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