1<!-- -*- sgml -*- --> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[]> 3 4<book id="ParportGuide"> 5 <bookinfo> 6 <title>The Linux 2.4 Parallel Port Subsystem</title> 7 8 <authorgroup> 9 <author> 10 <firstname>Tim</firstname> 11 <surname>Waugh</surname> 12 <affiliation> 13 <address> 14 <email>twaugh@redhat.com</email> 15 </address> 16 </affiliation> 17 </author> 18 </authorgroup> 19 20 <copyright> 21 <year>1999-2000</year> 22 <holder>Tim Waugh</holder> 23 </copyright> 24 25 <legalnotice> 26 <para> 27 Permission is granted to copy, distribute and/or modify this 28 document under the terms of the GNU Free Documentation License, 29 Version 1.1 or any later version published by the Free Software 30 Foundation; with no Invariant Sections, with no Front-Cover Texts, 31 and with no Back-Cover Texts. A copy of the license is included 32 in the section entitled "GNU Free Documentation License". 33 </para> 34 </legalnotice> 35 </bookinfo> 36 37 <toc></toc> 38 39 <chapter id="design"> 40 <title>Design goals</title> 41 42 <sect1> 43 <title>The problems</title> 44 45 <para> 46 The first parallel port support for Linux came with the line 47 printer driver, <literal>lp</literal>. The printer driver is a 48 character special device, and (in Linux 2.0) had support for 49 writing, via <function>write</function>, and configuration and 50 statistics reporting via <function>ioctl</function>. 51 </para> 52 53 <para> 54 The printer driver could be used on any computer that had an IBM 55 PC-compatible parallel port. Because some architectures have 56 parallel ports that aren't really the same as PC-style ports, 57 other variants of the printer driver were written in order to 58 support Amiga and Atari parallel ports. 59 </para> 60 61 <para> 62 When the Iomega Zip drive was released, and a driver written for 63 it, a problem became apparent. The Zip drive is a parallel port 64 device that provides a parallel port of its own---it is designed 65 to sit between a computer and an attached printer, with the 66 printer plugged into the Zip drive, and the Zip drive plugged into 67 the computer. 68 </para> 69 70 <para> 71 The problem was that, although printers and Zip drives were both 72 supported, for any given port only one could be used at a time. 73 Only one of the two drivers could be present in the kernel at 74 once. This was because of the fact that both drivers wanted to 75 drive the same hardware---the parallel port. When the printer 76 driver initialised, it would call the 77 <function>check_region</function> function to make sure that the 78 IO region associated with the parallel port was free, and then it 79 would call <function>request_region</function> to allocate it. 80 The Zip drive used the same mechanism. Whichever driver 81 initialised first would gain exclusive control of the parallel 82 port. 83 </para> 84 85 <para> 86 The only way around this problem at the time was to make sure that 87 both drivers were available as loadable kernel modules. To use 88 the printer, load the printer driver module; then for the Zip 89 drive, unload the printer driver module and load the Zip driver 90 module. 91 </para> 92 93 <para> 94 The net effect was that printing a document that was stored on a 95 Zip drive was a bit of an ordeal, at least if the Zip drive and 96 printer shared a parallel port. A better solution was 97 needed. 98 </para> 99 100 <para> 101 Zip drives are not the only devices that presented problems for 102 Linux. There are other devices with pass-through ports, for 103 example parallel port CD-ROM drives. There are also printers that 104 report their status textually rather than using simple error pins: 105 sending a command to the printer can cause it to report the number 106 of pages that it has ever printed, or how much free memory it has, 107 or whether it is running out of toner, and so on. The printer 108 driver didn't originally offer any facility for reading back this 109 information (although Carsten Gross added nibble mode readback 110 support for kernel 2.2). 111 </para> 112 113 <para> 114 The IEEE has issued a standards document called IEEE 1284, which 115 documents existing practice for parallel port communications in a 116 variety of modes. Those modes are: <quote>compatibility</quote>, 117 reverse nibble, reverse byte, ECP and EPP. Newer devices often 118 use the more advanced modes of transfer (ECP and EPP). In Linux 119 2.0, the printer driver only supported <quote>compatibility 120 mode</quote> (i.e. normal printer protocol) and reverse nibble 121 mode. 122 </para> 123 124 </sect1> 125 126 <sect1> 127 <title>The solutions</title> 128 129<!-- How they are addressed 130 - sharing model 131 - overview of structure (i.e. port drivers) in 2.2 and 2.3. 132 - IEEE 1284 stuff 133 - whether or not 'platform independence' goal was met 134 --> 135 136 <para> 137 The <literal>parport</literal> code in Linux 2.2 was designed to 138 meet these problems of architectural differences in parallel 139 ports, of port-sharing between devices with pass-through ports, 140 and of lack of support for IEEE 1284 transfer modes. 141 </para> 142 143 <!-- platform differences --> 144 145 <para> 146 There are two layers to the <literal>parport</literal> 147 subsystem, only one of which deals directly with the hardware. 148 The other layer deals with sharing and IEEE 1284 transfer modes. 149 In this way, parallel support for a particular architecture comes 150 in the form of a module which registers itself with the generic 151 sharing layer. 152 </para> 153 154 <!-- sharing model --> 155 156 <para> 157 The sharing model provided by the <literal>parport</literal> 158 subsystem is one of exclusive access. A device driver, such as 159 the printer driver, must ask the <literal>parport</literal> 160 layer for access to the port, and can only use the port once 161 access has been granted. When it has finished a 162 <quote>transaction</quote>, it can tell the 163 <literal>parport</literal> layer that it may release the port 164 for other device drivers to use. 165 </para> 166 167 <!-- talk a bit about how drivers can share devices on the same port --> 168 169 <para> 170 Devices with pass-through ports all manage to share a parallel 171 port with other devices in generally the same way. The device has 172 a latch for each of the pins on its pass-through port. The normal 173 state of affairs is pass-through mode, with the device copying the 174 signal lines between its host port and its pass-through port. 175 When the device sees a special signal from the host port, it 176 latches the pass-through port so that devices further downstream 177 don't get confused by the pass-through device's conversation with 178 the host parallel port: the device connected to the pass-through 179 port (and any devices connected in turn to it) are effectively cut 180 off from the computer. When the pass-through device has completed 181 its transaction with the computer, it enables the pass-through 182 port again. 183 </para> 184 185 <mediaobject> 186 <imageobject> 187 <imagedata fileref="parport-share" format="eps"> 188 </imageobject> 189 <imageobject> 190 <imagedata fileref="parport-share.png" format="png"> 191 </imageobject> 192 </mediaobject> 193 194 <para> 195 This technique relies on certain <quote>special signals</quote> 196 being invisible to devices that aren't watching for them. This 197 tends to mean only changing the data signals and leaving the 198 control signals alone. IEEE 1284.3 documents a standard protocol 199 for daisy-chaining devices together with parallel ports. 200 </para> 201 202 <!-- transfer modes --> 203 204 <para> 205 Support for standard transfer modes are provided as operations 206 that can be performed on a port, along with operations for setting 207 the data lines, or the control lines, or reading the status lines. 208 These operations appear to the device driver as function pointers; 209 more later. 210 </para> 211 212 </sect1> 213 214 </chapter> 215 216 <chapter id="transfermodes"> 217 <title>Standard transfer modes</title> 218 219 <!-- Defined by IEEE, but in common use (even though there are widely --> 220 <!-- varying implementations). --> 221 222 <para> 223 The <quote>standard</quote> transfer modes in use over the parallel 224 port are <quote>defined</quote> by a document called IEEE 1284. It 225 really just codifies existing practice and documents protocols (and 226 variations on protocols) that have been in common use for quite 227 some time. 228 </para> 229 230 <para> 231 The original definitions of which pin did what were set out by 232 Centronics Data Computer Corporation, but only the printer-side 233 interface signals were specified. 234 </para> 235 236 <para> 237 By the early 1980s, IBM's host-side implementation had become the 238 most widely used. New printers emerged that claimed Centronics 239 compatibility, but although compatible with Centronics they 240 differed from one another in a number of ways. 241 </para> 242 243 <para> 244 As a result of this, when IEEE 1284 was published in 1994, all that 245 it could really do was document the various protocols that are used 246 for printers (there are about six variations on a theme). 247 </para> 248 249 <para> 250 In addition to the protocol used to talk to Centronics-compatible 251 printers, IEEE 1284 defined other protocols that are used for 252 unidirectional peripheral-to-host transfers (reverse nibble and 253 reverse byte) and for fast bidirectional transfers (ECP and 254 EPP). 255 </para> 256 257 </chapter> 258 259 <chapter id="structure"> 260 <title>Structure</title> 261 262<!-- Main structure 263 - sharing core 264 - parports and their IEEE 1284 overrides 265 - IEEE 1284 transfer modes for generic ports 266 - maybe mention muxes here 267 - pardevices 268 - IEEE 1284.3 API 269 --> 270 271 <mediaobject> 272 <imageobject> 273 <imagedata fileref="parport-structure" format="eps"> 274 </imageobject> 275 <imageobject> 276 <imagedata fileref="parport-structure.png" format="png"> 277 </imageobject> 278 </mediaobject> 279 280 <sect1> 281 <title>Sharing core</title> 282 283 <para> 284 At the core of the <literal>parport</literal> subsystem is the 285 sharing mechanism (see 286 <filename>drivers/parport/share.c</filename>). This module, 287 <literal>parport</literal>, is responsible for keeping track of 288 which ports there are in the system, which device drivers might be 289 interested in new ports, and whether or not each port is available 290 for use (or if not, which driver is currently using it). 291 </para> 292 293 </sect1> 294 295 <sect1> 296 <title>Parports and their overrides</title> 297 298 <para> 299 The generic <literal>parport</literal> sharing code doesn't 300 directly handle the parallel port hardware. That is done instead 301 by <quote>low-level</quote> <literal>parport</literal> drivers. 302 The function of a low-level <literal>parport</literal> driver is 303 to detect parallel ports, register them with the sharing code, and 304 provide a list of access functions for each port. 305 </para> 306 307 <para> 308 The most basic access functions that must be provided are ones for 309 examining the status lines, for setting the control lines, and for 310 setting the data lines. There are also access functions for 311 setting the direction of the data lines; normally they are in the 312 <quote>forward</quote> direction (that is, the computer drives 313 them), but some ports allow switching to <quote>reverse</quote> 314 mode (driven by the peripheral). There is an access function for 315 examining the data lines once in reverse mode. 316 </para> 317 318 </sect1> 319 320 <sect1> 321 <title>IEEE 1284 transfer modes</title> 322 323 <para> 324 Stacked on top of the sharing mechanism, but still in the 325 <literal>parport</literal> module, are functions for 326 transferring data. They are provided for the device drivers to 327 use, and are very much like library routines. Since these 328 transfer functions are provided by the generic 329 <literal>parport</literal> core they must use the <quote>lowest 330 common denominator</quote> set of access functions: they can set 331 the control lines, examine the status lines, and use the data 332 lines. With some parallel ports the data lines can only be set 333 and not examined, and with other ports accessing the data register 334 causes control line activity; with these types of situations, the 335 IEEE 1284 transfer functions make a best effort attempt to do the 336 right thing. In some cases, it is not physically possible to use 337 particular IEEE 1284 transfer modes. 338 </para> 339 340 <para> 341 The low-level <literal>parport</literal> drivers also provide 342 IEEE 1284 transfer functions, as names in the access function 343 list. The low-level driver can just name the generic IEEE 1284 344 transfer functions for this. Some parallel ports can do IEEE 1284 345 transfers in hardware; for those ports, the low-level driver can 346 provide functions to utilise that feature. 347 </para> 348 349 </sect1> 350 351 <!-- muxes? --> 352 353 <sect1> 354 <title>Pardevices and parport_drivers</title> 355 356 <para> 357 When a parallel port device driver (such as 358 <literal>lp</literal>) initialises it tells the sharing layer 359 about itself using <function>parport_register_driver</function>. 360 The information is put into a <structname>struct 361 parport_driver</structname>, which is put into a linked list. The 362 information in a <structname>struct parport_driver</structname> 363 really just amounts to some function pointers to callbacks in the 364 parallel port device driver. 365 </para> 366 367 <para> 368 During its initialisation, a low-level port driver tells the 369 sharing layer about all the ports that it has found (using 370 <function>parport_register_port</function>), and the sharing layer 371 creates a <structname>struct parport</structname> for each of 372 them. Each <structname>struct parport</structname> contains 373 (among other things) a pointer to a <structname>struct 374 parport_operations</structname>, which is a list of function 375 pointers for the various operations that can be performed on a 376 port. You can think of a <structname>struct parport</structname> 377 as a parallel port <quote>object</quote>, if 378 <quote>object-orientated</quote> programming is your thing. The 379 <structname>parport</structname> structures are chained in a 380 linked list, whose head is <varname>portlist</varname> (in 381 <filename>drivers/parport/share.c</filename>). 382 </para> 383 384 <para> 385 Once the port has been registered, the low-level port driver 386 announces it. The <function>parport_announce_port</function> 387 function walks down the list of parallel port device drivers 388 (<structname>struct parport_driver</structname>s) calling the 389 <function>attach</function> function of each (which may block). 390 </para> 391 392 <para> 393 Similarly, a low-level port driver can undo the effect of 394 registering a port with the 395 <function>parport_unregister_port</function> function, and device 396 drivers are notified using the <function>detach</function> 397 callback (which may not block). 398 </para> 399 400 <para> 401 Device drivers can undo the effect of registering themselves with 402 the <function>parport_unregister_driver</function> 403 function. 404 </para> 405 406 </sect1> 407 408 <!-- IEEE 1284.3 API --> 409 410 <sect1> 411 <title>The IEEE 1284.3 API</title> 412 413 <para> 414 The ability to daisy-chain devices is very useful, but if every 415 device does it in a different way it could lead to lots of 416 complications for device driver writers. Fortunately, the IEEE 417 are standardising it in IEEE 1284.3, which covers daisy-chain 418 devices and port multiplexors. 419 </para> 420 421 <para> 422 At the time of writing, IEEE 1284.3 has not been published, but 423 the draft specifies the on-the-wire protocol for daisy-chaining 424 and multiplexing, and also suggests a programming interface for 425 using it. That interface (or most of it) has been implemented in 426 the <literal>parport</literal> code in Linux. 427 </para> 428 429 <para> 430 At initialisation of the parallel port <quote>bus</quote>, 431 daisy-chained devices are assigned addresses starting from zero. 432 There can only be four devices with daisy-chain addresses, plus 433 one device on the end that doesn't know about daisy-chaining and 434 thinks it's connected directly to a computer. 435 </para> 436 437 <para> 438 Another way of connecting more parallel port devices is to use a 439 multiplexor. The idea is to have a device that is connected 440 directly to a parallel port on a computer, but has a number of 441 parallel ports on the other side for other peripherals to connect 442 to (two or four ports are allowed). The multiplexor switches 443 control to different ports under software control---it is, in 444 effect, a programmable printer switch. 445 </para> 446 447 <para> 448 Combining the ability of daisy-chaining five devices together with 449 the ability to multiplex one parallel port between four gives the 450 potential to have twenty peripherals connected to the same 451 parallel port! 452 </para> 453 454 <para> 455 In addition, of course, a single computer can have multiple 456 parallel ports. So, each parallel port peripheral in the system 457 can be identified with three numbers, or co-ordinates: the 458 parallel port, the multiplexed port, and the daisy-chain 459 address. 460 </para> 461 462 <mediaobject> 463 <imageobject> 464 <imagedata fileref="parport-multi" format="eps"> 465 </imageobject> 466 <imageobject> 467 <imagedata fileref="parport-multi.png" format="png"> 468 </imageobject> 469 </mediaobject> 470 471 <para> 472 Each device in the system is numbered at initialisation (by 473 <function>parport_daisy_init</function>). You can convert between 474 this device number and its co-ordinates with 475 <function>parport_device_num</function> and 476 <function>parport_device_coords</function>. 477 </para> 478 479 <funcsynopsis> 480 <funcsynopsisinfo> 481#include <parport.h> 482 </funcsynopsisinfo> 483 <funcprototype> 484 <funcdef>int <function>parport_device_num</function></funcdef> 485 <paramdef>int <parameter>parport</parameter></paramdef> 486 <paramdef>int <parameter>mux</parameter></paramdef> 487 <paramdef>int <parameter>daisy</parameter></paramdef> 488 </funcprototype> 489 </funcsynopsis> 490 491 <funcsynopsis> 492 <funcprototype> 493 <funcdef>int <function>parport_device_coords</function></funcdef> 494 <paramdef>int <parameter>devnum</parameter></paramdef> 495 <paramdef>int *<parameter>parport</parameter></paramdef> 496 <paramdef>int *<parameter>mux</parameter></paramdef> 497 <paramdef>int *<parameter>daisy</parameter></paramdef> 498 </funcprototype> 499 </funcsynopsis> 500 501 <para> 502 Any parallel port peripheral will be connected directly or 503 indirectly to a parallel port on the system, but it won't have a 504 daisy-chain address if it does not know about daisy-chaining, and 505 it won't be connected through a multiplexor port if there is no 506 multiplexor. The special co-ordinate value 507 <constant>-1</constant> is used to indicate these cases. 508 </para> 509 510 <para> 511 Two functions are provided for finding devices based on their IEEE 512 1284 Device ID: <function>parport_find_device</function> and 513 <function>parport_find_class</function>. 514 </para> 515 516 <funcsynopsis> 517 <funcsynopsisinfo> 518#include <parport.h> 519 </funcsynopsisinfo> 520 <funcprototype> 521 <funcdef>int <function>parport_find_device</function></funcdef> 522 <paramdef>const char *<parameter>mfg</parameter></paramdef> 523 <paramdef>const char *<parameter>mdl</parameter></paramdef> 524 <paramdef>int <parameter>from</parameter></paramdef> 525 </funcprototype> 526 </funcsynopsis> 527 528 <funcsynopsis> 529 <funcprototype> 530 <funcdef>int <function>parport_find_class</function></funcdef> 531 <paramdef>parport_device_class <parameter>cls</parameter></paramdef> 532 <paramdef>int <parameter>from</parameter></paramdef> 533 </funcprototype> 534 </funcsynopsis> 535 536 <para> 537 These functions take a device number (in addition to some other 538 things), and return another device number. They walk through the 539 list of detected devices until they find one that matches the 540 requirements, and then return that device number (or 541 <constant>-1</constant> if there are no more such devices). They 542 start their search at the device after the one in the list with 543 the number given (at <parameter>from</parameter>+1, in other 544 words). 545 </para> 546 547 </sect1> 548 549 </chapter> 550 551 <chapter id="drivers"> 552 <title>Device driver's view</title> 553 554<!-- Cover: 555 - sharing interface, preemption, interrupts, wakeups... 556 - IEEE 1284.3 interface 557 - port operations 558 - why can read data but ctr is faked, etc. 559 --> 560 561<!-- I should take a look at the kernel hackers' guide bit I wrote, --> 562<!-- as that deals with a lot of this. The main complaint with it --> 563<!-- was that there weren't enough examples, but 'The printer --> 564<!-- driver' should deal with that later; might be worth mentioning --> 565<!-- in the text. --> 566 567 <para> 568 This section is written from the point of view of the device driver 569 programmer, who might be writing a driver for a printer or a 570 scanner or else anything that plugs into the parallel port. It 571 explains how to use the <literal>parport</literal> interface to 572 find parallel ports, use them, and share them with other device 573 drivers. 574 </para> 575 576 <para> 577 We'll start out with a description of the various functions that 578 can be called, and then look at a reasonably simple example of 579 their use: the printer driver. 580 </para> 581 582 <para> 583 The interactions between the device driver and the 584 <literal>parport</literal> layer are as follows. First, the 585 device driver registers its existence with 586 <literal>parport</literal>, in order to get told about any 587 parallel ports that have been (or will be) detected. When it gets 588 told about a parallel port, it then tells 589 <literal>parport</literal> that it wants to drive a device on 590 that port. Thereafter it can claim exclusive access to the port in 591 order to talk to its device. 592 </para> 593 594 <para> 595 So, the first thing for the device driver to do is tell 596 <literal>parport</literal> that it wants to know what parallel 597 ports are on the system. To do this, it uses the 598 <function>parport_register_driver</function> function: 599 </para> 600 601 <funcsynopsis> 602 <funcsynopsisinfo> 603#include <parport.h> 604 605struct parport_driver { 606 const char *name; 607 void (*attach) (struct parport *); 608 void (*detach) (struct parport *); 609 struct parport_driver *next; 610}; 611 </funcsynopsisinfo> 612 613 <funcprototype> 614 <funcdef>int <function>parport_register_driver</function></funcdef> 615 <paramdef>struct parport_driver *<parameter>driver</parameter></paramdef> 616 </funcprototype> 617 </funcsynopsis> 618 619 <para> 620 In other words, the device driver passes pointers to a couple of 621 functions to <literal>parport</literal>, and 622 <literal>parport</literal> calls <function>attach</function> for 623 each port that's detected (and <function>detach</function> for each 624 port that disappears---yes, this can happen). 625 </para> 626 627 <para> 628 The next thing that happens is that the device driver tells 629 <literal>parport</literal> that it thinks there's a device on the 630 port that it can drive. This typically will happen in the driver's 631 <function>attach</function> function, and is done with 632 <function>parport_register_device</function>: 633 </para> 634 635 <funcsynopsis> 636 <funcsynopsisinfo> 637#include <parport.h> 638 </funcsynopsisinfo> 639 <funcprototype> 640 <funcdef>struct pardevice *<function>parport_register_device</function></funcdef> 641 <paramdef>struct parport *<parameter>port</parameter></paramdef> 642 <paramdef>const char *<parameter>name</parameter></paramdef> 643 <paramdef>int <parameter>(*pf)</parameter> 644 <funcparams>void *</funcparams></paramdef> 645 <paramdef>void <parameter>(*kf)</parameter> 646 <funcparams>void *</funcparams></paramdef> 647 <paramdef>void <parameter>(*irq_func)</parameter> 648 <funcparams>int, void *, struct pt_regs *</funcparams></paramdef> 649 <paramdef>int <parameter>flags</parameter></paramdef> 650 <paramdef>void *<parameter>handle</parameter></paramdef> 651 </funcprototype> 652 </funcsynopsis> 653 654 <para> 655 The <parameter>port</parameter> comes from the parameter supplied 656 to the <function>attach</function> function when it is called, or 657 alternatively can be found from the list of detected parallel ports 658 directly with the (now deprecated) 659 <function>parport_enumerate</function> function. A better way of 660 doing this is with <function>parport_find_number</function> or 661 <function>parport_find_base</function> functions, which find ports 662 by number and by base I/O address respectively. 663 </para> 664 665 <funcsynopsis> 666 <funcsynopsisinfo> 667#include <parport.h> 668 </funcsynopsisinfo> 669 <funcprototype> 670 <funcdef>struct parport *<function>parport_find_number</function></funcdef> 671 <paramdef>int <parameter>number</parameter></paramdef> 672 </funcprototype> 673 </funcsynopsis> 674 <funcsynopsis> 675 <funcsynopsisinfo> 676#include <parport.h> 677 </funcsynopsisinfo> 678 <funcprototype> 679 <funcdef>struct parport *<function>parport_find_base</function></funcdef> 680 <paramdef>unsigned long <parameter>base</parameter></paramdef> 681 </funcprototype> 682 </funcsynopsis> 683 684 <para> 685 The next three parameters, <parameter>pf</parameter>, 686 <parameter>kf</parameter>, and <parameter>irq_func</parameter>, are 687 more function pointers. These callback functions get called under 688 various circumstances, and are always given the 689 <parameter>handle</parameter> as one of their parameters. 690 </para> 691 692 <para> 693 The preemption callback, <parameter>pf</parameter>, is called when 694 the driver has claimed access to the port but another device driver 695 wants access. If the driver is willing to let the port go, it 696 should return zero and the port will be released on its behalf. 697 There is no need to call <function>parport_release</function>. If 698 <parameter>pf</parameter> gets called at a bad time for letting the 699 port go, it should return non-zero and no action will be taken. It 700 is good manners for the driver to try to release the port at the 701 earliest opportunity after its preemption callback is 702 called. 703 </para> 704 705 <para> 706 The <quote>kick</quote> callback, <parameter>kf</parameter>, is 707 called when the port can be claimed for exclusive access; that is, 708 <function>parport_claim</function> is guaranteed to succeed inside 709 the <quote>kick</quote> callback. If the driver wants to claim the 710 port it should do so; otherwise, it need not take any 711 action. 712 </para> 713 714 <para> 715 The <parameter>irq_func</parameter> callback is called, 716 predictably, when a parallel port interrupt is generated. But it 717 is not the only code that hooks on the interrupt. The sequence is 718 this: the lowlevel driver is the one that has done 719 <function>request_irq</function>; it then does whatever 720 hardware-specific things it needs to do to the parallel port 721 hardware (for PC-style ports, there is nothing special to do); it 722 then tells the IEEE 1284 code about the interrupt, which may 723 involve reacting to an IEEE 1284 event, depending on the current 724 IEEE 1284 phase; and finally the <parameter>irq_func</parameter> 725 function is called. 726 </para> 727 728 <para> 729 None of the callback functions are allowed to block. 730 </para> 731 732 <para> 733 The <parameter>flags</parameter> are for telling 734 <literal>parport</literal> any requirements or hints that are 735 useful. The only useful value here (other than 736 <constant>0</constant>, which is the usual value) is 737 <constant>PARPORT_DEV_EXCL</constant>. The point of that flag is 738 to request exclusive access at all times---once a driver has 739 successfully called <function>parport_register_device</function> 740 with that flag, no other device drivers will be able to register 741 devices on that port (until the successful driver deregisters its 742 device, of course). 743 </para> 744 745 <para> 746 The <constant>PARPORT_DEV_EXCL</constant> flag is for preventing 747 port sharing, and so should only be used when sharing the port with 748 other device drivers is impossible and would lead to incorrect 749 behaviour. Use it sparingly! 750 </para> 751 752 <para> 753 Devices can also be registered by device drivers based on their 754 device numbers (the same device numbers as in the previous 755 section). 756 </para> 757 758 <para> 759 The <function>parport_open</function> function is similar to 760 <function>parport_register_device</function>, and 761 <function>parport_close</function> is the equivalent of 762 <function>parport_unregister_device</function>. The difference is 763 that <function>parport_open</function> takes a device number rather 764 than a pointer to a <structname>struct parport</structname>. 765 </para> 766 767 <funcsynopsis> 768 <funcsynopsisinfo> 769#include <parport.h> 770 </funcsynopsisinfo> 771 <funcprototype> 772 <funcdef>struct pardevice *<function>parport_open</function></funcdef> 773 <paramdef>int <parameter>devnum</parameter></paramdef> 774 <paramdef>const char *<parameter>name</parameter></paramdef> 775 <paramdef>int <parameter>(*pf)</parameter> 776 <funcparams>void *</funcparams></paramdef> 777 <paramdef>int <parameter>(*kf)</parameter> 778 <funcparams>void *</funcparams></paramdef> 779 <paramdef>int <parameter>(*irqf)</parameter> 780 <funcparams>int, void *, struct pt_regs *</funcparams></paramdef> 781 <paramdef>int <parameter>flags</parameter></paramdef> 782 <paramdef>void *<parameter>handle</parameter></paramdef> 783 </funcprototype> 784 </funcsynopsis> 785 786 <funcsynopsis> 787 <funcprototype> 788 <funcdef>void <function>parport_close</function></funcdef> 789 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef> 790 </funcprototype> 791 </funcsynopsis> 792 793 <funcsynopsis> 794 <funcprototype> 795 <funcdef>struct pardevice *<function>parport_register_device</function></funcdef> 796 <paramdef>struct parport *<parameter>port</parameter></paramdef> 797 <paramdef>const char *<parameter>name</parameter></paramdef> 798 <paramdef>int <parameter>(*pf)</parameter> 799 <funcparams>void *</funcparams></paramdef> 800 <paramdef>int <parameter>(*kf)</parameter> 801 <funcparams>void *</funcparams></paramdef> 802 <paramdef>int <parameter>(*irqf)</parameter> 803 <funcparams>int, void *, struct pt_regs *</funcparams></paramdef> 804 <paramdef>int <parameter>flags</parameter></paramdef> 805 <paramdef>void *<parameter>handle</parameter></paramdef> 806 </funcprototype> 807 </funcsynopsis> 808 809 <funcsynopsis> 810 <funcprototype> 811 <funcdef>void <function>parport_unregister_device</function></funcdef> 812 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef> 813 </funcprototype> 814 </funcsynopsis> 815 816 <para> 817 The intended use of these functions is during driver initialisation 818 while the driver looks for devices that it supports, as 819 demonstrated by the following code fragment: 820 </para> 821 822 <programlisting> 823 <![CDATA[ 824int devnum = -1; 825while ((devnum = parport_find_class (PARPORT_CLASS_DIGCAM, 826 devnum)) != -1) { 827 struct pardevice *dev = parport_open (devnum, ...); 828 ... 829} 830 ]]></programlisting> 831 832 <para> 833 Once your device driver has registered its device and been handed a 834 pointer to a <structname>struct pardevice</structname>, the next 835 thing you are likely to want to do is communicate with the device 836 you think is there. To do that you'll need to claim access to the 837 port. 838 </para> 839 840 <funcsynopsis> 841 <funcsynopsisinfo> 842#include <parport.h> 843 </funcsynopsisinfo> 844 <funcprototype> 845 <funcdef>int <function>parport_claim</function></funcdef> 846 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef> 847 </funcprototype> 848 </funcsynopsis> 849 850 <funcsynopsis> 851 <funcprototype> 852 <funcdef>int <function>parport_claim_or_block</function></funcdef> 853 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef> 854 </funcprototype> 855 </funcsynopsis> 856 857 <funcsynopsis> 858 <funcprototype> 859 <funcdef>void <function>parport_release</function></funcdef> 860 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef> 861 </funcprototype> 862 </funcsynopsis> 863 864 <para> 865 To claim access to the port, use <function>parport_claim</function> 866 or <function>parport_claim_or_block</function>. The first of these 867 will not block, and so can be used from interrupt context. If 868 <function>parport_claim</function> succeeds it will return zero and 869 the port is available to use. It may fail (returning non-zero) if 870 the port is in use by another driver and that driver is not willing 871 to relinquish control of the port. 872 </para> 873 874 <para> 875 The other function, <function>parport_claim_or_block</function>, 876 will block if necessary to wait for the port to be free. If it 877 slept, it returns <constant>1</constant>; if it succeeded without 878 needing to sleep it returns <constant>0</constant>. If it fails it 879 will return a negative error code. 880 </para> 881 882 <para> 883 When you have finished communicating with the device, you can give 884 up access to the port so that other drivers can communicate with 885 their devices. The <function>parport_release</function> function 886 cannot fail, but it should not be called without the port claimed. 887 Similarly, you should not try to claim the port if you already have 888 it claimed. 889 </para> 890 891 <para> 892 You may find that although there are convenient points for your 893 driver to relinquish the parallel port and allow other drivers to 894 talk to their devices, it would be preferable to keep hold of the 895 port. The printer driver only needs the port when there is data to 896 print, for example, but a network driver (such as PLIP) could be 897 sent a remote packet at any time. With PLIP, it is no huge 898 catastrophe if a network packet is dropped, since it will likely be 899 sent again, so it is possible for that kind of driver to share the 900 port with other (pass-through) devices. 901 </para> 902 903 <para> 904 The <function>parport_yield</function> and 905 <function>parport_yield_blocking</function> functions are for 906 marking points in the driver at which other drivers may claim the 907 port and use their devices. Yielding the port is similar to 908 releasing it and reclaiming it, but is more efficient because 909 nothing is done if there are no other devices needing the port. In 910 fact, nothing is done even if there are other devices waiting but 911 the current device is still within its <quote>timeslice</quote>. 912 The default timeslice is half a second, but it can be adjusted via 913 a <filename>/proc</filename> entry. 914 </para> 915 916 <funcsynopsis> 917 <funcsynopsisinfo> 918#include <parport.h> 919 </funcsynopsisinfo> 920 <funcprototype> 921 <funcdef>int <function>parport_yield</function></funcdef> 922 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef> 923 </funcprototype> 924 </funcsynopsis> 925 926 <funcsynopsis> 927 <funcprototype> 928 <funcdef>int <function>parport_yield_blocking</function></funcdef> 929 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef> 930 </funcprototype> 931 </funcsynopsis> 932 933 <para> 934 The first of these, <function>parport_yield</function>, will not 935 block but as a result may fail. The return value for 936 <function>parport_yield</function> is the same as for 937 <function>parport_claim</function>. The blocking version, 938 <function>parport_yield_blocking</function>, has the same return 939 code as <function>parport_claim_or_block</function>. 940 </para> 941 942 <para> 943 Once the port has been claimed, the device driver can use the 944 functions in the <structname>struct parport_operations</structname> 945 pointer in the <structname>struct parport</structname> it has a 946 pointer to. For example: 947 </para> 948 949 <programlisting> 950 <![CDATA[ 951port->ops->write_data (port, d); 952 ]]></programlisting> 953 954 <para> 955 Some of these operations have <quote>shortcuts</quote>. For 956 instance, <function>parport_write_data</function> is equivalent to 957 the above, but may be a little bit faster (it's a macro that in 958 some cases can avoid needing to indirect through 959 <varname>port</varname> and <varname>ops</varname>). 960 </para> 961 962 </chapter> 963 964 <chapter id="portdrivers"> 965 <title>Port drivers</title> 966 967 <!-- What port drivers are for (i.e. implementing parport objects). --> 968 969 <para> 970 To recap, then:</para> 971 972 <itemizedlist spacing=compact> 973 974 <listitem> 975 <para> 976 The device driver registers itself with <literal>parport</literal>. 977 </para> 978 </listitem> 979 980 <listitem> 981 <para> 982 A low-level driver finds a parallel port and registers it with 983 <literal>parport</literal> (these first two things can happen 984 in either order). This registration creates a <structname>struct 985 parport</structname> which is linked onto a list of known ports. 986 </para> 987 </listitem> 988 989 <listitem> 990 <para> 991 <literal>parport</literal> calls the 992 <function>attach</function> function of each registered device 993 driver, passing it the pointer to the new <structname>struct 994 parport</structname>. 995 </para> 996 </listitem> 997 998 <listitem> 999 <para> 1000 The device driver gets a handle from 1001 <literal>parport</literal>, for use with 1002 <function>parport_claim</function>/<function>release</function>. 1003 This handle takes the form of a pointer to a <structname>struct 1004 pardevice</structname>, representing a particular device on the 1005 parallel port, and is acquired using 1006 <function>parport_register_device</function>. 1007 </para> 1008 </listitem> 1009 1010 <listitem> 1011 <para> 1012 The device driver claims the port using 1013 <function>parport_claim</function> (or 1014 <function>function_claim_or_block</function>). 1015 </para> 1016 </listitem> 1017 1018 <listitem> 1019 <para> 1020 Then it goes ahead and uses the port. When finished it releases 1021 the port. 1022 </para> 1023 </listitem> 1024 1025 </itemizedlist> 1026 1027 <para> 1028 The purpose of the low-level drivers, then, is to detect parallel 1029 ports and provide methods of accessing them (i.e. implementing the 1030 operations in <structname>struct 1031 parport_operations</structname>). 1032 </para> 1033 1034 <!-- Should DocBookise this --> 1035 <para> 1036 A more complete description of which operation is supposed to do 1037 what is available in 1038 <filename>Documentation/parport-lowlevel.txt</filename>. 1039 </para> 1040 1041 </chapter> 1042 1043 <chapter id="lp"> 1044 <title>The printer driver</title> 1045 1046 <!-- Talk the reader through the printer driver. --> 1047 <!-- Could even talk about parallel port console here. --> 1048 1049 <para> 1050 The printer driver, <literal>lp</literal> is a character special 1051 device driver and a <literal>parport</literal> client. As a 1052 character special device driver it registers a <structname>struct 1053 file_operations</structname> using 1054 <function>register_chrdev</function>, with pointers filled in for 1055 <structfield>write</structfield>, <structfield>ioctl</structfield>, 1056 <structfield>open</structfield> and 1057 <structfield>release</structfield>. As a client of 1058 <literal>parport</literal>, it registers a <structname>struct 1059 parport_driver</structname> using 1060 <function>parport_register_driver</function>, so that 1061 <literal>parport</literal> knows to call 1062 <function>lp_attach</function> when a new parallel port is 1063 discovered (and <function>lp_detach</function> when it goes 1064 away). 1065 </para> 1066 1067 <para> 1068 The parallel port console functionality is also implemented in 1069 <filename>drivers/char/lp.c</filename>, but that won't be covered 1070 here (it's quite simple though). 1071 </para> 1072 1073 <para> 1074 The initialisation of the driver is quite easy to understand (see 1075 <function>lp_init</function>). The <varname>lp_table</varname> is 1076 an array of structures that contain information about a specific 1077 device (the <structname>struct pardevice</structname> associated 1078 with it, for example). That array is initialised to sensible 1079 values first of all. 1080 </para> 1081 1082 <para> 1083 Next, the printer driver calls <function>register_chrdev</function> 1084 passing it a pointer to <varname>lp_fops</varname>, which contains 1085 function pointers for the printer driver's implementation of 1086 <function>open</function>, <function>write</function>, and so on. 1087 This part is the same as for any character special device 1088 driver. 1089 </para> 1090 1091 <para> 1092 After successfully registering itself as a character special device 1093 driver, the printer driver registers itself as a 1094 <literal>parport</literal> client using 1095 <function>parport_register_driver</function>. It passes a pointer 1096 to this structure: 1097 </para> 1098 1099 <programlisting> 1100 <![CDATA[ 1101static struct parport_driver lp_driver = { 1102 "lp", 1103 lp_attach, 1104 lp_detach, 1105 NULL 1106}; 1107 ]]></programlisting> 1108 1109 <para> 1110 The <function>lp_detach</function> function is not very interesting 1111 (it does nothing); the interesting bit is 1112 <function>lp_attach</function>. What goes on here depends on 1113 whether the user supplied any parameters. The possibilities are: 1114 no parameters supplied, in which case the printer driver uses every 1115 port that is detected; the user supplied the parameter 1116 <quote>auto</quote>, in which case only ports on which the device 1117 ID string indicates a printer is present are used; or the user 1118 supplied a list of parallel port numbers to try, in which case only 1119 those are used. 1120 </para> 1121 1122 <para> 1123 For each port that the printer driver wants to use (see 1124 <function>lp_register</function>), it calls 1125 <function>parport_register_device</function> and stores the 1126 resulting <structname>struct pardevice</structname> pointer in the 1127 <varname>lp_table</varname>. If the user told it to do so, it then 1128 resets the printer. 1129 </para> 1130 1131 <para> 1132 The other interesting piece of the printer driver, from the point 1133 of view of <literal>parport</literal>, is 1134 <function>lp_write</function>. In this function, the user space 1135 process has data that it wants printed, and the printer driver 1136 hands it off to the <literal>parport</literal> code to deal with. 1137 </para> 1138 1139 <para> 1140 The <literal>parport</literal> functions it uses that we have not 1141 seen yet are <function>parport_negotiate</function>, 1142 <function>parport_set_timeout</function>, and 1143 <function>parport_write</function>. These functions are part of 1144 the IEEE 1284 implementation. 1145 </para> 1146 1147 <para> 1148 The way the IEEE 1284 protocol works is that the host tells the 1149 peripheral what transfer mode it would like to use, and the 1150 peripheral either accepts that mode or rejects it; if the mode is 1151 rejected, the host can try again with a different mode. This is 1152 the negotation phase. Once the peripheral has accepted a 1153 particular transfer mode, data transfer can begin that mode. 1154 </para> 1155 1156 <para> 1157 The particular transfer mode that the printer driver wants to use 1158 is named in IEEE 1284 as <quote>compatibility</quote> mode, and the 1159 function to request a particular mode is called 1160 <function>parport_negotiate</function>. 1161 </para> 1162 1163 <funcsynopsis> 1164 <funcsynopsisinfo> 1165#include <parport.h> 1166 </funcsynopsisinfo> 1167 <funcprototype> 1168 <funcdef>int <function>parport_negotiate</function></funcdef> 1169 <paramdef>struct parport *<parameter>port</parameter></paramdef> 1170 <paramdef>int <parameter>mode</parameter></paramdef> 1171 </funcprototype> 1172 </funcsynopsis> 1173 1174 <para> 1175 The <parameter>modes</parameter> parameter is a symbolic constant 1176 representing an IEEE 1284 mode; in this instance, it is 1177 <constant>IEEE1284_MODE_COMPAT</constant>. (Compatibility mode is 1178 slightly different to the other modes---rather than being 1179 specifically requested, it is the default until another mode is 1180 selected.) 1181 </para> 1182 1183 <para> 1184 Back to <function>lp_write</function> then. First, access to the 1185 parallel port is secured with 1186 <function>parport_claim_or_block</function>. At this point the 1187 driver might sleep, waiting for another driver (perhaps a Zip drive 1188 driver, for instance) to let the port go. Next, it goes to 1189 compatibility mode using <function>parport_negotiate</function>. 1190 </para> 1191 1192 <para> 1193 The main work is done in the write-loop. In particular, the line 1194 that hands the data over to <literal>parport</literal> reads: 1195 </para> 1196 1197<programlisting> 1198<![CDATA[ 1199 written = parport_write (port, kbuf, copy_size); 1200]]></programlisting> 1201 1202 <para> 1203 The <function>parport_write</function> function writes data to the 1204 peripheral using the currently selected transfer mode 1205 (compatibility mode, in this case). It returns the number of bytes 1206 successfully written: 1207 </para> 1208 1209 <funcsynopsis> 1210 <funcsynopsisinfo> 1211#include <parport.h> 1212 </funcsynopsisinfo> 1213 <funcprototype> 1214 <funcdef>ssize_t <function>parport_write</function></funcdef> 1215 <paramdef>struct parport *<parameter>port</parameter></paramdef> 1216 <paramdef>const void *<parameter>buf</parameter></paramdef> 1217 <paramdef>size_t <parameter>len</parameter></paramdef> 1218 </funcprototype> 1219 </funcsynopsis> 1220 1221 <funcsynopsis> 1222 <funcprototype> 1223 <funcdef>ssize_t <function>parport_read</function></funcdef> 1224 <paramdef>struct parport *<parameter>port</parameter></paramdef> 1225 <paramdef>void *<parameter>buf</parameter></paramdef> 1226 <paramdef>size_t <parameter>len</parameter></paramdef> 1227 </funcprototype> 1228 </funcsynopsis> 1229 1230 <para> 1231 (<function>parport_read</function> does what it sounds like, but 1232 only works for modes in which reverse transfer is possible. Of 1233 course, <function>parport_write</function> only works in modes in 1234 which forward transfer is possible, too.) 1235 </para> 1236 1237 <para> 1238 The <parameter>buf</parameter> pointer should be to kernel space 1239 memory, and obviously the <parameter>len</parameter> parameter 1240 specifies the amount of data to transfer. 1241 </para> 1242 1243 <para> 1244 In fact what <function>parport_write</function> does is call the 1245 appropriate block transfer function from the <structname>struct 1246 parport_operations</structname>: 1247 </para> 1248 1249 <programlisting> 1250 <![CDATA[ 1251struct parport_operations { 1252 [...] 1253 1254 /* Block read/write */ 1255 size_t (*epp_write_data) (struct parport *port, 1256 const void *buf, 1257 size_t len, int flags); 1258 size_t (*epp_read_data) (struct parport *port, 1259 void *buf, size_t len, 1260 int flags); 1261 size_t (*epp_write_addr) (struct parport *port, 1262 const void *buf, 1263 size_t len, int flags); 1264 size_t (*epp_read_addr) (struct parport *port, 1265 void *buf, size_t len, 1266 int flags); 1267 1268 size_t (*ecp_write_data) (struct parport *port, 1269 const void *buf, 1270 size_t len, int flags); 1271 size_t (*ecp_read_data) (struct parport *port, 1272 void *buf, size_t len, 1273 int flags); 1274 size_t (*ecp_write_addr) (struct parport *port, 1275 const void *buf, 1276 size_t len, int flags); 1277 1278 size_t (*compat_write_data) (struct parport *port, 1279 const void *buf, 1280 size_t len, int flags); 1281 size_t (*nibble_read_data) (struct parport *port, 1282 void *buf, size_t len, 1283 int flags); 1284 size_t (*byte_read_data) (struct parport *port, 1285 void *buf, size_t len, 1286 int flags); 1287}; 1288 ]]></programlisting> 1289 1290 <para> 1291 The transfer code in <literal>parport</literal> will tolerate a 1292 data transfer stall only for so long, and this timeout can be 1293 specified with <function>parport_set_timeout</function>, which 1294 returns the previous timeout: 1295 </para> 1296 1297 <funcsynopsis> 1298 <funcsynopsisinfo> 1299#include <parport.h> 1300 </funcsynopsisinfo> 1301 <funcprototype> 1302 <funcdef>long <function>parport_set_timeout</function></funcdef> 1303 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef> 1304 <paramdef>long <parameter>inactivity</parameter></paramdef> 1305 </funcprototype> 1306 </funcsynopsis> 1307 1308 <para> 1309 This timeout is specific to the device, and is restored on 1310 <function>parport_claim</function>. 1311 </para> 1312 1313 <para> 1314 The next function to look at is the one that allows processes to 1315 read from <filename>/dev/lp0</filename>: 1316 <function>lp_read</function>. It's short, like 1317 <function>lp_write</function>. 1318 </para> 1319 1320 <para> 1321 The semantics of reading from a line printer device are as follows: 1322 </para> 1323 1324 <itemizedlist> 1325 <listitem> 1326 <para> 1327 Switch to reverse nibble mode. 1328 </para> 1329 </listitem> 1330 1331 <listitem> 1332 <para> 1333 Try to read data from the peripheral using reverse nibble mode, 1334 until either the user-provided buffer is full or the peripheral 1335 indicates that there is no more data. 1336 </para> 1337 </listitem> 1338 1339 <listitem> 1340 <para> 1341 If there was data, stop, and return it. 1342 </para> 1343 </listitem> 1344 1345 <listitem> 1346 <para> 1347 Otherwise, we tried to read data and there was none. If the user 1348 opened the device node with the <constant>O_NONBLOCK</constant> 1349 flag, return. Otherwise wait until an interrupt occurs on the 1350 port (or a timeout elapses). 1351 </para> 1352 </listitem> 1353 </itemizedlist> 1354 1355 </chapter> 1356 1357 <chapter id="ppdev"> 1358 <title>User-level device drivers</title> 1359 1360 <!-- ppdev --> 1361 <sect1> 1362 <title>Introduction to ppdev</title> 1363 1364 <para> 1365 The printer is accessible through <filename>/dev/lp0</filename>; 1366 in the same way, the parallel port itself is accessible through 1367 <filename>/dev/parport0</filename>. The difference is in the 1368 level of control that you have over the wires in the parallel port 1369 cable. 1370 </para> 1371 1372 <para> 1373 With the printer driver, a user-space program (such as the printer 1374 spooler) can send bytes in <quote>printer protocol</quote>. 1375 Briefly, this means that for each byte, the eight data lines are 1376 set up, then a <quote>strobe</quote> line tells the printer to 1377 look at the data lines, and the printer sets an 1378 <quote>acknowledgement</quote> line to say that it got the byte. 1379 The printer driver also allows the user-space program to read 1380 bytes in <quote>nibble mode</quote>, which is a way of 1381 transferring data from the peripheral to the computer half a byte 1382 at a time (and so it's quite slow). 1383 </para> 1384 1385 <para> 1386 In contrast, the <literal>ppdev</literal> driver (accessed via 1387 <filename>/dev/parport0</filename>) allows you to: 1388 </para> 1389 1390 <itemizedlist spacing=compact> 1391 1392 <listitem> 1393 <para> 1394 examine status lines, 1395 </para> 1396 </listitem> 1397 1398 <listitem> 1399 <para> 1400 set control lines, 1401 </para> 1402 </listitem> 1403 1404 <listitem> 1405 <para> 1406 set/examine data lines (and control the direction of the data 1407 lines), 1408 </para> 1409 </listitem> 1410 1411 <listitem> 1412 <para> 1413 wait for an interrupt (triggered by one of the status lines), 1414 </para> 1415 </listitem> 1416 1417 <listitem> 1418 <para> 1419 find out how many new interrupts have occurred, 1420 </para> 1421 </listitem> 1422 1423 <listitem> 1424 <para> 1425 set up a response to an interrupt, 1426 </para> 1427 </listitem> 1428 1429 <listitem> 1430 <para> 1431 use IEEE 1284 negotiation (for telling peripheral which transfer 1432 mode, to use) 1433 </para> 1434 </listitem> 1435 1436 <listitem> 1437 <para> 1438 transfer data using a specified IEEE 1284 mode. 1439 </para> 1440 </listitem> 1441 1442 </itemizedlist> 1443 1444 </sect1> 1445 1446 <sect1> 1447 <title>User-level or kernel-level driver?</title> 1448 1449 <para> 1450 The decision of whether to choose to write a kernel-level device 1451 driver or a user-level device driver depends on several factors. 1452 One of the main ones from a practical point of view is speed: 1453 kernel-level device drivers get to run faster because they are not 1454 preemptable, unlike user-level applications. 1455 </para> 1456 1457 <para> 1458 Another factor is ease of development. It is in general easier to 1459 write a user-level driver because (a) one wrong move does not 1460 result in a crashed machine, (b) you have access to user libraries 1461 (such as the C library), and (c) debugging is easier. 1462 </para> 1463 1464 </sect1> 1465 1466 <sect1> 1467 <title>Programming interface</title> 1468 1469 <para> 1470 The <literal>ppdev</literal> interface is largely the same as that 1471 of other character special devices, in that it supports 1472 <function>open</function>, <function>close</function>, 1473 <function>read</function>, <function>write</function>, and 1474 <function>ioctl</function>. The constants for the 1475 <function>ioctl</function> commands are in 1476 <filename>include/linux/ppdev.h</filename>. 1477 </para> 1478 1479 <sect2> 1480 <title> 1481 Starting and stopping: <function>open</function> and 1482 <function>close</function> 1483 </title> 1484 1485 <para> 1486 The device node <filename>/dev/parport0</filename> represents any 1487 device that is connected to <filename>parport0</filename>, the 1488 first parallel port in the system. Each time the device node is 1489 opened, it represents (to the process doing the opening) a 1490 different device. It can be opened more than once, but only one 1491 instance can actually be in control of the parallel port at any 1492 time. A process that has opened 1493 <filename>/dev/parport0</filename> shares the parallel port in 1494 the same way as any other device driver. A user-land driver may 1495 be sharing the parallel port with in-kernel device drivers as 1496 well as other user-land drivers. 1497 </para> 1498 </sect2> 1499 1500 <sect2> 1501 <title>Control: <function>ioctl</function></title> 1502 1503 <para> 1504 Most of the control is done, naturally enough, via the 1505 <function>ioctl</function> call. Using 1506 <function>ioctl</function>, the user-land driver can control both 1507 the <literal>ppdev</literal> driver in the kernel and the 1508 physical parallel port itself. The <function>ioctl</function> 1509 call takes as parameters a file descriptor (the one returned from 1510 opening the device node), a command, and optionally (a pointer 1511 to) some data. 1512 </para> 1513 1514 <variablelist> 1515 <varlistentry><term><constant>PPCLAIM</constant></term> 1516 <listitem> 1517 1518 <para> 1519 Claims access to the port. As a user-land device driver 1520 writer, you will need to do this before you are able to 1521 actually change the state of the parallel port in any way. 1522 Note that some operations only affect the 1523 <literal>ppdev</literal> driver and not the port, such as 1524 <constant>PPSETMODE</constant>; they can be performed while 1525 access to the port is not claimed. 1526 </para> 1527 1528 </listitem></varlistentry> 1529 1530 <varlistentry><term><constant>PPEXCL</constant></term> 1531 <listitem> 1532 1533 <para> 1534 Instructs the kernel driver to forbid any sharing of the port 1535 with other drivers, i.e. it requests exclusivity. The 1536 <constant>PPEXCL</constant> command is only valid when the 1537 port is not already claimed for use, and it may mean that the 1538 next <constant>PPCLAIM</constant> <function>ioctl</function> 1539 will fail: some other driver may already have registered 1540 itself on that port. 1541 </para> 1542 1543 <para> 1544 Most device drivers don't need exclusive access to the port. 1545 It's only provided in case it is really needed, for example 1546 for devices where access to the port is required for extensive 1547 periods of time (many seconds). 1548 </para> 1549 1550 <para> 1551 Note that the <constant>PPEXCL</constant> 1552 <function>ioctl</function> doesn't actually claim the port 1553 there and then---action is deferred until the 1554 <constant>PPCLAIM</constant> <function>ioctl</function> is 1555 performed. 1556 </para> 1557 1558 </listitem></varlistentry> 1559 1560 <varlistentry><term><constant>PPRELEASE</constant></term> 1561 <listitem> 1562 1563 <para> 1564 Releases the port. Releasing the port undoes the effect of 1565 claiming the port. It allows other device drivers to talk to 1566 their devices (assuming that there are any). 1567 </para> 1568 1569 </listitem></varlistentry> 1570 1571 <varlistentry><term><constant>PPYIELD</constant></term> 1572 <listitem> 1573 1574 <para> 1575 Yields the port to another driver. This 1576 <function>ioctl</function> is a kind of short-hand for 1577 releasing the port and immediately reclaiming it. It gives 1578 other drivers a chance to talk to their devices, but 1579 afterwards claims the port back. An example of using this 1580 would be in a user-land printer driver: once a few characters 1581 have been written we could give the port to another device 1582 driver for a while, but if we still have characters to send to 1583 the printer we would want the port back as soon as possible. 1584 </para> 1585 1586 <para> 1587 It is important not to claim the parallel port for too long, 1588 as other device drivers will have no time to service their 1589 devices. If your device does not allow for parallel port 1590 sharing at all, it is better to claim the parallel port 1591 exclusively (see <constant>PPEXCL</constant>). 1592 </para> 1593 1594 </listitem></varlistentry> 1595 1596 <varlistentry><term><constant>PPNEGOT</constant></term> 1597 <listitem> 1598 1599 <para> 1600 Performs IEEE 1284 negotiation into a particular mode. 1601 Briefly, negotiation is the method by which the host and the 1602 peripheral decide on a protocol to use when transferring data. 1603 </para> 1604 1605 <para> 1606 An IEEE 1284 compliant device will start out in compatibility 1607 mode, and then the host can negotiate to another mode (such as 1608 ECP). 1609 </para> 1610 1611 <para> 1612 The <function>ioctl</function> parameter should be a pointer 1613 to an <type>int</type>; values for this are in 1614 <filename>incluce/linux/parport.h</filename> and include: 1615 </para> 1616 1617 <itemizedlist spacing=compact> 1618 <listitem><para> 1619 <constant>IEEE1284_MODE_COMPAT</constant></para></listitem> 1620 <listitem><para> 1621 <constant>IEEE1284_MODE_NIBBLE</constant></para></listitem> 1622 <listitem><para> 1623 <constant>IEEE1284_MODE_BYTE</constant></para></listitem> 1624 <listitem><para> 1625 <constant>IEEE1284_MODE_EPP</constant></para></listitem> 1626 <listitem><para> 1627 <constant>IEEE1284_MODE_ECP</constant></para></listitem> 1628 </itemizedlist> 1629 1630 <para> 1631 The <constant>PPNEGOT</constant> <function>ioctl</function> 1632 actually does two things: it performs the on-the-wire 1633 negotiation, and it sets the behaviour of subsequent 1634 <function>read</function>/<function>write</function> calls so 1635 that they use that mode (but see 1636 <constant>PPSETMODE</constant>). 1637 </para> 1638 1639 </listitem></varlistentry> 1640 1641 <varlistentry><term><constant>PPSETMODE</constant></term> 1642 <listitem> 1643 1644 <para> 1645 Sets which IEEE 1284 protocol to use for the 1646 <function>read</function> and <function>write</function> 1647 calls. 1648 </para> 1649 1650 <para> 1651 The <function>ioctl</function> parameter should be a pointer 1652 to an <type>int</type>. 1653 </para> 1654 1655 </listitem></varlistentry> 1656 1657 <varlistentry><term><constant>PPGETMODE</constant></term> 1658 <listitem> 1659 1660 <para> 1661 Retrieves the current IEEE 1284 mode to use for 1662 <function>read</function> and <function>write</function>. 1663 </para> 1664 1665 </listitem></varlistentry> 1666 1667 <varlistentry><term><constant>PPGETTIME</constant></term> 1668 <listitem> 1669 1670 <para> 1671 Retrieves the time-out value. The <function>read</function> 1672 and <function>write</function> calls will time out if the 1673 peripheral doesn't respond quickly enough. The 1674 <constant>PPGETTIME</constant> <function>ioctl</function> 1675 retrieves the length of time that the peripheral is allowed to 1676 have before giving up. 1677 </para> 1678 1679 <para> 1680 The <function>ioctl</function> parameter should be a pointer 1681 to a <structname>struct timeval</structname>. 1682 </para> 1683 1684 </listitem></varlistentry> 1685 1686 <varlistentry><term><constant>PPSETTIME</constant></term> 1687 <listitem> 1688 1689 <para> 1690 Sets the time-out. The <function>ioctl</function> parameter 1691 should be a pointer to a <structname>struct 1692 timeval</structname>. 1693 </para> 1694 1695 </listitem></varlistentry> 1696 1697 <varlistentry><term><constant>PPGETMODES</constant></term> 1698 <listitem> 1699 1700 <para> 1701 Retrieves the capabilities of the hardware (i.e. the 1702 <structfield>modes</structfield> field of the 1703 <structname>parport</structname> structure). 1704 </para> 1705 1706 </listitem></varlistentry> 1707 1708 <varlistentry><term><constant>PPSETFLAGS</constant></term> 1709 <listitem> 1710 1711 <para> 1712 Sets flags on the <literal>ppdev</literal> device which can 1713 affect future I/O operations. Available flags are: 1714 </para> 1715 1716 <itemizedlist spacing=compact> 1717 <listitem><para> 1718 <constant>PP_FASTWRITE</constant></para></listitem> 1719 <listitem><para> 1720 <constant>PP_FASTREAD</constant></para></listitem> 1721 <listitem><para> 1722 <constant>PP_W91284PIC</constant></para></listitem> 1723 </itemizedlist> 1724 1725 </listitem></varlistentry> 1726 1727 <varlistentry><term><constant>PPWCONTROL</constant></term> 1728 <listitem> 1729 1730 <para> 1731 Sets the control lines. The <function>ioctl</function> 1732 parameter is a pointer to an <type>unsigned char</type>, the 1733 bitwise OR of the control line values in 1734 <filename>include/linux/parport.h</filename>. 1735 </para> 1736 1737 </listitem></varlistentry> 1738 1739 <varlistentry><term><constant>PPRCONTROL</constant></term> 1740 <listitem> 1741 1742 <para> 1743 Returns the last value written to the control register, in the 1744 form of an <type>unsigned char</type>: each bit corresponds to 1745 a control line (although some are unused). The 1746 <function>ioctl</function> parameter should be a pointer to an 1747 <type>unsigned char</type>. 1748 </para> 1749 1750 <para> 1751 This doesn't actually touch the hardware; the last value 1752 written is remembered in software. This is because some 1753 parallel port hardware does not offer read access to the 1754 control register. 1755 </para> 1756 1757 <para> 1758 The control lines bits are defined in 1759 <filename>include/linux/parport.h</filename>: 1760 </para> 1761 1762 <itemizedlist spacing=compact> 1763 <listitem><para> 1764 <constant>PARPORT_CONTROL_STROBE</constant></para></listitem> 1765 <listitem><para> 1766 <constant>PARPORT_CONTROL_AUTOFD</constant></para></listitem> 1767 <listitem><para> 1768 <constant>PARPORT_CONTROL_SELECT</constant></para></listitem> 1769 <listitem><para> 1770 <constant>PARPORT_CONTROL_INIT</constant></para></listitem> 1771 </itemizedlist> 1772 1773 </listitem></varlistentry> 1774 1775 <varlistentry><term><constant>PPFCONTROL</constant></term> 1776 <listitem> 1777 1778 <para> 1779 Frobs the control lines. Since a common operation is to 1780 change one of the control signals while leaving the others 1781 alone, it would be quite inefficient for the user-land driver 1782 to have to use <constant>PPRCONTROL</constant>, make the 1783 change, and then use <constant>PPWCONTROL</constant>. Of 1784 course, each driver could remember what state the control 1785 lines are supposed to be in (they are never changed by 1786 anything else), but in order to provide 1787 <constant>PPRCONTROL</constant>, <literal>ppdev</literal> 1788 must remember the state of the control lines anyway. 1789 </para> 1790 1791 <para> 1792 The <constant>PPFCONTROL</constant> <function>ioctl</function> 1793 is for <quote>frobbing</quote> control lines, and is like 1794 <constant>PPWCONTROL</constant> but acts on a restricted set 1795 of control lines. The <function>ioctl</function> parameter is 1796 a pointer to a <structname>struct 1797 ppdev_frob_struct</structname>: 1798 </para> 1799 1800 <programlisting> 1801 <![CDATA[ 1802struct ppdev_frob_struct { 1803 unsigned char mask; 1804 unsigned char val; 1805}; 1806 ]]> 1807 </programlisting> 1808 1809 <para> 1810 The <structfield>mask</structfield> and 1811 <structfield>val</structfield> fields are bitwise ORs of 1812 control line names (such as in 1813 <constant>PPWCONTROL</constant>). The operation performed by 1814 <constant>PPFCONTROL</constant> is: 1815 </para> 1816 1817 <programlisting> 1818 <![CDATA[ 1819 new_ctr = (old_ctr & ~mask) | val;]]> 1820 </programlisting> 1821 1822 <para> 1823 In other words, the signals named in 1824 <structfield>mask</structfield> are set to the values in 1825 <structfield>val</structfield>. 1826 </para> 1827 1828 </listitem></varlistentry> 1829 1830 <varlistentry><term><constant>PPRSTATUS</constant></term> 1831 <listitem> 1832 1833 <para> 1834 Returns an <type>unsigned char</type> containing bits set for 1835 each status line that is set (for instance, 1836 <constant>PARPORT_STATUS_BUSY</constant>). The 1837 <function>ioctl</function> parameter should be a pointer to an 1838 <type>unsigned char</type>. 1839 </para> 1840 1841 </listitem></varlistentry> 1842 1843 <varlistentry><term><constant>PPDATADIR</constant></term> 1844 <listitem> 1845 1846 <para> 1847 Controls the data line drivers. Normally the computer's 1848 parallel port will drive the data lines, but for byte-wide 1849 transfers from the peripheral to the host it is useful to turn 1850 off those drivers and let the peripheral drive the 1851 signals. (If the drivers on the computer's parallel port are 1852 left on when this happens, the port might be damaged.) 1853 </para> 1854 1855 <para> 1856 This is only needed in conjunction with 1857 <constant>PPWDATA</constant> or 1858 <constant>PPRDATA</constant>. 1859 </para> 1860 1861 <para> 1862 The <function>ioctl</function> parameter is a pointer to an 1863 <type>int</type>. If the <type>int</type> is zero, the 1864 drivers are turned on (forward direction); if non-zero, the 1865 drivers are turned off (reverse direction). 1866 </para> 1867 1868 </listitem></varlistentry> 1869 1870 <varlistentry><term><constant>PPWDATA</constant></term> 1871 <listitem> 1872 1873 <para> 1874 Sets the data lines (if in forward mode). The 1875 <function>ioctl</function> parameter is a pointer to an 1876 <type>unsigned char</type>. 1877 </para> 1878 1879 </listitem></varlistentry> 1880 1881 <varlistentry><term><constant>PPRDATA</constant></term> 1882 <listitem> 1883 1884 <para> 1885 Reads the data lines (if in reverse mode). The 1886 <function>ioctl</function> parameter is a pointer to an 1887 <type>unsigned char</type>. 1888 </para> 1889 1890 </listitem></varlistentry> 1891 1892 <varlistentry><term><constant>PPCLRIRQ</constant></term> 1893 <listitem> 1894 1895 <para> 1896 Clears the interrupt count. The <literal>ppdev</literal> 1897 driver keeps a count of interrupts as they are triggered. 1898 <constant>PPCLRIRQ</constant> stores this count in an 1899 <type>int</type>, a pointer to which is passed in as the 1900 <function>ioctl</function> parameter. 1901 </para> 1902 1903 <para> 1904 In addition, the interrupt count is reset to zero. 1905 </para> 1906 1907 </listitem></varlistentry> 1908 1909 <varlistentry><term><constant>PPWCTLONIRQ</constant></term> 1910 <listitem> 1911 1912 <para> 1913 Set a trigger response. Afterwards when an interrupt is 1914 triggered, the interrupt handler will set the control lines as 1915 requested. The <function>ioctl</function> parameter is a 1916 pointer to an <type>unsigned char</type>, which is interpreted 1917 in the same way as for <constant>PPWCONTROL</constant>. 1918 </para> 1919 1920 <para> 1921 The reason for this <function>ioctl</function> is simply 1922 speed. Without this <function>ioctl</function>, responding to 1923 an interrupt would start in the interrupt handler, switch 1924 context to the user-land driver via <function>poll</function> 1925 or <function>select</function>, and then switch context back 1926 to the kernel in order to handle 1927 <constant>PPWCONTROL</constant>. Doing the whole lot in the 1928 interrupt handler is a lot faster. 1929 </para> 1930 1931 </listitem></varlistentry> 1932 1933 <!-- PPSETPHASE? --> 1934 1935 </variablelist> 1936 1937 </sect2> 1938 1939 <sect2> 1940 <title>Transferring data: <function>read</function> and 1941 <function>write</function></title> 1942 1943 <para> 1944 Transferring data using <function>read</function> and 1945 <function>write</function> is straightforward. The data is 1946 transferring using the current IEEE 1284 mode (see the 1947 <constant>PPSETMODE</constant> <function>ioctl</function>). For 1948 modes which can only transfer data in one direction, only the 1949 appropriate function will work, of course. 1950 </para> 1951 </sect2> 1952 1953 <sect2> 1954 <title>Waiting for events: <function>poll</function> and 1955 <function>select</function></title> 1956 1957 <para> 1958 The <literal>ppdev</literal> driver provides user-land device 1959 drivers with the ability to wait for interrupts, and this is done 1960 using <function>poll</function> (and <function>select</function>, 1961 which is implemented in terms of <function>poll</function>). 1962 </para> 1963 1964 <para> 1965 When a user-land device driver wants to wait for an interrupt, it 1966 sleeps with <function>poll</function>. When the interrupt 1967 arrives, <literal>ppdev</literal> wakes it up (with a 1968 <quote>read</quote> event, although strictly speaking there is 1969 nothing to actually <function>read</function>). 1970 </para> 1971 1972 </sect2> 1973 1974 </sect1> 1975 1976 <sect1> 1977 <title>Examples</title> 1978 1979 <para> 1980 Presented here are two demonstrations of how to write a simple 1981 printer driver for <literal>ppdev</literal>. Firstly we will 1982 use the <function>write</function> function, and after that we 1983 will drive the control and data lines directly. 1984 </para> 1985 1986 <para> 1987 The first thing to do is to actually open the device. 1988 </para> 1989 1990 <programlisting><![CDATA[ 1991int drive_printer (const char *name) 1992{ 1993 int fd; 1994 int mode; /* We'll need this later. */ 1995 1996 fd = open (name, O_RDWR); 1997 if (fd == -1) { 1998 perror ("open"); 1999 return 1; 2000 } 2001 ]]></programlisting> 2002 2003 <para> 2004 Here <varname>name</varname> should be something along the lines 2005 of <filename>"/dev/parport0"</filename>. (If you don't have any 2006 <filename>/dev/parport</filename> files, you can make them with 2007 <command>mknod</command>; they are character special device nodes 2008 with major 99.) 2009 </para> 2010 2011 <para> 2012 In order to do anything with the port we need to claim access to 2013 it. 2014 </para> 2015 2016 <programlisting><![CDATA[ 2017 if (ioctl (fd, PPCLAIM)) { 2018 perror ("PPCLAIM"); 2019 close (fd); 2020 return 1; 2021 } 2022 ]]></programlisting> 2023 2024 <para> 2025 Our printer driver will copy its input (from 2026 <varname>stdin</varname>) to the printer, and it can do that it 2027 one of two ways. The first way is to hand it all off to the 2028 kernel driver, with the knowledge that the protocol that the 2029 printer speaks is IEEE 1284's <quote>compatibility</quote> 2030 mode. 2031 </para> 2032 2033 <programlisting><![CDATA[ 2034 /* Switch to compatibility mode. (In fact we don't need 2035 * to do this, since we start off in compatibility mode 2036 * anyway, but this demonstrates PPNEGOT.) 2037 mode = IEEE1284_MODE_COMPAT; 2038 if (ioctl (fd, PPNEGOT, &mode)) { 2039 perror ("PPNEGOT"); 2040 close (fd); 2041 return 1; 2042 } 2043 2044 for (;;) { 2045 char buffer[1000]; 2046 char *ptr = buffer; 2047 size_t got; 2048 2049 got = read (0 /* stdin */, buffer, 1000); 2050 if (got < 0) { 2051 perror ("read"); 2052 close (fd); 2053 return 1; 2054 } 2055 2056 if (got == 0) 2057 /* End of input */ 2058 break; 2059 2060 while (got > 0) { 2061 int written = write_printer (fd, ptr, got); 2062 2063 if (written < 0) { 2064 perror ("write"); 2065 close (fd); 2066 return 1; 2067 } 2068 2069 ptr += written; 2070 got -= written; 2071 } 2072 } 2073 ]]></programlisting> 2074 2075 <para> 2076 The <function>write_printer</function> function is not pictured 2077 above. This is because the main loop that is shown can be used 2078 for both methods of driving the printer. Here is one 2079 implementation of <function>write_printer</function>: 2080 </para> 2081 2082 <programlisting><![CDATA[ 2083ssize_t write_printer (int fd, const void *ptr, size_t count) 2084{ 2085 return write (fd, ptr, count); 2086} 2087 ]]></programlisting> 2088 2089 <para> 2090 We hand the data to the kernel-level driver (using 2091 <function>write</function>) and it handles the printer 2092 protocol. 2093 </para> 2094 2095 <para> 2096 Now let's do it the hard way! In this particular example there is 2097 no practical reason to do anything other than just call 2098 <function>write</function>, because we know that the printer talks 2099 an IEEE 1284 protocol. On the other hand, this particular example 2100 does not even need a user-land driver since there is already a 2101 kernel-level one; for the purpose of this discussion, try to 2102 imagine that the printer speaks a protocol that is not already 2103 implemented under Linux. 2104 </para> 2105 2106 <para> 2107 So, here is the alternative implementation of 2108 <function>write_printer</function> (for brevity, error checking 2109 has been omitted): 2110 </para> 2111 2112 <programlisting><![CDATA[ 2113ssize_t write_printer (int fd, const void *ptr, size_t count) 2114{ 2115 ssize_t wrote = 0; 2116 2117 while (wrote < count) { 2118 unsigned char status, control, data; 2119 unsigned char mask = (PARPORT_STATUS_ERROR 2120 | PARPORT_STATUS_BUSY); 2121 unsigned char val = (PARPORT_STATUS_ERROR 2122 | PARPORT_STATUS_BUSY); 2123 struct ppdev_frob_struct frob; 2124 struct timespec ts; 2125 2126 /* Wait for printer to be ready */ 2127 for (;;) { 2128 ioctl (fd, PPRSTATUS, &status); 2129 2130 if ((status & mask) == val) 2131 break; 2132 2133 ioctl (fd, PPRELEASE); 2134 sleep (1); 2135 ioctl (fd, PPCLAIM); 2136 } 2137 2138 /* Set the data lines */ 2139 data = * ((char *) ptr)++; 2140 ioctl (fd, PPWDATA, &data); 2141 2142 /* Delay for a bit */ 2143 ts.tv_sec = 0; 2144 ts.tv_nsec = 1000; 2145 nanosleep (&ts, NULL); 2146 2147 /* Pulse strobe */ 2148 frob.mask = PARPORT_CONTROL_STROBE; 2149 frob.val = PARPORT_CONTROL_STROBE; 2150 ioctl (fd, PPFCONTROL, &frob); 2151 nanosleep (&ts, NULL); 2152 2153 /* End the pulse */ 2154 frob.val = 0; 2155 ioctl (fd, PPFCONTROL, &frob); 2156 nanosleep (&ts, NULL); 2157 2158 wrote++; 2159 } 2160 2161 return wrote; 2162} 2163 ]]></programlisting> 2164 2165 <para> 2166 To show a bit more of the <literal>ppdev</literal> interface, 2167 here is a small piece of code that is intended to mimic the 2168 printer's side of printer protocol. 2169 </para> 2170 2171 <programlisting><![CDATA[ 2172 for (;;) 2173 { 2174 int irqc; 2175 int busy = nAck | nFault; 2176 int acking = nFault; 2177 int ready = Busy | nAck | nFault; 2178 char ch; 2179 2180 /* Set up the control lines when an interrupt happens. */ 2181 ioctl (fd, PPWCTLONIRQ, &busy); 2182 2183 /* Now we're ready. */ 2184 ioctl (fd, PPWCONTROL, &ready); 2185 2186 /* Wait for an interrupt. */ 2187 { 2188 fd_set rfds; 2189 FD_ZERO (&rfds); 2190 FD_SET (fd, &rfds); 2191 if (!select (fd + 1, &rfds, NULL, NULL, NULL)) 2192 /* Caught a signal? */ 2193 continue; 2194 } 2195 2196 /* We are now marked as busy. */ 2197 2198 /* Fetch the data. */ 2199 ioctl (fd, PPRDATA, &ch); 2200 2201 /* Clear the interrupt. */ 2202 ioctl (fd, PPCLRIRQ, &irqc); 2203 if (irqc > 1) 2204 fprintf (stderr, "Arghh! Missed %d interrupt%s!\n", 2205 irqc - 1, irqc == 2 ? "s" : ""); 2206 2207 /* Ack it. */ 2208 ioctl (fd, PPWCONTROL, &acking); 2209 usleep (2); 2210 ioctl (fd, PPWCONTROL, &busy); 2211 2212 putchar (ch); 2213 } 2214 ]]></programlisting> 2215 2216 <para> 2217 And here is an example (with no error checking at all) to show how 2218 to read data from the port, using ECP mode, with optional 2219 negotiation to ECP mode first. 2220 </para> 2221 2222 <programlisting><![CDATA[ 2223 { 2224 int fd, mode; 2225 fd = open ("/dev/parport0", O_RDONLY | O_NOCTTY); 2226 ioctl (fd, PPCLAIM); 2227 mode = IEEE1284_MODE_ECP; 2228 if (negotiate_first) { 2229 ioctl (fd, PPNEGOT, &mode); 2230 /* no need for PPSETMODE */ 2231 } else { 2232 ioctl (fd, PPSETMODE, &mode); 2233 } 2234 2235 /* Now do whatever we want with fd */ 2236 close (0); 2237 dup2 (fd, 0); 2238 if (!fork()) { 2239 /* child */ 2240 execlp ("cat", "cat", NULL); 2241 exit (1); 2242 } else { 2243 /* parent */ 2244 wait (NULL); 2245 } 2246 2247 /* Okay, finished */ 2248 ioctl (fd, PPRELEASE); 2249 close (fd); 2250 } 2251 ]]></programlisting> 2252 2253 </sect1> 2254 2255 </chapter> 2256 2257 <appendix id="api"> 2258 <title> 2259 Linux parallel port driver API reference 2260 </title> 2261 2262!Fdrivers/parport/daisy.c parport_device_num 2263!Fdrivers/parport/daisy.c parport_device_coords 2264!Fdrivers/parport/daisy.c parport_find_device 2265!Fdrivers/parport/daisy.c parport_find_class 2266!Fdrivers/parport/share.c parport_register_driver 2267!Fdrivers/parport/share.c parport_unregister_driver 2268!Fdrivers/parport/share.c parport_get_port 2269!Fdrivers/parport/share.c parport_put_port 2270!Fdrivers/parport/share.c parport_find_number parport_find_base 2271!Fdrivers/parport/share.c parport_register_device 2272!Fdrivers/parport/share.c parport_unregister_device 2273!Fdrivers/parport/daisy.c parport_open 2274!Fdrivers/parport/daisy.c parport_close 2275!Fdrivers/parport/share.c parport_claim 2276!Fdrivers/parport/share.c parport_claim_or_block 2277!Fdrivers/parport/share.c parport_release 2278!Finclude/linux/parport.h parport_yield 2279!Finclude/linux/parport.h parport_yield_blocking 2280!Fdrivers/parport/ieee1284.c parport_negotiate 2281!Fdrivers/parport/ieee1284.c parport_write 2282!Fdrivers/parport/ieee1284.c parport_read 2283!Fdrivers/parport/ieee1284.c parport_set_timeout 2284 2285 </appendix> 2286 2287 <appendix> 2288 <title> 2289 The Linux 2.2 Parallel Port Subsystem 2290 </title> 2291 2292 <para> 2293 Although the interface described in this document is largely new 2294 with the 2.4 kernel, the sharing mechanism is available in the 2.2 2295 kernel as well. The functions available in 2.2 are: 2296 </para> 2297 2298 <itemizedlist> 2299 <listitem> 2300 <para> 2301 <function>parport_register_device</function> 2302 </para> 2303 </listitem> 2304 2305 <listitem> 2306 <para> 2307 <function>parport_unregister_device</function> 2308 </para> 2309 </listitem> 2310 2311 <listitem> 2312 <para> 2313 <function>parport_claim</function> 2314 </para> 2315 </listitem> 2316 2317 <listitem> 2318 <para> 2319 <function>parport_claim_or_block</function> 2320 </para> 2321 </listitem> 2322 2323 <listitem> 2324 <para> 2325 <function>parport_release</function> 2326 </para> 2327 </listitem> 2328 2329 <listitem> 2330 <para> 2331 <function>parport_yield</function> 2332 </para> 2333 </listitem> 2334 2335 <listitem> 2336 <para> 2337 <function>parport_yield_blocking</function> 2338 </para> 2339 </listitem> 2340 </itemizedlist> 2341 2342 <para> 2343 In addition, negotiation to reverse nibble mode is supported: 2344 </para> 2345 2346 <funcsynopsis> 2347 <funcprototype> 2348 <funcdef>int <function>parport_ieee1284_nibble_mode_ok</function></funcdef> 2349 <paramdef>struct parport *<parameter>port</parameter></paramdef> 2350 <paramdef>unsigned char <parameter>mode</parameter></paramdef> 2351 </funcprototype> 2352 </funcsynopsis> 2353 2354 <para> 2355 The only valid values for <parameter>mode</parameter> are 0 (for 2356 reverse nibble mode) and 4 (for Device ID in reverse nibble mode). 2357 </para> 2358 2359 <para> 2360 This function is obsoleted by 2361 <function>parport_negotiate</function> in Linux 2.4, and has been 2362 removed. 2363 </para> 2364 </appendix> 2365 2366 <appendix id="fdl"> 2367 <title> 2368 GNU Free Documentation License 2369 </title> 2370 2371 <literallayout class="monospaced"> 2372 GNU Free Documentation License 2373 Version 1.1, March 2000 2374 2375 Copyright (C) 2000 Free Software Foundation, Inc. 2376 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 2377 Everyone is permitted to copy and distribute verbatim copies 2378 of this license document, but changing it is not allowed. 2379 2380 23810. PREAMBLE 2382 2383The purpose of this License is to make a manual, textbook, or other 2384written document "free" in the sense of freedom: to assure everyone 2385the effective freedom to copy and redistribute it, with or without 2386modifying it, either commercially or noncommercially. Secondarily, 2387this License preserves for the author and publisher a way to get 2388credit for their work, while not being considered responsible for 2389modifications made by others. 2390 2391This License is a kind of "copyleft", which means that derivative 2392works of the document must themselves be free in the same sense. It 2393complements the GNU General Public License, which is a copyleft 2394license designed for free software. 2395 2396We have designed this License in order to use it for manuals for free 2397software, because free software needs free documentation: a free 2398program should come with manuals providing the same freedoms that the 2399software does. But this License is not limited to software manuals; 2400it can be used for any textual work, regardless of subject matter or 2401whether it is published as a printed book. We recommend this License 2402principally for works whose purpose is instruction or reference. 2403 2404 24051. APPLICABILITY AND DEFINITIONS 2406 2407This License applies to any manual or other work that contains a 2408notice placed by the copyright holder saying it can be distributed 2409under the terms of this License. The "Document", below, refers to any 2410such manual or work. Any member of the public is a licensee, and is 2411addressed as "you". 2412 2413A "Modified Version" of the Document means any work containing the 2414Document or a portion of it, either copied verbatim, or with 2415modifications and/or translated into another language. 2416 2417A "Secondary Section" is a named appendix or a front-matter section of 2418the Document that deals exclusively with the relationship of the 2419publishers or authors of the Document to the Document's overall subject 2420(or to related matters) and contains nothing that could fall directly 2421within that overall subject. (For example, if the Document is in part a 2422textbook of mathematics, a Secondary Section may not explain any 2423mathematics.) The relationship could be a matter of historical 2424connection with the subject or with related matters, or of legal, 2425commercial, philosophical, ethical or political position regarding 2426them. 2427 2428The "Invariant Sections" are certain Secondary Sections whose titles 2429are designated, as being those of Invariant Sections, in the notice 2430that says that the Document is released under this License. 2431 2432The "Cover Texts" are certain short passages of text that are listed, 2433as Front-Cover Texts or Back-Cover Texts, in the notice that says that 2434the Document is released under this License. 2435 2436A "Transparent" copy of the Document means a machine-readable copy, 2437represented in a format whose specification is available to the 2438general public, whose contents can be viewed and edited directly and 2439straightforwardly with generic text editors or (for images composed of 2440pixels) generic paint programs or (for drawings) some widely available 2441drawing editor, and that is suitable for input to text formatters or 2442for automatic translation to a variety of formats suitable for input 2443to text formatters. A copy made in an otherwise Transparent file 2444format whose markup has been designed to thwart or discourage 2445subsequent modification by readers is not Transparent. A copy that is 2446not "Transparent" is called "Opaque". 2447 2448Examples of suitable formats for Transparent copies include plain 2449ASCII without markup, Texinfo input format, LaTeX input format, SGML 2450or XML using a publicly available DTD, and standard-conforming simple 2451HTML designed for human modification. Opaque formats include 2452PostScript, PDF, proprietary formats that can be read and edited only 2453by proprietary word processors, SGML or XML for which the DTD and/or 2454processing tools are not generally available, and the 2455machine-generated HTML produced by some word processors for output 2456purposes only. 2457 2458The "Title Page" means, for a printed book, the title page itself, 2459plus such following pages as are needed to hold, legibly, the material 2460this License requires to appear in the title page. For works in 2461formats which do not have any title page as such, "Title Page" means 2462the text near the most prominent appearance of the work's title, 2463preceding the beginning of the body of the text. 2464 2465 24662. VERBATIM COPYING 2467 2468You may copy and distribute the Document in any medium, either 2469commercially or noncommercially, provided that this License, the 2470copyright notices, and the license notice saying this License applies 2471to the Document are reproduced in all copies, and that you add no other 2472conditions whatsoever to those of this License. You may not use 2473technical measures to obstruct or control the reading or further 2474copying of the copies you make or distribute. However, you may accept 2475compensation in exchange for copies. If you distribute a large enough 2476number of copies you must also follow the conditions in section 3. 2477 2478You may also lend copies, under the same conditions stated above, and 2479you may publicly display copies. 2480 2481 24823. COPYING IN QUANTITY 2483 2484If you publish printed copies of the Document numbering more than 100, 2485and the Document's license notice requires Cover Texts, you must enclose 2486the copies in covers that carry, clearly and legibly, all these Cover 2487Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 2488the back cover. Both covers must also clearly and legibly identify 2489you as the publisher of these copies. The front cover must present 2490the full title with all words of the title equally prominent and 2491visible. You may add other material on the covers in addition. 2492Copying with changes limited to the covers, as long as they preserve 2493the title of the Document and satisfy these conditions, can be treated 2494as verbatim copying in other respects. 2495 2496If the required texts for either cover are too voluminous to fit 2497legibly, you should put the first ones listed (as many as fit 2498reasonably) on the actual cover, and continue the rest onto adjacent 2499pages. 2500 2501If you publish or distribute Opaque copies of the Document numbering 2502more than 100, you must either include a machine-readable Transparent 2503copy along with each Opaque copy, or state in or with each Opaque copy 2504a publicly-accessible computer-network location containing a complete 2505Transparent copy of the Document, free of added material, which the 2506general network-using public has access to download anonymously at no 2507charge using public-standard network protocols. If you use the latter 2508option, you must take reasonably prudent steps, when you begin 2509distribution of Opaque copies in quantity, to ensure that this 2510Transparent copy will remain thus accessible at the stated location 2511until at least one year after the last time you distribute an Opaque 2512copy (directly or through your agents or retailers) of that edition to 2513the public. 2514 2515It is requested, but not required, that you contact the authors of the 2516Document well before redistributing any large number of copies, to give 2517them a chance to provide you with an updated version of the Document. 2518 2519 25204. MODIFICATIONS 2521 2522You may copy and distribute a Modified Version of the Document under 2523the conditions of sections 2 and 3 above, provided that you release 2524the Modified Version under precisely this License, with the Modified 2525Version filling the role of the Document, thus licensing distribution 2526and modification of the Modified Version to whoever possesses a copy 2527of it. In addition, you must do these things in the Modified Version: 2528 2529A. Use in the Title Page (and on the covers, if any) a title distinct 2530 from that of the Document, and from those of previous versions 2531 (which should, if there were any, be listed in the History section 2532 of the Document). You may use the same title as a previous version 2533 if the original publisher of that version gives permission. 2534B. List on the Title Page, as authors, one or more persons or entities 2535 responsible for authorship of the modifications in the Modified 2536 Version, together with at least five of the principal authors of the 2537 Document (all of its principal authors, if it has less than five). 2538C. State on the Title page the name of the publisher of the 2539 Modified Version, as the publisher. 2540D. Preserve all the copyright notices of the Document. 2541E. Add an appropriate copyright notice for your modifications 2542 adjacent to the other copyright notices. 2543F. Include, immediately after the copyright notices, a license notice 2544 giving the public permission to use the Modified Version under the 2545 terms of this License, in the form shown in the Addendum below. 2546G. Preserve in that license notice the full lists of Invariant Sections 2547 and required Cover Texts given in the Document's license notice. 2548H. Include an unaltered copy of this License. 2549I. Preserve the section entitled "History", and its title, and add to 2550 it an item stating at least the title, year, new authors, and 2551 publisher of the Modified Version as given on the Title Page. If 2552 there is no section entitled "History" in the Document, create one 2553 stating the title, year, authors, and publisher of the Document as 2554 given on its Title Page, then add an item describing the Modified 2555 Version as stated in the previous sentence. 2556J. Preserve the network location, if any, given in the Document for 2557 public access to a Transparent copy of the Document, and likewise 2558 the network locations given in the Document for previous versions 2559 it was based on. These may be placed in the "History" section. 2560 You may omit a network location for a work that was published at 2561 least four years before the Document itself, or if the original 2562 publisher of the version it refers to gives permission. 2563K. In any section entitled "Acknowledgements" or "Dedications", 2564 preserve the section's title, and preserve in the section all the 2565 substance and tone of each of the contributor acknowledgements 2566 and/or dedications given therein. 2567L. Preserve all the Invariant Sections of the Document, 2568 unaltered in their text and in their titles. Section numbers 2569 or the equivalent are not considered part of the section titles. 2570M. Delete any section entitled "Endorsements". Such a section 2571 may not be included in the Modified Version. 2572N. Do not retitle any existing section as "Endorsements" 2573 or to conflict in title with any Invariant Section. 2574 2575If the Modified Version includes new front-matter sections or 2576appendices that qualify as Secondary Sections and contain no material 2577copied from the Document, you may at your option designate some or all 2578of these sections as invariant. To do this, add their titles to the 2579list of Invariant Sections in the Modified Version's license notice. 2580These titles must be distinct from any other section titles. 2581 2582You may add a section entitled "Endorsements", provided it contains 2583nothing but endorsements of your Modified Version by various 2584parties--for example, statements of peer review or that the text has 2585been approved by an organization as the authoritative definition of a 2586standard. 2587 2588You may add a passage of up to five words as a Front-Cover Text, and a 2589passage of up to 25 words as a Back-Cover Text, to the end of the list 2590of Cover Texts in the Modified Version. Only one passage of 2591Front-Cover Text and one of Back-Cover Text may be added by (or 2592through arrangements made by) any one entity. If the Document already 2593includes a cover text for the same cover, previously added by you or 2594by arrangement made by the same entity you are acting on behalf of, 2595you may not add another; but you may replace the old one, on explicit 2596permission from the previous publisher that added the old one. 2597 2598The author(s) and publisher(s) of the Document do not by this License 2599give permission to use their names for publicity for or to assert or 2600imply endorsement of any Modified Version. 2601 2602 26035. COMBINING DOCUMENTS 2604 2605You may combine the Document with other documents released under this 2606License, under the terms defined in section 4 above for modified 2607versions, provided that you include in the combination all of the 2608Invariant Sections of all of the original documents, unmodified, and 2609list them all as Invariant Sections of your combined work in its 2610license notice. 2611 2612The combined work need only contain one copy of this License, and 2613multiple identical Invariant Sections may be replaced with a single 2614copy. If there are multiple Invariant Sections with the same name but 2615different contents, make the title of each such section unique by 2616adding at the end of it, in parentheses, the name of the original 2617author or publisher of that section if known, or else a unique number. 2618Make the same adjustment to the section titles in the list of 2619Invariant Sections in the license notice of the combined work. 2620 2621In the combination, you must combine any sections entitled "History" 2622in the various original documents, forming one section entitled 2623"History"; likewise combine any sections entitled "Acknowledgements", 2624and any sections entitled "Dedications". You must delete all sections 2625entitled "Endorsements." 2626 2627 26286. COLLECTIONS OF DOCUMENTS 2629 2630You may make a collection consisting of the Document and other documents 2631released under this License, and replace the individual copies of this 2632License in the various documents with a single copy that is included in 2633the collection, provided that you follow the rules of this License for 2634verbatim copying of each of the documents in all other respects. 2635 2636You may extract a single document from such a collection, and distribute 2637it individually under this License, provided you insert a copy of this 2638License into the extracted document, and follow this License in all 2639other respects regarding verbatim copying of that document. 2640 2641 2642 26437. AGGREGATION WITH INDEPENDENT WORKS 2644 2645A compilation of the Document or its derivatives with other separate 2646and independent documents or works, in or on a volume of a storage or 2647distribution medium, does not as a whole count as a Modified Version 2648of the Document, provided no compilation copyright is claimed for the 2649compilation. Such a compilation is called an "aggregate", and this 2650License does not apply to the other self-contained works thus compiled 2651with the Document, on account of their being thus compiled, if they 2652are not themselves derivative works of the Document. 2653 2654If the Cover Text requirement of section 3 is applicable to these 2655copies of the Document, then if the Document is less than one quarter 2656of the entire aggregate, the Document's Cover Texts may be placed on 2657covers that surround only the Document within the aggregate. 2658Otherwise they must appear on covers around the whole aggregate. 2659 2660 26618. TRANSLATION 2662 2663Translation is considered a kind of modification, so you may 2664distribute translations of the Document under the terms of section 4. 2665Replacing Invariant Sections with translations requires special 2666permission from their copyright holders, but you may include 2667translations of some or all Invariant Sections in addition to the 2668original versions of these Invariant Sections. You may include a 2669translation of this License provided that you also include the 2670original English version of this License. In case of a disagreement 2671between the translation and the original English version of this 2672License, the original English version will prevail. 2673 2674 26759. TERMINATION 2676 2677You may not copy, modify, sublicense, or distribute the Document except 2678as expressly provided for under this License. Any other attempt to 2679copy, modify, sublicense or distribute the Document is void, and will 2680automatically terminate your rights under this License. However, 2681parties who have received copies, or rights, from you under this 2682License will not have their licenses terminated so long as such 2683parties remain in full compliance. 2684 2685 268610. FUTURE REVISIONS OF THIS LICENSE 2687 2688The Free Software Foundation may publish new, revised versions 2689of the GNU Free Documentation License from time to time. Such new 2690versions will be similar in spirit to the present version, but may 2691differ in detail to address new problems or concerns. See 2692http:///www.gnu.org/copyleft/. 2693 2694Each version of the License is given a distinguishing version number. 2695If the Document specifies that a particular numbered version of this 2696License "or any later version" applies to it, you have the option of 2697following the terms and conditions either of that specified version or 2698of any later version that has been published (not as a draft) by the 2699Free Software Foundation. If the Document does not specify a version 2700number of this License, you may choose any version ever published (not 2701as a draft) by the Free Software Foundation. 2702 2703 2704ADDENDUM: How to use this License for your documents 2705 2706To use this License in a document you have written, include a copy of 2707the License in the document and put the following copyright and 2708license notices just after the title page: 2709 2710 Copyright (c) YEAR YOUR NAME. 2711 Permission is granted to copy, distribute and/or modify this document 2712 under the terms of the GNU Free Documentation License, Version 1.1 2713 or any later version published by the Free Software Foundation; 2714 with the Invariant Sections being LIST THEIR TITLES, with the 2715 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 2716 A copy of the license is included in the section entitled "GNU 2717 Free Documentation License". 2718 2719If you have no Invariant Sections, write "with no Invariant Sections" 2720instead of saying which ones are invariant. If you have no 2721Front-Cover Texts, write "no Front-Cover Texts" instead of 2722"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. 2723 2724If your document contains nontrivial examples of program code, we 2725recommend releasing these examples in parallel under your choice of 2726free software license, such as the GNU General Public License, 2727to permit their use in free software. 2728 </literallayout> 2729 </appendix> 2730 2731</book> 2732 2733<!-- Local Variables: --> 2734<!-- sgml-indent-step: 1 --> 2735<!-- sgml-indent-data: 1 --> 2736<!-- End: --> 2737
