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