[PATCH v4 00/13] device-global identifiers and routes introduced

[Ian Abbott]

On 03/10/18 21:55, Spencer E. Olson wrote:
> This patch set is the second revision of a recent patch set of the same name.
> Changes and notes:
>    - [PATCH v4 07/13]: Rebased patchset on repaired patch "staging: comedi:
>      ni_mio_common: protect register write overflow" (that patch had a missing
>      brace and this patch depends on that earlier patch).
> 
>    - [PATCH v3 04/13]: Minor update in indentation for support tool.
>    - [PATCH v3 05/13]: Simplify and clean up prototypes of functions for use with
>      besearch.
> 
>    - [PATCH v2 02/13]: Update signal/terminal names found after adding additional
>      devices to routing list in [PATCH v2 04/13].
>    - [PATCH v2 04/13]: Add routing information for PXIe-6535 and PXIe-6738
>      devices.
>    - [PATCH v2 04/13]: Implements Ian's suggestion to break up components of new
>      ni_routing module into multiple compile units so that .c files are not
>      included from .c files.
>    - [PATCH v2 04/13]: Fixes various function prototypes and "const" variable
>      declarations as per Ian's suggestions.
>    - [PATCH v2 05/13]: Tweak Makefile to build routing info for newly added
>      hardware in updates to [PATCH v2 04/13].
>    - [PATCH v2 05/13]: Fixes placement of "select COMEDI_NI_ROUTING" to ensure
>      ni_routing module is enabled for all dependent modules.
>    - [PATCH v2 05/13]: Removes a few inline function declarations in unit test.
>    - [PATCH v2 07/13]: This patch must be built upon an earlier patch recently
>      submitted and in the queue for integration:
>      "staging: comedi: ni_mio_common: protect register write overflow"
> 
> --
> 
> This patchset introduces a new framework for providing and maintaining a
> consistent namespace to define terminal/signal names for a set of comedi
> devices.  This effort was primarily focused on supporting NI hardware, but the
> interfaces introduced here can be implemented by all other hardware drivers, if
> desired.  Otherwise, these new interfaces do not effect any interfaces
> previously defined or prior use cases (i.e. backwards compatibility).
> 
> 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 end 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.  Some information is found in the register level
>      programming libraries provided by National Instruments (NI-MHDDK), but
>      many items are only vaguely found/mentioned in the comments of the NI-MHDDK
>      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 is not documented
>      and does not seem to be obtainable in any programmatic fashion, neither
>      through the proprietary NIDAQmx(-base) c-libraries, nor with register level
>      programming.  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.
> 
> Similar confusion, 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).
> 
> The goal of these patches are:
>    0) Allow current code to function as is, providing backwards compatibility to
>      the current interface, following a suggestion by Eric Piel.
>    1) Provide an interface to connect routes or identify signal sources and
>      destinations using a consistent naming scheme, global to a driver family.
>    2) For NI devices, use terminal/signal naming that is 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.
>    3) Make for easy maintenance of register level values that are to be used for
>      any particular NI device of any particular NI device family.
>    4) Provide a means whereby the user can query the set of signal routes that is
>      valid for a particular device.
>    5) Provide an interface whereby the user can query the status and capability
>      of any signal route.  The driver can provide information on whether the
>      route is valid for the device and whether the route is already connected.
> 
> This patch set implements various changes that keep the goals set forth here.
> This patch set is in nowise complete with respect to the various NI hardware
> options supported by comedi, though a large selection should be supported--all
> e/m-series (ni_mio_common.c hardware) boards and 660x boards are the target of
> this patch set, including the tio devices (counter/timers) used by these boards.
> 
> Spencer E. Olson (13):
>    staging: comedi: tests: add unittest framework for comedi
>    staging: comedi: add abstracted NI signal/terminal named constants
>    staging: comedi: add new device-global config interface
>    staging: comedi: ni_routing: Add NI signal routing info
>    staging: comedi: add interface to ni routing table information
>    staging: comedi: ni_mio_common: implement new routing for TRIG_EXT
>    staging: comedi: ni_mio_common: implement global pfi,rtsi routing
>    staging: comedi: ni_mio_common: implement output selection of
>      GPFO_{0,1}
>    staging: comedi: tio: implement global tio/ctr routing
>    staging: comedi: ni_mio_common: create device-global access to tio
>    staging: comedi: ni_660x: Add NI PCI-6608 to list of supported devices
>    staging: comedi: ni_660x: clean up pfi routing
>    staging: comedi: ni_660x: add device-global routing

Thanks for the new functionality.

Reviewed-by: Ian Abbott <abbotti at mev.co.uk>

-- 
-=( Ian Abbott <abbotti at mev.co.uk> || Web: www.mev.co.uk )=-
-=( MEV Ltd. is a company registered in England & Wales. )=-
-=( Registered number: 02862268.  Registered address:    )=-
-=( 15 West Park Road, Bramhall, STOCKPORT, SK7 3JZ, UK. )=-