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