parport-lowlevel.txt 32 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490
  1. PARPORT interface documentation
  2. -------------------------------
  3. Time-stamp: <2000-02-24 13:30:20 twaugh>
  4. Described here are the following functions:
  5. Global functions:
  6. parport_register_driver
  7. parport_unregister_driver
  8. parport_enumerate
  9. parport_register_device
  10. parport_unregister_device
  11. parport_claim
  12. parport_claim_or_block
  13. parport_release
  14. parport_yield
  15. parport_yield_blocking
  16. parport_wait_peripheral
  17. parport_poll_peripheral
  18. parport_wait_event
  19. parport_negotiate
  20. parport_read
  21. parport_write
  22. parport_open
  23. parport_close
  24. parport_device_id
  25. parport_device_num
  26. parport_device_coords
  27. parport_find_class
  28. parport_find_device
  29. parport_set_timeout
  30. Port functions (can be overridden by low-level drivers):
  31. SPP:
  32. port->ops->read_data
  33. port->ops->write_data
  34. port->ops->read_status
  35. port->ops->read_control
  36. port->ops->write_control
  37. port->ops->frob_control
  38. port->ops->enable_irq
  39. port->ops->disable_irq
  40. port->ops->data_forward
  41. port->ops->data_reverse
  42. EPP:
  43. port->ops->epp_write_data
  44. port->ops->epp_read_data
  45. port->ops->epp_write_addr
  46. port->ops->epp_read_addr
  47. ECP:
  48. port->ops->ecp_write_data
  49. port->ops->ecp_read_data
  50. port->ops->ecp_write_addr
  51. Other:
  52. port->ops->nibble_read_data
  53. port->ops->byte_read_data
  54. port->ops->compat_write_data
  55. The parport subsystem comprises 'parport' (the core port-sharing
  56. code), and a variety of low-level drivers that actually do the port
  57. accesses. Each low-level driver handles a particular style of port
  58. (PC, Amiga, and so on).
  59. The parport interface to the device driver author can be broken down
  60. into global functions and port functions.
  61. The global functions are mostly for communicating between the device
  62. driver and the parport subsystem: acquiring a list of available ports,
  63. claiming a port for exclusive use, and so on. They also include
  64. 'generic' functions for doing standard things that will work on any
  65. IEEE 1284-capable architecture.
  66. The port functions are provided by the low-level drivers, although the
  67. core parport module provides generic 'defaults' for some routines.
  68. The port functions can be split into three groups: SPP, EPP, and ECP.
  69. SPP (Standard Parallel Port) functions modify so-called 'SPP'
  70. registers: data, status, and control. The hardware may not actually
  71. have registers exactly like that, but the PC does and this interface is
  72. modelled after common PC implementations. Other low-level drivers may
  73. be able to emulate most of the functionality.
  74. EPP (Enhanced Parallel Port) functions are provided for reading and
  75. writing in IEEE 1284 EPP mode, and ECP (Extended Capabilities Port)
  76. functions are used for IEEE 1284 ECP mode. (What about BECP? Does
  77. anyone care?)
  78. Hardware assistance for EPP and/or ECP transfers may or may not be
  79. available, and if it is available it may or may not be used. If
  80. hardware is not used, the transfer will be software-driven. In order
  81. to cope with peripherals that only tenuously support IEEE 1284, a
  82. low-level driver specific function is provided, for altering 'fudge
  83. factors'.
  84. GLOBAL FUNCTIONS
  85. ----------------
  86. parport_register_driver - register a device driver with parport
  87. -----------------------
  88. SYNOPSIS
  89. #include <linux/parport.h>
  90. struct parport_driver {
  91. const char *name;
  92. void (*attach) (struct parport *);
  93. void (*detach) (struct parport *);
  94. struct parport_driver *next;
  95. };
  96. int parport_register_driver (struct parport_driver *driver);
  97. DESCRIPTION
  98. In order to be notified about parallel ports when they are detected,
  99. parport_register_driver should be called. Your driver will
  100. immediately be notified of all ports that have already been detected,
  101. and of each new port as low-level drivers are loaded.
  102. A 'struct parport_driver' contains the textual name of your driver,
  103. a pointer to a function to handle new ports, and a pointer to a
  104. function to handle ports going away due to a low-level driver
  105. unloading. Ports will only be detached if they are not being used
  106. (i.e. there are no devices registered on them).
  107. The visible parts of the 'struct parport *' argument given to
  108. attach/detach are:
  109. struct parport
  110. {
  111. struct parport *next; /* next parport in list */
  112. const char *name; /* port's name */
  113. unsigned int modes; /* bitfield of hardware modes */
  114. struct parport_device_info probe_info;
  115. /* IEEE1284 info */
  116. int number; /* parport index */
  117. struct parport_operations *ops;
  118. ...
  119. };
  120. There are other members of the structure, but they should not be
  121. touched.
  122. The 'modes' member summarises the capabilities of the underlying
  123. hardware. It consists of flags which may be bitwise-ored together:
  124. PARPORT_MODE_PCSPP IBM PC registers are available,
  125. i.e. functions that act on data,
  126. control and status registers are
  127. probably writing directly to the
  128. hardware.
  129. PARPORT_MODE_TRISTATE The data drivers may be turned off.
  130. This allows the data lines to be used
  131. for reverse (peripheral to host)
  132. transfers.
  133. PARPORT_MODE_COMPAT The hardware can assist with
  134. compatibility-mode (printer)
  135. transfers, i.e. compat_write_block.
  136. PARPORT_MODE_EPP The hardware can assist with EPP
  137. transfers.
  138. PARPORT_MODE_ECP The hardware can assist with ECP
  139. transfers.
  140. PARPORT_MODE_DMA The hardware can use DMA, so you might
  141. want to pass ISA DMA-able memory
  142. (i.e. memory allocated using the
  143. GFP_DMA flag with kmalloc) to the
  144. low-level driver in order to take
  145. advantage of it.
  146. There may be other flags in 'modes' as well.
  147. The contents of 'modes' is advisory only. For example, if the
  148. hardware is capable of DMA, and PARPORT_MODE_DMA is in 'modes', it
  149. doesn't necessarily mean that DMA will always be used when possible.
  150. Similarly, hardware that is capable of assisting ECP transfers won't
  151. necessarily be used.
  152. RETURN VALUE
  153. Zero on success, otherwise an error code.
  154. ERRORS
  155. None. (Can it fail? Why return int?)
  156. EXAMPLE
  157. static void lp_attach (struct parport *port)
  158. {
  159. ...
  160. private = kmalloc (...);
  161. dev[count++] = parport_register_device (...);
  162. ...
  163. }
  164. static void lp_detach (struct parport *port)
  165. {
  166. ...
  167. }
  168. static struct parport_driver lp_driver = {
  169. "lp",
  170. lp_attach,
  171. lp_detach,
  172. NULL /* always put NULL here */
  173. };
  174. int lp_init (void)
  175. {
  176. ...
  177. if (parport_register_driver (&lp_driver)) {
  178. /* Failed; nothing we can do. */
  179. return -EIO;
  180. }
  181. ...
  182. }
  183. SEE ALSO
  184. parport_unregister_driver, parport_register_device, parport_enumerate
  185. parport_unregister_driver - tell parport to forget about this driver
  186. -------------------------
  187. SYNOPSIS
  188. #include <linux/parport.h>
  189. struct parport_driver {
  190. const char *name;
  191. void (*attach) (struct parport *);
  192. void (*detach) (struct parport *);
  193. struct parport_driver *next;
  194. };
  195. void parport_unregister_driver (struct parport_driver *driver);
  196. DESCRIPTION
  197. This tells parport not to notify the device driver of new ports or of
  198. ports going away. Registered devices belonging to that driver are NOT
  199. unregistered: parport_unregister_device must be used for each one.
  200. EXAMPLE
  201. void cleanup_module (void)
  202. {
  203. ...
  204. /* Stop notifications. */
  205. parport_unregister_driver (&lp_driver);
  206. /* Unregister devices. */
  207. for (i = 0; i < NUM_DEVS; i++)
  208. parport_unregister_device (dev[i]);
  209. ...
  210. }
  211. SEE ALSO
  212. parport_register_driver, parport_enumerate
  213. parport_enumerate - retrieve a list of parallel ports (DEPRECATED)
  214. -----------------
  215. SYNOPSIS
  216. #include <linux/parport.h>
  217. struct parport *parport_enumerate (void);
  218. DESCRIPTION
  219. Retrieve the first of a list of valid parallel ports for this machine.
  220. Successive parallel ports can be found using the 'struct parport
  221. *next' element of the 'struct parport *' that is returned. If 'next'
  222. is NULL, there are no more parallel ports in the list. The number of
  223. ports in the list will not exceed PARPORT_MAX.
  224. RETURN VALUE
  225. A 'struct parport *' describing a valid parallel port for the machine,
  226. or NULL if there are none.
  227. ERRORS
  228. This function can return NULL to indicate that there are no parallel
  229. ports to use.
  230. EXAMPLE
  231. int detect_device (void)
  232. {
  233. struct parport *port;
  234. for (port = parport_enumerate ();
  235. port != NULL;
  236. port = port->next) {
  237. /* Try to detect a device on the port... */
  238. ...
  239. }
  240. }
  241. ...
  242. }
  243. NOTES
  244. parport_enumerate is deprecated; parport_register_driver should be
  245. used instead.
  246. SEE ALSO
  247. parport_register_driver, parport_unregister_driver
  248. parport_register_device - register to use a port
  249. -----------------------
  250. SYNOPSIS
  251. #include <linux/parport.h>
  252. typedef int (*preempt_func) (void *handle);
  253. typedef void (*wakeup_func) (void *handle);
  254. typedef int (*irq_func) (int irq, void *handle, struct pt_regs *);
  255. struct pardevice *parport_register_device(struct parport *port,
  256. const char *name,
  257. preempt_func preempt,
  258. wakeup_func wakeup,
  259. irq_func irq,
  260. int flags,
  261. void *handle);
  262. DESCRIPTION
  263. Use this function to register your device driver on a parallel port
  264. ('port'). Once you have done that, you will be able to use
  265. parport_claim and parport_release in order to use the port.
  266. This function will register three callbacks into your driver:
  267. 'preempt', 'wakeup' and 'irq'. Each of these may be NULL in order to
  268. indicate that you do not want a callback.
  269. When the 'preempt' function is called, it is because another driver
  270. wishes to use the parallel port. The 'preempt' function should return
  271. non-zero if the parallel port cannot be released yet -- if zero is
  272. returned, the port is lost to another driver and the port must be
  273. re-claimed before use.
  274. The 'wakeup' function is called once another driver has released the
  275. port and no other driver has yet claimed it. You can claim the
  276. parallel port from within the 'wakeup' function (in which case the
  277. claim is guaranteed to succeed), or choose not to if you don't need it
  278. now.
  279. If an interrupt occurs on the parallel port your driver has claimed,
  280. the 'irq' function will be called. (Write something about shared
  281. interrupts here.)
  282. The 'handle' is a pointer to driver-specific data, and is passed to
  283. the callback functions.
  284. 'flags' may be a bitwise combination of the following flags:
  285. Flag Meaning
  286. PARPORT_DEV_EXCL The device cannot share the parallel port at all.
  287. Use this only when absolutely necessary.
  288. The typedefs are not actually defined -- they are only shown in order
  289. to make the function prototype more readable.
  290. The visible parts of the returned 'struct pardevice' are:
  291. struct pardevice {
  292. struct parport *port; /* Associated port */
  293. void *private; /* Device driver's 'handle' */
  294. ...
  295. };
  296. RETURN VALUE
  297. A 'struct pardevice *': a handle to the registered parallel port
  298. device that can be used for parport_claim, parport_release, etc.
  299. ERRORS
  300. A return value of NULL indicates that there was a problem registering
  301. a device on that port.
  302. EXAMPLE
  303. static int preempt (void *handle)
  304. {
  305. if (busy_right_now)
  306. return 1;
  307. must_reclaim_port = 1;
  308. return 0;
  309. }
  310. static void wakeup (void *handle)
  311. {
  312. struct toaster *private = handle;
  313. struct pardevice *dev = private->dev;
  314. if (!dev) return; /* avoid races */
  315. if (want_port)
  316. parport_claim (dev);
  317. }
  318. static int toaster_detect (struct toaster *private, struct parport *port)
  319. {
  320. private->dev = parport_register_device (port, "toaster", preempt,
  321. wakeup, NULL, 0,
  322. private);
  323. if (!private->dev)
  324. /* Couldn't register with parport. */
  325. return -EIO;
  326. must_reclaim_port = 0;
  327. busy_right_now = 1;
  328. parport_claim_or_block (private->dev);
  329. ...
  330. /* Don't need the port while the toaster warms up. */
  331. busy_right_now = 0;
  332. ...
  333. busy_right_now = 1;
  334. if (must_reclaim_port) {
  335. parport_claim_or_block (private->dev);
  336. must_reclaim_port = 0;
  337. }
  338. ...
  339. }
  340. SEE ALSO
  341. parport_unregister_device, parport_claim
  342. parport_unregister_device - finish using a port
  343. -------------------------
  344. SYNPOPSIS
  345. #include <linux/parport.h>
  346. void parport_unregister_device (struct pardevice *dev);
  347. DESCRIPTION
  348. This function is the opposite of parport_register_device. After using
  349. parport_unregister_device, 'dev' is no longer a valid device handle.
  350. You should not unregister a device that is currently claimed, although
  351. if you do it will be released automatically.
  352. EXAMPLE
  353. ...
  354. kfree (dev->private); /* before we lose the pointer */
  355. parport_unregister_device (dev);
  356. ...
  357. SEE ALSO
  358. parport_unregister_driver
  359. parport_claim, parport_claim_or_block - claim the parallel port for a device
  360. -------------------------------------
  361. SYNOPSIS
  362. #include <linux/parport.h>
  363. int parport_claim (struct pardevice *dev);
  364. int parport_claim_or_block (struct pardevice *dev);
  365. DESCRIPTION
  366. These functions attempt to gain control of the parallel port on which
  367. 'dev' is registered. 'parport_claim' does not block, but
  368. 'parport_claim_or_block' may do. (Put something here about blocking
  369. interruptibly or non-interruptibly.)
  370. You should not try to claim a port that you have already claimed.
  371. RETURN VALUE
  372. A return value of zero indicates that the port was successfully
  373. claimed, and the caller now has possession of the parallel port.
  374. If 'parport_claim_or_block' blocks before returning successfully, the
  375. return value is positive.
  376. ERRORS
  377. -EAGAIN The port is unavailable at the moment, but another attempt
  378. to claim it may succeed.
  379. SEE ALSO
  380. parport_release
  381. parport_release - release the parallel port
  382. ---------------
  383. SYNOPSIS
  384. #include <linux/parport.h>
  385. void parport_release (struct pardevice *dev);
  386. DESCRIPTION
  387. Once a parallel port device has been claimed, it can be released using
  388. 'parport_release'. It cannot fail, but you should not release a
  389. device that you do not have possession of.
  390. EXAMPLE
  391. static size_t write (struct pardevice *dev, const void *buf,
  392. size_t len)
  393. {
  394. ...
  395. written = dev->port->ops->write_ecp_data (dev->port, buf,
  396. len);
  397. parport_release (dev);
  398. ...
  399. }
  400. SEE ALSO
  401. change_mode, parport_claim, parport_claim_or_block, parport_yield
  402. parport_yield, parport_yield_blocking - temporarily release a parallel port
  403. -------------------------------------
  404. SYNOPSIS
  405. #include <linux/parport.h>
  406. int parport_yield (struct pardevice *dev)
  407. int parport_yield_blocking (struct pardevice *dev);
  408. DESCRIPTION
  409. When a driver has control of a parallel port, it may allow another
  410. driver to temporarily 'borrow' it. 'parport_yield' does not block;
  411. 'parport_yield_blocking' may do.
  412. RETURN VALUE
  413. A return value of zero indicates that the caller still owns the port
  414. and the call did not block.
  415. A positive return value from 'parport_yield_blocking' indicates that
  416. the caller still owns the port and the call blocked.
  417. A return value of -EAGAIN indicates that the caller no longer owns the
  418. port, and it must be re-claimed before use.
  419. ERRORS
  420. -EAGAIN Ownership of the parallel port was given away.
  421. SEE ALSO
  422. parport_release
  423. parport_wait_peripheral - wait for status lines, up to 35ms
  424. -----------------------
  425. SYNOPSIS
  426. #include <linux/parport.h>
  427. int parport_wait_peripheral (struct parport *port,
  428. unsigned char mask,
  429. unsigned char val);
  430. DESCRIPTION
  431. Wait for the status lines in mask to match the values in val.
  432. RETURN VALUE
  433. -EINTR a signal is pending
  434. 0 the status lines in mask have values in val
  435. 1 timed out while waiting (35ms elapsed)
  436. SEE ALSO
  437. parport_poll_peripheral
  438. parport_poll_peripheral - wait for status lines, in usec
  439. -----------------------
  440. SYNOPSIS
  441. #include <linux/parport.h>
  442. int parport_poll_peripheral (struct parport *port,
  443. unsigned char mask,
  444. unsigned char val,
  445. int usec);
  446. DESCRIPTION
  447. Wait for the status lines in mask to match the values in val.
  448. RETURN VALUE
  449. -EINTR a signal is pending
  450. 0 the status lines in mask have values in val
  451. 1 timed out while waiting (usec microseconds have elapsed)
  452. SEE ALSO
  453. parport_wait_peripheral
  454. parport_wait_event - wait for an event on a port
  455. ------------------
  456. SYNOPSIS
  457. #include <linux/parport.h>
  458. int parport_wait_event (struct parport *port, signed long timeout)
  459. DESCRIPTION
  460. Wait for an event (e.g. interrupt) on a port. The timeout is in
  461. jiffies.
  462. RETURN VALUE
  463. 0 success
  464. <0 error (exit as soon as possible)
  465. >0 timed out
  466. parport_negotiate - perform IEEE 1284 negotiation
  467. -----------------
  468. SYNOPSIS
  469. #include <linux/parport.h>
  470. int parport_negotiate (struct parport *, int mode);
  471. DESCRIPTION
  472. Perform IEEE 1284 negotiation.
  473. RETURN VALUE
  474. 0 handshake OK; IEEE 1284 peripheral and mode available
  475. -1 handshake failed; peripheral not compliant (or none present)
  476. 1 handshake OK; IEEE 1284 peripheral present but mode not
  477. available
  478. SEE ALSO
  479. parport_read, parport_write
  480. parport_read - read data from device
  481. ------------
  482. SYNOPSIS
  483. #include <linux/parport.h>
  484. ssize_t parport_read (struct parport *, void *buf, size_t len);
  485. DESCRIPTION
  486. Read data from device in current IEEE 1284 transfer mode. This only
  487. works for modes that support reverse data transfer.
  488. RETURN VALUE
  489. If negative, an error code; otherwise the number of bytes transferred.
  490. SEE ALSO
  491. parport_write, parport_negotiate
  492. parport_write - write data to device
  493. -------------
  494. SYNOPSIS
  495. #include <linux/parport.h>
  496. ssize_t parport_write (struct parport *, const void *buf, size_t len);
  497. DESCRIPTION
  498. Write data to device in current IEEE 1284 transfer mode. This only
  499. works for modes that support forward data transfer.
  500. RETURN VALUE
  501. If negative, an error code; otherwise the number of bytes transferred.
  502. SEE ALSO
  503. parport_read, parport_negotiate
  504. parport_open - register device for particular device number
  505. ------------
  506. SYNOPSIS
  507. #include <linux/parport.h>
  508. struct pardevice *parport_open (int devnum, const char *name,
  509. int (*pf) (void *),
  510. void (*kf) (void *),
  511. void (*irqf) (int, void *,
  512. struct pt_regs *),
  513. int flags, void *handle);
  514. DESCRIPTION
  515. This is like parport_register_device but takes a device number instead
  516. of a pointer to a struct parport.
  517. RETURN VALUE
  518. See parport_register_device. If no device is associated with devnum,
  519. NULL is returned.
  520. SEE ALSO
  521. parport_register_device, parport_device_num
  522. parport_close - unregister device for particular device number
  523. -------------
  524. SYNOPSIS
  525. #include <linux/parport.h>
  526. void parport_close (struct pardevice *dev);
  527. DESCRIPTION
  528. This is the equivalent of parport_unregister_device for parport_open.
  529. SEE ALSO
  530. parport_unregister_device, parport_open
  531. parport_device_id - obtain IEEE 1284 Device ID
  532. -----------------
  533. SYNOPSIS
  534. #include <linux/parport.h>
  535. ssize_t parport_device_id (int devnum, char *buffer, size_t len);
  536. DESCRIPTION
  537. Obtains the IEEE 1284 Device ID associated with a given device.
  538. RETURN VALUE
  539. If negative, an error code; otherwise, the number of bytes of buffer
  540. that contain the device ID. The format of the device ID is as
  541. follows:
  542. [length][ID]
  543. The first two bytes indicate the inclusive length of the entire Device
  544. ID, and are in big-endian order. The ID is a sequence of pairs of the
  545. form:
  546. key:value;
  547. NOTES
  548. Many devices have ill-formed IEEE 1284 Device IDs.
  549. SEE ALSO
  550. parport_find_class, parport_find_device, parport_device_num
  551. parport_device_num - convert device coordinates to device number
  552. ------------------
  553. SYNOPSIS
  554. #include <linux/parport.h>
  555. int parport_device_num (int parport, int mux, int daisy);
  556. DESCRIPTION
  557. Convert between device coordinates (port, multiplexor, daisy chain
  558. address) and device number (zero-based).
  559. RETURN VALUE
  560. Device number, or -1 if no device at given coordinates.
  561. SEE ALSO
  562. parport_device_coords, parport_open, parport_device_id
  563. parport_device_coords - convert device number to device coordinates
  564. ------------------
  565. SYNOPSIS
  566. #include <linux/parport.h>
  567. int parport_device_coords (int devnum, int *parport, int *mux,
  568. int *daisy);
  569. DESCRIPTION
  570. Convert between device number (zero-based) and device coordinates
  571. (port, multiplexor, daisy chain address).
  572. RETURN VALUE
  573. Zero on success, in which case the coordinates are (*parport, *mux,
  574. *daisy).
  575. SEE ALSO
  576. parport_device_num, parport_open, parport_device_id
  577. parport_find_class - find a device by its class
  578. ------------------
  579. SYNOPSIS
  580. #include <linux/parport.h>
  581. typedef enum {
  582. PARPORT_CLASS_LEGACY = 0, /* Non-IEEE1284 device */
  583. PARPORT_CLASS_PRINTER,
  584. PARPORT_CLASS_MODEM,
  585. PARPORT_CLASS_NET,
  586. PARPORT_CLASS_HDC, /* Hard disk controller */
  587. PARPORT_CLASS_PCMCIA,
  588. PARPORT_CLASS_MEDIA, /* Multimedia device */
  589. PARPORT_CLASS_FDC, /* Floppy disk controller */
  590. PARPORT_CLASS_PORTS,
  591. PARPORT_CLASS_SCANNER,
  592. PARPORT_CLASS_DIGCAM,
  593. PARPORT_CLASS_OTHER, /* Anything else */
  594. PARPORT_CLASS_UNSPEC, /* No CLS field in ID */
  595. PARPORT_CLASS_SCSIADAPTER
  596. } parport_device_class;
  597. int parport_find_class (parport_device_class cls, int from);
  598. DESCRIPTION
  599. Find a device by class. The search starts from device number from+1.
  600. RETURN VALUE
  601. The device number of the next device in that class, or -1 if no such
  602. device exists.
  603. NOTES
  604. Example usage:
  605. int devnum = -1;
  606. while ((devnum = parport_find_class (PARPORT_CLASS_DIGCAM, devnum)) != -1) {
  607. struct pardevice *dev = parport_open (devnum, ...);
  608. ...
  609. }
  610. SEE ALSO
  611. parport_find_device, parport_open, parport_device_id
  612. parport_find_device - find a device by its class
  613. ------------------
  614. SYNOPSIS
  615. #include <linux/parport.h>
  616. int parport_find_device (const char *mfg, const char *mdl, int from);
  617. DESCRIPTION
  618. Find a device by vendor and model. The search starts from device
  619. number from+1.
  620. RETURN VALUE
  621. The device number of the next device matching the specifications, or
  622. -1 if no such device exists.
  623. NOTES
  624. Example usage:
  625. int devnum = -1;
  626. while ((devnum = parport_find_device ("IOMEGA", "ZIP+", devnum)) != -1) {
  627. struct pardevice *dev = parport_open (devnum, ...);
  628. ...
  629. }
  630. SEE ALSO
  631. parport_find_class, parport_open, parport_device_id
  632. parport_set_timeout - set the inactivity timeout
  633. -------------------
  634. SYNOPSIS
  635. #include <linux/parport.h>
  636. long parport_set_timeout (struct pardevice *dev, long inactivity);
  637. DESCRIPTION
  638. Set the inactivity timeout, in jiffies, for a registered device. The
  639. previous timeout is returned.
  640. RETURN VALUE
  641. The previous timeout, in jiffies.
  642. NOTES
  643. Some of the port->ops functions for a parport may take time, owing to
  644. delays at the peripheral. After the peripheral has not responded for
  645. 'inactivity' jiffies, a timeout will occur and the blocking function
  646. will return.
  647. A timeout of 0 jiffies is a special case: the function must do as much
  648. as it can without blocking or leaving the hardware in an unknown
  649. state. If port operations are performed from within an interrupt
  650. handler, for instance, a timeout of 0 jiffies should be used.
  651. Once set for a registered device, the timeout will remain at the set
  652. value until set again.
  653. SEE ALSO
  654. port->ops->xxx_read/write_yyy
  655. PORT FUNCTIONS
  656. --------------
  657. The functions in the port->ops structure (struct parport_operations)
  658. are provided by the low-level driver responsible for that port.
  659. port->ops->read_data - read the data register
  660. --------------------
  661. SYNOPSIS
  662. #include <linux/parport.h>
  663. struct parport_operations {
  664. ...
  665. unsigned char (*read_data) (struct parport *port);
  666. ...
  667. };
  668. DESCRIPTION
  669. If port->modes contains the PARPORT_MODE_TRISTATE flag and the
  670. PARPORT_CONTROL_DIRECTION bit in the control register is set, this
  671. returns the value on the data pins. If port->modes contains the
  672. PARPORT_MODE_TRISTATE flag and the PARPORT_CONTROL_DIRECTION bit is
  673. not set, the return value _may_ be the last value written to the data
  674. register. Otherwise the return value is undefined.
  675. SEE ALSO
  676. write_data, read_status, write_control
  677. port->ops->write_data - write the data register
  678. ---------------------
  679. SYNOPSIS
  680. #include <linux/parport.h>
  681. struct parport_operations {
  682. ...
  683. void (*write_data) (struct parport *port, unsigned char d);
  684. ...
  685. };
  686. DESCRIPTION
  687. Writes to the data register. May have side-effects (a STROBE pulse,
  688. for instance).
  689. SEE ALSO
  690. read_data, read_status, write_control
  691. port->ops->read_status - read the status register
  692. ----------------------
  693. SYNOPSIS
  694. #include <linux/parport.h>
  695. struct parport_operations {
  696. ...
  697. unsigned char (*read_status) (struct parport *port);
  698. ...
  699. };
  700. DESCRIPTION
  701. Reads from the status register. This is a bitmask:
  702. - PARPORT_STATUS_ERROR (printer fault, "nFault")
  703. - PARPORT_STATUS_SELECT (on-line, "Select")
  704. - PARPORT_STATUS_PAPEROUT (no paper, "PError")
  705. - PARPORT_STATUS_ACK (handshake, "nAck")
  706. - PARPORT_STATUS_BUSY (busy, "Busy")
  707. There may be other bits set.
  708. SEE ALSO
  709. read_data, write_data, write_control
  710. port->ops->read_control - read the control register
  711. -----------------------
  712. SYNOPSIS
  713. #include <linux/parport.h>
  714. struct parport_operations {
  715. ...
  716. unsigned char (*read_control) (struct parport *port);
  717. ...
  718. };
  719. DESCRIPTION
  720. Returns the last value written to the control register (either from
  721. write_control or frob_control). No port access is performed.
  722. SEE ALSO
  723. read_data, write_data, read_status, write_control
  724. port->ops->write_control - write the control register
  725. ------------------------
  726. SYNOPSIS
  727. #include <linux/parport.h>
  728. struct parport_operations {
  729. ...
  730. void (*write_control) (struct parport *port, unsigned char s);
  731. ...
  732. };
  733. DESCRIPTION
  734. Writes to the control register. This is a bitmask:
  735. _______
  736. - PARPORT_CONTROL_STROBE (nStrobe)
  737. _______
  738. - PARPORT_CONTROL_AUTOFD (nAutoFd)
  739. _____
  740. - PARPORT_CONTROL_INIT (nInit)
  741. _________
  742. - PARPORT_CONTROL_SELECT (nSelectIn)
  743. SEE ALSO
  744. read_data, write_data, read_status, frob_control
  745. port->ops->frob_control - write control register bits
  746. -----------------------
  747. SYNOPSIS
  748. #include <linux/parport.h>
  749. struct parport_operations {
  750. ...
  751. unsigned char (*frob_control) (struct parport *port,
  752. unsigned char mask,
  753. unsigned char val);
  754. ...
  755. };
  756. DESCRIPTION
  757. This is equivalent to reading from the control register, masking out
  758. the bits in mask, exclusive-or'ing with the bits in val, and writing
  759. the result to the control register.
  760. As some ports don't allow reads from the control port, a software copy
  761. of its contents is maintained, so frob_control is in fact only one
  762. port access.
  763. SEE ALSO
  764. read_data, write_data, read_status, write_control
  765. port->ops->enable_irq - enable interrupt generation
  766. ---------------------
  767. SYNOPSIS
  768. #include <linux/parport.h>
  769. struct parport_operations {
  770. ...
  771. void (*enable_irq) (struct parport *port);
  772. ...
  773. };
  774. DESCRIPTION
  775. The parallel port hardware is instructed to generate interrupts at
  776. appropriate moments, although those moments are
  777. architecture-specific. For the PC architecture, interrupts are
  778. commonly generated on the rising edge of nAck.
  779. SEE ALSO
  780. disable_irq
  781. port->ops->disable_irq - disable interrupt generation
  782. ----------------------
  783. SYNOPSIS
  784. #include <linux/parport.h>
  785. struct parport_operations {
  786. ...
  787. void (*disable_irq) (struct parport *port);
  788. ...
  789. };
  790. DESCRIPTION
  791. The parallel port hardware is instructed not to generate interrupts.
  792. The interrupt itself is not masked.
  793. SEE ALSO
  794. enable_irq
  795. port->ops->data_forward - enable data drivers
  796. -----------------------
  797. SYNOPSIS
  798. #include <linux/parport.h>
  799. struct parport_operations {
  800. ...
  801. void (*data_forward) (struct parport *port);
  802. ...
  803. };
  804. DESCRIPTION
  805. Enables the data line drivers, for 8-bit host-to-peripheral
  806. communications.
  807. SEE ALSO
  808. data_reverse
  809. port->ops->data_reverse - tristate the buffer
  810. -----------------------
  811. SYNOPSIS
  812. #include <linux/parport.h>
  813. struct parport_operations {
  814. ...
  815. void (*data_reverse) (struct parport *port);
  816. ...
  817. };
  818. DESCRIPTION
  819. Places the data bus in a high impedance state, if port->modes has the
  820. PARPORT_MODE_TRISTATE bit set.
  821. SEE ALSO
  822. data_forward
  823. port->ops->epp_write_data - write EPP data
  824. -------------------------
  825. SYNOPSIS
  826. #include <linux/parport.h>
  827. struct parport_operations {
  828. ...
  829. size_t (*epp_write_data) (struct parport *port, const void *buf,
  830. size_t len, int flags);
  831. ...
  832. };
  833. DESCRIPTION
  834. Writes data in EPP mode, and returns the number of bytes written.
  835. The 'flags' parameter may be one or more of the following,
  836. bitwise-or'ed together:
  837. PARPORT_EPP_FAST Use fast transfers. Some chips provide 16-bit and
  838. 32-bit registers. However, if a transfer
  839. times out, the return value may be unreliable.
  840. SEE ALSO
  841. epp_read_data, epp_write_addr, epp_read_addr
  842. port->ops->epp_read_data - read EPP data
  843. ------------------------
  844. SYNOPSIS
  845. #include <linux/parport.h>
  846. struct parport_operations {
  847. ...
  848. size_t (*epp_read_data) (struct parport *port, void *buf,
  849. size_t len, int flags);
  850. ...
  851. };
  852. DESCRIPTION
  853. Reads data in EPP mode, and returns the number of bytes read.
  854. The 'flags' parameter may be one or more of the following,
  855. bitwise-or'ed together:
  856. PARPORT_EPP_FAST Use fast transfers. Some chips provide 16-bit and
  857. 32-bit registers. However, if a transfer
  858. times out, the return value may be unreliable.
  859. SEE ALSO
  860. epp_write_data, epp_write_addr, epp_read_addr
  861. port->ops->epp_write_addr - write EPP address
  862. -------------------------
  863. SYNOPSIS
  864. #include <linux/parport.h>
  865. struct parport_operations {
  866. ...
  867. size_t (*epp_write_addr) (struct parport *port,
  868. const void *buf, size_t len, int flags);
  869. ...
  870. };
  871. DESCRIPTION
  872. Writes EPP addresses (8 bits each), and returns the number written.
  873. The 'flags' parameter may be one or more of the following,
  874. bitwise-or'ed together:
  875. PARPORT_EPP_FAST Use fast transfers. Some chips provide 16-bit and
  876. 32-bit registers. However, if a transfer
  877. times out, the return value may be unreliable.
  878. (Does PARPORT_EPP_FAST make sense for this function?)
  879. SEE ALSO
  880. epp_write_data, epp_read_data, epp_read_addr
  881. port->ops->epp_read_addr - read EPP address
  882. ------------------------
  883. SYNOPSIS
  884. #include <linux/parport.h>
  885. struct parport_operations {
  886. ...
  887. size_t (*epp_read_addr) (struct parport *port, void *buf,
  888. size_t len, int flags);
  889. ...
  890. };
  891. DESCRIPTION
  892. Reads EPP addresses (8 bits each), and returns the number read.
  893. The 'flags' parameter may be one or more of the following,
  894. bitwise-or'ed together:
  895. PARPORT_EPP_FAST Use fast transfers. Some chips provide 16-bit and
  896. 32-bit registers. However, if a transfer
  897. times out, the return value may be unreliable.
  898. (Does PARPORT_EPP_FAST make sense for this function?)
  899. SEE ALSO
  900. epp_write_data, epp_read_data, epp_write_addr
  901. port->ops->ecp_write_data - write a block of ECP data
  902. -------------------------
  903. SYNOPSIS
  904. #include <linux/parport.h>
  905. struct parport_operations {
  906. ...
  907. size_t (*ecp_write_data) (struct parport *port,
  908. const void *buf, size_t len, int flags);
  909. ...
  910. };
  911. DESCRIPTION
  912. Writes a block of ECP data. The 'flags' parameter is ignored.
  913. RETURN VALUE
  914. The number of bytes written.
  915. SEE ALSO
  916. ecp_read_data, ecp_write_addr
  917. port->ops->ecp_read_data - read a block of ECP data
  918. ------------------------
  919. SYNOPSIS
  920. #include <linux/parport.h>
  921. struct parport_operations {
  922. ...
  923. size_t (*ecp_read_data) (struct parport *port,
  924. void *buf, size_t len, int flags);
  925. ...
  926. };
  927. DESCRIPTION
  928. Reads a block of ECP data. The 'flags' parameter is ignored.
  929. RETURN VALUE
  930. The number of bytes read. NB. There may be more unread data in a
  931. FIFO. Is there a way of stunning the FIFO to prevent this?
  932. SEE ALSO
  933. ecp_write_block, ecp_write_addr
  934. port->ops->ecp_write_addr - write a block of ECP addresses
  935. -------------------------
  936. SYNOPSIS
  937. #include <linux/parport.h>
  938. struct parport_operations {
  939. ...
  940. size_t (*ecp_write_addr) (struct parport *port,
  941. const void *buf, size_t len, int flags);
  942. ...
  943. };
  944. DESCRIPTION
  945. Writes a block of ECP addresses. The 'flags' parameter is ignored.
  946. RETURN VALUE
  947. The number of bytes written.
  948. NOTES
  949. This may use a FIFO, and if so shall not return until the FIFO is empty.
  950. SEE ALSO
  951. ecp_read_data, ecp_write_data
  952. port->ops->nibble_read_data - read a block of data in nibble mode
  953. ---------------------------
  954. SYNOPSIS
  955. #include <linux/parport.h>
  956. struct parport_operations {
  957. ...
  958. size_t (*nibble_read_data) (struct parport *port,
  959. void *buf, size_t len, int flags);
  960. ...
  961. };
  962. DESCRIPTION
  963. Reads a block of data in nibble mode. The 'flags' parameter is ignored.
  964. RETURN VALUE
  965. The number of whole bytes read.
  966. SEE ALSO
  967. byte_read_data, compat_write_data
  968. port->ops->byte_read_data - read a block of data in byte mode
  969. -------------------------
  970. SYNOPSIS
  971. #include <linux/parport.h>
  972. struct parport_operations {
  973. ...
  974. size_t (*byte_read_data) (struct parport *port,
  975. void *buf, size_t len, int flags);
  976. ...
  977. };
  978. DESCRIPTION
  979. Reads a block of data in byte mode. The 'flags' parameter is ignored.
  980. RETURN VALUE
  981. The number of bytes read.
  982. SEE ALSO
  983. nibble_read_data, compat_write_data
  984. port->ops->compat_write_data - write a block of data in compatibility mode
  985. ----------------------------
  986. SYNOPSIS
  987. #include <linux/parport.h>
  988. struct parport_operations {
  989. ...
  990. size_t (*compat_write_data) (struct parport *port,
  991. const void *buf, size_t len, int flags);
  992. ...
  993. };
  994. DESCRIPTION
  995. Writes a block of data in compatibility mode. The 'flags' parameter
  996. is ignored.
  997. RETURN VALUE
  998. The number of bytes written.
  999. SEE ALSO
  1000. nibble_read_data, byte_read_data