1054 lines · c
1/* SPDX-License-Identifier: GPL-2.0+ */2/*3 * comedidev.h4 * header file for kernel-only structures, variables, and constants5 *6 * COMEDI - Linux Control and Measurement Device Interface7 * Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org>8 */9 10#ifndef _COMEDIDEV_H11#define _COMEDIDEV_H12 13#include <linux/dma-mapping.h>14#include <linux/mutex.h>15#include <linux/spinlock_types.h>16#include <linux/rwsem.h>17#include <linux/kref.h>18#include <linux/comedi.h>19 20#define COMEDI_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c))21#define COMEDI_VERSION_CODE COMEDI_VERSION(COMEDI_MAJORVERSION, \22 COMEDI_MINORVERSION, COMEDI_MICROVERSION)23#define COMEDI_RELEASE VERSION24 25#define COMEDI_NUM_BOARD_MINORS 0x3026 27/**28 * struct comedi_subdevice - Working data for a COMEDI subdevice29 * @device: COMEDI device to which this subdevice belongs. (Initialized by30 * comedi_alloc_subdevices().)31 * @index: Index of this subdevice within device's array of subdevices.32 * (Initialized by comedi_alloc_subdevices().)33 * @type: Type of subdevice from &enum comedi_subdevice_type. (Initialized by34 * the low-level driver.)35 * @n_chan: Number of channels the subdevice supports. (Initialized by the36 * low-level driver.)37 * @subdev_flags: Various "SDF" flags indicating aspects of the subdevice to38 * the COMEDI core and user application. (Initialized by the low-level39 * driver.)40 * @len_chanlist: Maximum length of a channel list if the subdevice supports41 * asynchronous acquisition commands. (Optionally initialized by the42 * 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 driver44 * itself, or by a call to comedi_alloc_spriv() which allocates storage.45 * In the latter case, the storage is automatically freed after the46 * low-level driver's "detach" handler is called for the device.47 * (Initialized by the low-level driver.)48 * @async: Pointer to &struct comedi_async id the subdevice supports49 * asynchronous acquisition commands. (Allocated and initialized during50 * post-configuration if needed.)51 * @lock: Pointer to a file object that performed a %COMEDI_LOCK ioctl on the52 * subdevice. (Initially NULL.)53 * @busy: Pointer to a file object that is performing an asynchronous54 * acquisition command on the subdevice. (Initially NULL.)55 * @runflags: Internal flags for use by COMEDI core, mostly indicating whether56 * an asynchronous acquisition command is running.57 * @spin_lock: Generic spin-lock for use by the COMEDI core and the low-level58 * driver. (Initialized by comedi_alloc_subdevices().)59 * @io_bits: Bit-mask indicating the channel directions for a DIO subdevice60 * with no more than 32 channels. A '1' at a bit position indicates the61 * corresponding channel is configured as an output. (Initialized by the62 * low-level driver for a DIO subdevice. Forced to all-outputs during63 * 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 by66 * the low-level driver.)67 * @maxdata_list: If the maximum data value is channel-specific, this points68 * to an array of maximum data values indexed by channel index.69 * (Initialized by the low-level driver.)70 * @range_table: If non-NULL, this points to a COMEDI range table for the71 * subdevice. If NULL, the range table is channel-specific. (Initialized72 * by the low-level driver, will be set to an "invalid" range table during73 * post-configuration if @range_table and @range_table_list are both74 * NULL.)75 * @range_table_list: If the COMEDI range table is channel-specific, this76 * points to an array of pointers to COMEDI range tables indexed by77 * channel number. (Initialized by the low-level driver.)78 * @chanlist: Not used.79 * @insn_read: Optional pointer to a handler for the %INSN_READ instruction.80 * (Initialized by the low-level driver, or set to a default handler81 * during post-configuration.)82 * @insn_write: Optional pointer to a handler for the %INSN_WRITE instruction.83 * (Initialized by the low-level driver, or set to a default handler84 * during post-configuration.)85 * @insn_bits: Optional pointer to a handler for the %INSN_BITS instruction86 * for a digital input, digital output or digital input/output subdevice.87 * (Initialized by the low-level driver, or set to a default handler88 * during post-configuration.)89 * @insn_config: Optional pointer to a handler for the %INSN_CONFIG90 * instruction. (Initialized by the low-level driver, or set to a default91 * handler during post-configuration.)92 * @do_cmd: If the subdevice supports asynchronous acquisition commands, this93 * points to a handler to set it up in hardware. (Initialized by the94 * low-level driver.)95 * @do_cmdtest: If the subdevice supports asynchronous acquisition commands,96 * this points to a handler used to check and possibly tweak a prospective97 * acquisition command without setting it up in hardware. (Initialized by98 * the low-level driver.)99 * @poll: If the subdevice supports asynchronous acquisition commands, this100 * is an optional pointer to a handler for the %COMEDI_POLL ioctl which101 * instructs the low-level driver to synchronize buffers. (Initialized by102 * the low-level driver if needed.)103 * @cancel: If the subdevice supports asynchronous acquisition commands, this104 * points to a handler used to terminate a running command. (Initialized105 * by the low-level driver.)106 * @buf_change: If the subdevice supports asynchronous acquisition commands,107 * this is an optional pointer to a handler that is called when the data108 * buffer for handling asynchronous commands is allocated or reallocated.109 * (Initialized by the low-level driver if needed.)110 * @munge: If the subdevice supports asynchronous acquisition commands and111 * uses DMA to transfer data from the hardware to the acquisition buffer,112 * this points to a function used to "munge" the data values from the113 * hardware into the format expected by COMEDI. (Initialized by the114 * low-level driver if needed.)115 * @async_dma_dir: If the subdevice supports asynchronous acquisition commands116 * and uses DMA to transfer data from the hardware to the acquisition117 * buffer, this sets the DMA direction for the buffer. (initialized to118 * %DMA_NONE by comedi_alloc_subdevices() and changed by the low-level119 * driver if necessary.)120 * @state: Handy bit-mask indicating the output states for a DIO or digital121 * output subdevice with no more than 32 channels. (Initialized by the122 * low-level driver.)123 * @class_dev: If the subdevice supports asynchronous acquisition commands,124 * this points to a sysfs comediX_subdY device where X is the minor device125 * number of the COMEDI device and Y is the subdevice number. The minor126 * device number for the sysfs device is allocated dynamically in the127 * range 48 to 255. This is used to allow the COMEDI device to be opened128 * with a different default read or write subdevice. (Allocated during129 * post-configuration if needed.)130 * @minor: If @class_dev is set, this is its dynamically allocated minor131 * device number. (Set during post-configuration if necessary.)132 * @readback: Optional pointer to memory allocated by133 * comedi_alloc_subdev_readback() used to hold the values written to134 * analog output channels so they can be read back. The storage is135 * automatically freed after the low-level driver's "detach" handler is136 * called for the device. (Initialized by the low-level driver.)137 *138 * This is the main control structure for a COMEDI subdevice. If the subdevice139 * supports asynchronous acquisition commands, additional information is stored140 * in the &struct comedi_async pointed to by @async.141 *142 * Most of the subdevice is initialized by the low-level driver's "attach" or143 * "auto_attach" handlers but parts of it are initialized by144 * comedi_alloc_subdevices(), and other parts are initialized during145 * post-configuration on return from that handler.146 *147 * A low-level driver that sets @insn_bits for a digital input, digital output,148 * or DIO subdevice may leave @insn_read and @insn_write uninitialized, in149 * which case they will be set to a default handler during post-configuration150 * that uses @insn_bits to emulate the %INSN_READ and %INSN_WRITE instructions.151 */152struct comedi_subdevice {153 struct comedi_device *device;154 int index;155 int type;156 int n_chan;157 int subdev_flags;158 int len_chanlist; /* maximum length of channel/gain list */159 160 void *private;161 162 struct comedi_async *async;163 164 void *lock;165 void *busy;166 unsigned int runflags;167 spinlock_t spin_lock; /* generic spin-lock for COMEDI and drivers */168 169 unsigned int io_bits;170 171 unsigned int maxdata; /* if maxdata==0, use list */172 const unsigned int *maxdata_list; /* list is channel specific */173 174 const struct comedi_lrange *range_table;175 const struct comedi_lrange *const *range_table_list;176 177 unsigned int *chanlist; /* driver-owned chanlist (not used) */178 179 int (*insn_read)(struct comedi_device *dev, struct comedi_subdevice *s,180 struct comedi_insn *insn, unsigned int *data);181 int (*insn_write)(struct comedi_device *dev, struct comedi_subdevice *s,182 struct comedi_insn *insn, unsigned int *data);183 int (*insn_bits)(struct comedi_device *dev, struct comedi_subdevice *s,184 struct comedi_insn *insn, unsigned int *data);185 int (*insn_config)(struct comedi_device *dev,186 struct comedi_subdevice *s,187 struct comedi_insn *insn,188 unsigned int *data);189 190 int (*do_cmd)(struct comedi_device *dev, struct comedi_subdevice *s);191 int (*do_cmdtest)(struct comedi_device *dev,192 struct comedi_subdevice *s,193 struct comedi_cmd *cmd);194 int (*poll)(struct comedi_device *dev, struct comedi_subdevice *s);195 int (*cancel)(struct comedi_device *dev, struct comedi_subdevice *s);196 197 /* called when the buffer changes */198 int (*buf_change)(struct comedi_device *dev,199 struct comedi_subdevice *s);200 201 void (*munge)(struct comedi_device *dev, struct comedi_subdevice *s,202 void *data, unsigned int num_bytes,203 unsigned int start_chan_index);204 enum dma_data_direction async_dma_dir;205 206 unsigned int state;207 208 struct device *class_dev;209 int minor;210 211 unsigned int *readback;212};213 214/**215 * struct comedi_buf_page - Describe a page of a COMEDI buffer216 * @virt_addr: Kernel address of page.217 * @dma_addr: DMA address of page if in DMA coherent memory.218 */219struct comedi_buf_page {220 void *virt_addr;221 dma_addr_t dma_addr;222};223 224/**225 * struct comedi_buf_map - Describe pages in a COMEDI buffer226 * @dma_hw_dev: Low-level hardware &struct device pointer copied from the227 * COMEDI device's hw_dev member.228 * @page_list: Pointer to array of &struct comedi_buf_page, one for each229 * page in the buffer.230 * @n_pages: Number of pages in the buffer.231 * @dma_dir: DMA direction used to allocate pages of DMA coherent memory,232 * or %DMA_NONE if pages allocated from regular memory.233 * @refcount: &struct kref reference counter used to free the buffer.234 *235 * A COMEDI data buffer is allocated as individual pages, either in236 * conventional memory or DMA coherent memory, depending on the attached,237 * low-level hardware device. (The buffer pages also get mapped into the238 * kernel's contiguous virtual address space pointed to by the 'prealloc_buf'239 * member of &struct comedi_async.)240 *241 * The buffer is normally freed when the COMEDI device is detached from the242 * low-level driver (which may happen due to device removal), but if it happens243 * to be mmapped at the time, the pages cannot be freed until the buffer has244 * been munmapped. That is what the reference counter is for. (The virtual245 * address space pointed by 'prealloc_buf' is freed when the COMEDI device is246 * detached.)247 */248struct comedi_buf_map {249 struct device *dma_hw_dev;250 struct comedi_buf_page *page_list;251 unsigned int n_pages;252 enum dma_data_direction dma_dir;253 struct kref refcount;254};255 256/**257 * struct comedi_async - Control data for asynchronous COMEDI commands258 * @prealloc_buf: Kernel virtual address of allocated acquisition buffer.259 * @prealloc_bufsz: Buffer size (in bytes).260 * @buf_map: Map of buffer pages.261 * @max_bufsize: Maximum allowed buffer size (in bytes).262 * @buf_write_count: "Write completed" count (in bytes, modulo 2**32).263 * @buf_write_alloc_count: "Allocated for writing" count (in bytes,264 * modulo 2**32).265 * @buf_read_count: "Read completed" count (in bytes, modulo 2**32).266 * @buf_read_alloc_count: "Allocated for reading" count (in bytes,267 * modulo 2**32).268 * @buf_write_ptr: Buffer position for writer.269 * @buf_read_ptr: Buffer position for reader.270 * @cur_chan: Current position in chanlist for scan (for those drivers that271 * use it).272 * @scans_done: The number of scans completed.273 * @scan_progress: Amount received or sent for current scan (in bytes).274 * @munge_chan: Current position in chanlist for "munging".275 * @munge_count: "Munge" count (in bytes, modulo 2**32).276 * @munge_ptr: Buffer position for "munging".277 * @events: Bit-vector of events that have occurred.278 * @cmd: Details of comedi command in progress.279 * @wait_head: Task wait queue for file reader or writer.280 * @cb_mask: Bit-vector of events that should wake waiting tasks.281 * @inttrig: Software trigger function for command, or NULL.282 *283 * Note about the ..._count and ..._ptr members:284 *285 * Think of the _Count values being integers of unlimited size, indexing286 * into a buffer of infinite length (though only an advancing portion287 * of the buffer of fixed length prealloc_bufsz is accessible at any288 * time). Then:289 *290 * Buf_Read_Count <= Buf_Read_Alloc_Count <= Munge_Count <=291 * Buf_Write_Count <= Buf_Write_Alloc_Count <=292 * (Buf_Read_Count + prealloc_bufsz)293 *294 * (Those aren't the actual members, apart from prealloc_bufsz.) When the295 * buffer is reset, those _Count values start at 0 and only increase in value,296 * maintaining the above inequalities until the next time the buffer is297 * reset. The buffer is divided into the following regions by the inequalities:298 *299 * [0, Buf_Read_Count):300 * old region no longer accessible301 *302 * [Buf_Read_Count, Buf_Read_Alloc_Count):303 * filled and munged region allocated for reading but not yet read304 *305 * [Buf_Read_Alloc_Count, Munge_Count):306 * filled and munged region not yet allocated for reading307 *308 * [Munge_Count, Buf_Write_Count):309 * filled region not yet munged310 *311 * [Buf_Write_Count, Buf_Write_Alloc_Count):312 * unfilled region allocated for writing but not yet written313 *314 * [Buf_Write_Alloc_Count, Buf_Read_Count + prealloc_bufsz):315 * unfilled region not yet allocated for writing316 *317 * [Buf_Read_Count + prealloc_bufsz, infinity):318 * unfilled region not yet accessible319 *320 * Data needs to be written into the buffer before it can be read out,321 * and may need to be converted (or "munged") between the two322 * operations. Extra unfilled buffer space may need to allocated for323 * writing (advancing Buf_Write_Alloc_Count) before new data is written.324 * After writing new data, the newly filled space needs to be released325 * (advancing Buf_Write_Count). This also results in the new data being326 * "munged" (advancing Munge_Count). Before data is read out of the327 * buffer, extra space may need to be allocated for reading (advancing328 * Buf_Read_Alloc_Count). After the data has been read out, the space329 * needs to be released (advancing Buf_Read_Count).330 *331 * The actual members, buf_read_count, buf_read_alloc_count,332 * munge_count, buf_write_count, and buf_write_alloc_count take the333 * value of the corresponding capitalized _Count values modulo 2^32334 * (UINT_MAX+1). Subtracting a "higher" _count value from a "lower"335 * _count value gives the same answer as subtracting a "higher" _Count336 * value from a lower _Count value because prealloc_bufsz < UINT_MAX+1.337 * The modulo operation is done implicitly.338 *339 * The buf_read_ptr, munge_ptr, and buf_write_ptr members take the value340 * of the corresponding capitalized _Count values modulo prealloc_bufsz.341 * These correspond to byte indices in the physical buffer. The modulo342 * operation is done by subtracting prealloc_bufsz when the value343 * exceeds prealloc_bufsz (assuming prealloc_bufsz plus the increment is344 * less than or equal to UINT_MAX).345 */346struct comedi_async {347 void *prealloc_buf;348 unsigned int prealloc_bufsz;349 struct comedi_buf_map *buf_map;350 unsigned int max_bufsize;351 unsigned int buf_write_count;352 unsigned int buf_write_alloc_count;353 unsigned int buf_read_count;354 unsigned int buf_read_alloc_count;355 unsigned int buf_write_ptr;356 unsigned int buf_read_ptr;357 unsigned int cur_chan;358 unsigned int scans_done;359 unsigned int scan_progress;360 unsigned int munge_chan;361 unsigned int munge_count;362 unsigned int munge_ptr;363 unsigned int events;364 struct comedi_cmd cmd;365 wait_queue_head_t wait_head;366 unsigned int cb_mask;367 int (*inttrig)(struct comedi_device *dev, struct comedi_subdevice *s,368 unsigned int x);369};370 371/**372 * enum comedi_cb - &struct comedi_async callback "events"373 * @COMEDI_CB_EOS: end-of-scan374 * @COMEDI_CB_EOA: end-of-acquisition/output375 * @COMEDI_CB_BLOCK: data has arrived, wakes up read() / write()376 * @COMEDI_CB_EOBUF: DEPRECATED: end of buffer377 * @COMEDI_CB_ERROR: card error during acquisition378 * @COMEDI_CB_OVERFLOW: buffer overflow/underflow379 * @COMEDI_CB_ERROR_MASK: events that indicate an error has occurred380 * @COMEDI_CB_CANCEL_MASK: events that will cancel an async command381 */382enum comedi_cb {383 COMEDI_CB_EOS = BIT(0),384 COMEDI_CB_EOA = BIT(1),385 COMEDI_CB_BLOCK = BIT(2),386 COMEDI_CB_EOBUF = BIT(3),387 COMEDI_CB_ERROR = BIT(4),388 COMEDI_CB_OVERFLOW = BIT(5),389 /* masks */390 COMEDI_CB_ERROR_MASK = (COMEDI_CB_ERROR | COMEDI_CB_OVERFLOW),391 COMEDI_CB_CANCEL_MASK = (COMEDI_CB_EOA | COMEDI_CB_ERROR_MASK)392};393 394/**395 * struct comedi_driver - COMEDI driver registration396 * @driver_name: Name of driver.397 * @module: Owning module.398 * @attach: The optional "attach" handler for manually configured COMEDI399 * devices.400 * @detach: The "detach" handler for deconfiguring COMEDI devices.401 * @auto_attach: The optional "auto_attach" handler for automatically402 * configured COMEDI devices.403 * @num_names: Optional number of "board names" supported.404 * @board_name: Optional pointer to a pointer to a board name. The pointer405 * to a board name is embedded in an element of a driver-defined array406 * of static, read-only board type information.407 * @offset: Optional size of each element of the driver-defined array of408 * static, read-only board type information, i.e. the offset between each409 * pointer to a board name.410 *411 * This is used with comedi_driver_register() and comedi_driver_unregister() to412 * register and unregister a low-level COMEDI driver with the COMEDI core.413 *414 * If @num_names is non-zero, @board_name should be non-NULL, and @offset415 * should be at least sizeof(*board_name). These are used by the handler for416 * the %COMEDI_DEVCONFIG ioctl to match a hardware device and its driver by417 * board name. If @num_names is zero, the %COMEDI_DEVCONFIG ioctl matches a418 * hardware device and its driver by driver name. This is only useful if the419 * @attach handler is set. If @num_names is non-zero, the driver's @attach420 * handler will be called with the COMEDI device structure's board_ptr member421 * pointing to the matched pointer to a board name within the driver's private422 * array of static, read-only board type information.423 *424 * The @detach handler has two roles. If a COMEDI device was successfully425 * configured by the @attach or @auto_attach handler, it is called when the426 * device is being deconfigured (by the %COMEDI_DEVCONFIG ioctl, or due to427 * unloading of the driver, or due to device removal). It is also called when428 * the @attach or @auto_attach handler returns an error. Therefore, the429 * @attach or @auto_attach handlers can defer clean-up on error until the430 * @detach handler is called. If the @attach or @auto_attach handlers free431 * any resources themselves, they must prevent the @detach handler from432 * freeing the same resources. The @detach handler must not assume that all433 * resources requested by the @attach or @auto_attach handler were434 * successfully allocated.435 */436struct comedi_driver {437 /* private: */438 struct comedi_driver *next; /* Next in list of COMEDI drivers. */439 /* public: */440 const char *driver_name;441 struct module *module;442 int (*attach)(struct comedi_device *dev, struct comedi_devconfig *it);443 void (*detach)(struct comedi_device *dev);444 int (*auto_attach)(struct comedi_device *dev, unsigned long context);445 unsigned int num_names;446 const char *const *board_name;447 int offset;448};449 450/**451 * struct comedi_device - Working data for a COMEDI device452 * @use_count: Number of open file objects.453 * @driver: Low-level COMEDI driver attached to this COMEDI device.454 * @pacer: Optional pointer to a dynamically allocated acquisition pacer455 * control. It is freed automatically after the COMEDI device is456 * detached from the low-level driver.457 * @private: Optional pointer to private data allocated by the low-level458 * driver. It is freed automatically after the COMEDI device is459 * detached from the low-level driver.460 * @class_dev: Sysfs comediX device.461 * @minor: Minor device number of COMEDI char device (0-47).462 * @detach_count: Counter incremented every time the COMEDI device is detached.463 * Used for checking a previous attachment is still valid.464 * @hw_dev: Optional pointer to the low-level hardware &struct device. It is465 * required for automatically configured COMEDI devices and optional for466 * COMEDI devices configured by the %COMEDI_DEVCONFIG ioctl, although467 * the bus-specific COMEDI functions only work if it is set correctly.468 * It is also passed to dma_alloc_coherent() for COMEDI subdevices that469 * have their 'async_dma_dir' member set to something other than470 * %DMA_NONE.471 * @board_name: Pointer to a COMEDI board name or a COMEDI driver name. When472 * the low-level driver's "attach" handler is called by the handler for473 * the %COMEDI_DEVCONFIG ioctl, it either points to a matched board name474 * string if the 'num_names' member of the &struct comedi_driver is475 * 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 an477 * automatically configured COMEDI device, it points to the low-level478 * driver name string. The low-level driver is free to change it in its479 * "attach" or "auto_attach" handler if it wishes.480 * @board_ptr: Optional pointer to private, read-only board type information in481 * the low-level driver. If the 'num_names' member of the &struct482 * comedi_driver is non-zero, the handler for the %COMEDI_DEVCONFIG ioctl483 * will point it to a pointer to a matched board name string within the484 * driver's private array of static, read-only board type information when485 * calling the driver's "attach" handler. The low-level driver is free to486 * change it.487 * @attached: Flag indicating that the COMEDI device is attached to a low-level488 * driver.489 * @ioenabled: Flag used to indicate that a PCI device has been enabled and490 * its regions requested.491 * @spinlock: Generic spin-lock for use by the low-level driver.492 * @mutex: Generic mutex for use by the COMEDI core module.493 * @attach_lock: &struct rw_semaphore used to guard against the COMEDI device494 * being detached while an operation is in progress. The down_write()495 * operation is only allowed while @mutex is held and is used when496 * changing @attached and @detach_count and calling the low-level driver's497 * "detach" handler. The down_read() operation is generally used without498 * holding @mutex.499 * @refcount: &struct kref reference counter for freeing COMEDI device.500 * @n_subdevices: Number of COMEDI subdevices allocated by the low-level501 * driver for this device.502 * @subdevices: Dynamically allocated array of COMEDI subdevices.503 * @mmio: Optional pointer to a remapped MMIO region set by the low-level504 * driver.505 * @iobase: Optional base of an I/O port region requested by the low-level506 * driver.507 * @iolen: Length of I/O port region requested at @iobase.508 * @irq: Optional IRQ number requested by the low-level driver.509 * @read_subdev: Optional pointer to a default COMEDI subdevice operated on by510 * the read() file operation. Set by the low-level driver.511 * @write_subdev: Optional pointer to a default COMEDI subdevice operated on by512 * the write() file operation. Set by the low-level driver.513 * @async_queue: Storage for fasync_helper().514 * @open: Optional pointer to a function set by the low-level driver to be515 * called when @use_count changes from 0 to 1.516 * @close: Optional pointer to a function set by the low-level driver to be517 * called when @use_count changed from 1 to 0.518 * @insn_device_config: Optional pointer to a handler for all sub-instructions519 * except %INSN_DEVICE_CONFIG_GET_ROUTES of the %INSN_DEVICE_CONFIG520 * instruction. If this is not initialized by the low-level driver, a521 * default handler will be set during post-configuration.522 * @get_valid_routes: Optional pointer to a handler for the523 * %INSN_DEVICE_CONFIG_GET_ROUTES sub-instruction of the524 * %INSN_DEVICE_CONFIG instruction set. If this is not initialized by the525 * low-level driver, a default handler that copies zero routes back to the526 * user will be used.527 *528 * This is the main control data structure for a COMEDI device (as far as the529 * COMEDI core is concerned). There are two groups of COMEDI devices -530 * "legacy" devices that are configured by the handler for the531 * %COMEDI_DEVCONFIG ioctl, and automatically configured devices resulting532 * from a call to comedi_auto_config() as a result of a bus driver probe in533 * a low-level COMEDI driver. The "legacy" COMEDI devices are allocated534 * during module initialization if the "comedi_num_legacy_minors" module535 * parameter is non-zero and use minor device numbers from 0 to536 * comedi_num_legacy_minors minus one. The automatically configured COMEDI537 * devices are allocated on demand and use minor device numbers from538 * comedi_num_legacy_minors to 47.539 */540struct comedi_device {541 int use_count;542 struct comedi_driver *driver;543 struct comedi_8254 *pacer;544 void *private;545 546 struct device *class_dev;547 int minor;548 unsigned int detach_count;549 struct device *hw_dev;550 551 const char *board_name;552 const void *board_ptr;553 unsigned int attached:1;554 unsigned int ioenabled:1;555 spinlock_t spinlock; /* generic spin-lock for low-level driver */556 struct mutex mutex; /* generic mutex for COMEDI core */557 struct rw_semaphore attach_lock;558 struct kref refcount;559 560 int n_subdevices;561 struct comedi_subdevice *subdevices;562 563 /* dumb */564 void __iomem *mmio;565 unsigned long iobase;566 unsigned long iolen;567 unsigned int irq;568 569 struct comedi_subdevice *read_subdev;570 struct comedi_subdevice *write_subdev;571 572 struct fasync_struct *async_queue;573 574 int (*open)(struct comedi_device *dev);575 void (*close)(struct comedi_device *dev);576 int (*insn_device_config)(struct comedi_device *dev,577 struct comedi_insn *insn, unsigned int *data);578 unsigned int (*get_valid_routes)(struct comedi_device *dev,579 unsigned int n_pairs,580 unsigned int *pair_data);581};582 583/*584 * function prototypes585 */586 587void comedi_event(struct comedi_device *dev, struct comedi_subdevice *s);588 589struct comedi_device *comedi_dev_get_from_minor(unsigned int minor);590int comedi_dev_put(struct comedi_device *dev);591 592bool comedi_is_subdevice_running(struct comedi_subdevice *s);593 594void *comedi_alloc_spriv(struct comedi_subdevice *s, size_t size);595void comedi_set_spriv_auto_free(struct comedi_subdevice *s);596 597int comedi_check_chanlist(struct comedi_subdevice *s,598 int n,599 unsigned int *chanlist);600 601/* range stuff */602 603#define RANGE(a, b) {(a) * 1e6, (b) * 1e6, 0}604#define RANGE_ext(a, b) {(a) * 1e6, (b) * 1e6, RF_EXTERNAL}605#define RANGE_mA(a, b) {(a) * 1e6, (b) * 1e6, UNIT_mA}606#define RANGE_unitless(a, b) {(a) * 1e6, (b) * 1e6, 0}607#define BIP_RANGE(a) {-(a) * 1e6, (a) * 1e6, 0}608#define UNI_RANGE(a) {0, (a) * 1e6, 0}609 610extern const struct comedi_lrange range_bipolar10;611extern const struct comedi_lrange range_bipolar5;612extern const struct comedi_lrange range_bipolar2_5;613extern const struct comedi_lrange range_unipolar10;614extern const struct comedi_lrange range_unipolar5;615extern const struct comedi_lrange range_unipolar2_5;616extern const struct comedi_lrange range_0_20mA;617extern const struct comedi_lrange range_4_20mA;618extern const struct comedi_lrange range_0_32mA;619extern const struct comedi_lrange range_unknown;620 621#define range_digital range_unipolar5622 623/**624 * struct comedi_lrange - Describes a COMEDI range table625 * @length: Number of entries in the range table.626 * @range: Array of &struct comedi_krange, one for each range.627 *628 * Each element of @range[] describes the minimum and maximum physical range629 * and the type of units. Typically, the type of unit is %UNIT_volt630 * (i.e. volts) and the minimum and maximum are in millionths of a volt.631 * There may also be a flag that indicates the minimum and maximum are merely632 * scale factors for an unknown, external reference.633 */634struct comedi_lrange {635 int length;636 struct comedi_krange range[] __counted_by(length);637};638 639/**640 * comedi_range_is_bipolar() - Test if subdevice range is bipolar641 * @s: COMEDI subdevice.642 * @range: Index of range within a range table.643 *644 * Tests whether a range is bipolar by checking whether its minimum value645 * is negative.646 *647 * Assumes @range is valid. Does not work for subdevices using a648 * channel-specific range table list.649 *650 * Return:651 * %true if the range is bipolar.652 * %false if the range is unipolar.653 */654static inline bool comedi_range_is_bipolar(struct comedi_subdevice *s,655 unsigned int range)656{657 return s->range_table->range[range].min < 0;658}659 660/**661 * comedi_range_is_unipolar() - Test if subdevice range is unipolar662 * @s: COMEDI subdevice.663 * @range: Index of range within a range table.664 *665 * Tests whether a range is unipolar by checking whether its minimum value666 * is at least 0.667 *668 * Assumes @range is valid. Does not work for subdevices using a669 * channel-specific range table list.670 *671 * Return:672 * %true if the range is unipolar.673 * %false if the range is bipolar.674 */675static inline bool comedi_range_is_unipolar(struct comedi_subdevice *s,676 unsigned int range)677{678 return s->range_table->range[range].min >= 0;679}680 681/**682 * comedi_range_is_external() - Test if subdevice range is external683 * @s: COMEDI subdevice.684 * @range: Index of range within a range table.685 *686 * Tests whether a range is externally reference by checking whether its687 * %RF_EXTERNAL flag is set.688 *689 * Assumes @range is valid. Does not work for subdevices using a690 * channel-specific range table list.691 *692 * Return:693 * %true if the range is external.694 * %false if the range is internal.695 */696static inline bool comedi_range_is_external(struct comedi_subdevice *s,697 unsigned int range)698{699 return !!(s->range_table->range[range].flags & RF_EXTERNAL);700}701 702/**703 * comedi_chan_range_is_bipolar() - Test if channel-specific range is bipolar704 * @s: COMEDI subdevice.705 * @chan: The channel number.706 * @range: Index of range within a range table.707 *708 * Tests whether a range is bipolar by checking whether its minimum value709 * is negative.710 *711 * Assumes @chan and @range are valid. Only works for subdevices with a712 * channel-specific range table list.713 *714 * Return:715 * %true if the range is bipolar.716 * %false if the range is unipolar.717 */718static inline bool comedi_chan_range_is_bipolar(struct comedi_subdevice *s,719 unsigned int chan,720 unsigned int range)721{722 return s->range_table_list[chan]->range[range].min < 0;723}724 725/**726 * comedi_chan_range_is_unipolar() - Test if channel-specific range is unipolar727 * @s: COMEDI subdevice.728 * @chan: The channel number.729 * @range: Index of range within a range table.730 *731 * Tests whether a range is unipolar by checking whether its minimum value732 * is at least 0.733 *734 * Assumes @chan and @range are valid. Only works for subdevices with a735 * channel-specific range table list.736 *737 * Return:738 * %true if the range is unipolar.739 * %false if the range is bipolar.740 */741static inline bool comedi_chan_range_is_unipolar(struct comedi_subdevice *s,742 unsigned int chan,743 unsigned int range)744{745 return s->range_table_list[chan]->range[range].min >= 0;746}747 748/**749 * comedi_chan_range_is_external() - Test if channel-specific range is external750 * @s: COMEDI subdevice.751 * @chan: The channel number.752 * @range: Index of range within a range table.753 *754 * Tests whether a range is externally reference by checking whether its755 * %RF_EXTERNAL flag is set.756 *757 * Assumes @chan and @range are valid. Only works for subdevices with a758 * channel-specific range table list.759 *760 * Return:761 * %true if the range is bipolar.762 * %false if the range is unipolar.763 */764static inline bool comedi_chan_range_is_external(struct comedi_subdevice *s,765 unsigned int chan,766 unsigned int range)767{768 return !!(s->range_table_list[chan]->range[range].flags & RF_EXTERNAL);769}770 771/**772 * comedi_offset_munge() - Convert between offset binary and 2's complement773 * @s: COMEDI subdevice.774 * @val: Value to be converted.775 *776 * Toggles the highest bit of a sample value to toggle between offset binary777 * and 2's complement. Assumes that @s->maxdata is a power of 2 minus 1.778 *779 * Return: The converted value.780 */781static inline unsigned int comedi_offset_munge(struct comedi_subdevice *s,782 unsigned int val)783{784 return val ^ s->maxdata ^ (s->maxdata >> 1);785}786 787/**788 * comedi_bytes_per_sample() - Determine subdevice sample size789 * @s: COMEDI subdevice.790 *791 * The sample size will be 4 (sizeof int) or 2 (sizeof short) depending on792 * whether the %SDF_LSAMPL subdevice flag is set or not.793 *794 * Return: The subdevice sample size.795 */796static inline unsigned int comedi_bytes_per_sample(struct comedi_subdevice *s)797{798 return s->subdev_flags & SDF_LSAMPL ? sizeof(int) : sizeof(short);799}800 801/**802 * comedi_sample_shift() - Determine log2 of subdevice sample size803 * @s: COMEDI subdevice.804 *805 * The sample size will be 4 (sizeof int) or 2 (sizeof short) depending on806 * whether the %SDF_LSAMPL subdevice flag is set or not. The log2 of the807 * sample size will be 2 or 1 and can be used as the right operand of a808 * bit-shift operator to multiply or divide something by the sample size.809 *810 * Return: log2 of the subdevice sample size.811 */812static inline unsigned int comedi_sample_shift(struct comedi_subdevice *s)813{814 return s->subdev_flags & SDF_LSAMPL ? 2 : 1;815}816 817/**818 * comedi_bytes_to_samples() - Convert a number of bytes to a number of samples819 * @s: COMEDI subdevice.820 * @nbytes: Number of bytes821 *822 * Return: The number of bytes divided by the subdevice sample size.823 */824static inline unsigned int comedi_bytes_to_samples(struct comedi_subdevice *s,825 unsigned int nbytes)826{827 return nbytes >> comedi_sample_shift(s);828}829 830/**831 * comedi_samples_to_bytes() - Convert a number of samples to a number of bytes832 * @s: COMEDI subdevice.833 * @nsamples: Number of samples.834 *835 * Return: The number of samples multiplied by the subdevice sample size.836 * (Does not check for arithmetic overflow.)837 */838static inline unsigned int comedi_samples_to_bytes(struct comedi_subdevice *s,839 unsigned int nsamples)840{841 return nsamples << comedi_sample_shift(s);842}843 844/**845 * comedi_check_trigger_src() - Trivially validate a comedi_cmd trigger source846 * @src: Pointer to the trigger source to validate.847 * @flags: Bitmask of valid %TRIG_* for the trigger.848 *849 * This is used in "step 1" of the do_cmdtest functions of comedi drivers850 * to validate the comedi_cmd triggers. The mask of the @src against the851 * @flags allows the userspace comedilib to pass all the comedi_cmd852 * triggers as %TRIG_ANY and get back a bitmask of the valid trigger sources.853 *854 * Return:855 * 0 if trigger sources in *@src are all supported.856 * -EINVAL if any trigger source in *@src is unsupported.857 */858static inline int comedi_check_trigger_src(unsigned int *src,859 unsigned int flags)860{861 unsigned int orig_src = *src;862 863 *src = orig_src & flags;864 if (*src == TRIG_INVALID || *src != orig_src)865 return -EINVAL;866 return 0;867}868 869/**870 * comedi_check_trigger_is_unique() - Make sure a trigger source is unique871 * @src: The trigger source to check.872 *873 * Return:874 * 0 if no more than one trigger source is set.875 * -EINVAL if more than one trigger source is set.876 */877static inline int comedi_check_trigger_is_unique(unsigned int src)878{879 /* this test is true if more than one _src bit is set */880 if ((src & (src - 1)) != 0)881 return -EINVAL;882 return 0;883}884 885/**886 * comedi_check_trigger_arg_is() - Trivially validate a trigger argument887 * @arg: Pointer to the trigger arg to validate.888 * @val: The value the argument should be.889 *890 * Forces *@arg to be @val.891 *892 * Return:893 * 0 if *@arg was already @val.894 * -EINVAL if *@arg differed from @val.895 */896static inline int comedi_check_trigger_arg_is(unsigned int *arg,897 unsigned int val)898{899 if (*arg != val) {900 *arg = val;901 return -EINVAL;902 }903 return 0;904}905 906/**907 * comedi_check_trigger_arg_min() - Trivially validate a trigger argument min908 * @arg: Pointer to the trigger arg to validate.909 * @val: The minimum value the argument should be.910 *911 * Forces *@arg to be at least @val, setting it to @val if necessary.912 *913 * Return:914 * 0 if *@arg was already at least @val.915 * -EINVAL if *@arg was less than @val.916 */917static inline int comedi_check_trigger_arg_min(unsigned int *arg,918 unsigned int val)919{920 if (*arg < val) {921 *arg = val;922 return -EINVAL;923 }924 return 0;925}926 927/**928 * comedi_check_trigger_arg_max() - Trivially validate a trigger argument max929 * @arg: Pointer to the trigger arg to validate.930 * @val: The maximum value the argument should be.931 *932 * Forces *@arg to be no more than @val, setting it to @val if necessary.933 *934 * Return:935 * 0 if*@arg was already no more than @val.936 * -EINVAL if *@arg was greater than @val.937 */938static inline int comedi_check_trigger_arg_max(unsigned int *arg,939 unsigned int val)940{941 if (*arg > val) {942 *arg = val;943 return -EINVAL;944 }945 return 0;946}947 948/*949 * Must set dev->hw_dev if you wish to dma directly into comedi's buffer.950 * Also useful for retrieving a previously configured hardware device of951 * known bus type. Set automatically for auto-configured devices.952 * Automatically set to NULL when detaching hardware device.953 */954int comedi_set_hw_dev(struct comedi_device *dev, struct device *hw_dev);955 956/**957 * comedi_buf_n_bytes_ready - Determine amount of unread data in buffer958 * @s: COMEDI subdevice.959 *960 * Determines the number of bytes of unread data in the asynchronous961 * acquisition data buffer for a subdevice. The data in question might not962 * have been fully "munged" yet.963 *964 * Returns: The amount of unread data in bytes.965 */966static inline unsigned int comedi_buf_n_bytes_ready(struct comedi_subdevice *s)967{968 return s->async->buf_write_count - s->async->buf_read_count;969}970 971unsigned int comedi_buf_write_alloc(struct comedi_subdevice *s, unsigned int n);972unsigned int comedi_buf_write_free(struct comedi_subdevice *s, unsigned int n);973 974unsigned int comedi_buf_read_n_available(struct comedi_subdevice *s);975unsigned int comedi_buf_read_alloc(struct comedi_subdevice *s, unsigned int n);976unsigned int comedi_buf_read_free(struct comedi_subdevice *s, unsigned int n);977 978unsigned int comedi_buf_write_samples(struct comedi_subdevice *s,979 const void *data, unsigned int nsamples);980unsigned int comedi_buf_read_samples(struct comedi_subdevice *s,981 void *data, unsigned int nsamples);982 983/* drivers.c - general comedi driver functions */984 985#define COMEDI_TIMEOUT_MS 1000986 987int comedi_timeout(struct comedi_device *dev, struct comedi_subdevice *s,988 struct comedi_insn *insn,989 int (*cb)(struct comedi_device *dev,990 struct comedi_subdevice *s,991 struct comedi_insn *insn, unsigned long context),992 unsigned long context);993 994unsigned int comedi_handle_events(struct comedi_device *dev,995 struct comedi_subdevice *s);996 997int comedi_dio_insn_config(struct comedi_device *dev,998 struct comedi_subdevice *s,999 struct comedi_insn *insn, unsigned int *data,1000 unsigned int mask);1001unsigned int comedi_dio_update_state(struct comedi_subdevice *s,1002 unsigned int *data);1003unsigned int comedi_bytes_per_scan_cmd(struct comedi_subdevice *s,1004 struct comedi_cmd *cmd);1005unsigned int comedi_bytes_per_scan(struct comedi_subdevice *s);1006unsigned int comedi_nscans_left(struct comedi_subdevice *s,1007 unsigned int nscans);1008unsigned int comedi_nsamples_left(struct comedi_subdevice *s,1009 unsigned int nsamples);1010void comedi_inc_scan_progress(struct comedi_subdevice *s,1011 unsigned int num_bytes);1012 1013void *comedi_alloc_devpriv(struct comedi_device *dev, size_t size);1014int comedi_alloc_subdevices(struct comedi_device *dev, int num_subdevices);1015int comedi_alloc_subdev_readback(struct comedi_subdevice *s);1016 1017int comedi_readback_insn_read(struct comedi_device *dev,1018 struct comedi_subdevice *s,1019 struct comedi_insn *insn, unsigned int *data);1020 1021int comedi_load_firmware(struct comedi_device *dev, struct device *hw_dev,1022 const char *name,1023 int (*cb)(struct comedi_device *dev,1024 const u8 *data, size_t size,1025 unsigned long context),1026 unsigned long context);1027 1028int __comedi_request_region(struct comedi_device *dev,1029 unsigned long start, unsigned long len);1030int comedi_request_region(struct comedi_device *dev,1031 unsigned long start, unsigned long len);1032void comedi_legacy_detach(struct comedi_device *dev);1033 1034int comedi_auto_config(struct device *hardware_device,1035 struct comedi_driver *driver, unsigned long context);1036void comedi_auto_unconfig(struct device *hardware_device);1037 1038int comedi_driver_register(struct comedi_driver *driver);1039void comedi_driver_unregister(struct comedi_driver *driver);1040 1041/**1042 * module_comedi_driver() - Helper macro for registering a comedi driver1043 * @__comedi_driver: comedi_driver struct1044 *1045 * Helper macro for comedi drivers which do not do anything special in module1046 * init/exit. This eliminates a lot of boilerplate. Each module may only use1047 * this macro once, and calling it replaces module_init() and module_exit().1048 */1049#define module_comedi_driver(__comedi_driver) \1050 module_driver(__comedi_driver, comedi_driver_register, \1051 comedi_driver_unregister)1052 1053#endif /* _COMEDIDEV_H */1054