mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-24 05:04:00 +08:00
staging: comedi: comedi.h: add kernel-doc comments to struct types
Add "kernel-doc"-formatted comments to the COMEDI `struct` declarations used with ioctls. Don't bother documenting `struct comedi_trig` as it is obsolete and not supported. Signed-off-by: Ian Abbott <abbotti@mev.co.uk> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Ian Abbott
Greg Kroah-Hartman
parent
8fb02b2947
commit
ace7aa7f64
@ -491,6 +491,19 @@ struct comedi_trig {
|
||||
unsigned int unused[3];
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_insn - COMEDI instruction
|
||||
* @insn: COMEDI instruction type (%INSN_xxx).
|
||||
* @n: Length of @data[].
|
||||
* @data: Pointer to data array operated on by the instruction.
|
||||
* @subdev: Subdevice index.
|
||||
* @chanspec: A packed "chanspec" value consisting of channel number,
|
||||
* analog range index, analog reference type, and flags.
|
||||
* @unused: Reserved for future use.
|
||||
*
|
||||
* This is used with the %COMEDI_INSN ioctl, and indirectly with the
|
||||
* %COMEDI_INSNLIST ioctl.
|
||||
*/
|
||||
struct comedi_insn {
|
||||
unsigned int insn;
|
||||
unsigned int n;
|
||||
@ -500,11 +513,95 @@ struct comedi_insn {
|
||||
unsigned int unused[3];
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_insnlist - list of COMEDI instructions
|
||||
* @n_insns: Number of COMEDI instructions.
|
||||
* @insns: Pointer to array COMEDI instructions.
|
||||
*
|
||||
* This is used with the %COMEDI_INSNLIST ioctl.
|
||||
*/
|
||||
struct comedi_insnlist {
|
||||
unsigned int n_insns;
|
||||
struct comedi_insn __user *insns;
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_cmd - COMEDI asynchronous acquisition command details
|
||||
* @subdev: Subdevice index.
|
||||
* @flags: Command flags (%CMDF_xxx).
|
||||
* @start_src: "Start acquisition" trigger source (%TRIG_xxx).
|
||||
* @start_arg: "Start acquisition" trigger argument.
|
||||
* @scan_begin_src: "Scan begin" trigger source.
|
||||
* @scan_begin_arg: "Scan begin" trigger argument.
|
||||
* @convert_src: "Convert" trigger source.
|
||||
* @convert_arg: "Convert" trigger argument.
|
||||
* @scan_end_src: "Scan end" trigger source.
|
||||
* @scan_end_arg: "Scan end" trigger argument.
|
||||
* @stop_src: "Stop acquisition" trigger source.
|
||||
* @stop_arg: "Stop acquisition" trigger argument.
|
||||
* @chanlist: Pointer to array of "chanspec" values, containing a
|
||||
* sequence of channel numbers packed with analog range
|
||||
* index, etc.
|
||||
* @chanlist_len: Number of channels in sequence.
|
||||
* @data: Pointer to miscellaneous set-up data (not used).
|
||||
* @data_len: Length of miscellaneous set-up data.
|
||||
*
|
||||
* This is used with the %COMEDI_CMD or %COMEDI_CMDTEST ioctl to set-up
|
||||
* or validate an asynchronous acquisition command. The ioctl may modify
|
||||
* the &struct comedi_cmd and copy it back to the caller.
|
||||
*
|
||||
* Optional command @flags values that can be ORed together...
|
||||
*
|
||||
* %CMDF_BOGUS - makes %COMEDI_CMD ioctl return error %EAGAIN instead of
|
||||
* starting the command.
|
||||
*
|
||||
* %CMDF_PRIORITY - requests "hard real-time" processing (which is not
|
||||
* supported in this version of COMEDI).
|
||||
*
|
||||
* %CMDF_WAKE_EOS - requests the command makes data available for reading
|
||||
* after every "scan" period.
|
||||
*
|
||||
* %CMDF_WRITE - marks the command as being in the "write" (to device)
|
||||
* direction. This does not need to be specified by the caller unless the
|
||||
* subdevice supports commands in either direction.
|
||||
*
|
||||
* %CMDF_RAWDATA - prevents the command from "munging" the data between the
|
||||
* COMEDI sample format and the raw hardware sample format.
|
||||
*
|
||||
* %CMDF_ROUND_NEAREST - requests timing periods to be rounded to nearest
|
||||
* supported values.
|
||||
*
|
||||
* %CMDF_ROUND_DOWN - requests timing periods to be rounded down to supported
|
||||
* values (frequencies rounded up).
|
||||
*
|
||||
* %CMDF_ROUND_UP - requests timing periods to be rounded up to supported
|
||||
* values (frequencies rounded down).
|
||||
*
|
||||
* Trigger source values for @start_src, @scan_begin_src, @convert_src,
|
||||
* @scan_end_src, and @stop_src...
|
||||
*
|
||||
* %TRIG_ANY - "all ones" value used to test which trigger sources are
|
||||
* supported.
|
||||
*
|
||||
* %TRIG_INVALID - "all zeroes" value used to indicate that all requested
|
||||
* trigger sources are invalid.
|
||||
*
|
||||
* %TRIG_NONE - never trigger (often used as a @stop_src value).
|
||||
*
|
||||
* %TRIG_NOW - trigger after '_arg' nanoseconds.
|
||||
*
|
||||
* %TRIG_FOLLOW - trigger follows another event.
|
||||
*
|
||||
* %TRIG_TIMER - trigger every '_arg' nanoseconds.
|
||||
*
|
||||
* %TRIG_COUNT - trigger when count '_arg' is reached.
|
||||
*
|
||||
* %TRIG_EXT - trigger on external signal specified by '_arg'.
|
||||
*
|
||||
* %TRIG_INT - trigger on internal, software trigger specified by '_arg'.
|
||||
*
|
||||
* %TRIG_OTHER - trigger on other, driver-defined signal specified by '_arg'.
|
||||
*/
|
||||
struct comedi_cmd {
|
||||
unsigned int subdev;
|
||||
unsigned int flags;
|
||||
@ -524,13 +621,31 @@ struct comedi_cmd {
|
||||
unsigned int stop_src;
|
||||
unsigned int stop_arg;
|
||||
|
||||
unsigned int *chanlist; /* channel/range list */
|
||||
unsigned int *chanlist;
|
||||
unsigned int chanlist_len;
|
||||
|
||||
short __user *data; /* data list, size depends on subd flags */
|
||||
short __user *data;
|
||||
unsigned int data_len;
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_chaninfo - used to retrieve per-channel information
|
||||
* @subdev: Subdevice index.
|
||||
* @maxdata_list: Optional pointer to per-channel maximum data values.
|
||||
* @flaglist: Optional pointer to per-channel flags.
|
||||
* @rangelist: Optional pointer to per-channel range types.
|
||||
* @unused: Reserved for future use.
|
||||
*
|
||||
* This is used with the %COMEDI_CHANINFO ioctl to get per-channel information
|
||||
* for the subdevice. Use of this requires knowledge of the number of channels
|
||||
* and subdevice flags obtained using the %COMEDI_SUBDINFO ioctl.
|
||||
*
|
||||
* The @maxdata_list member must be %NULL unless the %SDF_MAXDATA subdevice
|
||||
* flag is set. The @flaglist member must be %NULL unless the %SDF_FLAGS
|
||||
* subdevice flag is set. The @rangelist member must be %NULL unless the
|
||||
* %SDF_RANGETYPE subdevice flag is set. Otherwise, the arrays they point to
|
||||
* must be at least as long as the number of channels.
|
||||
*/
|
||||
struct comedi_chaninfo {
|
||||
unsigned int subdev;
|
||||
unsigned int __user *maxdata_list;
|
||||
@ -539,17 +654,157 @@ struct comedi_chaninfo {
|
||||
unsigned int unused[4];
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_rangeinfo - used to retrieve the range table for a channel
|
||||
* @range_type: Encodes subdevice index (bits 27:24), channel index
|
||||
* (bits 23:16) and range table length (bits 15:0).
|
||||
* @range_ptr: Pointer to array of @struct comedi_krange to be filled
|
||||
* in with the range table for the channel or subdevice.
|
||||
*
|
||||
* This is used with the %COMEDI_RANGEINFO ioctl to retrieve the range table
|
||||
* for a specific channel (if the subdevice has the %SDF_RANGETYPE flag set to
|
||||
* indicate that the range table depends on the channel), or for the subdevice
|
||||
* as a whole (if the %SDF_RANGETYPE flag is clear, indicating the range table
|
||||
* is shared by all channels).
|
||||
*
|
||||
* The @range_type value is an input to the ioctl and comes from a previous
|
||||
* use of the %COMEDI_SUBDINFO ioctl (if the %SDF_RANGETYPE flag is clear),
|
||||
* or the %COMEDI_CHANINFO ioctl (if the %SDF_RANGETYPE flag is set).
|
||||
*/
|
||||
struct comedi_rangeinfo {
|
||||
unsigned int range_type;
|
||||
void __user *range_ptr;
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_krange - describes a range in a range table
|
||||
* @min: Minimum value in millionths (1e-6) of a unit.
|
||||
* @max: Maximum value in millionths (1e-6) of a unit.
|
||||
* @flags: Indicates the units (in bits 7:0) OR'ed with optional flags.
|
||||
*
|
||||
* A range table is associated with a single channel, or with all channels in a
|
||||
* subdevice, and a list of one or more ranges. A %struct comedi_krange
|
||||
* describes the physical range of units for one of those ranges. Sample
|
||||
* values in COMEDI are unsigned from %0 up to some 'maxdata' value. The
|
||||
* mapping from sample values to physical units is assumed to be nomimally
|
||||
* linear (for the purpose of describing the range), with sample value %0
|
||||
* mapping to @min, and the 'maxdata' sample value mapping to @max.
|
||||
*
|
||||
* The currently defined units are %UNIT_volt (%0), %UNIT_mA (%1), and
|
||||
* %UNIT_none (%2). The @min and @max values are the physical range multiplied
|
||||
* by 1e6, so a @max value of %1000000 (with %UNIT_volt) represents a maximal
|
||||
* value of 1 volt.
|
||||
*
|
||||
* The only defined flag value is %RF_external (%1 << %8), indicating that the
|
||||
* the range needs to be multiplied by an external reference.
|
||||
*/
|
||||
struct comedi_krange {
|
||||
int min; /* fixed point, multiply by 1e-6 */
|
||||
int max; /* fixed point, multiply by 1e-6 */
|
||||
int min;
|
||||
int max;
|
||||
unsigned int flags;
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_subdinfo - used to retrieve information about a subdevice
|
||||
* @type: Type of subdevice from &enum comedi_subdevice_type.
|
||||
* @n_chan: Number of channels the subdevice supports.
|
||||
* @subd_flags: A mixture of static and dynamic flags describing
|
||||
* aspects of the subdevice and its current state.
|
||||
* @timer_type: Timer type. Always set to %5 ("nanosecond timer").
|
||||
* @len_chanlist: Maximum length of a channel list if the subdevice
|
||||
* supports asynchronous acquisition commands.
|
||||
* @maxdata: Maximum sample value for all channels if the
|
||||
* %SDF_MAXDATA subdevice flag is clear.
|
||||
* @flags: Channel flags for all channels if the %SDF_FLAGS
|
||||
* subdevice flag is clear.
|
||||
* @range_type: The range type for all channels if the %SDF_RANGETYPE
|
||||
* subdevice flag is clear. Encodes the subdevice index
|
||||
* (bits 27:24), a dummy channel index %0 (bits 23:16),
|
||||
* and the range table length (bits 15:0).
|
||||
* @settling_time_0: Not used.
|
||||
* @insn_bits_support: Set to %COMEDI_SUPPORTED if the subdevice supports the
|
||||
* %INSN_BITS instruction, or to %COMEDI_UNSUPPORTED if it
|
||||
* does not.
|
||||
* @unused: Reserved for future use.
|
||||
*
|
||||
* This is used with the %COMEDI_SUBDINFO ioctl which copies an array of
|
||||
* &struct comedi_subdinfo back to user space, with one element per subdevice.
|
||||
* Use of this requires knowledge of the number of subdevices obtained from
|
||||
* the %COMEDI_DEVINFO ioctl.
|
||||
*
|
||||
* These are the @subd_flags values that may be ORed together...
|
||||
*
|
||||
* %SDF_BUSY - the subdevice is busy processing an asynchronous command or a
|
||||
* synchronous instruction.
|
||||
*
|
||||
* %SDF_BUSY_OWNER - the subdevice is busy processing an asynchronous
|
||||
* acquisition command started on the current file object (the file object
|
||||
* issuing the %COMEDI_SUBDINFO ioctl).
|
||||
*
|
||||
* %SDF_LOCKED - the subdevice is locked by a %COMEDI_LOCK ioctl.
|
||||
*
|
||||
* %SDF_LOCK_OWNER - the subdevice is locked by a %COMEDI_LOCK ioctl from the
|
||||
* current file object.
|
||||
*
|
||||
* %SDF_MAXDATA - maximum sample values are channel-specific.
|
||||
*
|
||||
* %SDF_FLAGS - channel flags are channel-specific.
|
||||
*
|
||||
* %SDF_RANGETYPE - range types are channel-specific.
|
||||
*
|
||||
* %SDF_MODE0 (aliased as %SDF_PWM_COUNTER) - the subdevice can do mode 0 (?)
|
||||
* or PWM can switch off automatically.
|
||||
*
|
||||
* %SDF_MODE1 (aliased as %SDF_PWM_HBRIDGE) - the subdevice can do mode 1 (?)
|
||||
* or PWM is signed (H-bridge).
|
||||
*
|
||||
* %SDF_MODE2 - the subdevice can do mode 2 (?).
|
||||
*
|
||||
* %SDF_MODE3 - the subdevice can do mode 3 (?).
|
||||
*
|
||||
* %SDF_MODE4 - the subdevice can do mode 4 (?).
|
||||
*
|
||||
* %SDF_CMD - the subdevice supports asynchronous commands.
|
||||
*
|
||||
* %SDF_SOFT_CALIBRATED - the subdevice uses software calibration.
|
||||
*
|
||||
* %SDF_CMD_WRITE - the subdevice supports asynchronous commands in the output
|
||||
* ("write") direction.
|
||||
*
|
||||
* %SDF_CMD_READ - the subdevice supports asynchronous commands in the input
|
||||
* ("read") direction.
|
||||
*
|
||||
* %SDF_READABLE - the subdevice is readable (e.g. analog input).
|
||||
*
|
||||
* %SDF_WRITABLE (aliased as %SDF_WRITEABLE) - the subdevice is writable (e.g.
|
||||
* analog output).
|
||||
*
|
||||
* %SDF_INTERNAL - the subdevice has no externally visible lines.
|
||||
*
|
||||
* %SDF_GROUND - the subdevice can use ground as an analog reference.
|
||||
*
|
||||
* %SDF_COMMON - the subdevice can use a common analog reference.
|
||||
*
|
||||
* %SDF_DIFF - the subdevice can use differential inputs (or outputs).
|
||||
*
|
||||
* %SDF_OTHER - the subdevice can use some other analog reference.
|
||||
*
|
||||
* %SDF_DITHER - the subdevice can do dithering.
|
||||
*
|
||||
* %SDF_DEGLITCH - the subdevice can do deglitching.
|
||||
*
|
||||
* %SDF_MMAP - this is never set.
|
||||
*
|
||||
* %SDF_RUNNING - an asynchronous command is still running.
|
||||
*
|
||||
* %SDF_LSAMPL - the subdevice uses "long" (32-bit) samples (for asynchronous
|
||||
* command data).
|
||||
*
|
||||
* %SDF_PACKED - the subdevice packs several DIO samples into a single sample
|
||||
* (for asynchronous command data).
|
||||
*
|
||||
* No "channel flags" (@flags) values are currently defined.
|
||||
*/
|
||||
struct comedi_subdinfo {
|
||||
unsigned int type;
|
||||
unsigned int n_chan;
|
||||
@ -557,14 +812,26 @@ struct comedi_subdinfo {
|
||||
unsigned int timer_type;
|
||||
unsigned int len_chanlist;
|
||||
unsigned int maxdata;
|
||||
unsigned int flags; /* channel flags */
|
||||
unsigned int range_type; /* lookup in kernel */
|
||||
unsigned int flags;
|
||||
unsigned int range_type;
|
||||
unsigned int settling_time_0;
|
||||
/* see support_level enum for values */
|
||||
unsigned insn_bits_support;
|
||||
unsigned int unused[8];
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_devinfo - used to retrieve information about a COMEDI device
|
||||
* @version_code: COMEDI version code.
|
||||
* @n_subdevs: Number of subdevices the device has.
|
||||
* @driver_name: Null-terminated COMEDI driver name.
|
||||
* @board_name: Null-terminated COMEDI board name.
|
||||
* @read_subdevice: Index of the current "read" subdevice (%-1 if none).
|
||||
* @write_subdevice: Index of the current "write" subdevice (%-1 if none).
|
||||
* @unused: Reserved for future use.
|
||||
*
|
||||
* This is used with the %COMEDI_DEVINFO ioctl to get basic information about
|
||||
* the device.
|
||||
*/
|
||||
struct comedi_devinfo {
|
||||
unsigned int version_code;
|
||||
unsigned int n_subdevs;
|
||||
@ -575,11 +842,45 @@ struct comedi_devinfo {
|
||||
int unused[30];
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_devconfig - used to configure a legacy COMEDI device
|
||||
* @board_name: Null-terminated string specifying the type of board
|
||||
* to configure.
|
||||
* @options: An array of integer configuration options.
|
||||
*
|
||||
* This is used with the %COMEDI_DEVCONFIG ioctl to configure a "legacy" COMEDI
|
||||
* device, such as an ISA card. Not all COMEDI drivers support this. Those
|
||||
* that do either expect the specified board name to match one of a list of
|
||||
* names registered with the COMEDI core, or expect the specified board name
|
||||
* to match the COMEDI driver name itself. The configuration options are
|
||||
* handled in a driver-specific manner.
|
||||
*/
|
||||
struct comedi_devconfig {
|
||||
char board_name[COMEDI_NAMELEN];
|
||||
int options[COMEDI_NDEVCONFOPTS];
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_bufconfig - used to set or get buffer size for a subdevice
|
||||
* @subdevice: Subdevice index.
|
||||
* @flags: Not used.
|
||||
* @maximum_size: Maximum allowed buffer size.
|
||||
* @size: Buffer size.
|
||||
* @unused: Reserved for future use.
|
||||
*
|
||||
* This is used with the %COMEDI_BUFCONFIG ioctl to get or configure the
|
||||
* maximum buffer size and current buffer size for a COMEDI subdevice that
|
||||
* supports asynchronous commands. If the subdevice does not support
|
||||
* asynchronous commands, @maximum_size and @size are ignored and set to 0.
|
||||
*
|
||||
* On ioctl input, non-zero values of @maximum_size and @size specify a
|
||||
* new maximum size and new current size (in bytes), respectively. These
|
||||
* will by rounded up to a multiple of %PAGE_SIZE. Specifying a new maximum
|
||||
* size requires admin capabilities.
|
||||
*
|
||||
* On ioctl output, @maximum_size and @size and set to the current maximum
|
||||
* buffer size and current buffer size, respectively.
|
||||
*/
|
||||
struct comedi_bufconfig {
|
||||
unsigned int subdevice;
|
||||
unsigned int flags;
|
||||
@ -590,6 +891,23 @@ struct comedi_bufconfig {
|
||||
unsigned int unused[4];
|
||||
};
|
||||
|
||||
/**
|
||||
* struct comedi_bufinfo - used to manipulate buffer position for a subdevice
|
||||
* @subdevice: Subdevice index.
|
||||
* @bytes_read: Specify amount to advance read position for an
|
||||
* asynchronous command in the input ("read") direction.
|
||||
* @buf_write_ptr: Current write position (index) within the buffer.
|
||||
* @buf_read_ptr: Current read position (index) within the buffer.
|
||||
* @buf_write_count: Total amount written, modulo 2^32.
|
||||
* @buf_read_count: Total amount read, modulo 2^32.
|
||||
* @bytes_written: Specify amount to advance write position for an
|
||||
* asynchronous command in the output ("write") direction.
|
||||
* @unused: Reserved for future use.
|
||||
*
|
||||
* This is used with the %COMEDI_BUFINFO ioctl to optionally advance the
|
||||
* current read or write position in an asynchronous acquisition data buffer,
|
||||
* and to get the current read and write positions in the buffer.
|
||||
*/
|
||||
struct comedi_bufinfo {
|
||||
unsigned int subdevice;
|
||||
unsigned int bytes_read;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user