diff options
Diffstat (limited to 'drivers/staging/comedi/drivers/ni_routing/README')
| -rw-r--r-- | drivers/staging/comedi/drivers/ni_routing/README | 240 |
1 files changed, 0 insertions, 240 deletions
diff --git a/drivers/staging/comedi/drivers/ni_routing/README b/drivers/staging/comedi/drivers/ni_routing/README deleted file mode 100644 index b65c4ebedbc4..000000000000 --- a/drivers/staging/comedi/drivers/ni_routing/README +++ /dev/null @@ -1,240 +0,0 @@ -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) |