skel.c revision 5f74ea14c07fee91d3bdbaad88bff6264c6200e6
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/* 24Driver: skel 25Description: Skeleton driver, an example for driver writers 26Devices: 27Author: ds 28Updated: Mon, 18 Mar 2002 15:34:01 -0800 29Status: works 30 31This driver is a documented example on how Comedi drivers are 32written. 33 34Configuration 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 */ 91struct skel_board { 92 const char *name; 93 int ai_chans; 94 int ai_bits; 95 int have_dio; 96}; 97 98static 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 118static 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 124MODULE_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. */ 134struct 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 */ 157static int skel_attach(struct comedi_device *dev, struct comedi_devconfig *it); 158static int skel_detach(struct comedi_device *dev); 159static 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 = ARRAY_SIZE(skel_boards), 185}; 186 187static int skel_ai_rinsn(struct comedi_device *dev, struct comedi_subdevice *s, 188 struct comedi_insn *insn, unsigned int *data); 189static int skel_ao_winsn(struct comedi_device *dev, struct comedi_subdevice *s, 190 struct comedi_insn *insn, unsigned int *data); 191static int skel_ao_rinsn(struct comedi_device *dev, struct comedi_subdevice *s, 192 struct comedi_insn *insn, unsigned int *data); 193static int skel_dio_insn_bits(struct comedi_device *dev, struct comedi_subdevice *s, 194 struct comedi_insn *insn, unsigned int *data); 195static int skel_dio_insn_config(struct comedi_device *dev, struct comedi_subdevice *s, 196 struct comedi_insn *insn, unsigned int *data); 197static int skel_ai_cmdtest(struct comedi_device *dev, struct comedi_subdevice *s, 198 struct comedi_cmd *cmd); 199static 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 */ 207static 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 */ 295static 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 */ 306static 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 /* printk() should be used instead of printk() 335 * whenever the code can be called from real-time. */ 336 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 354static 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. */ 511static 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 523static 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. */ 544static 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 */ 561static 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 586static 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 */ 621COMEDI_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) */ 625