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 /* this structure is for data unique to this hardware driver.  If
 129    several hardware drivers keep similar information in this structure,
 130    feel free to suggest moving the variable to the struct comedi_device struct.
 131  */
 132 struct skel_private {
 133
 134         int data;
 135
 136         /* would be useful for a PCI device */
 137         struct pci_dev *pci_dev;
 138
 139         /* Used for AO readback */
 140         unsigned int ao_readback[2];
 141 };
 142
 143 /*
 144  * The struct comedi_driver structure tells the Comedi core module
 145  * which functions to call to configure/deconfigure (attach/detach)
 146  * the board, and also about the kernel module that contains
 147  * the device code.
 148  */
 149 static int skel_attach(struct comedi_device *dev, struct comedi_devconfig *it);
 150 static void skel_detach(struct comedi_device *dev);
 151 static struct comedi_driver driver_skel = {
 152         .driver_name = "dummy",
 153         .module = THIS_MODULE,
 154         .attach = skel_attach,
 155         .detach = skel_detach,
 156 /* It is not necessary to implement the following members if you are
 157  * writing a driver for a ISA PnP or PCI card */
 158         /* Most drivers will support multiple types of boards by
 159          * having an array of board structures.  These were defined
 160          * in skel_boards[] above.  Note that the element 'name'
 161          * was first in the structure -- Comedi uses this fact to
 162          * extract the name of the board without knowing any details
 163          * about the structure except for its length.
 164          * When a device is attached (by comedi_config), the name
 165          * of the device is given to Comedi, and Comedi tries to
 166          * match it by going through the list of board names.  If
 167          * there is a match, the address of the pointer is put
 168          * into dev->board_ptr and driver->attach() is called.
 169          *
 170          * Note that these are not necessary if you can determine
 171          * the type of board in software.  ISA PnP, PCI, and PCMCIA
 172          * devices are such boards.
 173          */
 174         .board_name = &skel_boards[0].name,
 175         .offset = sizeof(struct skel_board),
 176         .num_names = ARRAY_SIZE(skel_boards),
 177 };
 178
 179 static int skel_ai_rinsn(struct comedi_device *dev, struct comedi_subdevice *s,
 180                          struct comedi_insn *insn, unsigned int *data);
 181 static int skel_ao_winsn(struct comedi_device *dev, struct comedi_subdevice *s,
 182                          struct comedi_insn *insn, unsigned int *data);
 183 static int skel_ao_rinsn(struct comedi_device *dev, struct comedi_subdevice *s,
 184                          struct comedi_insn *insn, unsigned int *data);
 185 static int skel_dio_insn_bits(struct comedi_device *dev,
 186                               struct comedi_subdevice *s,
 187                               struct comedi_insn *insn, unsigned int *data);
 188 static int skel_dio_insn_config(struct comedi_device *dev,
 189                                 struct comedi_subdevice *s,
 190                                 struct comedi_insn *insn, unsigned int *data);
 191 static int skel_ai_cmdtest(struct comedi_device *dev,
 192                            struct comedi_subdevice *s, struct comedi_cmd *cmd);
 193 static int skel_ns_to_timer(unsigned int *ns, int round);
 194
 195 /*
 196  * Attach is called by the Comedi core to configure the driver
 197  * for a particular board.  If you specified a board_name array
 198  * in the driver structure, dev->board_ptr contains that
 199  * address.
 200  */
 201 static int skel_attach(struct comedi_device *dev, struct comedi_devconfig *it)
 202 {
 203         const struct skel_board *thisboard;
 204         struct skel_private *devpriv;
 205         struct comedi_subdevice *s;
 206         int ret;
 207
 208         pr_info("comedi%d: skel: ", dev->minor);
 209
 210 /*
 211  * If you can probe the device to determine what device in a series
 212  * it is, this is the place to do it.  Otherwise, dev->board_ptr
 213  * should already be initialized.
 214  */
 215         /* dev->board_ptr = skel_probe(dev, it); */
 216
 217         thisboard = comedi_board(dev);
 218 /*
 219  * Initialize dev->board_name.
 220  */
 221         dev->board_name = thisboard->name;
 222
 223         /* Allocate the private data */
 224         devpriv = kzalloc(sizeof(*devpriv), GFP_KERNEL);
 225         if (!devpriv)
 226                 return -ENOMEM;
 227         dev->private = devpriv;
 228
 229         ret = comedi_alloc_subdevices(dev, 3);
 230         if (ret)
 231                 return ret;
 232
 233         s = &dev->subdevices[0];
 234         /* dev->read_subdev=s; */
 235         /* analog input subdevice */
 236         s->type = COMEDI_SUBD_AI;
 237         /* we support single-ended (ground) and differential */
 238         s->subdev_flags = SDF_READABLE | SDF_GROUND | SDF_DIFF;
 239         s->n_chan = thisboard->ai_chans;
 240         s->maxdata = (1 << thisboard->ai_bits) - 1;
 241         s->range_table = &range_bipolar10;
 242         s->len_chanlist = 16;   /* This is the maximum chanlist length that
 243                                    the board can handle */
 244         s->insn_read = skel_ai_rinsn;
 245 /*
 246 *       s->subdev_flags |= SDF_CMD_READ;
 247 *       s->do_cmd = skel_ai_cmd;
 248 */
 249         s->do_cmdtest = skel_ai_cmdtest;
 250
 251         s = &dev->subdevices[1];
 252         /* analog output subdevice */
 253         s->type = COMEDI_SUBD_AO;
 254         s->subdev_flags = SDF_WRITABLE;
 255         s->n_chan = 1;
 256         s->maxdata = 0xffff;
 257         s->range_table = &range_bipolar5;
 258         s->insn_write = skel_ao_winsn;
 259         s->insn_read = skel_ao_rinsn;
 260
 261         s = &dev->subdevices[2];
 262         /* digital i/o subdevice */
 263         if (thisboard->have_dio) {
 264                 s->type = COMEDI_SUBD_DIO;
 265                 s->subdev_flags = SDF_READABLE | SDF_WRITABLE;
 266                 s->n_chan = 16;
 267                 s->maxdata = 1;
 268                 s->range_table = &range_digital;
 269                 s->insn_bits = skel_dio_insn_bits;
 270                 s->insn_config = skel_dio_insn_config;
 271         } else {
 272                 s->type = COMEDI_SUBD_UNUSED;
 273         }
 274
 275         pr_info("attached\n");
 276
 277         return 0;
 278 }
 279
 280 /*
 281  * _detach is called to deconfigure a device.  It should deallocate
 282  * resources.
 283  * This function is also called when _attach() fails, so it should be
 284  * careful not to release resources that were not necessarily
 285  * allocated by _attach().  dev->private and dev->subdevices are
 286  * deallocated automatically by the core.
 287  */
 288 static void skel_detach(struct comedi_device *dev)
 289 {
 290 }
 291
 292 /*
 293  * "instructions" read/write data in "one-shot" or "software-triggered"
 294  * mode.
 295  */
 296 static int skel_ai_rinsn(struct comedi_device *dev, struct comedi_subdevice *s,
 297                          struct comedi_insn *insn, unsigned int *data)
 298 {
 299         const struct skel_board *thisboard = comedi_board(dev);
 300         int n, i;
 301         unsigned int d;
 302         unsigned int status;
 303
 304         /* a typical programming sequence */
 305
 306         /* write channel to multiplexer */
 307         /* outw(chan,dev->iobase + SKEL_MUX); */
 308
 309         /* don't wait for mux to settle */
 310
 311         /* convert n samples */
 312         for (n = 0; n < insn->n; n++) {
 313                 /* trigger conversion */
 314                 /* outw(0,dev->iobase + SKEL_CONVERT); */
 315
 316 #define TIMEOUT 100
 317                 /* wait for conversion to end */
 318                 for (i = 0; i < TIMEOUT; i++) {
 319                         status = 1;
 320                         /* status = inb(dev->iobase + SKEL_STATUS); */
 321                         if (status)
 322                                 break;
 323                 }
 324                 if (i == TIMEOUT) {
 325                         /* printk() should be used instead of printk()
 326                          * whenever the code can be called from real-time. */
 327                         pr_info("timeout\n");
 328                         return -ETIMEDOUT;
 329                 }
 330
 331                 /* read data */
 332                 /* d = inw(dev->iobase + SKEL_AI_DATA); */
 333                 d = 0;
 334
 335                 /* mangle the data as necessary */
 336                 d ^= 1 << (thisboard->ai_bits - 1);
 337
 338                 data[n] = d;
 339         }
 340
 341         /* return the number of samples read/written */
 342         return n;
 343 }
 344
 345 /*
 346  * cmdtest tests a particular command to see if it is valid.
 347  * Using the cmdtest ioctl, a user can create a valid cmd
 348  * and then have it executes by the cmd ioctl.
 349  *
 350  * cmdtest returns 1,2,3,4 or 0, depending on which tests
 351  * the command passes.
 352  */
 353 static int skel_ai_cmdtest(struct comedi_device *dev,
 354                            struct comedi_subdevice *s,
 355                            struct comedi_cmd *cmd)
 356 {
 357         int err = 0;
 358         int tmp;
 359
 360         /* Step 1 : check if triggers are trivially valid */
 361
 362         err |= cfc_check_trigger_src(&cmd->start_src, TRIG_NOW);
 363         err |= cfc_check_trigger_src(&cmd->scan_begin_src,
 364                                         TRIG_TIMER | TRIG_EXT);
 365         err |= cfc_check_trigger_src(&cmd->convert_src, TRIG_TIMER | TRIG_EXT);
 366         err |= cfc_check_trigger_src(&cmd->scan_end_src, TRIG_COUNT);
 367         err |= cfc_check_trigger_src(&cmd->stop_src, TRIG_COUNT | TRIG_NONE);
 368
 369         if (err)
 370                 return 1;
 371
 372         /* Step 2a : make sure trigger sources are unique */
 373
 374         err |= cfc_check_trigger_is_unique(cmd->scan_begin_src);
 375         err |= cfc_check_trigger_is_unique(cmd->convert_src);
 376         err |= cfc_check_trigger_is_unique(cmd->stop_src);
 377
 378         /* Step 2b : and mutually compatible */
 379
 380         if (err)
 381                 return 2;
 382
 383         /* step 3: make sure arguments are trivially compatible */
 384
 385         if (cmd->start_arg != 0) {
 386                 cmd->start_arg = 0;
 387                 err++;
 388         }
 389 #define MAX_SPEED       10000   /* in nanoseconds */
 390 #define MIN_SPEED       1000000000      /* in nanoseconds */
 391
 392         if (cmd->scan_begin_src == TRIG_TIMER) {
 393                 if (cmd->scan_begin_arg < MAX_SPEED) {
 394                         cmd->scan_begin_arg = MAX_SPEED;
 395                         err++;
 396                 }
 397                 if (cmd->scan_begin_arg > MIN_SPEED) {
 398                         cmd->scan_begin_arg = MIN_SPEED;
 399                         err++;
 400                 }
 401         } else {
 402                 /* external trigger */
 403                 /* should be level/edge, hi/lo specification here */
 404                 /* should specify multiple external triggers */
 405                 if (cmd->scan_begin_arg > 9) {
 406                         cmd->scan_begin_arg = 9;
 407                         err++;
 408                 }
 409         }
 410         if (cmd->convert_src == TRIG_TIMER) {
 411                 if (cmd->convert_arg < MAX_SPEED) {
 412                         cmd->convert_arg = MAX_SPEED;
 413                         err++;
 414                 }
 415                 if (cmd->convert_arg > MIN_SPEED) {
 416                         cmd->convert_arg = MIN_SPEED;
 417                         err++;
 418                 }
 419         } else {
 420                 /* external trigger */
 421                 /* see above */
 422                 if (cmd->convert_arg > 9) {
 423                         cmd->convert_arg = 9;
 424                         err++;
 425                 }
 426         }
 427
 428         if (cmd->scan_end_arg != cmd->chanlist_len) {
 429                 cmd->scan_end_arg = cmd->chanlist_len;
 430                 err++;
 431         }
 432         if (cmd->stop_src == TRIG_COUNT) {
 433                 if (cmd->stop_arg > 0x00ffffff) {
 434                         cmd->stop_arg = 0x00ffffff;
 435                         err++;
 436                 }
 437         } else {
 438                 /* TRIG_NONE */
 439                 if (cmd->stop_arg != 0) {
 440                         cmd->stop_arg = 0;
 441                         err++;
 442                 }
 443         }
 444
 445         if (err)
 446                 return 3;
 447
 448         /* step 4: fix up any arguments */
 449
 450         if (cmd->scan_begin_src == TRIG_TIMER) {
 451                 tmp = cmd->scan_begin_arg;
 452                 skel_ns_to_timer(&cmd->scan_begin_arg,
 453                                  cmd->flags & TRIG_ROUND_MASK);
 454                 if (tmp != cmd->scan_begin_arg)
 455                         err++;
 456         }
 457         if (cmd->convert_src == TRIG_TIMER) {
 458                 tmp = cmd->convert_arg;
 459                 skel_ns_to_timer(&cmd->convert_arg,
 460                                  cmd->flags & TRIG_ROUND_MASK);
 461                 if (tmp != cmd->convert_arg)
 462                         err++;
 463                 if (cmd->scan_begin_src == TRIG_TIMER &&
 464                     cmd->scan_begin_arg <
 465                     cmd->convert_arg * cmd->scan_end_arg) {
 466                         cmd->scan_begin_arg =
 467                             cmd->convert_arg * cmd->scan_end_arg;
 468                         err++;
 469                 }
 470         }
 471
 472         if (err)
 473                 return 4;
 474
 475         return 0;
 476 }
 477
 478 /* This function doesn't require a particular form, this is just
 479  * what happens to be used in some of the drivers.  It should
 480  * convert ns nanoseconds to a counter value suitable for programming
 481  * the device.  Also, it should adjust ns so that it cooresponds to
 482  * the actual time that the device will use. */
 483 static int skel_ns_to_timer(unsigned int *ns, int round)
 484 {
 485         /* trivial timer */
 486         /* if your timing is done through two cascaded timers, the
 487          * i8253_cascade_ns_to_timer() function in 8253.h can be
 488          * very helpful.  There are also i8254_load() and i8254_mm_load()
 489          * which can be used to load values into the ubiquitous 8254 counters
 490          */
 491
 492         return *ns;
 493 }
 494
 495 static int skel_ao_winsn(struct comedi_device *dev, struct comedi_subdevice *s,
 496                          struct comedi_insn *insn, unsigned int *data)
 497 {
 498         struct skel_private *devpriv = dev->private;
 499         int i;
 500         int chan = CR_CHAN(insn->chanspec);
 501
 502         pr_info("skel_ao_winsn\n");
 503         /* Writing a list of values to an AO channel is probably not
 504          * very useful, but that's how the interface is defined. */
 505         for (i = 0; i < insn->n; i++) {
 506                 /* a typical programming sequence */
 507                 /* outw(data[i],dev->iobase + SKEL_DA0 + chan); */
 508                 devpriv->ao_readback[chan] = data[i];
 509         }
 510
 511         /* return the number of samples read/written */
 512         return i;
 513 }
 514
 515 /* AO subdevices should have a read insn as well as a write insn.
 516  * Usually this means copying a value stored in devpriv. */
 517 static int skel_ao_rinsn(struct comedi_device *dev, struct comedi_subdevice *s,
 518                          struct comedi_insn *insn, unsigned int *data)
 519 {
 520         struct skel_private *devpriv = dev->private;
 521         int i;
 522         int chan = CR_CHAN(insn->chanspec);
 523
 524         for (i = 0; i < insn->n; i++)
 525                 data[i] = devpriv->ao_readback[chan];
 526
 527         return i;
 528 }
 529
 530 /* DIO devices are slightly special.  Although it is possible to
 531  * implement the insn_read/insn_write interface, it is much more
 532  * useful to applications if you implement the insn_bits interface.
 533  * This allows packed reading/writing of the DIO channels.  The
 534  * comedi core can convert between insn_bits and insn_read/write */
 535 static int skel_dio_insn_bits(struct comedi_device *dev,
 536                               struct comedi_subdevice *s,
 537                               struct comedi_insn *insn, unsigned int *data)
 538 {
 539         /* The insn data is a mask in data[0] and the new data
 540          * in data[1], each channel cooresponding to a bit. */
 541         if (data[0]) {
 542                 s->state &= ~data[0];
 543                 s->state |= data[0] & data[1];
 544                 /* Write out the new digital output lines */
 545                 /* outw(s->state,dev->iobase + SKEL_DIO); */
 546         }
 547
 548         /* on return, data[1] contains the value of the digital
 549          * input and output lines. */
 550         /* data[1]=inw(dev->iobase + SKEL_DIO); */
 551         /* or we could just return the software copy of the output values if
 552          * it was a purely digital output subdevice */
 553         /* data[1]=s->state; */
 554
 555         return insn->n;
 556 }
 557
 558 static int skel_dio_insn_config(struct comedi_device *dev,
 559                                 struct comedi_subdevice *s,
 560                                 struct comedi_insn *insn, unsigned int *data)
 561 {
 562         int chan = CR_CHAN(insn->chanspec);
 563
 564         /* The input or output configuration of each digital line is
 565          * configured by a special insn_config instruction.  chanspec
 566          * contains the channel to be changed, and data[0] contains the
 567          * value COMEDI_INPUT or COMEDI_OUTPUT. */
 568         switch (data[0]) {
 569         case INSN_CONFIG_DIO_OUTPUT:
 570                 s->io_bits |= 1 << chan;
 571                 break;
 572         case INSN_CONFIG_DIO_INPUT:
 573                 s->io_bits &= ~(1 << chan);
 574                 break;
 575         case INSN_CONFIG_DIO_QUERY:
 576                 data[1] =
 577                     (s->io_bits & (1 << chan)) ? COMEDI_OUTPUT : COMEDI_INPUT;
 578                 return insn->n;
 579                 break;
 580         default:
 581                 return -EINVAL;
 582                 break;
 583         }
 584         /* outw(s->io_bits,dev->iobase + SKEL_DIO_CONFIG); */
 585
 586         return insn->n;
 587 }
 588
 589 #ifdef CONFIG_COMEDI_PCI_DRIVERS
 590 static int __devinit driver_skel_pci_probe(struct pci_dev *dev,
 591                                            const struct pci_device_id *ent)
 592 {
 593         return comedi_pci_auto_config(dev, &driver_skel);
 594 }
 595
 596 static void __devexit driver_skel_pci_remove(struct pci_dev *dev)
 597 {
 598         comedi_pci_auto_unconfig(dev);
 599 }
 600
 601 static struct pci_driver driver_skel_pci_driver = {
 602         .id_table = skel_pci_table,
 603         .probe = &driver_skel_pci_probe,
 604         .remove = __devexit_p(&driver_skel_pci_remove)
 605 };
 606
 607 static int __init driver_skel_init_module(void)
 608 {
 609         int retval;
 610
 611         retval = comedi_driver_register(&driver_skel);
 612         if (retval < 0)
 613                 return retval;
 614
 615         driver_skel_pci_driver.name = (char *)driver_skel.driver_name;
 616         return pci_register_driver(&driver_skel_pci_driver);
 617 }
 618
 619 static void __exit driver_skel_cleanup_module(void)
 620 {
 621         pci_unregister_driver(&driver_skel_pci_driver);
 622         comedi_driver_unregister(&driver_skel);
 623 }
 624
 625 module_init(driver_skel_init_module);
 626 module_exit(driver_skel_cleanup_module);
 627 #else
 628 module_comedi_driver(driver_skel);
 629 #endif
 630
 631 MODULE_AUTHOR("Comedi http://www.comedi.org");
 632 MODULE_DESCRIPTION("Comedi low-level driver");
 633 MODULE_LICENSE("GPL");