| 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) |
