1833 lines · plain
1===============================2PARPORT interface documentation3===============================4 5:Time-stamp: <2000-02-24 13:30:20 twaugh>6 7Described here are the following functions:8 9Global functions::10 parport_register_driver11 parport_unregister_driver12 parport_enumerate13 parport_register_device14 parport_unregister_device15 parport_claim16 parport_claim_or_block17 parport_release18 parport_yield19 parport_yield_blocking20 parport_wait_peripheral21 parport_poll_peripheral22 parport_wait_event23 parport_negotiate24 parport_read25 parport_write26 parport_open27 parport_close28 parport_device_id29 parport_device_coords30 parport_find_class31 parport_find_device32 parport_set_timeout33 34Port functions (can be overridden by low-level drivers):35 36 SPP::37 port->ops->read_data38 port->ops->write_data39 port->ops->read_status40 port->ops->read_control41 port->ops->write_control42 port->ops->frob_control43 port->ops->enable_irq44 port->ops->disable_irq45 port->ops->data_forward46 port->ops->data_reverse47 48 EPP::49 port->ops->epp_write_data50 port->ops->epp_read_data51 port->ops->epp_write_addr52 port->ops->epp_read_addr53 54 ECP::55 port->ops->ecp_write_data56 port->ops->ecp_read_data57 port->ops->ecp_write_addr58 59 Other::60 port->ops->nibble_read_data61 port->ops->byte_read_data62 port->ops->compat_write_data63 64The parport subsystem comprises ``parport`` (the core port-sharing65code), and a variety of low-level drivers that actually do the port66accesses. Each low-level driver handles a particular style of port67(PC, Amiga, and so on).68 69The parport interface to the device driver author can be broken down70into global functions and port functions.71 72The global functions are mostly for communicating between the device73driver and the parport subsystem: acquiring a list of available ports,74claiming a port for exclusive use, and so on. They also include75``generic`` functions for doing standard things that will work on any76IEEE 1284-capable architecture.77 78The port functions are provided by the low-level drivers, although the79core 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 actually84have registers exactly like that, but the PC does and this interface is85modelled after common PC implementations. Other low-level drivers may86be able to emulate most of the functionality.87 88EPP (Enhanced Parallel Port) functions are provided for reading and89writing in IEEE 1284 EPP mode, and ECP (Extended Capabilities Port)90functions are used for IEEE 1284 ECP mode. (What about BECP? Does91anyone care?)92 93Hardware assistance for EPP and/or ECP transfers may or may not be94available, and if it is available it may or may not be used. If95hardware is not used, the transfer will be software-driven. In order96to cope with peripherals that only tenuously support IEEE 1284, a97low-level driver specific function is provided, for altering 'fudge98factors'.99 100Global functions101================102 103parport_register_driver - register a device driver with parport104---------------------------------------------------------------105 106SYNOPSIS107^^^^^^^^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 121DESCRIPTION122^^^^^^^^^^^123 124In order to be notified about parallel ports when they are detected,125parport_register_driver should be called. Your driver will126immediately 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 a131function to handle ports going away due to a low-level driver132unloading. Ports will only be detached if they are not being used133(i.e. there are no devices registered on them).134 135The visible parts of the ``struct parport *`` argument given to136attach/detach are::137 138 struct parport139 {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 be151touched.152 153The ``modes`` member summarises the capabilities of the underlying154hardware. 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 are160 probably writing directly to the161 hardware.162 PARPORT_MODE_TRISTATE The data drivers may be turned off.163 This allows the data lines to be used164 for reverse (peripheral to host)165 transfers.166 PARPORT_MODE_COMPAT The hardware can assist with167 compatibility-mode (printer)168 transfers, i.e. compat_write_block.169 PARPORT_MODE_EPP The hardware can assist with EPP170 transfers.171 PARPORT_MODE_ECP The hardware can assist with ECP172 transfers.173 PARPORT_MODE_DMA The hardware can use DMA, so you might174 want to pass ISA DMA-able memory175 (i.e. memory allocated using the176 GFP_DMA flag with kmalloc) to the177 low-level driver in order to take178 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 the184hardware is capable of DMA, and PARPORT_MODE_DMA is in ``modes``, it185doesn't necessarily mean that DMA will always be used when possible.186Similarly, hardware that is capable of assisting ECP transfers won't187necessarily be used.188 189RETURN VALUE190^^^^^^^^^^^^191 192Zero on success, otherwise an error code.193 194ERRORS195^^^^^^196 197None. (Can it fail? Why return int?)198 199EXAMPLE200^^^^^^^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 ALSO236^^^^^^^^237 238parport_unregister_driver, parport_register_device, parport_enumerate239 240 241 242parport_unregister_driver - tell parport to forget about this driver243--------------------------------------------------------------------244 245SYNOPSIS246^^^^^^^^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 260DESCRIPTION261^^^^^^^^^^^262 263This tells parport not to notify the device driver of new ports or of264ports going away. Registered devices belonging to that driver are NOT265unregistered: parport_unregister_device must be used for each one.266 267EXAMPLE268^^^^^^^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 ALSO285^^^^^^^^286 287parport_register_driver, parport_enumerate288 289 290 291parport_enumerate - retrieve a list of parallel ports (DEPRECATED)292------------------------------------------------------------------293 294SYNOPSIS295^^^^^^^^296 297::298 299 #include <linux/parport.h>300 301 struct parport *parport_enumerate (void);302 303DESCRIPTION304^^^^^^^^^^^305 306Retrieve the first of a list of valid parallel ports for this machine.307Successive parallel ports can be found using the ``struct parport308*next`` element of the ``struct parport *`` that is returned. If ``next``309is NULL, there are no more parallel ports in the list. The number of310ports in the list will not exceed PARPORT_MAX.311 312RETURN VALUE313^^^^^^^^^^^^314 315A ``struct parport *`` describing a valid parallel port for the machine,316or NULL if there are none.317 318ERRORS319^^^^^^320 321This function can return NULL to indicate that there are no parallel322ports to use.323 324EXAMPLE325^^^^^^^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 344NOTES345^^^^^346 347parport_enumerate is deprecated; parport_register_driver should be348used instead.349 350SEE ALSO351^^^^^^^^352 353parport_register_driver, parport_unregister_driver354 355 356 357parport_register_device - register to use a port358------------------------------------------------359 360SYNOPSIS361^^^^^^^^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 379DESCRIPTION380^^^^^^^^^^^381 382Use this function to register your device driver on a parallel port383(``port``). Once you have done that, you will be able to use384parport_claim and parport_release in order to use the port.385 386The (``name``) argument is the name of the device that appears in /proc387filesystem. The string must be valid for the whole lifetime of the388device (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 to392indicate that you do not want a callback.393 394When the ``preempt`` function is called, it is because another driver395wishes to use the parallel port. The ``preempt`` function should return396non-zero if the parallel port cannot be released yet -- if zero is397returned, the port is lost to another driver and the port must be398re-claimed before use.399 400The ``wakeup`` function is called once another driver has released the401port and no other driver has yet claimed it. You can claim the402parallel port from within the ``wakeup`` function (in which case the403claim is guaranteed to succeed), or choose not to if you don't need it404now.405 406If an interrupt occurs on the parallel port your driver has claimed,407the ``irq`` function will be called. (Write something about shared408interrupts here.)409 410The ``handle`` is a pointer to driver-specific data, and is passed to411the callback functions.412 413``flags`` may be a bitwise combination of the following flags:414 415 ===================== =================================================416 Flag Meaning417 ===================== =================================================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 order423to 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 VALUE434^^^^^^^^^^^^435 436A ``struct pardevice *``: a handle to the registered parallel port437device that can be used for parport_claim, parport_release, etc.438 439ERRORS440^^^^^^441 442A return value of NULL indicates that there was a problem registering443a device on that port.444 445EXAMPLE446^^^^^^^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 ALSO494^^^^^^^^495 496parport_unregister_device, parport_claim497 498 499 500parport_unregister_device - finish using a port501-----------------------------------------------502 503SYNPOPSIS504 505::506 507 #include <linux/parport.h>508 509 void parport_unregister_device (struct pardevice *dev);510 511DESCRIPTION512^^^^^^^^^^^513 514This function is the opposite of parport_register_device. After using515parport_unregister_device, ``dev`` is no longer a valid device handle.516 517You should not unregister a device that is currently claimed, although518if you do it will be released automatically.519 520EXAMPLE521^^^^^^^522 523::524 525 ...526 kfree (dev->private); /* before we lose the pointer */527 parport_unregister_device (dev);528 ...529 530SEE ALSO531^^^^^^^^532 533 534parport_unregister_driver535 536parport_claim, parport_claim_or_block - claim the parallel port for a device537----------------------------------------------------------------------------538 539SYNOPSIS540^^^^^^^^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 549DESCRIPTION550^^^^^^^^^^^551 552These functions attempt to gain control of the parallel port on which553``dev`` is registered. ``parport_claim`` does not block, but554``parport_claim_or_block`` may do. (Put something here about blocking555interruptibly or non-interruptibly.)556 557You should not try to claim a port that you have already claimed.558 559RETURN VALUE560^^^^^^^^^^^^561 562A return value of zero indicates that the port was successfully563claimed, and the caller now has possession of the parallel port.564 565If ``parport_claim_or_block`` blocks before returning successfully, the566return value is positive.567 568ERRORS569^^^^^^570 571========== ==========================================================572 -EAGAIN The port is unavailable at the moment, but another attempt573 to claim it may succeed.574========== ==========================================================575 576SEE ALSO577^^^^^^^^578 579 580parport_release581 582parport_release - release the parallel port583-------------------------------------------584 585SYNOPSIS586^^^^^^^^587 588::589 590 #include <linux/parport.h>591 592 void parport_release (struct pardevice *dev);593 594DESCRIPTION595^^^^^^^^^^^596 597Once a parallel port device has been claimed, it can be released using598``parport_release``. It cannot fail, but you should not release a599device that you do not have possession of.600 601EXAMPLE602^^^^^^^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 ALSO618^^^^^^^^619 620change_mode, parport_claim, parport_claim_or_block, parport_yield621 622 623 624parport_yield, parport_yield_blocking - temporarily release a parallel port625---------------------------------------------------------------------------626 627SYNOPSIS628^^^^^^^^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 637DESCRIPTION638^^^^^^^^^^^639 640When a driver has control of a parallel port, it may allow another641driver to temporarily ``borrow`` it. ``parport_yield`` does not block;642``parport_yield_blocking`` may do.643 644RETURN VALUE645^^^^^^^^^^^^646 647A return value of zero indicates that the caller still owns the port648and the call did not block.649 650A positive return value from ``parport_yield_blocking`` indicates that651the caller still owns the port and the call blocked.652 653A return value of -EAGAIN indicates that the caller no longer owns the654port, and it must be re-claimed before use.655 656ERRORS657^^^^^^658 659========= ==========================================================660 -EAGAIN Ownership of the parallel port was given away.661========= ==========================================================662 663SEE ALSO664^^^^^^^^665 666parport_release667 668 669 670parport_wait_peripheral - wait for status lines, up to 35ms671-----------------------------------------------------------672 673SYNOPSIS674^^^^^^^^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 684DESCRIPTION685^^^^^^^^^^^686 687Wait for the status lines in mask to match the values in val.688 689RETURN VALUE690^^^^^^^^^^^^691 692======== ==========================================================693 -EINTR a signal is pending694 0 the status lines in mask have values in val695 1 timed out while waiting (35ms elapsed)696======== ==========================================================697 698SEE ALSO699^^^^^^^^700 701parport_poll_peripheral702 703 704 705parport_poll_peripheral - wait for status lines, in usec706--------------------------------------------------------707 708SYNOPSIS709^^^^^^^^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 720DESCRIPTION721^^^^^^^^^^^722 723Wait for the status lines in mask to match the values in val.724 725RETURN VALUE726^^^^^^^^^^^^727 728======== ==========================================================729 -EINTR a signal is pending730 0 the status lines in mask have values in val731 1 timed out while waiting (usec microseconds have elapsed)732======== ==========================================================733 734SEE ALSO735^^^^^^^^736 737parport_wait_peripheral738 739 740 741parport_wait_event - wait for an event on a port742------------------------------------------------743 744SYNOPSIS745^^^^^^^^746 747::748 749 #include <linux/parport.h>750 751 int parport_wait_event (struct parport *port, signed long timeout)752 753DESCRIPTION754^^^^^^^^^^^755 756Wait for an event (e.g. interrupt) on a port. The timeout is in757jiffies.758 759RETURN VALUE760^^^^^^^^^^^^761 762======= ==========================================================763 0 success764 <0 error (exit as soon as possible)765 >0 timed out766======= ==========================================================767 768parport_negotiate - perform IEEE 1284 negotiation769-------------------------------------------------770 771SYNOPSIS772^^^^^^^^773 774::775 776 #include <linux/parport.h>777 778 int parport_negotiate (struct parport *, int mode);779 780DESCRIPTION781^^^^^^^^^^^782 783Perform IEEE 1284 negotiation.784 785RETURN VALUE786^^^^^^^^^^^^787 788======= ==========================================================789 0 handshake OK; IEEE 1284 peripheral and mode available790 -1 handshake failed; peripheral not compliant (or none present)791 1 handshake OK; IEEE 1284 peripheral present but mode not792 available793======= ==========================================================794 795SEE ALSO796^^^^^^^^797 798parport_read, parport_write799 800 801 802parport_read - read data from device803------------------------------------804 805SYNOPSIS806^^^^^^^^807 808::809 810 #include <linux/parport.h>811 812 ssize_t parport_read (struct parport *, void *buf, size_t len);813 814DESCRIPTION815^^^^^^^^^^^816 817Read data from device in current IEEE 1284 transfer mode. This only818works for modes that support reverse data transfer.819 820RETURN VALUE821^^^^^^^^^^^^822 823If negative, an error code; otherwise the number of bytes transferred.824 825SEE ALSO826^^^^^^^^827 828parport_write, parport_negotiate829 830 831 832parport_write - write data to device833------------------------------------834 835SYNOPSIS836^^^^^^^^837 838::839 840 #include <linux/parport.h>841 842 ssize_t parport_write (struct parport *, const void *buf, size_t len);843 844DESCRIPTION845^^^^^^^^^^^846 847Write data to device in current IEEE 1284 transfer mode. This only848works for modes that support forward data transfer.849 850RETURN VALUE851^^^^^^^^^^^^852 853If negative, an error code; otherwise the number of bytes transferred.854 855SEE ALSO856^^^^^^^^857 858parport_read, parport_negotiate859 860 861 862parport_open - register device for particular device number863-----------------------------------------------------------864 865SYNOPSIS866^^^^^^^^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 879DESCRIPTION880^^^^^^^^^^^881 882This is like parport_register_device but takes a device number instead883of a pointer to a struct parport.884 885RETURN VALUE886^^^^^^^^^^^^887 888See parport_register_device. If no device is associated with devnum,889NULL is returned.890 891SEE ALSO892^^^^^^^^893 894parport_register_device895 896 897 898parport_close - unregister device for particular device number899--------------------------------------------------------------900 901SYNOPSIS902^^^^^^^^903 904::905 906 #include <linux/parport.h>907 908 void parport_close (struct pardevice *dev);909 910DESCRIPTION911^^^^^^^^^^^912 913This is the equivalent of parport_unregister_device for parport_open.914 915SEE ALSO916^^^^^^^^917 918parport_unregister_device, parport_open919 920 921 922parport_device_id - obtain IEEE 1284 Device ID923----------------------------------------------924 925SYNOPSIS926^^^^^^^^927 928::929 930 #include <linux/parport.h>931 932 ssize_t parport_device_id (int devnum, char *buffer, size_t len);933 934DESCRIPTION935^^^^^^^^^^^936 937Obtains the IEEE 1284 Device ID associated with a given device.938 939RETURN VALUE940^^^^^^^^^^^^941 942If negative, an error code; otherwise, the number of bytes of buffer943that contain the device ID. The format of the device ID is as944follows::945 946 [length][ID]947 948The first two bytes indicate the inclusive length of the entire Device949ID, and are in big-endian order. The ID is a sequence of pairs of the950form::951 952 key:value;953 954NOTES955^^^^^956 957Many devices have ill-formed IEEE 1284 Device IDs.958 959SEE ALSO960^^^^^^^^961 962parport_find_class, parport_find_device963 964 965 966parport_device_coords - convert device number to device coordinates967-------------------------------------------------------------------968 969SYNOPSIS970^^^^^^^^971 972::973 974 #include <linux/parport.h>975 976 int parport_device_coords (int devnum, int *parport, int *mux,977 int *daisy);978 979DESCRIPTION980^^^^^^^^^^^981 982Convert between device number (zero-based) and device coordinates983(port, multiplexor, daisy chain address).984 985RETURN VALUE986^^^^^^^^^^^^987 988Zero on success, in which case the coordinates are (``*parport``, ``*mux``,989``*daisy``).990 991SEE ALSO992^^^^^^^^993 994parport_open, parport_device_id995 996 997 998parport_find_class - find a device by its class999-----------------------------------------------1000 1001SYNOPSIS1002^^^^^^^^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_SCSIADAPTER1023 } parport_device_class;1024 1025 int parport_find_class (parport_device_class cls, int from);1026 1027DESCRIPTION1028^^^^^^^^^^^1029 1030Find a device by class. The search starts from device number from+1.1031 1032RETURN VALUE1033^^^^^^^^^^^^1034 1035The device number of the next device in that class, or -1 if no such1036device exists.1037 1038NOTES1039^^^^^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 ALSO1050^^^^^^^^1051 1052parport_find_device, parport_open, parport_device_id1053 1054 1055 1056parport_find_device - find a device by its class1057------------------------------------------------1058 1059SYNOPSIS1060^^^^^^^^1061 1062::1063 1064 #include <linux/parport.h>1065 1066 int parport_find_device (const char *mfg, const char *mdl, int from);1067 1068DESCRIPTION1069^^^^^^^^^^^1070 1071Find a device by vendor and model. The search starts from device1072number from+1.1073 1074RETURN VALUE1075^^^^^^^^^^^^1076 1077The device number of the next device matching the specifications, or1078-1 if no such device exists.1079 1080NOTES1081^^^^^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 ALSO1092^^^^^^^^1093 1094parport_find_class, parport_open, parport_device_id1095 1096 1097 1098parport_set_timeout - set the inactivity timeout1099------------------------------------------------1100 1101SYNOPSIS1102^^^^^^^^1103 1104::1105 1106 #include <linux/parport.h>1107 1108 long parport_set_timeout (struct pardevice *dev, long inactivity);1109 1110DESCRIPTION1111^^^^^^^^^^^1112 1113Set the inactivity timeout, in jiffies, for a registered device. The1114previous timeout is returned.1115 1116RETURN VALUE1117^^^^^^^^^^^^1118 1119The previous timeout, in jiffies.1120 1121NOTES1122^^^^^1123 1124Some of the port->ops functions for a parport may take time, owing to1125delays at the peripheral. After the peripheral has not responded for1126``inactivity`` jiffies, a timeout will occur and the blocking function1127will return.1128 1129A timeout of 0 jiffies is a special case: the function must do as much1130as it can without blocking or leaving the hardware in an unknown1131state. If port operations are performed from within an interrupt1132handler, for instance, a timeout of 0 jiffies should be used.1133 1134Once set for a registered device, the timeout will remain at the set1135value until set again.1136 1137SEE ALSO1138^^^^^^^^1139 1140port->ops->xxx_read/write_yyy1141 1142 1143 1144 1145PORT FUNCTIONS1146==============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 register1152---------------------------------------------1153 1154SYNOPSIS1155^^^^^^^^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 1167DESCRIPTION1168^^^^^^^^^^^1169 1170If port->modes contains the PARPORT_MODE_TRISTATE flag and the1171PARPORT_CONTROL_DIRECTION bit in the control register is set, this1172returns the value on the data pins. If port->modes contains the1173PARPORT_MODE_TRISTATE flag and the PARPORT_CONTROL_DIRECTION bit is1174not set, the return value _may_ be the last value written to the data1175register. Otherwise the return value is undefined.1176 1177SEE ALSO1178^^^^^^^^1179 1180write_data, read_status, write_control1181 1182 1183 1184port->ops->write_data - write the data register1185-----------------------------------------------1186 1187SYNOPSIS1188^^^^^^^^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 1200DESCRIPTION1201^^^^^^^^^^^1202 1203Writes to the data register. May have side-effects (a STROBE pulse,1204for instance).1205 1206SEE ALSO1207^^^^^^^^1208 1209read_data, read_status, write_control1210 1211 1212 1213port->ops->read_status - read the status register1214-------------------------------------------------1215 1216SYNOPSIS1217^^^^^^^^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 1229DESCRIPTION1230^^^^^^^^^^^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 ALSO1243^^^^^^^^1244 1245read_data, write_data, write_control1246 1247 1248 1249port->ops->read_control - read the control register1250---------------------------------------------------1251 1252SYNOPSIS1253^^^^^^^^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 1265DESCRIPTION1266^^^^^^^^^^^1267 1268Returns the last value written to the control register (either from1269write_control or frob_control). No port access is performed.1270 1271SEE ALSO1272^^^^^^^^1273 1274read_data, write_data, read_status, write_control1275 1276 1277 1278port->ops->write_control - write the control register1279-----------------------------------------------------1280 1281SYNOPSIS1282^^^^^^^^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 1294DESCRIPTION1295^^^^^^^^^^^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 ALSO1309^^^^^^^^1310 1311read_data, write_data, read_status, frob_control1312 1313 1314 1315port->ops->frob_control - write control register bits1316-----------------------------------------------------1317 1318SYNOPSIS1319^^^^^^^^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 1333DESCRIPTION1334^^^^^^^^^^^1335 1336This is equivalent to reading from the control register, masking out1337the bits in mask, exclusive-or'ing with the bits in val, and writing1338the result to the control register.1339 1340As some ports don't allow reads from the control port, a software copy1341of its contents is maintained, so frob_control is in fact only one1342port access.1343 1344SEE ALSO1345^^^^^^^^1346 1347read_data, write_data, read_status, write_control1348 1349 1350 1351port->ops->enable_irq - enable interrupt generation1352---------------------------------------------------1353 1354SYNOPSIS1355^^^^^^^^1356 1357::1358 1359 #include <linux/parport.h>1360 1361 struct parport_operations {1362 ...1363 void (*enable_irq) (struct parport *port);1364 ...1365 };1366 1367DESCRIPTION1368^^^^^^^^^^^1369 1370The parallel port hardware is instructed to generate interrupts at1371appropriate moments, although those moments are1372architecture-specific. For the PC architecture, interrupts are1373commonly generated on the rising edge of nAck.1374 1375SEE ALSO1376^^^^^^^^1377 1378disable_irq1379 1380 1381 1382port->ops->disable_irq - disable interrupt generation1383-----------------------------------------------------1384 1385SYNOPSIS1386^^^^^^^^1387 1388::1389 1390 #include <linux/parport.h>1391 1392 struct parport_operations {1393 ...1394 void (*disable_irq) (struct parport *port);1395 ...1396 };1397 1398DESCRIPTION1399^^^^^^^^^^^1400 1401The parallel port hardware is instructed not to generate interrupts.1402The interrupt itself is not masked.1403 1404SEE ALSO1405^^^^^^^^1406 1407enable_irq1408 1409 1410 1411port->ops->data_forward - enable data drivers1412---------------------------------------------1413 1414SYNOPSIS1415^^^^^^^^1416 1417::1418 1419 #include <linux/parport.h>1420 1421 struct parport_operations {1422 ...1423 void (*data_forward) (struct parport *port);1424 ...1425 };1426 1427DESCRIPTION1428^^^^^^^^^^^1429 1430Enables the data line drivers, for 8-bit host-to-peripheral1431communications.1432 1433SEE ALSO1434^^^^^^^^1435 1436data_reverse1437 1438 1439 1440port->ops->data_reverse - tristate the buffer1441---------------------------------------------1442 1443SYNOPSIS1444^^^^^^^^1445 1446::1447 1448 #include <linux/parport.h>1449 1450 struct parport_operations {1451 ...1452 void (*data_reverse) (struct parport *port);1453 ...1454 };1455 1456DESCRIPTION1457^^^^^^^^^^^1458 1459Places the data bus in a high impedance state, if port->modes has the1460PARPORT_MODE_TRISTATE bit set.1461 1462SEE ALSO1463^^^^^^^^1464 1465data_forward1466 1467 1468 1469port->ops->epp_write_data - write EPP data1470------------------------------------------1471 1472SYNOPSIS1473^^^^^^^^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 1486DESCRIPTION1487^^^^^^^^^^^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 and1496 32-bit registers. However, if a transfer1497 times out, the return value may be unreliable.1498======================= =================================================1499 1500SEE ALSO1501^^^^^^^^1502 1503epp_read_data, epp_write_addr, epp_read_addr1504 1505 1506 1507port->ops->epp_read_data - read EPP data1508----------------------------------------1509 1510SYNOPSIS1511^^^^^^^^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 1524DESCRIPTION1525^^^^^^^^^^^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 and1534 32-bit registers. However, if a transfer1535 times out, the return value may be unreliable.1536======================= =================================================1537 1538SEE ALSO1539^^^^^^^^1540 1541epp_write_data, epp_write_addr, epp_read_addr1542 1543 1544 1545port->ops->epp_write_addr - write EPP address1546---------------------------------------------1547 1548SYNOPSIS1549^^^^^^^^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 1562DESCRIPTION1563^^^^^^^^^^^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 and1572 32-bit registers. However, if a transfer1573 times out, the return value may be unreliable.1574======================= =================================================1575 1576(Does PARPORT_EPP_FAST make sense for this function?)1577 1578SEE ALSO1579^^^^^^^^1580 1581epp_write_data, epp_read_data, epp_read_addr1582 1583 1584 1585port->ops->epp_read_addr - read EPP address1586-------------------------------------------1587 1588SYNOPSIS1589^^^^^^^^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 1602DESCRIPTION1603^^^^^^^^^^^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 and1612 32-bit registers. However, if a transfer1613 times out, the return value may be unreliable.1614======================= =================================================1615 1616(Does PARPORT_EPP_FAST make sense for this function?)1617 1618SEE ALSO1619^^^^^^^^1620 1621epp_write_data, epp_read_data, epp_write_addr1622 1623 1624 1625port->ops->ecp_write_data - write a block of ECP data1626-----------------------------------------------------1627 1628SYNOPSIS1629^^^^^^^^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 1642DESCRIPTION1643^^^^^^^^^^^1644 1645Writes a block of ECP data. The ``flags`` parameter is ignored.1646 1647RETURN VALUE1648^^^^^^^^^^^^1649 1650The number of bytes written.1651 1652SEE ALSO1653^^^^^^^^1654 1655ecp_read_data, ecp_write_addr1656 1657 1658 1659port->ops->ecp_read_data - read a block of ECP data1660---------------------------------------------------1661 1662SYNOPSIS1663^^^^^^^^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 1676DESCRIPTION1677^^^^^^^^^^^1678 1679Reads a block of ECP data. The ``flags`` parameter is ignored.1680 1681RETURN VALUE1682^^^^^^^^^^^^1683 1684The number of bytes read. NB. There may be more unread data in a1685FIFO. Is there a way of stunning the FIFO to prevent this?1686 1687SEE ALSO1688^^^^^^^^1689 1690ecp_write_block, ecp_write_addr1691 1692 1693 1694port->ops->ecp_write_addr - write a block of ECP addresses1695----------------------------------------------------------1696 1697SYNOPSIS1698^^^^^^^^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 1711DESCRIPTION1712^^^^^^^^^^^1713 1714Writes a block of ECP addresses. The ``flags`` parameter is ignored.1715 1716RETURN VALUE1717^^^^^^^^^^^^1718 1719The number of bytes written.1720 1721NOTES1722^^^^^1723 1724This may use a FIFO, and if so shall not return until the FIFO is empty.1725 1726SEE ALSO1727^^^^^^^^1728 1729ecp_read_data, ecp_write_data1730 1731 1732 1733port->ops->nibble_read_data - read a block of data in nibble mode1734-----------------------------------------------------------------1735 1736SYNOPSIS1737^^^^^^^^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 1750DESCRIPTION1751^^^^^^^^^^^1752 1753Reads a block of data in nibble mode. The ``flags`` parameter is ignored.1754 1755RETURN VALUE1756^^^^^^^^^^^^1757 1758The number of whole bytes read.1759 1760SEE ALSO1761^^^^^^^^1762 1763byte_read_data, compat_write_data1764 1765 1766 1767port->ops->byte_read_data - read a block of data in byte mode1768-------------------------------------------------------------1769 1770SYNOPSIS1771^^^^^^^^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 1784DESCRIPTION1785^^^^^^^^^^^1786 1787Reads a block of data in byte mode. The ``flags`` parameter is ignored.1788 1789RETURN VALUE1790^^^^^^^^^^^^1791 1792The number of bytes read.1793 1794SEE ALSO1795^^^^^^^^1796 1797nibble_read_data, compat_write_data1798 1799 1800 1801port->ops->compat_write_data - write a block of data in compatibility mode1802--------------------------------------------------------------------------1803 1804SYNOPSIS1805^^^^^^^^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 1818DESCRIPTION1819^^^^^^^^^^^1820 1821Writes a block of data in compatibility mode. The ``flags`` parameter1822is ignored.1823 1824RETURN VALUE1825^^^^^^^^^^^^1826 1827The number of bytes written.1828 1829SEE ALSO1830^^^^^^^^1831 1832nibble_read_data, byte_read_data1833