linux/comedi/comedidev.h

1 /* SPDX-License-Identifier: GPL-2.0+ */
4  * header file for kernel-only structures, variables, and constants
6  * COMEDI - Linux Control and Measurement Device Interface
7  * Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>
13 #include <linux/dma-mapping.h>
28  * struct comedi_subdevice - Working data for a COMEDI subdevice
34  *	the low-level driver.)
36  *	low-level driver.)
38  *	the COMEDI core and user application.  (Initialized by the low-level
42  *	low-level driver, or changed from 0 to 1 during post-configuration.)
43  * @private: Private data pointer which is either set by the low-level driver
46  *	low-level driver's "detach" handler is called for the device.
47  *	(Initialized by the low-level driver.)
50  *	post-configuration if needed.)
57  * @spin_lock: Generic spin-lock for use by the COMEDI core and the low-level
59  * @io_bits: Bit-mask indicating the channel directions for a DIO subdevice
62  *	low-level driver for a DIO subdevice.  Forced to all-outputs during
63  *	post-configuration for a digital output subdevice.)
64  * @maxdata: If non-zero, this is the maximum raw data value of each channel.
65  *	If zero, the maximum data value is channel-specific.  (Initialized by
66  *	the low-level driver.)
67  * @maxdata_list: If the maximum data value is channel-specific, this points
69  *	(Initialized by the low-level driver.)
70  * @range_table: If non-NULL, this points to a COMEDI range table for the
71  *	subdevice.  If NULL, the range table is channel-specific.  (Initialized
72  *	by the low-level driver, will be set to an "invalid" range table during
73  *	post-configuration if @range_table and @range_table_list are both
75  * @range_table_list: If the COMEDI range table is channel-specific, this
77  *	channel number.  (Initialized by the low-level driver.)
80  *	(Initialized by the low-level driver, or set to a default handler
81  *	during post-configuration.)
83  *	(Initialized by the low-level driver, or set to a default handler
84  *	during post-configuration.)
87  *	(Initialized by the low-level driver, or set to a default handler
88  *	during post-configuration.)
90  *	instruction.  (Initialized by the low-level driver, or set to a default
91  *	handler during post-configuration.)
94  *	low-level driver.)
98  *	the low-level driver.)
101  *	instructs the low-level driver to synchronize buffers.  (Initialized by
102  *	the low-level driver if needed.)
105  *	by the low-level driver.)
109  *	(Initialized by the low-level driver if needed.)
114  *	low-level driver if needed.)
118  *	%DMA_NONE by comedi_alloc_subdevices() and changed by the low-level
120  * @state: Handy bit-mask indicating the output states for a DIO or digital
122  *	low-level driver.)
129  *	post-configuration if needed.)
131  *	device number.  (Set during post-configuration if necessary.)
135  *	automatically freed after the low-level driver's "detach" handler is
136  *	called for the device.  (Initialized by the low-level driver.)
142  * Most of the subdevice is initialized by the low-level driver's "attach" or
145  * post-configuration on return from that handler.
147  * A low-level driver that sets @insn_bits for a digital input, digital output,
149  * which case they will be set to a default handler during post-configuration
167 	spinlock_t spin_lock;	/* generic spin-lock for COMEDI and drivers */
177 	unsigned int *chanlist;	/* driver-owned chanlist (not used) */
215  * struct comedi_buf_page - Describe a page of a COMEDI buffer
225  * struct comedi_buf_map - Describe pages in a COMEDI buffer
226  * @dma_hw_dev: Low-level hardware &struct device pointer copied from the
237  * low-level hardware device.  (The buffer pages also get mapped into the
242  * low-level driver (which may happen due to device removal), but if it happens
257  * struct comedi_async - Control data for asynchronous COMEDI commands
277  * @events: Bit-vector of events that have occurred.
280  * @cb_mask: Bit-vector of events that should wake waiting tasks.
372  * enum comedi_cb - &struct comedi_async callback "events"
373  * @COMEDI_CB_EOS:		end-of-scan
374  * @COMEDI_CB_EOA:		end-of-acquisition/output
395  * struct comedi_driver - COMEDI driver registration
405  *	to a board name is embedded in an element of a driver-defined array
406  *	of static, read-only board type information.
407  * @offset: Optional size of each element of the driver-defined array of
408  *	static, read-only board type information, i.e. the offset between each
412  * register and unregister a low-level COMEDI driver with the COMEDI core.
414  * If @num_names is non-zero, @board_name should be non-NULL, and @offset
419  * @attach handler is set.  If @num_names is non-zero, the driver's @attach
422  * array of static, read-only board type information.
429  * @attach or @auto_attach handlers can defer clean-up on error until the
451  * struct comedi_device - Working data for a COMEDI device
453  * @driver: Low-level COMEDI driver attached to this COMEDI device.
456  *	detached from the low-level driver.
457  * @private: Optional pointer to private data allocated by the low-level
459  *	detached from the low-level driver.
461  * @minor: Minor device number of COMEDI char device (0-47).
464  * @hw_dev: Optional pointer to the low-level hardware &struct device.  It is
467  *	the bus-specific COMEDI functions only work if it is set correctly.
472  *	the low-level driver's "attach" handler is called by the handler for
475  *	non-zero, otherwise it points to the low-level driver name string.
476  *	When the low-lever driver's "auto_attach" handler is called for an
477  *	automatically configured COMEDI device, it points to the low-level
478  *	driver name string.  The low-level driver is free to change it in its
480  * @board_ptr: Optional pointer to private, read-only board type information in
481  *	the low-level driver.  If the 'num_names' member of the &struct
482  *	comedi_driver is non-zero, the handler for the %COMEDI_DEVCONFIG ioctl
484  *	driver's private array of static, read-only board type information when
485  *	calling the driver's "attach" handler.  The low-level driver is free to
487  * @attached: Flag indicating that the COMEDI device is attached to a low-level
491  * @spinlock: Generic spin-lock for use by the low-level driver.
496  *	changing @attached and @detach_count and calling the low-level driver's
500  * @n_subdevices: Number of COMEDI subdevices allocated by the low-level
503  * @mmio: Optional pointer to a remapped MMIO region set by the low-level
505  * @iobase: Optional base of an I/O port region requested by the low-level
508  * @irq: Optional IRQ number requested by the low-level driver.
510  *	the read() file operation.  Set by the low-level driver.
512  *	the write() file operation.  Set by the low-level driver.
514  * @open: Optional pointer to a function set by the low-level driver to be
516  * @close: Optional pointer to a function set by the low-level driver to be
518  * @insn_device_config: Optional pointer to a handler for all sub-instructions
520  *	instruction.  If this is not initialized by the low-level driver, a
521  *	default handler will be set during post-configuration.
523  *	%INSN_DEVICE_CONFIG_GET_ROUTES sub-instruction of the
525  *	low-level driver, a default handler that copies zero routes back to the
529  * COMEDI core is concerned).  There are two groups of COMEDI devices -
533  * a low-level COMEDI driver.  The "legacy" COMEDI devices are allocated
535  * parameter is non-zero and use minor device numbers from 0 to
555 	spinlock_t spinlock;	/* generic spin-lock for low-level driver */
607 #define BIP_RANGE(a)		{-(a) * 1e6, (a) * 1e6, 0}
624  * struct comedi_lrange - Describes a COMEDI range table
640  * comedi_range_is_bipolar() - Test if subdevice range is bipolar
648  * channel-specific range table list.
657 	return s->range_table->range[range].min < 0;  in comedi_range_is_bipolar()
661  * comedi_range_is_unipolar() - Test if subdevice range is unipolar
669  * channel-specific range table list.
678 	return s->range_table->range[range].min >= 0;  in comedi_range_is_unipolar()
682  * comedi_range_is_external() - Test if subdevice range is external
690  * channel-specific range table list.
699 	return !!(s->range_table->range[range].flags & RF_EXTERNAL);  in comedi_range_is_external()
703  * comedi_chan_range_is_bipolar() - Test if channel-specific range is bipolar
712  * channel-specific range table list.
722 	return s->range_table_list[chan]->range[range].min < 0;  in comedi_chan_range_is_bipolar()
726  * comedi_chan_range_is_unipolar() - Test if channel-specific range is unipolar
735  * channel-specific range table list.
745 	return s->range_table_list[chan]->range[range].min >= 0;  in comedi_chan_range_is_unipolar()
749  * comedi_chan_range_is_external() - Test if channel-specific range is external
758  * channel-specific range table list.
768 	return !!(s->range_table_list[chan]->range[range].flags & RF_EXTERNAL);  in comedi_chan_range_is_external()
772  * comedi_offset_munge() - Convert between offset binary and 2's complement
777  * and 2's complement.  Assumes that @s->maxdata is a power of 2 minus 1.
784 	return val ^ s->maxdata ^ (s->maxdata >> 1);  in comedi_offset_munge()
788  * comedi_bytes_per_sample() - Determine subdevice sample size
798 	return s->subdev_flags & SDF_LSAMPL ? sizeof(int) : sizeof(short);  in comedi_bytes_per_sample()
802  * comedi_sample_shift() - Determine log2 of subdevice sample size
808  * bit-shift operator to multiply or divide something by the sample size.
814 	return s->subdev_flags & SDF_LSAMPL ? 2 : 1;  in comedi_sample_shift()
818  * comedi_bytes_to_samples() - Convert a number of bytes to a number of samples
831  * comedi_samples_to_bytes() - Convert a number of samples to a number of bytes
845  * comedi_check_trigger_src() - Trivially validate a comedi_cmd trigger source
856  *	-EINVAL if any trigger source in *@src is unsupported.
865 		return -EINVAL;  in comedi_check_trigger_src()
870  * comedi_check_trigger_is_unique() - Make sure a trigger source is unique
875  *	-EINVAL if more than one trigger source is set.
880 	if ((src & (src - 1)) != 0)  in comedi_check_trigger_is_unique()
881 		return -EINVAL;  in comedi_check_trigger_is_unique()
886  * comedi_check_trigger_arg_is() - Trivially validate a trigger argument
894  *	-EINVAL if *@arg differed from @val.
901 		return -EINVAL;  in comedi_check_trigger_arg_is()
907  * comedi_check_trigger_arg_min() - Trivially validate a trigger argument min
915  *	-EINVAL if *@arg was less than @val.
922 		return -EINVAL;  in comedi_check_trigger_arg_min()
928  * comedi_check_trigger_arg_max() - Trivially validate a trigger argument max
936  *	-EINVAL if *@arg was greater than @val.
943 		return -EINVAL;  in comedi_check_trigger_arg_max()
949  * Must set dev->hw_dev if you wish to dma directly into comedi's buffer.
951  * known bus type.  Set automatically for auto-configured devices.
957  * comedi_buf_n_bytes_ready - Determine amount of unread data in buffer
968 	return s->async->buf_write_count - s->async->buf_read_count;  in comedi_buf_n_bytes_ready()
983 /* drivers.c - general comedi driver functions */
1042  * module_comedi_driver() - Helper macro for registering a comedi driver