[PATCH 02/15] staging: comedi: add abstracted NI signal/terminal named constants

Ian Abbott abbotti at mev.co.uk
Thu Nov 10 16:29:05 UTC 2016


On 12/10/16 12:05, Spencer E. Olson wrote:
> This change adds abstracted constants for National Instruments
> terminal/signal names.
>
> 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.
>
> 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.
>
> The names added here mirror the names chosen and well documented by NI.
> These names are exposed to the user via the comedilib user library.  By
> keeping the names in this format, in spite of the use of CamelScript,
> maintenance will be greatly eased and confusion for users _and_ comedi
> developers will be greatly reduced.
>
> Signed-off-by: Spencer E. Olson <olsonse at umich.edu>
> ---
>  drivers/staging/comedi/comedi.h | 128 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 128 insertions(+)
>
> diff --git a/drivers/staging/comedi/comedi.h b/drivers/staging/comedi/comedi.h
> index a1c1081..c80d0d6 100644
> --- a/drivers/staging/comedi/comedi.h
> +++ b/drivers/staging/comedi/comedi.h
> @@ -937,6 +937,134 @@ enum i8254_mode {
>  	I8254_BINARY = 0
>  };
>
> +/* *** BEGIN GLOBALLY-NAMED NI TERMINALS/SIGNALS *** */
> +
> +/* Common National Instruments Terminal/Signal names.

This just needs to start with a '/*' line.

> + * Some of these have no NI_ prefix as they are useful for non-NI hardware, such
> + * as those that utilize the PXI/RTSI trigger lines.
> + *
> + * NOTE ABOUT THE CHOICE OF NAMES HERE AND THE CAMELSCRIPT:
> + *   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!
> + *
> + *   More detail:
> + *   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.
> + *
> + *   Similar, albeit less, confusion plagued NI's previous version of their own
> + *   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.
> + *
> + *   The names below mirror the names chosen and well documented by NI.  These
> + *   names are exposed to the user via the comedilib user library.  By keeping
> + *   the names below, in spite of the use of CamelScript, maintenance will be
> + *   greatly eased and confusion for users _and_ comedi developers will be
> + *   greatly reduced.
> + */
> +/**

A comment opening with two asterisks should only be used for kerneldoc 
comments.

> + * Base of abstracted NI names.
> + * The first 16 bits of *_arg are reserved for channel selection.
> + * Since we only actually need the first 4 or 5 bits for all register values on
> + * NI select registers anyways, we'll identify all values >= (1<<15) as being an
> + * abstracted NI signal/terminal name.
> + * These values are also used/returned by INSN_DEVICE_CONFIG_TEST_ROUTE,
> + * INSN_DEVICE_CONFIG_CONNECT_ROUTE, INSN_DEVICE_CONFIG_DISCONNECT_ROUTE,
> + * and INSN_DEVICE_CONFIG_GET_ROUTES.
> + */
> +#define NI_NAMES_BASE	BIT(15)

comedi.h is intended to be moved to uapi/linux/comedi.h, and the BIT(n) 
macro cannot be used there.  On the other hand, writing `(1U << 15)` 
encourages people to submit patches to change it back to `BIT(15)`. So a 
`0x8000u` works well here.

-- 
-=( Ian Abbott @ MEV Ltd.    E-mail: <abbotti at mev.co.uk> )=-
-=(                          Web: http://www.mev.co.uk/  )=-


More information about the devel mailing list