drivers/comedi/drivers/ni_routing/README

   1 Framework for Maintaining Common National Instruments Terminal/Signal names
   2
   3 The contents of this directory are primarily for maintaining and formatting all
   4 known valid signal routes for various National Instruments devices.
   5
   6 Some background:
   7   There have been significant confusions over the past many years for users
   8   when trying to understand how to connect to/from signals and terminals on
   9   NI hardware using comedi.  The major reason for this is that the actual
  10   register values were exposed and required to be used by users.  Several
  11   major reasons exist why this caused major confusion for users:
  12
  13   1) The register values are _NOT_ in user documentation, but rather in
  14     arcane locations, such as a few register programming manuals that are
  15     increasingly hard to find and the NI-MHDDK (comments in in example code).
  16     There is no one place to find the various valid values of the registers.
  17
  18   2) The register values are _NOT_ completely consistent.  There is no way to
  19     gain any sense of intuition of which values, or even enums one should use
  20     for various registers.  There was some attempt in prior use of comedi to
  21     name enums such that a user might know which enums should be used for
  22     varying purposes, but the end-user had to gain a knowledge of register
  23     values to correctly wield this approach.
  24
  25   3) The names for signals and registers found in the various register level
  26     programming manuals and vendor-provided documentation are _not_ even
  27     close to the same names that are in the end-user documentation.
  28
  29   4) The sets of routes that are valid are not consistent from device to device.
  30     One additional major challenge is that this information does not seem to be
  31     obtainable in any programmatic fashion, neither through the proprietary
  32     NIDAQmx(-base) c-libraries, nor with register level programming, _nor_
  33     through any documentation.  In fact, the only consistent source of this
  34     information is through the proprietary NI-MAX software, which currently only
  35     runs on Windows platforms.  A further challenge is that this information
  36     cannot be exported from NI-MAX, except by screenshot.
  37
  38
  39
  40 The content of this directory is part of an effort to greatly simplify the use
  41 of signal routing capabilities of National Instruments data-acquisition and
  42 control hardware.  In order to facilitate the transfer of register-level
  43 information _and_ the knowledge of valid routes per device, a few specific
  44 choices were made:
  45
  46
  47 1) The names of the National Instruments signals/terminals that are used in this
  48   directory are chosen to be consistent with (a) the NI's user level
  49   documentation, (b) NI's user-level code, (c) the information as provided by
  50   the proprietary NI-MAX software, and (d) the user interface code provided by
  51   the user-land comedilib library.
  52
  53   The impact of this choice implies that one allows the use of CamelScript names
  54   in the kernel.  In short, the choice to use CamelScript and the exact names
  55   below is for maintainability, clarity, similarity to manufacturer's
  56   documentation, _and_ a mitigation for confusion that has plagued the use of
  57   these drivers for years!
  58
  59 2) The bulk of the real content for this directory is stored in two separate
  60   collections (i.e. sub-directories) of tables stored in c source files:
  61
  62   (a) ni_route_values/ni_[series-label]series.c
  63
  64         This data represents all the various register values to use for the
  65         multiple different signal MUXes for the specific device families.
  66
  67         The values are all wrapped in one of three macros to help document and
  68         track which values have been implemented and tested.
  69         These macros are:
  70           V(<value>) : register value is valid, tested, and implemented
  71           I(<value>) : register value is implemented but needs testing
  72           U(<value>) : register value is not implemented
  73
  74         The actual function of these macros will depend on whether the code is
  75         compiled in the kernel or whether it is compiled into the conversion
  76         tools.  For the conversion tools, it can be used to indicate the status
  77         of the register value.  For the kernel, V() and I() both perform the
  78         same function and prepare data to be used; U() zeroes out the value to
  79         ensure that it cannot be used.
  80
  81         *** It would be a great help for users to test these values such that
  82         these files can be correctly marked/documented ***
  83
  84   (b) ni_device_routes/[board-name].c
  85
  86         This data represents the known set of valid signal routes that are
  87         possible for each specific board.  Although the family defines the
  88         register values to use for a particular signal MUX, not all possible
  89         signals are actually available on each board.
  90
  91         In order for a particular board to take advantage of the effort to
  92         simplify/clarify signal routing on NI devices, a corresponding
  93         [board-name].c file must be created.  This file should reflect the known
  94         valid _direct_ routing capabilities of the board.
  95
  96         As noted above, the only known consistent source of information for
  97         valid device routes comes from the proprietary National Instruments
  98         Windows software, NI-MAX.  Also, as noted above, this information can
  99         only be visually conveyed from NI-MAX to other media.  To make this
 100         easier, the naming conventions used in the [board-name].c file are
 101         similar to the naming conventions as presented by NI-MAX.
 102
 103
 104 3) Two other files aggregate the above data to integrate it into comedi:
 105     ni_route_values.c
 106     ni_device_routes.c
 107
 108   When adding a new [board-name].c file, be sure to also add in the line in
 109   ni_device_routes.c to include this information into comedi.
 110
 111
 112 4) Several tools have been included to convert from/to the c file formats.
 113   These tools are best used/demonstrated via the included Makefile targets:
 114   (a) `make csv-files`
 115      Creates new csv-files using content of c-files of existing
 116      ni_routing/* content.  New csv files are placed in csv
 117      sub-directory.
 118
 119      As noted above, the only consistent source of information of valid
 120      device routes comes from the proprietary National Instruments Windows
 121      software, NI-MAX.  Also, as noted above, this information can only be
 122      visually conveyed from NI-MAX to other media.  This make target creates
 123      spreadsheet representations of the routing data.  The choice of using a
 124      spreadsheet (ala CSV) to copy this information allows for easy direct
 125      visual comparison to the NI-MAX "Valid Routes" tables.
 126
 127      Furthermore, the register-level information is much easier to identify and
 128      correct when entire families of NI devices are shown side by side in table
 129      format.  This is made easy by using a file-storage format that can be
 130      loaded into a spreadsheet application.
 131
 132      Finally, .csv content is very easy to edit and read using a variety of
 133      tools, including spreadsheets or various other scripting languages.  In
 134      fact, the tools provided here enable quick conversion of the
 135      spreadsheet-like .csv format to c-files that follow the kernel coding
 136      conventions.
 137
 138
 139   (b) `make c-files`
 140      Creates new c-files using content of csv sub-directory.  These
 141      new c-files can be compared to the active content in the
 142      ni_routing directory.
 143   (c) `make csv-blank`
 144      Create a new blank csv file.  This is useful for establishing a
 145      new data table for either a device family (less likely) or a
 146      specific board of an existing device family (more likely).
 147   (d) `make clean`
 148      Remove all generated files/directories.
 149   (e) `make everything`
 150      Build all csv-files, then all new c-files.
 151
 152
 153
 154
 155 In summary, similar confusion about signal routing configuration, albeit less,
 156 plagued NI's previous version of their own proprietary drivers.  Earlier than
 157 2003, NI greatly simplified the situation for users by releasing a new API that
 158 abstracted the names of signals/terminals to a common and intuitive set of
 159 names.  In addition, this new API provided a much more common interface to use
 160 for most of NI hardware.
 161
 162 Comedi already provides such a common interface for data-acquisition and control
 163 hardware.  This effort complements comedi's abstraction layers by further
 164 abstracting much more of the use cases for NI hardware, but allowing users _and_
 165 developers to directly refer to NI documentation (user-level, register-level,
 166 and the register-level examples of the NI-MHDDK).
 167
 168
 169
 170 --------------------------------------------------------------------------------
 171 Various naming conventions and relations:
 172 --------------------------------------------------------------------------------
 173 These are various notes that help to relate the naming conventions used in the
 174 NI-STC with those naming conventions used here.
 175 --------------------------------------------------------------------------------
 176
 177   Signal sources for most signals-destinations are given a specific naming
 178   convention, although the register values are not consistent.  This next table
 179   shows the mapping between the names used in comedi for NI and those names
 180   typically used within the NI-STC documentation.
 181
 182   (comedi)                      (NI-STC input or output)    (NOTE)
 183   ------------------------------------------------------------------------------
 184   TRIGGER_LINE(i)               RTSI_Trig_i_Output_Select   i in range [0..7]
 185   NI_AI_STOP                    AI_STOP
 186   NI_AI_SampleClock             AI_START_Select
 187   NI_AI_SampleClockTimebase     AI_SI                       If internal sample
 188                                                             clock signal is used
 189   NI_AI_StartTrigger            AI_START1_Select
 190   NI_AI_ReferenceTrigger        AI_START2_Select            for pre-triggered
 191                                                             acquisition---not
 192                                                             currently supported
 193                                                             in comedi
 194   NI_AI_ConvertClock            AI_CONVERT_Source_Select
 195   NI_AI_ConvertClockTimebase    AI_SI2                      If internal convert
 196                                                             signal is used
 197   NI_AI_HoldCompleteEvent
 198   NI_AI_PauseTrigger            AI_External_Gate
 199   NI_AO_SampleClock             AO_UPDATE
 200   NI_AO_SampleClockTimebase     AO_UI
 201   NI_AO_StartTrigger            AO_START1
 202   NI_AO_PauseTrigger            AO_External_Gate
 203   NI_DI_SampleClock
 204   NI_DO_SampleClock
 205   NI_MasterTimebase
 206   NI_20MHzTimebase              TIMEBASE 1 && TIMEBASE 3 if no higher clock exists
 207   NI_80MHzTimebase              TIMEBASE 3
 208   NI_100kHzTimebase             TIMEBASE 2
 209   NI_10MHzRefClock
 210   PXI_Clk10
 211   NI_CtrOut(0)                  GPFO_0                      external ctr0out pin
 212   NI_CtrOut(1)                  GPFO_1                      external ctr1out pin
 213   NI_CtrSource(0)
 214   NI_CtrSource(1)
 215   NI_CtrGate(0)
 216   NI_CtrGate(1)
 217   NI_CtrInternalOutput(0)       G_OUT0, G0_TC               for Ctr1Source, Ctr1Gate
 218   NI_CtrInternalOutput(1)       G_OUT1, G1_TC               for Ctr0Source, Ctr0Gate
 219   NI_RGOUT0                     RGOUT0                      internal signal
 220   NI_FrequencyOutput
 221   #NI_FrequencyOutputTimebase
 222   NI_ChangeDetectionEvent
 223   NI_RTSI_BRD(0)
 224   NI_RTSI_BRD(1)
 225   NI_RTSI_BRD(2)
 226   NI_RTSI_BRD(3)
 227   #NI_SoftwareStrobe
 228   NI_LogicLow
 229   NI_CtrA(0)                    G0_A_Select                 see M-Series user
 230                                                             manual (371022K-01)
 231   NI_CtrA(1)                    G1_A_Select                 see M-Series user
 232                                                             manual (371022K-01)
 233   NI_CtrB(0)                    G0_B_Select, up/down        see M-Series user
 234                                                             manual (371022K-01)
 235   NI_CtrB(1)                    G1_B_Select, up/down        see M-Series user
 236                                                             manual (371022K-01)
 237   NI_CtrZ(0)                                                see M-Series user
 238                                                             manual (371022K-01)
 239   NI_CtrZ(1)                                                see M-Series user
 240                                                             manual (371022K-01)