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