Documentation/parport-lowlevel.txt

   1 PARPORT interface documentation
   2 -------------------------------
   3
   4 Time-stamp: <2000-02-24 13:30:20 twaugh>
   5
   6 Described here are the following functions:
   7
   8 Global functions:
   9   parport_register_driver
  10   parport_unregister_driver
  11   parport_enumerate
  12   parport_register_device
  13   parport_unregister_device
  14   parport_claim
  15   parport_claim_or_block
  16   parport_release
  17   parport_yield
  18   parport_yield_blocking
  19   parport_wait_peripheral
  20   parport_poll_peripheral
  21   parport_wait_event
  22   parport_negotiate
  23   parport_read
  24   parport_write
  25   parport_open
  26   parport_close
  27   parport_device_id
  28   parport_device_coords
  29   parport_find_class
  30   parport_find_device
  31   parport_set_timeout
  32
  33 Port functions (can be overridden by low-level drivers):
  34   SPP:
  35     port->ops->read_data
  36     port->ops->write_data
  37     port->ops->read_status
  38     port->ops->read_control
  39     port->ops->write_control
  40     port->ops->frob_control
  41     port->ops->enable_irq
  42     port->ops->disable_irq
  43     port->ops->data_forward
  44     port->ops->data_reverse
  45
  46   EPP:
  47     port->ops->epp_write_data
  48     port->ops->epp_read_data
  49     port->ops->epp_write_addr
  50     port->ops->epp_read_addr
  51
  52   ECP:
  53     port->ops->ecp_write_data
  54     port->ops->ecp_read_data
  55     port->ops->ecp_write_addr
  56
  57   Other:
  58     port->ops->nibble_read_data
  59     port->ops->byte_read_data
  60     port->ops->compat_write_data
  61
  62 The parport subsystem comprises 'parport' (the core port-sharing
  63 code), and a variety of low-level drivers that actually do the port
  64 accesses.  Each low-level driver handles a particular style of port
  65 (PC, Amiga, and so on).
  66
  67 The parport interface to the device driver author can be broken down
  68 into global functions and port functions.
  69
  70 The global functions are mostly for communicating between the device
  71 driver and the parport subsystem: acquiring a list of available ports,
  72 claiming a port for exclusive use, and so on.  They also include
  73 'generic' functions for doing standard things that will work on any
  74 IEEE 1284-capable architecture.
  75
  76 The port functions are provided by the low-level drivers, although the
  77 core parport module provides generic 'defaults' for some routines.
  78 The port functions can be split into three groups: SPP, EPP, and ECP.
  79
  80 SPP (Standard Parallel Port) functions modify so-called 'SPP'
  81 registers: data, status, and control.  The hardware may not actually
  82 have registers exactly like that, but the PC does and this interface is
  83 modelled after common PC implementations.  Other low-level drivers may
  84 be able to emulate most of the functionality.
  85
  86 EPP (Enhanced Parallel Port) functions are provided for reading and
  87 writing in IEEE 1284 EPP mode, and ECP (Extended Capabilities Port)
  88 functions are used for IEEE 1284 ECP mode. (What about BECP? Does
  89 anyone care?)
  90
  91 Hardware assistance for EPP and/or ECP transfers may or may not be
  92 available, and if it is available it may or may not be used.  If
  93 hardware is not used, the transfer will be software-driven.  In order
  94 to cope with peripherals that only tenuously support IEEE 1284, a
  95 low-level driver specific function is provided, for altering 'fudge
  96 factors'.
  97 \f
  98 GLOBAL FUNCTIONS
  99 ----------------
 100
 101 parport_register_driver - register a device driver with parport
 102 -----------------------
 103
 104 SYNOPSIS
 105
 106 #include <linux/parport.h>
 107
 108 struct parport_driver {
 109         const char *name;
 110         void (*attach) (struct parport *);
 111         void (*detach) (struct parport *);
 112         struct parport_driver *next;
 113 };
 114 int parport_register_driver (struct parport_driver *driver);
 115
 116 DESCRIPTION
 117
 118 In order to be notified about parallel ports when they are detected,
 119 parport_register_driver should be called.  Your driver will
 120 immediately be notified of all ports that have already been detected,
 121 and of each new port as low-level drivers are loaded.
 122
 123 A 'struct parport_driver' contains the textual name of your driver,
 124 a pointer to a function to handle new ports, and a pointer to a
 125 function to handle ports going away due to a low-level driver
 126 unloading.  Ports will only be detached if they are not being used
 127 (i.e. there are no devices registered on them).
 128
 129 The visible parts of the 'struct parport *' argument given to
 130 attach/detach are:
 131
 132 struct parport
 133 {
 134         struct parport *next; /* next parport in list */
 135         const char *name;     /* port's name */
 136         unsigned int modes;   /* bitfield of hardware modes */
 137         struct parport_device_info probe_info;
 138                               /* IEEE1284 info */
 139         int number;           /* parport index */
 140         struct parport_operations *ops;
 141         ...
 142 };
 143
 144 There are other members of the structure, but they should not be
 145 touched.
 146
 147 The 'modes' member summarises the capabilities of the underlying
 148 hardware.  It consists of flags which may be bitwise-ored together:
 149
 150   PARPORT_MODE_PCSPP            IBM PC registers are available,
 151                                 i.e. functions that act on data,
 152                                 control and status registers are
 153                                 probably writing directly to the
 154                                 hardware.
 155   PARPORT_MODE_TRISTATE         The data drivers may be turned off.
 156                                 This allows the data lines to be used
 157                                 for reverse (peripheral to host)
 158                                 transfers.
 159   PARPORT_MODE_COMPAT           The hardware can assist with
 160                                 compatibility-mode (printer)
 161                                 transfers, i.e. compat_write_block.
 162   PARPORT_MODE_EPP              The hardware can assist with EPP
 163                                 transfers.
 164   PARPORT_MODE_ECP              The hardware can assist with ECP
 165                                 transfers.
 166   PARPORT_MODE_DMA              The hardware can use DMA, so you might
 167                                 want to pass ISA DMA-able memory
 168                                 (i.e. memory allocated using the
 169                                 GFP_DMA flag with kmalloc) to the
 170                                 low-level driver in order to take
 171                                 advantage of it.
 172
 173 There may be other flags in 'modes' as well.
 174
 175 The contents of 'modes' is advisory only.  For example, if the
 176 hardware is capable of DMA, and PARPORT_MODE_DMA is in 'modes', it
 177 doesn't necessarily mean that DMA will always be used when possible.
 178 Similarly, hardware that is capable of assisting ECP transfers won't
 179 necessarily be used.
 180
 181 RETURN VALUE
 182
 183 Zero on success, otherwise an error code.
 184
 185 ERRORS
 186
 187 None. (Can it fail? Why return int?)
 188
 189 EXAMPLE
 190
 191 static void lp_attach (struct parport *port)
 192 {
 193         ...
 194         private = kmalloc (...);
 195         dev[count++] = parport_register_device (...);
 196         ...
 197 }
 198
 199 static void lp_detach (struct parport *port)
 200 {
 201         ...
 202 }
 203
 204 static struct parport_driver lp_driver = {
 205         "lp",
 206         lp_attach,
 207         lp_detach,
 208         NULL /* always put NULL here */
 209 };
 210
 211 int lp_init (void)
 212 {
 213         ...
 214         if (parport_register_driver (&lp_driver)) {
 215                 /* Failed; nothing we can do. */
 216                 return -EIO;
 217         }
 218         ...
 219 }
 220
 221 SEE ALSO
 222
 223 parport_unregister_driver, parport_register_device, parport_enumerate
 224 \f
 225 parport_unregister_driver - tell parport to forget about this driver
 226 -------------------------
 227
 228 SYNOPSIS
 229
 230 #include <linux/parport.h>
 231
 232 struct parport_driver {
 233         const char *name;
 234         void (*attach) (struct parport *);
 235         void (*detach) (struct parport *);
 236         struct parport_driver *next;
 237 };
 238 void parport_unregister_driver (struct parport_driver *driver);
 239
 240 DESCRIPTION
 241
 242 This tells parport not to notify the device driver of new ports or of
 243 ports going away.  Registered devices belonging to that driver are NOT
 244 unregistered: parport_unregister_device must be used for each one.
 245
 246 EXAMPLE
 247
 248 void cleanup_module (void)
 249 {
 250         ...
 251         /* Stop notifications. */
 252         parport_unregister_driver (&lp_driver);
 253
 254         /* Unregister devices. */
 255         for (i = 0; i < NUM_DEVS; i++)
 256                 parport_unregister_device (dev[i]);
 257         ...
 258 }
 259
 260 SEE ALSO
 261
 262 parport_register_driver, parport_enumerate
 263 \f
 264 parport_enumerate - retrieve a list of parallel ports (DEPRECATED)
 265 -----------------
 266
 267 SYNOPSIS
 268
 269 #include <linux/parport.h>
 270
 271 struct parport *parport_enumerate (void);
 272
 273 DESCRIPTION
 274
 275 Retrieve the first of a list of valid parallel ports for this machine.
 276 Successive parallel ports can be found using the 'struct parport
 277 *next' element of the 'struct parport *' that is returned.  If 'next'
 278 is NULL, there are no more parallel ports in the list.  The number of
 279 ports in the list will not exceed PARPORT_MAX.
 280
 281 RETURN VALUE
 282
 283 A 'struct parport *' describing a valid parallel port for the machine,
 284 or NULL if there are none.
 285
 286 ERRORS
 287
 288 This function can return NULL to indicate that there are no parallel
 289 ports to use.
 290
 291 EXAMPLE
 292
 293 int detect_device (void)
 294 {
 295         struct parport *port;
 296
 297         for (port = parport_enumerate ();
 298              port != NULL;
 299              port = port->next) {
 300                 /* Try to detect a device on the port... */
 301                 ...
 302              }
 303         }
 304
 305         ...
 306 }
 307
 308 NOTES
 309
 310 parport_enumerate is deprecated; parport_register_driver should be
 311 used instead.
 312
 313 SEE ALSO
 314
 315 parport_register_driver, parport_unregister_driver
 316 \f
 317 parport_register_device - register to use a port
 318 -----------------------
 319
 320 SYNOPSIS
 321
 322 #include <linux/parport.h>
 323
 324 typedef int (*preempt_func) (void *handle);
 325 typedef void (*wakeup_func) (void *handle);
 326 typedef int (*irq_func) (int irq, void *handle, struct pt_regs *);
 327
 328 struct pardevice *parport_register_device(struct parport *port,
 329                                           const char *name,
 330                                           preempt_func preempt,
 331                                           wakeup_func wakeup,
 332                                           irq_func irq,
 333                                           int flags,
 334                                           void *handle);
 335
 336 DESCRIPTION
 337
 338 Use this function to register your device driver on a parallel port
 339 ('port').  Once you have done that, you will be able to use
 340 parport_claim and parport_release in order to use the port.
 341
 342 This function will register three callbacks into your driver:
 343 'preempt', 'wakeup' and 'irq'.  Each of these may be NULL in order to
 344 indicate that you do not want a callback.
 345
 346 When the 'preempt' function is called, it is because another driver
 347 wishes to use the parallel port.  The 'preempt' function should return
 348 non-zero if the parallel port cannot be released yet -- if zero is
 349 returned, the port is lost to another driver and the port must be
 350 re-claimed before use.
 351
 352 The 'wakeup' function is called once another driver has released the
 353 port and no other driver has yet claimed it.  You can claim the
 354 parallel port from within the 'wakeup' function (in which case the
 355 claim is guaranteed to succeed), or choose not to if you don't need it
 356 now.
 357
 358 If an interrupt occurs on the parallel port your driver has claimed,
 359 the 'irq' function will be called. (Write something about shared
 360 interrupts here.)
 361
 362 The 'handle' is a pointer to driver-specific data, and is passed to
 363 the callback functions.
 364
 365 'flags' may be a bitwise combination of the following flags:
 366
 367         Flag            Meaning
 368   PARPORT_DEV_EXCL      The device cannot share the parallel port at all.
 369                         Use this only when absolutely necessary.
 370
 371 The typedefs are not actually defined -- they are only shown in order
 372 to make the function prototype more readable.
 373
 374 The visible parts of the returned 'struct pardevice' are:
 375
 376 struct pardevice {
 377         struct parport *port;   /* Associated port */
 378         void *private;          /* Device driver's 'handle' */
 379         ...
 380 };
 381
 382 RETURN VALUE
 383
 384 A 'struct pardevice *': a handle to the registered parallel port
 385 device that can be used for parport_claim, parport_release, etc.
 386
 387 ERRORS
 388
 389 A return value of NULL indicates that there was a problem registering
 390 a device on that port.
 391
 392 EXAMPLE
 393
 394 static int preempt (void *handle)
 395 {
 396         if (busy_right_now)
 397                 return 1;
 398
 399         must_reclaim_port = 1;
 400         return 0;
 401 }
 402
 403 static void wakeup (void *handle)
 404 {
 405         struct toaster *private = handle;
 406         struct pardevice *dev = private->dev;
 407         if (!dev) return; /* avoid races */
 408
 409         if (want_port)
 410                 parport_claim (dev);
 411 }
 412
 413 static int toaster_detect (struct toaster *private, struct parport *port)
 414 {
 415         private->dev = parport_register_device (port, "toaster", preempt,
 416                                                 wakeup, NULL, 0,
 417                                                 private);
 418         if (!private->dev)
 419                 /* Couldn't register with parport. */
 420                 return -EIO;
 421
 422         must_reclaim_port = 0;
 423         busy_right_now = 1;
 424         parport_claim_or_block (private->dev);
 425         ...
 426         /* Don't need the port while the toaster warms up. */
 427         busy_right_now = 0;
 428         ...
 429         busy_right_now = 1;
 430         if (must_reclaim_port) {
 431                 parport_claim_or_block (private->dev);
 432                 must_reclaim_port = 0;
 433         }
 434         ...
 435 }
 436
 437 SEE ALSO
 438
 439 parport_unregister_device, parport_claim
 440 \f
 441 parport_unregister_device - finish using a port
 442 -------------------------
 443
 444 SYNPOPSIS
 445
 446 #include <linux/parport.h>
 447
 448 void parport_unregister_device (struct pardevice *dev);
 449
 450 DESCRIPTION
 451
 452 This function is the opposite of parport_register_device.  After using
 453 parport_unregister_device, 'dev' is no longer a valid device handle.
 454
 455 You should not unregister a device that is currently claimed, although
 456 if you do it will be released automatically.
 457
 458 EXAMPLE
 459
 460         ...
 461         kfree (dev->private); /* before we lose the pointer */
 462         parport_unregister_device (dev);
 463         ...
 464
 465 SEE ALSO
 466
 467 parport_unregister_driver
 468 \f
 469 parport_claim, parport_claim_or_block - claim the parallel port for a device
 470 -------------------------------------
 471
 472 SYNOPSIS
 473
 474 #include <linux/parport.h>
 475
 476 int parport_claim (struct pardevice *dev);
 477 int parport_claim_or_block (struct pardevice *dev);
 478
 479 DESCRIPTION
 480
 481 These functions attempt to gain control of the parallel port on which
 482 'dev' is registered.  'parport_claim' does not block, but
 483 'parport_claim_or_block' may do. (Put something here about blocking
 484 interruptibly or non-interruptibly.)
 485
 486 You should not try to claim a port that you have already claimed.
 487
 488 RETURN VALUE
 489
 490 A return value of zero indicates that the port was successfully
 491 claimed, and the caller now has possession of the parallel port.
 492
 493 If 'parport_claim_or_block' blocks before returning successfully, the
 494 return value is positive.
 495
 496 ERRORS
 497
 498   -EAGAIN  The port is unavailable at the moment, but another attempt
 499            to claim it may succeed.
 500
 501 SEE ALSO
 502
 503 parport_release
 504 \f
 505 parport_release - release the parallel port
 506 ---------------
 507
 508 SYNOPSIS
 509
 510 #include <linux/parport.h>
 511
 512 void parport_release (struct pardevice *dev);
 513
 514 DESCRIPTION
 515
 516 Once a parallel port device has been claimed, it can be released using
 517 'parport_release'.  It cannot fail, but you should not release a
 518 device that you do not have possession of.
 519
 520 EXAMPLE
 521
 522 static size_t write (struct pardevice *dev, const void *buf,
 523                      size_t len)
 524 {
 525         ...
 526         written = dev->port->ops->write_ecp_data (dev->port, buf,
 527                                                   len);
 528         parport_release (dev);
 529         ...
 530 }
 531
 532
 533 SEE ALSO
 534
 535 change_mode, parport_claim, parport_claim_or_block, parport_yield
 536 \f
 537 parport_yield, parport_yield_blocking - temporarily release a parallel port
 538 -------------------------------------
 539
 540 SYNOPSIS
 541
 542 #include <linux/parport.h>
 543
 544 int parport_yield (struct pardevice *dev)
 545 int parport_yield_blocking (struct pardevice *dev);
 546
 547 DESCRIPTION
 548
 549 When a driver has control of a parallel port, it may allow another
 550 driver to temporarily 'borrow' it.  'parport_yield' does not block;
 551 'parport_yield_blocking' may do.
 552
 553 RETURN VALUE
 554
 555 A return value of zero indicates that the caller still owns the port
 556 and the call did not block.
 557
 558 A positive return value from 'parport_yield_blocking' indicates that
 559 the caller still owns the port and the call blocked.
 560
 561 A return value of -EAGAIN indicates that the caller no longer owns the
 562 port, and it must be re-claimed before use.
 563
 564 ERRORS
 565
 566   -EAGAIN  Ownership of the parallel port was given away.
 567
 568 SEE ALSO
 569
 570 parport_release
 571 \f
 572 parport_wait_peripheral - wait for status lines, up to 35ms
 573 -----------------------
 574
 575 SYNOPSIS
 576
 577 #include <linux/parport.h>
 578
 579 int parport_wait_peripheral (struct parport *port,
 580                              unsigned char mask,
 581                              unsigned char val);
 582
 583 DESCRIPTION
 584
 585 Wait for the status lines in mask to match the values in val.
 586
 587 RETURN VALUE
 588
 589  -EINTR  a signal is pending
 590       0  the status lines in mask have values in val
 591       1  timed out while waiting (35ms elapsed)
 592
 593 SEE ALSO
 594
 595 parport_poll_peripheral
 596 \f
 597 parport_poll_peripheral - wait for status lines, in usec
 598 -----------------------
 599
 600 SYNOPSIS
 601
 602 #include <linux/parport.h>
 603
 604 int parport_poll_peripheral (struct parport *port,
 605                              unsigned char mask,
 606                              unsigned char val,
 607                              int usec);
 608
 609 DESCRIPTION
 610
 611 Wait for the status lines in mask to match the values in val.
 612
 613 RETURN VALUE
 614
 615  -EINTR  a signal is pending
 616       0  the status lines in mask have values in val
 617       1  timed out while waiting (usec microseconds have elapsed)
 618
 619 SEE ALSO
 620
 621 parport_wait_peripheral
 622 \f
 623 parport_wait_event - wait for an event on a port
 624 ------------------
 625
 626 SYNOPSIS
 627
 628 #include <linux/parport.h>
 629
 630 int parport_wait_event (struct parport *port, signed long timeout)
 631
 632 DESCRIPTION
 633
 634 Wait for an event (e.g. interrupt) on a port.  The timeout is in
 635 jiffies.
 636
 637 RETURN VALUE
 638
 639       0  success
 640      <0  error (exit as soon as possible)
 641      >0  timed out
 642 \f
 643 parport_negotiate - perform IEEE 1284 negotiation
 644 -----------------
 645
 646 SYNOPSIS
 647
 648 #include <linux/parport.h>
 649
 650 int parport_negotiate (struct parport *, int mode);
 651
 652 DESCRIPTION
 653
 654 Perform IEEE 1284 negotiation.
 655
 656 RETURN VALUE
 657
 658      0  handshake OK; IEEE 1284 peripheral and mode available
 659     -1  handshake failed; peripheral not compliant (or none present)
 660      1  handshake OK; IEEE 1284 peripheral present but mode not
 661         available
 662
 663 SEE ALSO
 664
 665 parport_read, parport_write
 666 \f
 667 parport_read - read data from device
 668 ------------
 669
 670 SYNOPSIS
 671
 672 #include <linux/parport.h>
 673
 674 ssize_t parport_read (struct parport *, void *buf, size_t len);
 675
 676 DESCRIPTION
 677
 678 Read data from device in current IEEE 1284 transfer mode.  This only
 679 works for modes that support reverse data transfer.
 680
 681 RETURN VALUE
 682
 683 If negative, an error code; otherwise the number of bytes transferred.
 684
 685 SEE ALSO
 686
 687 parport_write, parport_negotiate
 688 \f
 689 parport_write - write data to device
 690 -------------
 691
 692 SYNOPSIS
 693
 694 #include <linux/parport.h>
 695
 696 ssize_t parport_write (struct parport *, const void *buf, size_t len);
 697
 698 DESCRIPTION
 699
 700 Write data to device in current IEEE 1284 transfer mode.  This only
 701 works for modes that support forward data transfer.
 702
 703 RETURN VALUE
 704
 705 If negative, an error code; otherwise the number of bytes transferred.
 706
 707 SEE ALSO
 708
 709 parport_read, parport_negotiate
 710 \f
 711 parport_open - register device for particular device number
 712 ------------
 713
 714 SYNOPSIS
 715
 716 #include <linux/parport.h>
 717
 718 struct pardevice *parport_open (int devnum, const char *name,
 719                                 int (*pf) (void *),
 720                                 void (*kf) (void *),
 721                                 void (*irqf) (int, void *,
 722                                               struct pt_regs *),
 723                                 int flags, void *handle);
 724
 725 DESCRIPTION
 726
 727 This is like parport_register_device but takes a device number instead
 728 of a pointer to a struct parport.
 729
 730 RETURN VALUE
 731
 732 See parport_register_device.  If no device is associated with devnum,
 733 NULL is returned.
 734
 735 SEE ALSO
 736
 737 parport_register_device
 738 \f
 739 parport_close - unregister device for particular device number
 740 -------------
 741
 742 SYNOPSIS
 743
 744 #include <linux/parport.h>
 745
 746 void parport_close (struct pardevice *dev);
 747
 748 DESCRIPTION
 749
 750 This is the equivalent of parport_unregister_device for parport_open.
 751
 752 SEE ALSO
 753
 754 parport_unregister_device, parport_open
 755 \f
 756 parport_device_id - obtain IEEE 1284 Device ID
 757 -----------------
 758
 759 SYNOPSIS
 760
 761 #include <linux/parport.h>
 762
 763 ssize_t parport_device_id (int devnum, char *buffer, size_t len);
 764
 765 DESCRIPTION
 766
 767 Obtains the IEEE 1284 Device ID associated with a given device.
 768
 769 RETURN VALUE
 770
 771 If negative, an error code; otherwise, the number of bytes of buffer
 772 that contain the device ID.  The format of the device ID is as
 773 follows:
 774
 775 [length][ID]
 776
 777 The first two bytes indicate the inclusive length of the entire Device
 778 ID, and are in big-endian order.  The ID is a sequence of pairs of the
 779 form:
 780
 781 key:value;
 782
 783 NOTES
 784
 785 Many devices have ill-formed IEEE 1284 Device IDs.
 786
 787 SEE ALSO
 788
 789 parport_find_class, parport_find_device
 790 \f
 791 parport_device_coords - convert device number to device coordinates
 792 ------------------
 793
 794 SYNOPSIS
 795
 796 #include <linux/parport.h>
 797
 798 int parport_device_coords (int devnum, int *parport, int *mux,
 799                            int *daisy);
 800
 801 DESCRIPTION
 802
 803 Convert between device number (zero-based) and device coordinates
 804 (port, multiplexor, daisy chain address).
 805
 806 RETURN VALUE
 807
 808 Zero on success, in which case the coordinates are (*parport, *mux,
 809 *daisy).
 810
 811 SEE ALSO
 812
 813 parport_open, parport_device_id
 814 \f
 815 parport_find_class - find a device by its class
 816 ------------------
 817
 818 SYNOPSIS
 819
 820 #include <linux/parport.h>
 821
 822 typedef enum {
 823         PARPORT_CLASS_LEGACY = 0,       /* Non-IEEE1284 device */
 824         PARPORT_CLASS_PRINTER,
 825         PARPORT_CLASS_MODEM,
 826         PARPORT_CLASS_NET,
 827         PARPORT_CLASS_HDC,              /* Hard disk controller */
 828         PARPORT_CLASS_PCMCIA,
 829         PARPORT_CLASS_MEDIA,            /* Multimedia device */
 830         PARPORT_CLASS_FDC,              /* Floppy disk controller */
 831         PARPORT_CLASS_PORTS,
 832         PARPORT_CLASS_SCANNER,
 833         PARPORT_CLASS_DIGCAM,
 834         PARPORT_CLASS_OTHER,            /* Anything else */
 835         PARPORT_CLASS_UNSPEC,           /* No CLS field in ID */
 836         PARPORT_CLASS_SCSIADAPTER
 837 } parport_device_class;
 838
 839 int parport_find_class (parport_device_class cls, int from);
 840
 841 DESCRIPTION
 842
 843 Find a device by class.  The search starts from device number from+1.
 844
 845 RETURN VALUE
 846
 847 The device number of the next device in that class, or -1 if no such
 848 device exists.
 849
 850 NOTES
 851
 852 Example usage:
 853
 854 int devnum = -1;
 855 while ((devnum = parport_find_class (PARPORT_CLASS_DIGCAM, devnum)) != -1) {
 856     struct pardevice *dev = parport_open (devnum, ...);
 857     ...
 858 }
 859
 860 SEE ALSO
 861
 862 parport_find_device, parport_open, parport_device_id
 863 \f
 864 parport_find_device - find a device by its class
 865 ------------------
 866
 867 SYNOPSIS
 868
 869 #include <linux/parport.h>
 870
 871 int parport_find_device (const char *mfg, const char *mdl, int from);
 872
 873 DESCRIPTION
 874
 875 Find a device by vendor and model.  The search starts from device
 876 number from+1.
 877
 878 RETURN VALUE
 879
 880 The device number of the next device matching the specifications, or
 881 -1 if no such device exists.
 882
 883 NOTES
 884
 885 Example usage:
 886
 887 int devnum = -1;
 888 while ((devnum = parport_find_device ("IOMEGA", "ZIP+", devnum)) != -1) {
 889     struct pardevice *dev = parport_open (devnum, ...);
 890     ...
 891 }
 892
 893 SEE ALSO
 894
 895 parport_find_class, parport_open, parport_device_id
 896 \f
 897 parport_set_timeout - set the inactivity timeout
 898 -------------------
 899
 900 SYNOPSIS
 901
 902 #include <linux/parport.h>
 903
 904 long parport_set_timeout (struct pardevice *dev, long inactivity);
 905
 906 DESCRIPTION
 907
 908 Set the inactivity timeout, in jiffies, for a registered device.  The
 909 previous timeout is returned.
 910
 911 RETURN VALUE
 912
 913 The previous timeout, in jiffies.
 914
 915 NOTES
 916
 917 Some of the port->ops functions for a parport may take time, owing to
 918 delays at the peripheral.  After the peripheral has not responded for
 919 'inactivity' jiffies, a timeout will occur and the blocking function
 920 will return.
 921
 922 A timeout of 0 jiffies is a special case: the function must do as much
 923 as it can without blocking or leaving the hardware in an unknown
 924 state.  If port operations are performed from within an interrupt
 925 handler, for instance, a timeout of 0 jiffies should be used.
 926
 927 Once set for a registered device, the timeout will remain at the set
 928 value until set again.
 929
 930 SEE ALSO
 931
 932 port->ops->xxx_read/write_yyy
 933 \f
 934 PORT FUNCTIONS
 935 --------------
 936
 937 The functions in the port->ops structure (struct parport_operations)
 938 are provided by the low-level driver responsible for that port.
 939
 940 port->ops->read_data - read the data register
 941 --------------------
 942
 943 SYNOPSIS
 944
 945 #include <linux/parport.h>
 946
 947 struct parport_operations {
 948         ...
 949         unsigned char (*read_data) (struct parport *port);
 950         ...
 951 };
 952
 953 DESCRIPTION
 954
 955 If port->modes contains the PARPORT_MODE_TRISTATE flag and the
 956 PARPORT_CONTROL_DIRECTION bit in the control register is set, this
 957 returns the value on the data pins.  If port->modes contains the
 958 PARPORT_MODE_TRISTATE flag and the PARPORT_CONTROL_DIRECTION bit is
 959 not set, the return value _may_ be the last value written to the data
 960 register.  Otherwise the return value is undefined.
 961
 962 SEE ALSO
 963
 964 write_data, read_status, write_control
 965 \f
 966 port->ops->write_data - write the data register
 967 ---------------------
 968
 969 SYNOPSIS
 970
 971 #include <linux/parport.h>
 972
 973 struct parport_operations {
 974         ...
 975         void (*write_data) (struct parport *port, unsigned char d);
 976         ...
 977 };
 978
 979 DESCRIPTION
 980
 981 Writes to the data register.  May have side-effects (a STROBE pulse,
 982 for instance).
 983
 984 SEE ALSO
 985
 986 read_data, read_status, write_control
 987 \f
 988 port->ops->read_status - read the status register
 989 ----------------------
 990
 991 SYNOPSIS
 992
 993 #include <linux/parport.h>
 994
 995 struct parport_operations {
 996         ...
 997         unsigned char (*read_status) (struct parport *port);
 998         ...
 999 };
