staging: comedi: ni_routing: Add NI signal routing info

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)

// SPDX-License-Identifier: GPL-2.0+

/* vim: set ts=8 sw=8 noet tw=80 nowrap: */

/*

 *  comedi/drivers/ni_routing/ni_device_routes.c

 *  List of valid routes for specific NI boards.

 *

 *  COMEDI - Linux Control and Measurement Device Interface

 *  Copyright (C) 2016 Spencer E. Olson <olsonse@umich.edu>

 *

 *  This program is free software; you can redistribute it and/or modify

 *  it under the terms of the GNU General Public License as published by

 *  the Free Software Foundation; either version 2 of the License, or

 *  (at your option) any later version.

 *

 *  This program is distributed in the hope that it will be useful,

 *  but WITHOUT ANY WARRANTY; without even the implied warranty of

 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 *  GNU General Public License for more details.

 */

/*

 * The contents of this file are generated using the tools in

 * comedi/drivers/ni_routing/tools

 *

 * Please use those tools to help maintain the contents of this file.

 */

#include "ni_device_routes.h"

#include "ni_device_routes/all.h"

struct ni_device_routes *const ni_device_routes_list[] = {

	&ni_pxi_6030e_device_routes,

	&ni_pci_6070e_device_routes,

	&ni_pci_6220_device_routes,

	&ni_pci_6221_device_routes,

	&ni_pxi_6224_device_routes,

	&ni_pxi_6225_device_routes,

	&ni_pci_6229_device_routes,

	&ni_pci_6251_device_routes,

	&ni_pxi_6251_device_routes,

	&ni_pxie_6251_device_routes,

	&ni_pci_6254_device_routes,

	&ni_pci_6259_device_routes,

	&ni_pci_6534_device_routes,

	&ni_pci_6602_device_routes,

	&ni_pci_6713_device_routes,

	&ni_pci_6723_device_routes,

	&ni_pci_6733_device_routes,

	&ni_pxi_6733_device_routes,

	NULL,

};

/* SPDX-License-Identifier: GPL-2.0+ */

/* vim: set ts=8 sw=8 noet tw=80 nowrap: */

/*

 *  comedi/drivers/ni_routing/ni_device_routes.c

 *  List of valid routes for specific NI boards.

 *

 *  COMEDI - Linux Control and Measurement Device Interface

 *  Copyright (C) 2016 Spencer E. Olson <olsonse@umich.edu>

 *

 *  This program is free software; you can redistribute it and/or modify

 *  it under the terms of the GNU General Public License as published by

 *  the Free Software Foundation; either version 2 of the License, or

 *  (at your option) any later version.

 *

 *  This program is distributed in the hope that it will be useful,

 *  but WITHOUT ANY WARRANTY; without even the implied warranty of

 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 *  GNU General Public License for more details.

 */

/*

 * This file is meant to be included by comedi/drivers/ni_routes.c

 */

#ifndef _COMEDI_DRIVERS_NI_ROUTINT_NI_DEVICE_ROUTES_H

#define _COMEDI_DRIVERS_NI_ROUTINT_NI_DEVICE_ROUTES_H

#include "../ni_routes.h"

extern struct ni_device_routes *const ni_device_routes_list[];

#endif /* _COMEDI_DRIVERS_NI_ROUTINT_NI_DEVICE_ROUTES_H */

/* SPDX-License-Identifier: GPL-2.0+ */

/* vim: set ts=8 sw=8 noet tw=80 nowrap: */

/*

 *  comedi/drivers/ni_routing/ni_device_routes/all.h

 *  List of valid routes for specific NI boards.

 *

 *  COMEDI - Linux Control and Measurement Device Interface

 *  Copyright (C) 2016 Spencer E. Olson <olsonse@umich.edu>

 *

 *  This program is free software; you can redistribute it and/or modify

 *  it under the terms of the GNU General Public License as published by

 *  the Free Software Foundation; either version 2 of the License, or

 *  (at your option) any later version.

 *

 *  This program is distributed in the hope that it will be useful,

 *  but WITHOUT ANY WARRANTY; without even the implied warranty of

 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 *  GNU General Public License for more details.

 */

/*

 * The contents of this file are generated using the tools in

 * comedi/drivers/ni_routing/tools

 *

 * Please use those tools to help maintain the contents of this file.

 */

#ifndef _COMEDI_DRIVERS_NI_ROUTING_NI_DEVICE_ROUTES_EXTERN_H

#define _COMEDI_DRIVERS_NI_ROUTING_NI_DEVICE_ROUTES_EXTERN_H

#include "../ni_device_routes.h"

extern struct ni_device_routes ni_pxi_6030e_device_routes;

extern struct ni_device_routes ni_pci_6070e_device_routes;

extern struct ni_device_routes ni_pci_6220_device_routes;

extern struct ni_device_routes ni_pci_6221_device_routes;

extern struct ni_device_routes ni_pxi_6224_device_routes;

extern struct ni_device_routes ni_pxi_6225_device_routes;

extern struct ni_device_routes ni_pci_6229_device_routes;

extern struct ni_device_routes ni_pci_6251_device_routes;

extern struct ni_device_routes ni_pxi_6251_device_routes;

extern struct ni_device_routes ni_pxie_6251_device_routes;

extern struct ni_device_routes ni_pci_6254_device_routes;

extern struct ni_device_routes ni_pci_6259_device_routes;

extern struct ni_device_routes ni_pci_6534_device_routes;

extern struct ni_device_routes ni_pxie_6535_device_routes;

extern struct ni_device_routes ni_pci_6602_device_routes;

extern struct ni_device_routes ni_pci_6713_device_routes;

extern struct ni_device_routes ni_pci_6723_device_routes;

extern struct ni_device_routes ni_pci_6733_device_routes;

extern struct ni_device_routes ni_pxi_6733_device_routes;

extern struct ni_device_routes ni_pxie_6738_device_routes;

#endif //_COMEDI_DRIVERS_NI_ROUTING_NI_DEVICE_ROUTES_EXTERN_H