3 Skeleton code for a Comedi driver
5 COMEDI - Linux Control and Measurement Device Interface
6 Copyright (C) 2000 David A. Schleef <ds@schleef.org>
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.
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.
20 Description: Skeleton driver, an example for driver writers
23 Updated: Mon, 18 Mar 2002 15:34:01 -0800
26 This driver is a documented example on how Comedi drivers are
29 Configuration Options:
34 * The previous block comment is used to automatically generate
35 * documentation in Comedi and Comedilib. The fields:
37 * Driver: the name of the driver
38 * Description: a short phrase describing the driver. Don't list boards.
39 * Devices: a full list of the boards that attempt to be supported by
40 * the driver. Format is "(manufacturer) board name [comedi name]",
41 * where comedi_name is the name that is used to configure the board.
42 * See the comment near board_name: in the struct comedi_driver structure
43 * below. If (manufacturer) or [comedi name] is missing, the previous
46 * Updated: date when the _documentation_ was last updated. Use 'date -R'
47 * to get a value for this.
48 * Status: a one-word description of the status. Valid values are:
49 * works - driver works correctly on most boards supported, and
51 * unknown - unknown. Usually put there by ds.
52 * experimental - may not work in any particular release. Author
53 * probably wants assistance testing it.
54 * bitrotten - driver has not been update in a long time, probably
55 * doesn't work, and probably is missing support for significant
56 * Comedi interface features.
57 * untested - author probably wrote it "blind", and is believed to
58 * work, but no confirmation.
60 * These headers should be followed by a blank line, and any comments
61 * you wish to say about the driver. The comment area is the place
62 * to put any known bugs, limitations, unsupported features, supported
63 * command triggers, whether or not commands are supported on particular
66 * Somewhere in the comment should be information about configuration
67 * options that are used with comedi_config.
70 #include <linux/module.h>
71 #include <linux/pci.h>
73 #include "../comedidev.h"
75 #include "comedi_fc.h"
77 /* Imaginary registers for the imaginary board */
81 #define SKEL_START_AI_CONV 0
82 #define SKEL_AI_READ 0
85 * Board descriptions for two imaginary boards. Describing the
86 * boards in this way is optional, and completely driver-dependent.
87 * Some drivers use arrays such as this, other do not.
101 static const struct skel_board skel_boards
[] = {
115 /* this structure is for data unique to this hardware driver. If
116 several hardware drivers keep similar information in this structure,
117 feel free to suggest moving the variable to the struct comedi_device struct.
119 struct skel_private
{
123 /* Used for AO readback */
124 unsigned int ao_readback
[2];
127 /* This function doesn't require a particular form, this is just
128 * what happens to be used in some of the drivers. It should
129 * convert ns nanoseconds to a counter value suitable for programming
130 * the device. Also, it should adjust ns so that it cooresponds to
131 * the actual time that the device will use. */
132 static int skel_ns_to_timer(unsigned int *ns
, int round
)
135 /* if your timing is done through two cascaded timers, the
136 * i8253_cascade_ns_to_timer() function in 8253.h can be
137 * very helpful. There are also i8254_load() and i8254_mm_load()
138 * which can be used to load values into the ubiquitous 8254 counters
145 * This function doesn't require a particular form, this is just
146 * what happens to be used in some of the drivers. The comedi_timeout()
147 * helper uses this callback to check for the end-of-conversion while
148 * waiting for up to 1 second. This function should return 0 when the
149 * conversion is finished and -EBUSY to keep waiting. Any other errno
150 * will terminate comedi_timeout() and return that errno to the caller.
151 * If the timeout occurs, comedi_timeout() will return -ETIMEDOUT.
153 static int skel_ai_eoc(struct comedi_device
*dev
,
154 struct comedi_subdevice
*s
,
155 struct comedi_insn
*insn
,
156 unsigned long context
)
160 /* status = inb(dev->iobase + SKEL_STATUS); */
168 * "instructions" read/write data in "one-shot" or "software-triggered"
171 static int skel_ai_rinsn(struct comedi_device
*dev
, struct comedi_subdevice
*s
,
172 struct comedi_insn
*insn
, unsigned int *data
)
174 const struct skel_board
*thisboard
= comedi_board(dev
);
179 /* a typical programming sequence */
181 /* write channel to multiplexer */
182 /* outw(chan,dev->iobase + SKEL_MUX); */
184 /* don't wait for mux to settle */
186 /* convert n samples */
187 for (n
= 0; n
< insn
->n
; n
++) {
188 /* trigger conversion */
189 /* outw(0,dev->iobase + SKEL_CONVERT); */
191 /* wait for conversion to end */
192 ret
= comedi_timeout(dev
, s
, insn
, skel_ai_eoc
, 0);
197 /* d = inw(dev->iobase + SKEL_AI_DATA); */
200 /* mangle the data as necessary */
201 d
^= 1 << (thisboard
->ai_bits
- 1);
206 /* return the number of samples read/written */
211 * cmdtest tests a particular command to see if it is valid.
212 * Using the cmdtest ioctl, a user can create a valid cmd
213 * and then have it executes by the cmd ioctl.
215 * cmdtest returns 1,2,3,4 or 0, depending on which tests
216 * the command passes.
218 static int skel_ai_cmdtest(struct comedi_device
*dev
,
219 struct comedi_subdevice
*s
,
220 struct comedi_cmd
*cmd
)
225 /* Step 1 : check if triggers are trivially valid */
227 err
|= cfc_check_trigger_src(&cmd
->start_src
, TRIG_NOW
);
228 err
|= cfc_check_trigger_src(&cmd
->scan_begin_src
,
229 TRIG_TIMER
| TRIG_EXT
);
230 err
|= cfc_check_trigger_src(&cmd
->convert_src
, TRIG_TIMER
| TRIG_EXT
);
231 err
|= cfc_check_trigger_src(&cmd
->scan_end_src
, TRIG_COUNT
);
232 err
|= cfc_check_trigger_src(&cmd
->stop_src
, TRIG_COUNT
| TRIG_NONE
);
237 /* Step 2a : make sure trigger sources are unique */
239 err
|= cfc_check_trigger_is_unique(cmd
->scan_begin_src
);
240 err
|= cfc_check_trigger_is_unique(cmd
->convert_src
);
241 err
|= cfc_check_trigger_is_unique(cmd
->stop_src
);
243 /* Step 2b : and mutually compatible */
248 /* Step 3: check if arguments are trivially valid */
250 err
|= cfc_check_trigger_arg_is(&cmd
->start_arg
, 0);
252 #define MAX_SPEED 10000 /* in nanoseconds */
253 #define MIN_SPEED 1000000000 /* in nanoseconds */
255 if (cmd
->scan_begin_src
== TRIG_TIMER
) {
256 err
|= cfc_check_trigger_arg_min(&cmd
->scan_begin_arg
,
258 err
|= cfc_check_trigger_arg_max(&cmd
->scan_begin_arg
,
261 /* external trigger */
262 /* should be level/edge, hi/lo specification here */
263 /* should specify multiple external triggers */
264 err
|= cfc_check_trigger_arg_max(&cmd
->scan_begin_arg
, 9);
267 if (cmd
->convert_src
== TRIG_TIMER
) {
268 err
|= cfc_check_trigger_arg_min(&cmd
->convert_arg
, MAX_SPEED
);
269 err
|= cfc_check_trigger_arg_max(&cmd
->convert_arg
, MIN_SPEED
);
271 /* external trigger */
273 err
|= cfc_check_trigger_arg_max(&cmd
->scan_begin_arg
, 9);
276 err
|= cfc_check_trigger_arg_is(&cmd
->scan_end_arg
, cmd
->chanlist_len
);
278 if (cmd
->stop_src
== TRIG_COUNT
)
279 err
|= cfc_check_trigger_arg_max(&cmd
->stop_arg
, 0x00ffffff);
281 err
|= cfc_check_trigger_arg_is(&cmd
->stop_arg
, 0);
286 /* step 4: fix up any arguments */
288 if (cmd
->scan_begin_src
== TRIG_TIMER
) {
289 arg
= cmd
->scan_begin_arg
;
290 skel_ns_to_timer(&arg
, cmd
->flags
& TRIG_ROUND_MASK
);
291 err
|= cfc_check_trigger_arg_is(&cmd
->scan_begin_arg
, arg
);
293 if (cmd
->convert_src
== TRIG_TIMER
) {
294 arg
= cmd
->convert_arg
;
295 skel_ns_to_timer(&arg
, cmd
->flags
& TRIG_ROUND_MASK
);
296 err
|= cfc_check_trigger_arg_is(&cmd
->convert_arg
, arg
);
298 if (cmd
->scan_begin_src
== TRIG_TIMER
) {
299 arg
= cmd
->convert_arg
* cmd
->scan_end_arg
;
300 err
|= cfc_check_trigger_arg_min(&cmd
->scan_begin_arg
,
311 static int skel_ao_winsn(struct comedi_device
*dev
, struct comedi_subdevice
*s
,
312 struct comedi_insn
*insn
, unsigned int *data
)
314 struct skel_private
*devpriv
= dev
->private;
316 int chan
= CR_CHAN(insn
->chanspec
);
318 /* Writing a list of values to an AO channel is probably not
319 * very useful, but that's how the interface is defined. */
320 for (i
= 0; i
< insn
->n
; i
++) {
321 /* a typical programming sequence */
322 /* outw(data[i],dev->iobase + SKEL_DA0 + chan); */
323 devpriv
->ao_readback
[chan
] = data
[i
];
326 /* return the number of samples read/written */
330 /* AO subdevices should have a read insn as well as a write insn.
331 * Usually this means copying a value stored in devpriv. */
332 static int skel_ao_rinsn(struct comedi_device
*dev
, struct comedi_subdevice
*s
,
333 struct comedi_insn
*insn
, unsigned int *data
)
335 struct skel_private
*devpriv
= dev
->private;
337 int chan
= CR_CHAN(insn
->chanspec
);
339 for (i
= 0; i
< insn
->n
; i
++)
340 data
[i
] = devpriv
->ao_readback
[chan
];
346 * DIO devices are slightly special. Although it is possible to
347 * implement the insn_read/insn_write interface, it is much more
348 * useful to applications if you implement the insn_bits interface.
349 * This allows packed reading/writing of the DIO channels. The
350 * comedi core can convert between insn_bits and insn_read/write.
352 static int skel_dio_insn_bits(struct comedi_device
*dev
,
353 struct comedi_subdevice
*s
,
354 struct comedi_insn
*insn
,
358 * The insn data is a mask in data[0] and the new data
359 * in data[1], each channel cooresponding to a bit.
361 * The core provided comedi_dio_update_state() function can
362 * be used to handle the internal state update to DIO subdevices
363 * with <= 32 channels. This function will return '0' if the
364 * state does not change or the mask of the channels that need
367 if (comedi_dio_update_state(s
, data
)) {
368 /* Write out the new digital output lines */
369 /* outw(s->state, dev->iobase + SKEL_DIO); */
373 * On return, data[1] contains the value of the digital
374 * input and output lines.
376 /* data[1] = inw(dev->iobase + SKEL_DIO); */
379 * Or we could just return the software copy of the output
380 * values if it was a purely digital output subdevice.
382 /* data[1] = s->state; */
387 static int skel_dio_insn_config(struct comedi_device
*dev
,
388 struct comedi_subdevice
*s
,
389 struct comedi_insn
*insn
,
395 * The input or output configuration of each digital line is
396 * configured by special insn_config instructions.
398 * chanspec contains the channel to be changed
399 * data[0] contains the instruction to perform on the channel
401 * Normally the core provided comedi_dio_insn_config() function
402 * can be used to handle the boilerplpate.
404 ret
= comedi_dio_insn_config(dev
, s
, insn
, data
, 0);
408 /* Update the hardware to the new configuration */
409 /* outw(s->io_bits, dev->iobase + SKEL_DIO_CONFIG); */
415 * Handle common part of skel_attach() and skel_auto_attach().
417 static int skel_common_attach(struct comedi_device
*dev
)
419 const struct skel_board
*thisboard
= comedi_board(dev
);
420 struct comedi_subdevice
*s
;
423 ret
= comedi_alloc_subdevices(dev
, 3);
427 s
= &dev
->subdevices
[0];
428 /* dev->read_subdev=s; */
429 /* analog input subdevice */
430 s
->type
= COMEDI_SUBD_AI
;
431 /* we support single-ended (ground) and differential */
432 s
->subdev_flags
= SDF_READABLE
| SDF_GROUND
| SDF_DIFF
;
433 s
->n_chan
= thisboard
->ai_chans
;
434 s
->maxdata
= (1 << thisboard
->ai_bits
) - 1;
435 s
->range_table
= &range_bipolar10
;
436 s
->len_chanlist
= 16; /* This is the maximum chanlist length that
437 the board can handle */
438 s
->insn_read
= skel_ai_rinsn
;
440 * s->subdev_flags |= SDF_CMD_READ;
441 * s->do_cmd = skel_ai_cmd;
443 s
->do_cmdtest
= skel_ai_cmdtest
;
445 s
= &dev
->subdevices
[1];
446 /* analog output subdevice */
447 s
->type
= COMEDI_SUBD_AO
;
448 s
->subdev_flags
= SDF_WRITABLE
;
451 s
->range_table
= &range_bipolar5
;
452 s
->insn_write
= skel_ao_winsn
;
453 s
->insn_read
= skel_ao_rinsn
;
455 s
= &dev
->subdevices
[2];
456 /* digital i/o subdevice */
457 if (thisboard
->have_dio
) {
458 s
->type
= COMEDI_SUBD_DIO
;
459 s
->subdev_flags
= SDF_READABLE
| SDF_WRITABLE
;
462 s
->range_table
= &range_digital
;
463 s
->insn_bits
= skel_dio_insn_bits
;
464 s
->insn_config
= skel_dio_insn_config
;
466 s
->type
= COMEDI_SUBD_UNUSED
;
473 * _attach is called by the Comedi core to configure the driver
474 * for a particular board in response to the COMEDI_DEVCONFIG ioctl for
475 * a matching board or driver name. If you specified a board_name array
476 * in the driver structure, dev->board_ptr contains that address.
478 * Drivers that handle only PCI or USB devices do not usually support
479 * manual attachment of those devices via the COMEDI_DEVCONFIG ioctl, so
480 * those drivers do not have an _attach function; they just have an
481 * _auto_attach function instead. (See skel_auto_attach() for an example
482 * of such a function.)
484 static int skel_attach(struct comedi_device
*dev
, struct comedi_devconfig
*it
)
486 const struct skel_board
*thisboard
;
487 struct skel_private
*devpriv
;
490 * If you can probe the device to determine what device in a series
491 * it is, this is the place to do it. Otherwise, dev->board_ptr
492 * should already be initialized.
494 /* dev->board_ptr = skel_probe(dev, it); */
496 thisboard
= comedi_board(dev
);
499 * The dev->board_name is initialized by the comedi core before
500 * calling the (*attach) function. It can be optionally set by
501 * the driver if additional probing has been done.
503 /* dev->board_name = thisboard->name; */
505 /* Allocate the private data */
506 devpriv
= comedi_alloc_devpriv(dev
, sizeof(*devpriv
));
511 * Supported boards are usually either auto-attached via the
512 * Comedi driver's _auto_attach routine, or manually attached via the
513 * Comedi driver's _attach routine. In most cases, attempts to
514 * manual attach boards that are usually auto-attached should be
515 * rejected by this function.
518 * if (thisboard->bustype == pci_bustype) {
519 * dev_err(dev->class_dev,
520 * "Manual attachment of PCI board '%s' not supported\n",
526 * For ISA boards, get the i/o base address from it->options[],
527 * request the i/o region and set dev->iobase * from it->options[].
528 * If using interrupts, get the IRQ number from it->options[].
532 * Call a common function to handle the remaining things to do for
533 * attaching ISA or PCI boards. (Extra parameters could be added
534 * to pass additional information such as IRQ number.)
536 return skel_common_attach(dev
);
540 * _auto_attach is called via comedi_pci_auto_config() (or
541 * comedi_usb_auto_config(), etc.) to handle devices that can be attached
542 * to the Comedi core automatically without the COMEDI_DEVCONFIG ioctl.
544 * The context parameter is driver dependent.
546 static int skel_auto_attach(struct comedi_device
*dev
,
547 unsigned long context
)
549 struct pci_dev
*pcidev
= comedi_to_pci_dev(dev
);
550 const struct skel_board
*thisboard
= NULL
;
551 struct skel_private
*devpriv
;
554 /* Hack to allow unused code to be optimized out. */
555 if (!IS_ENABLED(CONFIG_COMEDI_PCI_DRIVERS
))
559 * In this example, the _auto_attach is for a PCI device.
561 * The 'context' passed to this function is the id->driver_data
562 * associated with the PCI device found in the id_table during
563 * the modprobe. This 'context' is the index of the entry in
564 * skel_boards[i] that contains the boardinfo for the PCI device.
566 if (context
< ARRAY_SIZE(skel_boards
))
567 thisboard
= &skel_boards
[context
];
572 * Point the struct comedi_device to the matching board info
573 * and set the board name.
575 dev
->board_ptr
= thisboard
;
576 dev
->board_name
= thisboard
->name
;
578 /* Allocate the private data */
579 devpriv
= comedi_alloc_devpriv(dev
, sizeof(*devpriv
));
583 /* Enable the PCI device. */
584 ret
= comedi_pci_enable(dev
);
589 * Record the fact that the PCI device is enabled so that it can
590 * be disabled during _detach().
592 * For this example driver, we assume PCI BAR 0 is the main I/O
593 * region for the board registers and use dev->iobase to hold the
594 * I/O base address and to indicate that the PCI device has been
597 * (For boards with memory-mapped registers, dev->iobase is not
598 * usually needed for register access, so can just be set to 1
599 * to indicate that the PCI device has been enabled.)
601 dev
->iobase
= pci_resource_start(pcidev
, 0);
604 * Call a common function to handle the remaining things to do for
605 * attaching ISA or PCI boards. (Extra parameters could be added
606 * to pass additional information such as IRQ number.)
608 return skel_common_attach(dev
);
612 * _detach is called to deconfigure a device. It should deallocate
614 * This function is also called when _attach() fails, so it should be
615 * careful not to release resources that were not necessarily
616 * allocated by _attach(). dev->private and dev->subdevices are
617 * deallocated automatically by the core.
619 static void skel_detach(struct comedi_device
*dev
)
621 const struct skel_board
*thisboard
= comedi_board(dev
);
622 struct skel_private
*devpriv
= dev
->private;
624 if (!thisboard
|| !devpriv
)
628 * Do common stuff such as freeing IRQ, unmapping remapped memory
629 * regions, etc., being careful to check that the stuff is valid given
630 * that _detach() is called even when _attach() or _auto_attach() return
634 if (IS_ENABLED(CONFIG_COMEDI_PCI_DRIVERS
) /* &&
635 thisboard->bustype == pci_bustype */) {
639 * If PCI device enabled by _auto_attach() (or _attach()),
642 comedi_pci_disable(dev
);
647 * Release the first I/O region requested during the
648 * _attach(). This is safe to call even if the request
649 * failed. If any additional I/O regions are requested
650 * they need to be released by the driver.
652 comedi_legacy_detach(dev
);
657 * The struct comedi_driver structure tells the Comedi core module
658 * which functions to call to configure/deconfigure (attach/detach)
659 * the board, and also about the kernel module that contains
662 static struct comedi_driver skel_driver
= {
663 .driver_name
= "dummy",
664 .module
= THIS_MODULE
,
665 .attach
= skel_attach
,
666 .auto_attach
= skel_auto_attach
,
667 .detach
= skel_detach
,
668 /* It is not necessary to implement the following members if you are
669 * writing a driver for a ISA PnP or PCI card */
670 /* Most drivers will support multiple types of boards by
671 * having an array of board structures. These were defined
672 * in skel_boards[] above. Note that the element 'name'
673 * was first in the structure -- Comedi uses this fact to
674 * extract the name of the board without knowing any details
675 * about the structure except for its length.
676 * When a device is attached (by comedi_config), the name
677 * of the device is given to Comedi, and Comedi tries to
678 * match it by going through the list of board names. If
679 * there is a match, the address of the pointer is put
680 * into dev->board_ptr and driver->attach() is called.
682 * Note that these are not necessary if you can determine
683 * the type of board in software. ISA PnP, PCI, and PCMCIA
684 * devices are such boards.
686 .board_name
= &skel_boards
[0].name
,
687 .offset
= sizeof(struct skel_board
),
688 .num_names
= ARRAY_SIZE(skel_boards
),
691 #ifdef CONFIG_COMEDI_PCI_DRIVERS
693 static int skel_pci_probe(struct pci_dev
*dev
,
694 const struct pci_device_id
*id
)
696 return comedi_pci_auto_config(dev
, &skel_driver
, id
->driver_data
);
700 * Please add your PCI vendor ID to comedidev.h, and it will
701 * be forwarded upstream.
703 #define PCI_VENDOR_ID_SKEL 0xdafe
706 * This is used by modprobe to translate PCI IDs to drivers.
707 * Should only be used for PCI and ISA-PnP devices
709 static const struct pci_device_id skel_pci_table
[] = {
710 { PCI_VDEVICE(SKEL
, 0x0100), BOARD_SKEL100
},
711 { PCI_VDEVICE(SKEL
, 0x0200), BOARD_SKEL200
},
714 MODULE_DEVICE_TABLE(pci
, skel_pci_table
);
716 static struct pci_driver skel_pci_driver
= {
718 .id_table
= skel_pci_table
,
719 .probe
= skel_pci_probe
,
720 .remove
= comedi_pci_auto_unconfig
,
722 module_comedi_pci_driver(skel_driver
, skel_pci_driver
);
724 module_comedi_driver(skel_driver
);
727 MODULE_AUTHOR("Comedi http://www.comedi.org");
728 MODULE_DESCRIPTION("Comedi low-level driver");
729 MODULE_LICENSE("GPL");