On Thu, 2016-11-10 at 16:29 +0000, Ian Abbott wrote:
> 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@xxxxxxxxx>
> > ---
> > 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.
>
So, out of curiosity, will this mean that the userland comedilib library
might in the future be able to directly reference the kernel version of
comedi.h instead of us needing the keep these in sync manually?
_______________________________________________
devel mailing list
devel@xxxxxxxxxxxxxxxxxxxxxx
http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel
