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
          I(<value>) : register value is implemented but needs testing
          U(<value>) : register value is not implemented

        The actual function of these macros will depend on whether the code is
        compiled in the kernel or whether it is compiled into the conversion
        tools.  For the conversion tools, it can be used to indicate the status
        of the register value.  For the kernel, V() and I() both perform the
        same function and prepare data to be used; U() zeroes out the value to
        ensure that it cannot be used.

        *** It would be a great help for users to test these values such that
        these files can be correctly marked/documented ***

  (b) ni_device_routes/[board-name].c

        This data represents the known set of valid signal routes that are
        possible for each specific board.  Although the family defines the
        register values to use for a particular signal MUX, not all possible
        signals are actually available on each board.

        In order for a particular board to take advantage of the effort to
        simplify/clarify signal routing on NI devices, a corresponding
        [board-name].c file must be created.  This file should reflect the known
        valid _direct_ routing capabilities of the board.

        As noted above, the only known consistent source of information for
        valid device routes comes from the proprietary National Instruments
        Windows software, NI-MAX.  Also, as noted above, this information can
        only be visually conveyed from NI-MAX to other media.  To make this
        easier, the naming conventions used in the [board-name].c file are
        similar to the naming conventions as presented by NI-MAX.


3) Two other files aggregate the above data to integrate it into comedi:
    ni_route_values.c
    ni_device_routes.c

  When adding a new [board-name].c file, be sure to also add in the line in
  ni_device_routes.c to include this information into comedi.


4) Several tools have been included to convert from/to the c file formats.
  These tools are best used/demonstrated via the included Makefile targets:
  (a) `make csv-files`
     Creates new csv-files using content of c-files of existing
     ni_routing/* content.  New csv files are placed in csv
     sub-directory.

     As noted above, the only consistent source of information of valid
     device routes comes from the proprietary National Instruments Windows
     software, NI-MAX.  Also, as noted above, this information can only be
     visually conveyed from NI-MAX to other media.  This make target creates
     spreadsheet representations of the routing data.  The choice of using a
     spreadsheet (ala CSV) to copy this information allows for easy direct
     visual comparison to the NI-MAX "Valid Routes" tables.

     Furthermore, the register-level information is much easier to identify and
     correct when entire families of NI devices are shown side by side in table
     format.  This is made easy by using a file-storage format that can be
     loaded into a spreadsheet application.

     Finally, .csv content is very easy to edit and read using a variety of
     tools, including spreadsheets or various other scripting languages.  In
     fact, the tools provided here enable quick conversion of the
     spreadsheet-like .csv format to c-files that follow the kernel coding
     conventions.


  (b) `make c-files`
     Creates new c-files using content of csv sub-directory.  These
     new c-files can be compared to the active content in the
     ni_routing directory.
  (c) `make csv-blank`
     Create a new blank csv file.  This is useful for establishing a
     new data table for either a device family (less likely) or a
     specific board of an existing device family (more likely).
  (d) `make clean`
     Remove all generated files/directories.
  (e) `make everything`
     Build all csv-files, then all new c-files.


In summary, similar confusion about signal routing configuration, albeit less,
plagued NI's previous version of their own proprietary drivers.  Earlier than
2003, NI greatly simplified the situation for users by releasing a new API that
abstracted the names of signals/terminals to a common and intuitive set of
names.  In addition, this new API provided a much more common interface to use
for most of NI hardware.

Comedi already provides such a common interface for data-acquisition and control
hardware.  This effort complements comedi's abstraction layers by further
abstracting much more of the use cases for NI hardware, but allowing users _and_
developers to directly refer to NI documentation (user-level, register-level,
and the register-level examples of the NI-MHDDK).


--------------------------------------------------------------------------------
Various naming conventions and relations:
--------------------------------------------------------------------------------
These are various notes that help to relate the naming conventions used in the
NI-STC with those naming conventions used here.
--------------------------------------------------------------------------------

  Signal sources for most signals-destinations are given a specific naming
  convention, although the register values are not consistent.  This next table
  shows the mapping between the names used in comedi for NI and those names
  typically used within the NI-STC documentation.

  (comedi)                      (NI-STC input or output)    (NOTE)
  ------------------------------------------------------------------------------
  TRIGGER_LINE(i)               RTSI_Trig_i_Output_Select   i in range [0..7]
  NI_AI_STOP                    AI_STOP
  NI_AI_SampleClock             AI_START_Select
  NI_AI_SampleClockTimebase     AI_SI                       If internal sample
                                                            clock signal is used
  NI_AI_StartTrigger            AI_START1_Select
  NI_AI_ReferenceTrigger        AI_START2_Select            for pre-triggered
                                                            acquisition---not
                                                            currently supported
                                                            in comedi
  NI_AI_ConvertClock            AI_CONVERT_Source_Select
  NI_AI_ConvertClockTimebase    AI_SI2                      If internal convert
                                                            signal is used
  NI_AI_HoldCompleteEvent
  NI_AI_PauseTrigger            AI_External_Gate
  NI_AO_SampleClock             AO_UPDATE
  NI_AO_SampleClockTimebase     AO_UI
  NI_AO_StartTrigger            AO_START1
  NI_AO_PauseTrigger            AO_External_Gate
  NI_DI_SampleClock
  NI_DO_SampleClock
  NI_MasterTimebase
  NI_20MHzTimebase              TIMEBASE 1 && TIMEBASE 3 if no higher clock exists
  NI_80MHzTimebase              TIMEBASE 3
  NI_100kHzTimebase             TIMEBASE 2
  NI_10MHzRefClock
  PXI_Clk10
  NI_CtrOut(0)                  GPFO_0                      external ctr0out pin
  NI_CtrOut(1)                  GPFO_1                      external ctr1out pin
  NI_CtrSource(0)
  NI_CtrSource(1)
  NI_CtrGate(0)
  NI_CtrGate(1)
  NI_CtrInternalOutput(0)       G_OUT0, G0_TC               for Ctr1Source, Ctr1Gate
  NI_CtrInternalOutput(1)       G_OUT1, G1_TC               for Ctr0Source, Ctr0Gate
  NI_RGOUT0                     RGOUT0                      internal signal
  NI_FrequencyOutput
  #NI_FrequencyOutputTimebase
  NI_ChangeDetectionEvent
  NI_RTSI_BRD(0)
  NI_RTSI_BRD(1)
  NI_RTSI_BRD(2)
  NI_RTSI_BRD(3)
  #NI_SoftwareStrobe
  NI_LogicLow
  NI_CtrA(0)                    G0_A_Select                 see M-Series user
                                                            manual (371022K-01)
  NI_CtrA(1)                    G1_A_Select                 see M-Series user
                                                            manual (371022K-01)
  NI_CtrB(0)                    G0_B_Select, up/down        see M-Series user
                                                            manual (371022K-01)
  NI_CtrB(1)                    G1_B_Select, up/down        see M-Series user
                                                            manual (371022K-01)
  NI_CtrZ(0)                                                see M-Series user
                                                            manual (371022K-01)
  NI_CtrZ(1)                                                see M-Series user
                                                            manual (371022K-01)