/**
 * @file
 * Analogy for Linux, channel, range related features
 *
 * Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
 * Copyright (C) 2008 Alexis Berlemont <alexis.berlemont@free.fr>
 *
 * Xenomai is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * Xenomai is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Xenomai; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */
#ifndef _COBALT_RTDM_ANALOGY_CHANNEL_RANGE_H
#define _COBALT_RTDM_ANALOGY_CHANNEL_RANGE_H

#include <rtdm/uapi/analogy.h>

/**
 * @ingroup analogy_driver_facilities
 * @defgroup analogy_channel_range Channels and ranges
 *
 * 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 (struct a4l_channel) is used to
 * define one channel.
 *
 * Another structure named a4l_channels_desc (struct a4l_channels_desc)
 * 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:
 * <tt> @verbatim
struct a4l_channels_desc 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
	},
};
@endverbatim </tt>
 *
 * 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 struct a4l_rngtab. Here is an
 * example:
 * <tt> @verbatim
struct a4l_rngtab example_tab = {
    length: 2,
    rngs: {
	RANGE_V(-5,5),
	RANGE_V(-10,10),
    },
};
@endverbatim </tt>
 *
 * For each subdevice, a specific structure is designed to gather all
 * the ranges tabs of all the channels. In this structure, called
 * struct a4l_rngdesc, 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:
 * <tt> @verbatim
struct a4l_rngdesc example_rng = RNG_GLOBAL(example_tab);
@endverbatim </tt>
 *
 * @{
 */


/* --- Channel section --- */

/*!
 * @anchor A4L_CHAN_AREF_xxx @name Channel reference
 * @brief Flags to define the channel's reference
 * @{
 */

/**
 * Ground reference
 */
#define A4L_CHAN_AREF_GROUND 0x1
/**
 * Common reference
 */
#define A4L_CHAN_AREF_COMMON 0x2
/**
 * Differential reference
 */
#define A4L_CHAN_AREF_DIFF 0x4
/**
 * Misc reference
 */
#define A4L_CHAN_AREF_OTHER 0x8

	  /*! @} A4L_CHAN_AREF_xxx */

/**
 * Internal use flag (must not be used by driver developer)
 */
#define A4L_CHAN_GLOBAL 0x10

/*!
 * @brief Structure describing some channel's characteristics
 */

struct a4l_channel {
	unsigned long flags; /*!< Channel flags to define the reference. */
	unsigned long nb_bits; /*!< Channel resolution. */
};

/*!
 * @anchor A4L_CHAN_xxx @name Channels declaration mode
 * @brief Constant to define whether the channels in a descriptor are
 * identical
 * @{
 */

/**
 * Global declaration, the set contains channels with similar
 * characteristics
 */
#define A4L_CHAN_GLOBAL_CHANDESC 0
/**
 * Per channel declaration, the decriptor gathers differents channels
 */
#define A4L_CHAN_PERCHAN_CHANDESC 1

	  /*! @} A4L_CHAN_xxx */

/*!
 * @brief Structure describing a channels set
 */

struct a4l_channels_desc {
	unsigned long mode; /*!< Declaration mode (global or per channel) */
	unsigned long length; /*!< Channels count */
	struct a4l_channel chans[]; /*!< Channels tab */
};

/**
 * Internal use flag (must not be used by driver developer)
 */
#define A4L_RNG_GLOBAL 0x8

/*!
 * @brief Structure describing a (unique) range
 */

struct a4l_range {
	long min; /*!< Minimal value */
	long max; /*!< Maximal falue */
	unsigned long flags; /*!< Range flags (unit, etc.) */
};

/**
 * Macro to declare a (unique) range with no unit defined
 */
#define RANGE(x,y) {(x * A4L_RNG_FACTOR), (y * A4L_RNG_FACTOR),	\
			A4L_RNG_NO_UNIT}
/**
 * Macro to declare a (unique) range in Volt
 */
#define RANGE_V(x,y) {(x * A4L_RNG_FACTOR),(y * A4L_RNG_FACTOR), \
			A4L_RNG_VOLT_UNIT}
/**
 * Macro to declare a (unique) range in milliAmpere
 */
#define RANGE_mA(x,y) {(x * A4L_RNG_FACTOR),(y * A4L_RNG_FACTOR), \
			A4L_RNG_MAMP_UNIT}
/**
 * Macro to declare a (unique) range in some external reference
 */
#define RANGE_ext(x,y) {(x * A4L_RNG_FACTOR),(y * A4L_RNG_FACTOR), \
			A4L_RNG_EXT_UNIT}


/* Ranges tab descriptor */
struct a4l_rngtab {
	unsigned char length;
	struct a4l_range rngs[];
};

/**
 * Constant to define a ranges descriptor as global (inter-channel)
 */
#define A4L_RNG_GLOBAL_RNGDESC 0
/**
 * Constant to define a ranges descriptor as specific for a channel
 */
#define A4L_RNG_PERCHAN_RNGDESC 1

/* Global ranges descriptor */
struct a4l_rngdesc {
	unsigned char mode;
	unsigned char length;
	struct a4l_rngtab *rngtabs[];
};

/**
 * Macro to declare a ranges global descriptor in one line
 */
#define RNG_GLOBAL(x) {			\
	.mode = A4L_RNG_GLOBAL_RNGDESC,	\
	.length =  1,			\
	.rngtabs = {&(x)},		\
}

extern struct a4l_rngdesc a4l_range_bipolar10;
extern struct a4l_rngdesc a4l_range_bipolar5;
extern struct a4l_rngdesc a4l_range_unipolar10;
extern struct a4l_rngdesc a4l_range_unipolar5;
extern struct a4l_rngdesc a4l_range_unknown;
extern struct a4l_rngdesc a4l_range_fake;

#define range_digital a4l_range_unipolar5

/*! @} channelrange */

#endif /* !_COBALT_RTDM_ANALOGY_CHANNEL_RANGE_H */