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.o
  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 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 <linux/comedidev.h>
  76
  77 #include <linux/pci.h> /* for PCI devices */
  78
  79
  80 /* Imaginary registers for the imaginary board */
  81
  82 #define SKEL_SIZE 0
  83
  84 #define SKEL_START_AI_CONV      0
  85 #define SKEL_AI_READ            0
  86
  87 /*
  88  * Board descriptions for two imaginary boards.  Describing the
  89  * boards in this way is optional, and completely driver-dependent.
  90  * Some drivers use arrays such as this, other do not.
  91  */
  92 typedef struct skel_board_struct{
  93         const char *name;
  94         int ai_chans;
  95         int ai_bits;
  96         int have_dio;
  97 }skel_board;
  98 static 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 struct pci_device_id skel_pci_table[] __devinitdata = {
 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 MODULE_DEVICE_TABLE(pci, skel_pci_table);
 124
 125 /*
 126  * Useful for shorthand access to the particular board structure
 127  */
 128 #define thisboard ((skel_board *)dev->board_ptr)
 129
 130 /* this structure is for data unique to this hardware driver.  If
 131    several hardware drivers keep similar information in this structure,
 132    feel free to suggest moving the variable to the comedi_device struct.  */
 133 typedef struct{
 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         lsampl_t ao_readback[2];
 141 }skel_private;
 142 /*
 143  * most drivers define the following macro to make it easy to
 144  * access the private structure.
 145  */
 146 #define devpriv ((skel_private *)dev->private)
 147
 148 /*
 149  * The 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(comedi_device *dev,comedi_devconfig *it);
 155 static int skel_detach(comedi_device *dev);
 156 static 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(skel_board),
 181         num_names:      sizeof(skel_boards) / sizeof(skel_board),
 182 };
 183
 184 static int skel_ai_rinsn(comedi_device *dev,comedi_subdevice *s,comedi_insn *insn,lsampl_t *data);
 185 static int skel_ao_winsn(comedi_device *dev,comedi_subdevice *s,comedi_insn *insn,lsampl_t *data);
 186 static int skel_ao_rinsn(comedi_device *dev,comedi_subdevice *s,comedi_insn *insn,lsampl_t *data);
 187 static int skel_dio_insn_bits(comedi_device *dev,comedi_subdevice *s,
 188         comedi_insn *insn,lsampl_t *data);
 189 static int skel_dio_insn_config(comedi_device *dev,comedi_subdevice *s,
 190         comedi_insn *insn,lsampl_t *data);
 191 static int skel_ai_cmdtest(comedi_device *dev,comedi_subdevice *s,
 192         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(comedi_device *dev,comedi_devconfig *it)
 202 {
 203         comedi_subdevice *s;
 204
 205         printk("comedi%d: skel: ",dev->minor);
 206
 207 /*
 208  * If you can probe the device to determine what device in a series
 209  * it is, this is the place to do it.  Otherwise, dev->board_ptr
 210  * should already be initialized.
 211  */
 212         //dev->board_ptr = skel_probe(dev);
 213
 214 /*
 215  * Initialize dev->board_name.  Note that we can use the "thisboard"
 216  * macro now, since we just initialized it in the last line.
 217  */
 218         dev->board_name = thisboard->name;
 219
 220 /*
 221  * Allocate the private structure area.  alloc_private() is a
 222  * convenient macro defined in comedidev.h.
 223  */
 224         if(alloc_private(dev,sizeof(skel_private))<0)
 225                 return -ENOMEM;
 226
 227 /*
 228  * Allocate the subdevice structures.  alloc_subdevice() is a
 229  * convenient macro defined in comedidev.h.
 230  */
 231         if(alloc_subdevices(dev, 3)<0)
 232                 return -ENOMEM;
 233
 234         s=dev->subdevices+0;
 235         //dev->read_subdev=s;
 236         /* analog input subdevice */
 237         s->type=COMEDI_SUBD_AI;
 238         /* we support single-ended (ground) and differential */
 239         s->subdev_flags=SDF_READABLE|SDF_GROUND|SDF_DIFF;
 240         s->n_chan=thisboard->ai_chans;
 241         s->maxdata=(1<<thisboard->ai_bits)-1;
 242         s->range_table=&range_bipolar10;
 243         s->len_chanlist=16;  /* This is the maximum chanlist length that
 244                                 the board can handle */
 245         s->insn_read = skel_ai_rinsn;
 246 //      s->subdev_flags |= SDF_CMD_READ;
 247 //      s->do_cmd = skel_ai_cmd;
 248         s->do_cmdtest = skel_ai_cmdtest;
 249
 250         s=dev->subdevices+1;
 251         /* analog output subdevice */
 252         s->type=COMEDI_SUBD_AO;
 253         s->subdev_flags=SDF_WRITABLE;
 254         s->n_chan=1;
 255         s->maxdata=0xffff;
 256         s->range_table=&range_bipolar5;
 257         s->insn_write = skel_ao_winsn;
 258         s->insn_read = skel_ao_rinsn;
 259
 260         s=dev->subdevices+2;
 261         /* digital i/o subdevice */
 262         if(thisboard->have_dio){
 263                 s->type=COMEDI_SUBD_DIO;
 264                 s->subdev_flags=SDF_READABLE|SDF_WRITABLE;
 265                 s->n_chan=16;
 266                 s->maxdata=1;
 267                 s->range_table=&range_digital;
 268                 s->insn_bits = skel_dio_insn_bits;
 269                 s->insn_config = skel_dio_insn_config;
 270         }else{
 271                 s->type = COMEDI_SUBD_UNUSED;
 272         }
 273
 274         printk("attached\n");
 275
 276         return 0;
 277 }
 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 int skel_detach(comedi_device *dev)
 289 {
 290         printk("comedi%d: skel: remove\n",dev->minor);
 291
 292         return 0;
 293 }
 294
 295 /*
 296  * "instructions" read/write data in "one-shot" or "software-triggered"
 297  * mode.
 298  */
 299 static int skel_ai_rinsn(comedi_device *dev,comedi_subdevice *s,comedi_insn *insn,lsampl_t *data)
 300 {
 301         int n,i;
 302         unsigned int d;
 303         unsigned int status;
 304
 305         /* a typical programming sequence */
 306
 307         /* write channel to multiplexer */
 308         //outw(chan,dev->iobase + SKEL_MUX);
 309
 310         /* don't wait for mux to settle */
 311
 312         /* convert n samples */
 313         for(n=0;n<insn->n;n++){
 314                 /* trigger conversion */
 315                 //outw(0,dev->iobase + SKEL_CONVERT);
 316
 317 #define TIMEOUT 100
 318                 /* wait for conversion to end */
 319                 for(i=0;i<TIMEOUT;i++){
 320                         status = 1;
 321                         //status = inb(dev->iobase + SKEL_STATUS);
 322                         if(status)break;
 323                 }
 324                 if(i==TIMEOUT){
 325                         /* rt_printk() should be used instead of printk()
 326                          * whenever the code can be called from real-time. */
 327                         rt_printk("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 static int skel_ai_cmdtest(comedi_device *dev,comedi_subdevice *s,
 346         comedi_cmd *cmd)
 347 {
 348         int err=0;
 349         int tmp;
 350
 351         /* cmdtest tests a particular command to see if it is valid.
 352          * Using the cmdtest ioctl, a user can create a valid cmd
 353          * and then have it executes by the cmd ioctl.
 354          *
 355          * cmdtest returns 1,2,3,4 or 0, depending on which tests
 356          * the command passes. */
 357
 358         /* step 1: make sure trigger sources are trivially valid */
 359
 360         tmp=cmd->start_src;
 361         cmd->start_src &= TRIG_NOW;
 362         if(!cmd->start_src || tmp!=cmd->start_src)err++;
 363
 364         tmp=cmd->scan_begin_src;
 365         cmd->scan_begin_src &= TRIG_TIMER|TRIG_EXT;
 366         if(!cmd->scan_begin_src || tmp!=cmd->scan_begin_src)err++;
 367
 368         tmp=cmd->convert_src;
 369         cmd->convert_src &= TRIG_TIMER|TRIG_EXT;
 370         if(!cmd->convert_src || tmp!=cmd->convert_src)err++;
 371
 372         tmp=cmd->scan_end_src;
 373         cmd->scan_end_src &= TRIG_COUNT;
 374         if(!cmd->scan_end_src || tmp!=cmd->scan_end_src)err++;
 375
 376         tmp=cmd->stop_src;
 377         cmd->stop_src &= TRIG_COUNT|TRIG_NONE;
 378         if(!cmd->stop_src || tmp!=cmd->stop_src)err++;
 379
 380         if(err)return 1;
 381
 382         /* step 2: make sure trigger sources are unique and mutually compatible */
 383
 384         /* note that mutual compatiblity is not an issue here */
 385         if(cmd->scan_begin_src!=TRIG_TIMER &&
 386            cmd->scan_begin_src!=TRIG_EXT)err++;
 387         if(cmd->convert_src!=TRIG_TIMER &&
 388            cmd->convert_src!=TRIG_EXT)err++;
 389         if(cmd->stop_src!=TRIG_COUNT &&
 390            cmd->stop_src!=TRIG_NONE)err++;
 391
 392         if(err)return 2;
 393
 394         /* step 3: make sure arguments are trivially compatible */
 395
 396         if(cmd->start_arg!=0){
 397                 cmd->start_arg=0;
 398                 err++;
 399         }
 400
 401 #define MAX_SPEED       10000           /* in nanoseconds */
 402 #define MIN_SPEED       1000000000      /* in nanoseconds */
 403
 404         if(cmd->scan_begin_src==TRIG_TIMER){
 405                 if(cmd->scan_begin_arg<MAX_SPEED){
 406                         cmd->scan_begin_arg=MAX_SPEED;
 407                         err++;
 408                 }
 409                 if(cmd->scan_begin_arg>MIN_SPEED){
 410                         cmd->scan_begin_arg=MIN_SPEED;
 411                         err++;
 412                 }
 413         }else{
 414                 /* external trigger */
 415                 /* should be level/edge, hi/lo specification here */
 416                 /* should specify multiple external triggers */
 417                 if(cmd->scan_begin_arg>9){
 418                         cmd->scan_begin_arg=9;
 419                         err++;
 420                 }
 421         }
 422         if(cmd->convert_src==TRIG_TIMER){
 423                 if(cmd->convert_arg<MAX_SPEED){
 424                         cmd->convert_arg=MAX_SPEED;
 425                         err++;
 426                 }
 427                 if(cmd->convert_arg>MIN_SPEED){
 428                         cmd->convert_arg=MIN_SPEED;
 429                         err++;
 430                 }
 431         }else{
 432                 /* external trigger */
 433                 /* see above */
 434                 if(cmd->convert_arg>9){
 435                         cmd->convert_arg=9;
 436                         err++;
 437                 }
 438         }
 439
 440         if(cmd->scan_end_arg!=cmd->chanlist_len){
 441                 cmd->scan_end_arg=cmd->chanlist_len;
 442                 err++;
 443         }
 444         if(cmd->stop_src==TRIG_COUNT){
 445                 if(cmd->stop_arg>0x00ffffff){
 446                         cmd->stop_arg=0x00ffffff;
 447                         err++;
 448                 }
 449         }else{
 450                 /* TRIG_NONE */
 451                 if(cmd->stop_arg!=0){
 452                         cmd->stop_arg=0;
 453                         err++;
 454                 }
 455         }
 456
 457         if(err)return 3;
 458
 459         /* step 4: fix up any arguments */
 460
 461         if(cmd->scan_begin_src==TRIG_TIMER){
 462                 tmp=cmd->scan_begin_arg;
 463                 skel_ns_to_timer(&cmd->scan_begin_arg,cmd->flags&TRIG_ROUND_MASK);
 464                 if(tmp!=cmd->scan_begin_arg)err++;
 465         }
 466         if(cmd->convert_src==TRIG_TIMER){
 467                 tmp=cmd->convert_arg;
 468                 skel_ns_to_timer(&cmd->convert_arg,cmd->flags&TRIG_ROUND_MASK);
 469                 if(tmp!=cmd->convert_arg)err++;
 470                 if(cmd->scan_begin_src==TRIG_TIMER &&
 471                   cmd->scan_begin_arg<cmd->convert_arg*cmd->scan_end_arg){
 472                         cmd->scan_begin_arg=cmd->convert_arg*cmd->scan_end_arg;
 473                         err++;
 474                 }
 475         }
 476
 477         if(err)return 4;
 478
 479         return 0;
 480 }
 481
 482 /* This function doesn't require a particular form, this is just
 483  * what happens to be used in some of the drivers.  It should
 484  * convert ns nanoseconds to a counter value suitable for programming
 485  * the device.  Also, it should adjust ns so that it cooresponds to
 486  * the actual time that the device will use. */
 487 static int skel_ns_to_timer(unsigned int *ns,int round)
 488 {
 489         /* trivial timer */
 490         /* if your timing is done through two cascaded timers, the
 491          * i8253_cascade_ns_to_timer() function in 8253.h can be
 492          * very helpful.  There are also i8254_load() and i8254_mm_load()
 493          * which can be used to load values into the ubiquitous 8254 counters
 494          */
 495
 496         return *ns;
 497 }
 498
 499
 500 static int skel_ao_winsn(comedi_device *dev,comedi_subdevice *s,comedi_insn *insn,lsampl_t *data)
 501 {
 502         int i;
 503         int chan = CR_CHAN(insn->chanspec);
 504
 505 printk("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(comedi_device *dev,comedi_subdevice *s,comedi_insn *insn,lsampl_t *data)
 521 {
 522         int i;
 523         int chan = CR_CHAN(insn->chanspec);
 524
 525         for(i=0;i<insn->n;i++)
 526                 data[i] = devpriv->ao_readback[chan];
 527
 528         return i;
 529 }
 530
 531 /* DIO devices are slightly special.  Although it is possible to
 532  * implement the insn_read/insn_write interface, it is much more
 533  * useful to applications if you implement the insn_bits interface.
 534  * This allows packed reading/writing of the DIO channels.  The
 535  * comedi core can convert between insn_bits and insn_read/write */
 536 static int skel_dio_insn_bits(comedi_device *dev,comedi_subdevice *s,
 537         comedi_insn *insn,lsampl_t *data)
 538 {
 539         if(insn->n!=2)return -EINVAL;
 540
 541         /* The insn data is a mask in data[0] and the new data
 542          * in data[1], each channel cooresponding to a bit. */
 543         if(data[0]){
 544                 s->state &= ~data[0];
 545                 s->state |= data[0]&data[1];
 546                 /* Write out the new digital output lines */
 547                 //outw(s->state,dev->iobase + SKEL_DIO);
 548         }
 549
 550         /* on return, data[1] contains the value of the digital
 551          * input and output lines. */
 552         //data[1]=inw(dev->iobase + SKEL_DIO);
 553         /* or we could just return the software copy of the output values if
 554          * it was a purely digital output subdevice */
 555         //data[1]=s->state;
 556
 557         return 2;
 558 }
 559
 560 static int skel_dio_insn_config(comedi_device *dev,comedi_subdevice *s,
 561         comedi_insn *insn,lsampl_t *data)
 562 {
 563         int chan=CR_CHAN(insn->chanspec);
 564
 565         /* The input or output configuration of each digital line is
 566          * configured by a special insn_config instruction.  chanspec
 567          * contains the channel to be changed, and data[0] contains the
 568          * value COMEDI_INPUT or COMEDI_OUTPUT. */
 569         switch(data[0])
 570         {
 571         case INSN_CONFIG_DIO_OUTPUT:
 572                 s->io_bits |= 1<<chan;
 573                 break;
 574         case INSN_CONFIG_DIO_INPUT:
 575                 s->io_bits &= ~(1<<chan);
 576                 break;
 577         case INSN_CONFIG_DIO_QUERY:
 578                 data[1] = (s->io_bits & (1 << chan)) ? COMEDI_OUTPUT : COMEDI_INPUT;
 579                 return insn->n;
 580                 break;
 581         default:
 582                 return -EINVAL;
 583                 break;
 584         }
 585         //outw(s->io_bits,dev->iobase + SKEL_DIO_CONFIG);
 586
 587         return insn->n;
 588 }
 589
 590 /*
 591  * A convenient macro that defines init_module() and cleanup_module(),
 592  * as necessary.
 593  */
 594 COMEDI_INITCLEANUP(driver_skel);
 595