Channels and ranges

Collaboration diagram for Channels and ranges:

Data Structures
struct	a4l_channel
	Structure describing some channel's characteristics. More...
struct	a4l_channels_desc
	Structure describing a channels set. More...
struct	a4l_range
	Structure describing a (unique) range. More...

Macros
#define	A4L_CHAN_GLOBAL   0x10
	Internal use flag (must not be used by driver developer)
#define	A4L_RNG_FACTOR   1000000
	Constant for internal use only (must not be used by driver developer). More...
#define	A4L_RNG_VOLT_UNIT   0x0
	Volt unit range flag.
#define	A4L_RNG_MAMP_UNIT   0x1
	MilliAmpere unit range flag.
#define	A4L_RNG_NO_UNIT   0x2
	No unit range flag.
#define	A4L_RNG_EXT_UNIT   0x4
	External unit range flag.
#define	A4L_RNG_UNIT(x)
	Macro to retrieve the range unit from the range flags.
#define	A4L_RNG_GLOBAL   0x8
	Internal use flag (must not be used by driver developer)
#define	RANGE(x, y)
	Macro to declare a (unique) range with no unit defined.
#define	RANGE_V(x, y)
	Macro to declare a (unique) range in Volt.
#define	RANGE_mA(x, y)
	Macro to declare a (unique) range in milliAmpere.
#define	RANGE_ext(x, y)
	Macro to declare a (unique) range in some external reference.
#define	A4L_RNG_GLOBAL_RNGDESC   0
	Constant to define a ranges descriptor as global (inter-channel)
#define	A4L_RNG_PERCHAN_RNGDESC   1
	Constant to define a ranges descriptor as specific for a channel.
#define	RNG_GLOBAL(x)
	Macro to declare a ranges global descriptor in one line.

Channel reference
Flags to define the channel's reference
#define	A4L_CHAN_AREF_GROUND   0x1
	Ground reference.
#define	A4L_CHAN_AREF_COMMON   0x2
	Common reference.
#define	A4L_CHAN_AREF_DIFF   0x4
	Differential reference.
#define	A4L_CHAN_AREF_OTHER   0x8
	Misc reference.

Channels declaration mode
Constant to define whether the channels in a descriptor are identical
#define	A4L_CHAN_GLOBAL_CHANDESC   0
	Global declaration, the set contains channels with similar characteristics.
#define	A4L_CHAN_PERCHAN_CHANDESC   1
	Per channel declaration, the decriptor gathers differents channels.

Detailed Description

Channels

According to the Analogy nomenclature, the channel is the elementary acquisition entity. One channel is supposed to acquire one data at a time. A channel can be:

• an analog input or an analog ouput;
• a digital input or a digital ouput;

Channels are defined by their type and by some other characteristics like:

• their resolutions for analog channels (which usually ranges from 8 to 32 bits);
• their references;

Such parameters must be declared for each channel composing a subdevice. The structure a4l_channel (a4l_chan_t) is used to define one channel.

Another structure named a4l_channels_desc (a4l_chdesc_t) gathers all channels for a specific subdevice. This latter structure also stores :

• the channels count;
• the channels declaration mode (A4L_CHAN_GLOBAL_CHANDESC or A4L_CHAN_PERCHAN_CHANDESC): if all the channels composing a subdevice are identical, there is no need to declare the parameters for each channel; the global declaration mode eases the structure composition.

Usually the channels descriptor looks like this:

a4l_chdesc_t example_chan = {
        mode: A4L_CHAN_GLOBAL_CHANDESC, -> Global declaration
                                              mode is set
        length: 8, -> 8 channels
        chans: {
                {A4L_CHAN_AREF_GROUND, 16}, -> Each channel is 16 bits
                                                  wide with the ground as
                                                  reference
        },
};

Ranges

So as to perform conversion from logical values acquired by the device to physical units, some range structure(s) must be declared on the driver side.

Such structures contain:

• the physical unit type (Volt, Ampere, none);
• the minimal and maximal values;

These range structures must be associated with the channels at subdevice registration time as a channel can work with many ranges. At configuration time (thanks to an Analogy command), one range will be selected for each enabled channel.

Consequently, for each channel, the developer must declare all the possible ranges in a structure called a4l_rngtab_t. Here is an example:

a4l_rngtab_t example_tab = {
    length: 2,
    rngs: {
        RANGE_V(-5,5),
        RANGE_V(-10,10),
    },
};

For each subdevice, a specific structure is designed to gather all the ranges tabs of all the channels. In this structure, called a4l_rngdesc_t, three fields must be filled:

• the declaration mode (A4L_RNG_GLOBAL_RNGDESC or A4L_RNG_PERCHAN_RNGDESC);
• the number of ranges tab;
• the tab of ranges tabs pointers;

Most of the time, the channels which belong to the same subdevice use the same set of ranges. So, there is no need to declare the same ranges for each channel. A macro is defined to prevent redundant declarations: RNG_GLOBAL().

Here is an example:

a4l_rngdesc_t example_rng = RNG_GLOBAL(example_tab);

Macro Definition Documentation

#define A4L_RNG_FACTOR   1000000

Constant for internal use only (must not be used by driver developer).

Referenced by a4l_dtoraw(), a4l_find_range(), a4l_ftoraw(), a4l_rawtod(), and a4l_rawtof().