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