]> Pileus Git - ~andy/linux/blob - drivers/staging/comedi/drivers/skel.c
staging: comedi: remove inline alloc_private()
[~andy/linux] / drivers / staging / comedi / drivers / skel.c
1 /*
2     comedi/drivers/skel.c
3     Skeleton code for a Comedi driver
4
5     COMEDI - Linux Control and Measurement Device Interface
6     Copyright (C) 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     You should have received a copy of the GNU General Public License
19     along with this program; if not, write to the Free Software
20     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
21
22 */
23 /*
24 Driver: skel
25 Description: Skeleton driver, an example for driver writers
26 Devices:
27 Author: ds
28 Updated: Mon, 18 Mar 2002 15:34:01 -0800
29 Status: works
30
31 This driver is a documented example on how Comedi drivers are
32 written.
33
34 Configuration Options:
35   none
36 */
37
38 /*
39  * The previous block comment is used to automatically generate
40  * documentation in Comedi and Comedilib.  The fields:
41  *
42  *  Driver: the name of the driver
43  *  Description: a short phrase describing the driver.  Don't list boards.
44  *  Devices: a full list of the boards that attempt to be supported by
45  *    the driver.  Format is "(manufacturer) board name [comedi name]",
46  *    where comedi_name is the name that is used to configure the board.
47  *    See the comment near board_name: in the struct comedi_driver structure
48  *    below.  If (manufacturer) or [comedi name] is missing, the previous
49  *    value is used.
50  *  Author: you
51  *  Updated: date when the _documentation_ was last updated.  Use 'date -R'
52  *    to get a value for this.
53  *  Status: a one-word description of the status.  Valid values are:
54  *    works - driver works correctly on most boards supported, and
55  *      passes comedi_test.
56  *    unknown - unknown.  Usually put there by ds.
57  *    experimental - may not work in any particular release.  Author
58  *      probably wants assistance testing it.
59  *    bitrotten - driver has not been update in a long time, probably
60  *      doesn't work, and probably is missing support for significant
61  *      Comedi interface features.
62  *    untested - author probably wrote it "blind", and is believed to
63  *      work, but no confirmation.
64  *
65  * These headers should be followed by a blank line, and any comments
66  * you wish to say about the driver.  The comment area is the place
67  * to put any known bugs, limitations, unsupported features, supported
68  * command triggers, whether or not commands are supported on particular
69  * subdevices, etc.
70  *
71  * Somewhere in the comment should be information about configuration
72  * options that are used with comedi_config.
73  */
74
75 #include "../comedidev.h"
76
77 #include <linux/pci.h>          /* for PCI devices */
78
79 #include "comedi_fc.h"
80
81 /* Imaginary registers for the imaginary board */
82
83 #define SKEL_SIZE 0
84
85 #define SKEL_START_AI_CONV      0
86 #define SKEL_AI_READ            0
87
88 /*
89  * Board descriptions for two imaginary boards.  Describing the
90  * boards in this way is optional, and completely driver-dependent.
91  * Some drivers use arrays such as this, other do not.
92  */
93 struct skel_board {
94         const char *name;
95         int ai_chans;
96         int ai_bits;
97         int have_dio;
98 };
99
100 static const struct skel_board skel_boards[] = {
101         {
102          .name = "skel-100",
103          .ai_chans = 16,
104          .ai_bits = 12,
105          .have_dio = 1,
106          },
107         {
108          .name = "skel-200",
109          .ai_chans = 8,
110          .ai_bits = 16,
111          .have_dio = 0,
112          },
113 };
114
115 /* This is used by modprobe to translate PCI IDs to drivers.  Should
116  * only be used for PCI and ISA-PnP devices */
117 /* Please add your PCI vendor ID to comedidev.h, and it will be forwarded
118  * upstream. */
119 #define PCI_VENDOR_ID_SKEL 0xdafe
120 static DEFINE_PCI_DEVICE_TABLE(skel_pci_table) = {
121         { PCI_DEVICE(PCI_VENDOR_ID_SKEL, 0x0100) },
122         { PCI_DEVICE(PCI_VENDOR_ID_SKEL, 0x0200) },
123         { 0 }
124 };
125
126 MODULE_DEVICE_TABLE(pci, skel_pci_table);
127
128 /*
129  * Useful for shorthand access to the particular board structure
130  */
131 #define thisboard ((const struct skel_board *)dev->board_ptr)
132
133 /* this structure is for data unique to this hardware driver.  If
134    several hardware drivers keep similar information in this structure,
135    feel free to suggest moving the variable to the struct comedi_device struct.
136  */
137 struct skel_private {
138
139         int data;
140
141         /* would be useful for a PCI device */
142         struct pci_dev *pci_dev;
143
144         /* Used for AO readback */
145         unsigned int ao_readback[2];
146 };
147
148 /*
149  * The struct comedi_driver structure tells the Comedi core module
150  * which functions to call to configure/deconfigure (attach/detach)
151  * the board, and also about the kernel module that contains
152  * the device code.
153  */
154 static int skel_attach(struct comedi_device *dev, struct comedi_devconfig *it);
155 static void skel_detach(struct comedi_device *dev);
156 static struct comedi_driver driver_skel = {
157         .driver_name = "dummy",
158         .module = THIS_MODULE,
159         .attach = skel_attach,
160         .detach = skel_detach,
161 /* It is not necessary to implement the following members if you are
162  * writing a driver for a ISA PnP or PCI card */
163         /* Most drivers will support multiple types of boards by
164          * having an array of board structures.  These were defined
165          * in skel_boards[] above.  Note that the element 'name'
166          * was first in the structure -- Comedi uses this fact to
167          * extract the name of the board without knowing any details
168          * about the structure except for its length.
169          * When a device is attached (by comedi_config), the name
170          * of the device is given to Comedi, and Comedi tries to
171          * match it by going through the list of board names.  If
172          * there is a match, the address of the pointer is put
173          * into dev->board_ptr and driver->attach() is called.
174          *
175          * Note that these are not necessary if you can determine
176          * the type of board in software.  ISA PnP, PCI, and PCMCIA
177          * devices are such boards.
178          */
179         .board_name = &skel_boards[0].name,
180         .offset = sizeof(struct skel_board),
181         .num_names = ARRAY_SIZE(skel_boards),
182 };
183
184 static int skel_ai_rinsn(struct comedi_device *dev, struct comedi_subdevice *s,
185                          struct comedi_insn *insn, unsigned int *data);
186 static int skel_ao_winsn(struct comedi_device *dev, struct comedi_subdevice *s,
187                          struct comedi_insn *insn, unsigned int *data);
188 static int skel_ao_rinsn(struct comedi_device *dev, struct comedi_subdevice *s,
189                          struct comedi_insn *insn, unsigned int *data);
190 static int skel_dio_insn_bits(struct comedi_device *dev,
191                               struct comedi_subdevice *s,
192                               struct comedi_insn *insn, unsigned int *data);
193 static int skel_dio_insn_config(struct comedi_device *dev,
194                                 struct comedi_subdevice *s,
195                                 struct comedi_insn *insn, unsigned int *data);
196 static int skel_ai_cmdtest(struct comedi_device *dev,
197                            struct comedi_subdevice *s, struct comedi_cmd *cmd);
198 static int skel_ns_to_timer(unsigned int *ns, int round);
199
200 /*
201  * Attach is called by the Comedi core to configure the driver
202  * for a particular board.  If you specified a board_name array
203  * in the driver structure, dev->board_ptr contains that
204  * address.
205  */
206 static int skel_attach(struct comedi_device *dev, struct comedi_devconfig *it)
207 {
208         struct skel_private *devpriv;
209         struct comedi_subdevice *s;
210         int ret;
211
212         pr_info("comedi%d: skel: ", dev->minor);
213
214 /*
215  * If you can probe the device to determine what device in a series
216  * it is, this is the place to do it.  Otherwise, dev->board_ptr
217  * should already be initialized.
218  */
219         /* dev->board_ptr = skel_probe(dev, it); */
220
221 /*
222  * Initialize dev->board_name.  Note that we can use the "thisboard"
223  * macro now, since we just initialized it in the last line.
224  */
225         dev->board_name = thisboard->name;
226
227         /* Allocate the private data */
228         devpriv = kzalloc(sizeof(*devpriv), GFP_KERNEL);
229         if (!devpriv)
230                 return -ENOMEM;
231         dev->private = devpriv;
232
233         ret = comedi_alloc_subdevices(dev, 3);
234         if (ret)
235                 return ret;
236
237         s = &dev->subdevices[0];
238         /* dev->read_subdev=s; */
239         /* analog input subdevice */
240         s->type = COMEDI_SUBD_AI;
241         /* we support single-ended (ground) and differential */
242         s->subdev_flags = SDF_READABLE | SDF_GROUND | SDF_DIFF;
243         s->n_chan = thisboard->ai_chans;
244         s->maxdata = (1 << thisboard->ai_bits) - 1;
245         s->range_table = &range_bipolar10;
246         s->len_chanlist = 16;   /* This is the maximum chanlist length that
247                                    the board can handle */
248         s->insn_read = skel_ai_rinsn;
249 /*
250 *       s->subdev_flags |= SDF_CMD_READ;
251 *       s->do_cmd = skel_ai_cmd;
252 */
253         s->do_cmdtest = skel_ai_cmdtest;
254
255         s = &dev->subdevices[1];
256         /* analog output subdevice */
257         s->type = COMEDI_SUBD_AO;
258         s->subdev_flags = SDF_WRITABLE;
259         s->n_chan = 1;
260         s->maxdata = 0xffff;
261         s->range_table = &range_bipolar5;
262         s->insn_write = skel_ao_winsn;
263         s->insn_read = skel_ao_rinsn;
264
265         s = &dev->subdevices[2];
266         /* digital i/o subdevice */
267         if (thisboard->have_dio) {
268                 s->type = COMEDI_SUBD_DIO;
269                 s->subdev_flags = SDF_READABLE | SDF_WRITABLE;
270                 s->n_chan = 16;
271                 s->maxdata = 1;
272                 s->range_table = &range_digital;
273                 s->insn_bits = skel_dio_insn_bits;
274                 s->insn_config = skel_dio_insn_config;
275         } else {
276                 s->type = COMEDI_SUBD_UNUSED;
277         }
278
279         pr_info("attached\n");
280
281         return 0;
282 }
283
284 /*
285  * _detach is called to deconfigure a device.  It should deallocate
286  * resources.
287  * This function is also called when _attach() fails, so it should be
288  * careful not to release resources that were not necessarily
289  * allocated by _attach().  dev->private and dev->subdevices are
290  * deallocated automatically by the core.
291  */
292 static void skel_detach(struct comedi_device *dev)
293 {
294 }
295
296 /*
297  * "instructions" read/write data in "one-shot" or "software-triggered"
298  * mode.
299  */
300 static int skel_ai_rinsn(struct comedi_device *dev, struct comedi_subdevice *s,
301                          struct comedi_insn *insn, unsigned int *data)
302 {
303         int n, i;
304         unsigned int d;
305         unsigned int status;
306
307         /* a typical programming sequence */
308
309         /* write channel to multiplexer */
310         /* outw(chan,dev->iobase + SKEL_MUX); */
311
312         /* don't wait for mux to settle */
313
314         /* convert n samples */
315         for (n = 0; n < insn->n; n++) {
316                 /* trigger conversion */
317                 /* outw(0,dev->iobase + SKEL_CONVERT); */
318
319 #define TIMEOUT 100
320                 /* wait for conversion to end */
321                 for (i = 0; i < TIMEOUT; i++) {
322                         status = 1;
323                         /* status = inb(dev->iobase + SKEL_STATUS); */
324                         if (status)
325                                 break;
326                 }
327                 if (i == TIMEOUT) {
328                         /* printk() should be used instead of printk()
329                          * whenever the code can be called from real-time. */
330                         pr_info("timeout\n");
331                         return -ETIMEDOUT;
332                 }
333
334                 /* read data */
335                 /* d = inw(dev->iobase + SKEL_AI_DATA); */
336                 d = 0;
337
338                 /* mangle the data as necessary */
339                 d ^= 1 << (thisboard->ai_bits - 1);
340
341                 data[n] = d;
342         }
343
344         /* return the number of samples read/written */
345         return n;
346 }
347
348 /*
349  * cmdtest tests a particular command to see if it is valid.
350  * Using the cmdtest ioctl, a user can create a valid cmd
351  * and then have it executes by the cmd ioctl.
352  *
353  * cmdtest returns 1,2,3,4 or 0, depending on which tests
354  * the command passes.
355  */
356 static int skel_ai_cmdtest(struct comedi_device *dev,
357                            struct comedi_subdevice *s,
358                            struct comedi_cmd *cmd)
359 {
360         int err = 0;
361         int tmp;
362
363         /* Step 1 : check if triggers are trivially valid */
364
365         err |= cfc_check_trigger_src(&cmd->start_src, TRIG_NOW);
366         err |= cfc_check_trigger_src(&cmd->scan_begin_src,
367                                         TRIG_TIMER | TRIG_EXT);
368         err |= cfc_check_trigger_src(&cmd->convert_src, TRIG_TIMER | TRIG_EXT);
369         err |= cfc_check_trigger_src(&cmd->scan_end_src, TRIG_COUNT);
370         err |= cfc_check_trigger_src(&cmd->stop_src, TRIG_COUNT | TRIG_NONE);
371
372         if (err)
373                 return 1;
374
375         /* Step 2a : make sure trigger sources are unique */
376
377         err |= cfc_check_trigger_is_unique(cmd->scan_begin_src);
378         err |= cfc_check_trigger_is_unique(cmd->convert_src);
379         err |= cfc_check_trigger_is_unique(cmd->stop_src);
380
381         /* Step 2b : and mutually compatible */
382
383         if (err)
384                 return 2;
385
386         /* step 3: make sure arguments are trivially compatible */
387
388         if (cmd->start_arg != 0) {
389                 cmd->start_arg = 0;
390                 err++;
391         }
392 #define MAX_SPEED       10000   /* in nanoseconds */
393 #define MIN_SPEED       1000000000      /* in nanoseconds */
394
395         if (cmd->scan_begin_src == TRIG_TIMER) {
396                 if (cmd->scan_begin_arg < MAX_SPEED) {
397                         cmd->scan_begin_arg = MAX_SPEED;
398                         err++;
399                 }
400                 if (cmd->scan_begin_arg > MIN_SPEED) {
401                         cmd->scan_begin_arg = MIN_SPEED;
402                         err++;
403                 }
404         } else {
405                 /* external trigger */
406                 /* should be level/edge, hi/lo specification here */
407                 /* should specify multiple external triggers */
408                 if (cmd->scan_begin_arg > 9) {
409                         cmd->scan_begin_arg = 9;
410                         err++;
411                 }
412         }
413         if (cmd->convert_src == TRIG_TIMER) {
414                 if (cmd->convert_arg < MAX_SPEED) {
415                         cmd->convert_arg = MAX_SPEED;
416                         err++;
417                 }
418                 if (cmd->convert_arg > MIN_SPEED) {
419                         cmd->convert_arg = MIN_SPEED;
420                         err++;
421                 }
422         } else {
423                 /* external trigger */
424                 /* see above */
425                 if (cmd->convert_arg > 9) {
426                         cmd->convert_arg = 9;
427                         err++;
428                 }
429         }
430
431         if (cmd->scan_end_arg != cmd->chanlist_len) {
432                 cmd->scan_end_arg = cmd->chanlist_len;
433                 err++;
434         }
435         if (cmd->stop_src == TRIG_COUNT) {
436                 if (cmd->stop_arg > 0x00ffffff) {
437                         cmd->stop_arg = 0x00ffffff;
438                         err++;
439                 }
440         } else {
441                 /* TRIG_NONE */
442                 if (cmd->stop_arg != 0) {
443                         cmd->stop_arg = 0;
444                         err++;
445                 }
446         }
447
448         if (err)
449                 return 3;
450
451         /* step 4: fix up any arguments */
452
453         if (cmd->scan_begin_src == TRIG_TIMER) {
454                 tmp = cmd->scan_begin_arg;
455                 skel_ns_to_timer(&cmd->scan_begin_arg,
456                                  cmd->flags & TRIG_ROUND_MASK);
457                 if (tmp != cmd->scan_begin_arg)
458                         err++;
459         }
460         if (cmd->convert_src == TRIG_TIMER) {
461                 tmp = cmd->convert_arg;
462                 skel_ns_to_timer(&cmd->convert_arg,
463                                  cmd->flags & TRIG_ROUND_MASK);
464                 if (tmp != cmd->convert_arg)
465                         err++;
466                 if (cmd->scan_begin_src == TRIG_TIMER &&
467                     cmd->scan_begin_arg <
468                     cmd->convert_arg * cmd->scan_end_arg) {
469                         cmd->scan_begin_arg =
470                             cmd->convert_arg * cmd->scan_end_arg;
471                         err++;
472                 }
473         }
474
475         if (err)
476                 return 4;
477
478         return 0;
479 }
480
481 /* This function doesn't require a particular form, this is just
482  * what happens to be used in some of the drivers.  It should
483  * convert ns nanoseconds to a counter value suitable for programming
484  * the device.  Also, it should adjust ns so that it cooresponds to
485  * the actual time that the device will use. */
486 static int skel_ns_to_timer(unsigned int *ns, int round)
487 {
488         /* trivial timer */
489         /* if your timing is done through two cascaded timers, the
490          * i8253_cascade_ns_to_timer() function in 8253.h can be
491          * very helpful.  There are also i8254_load() and i8254_mm_load()
492          * which can be used to load values into the ubiquitous 8254 counters
493          */
494
495         return *ns;
496 }
497
498 static int skel_ao_winsn(struct comedi_device *dev, struct comedi_subdevice *s,
499                          struct comedi_insn *insn, unsigned int *data)
500 {
501         struct skel_private *devpriv = dev->private;
502         int i;
503         int chan = CR_CHAN(insn->chanspec);
504
505         pr_info("skel_ao_winsn\n");
506         /* Writing a list of values to an AO channel is probably not
507          * very useful, but that's how the interface is defined. */
508         for (i = 0; i < insn->n; i++) {
509                 /* a typical programming sequence */
510                 /* outw(data[i],dev->iobase + SKEL_DA0 + chan); */
511                 devpriv->ao_readback[chan] = data[i];
512         }
513
514         /* return the number of samples read/written */
515         return i;
516 }
517
518 /* AO subdevices should have a read insn as well as a write insn.
519  * Usually this means copying a value stored in devpriv. */
520 static int skel_ao_rinsn(struct comedi_device *dev, struct comedi_subdevice *s,
521                          struct comedi_insn *insn, unsigned int *data)
522 {
523         struct skel_private *devpriv = dev->private;
524         int i;
525         int chan = CR_CHAN(insn->chanspec);
526
527         for (i = 0; i < insn->n; i++)
528                 data[i] = devpriv->ao_readback[chan];
529
530         return i;
531 }
532
533 /* DIO devices are slightly special.  Although it is possible to
534  * implement the insn_read/insn_write interface, it is much more
535  * useful to applications if you implement the insn_bits interface.
536  * This allows packed reading/writing of the DIO channels.  The
537  * comedi core can convert between insn_bits and insn_read/write */
538 static int skel_dio_insn_bits(struct comedi_device *dev,
539                               struct comedi_subdevice *s,
540                               struct comedi_insn *insn, unsigned int *data)
541 {
542         /* The insn data is a mask in data[0] and the new data
543          * in data[1], each channel cooresponding to a bit. */
544         if (data[0]) {
545                 s->state &= ~data[0];
546                 s->state |= data[0] & data[1];
547                 /* Write out the new digital output lines */
548                 /* outw(s->state,dev->iobase + SKEL_DIO); */
549         }
550
551         /* on return, data[1] contains the value of the digital
552          * input and output lines. */
553         /* data[1]=inw(dev->iobase + SKEL_DIO); */
554         /* or we could just return the software copy of the output values if
555          * it was a purely digital output subdevice */
556         /* data[1]=s->state; */
557
558         return insn->n;
559 }
560
561 static int skel_dio_insn_config(struct comedi_device *dev,
562                                 struct comedi_subdevice *s,
563                                 struct comedi_insn *insn, unsigned int *data)
564 {
565         int chan = CR_CHAN(insn->chanspec);
566
567         /* The input or output configuration of each digital line is
568          * configured by a special insn_config instruction.  chanspec
569          * contains the channel to be changed, and data[0] contains the
570          * value COMEDI_INPUT or COMEDI_OUTPUT. */
571         switch (data[0]) {
572         case INSN_CONFIG_DIO_OUTPUT:
573                 s->io_bits |= 1 << chan;
574                 break;
575         case INSN_CONFIG_DIO_INPUT:
576                 s->io_bits &= ~(1 << chan);
577                 break;
578         case INSN_CONFIG_DIO_QUERY:
579                 data[1] =
580                     (s->io_bits & (1 << chan)) ? COMEDI_OUTPUT : COMEDI_INPUT;
581                 return insn->n;
582                 break;
583         default:
584                 return -EINVAL;
585                 break;
586         }
587         /* outw(s->io_bits,dev->iobase + SKEL_DIO_CONFIG); */
588
589         return insn->n;
590 }
591
592 #ifdef CONFIG_COMEDI_PCI_DRIVERS
593 static int __devinit driver_skel_pci_probe(struct pci_dev *dev,
594                                            const struct pci_device_id *ent)
595 {
596         return comedi_pci_auto_config(dev, &driver_skel);
597 }
598
599 static void __devexit driver_skel_pci_remove(struct pci_dev *dev)
600 {
601         comedi_pci_auto_unconfig(dev);
602 }
603
604 static struct pci_driver driver_skel_pci_driver = {
605         .id_table = skel_pci_table,
606         .probe = &driver_skel_pci_probe,
607         .remove = __devexit_p(&driver_skel_pci_remove)
608 };
609
610 static int __init driver_skel_init_module(void)
611 {
612         int retval;
613
614         retval = comedi_driver_register(&driver_skel);
615         if (retval < 0)
616                 return retval;
617
618         driver_skel_pci_driver.name = (char *)driver_skel.driver_name;
619         return pci_register_driver(&driver_skel_pci_driver);
620 }
621
622 static void __exit driver_skel_cleanup_module(void)
623 {
624         pci_unregister_driver(&driver_skel_pci_driver);
625         comedi_driver_unregister(&driver_skel);
626 }
627
628 module_init(driver_skel_init_module);
629 module_exit(driver_skel_cleanup_module);
630 #else
631 static int __init driver_skel_init_module(void)
632 {
633         return comedi_driver_register(&driver_skel);
634 }
635
636 static void __exit driver_skel_cleanup_module(void)
637 {
638         comedi_driver_unregister(&driver_skel);
639 }
640
641 module_init(driver_skel_init_module);
642 module_exit(driver_skel_cleanup_module);
643 #endif
644
645 MODULE_AUTHOR("Comedi http://www.comedi.org");
646 MODULE_DESCRIPTION("Comedi low-level driver");
647 MODULE_LICENSE("GPL");