1Framework for Maintaining Common National Instruments Terminal/Signal names 2 3The contents of this directory are primarily for maintaining and formatting all 4known valid signal routes for various National Instruments devices. 5 6Some 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 40The content of this directory is part of an effort to greatly simplify the use 41of signal routing capabilities of National Instruments data-acquisition and 42control hardware. In order to facilitate the transfer of register-level 43information _and_ the knowledge of valid routes per device, a few specific 44choices were made: 45 46 471) 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 592) 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 1043) 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 1124) 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 155In summary, similar confusion about signal routing configuration, albeit less, 156plagued NI's previous version of their own proprietary drivers. Earlier than 1572003, NI greatly simplified the situation for users by releasing a new API that 158abstracted the names of signals/terminals to a common and intuitive set of 159names. In addition, this new API provided a much more common interface to use 160for most of NI hardware. 161 162Comedi already provides such a common interface for data-acquisition and control 163hardware. This effort complements comedi's abstraction layers by further 164abstracting much more of the use cases for NI hardware, but allowing users _and_ 165developers to directly refer to NI documentation (user-level, register-level, 166and the register-level examples of the NI-MHDDK). 167 168 169 170-------------------------------------------------------------------------------- 171Various naming conventions and relations: 172-------------------------------------------------------------------------------- 173These are various notes that help to relate the naming conventions used in the 174NI-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) 241