1/* 2 * comedidev.h 3 * header file for kernel-only structures, variables, and constants 4 * 5 * COMEDI - Linux Control and Measurement Device Interface 6 * Copyright (C) 1997-2000 David A. Schleef <ds@schleef.org> 7 * 8 * This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation; either version 2 of the License, or 11 * (at your option) any later version. 12 * 13 * This program is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details. 17 */ 18 19#ifndef _COMEDIDEV_H 20#define _COMEDIDEV_H 21 22#include <linux/dma-mapping.h> 23#include <linux/mutex.h> 24#include <linux/spinlock_types.h> 25#include <linux/rwsem.h> 26#include <linux/kref.h> 27 28#include "comedi.h" 29 30#define COMEDI_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c)) 31#define COMEDI_VERSION_CODE COMEDI_VERSION(COMEDI_MAJORVERSION, \ 32 COMEDI_MINORVERSION, COMEDI_MICROVERSION) 33#define COMEDI_RELEASE VERSION 34 35#define COMEDI_NUM_BOARD_MINORS 0x30 36 37/** 38 * struct comedi_subdevice - Working data for a COMEDI subdevice 39 * @device: COMEDI device to which this subdevice belongs. (Initialized by 40 * comedi_alloc_subdevices().) 41 * @index: Index of this subdevice within device's array of subdevices. 42 * (Initialized by comedi_alloc_subdevices().) 43 * @type: Type of subdevice from &enum comedi_subdevice_type. (Initialized by 44 * the low-level driver.) 45 * @n_chan: Number of channels the subdevice supports. (Initialized by the 46 * low-level driver.) 47 * @subdev_flags: Various "SDF" flags indicating aspects of the subdevice to 48 * the COMEDI core and user application. (Initialized by the low-level 49 * driver.) 50 * @len_chanlist: Maximum length of a channel list if the subdevice supports 51 * asynchronous acquisition commands. (Optionally initialized by the 52 * low-level driver, or changed from 0 to 1 during post-configuration.) 53 * @private: Private data pointer which is either set by the low-level driver 54 * itself, or by a call to comedi_alloc_spriv() which allocates storage. 55 * In the latter case, the storage is automatically freed after the 56 * low-level driver's "detach" handler is called for the device. 57 * (Initialized by the low-level driver.) 58 * @async: Pointer to &struct comedi_async id the subdevice supports 59 * asynchronous acquisition commands. (Allocated and initialized during 60 * post-configuration if needed.) 61 * @lock: Pointer to a file object that performed a %COMEDI_LOCK ioctl on the 62 * subdevice. (Initially NULL.) 63 * @busy: Pointer to a file object that is performing an asynchronous 64 * acquisition command on the subdevice. (Initially NULL.) 65 * @runflags: Internal flags for use by COMEDI core, mostly indicating whether 66 * an asynchronous acquisition command is running. 67 * @spin_lock: Generic spin-lock for use by the COMEDI core and the low-level 68 * driver. (Initialized by comedi_alloc_subdevices().) 69 * @io_bits: Bit-mask indicating the channel directions for a DIO subdevice 70 * with no more than 32 channels. A '1' at a bit position indicates the 71 * corresponding channel is configured as an output. (Initialized by the 72 * low-level driver for a DIO subdevice. Forced to all-outputs during 73 * post-configuration for a digital output subdevice.) 74 * @maxdata: If non-zero, this is the maximum raw data value of each channel. 75 * If zero, the maximum data value is channel-specific. (Initialized by 76 * the low-level driver.) 77 * @maxdata_list: If the maximum data value is channel-specific, this points 78 * to an array of maximum data values indexed by channel index. 79 * (Initialized by the low-level driver.) 80 * @range_table: If non-NULL, this points to a COMEDI range table for the 81 * subdevice. If NULL, the range table is channel-specific. (Initialized 82 * by the low-level driver, will be set to an "invalid" range table during 83 * post-configuration if @range_table and @range_table_list are both 84 * NULL.) 85 * @range_table_list: If the COMEDI range table is channel-specific, this 86 * points to an array of pointers to COMEDI range tables indexed by 87 * channel number. (Initialized by the low-level driver.) 88 * @chanlist: Not used. 89 * @insn_read: Optional pointer to a handler for the %INSN_READ instruction. 90 * (Initialized by the low-level driver, or set to a default handler 91 * during post-configuration.) 92 * @insn_write: Optional pointer to a handler for the %INSN_WRITE instruction. 93 * (Initialized by the low-level driver, or set to a default handler 94 * during post-configuration.) 95 * @insn_bits: Optional pointer to a handler for the %INSN_BITS instruction 96 * for a digital input, digital output or digital input/output subdevice. 97 * (Initialized by the low-level driver, or set to a default handler 98 * during post-configuration.) 99 * @insn_config: Optional pointer to a handler for the %INSN_CONFIG 100 * instruction. (Initialized by the low-level driver, or set to a default 101 * handler during post-configuration.) 102 * @do_cmd: If the subdevice supports asynchronous acquisition commands, this 103 * points to a handler to set it up in hardware. (Initialized by the 104 * low-level driver.) 105 * @do_cmdtest: If the subdevice supports asynchronous acquisition commands, 106 * this points to a handler used to check and possibly tweak a prospective 107 * acquisition command without setting it up in hardware. (Initialized by 108 * the low-level driver.) 109 * @poll: If the subdevice supports asynchronous acquisition commands, this 110 * is an optional pointer to a handler for the %COMEDI_POLL ioctl which 111 * instructs the low-level driver to synchronize buffers. (Initialized by 112 * the low-level driver if needed.) 113 * @cancel: If the subdevice supports asynchronous acquisition commands, this 114 * points to a handler used to terminate a running command. (Initialized 115 * by the low-level driver.) 116 * @buf_change: If the subdevice supports asynchronous acquisition commands, 117 * this is an optional pointer to a handler that is called when the data 118 * buffer for handling asynchronous commands is allocated or reallocated. 119 * (Initialized by the low-level driver if needed.) 120 * @munge: If the subdevice supports asynchronous acquisition commands and 121 * uses DMA to transfer data from the hardware to the acquisition buffer, 122 * this points to a function used to "munge" the data values from the 123 * hardware into the format expected by COMEDI. (Initialized by the 124 * low-level driver if needed.) 125 * @async_dma_dir: If the subdevice supports asynchronous acquisition commands 126 * and uses DMA to transfer data from the hardware to the acquisition 127 * buffer, this sets the DMA direction for the buffer. (initialized to 128 * %DMA_NONE by comedi_alloc_subdevices() and changed by the low-level 129 * driver if necessary.) 130 * @state: Handy bit-mask indicating the output states for a DIO or digital 131 * output subdevice with no more than 32 channels. (Initialized by the 132 * low-level driver.) 133 * @class_dev: If the subdevice supports asynchronous acquisition commands, 134 * this points to a sysfs comediX_subdY device where X is the minor device 135 * number of the COMEDI device and Y is the subdevice number. The minor 136 * device number for the sysfs device is allocated dynamically in the 137 * range 48 to 255. This is used to allow the COMEDI device to be opened 138 * with a different default read or write subdevice. (Allocated during 139 * post-configuration if needed.) 140 * @minor: If @class_dev is set, this is its dynamically allocated minor 141 * device number. (Set during post-configuration if necessary.) 142 * @readback: Optional pointer to memory allocated by 143 * comedi_alloc_subdev_readback() used to hold the values written to 144 * analog output channels so they can be read back. The storage is 145 * automatically freed after the low-level driver's "detach" handler is 146 * called for the device. (Initialized by the low-level driver.) 147 * 148 * This is the main control structure for a COMEDI subdevice. If the subdevice 149 * supports asynchronous acquisition commands, additional information is stored 150 * in the &struct comedi_async pointed to by @async. 151 * 152 * Most of the subdevice is initialized by the low-level driver's "attach" or 153 * "auto_attach" handlers but parts of it are initialized by 154 * comedi_alloc_subdevices(), and other parts are initialized during 155 * post-configuration on return from that handler. 156 * 157 * A low-level driver that sets @insn_bits for a digital input, digital output, 158 * or DIO subdevice may leave @insn_read and @insn_write uninitialized, in 159 * which case they will be set to a default handler during post-configuration 160 * that uses @insn_bits to emulate the %INSN_READ and %INSN_WRITE instructions. 161 */ 162struct comedi_subdevice { 163 struct comedi_device *device; 164 int index; 165 int type; 166 int n_chan; 167 int subdev_flags; 168 int len_chanlist; /* maximum length of channel/gain list */ 169 170 void *private; 171 172 struct comedi_async *async; 173 174 void *lock; 175 void *busy; 176 unsigned runflags; 177 spinlock_t spin_lock; /* generic spin-lock for COMEDI and drivers */ 178 179 unsigned int io_bits; 180 181 unsigned int maxdata; /* if maxdata==0, use list */ 182 const unsigned int *maxdata_list; /* list is channel specific */ 183 184 const struct comedi_lrange *range_table; 185 const struct comedi_lrange *const *range_table_list; 186 187 unsigned int *chanlist; /* driver-owned chanlist (not used) */ 188 189 int (*insn_read)(struct comedi_device *, struct comedi_subdevice *, 190 struct comedi_insn *, unsigned int *); 191 int (*insn_write)(struct comedi_device *, struct comedi_subdevice *, 192 struct comedi_insn *, unsigned int *); 193 int (*insn_bits)(struct comedi_device *, struct comedi_subdevice *, 194 struct comedi_insn *, unsigned int *); 195 int (*insn_config)(struct comedi_device *, struct comedi_subdevice *, 196 struct comedi_insn *, unsigned int *); 197 198 int (*do_cmd)(struct comedi_device *, struct comedi_subdevice *); 199 int (*do_cmdtest)(struct comedi_device *, struct comedi_subdevice *, 200 struct comedi_cmd *); 201 int (*poll)(struct comedi_device *, struct comedi_subdevice *); 202 int (*cancel)(struct comedi_device *, struct comedi_subdevice *); 203 204 /* called when the buffer changes */ 205 int (*buf_change)(struct comedi_device *, struct comedi_subdevice *); 206 207 void (*munge)(struct comedi_device *dev, struct comedi_subdevice *s, 208 void *data, unsigned int num_bytes, 209 unsigned int start_chan_index); 210 enum dma_data_direction async_dma_dir; 211 212 unsigned int state; 213 214 struct device *class_dev; 215 int minor; 216 217 unsigned int *readback; 218}; 219 220/** 221 * struct comedi_buf_page - Describe a page of a COMEDI buffer 222 * @virt_addr: Kernel address of page. 223 * @dma_addr: DMA address of page if in DMA coherent memory. 224 */ 225struct comedi_buf_page { 226 void *virt_addr; 227 dma_addr_t dma_addr; 228}; 229 230/** 231 * struct comedi_buf_map - Describe pages in a COMEDI buffer 232 * @dma_hw_dev: Low-level hardware &struct device pointer copied from the 233 * COMEDI device's hw_dev member. 234 * @page_list: Pointer to array of &struct comedi_buf_page, one for each 235 * page in the buffer. 236 * @n_pages: Number of pages in the buffer. 237 * @dma_dir: DMA direction used to allocate pages of DMA coherent memory, 238 * or %DMA_NONE if pages allocated from regular memory. 239 * @refcount: &struct kref reference counter used to free the buffer. 240 * 241 * A COMEDI data buffer is allocated as individual pages, either in 242 * conventional memory or DMA coherent memory, depending on the attached, 243 * low-level hardware device. (The buffer pages also get mapped into the 244 * kernel's contiguous virtual address space pointed to by the 'prealloc_buf' 245 * member of &struct comedi_async.) 246 * 247 * The buffer is normally freed when the COMEDI device is detached from the 248 * low-level driver (which may happen due to device removal), but if it happens 249 * to be mmapped at the time, the pages cannot be freed until the buffer has 250 * been munmapped. That is what the reference counter is for. (The virtual 251 * address space pointed by 'prealloc_buf' is freed when the COMEDI device is 252 * detached.) 253 */ 254struct comedi_buf_map { 255 struct device *dma_hw_dev; 256 struct comedi_buf_page *page_list; 257 unsigned int n_pages; 258 enum dma_data_direction dma_dir; 259 struct kref refcount; 260}; 261 262/** 263 * struct comedi_async - Control data for asynchronous COMEDI commands 264 * @prealloc_buf: Kernel virtual address of allocated acquisition buffer. 265 * @prealloc_bufsz: Buffer size (in bytes). 266 * @buf_map: Map of buffer pages. 267 * @max_bufsize: Maximum allowed buffer size (in bytes). 268 * @buf_write_count: "Write completed" count (in bytes, modulo 2**32). 269 * @buf_write_alloc_count: "Allocated for writing" count (in bytes, 270 * modulo 2**32). 271 * @buf_read_count: "Read completed" count (in bytes, modulo 2**32). 272 * @buf_read_alloc_count: "Allocated for reading" count (in bytes, 273 * modulo 2**32). 274 * @buf_write_ptr: Buffer position for writer. 275 * @buf_read_ptr: Buffer position for reader. 276 * @cur_chan: Current position in chanlist for scan (for those drivers that 277 * use it). 278 * @scans_done: The number of scans completed. 279 * @scan_progress: Amount received or sent for current scan (in bytes). 280 * @munge_chan: Current position in chanlist for "munging". 281 * @munge_count: "Munge" count (in bytes, modulo 2**32). 282 * @munge_ptr: Buffer position for "munging". 283 * @events: Bit-vector of events that have occurred. 284 * @cmd: Details of comedi command in progress. 285 * @wait_head: Task wait queue for file reader or writer. 286 * @cb_mask: Bit-vector of events that should wake waiting tasks. 287 * @inttrig: Software trigger function for command, or NULL. 288 * 289 * Note about the ..._count and ..._ptr members: 290 * 291 * Think of the _Count values being integers of unlimited size, indexing 292 * into a buffer of infinite length (though only an advancing portion 293 * of the buffer of fixed length prealloc_bufsz is accessible at any 294 * time). Then: 295 * 296 * Buf_Read_Count <= Buf_Read_Alloc_Count <= Munge_Count <= 297 * Buf_Write_Count <= Buf_Write_Alloc_Count <= 298 * (Buf_Read_Count + prealloc_bufsz) 299 * 300 * (Those aren't the actual members, apart from prealloc_bufsz.) When the 301 * buffer is reset, those _Count values start at 0 and only increase in value, 302 * maintaining the above inequalities until the next time the buffer is 303 * reset. The buffer is divided into the following regions by the inequalities: 304 * 305 * [0, Buf_Read_Count): 306 * old region no longer accessible 307 * 308 * [Buf_Read_Count, Buf_Read_Alloc_Count): 309 * filled and munged region allocated for reading but not yet read 310 * 311 * [Buf_Read_Alloc_Count, Munge_Count): 312 * filled and munged region not yet allocated for reading 313 * 314 * [Munge_Count, Buf_Write_Count): 315 * filled region not yet munged 316 * 317 * [Buf_Write_Count, Buf_Write_Alloc_Count): 318 * unfilled region allocated for writing but not yet written 319 * 320 * [Buf_Write_Alloc_Count, Buf_Read_Count + prealloc_bufsz): 321 * unfilled region not yet allocated for writing 322 * 323 * [Buf_Read_Count + prealloc_bufsz, infinity): 324 * unfilled region not yet accessible 325 * 326 * Data needs to be written into the buffer before it can be read out, 327 * and may need to be converted (or "munged") between the two 328 * operations. Extra unfilled buffer space may need to allocated for 329 * writing (advancing Buf_Write_Alloc_Count) before new data is written. 330 * After writing new data, the newly filled space needs to be released 331 * (advancing Buf_Write_Count). This also results in the new data being 332 * "munged" (advancing Munge_Count). Before data is read out of the 333 * buffer, extra space may need to be allocated for reading (advancing 334 * Buf_Read_Alloc_Count). After the data has been read out, the space 335 * needs to be released (advancing Buf_Read_Count). 336 * 337 * The actual members, buf_read_count, buf_read_alloc_count, 338 * munge_count, buf_write_count, and buf_write_alloc_count take the 339 * value of the corresponding capitalized _Count values modulo 2^32 340 * (UINT_MAX+1). Subtracting a "higher" _count value from a "lower" 341 * _count value gives the same answer as subtracting a "higher" _Count 342 * value from a lower _Count value because prealloc_bufsz < UINT_MAX+1. 343 * The modulo operation is done implicitly. 344 * 345 * The buf_read_ptr, munge_ptr, and buf_write_ptr members take the value 346 * of the corresponding capitalized _Count values modulo prealloc_bufsz. 347 * These correspond to byte indices in the physical buffer. The modulo 348 * operation is done by subtracting prealloc_bufsz when the value 349 * exceeds prealloc_bufsz (assuming prealloc_bufsz plus the increment is 350 * less than or equal to UINT_MAX). 351 */ 352struct comedi_async { 353 void *prealloc_buf; 354 unsigned int prealloc_bufsz; 355 struct comedi_buf_map *buf_map; 356 unsigned int max_bufsize; 357 unsigned int buf_write_count; 358 unsigned int buf_write_alloc_count; 359 unsigned int buf_read_count; 360 unsigned int buf_read_alloc_count; 361 unsigned int buf_write_ptr; 362 unsigned int buf_read_ptr; 363 unsigned int cur_chan; 364 unsigned int scans_done; 365 unsigned int scan_progress; 366 unsigned int munge_chan; 367 unsigned int munge_count; 368 unsigned int munge_ptr; 369 unsigned int events; 370 struct comedi_cmd cmd; 371 wait_queue_head_t wait_head; 372 unsigned int cb_mask; 373 int (*inttrig)(struct comedi_device *dev, struct comedi_subdevice *s, 374 unsigned int x); 375}; 376 377/** 378 * enum comedi_cb - &struct comedi_async callback "events" 379 * @COMEDI_CB_EOS: end-of-scan 380 * @COMEDI_CB_EOA: end-of-acquisition/output 381 * @COMEDI_CB_BLOCK: data has arrived, wakes up read() / write() 382 * @COMEDI_CB_EOBUF: DEPRECATED: end of buffer 383 * @COMEDI_CB_ERROR: card error during acquisition 384 * @COMEDI_CB_OVERFLOW: buffer overflow/underflow 385 * @COMEDI_CB_ERROR_MASK: events that indicate an error has occurred 386 * @COMEDI_CB_CANCEL_MASK: events that will cancel an async command 387 */ 388enum comedi_cb { 389 COMEDI_CB_EOS = BIT(0), 390 COMEDI_CB_EOA = BIT(1), 391 COMEDI_CB_BLOCK = BIT(2), 392 COMEDI_CB_EOBUF = BIT(3), 393 COMEDI_CB_ERROR = BIT(4), 394 COMEDI_CB_OVERFLOW = BIT(5), 395 /* masks */ 396 COMEDI_CB_ERROR_MASK = (COMEDI_CB_ERROR | COMEDI_CB_OVERFLOW), 397 COMEDI_CB_CANCEL_MASK = (COMEDI_CB_EOA | COMEDI_CB_ERROR_MASK) 398}; 399 400/** 401 * struct comedi_driver - COMEDI driver registration 402 * @driver_name: Name of driver. 403 * @module: Owning module. 404 * @attach: The optional "attach" handler for manually configured COMEDI 405 * devices. 406 * @detach: The "detach" handler for deconfiguring COMEDI devices. 407 * @auto_attach: The optional "auto_attach" handler for automatically 408 * configured COMEDI devices. 409 * @num_names: Optional number of "board names" supported. 410 * @board_name: Optional pointer to a pointer to a board name. The pointer 411 * to a board name is embedded in an element of a driver-defined array 412 * of static, read-only board type information. 413 * @offset: Optional size of each element of the driver-defined array of 414 * static, read-only board type information, i.e. the offset between each 415 * pointer to a board name. 416 * 417 * This is used with comedi_driver_register() and comedi_driver_unregister() to 418 * register and unregister a low-level COMEDI driver with the COMEDI core. 419 * 420 * If @num_names is non-zero, @board_name should be non-NULL, and @offset 421 * should be at least sizeof(*board_name). These are used by the handler for 422 * the %COMEDI_DEVCONFIG ioctl to match a hardware device and its driver by 423 * board name. If @num_names is zero, the %COMEDI_DEVCONFIG ioctl matches a 424 * hardware device and its driver by driver name. This is only useful if the 425 * @attach handler is set. If @num_names is non-zero, the driver's @attach 426 * handler will be called with the COMEDI device structure's board_ptr member 427 * pointing to the matched pointer to a board name within the driver's private 428 * array of static, read-only board type information. 429 */ 430struct comedi_driver { 431 /* private: */ 432 struct comedi_driver *next; /* Next in list of COMEDI drivers. */ 433 /* public: */ 434 const char *driver_name; 435 struct module *module; 436 int (*attach)(struct comedi_device *, struct comedi_devconfig *); 437 void (*detach)(struct comedi_device *); 438 int (*auto_attach)(struct comedi_device *, unsigned long); 439 unsigned int num_names; 440 const char *const *board_name; 441 int offset; 442}; 443 444/** 445 * struct comedi_device - Working data for a COMEDI device 446 * @use_count: Number of open file objects. 447 * @driver: Low-level COMEDI driver attached to this COMEDI device. 448 * @pacer: Optional pointer to a dynamically allocated acquisition pacer 449 * control. It is freed automatically after the COMEDI device is 450 * detached from the low-level driver. 451 * @private: Optional pointer to private data allocated by the low-level 452 * driver. It is freed automatically after the COMEDI device is 453 * detached from the low-level driver. 454 * @class_dev: Sysfs comediX device. 455 * @minor: Minor device number of COMEDI char device (0-47). 456 * @detach_count: Counter incremented every time the COMEDI device is detached. 457 * Used for checking a previous attachment is still valid. 458 * @hw_dev: Optional pointer to the low-level hardware &struct device. It is 459 * required for automatically configured COMEDI devices and optional for 460 * COMEDI devices configured by the %COMEDI_DEVCONFIG ioctl, although 461 * the bus-specific COMEDI functions only work if it is set correctly. 462 * It is also passed to dma_alloc_coherent() for COMEDI subdevices that 463 * have their 'async_dma_dir' member set to something other than 464 * %DMA_NONE. 465 * @board_name: Pointer to a COMEDI board name or a COMEDI driver name. When 466 * the low-level driver's "attach" handler is called by the handler for 467 * the %COMEDI_DEVCONFIG ioctl, it either points to a matched board name 468 * string if the 'num_names' member of the &struct comedi_driver is 469 * non-zero, otherwise it points to the low-level driver name string. 470 * When the low-lever driver's "auto_attach" handler is called for an 471 * automatically configured COMEDI device, it points to the low-level 472 * driver name string. The low-level driver is free to change it in its 473 * "attach" or "auto_attach" handler if it wishes. 474 * @board_ptr: Optional pointer to private, read-only board type information in 475 * the low-level driver. If the 'num_names' member of the &struct 476 * comedi_driver is non-zero, the handler for the %COMEDI_DEVCONFIG ioctl 477 * will point it to a pointer to a matched board name string within the 478 * driver's private array of static, read-only board type information when 479 * calling the driver's "attach" handler. The low-level driver is free to 480 * change it. 481 * @attached: Flag indicating that the COMEDI device is attached to a low-level 482 * driver. 483 * @ioenabled: Flag used to indicate that a PCI device has been enabled and 484 * its regions requested. 485 * @spinlock: Generic spin-lock for use by the low-level driver. 486 * @mutex: Generic mutex for use by the COMEDI core module. 487 * @attach_lock: &struct rw_semaphore used to guard against the COMEDI device 488 * being detached while an operation is in progress. The down_write() 489 * operation is only allowed while @mutex is held and is used when 490 * changing @attached and @detach_count and calling the low-level driver's 491 * "detach" handler. The down_read() operation is generally used without 492 * holding @mutex. 493 * @refcount: &struct kref reference counter for freeing COMEDI device. 494 * @n_subdevices: Number of COMEDI subdevices allocated by the low-level 495 * driver for this device. 496 * @subdevices: Dynamically allocated array of COMEDI subdevices. 497 * @mmio: Optional pointer to a remapped MMIO region set by the low-level 498 * driver. 499 * @iobase: Optional base of an I/O port region requested by the low-level 500 * driver. 501 * @iolen: Length of I/O port region requested at @iobase. 502 * @irq: Optional IRQ number requested by the low-level driver. 503 * @read_subdev: Optional pointer to a default COMEDI subdevice operated on by 504 * the read() file operation. Set by the low-level driver. 505 * @write_subdev: Optional pointer to a default COMEDI subdevice operated on by 506 * the write() file operation. Set by the low-level driver. 507 * @async_queue: Storage for fasync_helper(). 508 * @open: Optional pointer to a function set by the low-level driver to be 509 * called when @use_count changes from 0 to 1. 510 * @close: Optional pointer to a function set by the low-level driver to be 511 * called when @use_count changed from 1 to 0. 512 * 513 * This is the main control data structure for a COMEDI device (as far as the 514 * COMEDI core is concerned). There are two groups of COMEDI devices - 515 * "legacy" devices that are configured by the handler for the 516 * %COMEDI_DEVCONFIG ioctl, and automatically configured devices resulting 517 * from a call to comedi_auto_config() as a result of a bus driver probe in 518 * a low-level COMEDI driver. The "legacy" COMEDI devices are allocated 519 * during module initialization if the "comedi_num_legacy_minors" module 520 * parameter is non-zero and use minor device numbers from 0 to 521 * comedi_num_legacy_minors minus one. The automatically configured COMEDI 522 * devices are allocated on demand and use minor device numbers from 523 * comedi_num_legacy_minors to 47. 524 */ 525struct comedi_device { 526 int use_count; 527 struct comedi_driver *driver; 528 struct comedi_8254 *pacer; 529 void *private; 530 531 struct device *class_dev; 532 int minor; 533 unsigned int detach_count; 534 struct device *hw_dev; 535 536 const char *board_name; 537 const void *board_ptr; 538 bool attached:1; 539 bool ioenabled:1; 540 spinlock_t spinlock; /* generic spin-lock for low-level driver */ 541 struct mutex mutex; /* generic mutex for COMEDI core */ 542 struct rw_semaphore attach_lock; 543 struct kref refcount; 544 545 int n_subdevices; 546 struct comedi_subdevice *subdevices; 547 548 /* dumb */ 549 void __iomem *mmio; 550 unsigned long iobase; 551 unsigned long iolen; 552 unsigned int irq; 553 554 struct comedi_subdevice *read_subdev; 555 struct comedi_subdevice *write_subdev; 556 557 struct fasync_struct *async_queue; 558 559 int (*open)(struct comedi_device *dev); 560 void (*close)(struct comedi_device *dev); 561}; 562 563/* 564 * function prototypes 565 */ 566 567void comedi_event(struct comedi_device *dev, struct comedi_subdevice *s); 568 569struct comedi_device *comedi_dev_get_from_minor(unsigned minor); 570int comedi_dev_put(struct comedi_device *dev); 571 572bool comedi_is_subdevice_running(struct comedi_subdevice *s); 573 574void *comedi_alloc_spriv(struct comedi_subdevice *s, size_t size); 575void comedi_set_spriv_auto_free(struct comedi_subdevice *s); 576 577int comedi_check_chanlist(struct comedi_subdevice *s, 578 int n, 579 unsigned int *chanlist); 580 581/* range stuff */ 582 583#define RANGE(a, b) {(a) * 1e6, (b) * 1e6, 0} 584#define RANGE_ext(a, b) {(a) * 1e6, (b) * 1e6, RF_EXTERNAL} 585#define RANGE_mA(a, b) {(a) * 1e6, (b) * 1e6, UNIT_mA} 586#define RANGE_unitless(a, b) {(a) * 1e6, (b) * 1e6, 0} 587#define BIP_RANGE(a) {-(a) * 1e6, (a) * 1e6, 0} 588#define UNI_RANGE(a) {0, (a) * 1e6, 0} 589 590extern const struct comedi_lrange range_bipolar10; 591extern const struct comedi_lrange range_bipolar5; 592extern const struct comedi_lrange range_bipolar2_5; 593extern const struct comedi_lrange range_unipolar10; 594extern const struct comedi_lrange range_unipolar5; 595extern const struct comedi_lrange range_unipolar2_5; 596extern const struct comedi_lrange range_0_20mA; 597extern const struct comedi_lrange range_4_20mA; 598extern const struct comedi_lrange range_0_32mA; 599extern const struct comedi_lrange range_unknown; 600 601#define range_digital range_unipolar5 602 603#if __GNUC__ >= 3 604#define GCC_ZERO_LENGTH_ARRAY 605#else 606#define GCC_ZERO_LENGTH_ARRAY 0 607#endif 608 609/** 610 * struct comedi_lrange - Describes a COMEDI range table 611 * @length: Number of entries in the range table. 612 * @range: Array of &struct comedi_krange, one for each range. 613 * 614 * Each element of @range[] describes the minimum and maximum physical range 615 * range and the type of units. Typically, the type of unit is %UNIT_volt 616 * (i.e. volts) and the minimum and maximum are in millionths of a volt. 617 * There may also be a flag that indicates the minimum and maximum are merely 618 * scale factors for an unknown, external reference. 619 */ 620struct comedi_lrange { 621 int length; 622 struct comedi_krange range[GCC_ZERO_LENGTH_ARRAY]; 623}; 624 625/** 626 * comedi_range_is_bipolar() - Test if subdevice range is bipolar 627 * @s: COMEDI subdevice. 628 * @range: Index of range within a range table. 629 * 630 * Tests whether a range is bipolar by checking whether its minimum value 631 * is negative. 632 * 633 * Assumes @range is valid. Does not work for subdevices using a 634 * channel-specific range table list. 635 * 636 * Return: 637 * %true if the range is bipolar. 638 * %false if the range is unipolar. 639 */ 640static inline bool comedi_range_is_bipolar(struct comedi_subdevice *s, 641 unsigned int range) 642{ 643 return s->range_table->range[range].min < 0; 644} 645 646/** 647 * comedi_range_is_unipolar() - Test if subdevice range is unipolar 648 * @s: COMEDI subdevice. 649 * @range: Index of range within a range table. 650 * 651 * Tests whether a range is unipolar by checking whether its minimum value 652 * is at least 0. 653 * 654 * Assumes @range is valid. Does not work for subdevices using a 655 * channel-specific range table list. 656 * 657 * Return: 658 * %true if the range is unipolar. 659 * %false if the range is bipolar. 660 */ 661static inline bool comedi_range_is_unipolar(struct comedi_subdevice *s, 662 unsigned int range) 663{ 664 return s->range_table->range[range].min >= 0; 665} 666 667/** 668 * comedi_range_is_external() - Test if subdevice range is external 669 * @s: COMEDI subdevice. 670 * @range: Index of range within a range table. 671 * 672 * Tests whether a range is externally reference by checking whether its 673 * %RF_EXTERNAL flag is set. 674 * 675 * Assumes @range is valid. Does not work for subdevices using a 676 * channel-specific range table list. 677 * 678 * Return: 679 * %true if the range is external. 680 * %false if the range is internal. 681 */ 682static inline bool comedi_range_is_external(struct comedi_subdevice *s, 683 unsigned int range) 684{ 685 return !!(s->range_table->range[range].flags & RF_EXTERNAL); 686} 687 688/** 689 * comedi_chan_range_is_bipolar() - Test if channel-specific range is bipolar 690 * @s: COMEDI subdevice. 691 * @chan: The channel number. 692 * @range: Index of range within a range table. 693 * 694 * Tests whether a range is bipolar by checking whether its minimum value 695 * is negative. 696 * 697 * Assumes @chan and @range are valid. Only works for subdevices with a 698 * channel-specific range table list. 699 * 700 * Return: 701 * %true if the range is bipolar. 702 * %false if the range is unipolar. 703 */ 704static inline bool comedi_chan_range_is_bipolar(struct comedi_subdevice *s, 705 unsigned int chan, 706 unsigned int range) 707{ 708 return s->range_table_list[chan]->range[range].min < 0; 709} 710 711/** 712 * comedi_chan_range_is_unipolar() - Test if channel-specific range is unipolar 713 * @s: COMEDI subdevice. 714 * @chan: The channel number. 715 * @range: Index of range within a range table. 716 * 717 * Tests whether a range is unipolar by checking whether its minimum value 718 * is at least 0. 719 * 720 * Assumes @chan and @range are valid. Only works for subdevices with a 721 * channel-specific range table list. 722 * 723 * Return: 724 * %true if the range is unipolar. 725 * %false if the range is bipolar. 726 */ 727static inline bool comedi_chan_range_is_unipolar(struct comedi_subdevice *s, 728 unsigned int chan, 729 unsigned int range) 730{ 731 return s->range_table_list[chan]->range[range].min >= 0; 732} 733 734/** 735 * comedi_chan_range_is_external() - Test if channel-specific range is external 736 * @s: COMEDI subdevice. 737 * @chan: The channel number. 738 * @range: Index of range within a range table. 739 * 740 * Tests whether a range is externally reference by checking whether its 741 * %RF_EXTERNAL flag is set. 742 * 743 * Assumes @chan and @range are valid. Only works for subdevices with a 744 * channel-specific range table list. 745 * 746 * Return: 747 * %true if the range is bipolar. 748 * %false if the range is unipolar. 749 */ 750static inline bool comedi_chan_range_is_external(struct comedi_subdevice *s, 751 unsigned int chan, 752 unsigned int range) 753{ 754 return !!(s->range_table_list[chan]->range[range].flags & RF_EXTERNAL); 755} 756 757/** 758 * comedi_offset_munge() - Convert between offset binary and 2's complement 759 * @s: COMEDI subdevice. 760 * @val: Value to be converted. 761 * 762 * Toggles the highest bit of a sample value to toggle between offset binary 763 * and 2's complement. Assumes that @s->maxdata is a power of 2 minus 1. 764 * 765 * Return: The converted value. 766 */ 767static inline unsigned int comedi_offset_munge(struct comedi_subdevice *s, 768 unsigned int val) 769{ 770 return val ^ s->maxdata ^ (s->maxdata >> 1); 771} 772 773/** 774 * comedi_bytes_per_sample() - Determine subdevice sample size 775 * @s: COMEDI subdevice. 776 * 777 * The sample size will be 4 (sizeof int) or 2 (sizeof short) depending on 778 * whether the %SDF_LSAMPL subdevice flag is set or not. 779 * 780 * Return: The subdevice sample size. 781 */ 782static inline unsigned int comedi_bytes_per_sample(struct comedi_subdevice *s) 783{ 784 return s->subdev_flags & SDF_LSAMPL ? sizeof(int) : sizeof(short); 785} 786 787/** 788 * comedi_sample_shift() - Determine log2 of subdevice sample size 789 * @s: COMEDI subdevice. 790 * 791 * The sample size will be 4 (sizeof int) or 2 (sizeof short) depending on 792 * whether the %SDF_LSAMPL subdevice flag is set or not. The log2 of the 793 * sample size will be 2 or 1 and can be used as the right operand of a 794 * bit-shift operator to multiply or divide something by the sample size. 795 * 796 * Return: log2 of the subdevice sample size. 797 */ 798static inline unsigned int comedi_sample_shift(struct comedi_subdevice *s) 799{ 800 return s->subdev_flags & SDF_LSAMPL ? 2 : 1; 801} 802 803/** 804 * comedi_bytes_to_samples() - Convert a number of bytes to a number of samples 805 * @s: COMEDI subdevice. 806 * @nbytes: Number of bytes 807 * 808 * Return: The number of bytes divided by the subdevice sample size. 809 */ 810static inline unsigned int comedi_bytes_to_samples(struct comedi_subdevice *s, 811 unsigned int nbytes) 812{ 813 return nbytes >> comedi_sample_shift(s); 814} 815 816/** 817 * comedi_samples_to_bytes() - Convert a number of samples to a number of bytes 818 * @s: COMEDI subdevice. 819 * @nsamples: Number of samples. 820 * 821 * Return: The number of samples multiplied by the subdevice sample size. 822 * (Does not check for arithmetic overflow.) 823 */ 824static inline unsigned int comedi_samples_to_bytes(struct comedi_subdevice *s, 825 unsigned int nsamples) 826{ 827 return nsamples << comedi_sample_shift(s); 828} 829 830/** 831 * comedi_check_trigger_src() - Trivially validate a comedi_cmd trigger source 832 * @src: Pointer to the trigger source to validate. 833 * @flags: Bitmask of valid %TRIG_* for the trigger. 834 * 835 * This is used in "step 1" of the do_cmdtest functions of comedi drivers 836 * to validate the comedi_cmd triggers. The mask of the @src against the 837 * @flags allows the userspace comedilib to pass all the comedi_cmd 838 * triggers as %TRIG_ANY and get back a bitmask of the valid trigger sources. 839 * 840 * Return: 841 * 0 if trigger sources in *@src are all supported. 842 * -EINVAL if any trigger source in *@src is unsupported. 843 */ 844static inline int comedi_check_trigger_src(unsigned int *src, 845 unsigned int flags) 846{ 847 unsigned int orig_src = *src; 848 849 *src = orig_src & flags; 850 if (*src == TRIG_INVALID || *src != orig_src) 851 return -EINVAL; 852 return 0; 853} 854 855/** 856 * comedi_check_trigger_is_unique() - Make sure a trigger source is unique 857 * @src: The trigger source to check. 858 * 859 * Return: 860 * 0 if no more than one trigger source is set. 861 * -EINVAL if more than one trigger source is set. 862 */ 863static inline int comedi_check_trigger_is_unique(unsigned int src) 864{ 865 /* this test is true if more than one _src bit is set */ 866 if ((src & (src - 1)) != 0) 867 return -EINVAL; 868 return 0; 869} 870 871/** 872 * comedi_check_trigger_arg_is() - Trivially validate a trigger argument 873 * @arg: Pointer to the trigger arg to validate. 874 * @val: The value the argument should be. 875 * 876 * Forces *@arg to be @val. 877 * 878 * Return: 879 * 0 if *@arg was already @val. 880 * -EINVAL if *@arg differed from @val. 881 */ 882static inline int comedi_check_trigger_arg_is(unsigned int *arg, 883 unsigned int val) 884{ 885 if (*arg != val) { 886 *arg = val; 887 return -EINVAL; 888 } 889 return 0; 890} 891 892/** 893 * comedi_check_trigger_arg_min() - Trivially validate a trigger argument min 894 * @arg: Pointer to the trigger arg to validate. 895 * @val: The minimum value the argument should be. 896 * 897 * Forces *@arg to be at least @val, setting it to @val if necessary. 898 * 899 * Return: 900 * 0 if *@arg was already at least @val. 901 * -EINVAL if *@arg was less than @val. 902 */ 903static inline int comedi_check_trigger_arg_min(unsigned int *arg, 904 unsigned int val) 905{ 906 if (*arg < val) { 907 *arg = val; 908 return -EINVAL; 909 } 910 return 0; 911} 912 913/** 914 * comedi_check_trigger_arg_max() - Trivially validate a trigger argument max 915 * @arg: Pointer to the trigger arg to validate. 916 * @val: The maximum value the argument should be. 917 * 918 * Forces *@arg to be no more than @val, setting it to @val if necessary. 919 * 920 * Return: 921 * 0 if*@arg was already no more than @val. 922 * -EINVAL if *@arg was greater than @val. 923 */ 924static inline int comedi_check_trigger_arg_max(unsigned int *arg, 925 unsigned int val) 926{ 927 if (*arg > val) { 928 *arg = val; 929 return -EINVAL; 930 } 931 return 0; 932} 933 934/* 935 * Must set dev->hw_dev if you wish to dma directly into comedi's buffer. 936 * Also useful for retrieving a previously configured hardware device of 937 * known bus type. Set automatically for auto-configured devices. 938 * Automatically set to NULL when detaching hardware device. 939 */ 940int comedi_set_hw_dev(struct comedi_device *dev, struct device *hw_dev); 941 942/** 943 * comedi_buf_n_bytes_ready - Determine amount of unread data in buffer 944 * @s: COMEDI subdevice. 945 * 946 * Determines the number of bytes of unread data in the asynchronous 947 * acquisition data buffer for a subdevice. The data in question might not 948 * have been fully "munged" yet. 949 * 950 * Returns: The amount of unread data in bytes. 951 */ 952static inline unsigned int comedi_buf_n_bytes_ready(struct comedi_subdevice *s) 953{ 954 return s->async->buf_write_count - s->async->buf_read_count; 955} 956 957unsigned int comedi_buf_write_alloc(struct comedi_subdevice *s, unsigned int n); 958unsigned int comedi_buf_write_free(struct comedi_subdevice *s, unsigned int n); 959 960unsigned int comedi_buf_read_n_available(struct comedi_subdevice *s); 961unsigned int comedi_buf_read_alloc(struct comedi_subdevice *s, unsigned int n); 962unsigned int comedi_buf_read_free(struct comedi_subdevice *s, unsigned int n); 963 964unsigned int comedi_buf_write_samples(struct comedi_subdevice *s, 965 const void *data, unsigned int nsamples); 966unsigned int comedi_buf_read_samples(struct comedi_subdevice *s, 967 void *data, unsigned int nsamples); 968 969/* drivers.c - general comedi driver functions */ 970 971#define COMEDI_TIMEOUT_MS 1000 972 973int comedi_timeout(struct comedi_device *, struct comedi_subdevice *, 974 struct comedi_insn *, 975 int (*cb)(struct comedi_device *, struct comedi_subdevice *, 976 struct comedi_insn *, unsigned long context), 977 unsigned long context); 978 979unsigned int comedi_handle_events(struct comedi_device *dev, 980 struct comedi_subdevice *s); 981 982int comedi_dio_insn_config(struct comedi_device *, struct comedi_subdevice *, 983 struct comedi_insn *, unsigned int *data, 984 unsigned int mask); 985unsigned int comedi_dio_update_state(struct comedi_subdevice *, 986 unsigned int *data); 987unsigned int comedi_bytes_per_scan(struct comedi_subdevice *s); 988unsigned int comedi_nscans_left(struct comedi_subdevice *s, 989 unsigned int nscans); 990unsigned int comedi_nsamples_left(struct comedi_subdevice *s, 991 unsigned int nsamples); 992void comedi_inc_scan_progress(struct comedi_subdevice *s, 993 unsigned int num_bytes); 994 995void *comedi_alloc_devpriv(struct comedi_device *, size_t); 996int comedi_alloc_subdevices(struct comedi_device *, int); 997int comedi_alloc_subdev_readback(struct comedi_subdevice *); 998 999int comedi_readback_insn_read(struct comedi_device *, struct comedi_subdevice *, 1000 struct comedi_insn *, unsigned int *data); 1001 1002int comedi_load_firmware(struct comedi_device *, struct device *, 1003 const char *name, 1004 int (*cb)(struct comedi_device *, 1005 const u8 *data, size_t size, 1006 unsigned long context), 1007 unsigned long context); 1008 1009int __comedi_request_region(struct comedi_device *, 1010 unsigned long start, unsigned long len); 1011int comedi_request_region(struct comedi_device *, 1012 unsigned long start, unsigned long len); 1013void comedi_legacy_detach(struct comedi_device *); 1014 1015int comedi_auto_config(struct device *, struct comedi_driver *, 1016 unsigned long context); 1017void comedi_auto_unconfig(struct device *); 1018 1019int comedi_driver_register(struct comedi_driver *); 1020void comedi_driver_unregister(struct comedi_driver *); 1021 1022/** 1023 * module_comedi_driver() - Helper macro for registering a comedi driver 1024 * @__comedi_driver: comedi_driver struct 1025 * 1026 * Helper macro for comedi drivers which do not do anything special in module 1027 * init/exit. This eliminates a lot of boilerplate. Each module may only use 1028 * this macro once, and calling it replaces module_init() and module_exit(). 1029 */ 1030#define module_comedi_driver(__comedi_driver) \ 1031 module_driver(__comedi_driver, comedi_driver_register, \ 1032 comedi_driver_unregister) 1033 1034#endif /* _COMEDIDEV_H */ 1035