drivers/comedi/drivers/ni_routing/README

Source file repositories/reference/linux-study-clean/drivers/comedi/drivers/ni_routing/README

File Facts

System
Linux kernel
Corpus path
drivers/comedi/drivers/ni_routing/README
Extension
[no extension]
Size
12365 bytes
Lines
241
Domain
Driver Families
Bucket
drivers/comedi
Inferred role
Driver Families: drivers/comedi
Status
atlas-only

Why This File Exists

Repeatable hardware-adapter layer. Deep compatibility for every driver is out of scope; this atlas records patterns, probe lifecycles, bus glue, IRQ/DMA usage, and links back to core abstractions.

Dependency Surface

Detected Declarations

Annotated Snippet

Framework for Maintaining Common National Instruments Terminal/Signal names

The contents of this directory are primarily for maintaining and formatting all
known valid signal routes for various National Instruments devices.

Some background:
  There have been significant confusions over the past many years for users
  when trying to understand how to connect to/from signals and terminals on
  NI hardware using comedi.  The major reason for this is that the actual
  register values were exposed and required to be used by users.  Several
  major reasons exist why this caused major confusion for users:

  1) The register values are _NOT_ in user documentation, but rather in
    arcane locations, such as a few register programming manuals that are
    increasingly hard to find and the NI-MHDDK (comments in in example code).
    There is no one place to find the various valid values of the registers.

  2) The register values are _NOT_ completely consistent.  There is no way to
    gain any sense of intuition of which values, or even enums one should use
    for various registers.  There was some attempt in prior use of comedi to
    name enums such that a user might know which enums should be used for
    varying purposes, but the end-user had to gain a knowledge of register
    values to correctly wield this approach.

  3) The names for signals and registers found in the various register level
    programming manuals and vendor-provided documentation are _not_ even
    close to the same names that are in the end-user documentation.

  4) The sets of routes that are valid are not consistent from device to device.
    One additional major challenge is that this information does not seem to be
    obtainable in any programmatic fashion, neither through the proprietary
    NIDAQmx(-base) c-libraries, nor with register level programming, _nor_
    through any documentation.  In fact, the only consistent source of this
    information is through the proprietary NI-MAX software, which currently only
    runs on Windows platforms.  A further challenge is that this information
    cannot be exported from NI-MAX, except by screenshot.



The content of this directory is part of an effort to greatly simplify the use
of signal routing capabilities of National Instruments data-acquisition and
control hardware.  In order to facilitate the transfer of register-level
information _and_ the knowledge of valid routes per device, a few specific
choices were made:


1) The names of the National Instruments signals/terminals that are used in this
  directory are chosen to be consistent with (a) the NI's user level
  documentation, (b) NI's user-level code, (c) the information as provided by
  the proprietary NI-MAX software, and (d) the user interface code provided by
  the user-land comedilib library.

  The impact of this choice implies that one allows the use of CamelScript names
  in the kernel.  In short, the choice to use CamelScript and the exact names
  below is for maintainability, clarity, similarity to manufacturer's
  documentation, _and_ a mitigation for confusion that has plagued the use of
  these drivers for years!

2) The bulk of the real content for this directory is stored in two separate
  collections (i.e. sub-directories) of tables stored in c source files:

  (a) ni_route_values/ni_[series-label]series.c

        This data represents all the various register values to use for the
        multiple different signal MUXes for the specific device families.

        The values are all wrapped in one of three macros to help document and
        track which values have been implemented and tested.
        These macros are:
          V(<value>) : register value is valid, tested, and implemented

Annotation

Implementation Notes