1000
1001 DESCRIPTION
1002
1003 Reads from the status register.  This is a bitmask:
1004
1005 - PARPORT_STATUS_ERROR (printer fault, "nFault")
1006 - PARPORT_STATUS_SELECT (on-line, "Select")
1007 - PARPORT_STATUS_PAPEROUT (no paper, "PError")
1008 - PARPORT_STATUS_ACK (handshake, "nAck")
1009 - PARPORT_STATUS_BUSY (busy, "Busy")
1010
1011 There may be other bits set.
1012
1013 SEE ALSO
1014
1015 read_data, write_data, write_control
1016 \f
1017 port->ops->read_control - read the control register
1018 -----------------------
1019
1020 SYNOPSIS
1021
1022 #include <linux/parport.h>
1023
1024 struct parport_operations {
1025         ...
1026         unsigned char (*read_control) (struct parport *port);
1027         ...
1028 };
1029
1030 DESCRIPTION
1031
1032 Returns the last value written to the control register (either from
1033 write_control or frob_control).  No port access is performed.
1034
1035 SEE ALSO
1036
1037 read_data, write_data, read_status, write_control
1038 \f
1039 port->ops->write_control - write the control register
1040 ------------------------
1041
1042 SYNOPSIS
1043
1044 #include <linux/parport.h>
1045
1046 struct parport_operations {
1047         ...
1048         void (*write_control) (struct parport *port, unsigned char s);
1049         ...
1050 };
1051
1052 DESCRIPTION
1053
1054 Writes to the control register. This is a bitmask:
1055                           _______
1056 - PARPORT_CONTROL_STROBE (nStrobe)
1057                           _______
1058 - PARPORT_CONTROL_AUTOFD (nAutoFd)
1059                         _____
1060 - PARPORT_CONTROL_INIT (nInit)
1061                           _________
1062 - PARPORT_CONTROL_SELECT (nSelectIn)
1063
1064 SEE ALSO
1065
1066 read_data, write_data, read_status, frob_control
1067 \f
1068 port->ops->frob_control - write control register bits
1069 -----------------------
1070
1071 SYNOPSIS
1072
1073 #include <linux/parport.h>
1074
1075 struct parport_operations {
1076         ...
1077         unsigned char (*frob_control) (struct parport *port,
1078                                        unsigned char mask,
1079                                        unsigned char val);
1080         ...
1081 };
1082
1083 DESCRIPTION
1084
1085 This is equivalent to reading from the control register, masking out
1086 the bits in mask, exclusive-or'ing with the bits in val, and writing
1087 the result to the control register.
1088
1089 As some ports don't allow reads from the control port, a software copy
1090 of its contents is maintained, so frob_control is in fact only one
1091 port access.
1092
1093 SEE ALSO
1094
1095 read_data, write_data, read_status, write_control
1096 \f
1097 port->ops->enable_irq - enable interrupt generation
1098 ---------------------
1099
1100 SYNOPSIS
1101
1102 #include <linux/parport.h>
1103
1104 struct parport_operations {
1105         ...
1106         void (*enable_irq) (struct parport *port);
1107         ...
1108 };
1109
1110 DESCRIPTION
1111
1112 The parallel port hardware is instructed to generate interrupts at
1113 appropriate moments, although those moments are
1114 architecture-specific.  For the PC architecture, interrupts are
1115 commonly generated on the rising edge of nAck.
1116
1117 SEE ALSO
1118
1119 disable_irq
1120 \f
1121 port->ops->disable_irq - disable interrupt generation
1122 ----------------------
1123
1124 SYNOPSIS
1125
1126 #include <linux/parport.h>
1127
1128 struct parport_operations {
1129         ...
1130         void (*disable_irq) (struct parport *port);
1131         ...
1132 };
1133
1134 DESCRIPTION
1135
1136 The parallel port hardware is instructed not to generate interrupts.
1137 The interrupt itself is not masked.
1138
1139 SEE ALSO
1140
1141 enable_irq
1142 \f
1143 port->ops->data_forward - enable data drivers
1144 -----------------------
1145
1146 SYNOPSIS
1147
1148 #include <linux/parport.h>
1149
1150 struct parport_operations {
1151         ...
1152         void (*data_forward) (struct parport *port);
1153         ...
1154 };
1155
1156 DESCRIPTION
1157
1158 Enables the data line drivers, for 8-bit host-to-peripheral
1159 communications.
1160
1161 SEE ALSO
1162
1163 data_reverse
1164 \f
1165 port->ops->data_reverse - tristate the buffer
1166 -----------------------
1167
1168 SYNOPSIS
1169
1170 #include <linux/parport.h>
1171
1172 struct parport_operations {
1173         ...
1174         void (*data_reverse) (struct parport *port);
1175         ...
1176 };
1177
1178 DESCRIPTION
1179
1180 Places the data bus in a high impedance state, if port->modes has the
1181 PARPORT_MODE_TRISTATE bit set.
1182
1183 SEE ALSO
1184
1185 data_forward
1186 \f
1187 port->ops->epp_write_data - write EPP data
1188 -------------------------
1189
1190 SYNOPSIS
1191
1192 #include <linux/parport.h>
1193
1194 struct parport_operations {
1195         ...
1196         size_t (*epp_write_data) (struct parport *port, const void *buf,
1197                                   size_t len, int flags);
1198         ...
1199 };
1200
1201 DESCRIPTION
1202
1203 Writes data in EPP mode, and returns the number of bytes written.
1204
1205 The 'flags' parameter may be one or more of the following,
1206 bitwise-or'ed together:
1207
1208 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1209                         32-bit registers.  However, if a transfer
1210                         times out, the return value may be unreliable.
1211
1212 SEE ALSO
1213
1214 epp_read_data, epp_write_addr, epp_read_addr
1215 \f
1216 port->ops->epp_read_data - read EPP data
1217 ------------------------
1218
1219 SYNOPSIS
1220
1221 #include <linux/parport.h>
1222
1223 struct parport_operations {
1224         ...
1225         size_t (*epp_read_data) (struct parport *port, void *buf,
1226                                  size_t len, int flags);
1227         ...
1228 };
1229
1230 DESCRIPTION
1231
1232 Reads data in EPP mode, and returns the number of bytes read.
1233
1234 The 'flags' parameter may be one or more of the following,
1235 bitwise-or'ed together:
1236
1237 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1238                         32-bit registers.  However, if a transfer
1239                         times out, the return value may be unreliable.
1240
1241 SEE ALSO
1242
1243 epp_write_data, epp_write_addr, epp_read_addr
1244 \f
1245 port->ops->epp_write_addr - write EPP address
1246 -------------------------
1247
1248 SYNOPSIS
1249
1250 #include <linux/parport.h>
1251
1252 struct parport_operations {
1253         ...
1254         size_t (*epp_write_addr) (struct parport *port,
1255                                   const void *buf, size_t len, int flags);
1256         ...
1257 };
1258
1259 DESCRIPTION
1260
1261 Writes EPP addresses (8 bits each), and returns the number written.
1262
1263 The 'flags' parameter may be one or more of the following,
1264 bitwise-or'ed together:
1265
1266 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1267                         32-bit registers.  However, if a transfer
1268                         times out, the return value may be unreliable.
1269
1270 (Does PARPORT_EPP_FAST make sense for this function?)
1271
1272 SEE ALSO
1273
1274 epp_write_data, epp_read_data, epp_read_addr
1275 \f
1276 port->ops->epp_read_addr - read EPP address
1277 ------------------------
1278
1279 SYNOPSIS
1280
1281 #include <linux/parport.h>
1282
1283 struct parport_operations {
1284         ...
1285         size_t (*epp_read_addr) (struct parport *port, void *buf,
1286                                  size_t len, int flags);
1287         ...
1288 };
1289
1290 DESCRIPTION
1291
1292 Reads EPP addresses (8 bits each), and returns the number read.
1293
1294 The 'flags' parameter may be one or more of the following,
1295 bitwise-or'ed together:
1296
1297 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1298                         32-bit registers.  However, if a transfer
1299                         times out, the return value may be unreliable.
1300
1301 (Does PARPORT_EPP_FAST make sense for this function?)
1302
1303 SEE ALSO
1304
1305 epp_write_data, epp_read_data, epp_write_addr
1306 \f
1307 port->ops->ecp_write_data - write a block of ECP data
1308 -------------------------
1309
1310 SYNOPSIS
1311
1312 #include <linux/parport.h>
1313
1314 struct parport_operations {
1315         ...
1316         size_t (*ecp_write_data) (struct parport *port,
1317                                   const void *buf, size_t len, int flags);
1318         ...
1319 };
1320
1321 DESCRIPTION
1322
1323 Writes a block of ECP data.  The 'flags' parameter is ignored.
1324
1325 RETURN VALUE
1326
1327 The number of bytes written.
1328
1329 SEE ALSO
1330
1331 ecp_read_data, ecp_write_addr
1332 \f
1333 port->ops->ecp_read_data - read a block of ECP data
1334 ------------------------
1335
1336 SYNOPSIS
1337
1338 #include <linux/parport.h>
1339
1340 struct parport_operations {
1341         ...
1342         size_t (*ecp_read_data) (struct parport *port,
1343                                  void *buf, size_t len, int flags);
1344         ...
1345 };
1346
1347 DESCRIPTION
1348
1349 Reads a block of ECP data.  The 'flags' parameter is ignored.
1350
1351 RETURN VALUE
1352
1353 The number of bytes read.  NB. There may be more unread data in a
1354 FIFO.  Is there a way of stunning the FIFO to prevent this?
1355
1356 SEE ALSO
1357
1358 ecp_write_block, ecp_write_addr
1359 \f
1360 port->ops->ecp_write_addr - write a block of ECP addresses
1361 -------------------------
1362
1363 SYNOPSIS
1364
1365 #include <linux/parport.h>
1366
1367 struct parport_operations {
1368         ...
1369         size_t (*ecp_write_addr) (struct parport *port,
1370                                   const void *buf, size_t len, int flags);
1371         ...
1372 };
1373
1374 DESCRIPTION
1375
1376 Writes a block of ECP addresses.  The 'flags' parameter is ignored.
1377
1378 RETURN VALUE
1379
1380 The number of bytes written.
1381
1382 NOTES
1383
1384 This may use a FIFO, and if so shall not return until the FIFO is empty.
1385
1386 SEE ALSO
1387
1388 ecp_read_data, ecp_write_data
1389 \f
1390 port->ops->nibble_read_data - read a block of data in nibble mode
1391 ---------------------------
1392
1393 SYNOPSIS
1394
1395 #include <linux/parport.h>
1396
1397 struct parport_operations {
1398         ...
1399         size_t (*nibble_read_data) (struct parport *port,
1400                                     void *buf, size_t len, int flags);
1401         ...
1402 };
1403
1404 DESCRIPTION
1405
1406 Reads a block of data in nibble mode.  The 'flags' parameter is ignored.
1407
1408 RETURN VALUE
1409
1410 The number of whole bytes read.
1411
1412 SEE ALSO
1413
1414 byte_read_data, compat_write_data
1415 \f
1416 port->ops->byte_read_data - read a block of data in byte mode
1417 -------------------------
1418
1419 SYNOPSIS
1420
1421 #include <linux/parport.h>
1422
1423 struct parport_operations {
1424         ...
1425         size_t (*byte_read_data) (struct parport *port,
1426                                   void *buf, size_t len, int flags);
1427         ...
1428 };
1429
1430 DESCRIPTION
1431
1432 Reads a block of data in byte mode.  The 'flags' parameter is ignored.
1433
1434 RETURN VALUE
1435
1436 The number of bytes read.
1437
1438 SEE ALSO
1439
1440 nibble_read_data, compat_write_data
1441 \f
1442 port->ops->compat_write_data - write a block of data in compatibility mode
1443 ----------------------------
1444
1445 SYNOPSIS
1446
1447 #include <linux/parport.h>
1448
1449 struct parport_operations {
1450         ...
1451         size_t (*compat_write_data) (struct parport *port,
1452                                      const void *buf, size_t len, int flags);
1453         ...
1454 };
1455
1456 DESCRIPTION
1457
1458 Writes a block of data in compatibility mode.  The 'flags' parameter
1459 is ignored.
1460
1461 RETURN VALUE
1462
1463 The number of bytes written.
1464
1465 SEE ALSO
1466
1467 nibble_read_data, byte_read_data