[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