| blob | 6723835203c0b00836b73ce840b4798ea635956c |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH ECPP 7D "Oct 9, 2004"
7 .SH NAME
8 ecpp \- IEEE 1284 compliant parallel port driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/types.h>
13 .fi
15 .LP
16 .nf
17 #include <sys/ecppio.h>
18 .fi
20 .LP
21 .nf
22 ecpp@unit-address
23 .fi
25 .SH DESCRIPTION
26 .sp
27 .LP
28 The \fBecpp\fR driver provides a bi-directional interface to \fIIEEE 1284\fR
29 compliant devices as well as a forward single-directional interface to
30 Centronics devices. In addition to the Centronics protocol, the \fBecpp\fR
31 driver supports the \fIIEEE 1284\fRCompatibility, Nibble, and ECP protocols.
32 \fBECPP_COMPAT_MODE\fR and \fBECPP_CENTRONICS\fR modes of operation have
33 logically identical handshaking protocols, however devices that support
34 \fBECPP_COMPAT_MODE\fR are \fIIEEE 1284\fR compliant devices. \fIIEEE 1284\fR
35 compliant devices support at least \fBECPP_COMPAT_MODE\fR and
36 \fBECPP_NIBBLE_MODE\fR. Centronics devices support only \fBECPP_CENTRONICS\fR
37 mode.
38 .sp
39 .LP
40 By default, \fBECPP_COMPAT_MODE\fR devices have a strobe handshaking pulse
41 width of 500ns. For this mode, forward data transfers are conducted by DMA. By
42 default, the strobe pulse width for \fBECPP_CENTRONICS\fR devices is two
43 microseconds. Forward transfers for these devices are managed through PIO. The
44 default characteristics for both \fBECPP_COMPAT_MODE\fR and
45 \fBECPP_CENTRONICS\fR devices may be changed through tunable variables defined
46 in \fBecpp.conf\fR.
47 .sp
48 .LP
49 The \fBecpp\fR driver is an \fIexclusive-use\fR device, meaning that if the
50 device is already open, subsequent opens fail with \fBEBUSY\fR.
51 .SS "Default Operation"
52 .sp
53 .LP
54 Each time the \fBecpp\fR device is opened, the device is marked as \fBEBUSY\fR
55 and the configuration variables are set to their default values. The
56 \fBwrite_timeout\fR period is set to 90 seconds.
57 .sp
58 .LP
59 The driver sets the mode variable according to the following algorithm: The
60 driver initially attempts to negotiate the link into \fBECPP_ECP_MODE\fR during
61 \fBopen\fR(2). If it fails, the driver tries to negotiate into
62 \fBECPP_NIBBLE_MODE\fR mode. If that fails, the driver operates in
63 \fBECPP_CENTRONICS\fR mode. Upon successfully opening the device, \fIIEEE
64 1284\fR compliant devices will be left idle in either reverse idle phase of
65 \fBECPP_ECP_MODE\fR or in \fBECPP_NIBBLE_MODE\fR. Subsequent calls to
66 \fBwrite\fR(2) invokes the driver to move the link into either
67 \fBECPP_COMPAT_MODE\fR or the forward phase of \fBECPP_ECP_MODE\fR. After the
68 transfer completes, the link returns to idle state.
69 .sp
70 .LP
71 The application may attempt to negotiate the device into a specific mode or set
72 the \fBwrite_timeout\fR values through the \fBECPPIOC_SETPARMS\fR
73 \fBioctl\fR(2) call. For mode negotiation to be successful, both the host
74 workstation and the peripheral must support the requested mode.
75 .SS "Tunables"
76 .sp
77 .LP
78 Characteristics of the \fBecpp\fR driver may be tuned by the variables
79 described in \fB/kernel/drv/ecpp.conf\fR. These variables are read by the
80 kernel during system startup. To tune the variables, edit the \fBecpp.conf\fR
81 file and invoke \fBupdate_drv\fR(1M) to have the kernel read the file again.
82 .sp
83 .LP
84 Some Centronics peripherals and certain \fIIEEE 1284\fR compatible peripherals
85 will not operate with the parallel port operating in a fast handshaking mode.
86 If printing problems occur, set "fast-centronics" and "fast-1284-compatible" to
87 "false." See \fB/kernel/drv/ecpp.conf\fR for more information.
88 .SS "Read/Write Operation"
89 .sp
90 .LP
91 The \fBecpp\fR driver is a full duplex STREAMS device driver. While an
92 application is writing to an \fIIEEE 1284\fR compliant device, another thread
93 may read from it.
94 .SS "Write Operation"
95 .sp
96 .LP
97 A \fBwrite\fR(2) operation returns the number of bytes successfully written to
98 the stream head. If a failure occurs while a Centronics device is transferring
99 data, the content of the status bits will be captured at the time of the error
100 and can be retrieved by the application program using the \fBBPPIOC_GETERR\fR
101 \fBioctl\fR(2) call. The captured status information is overwritten each time
102 an attempted transfer or a \fBBPPIOC_TESTIO\fR \fBioctl\fR(2) occurs.
103 .SS "Read Operation"
104 .sp
105 .LP
106 If a failure or error condition occurs during a \fBread\fR(2), the number of
107 bytes successfully read is returned (short read). When attempting to read a
108 port that has no data currently available, \fBread\fR(2) returns \fB0\fR if
109 \fBO_NDELAY\fR is set. If \fBO_NONBLOCK\fR is set, \fBread\fR(2) returns
110 \fB-1\fR and sets errno to \fBEAGAIN.\fR If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR
111 are clear, \fBread\fR(2) blocks until data become available.
112 .SH IOCTLS
113 .sp
114 .LP
115 The \fBioctl\fR(2) calls described below are supported. Note that when
116 \fBecpp\fR is transferring data, the driver waits until the data has been sent
117 to the device before processing the \fBioctl\fR(2) call.
118 .sp
119 .LP
120 The ecpp driver supports \fBprnio\fR(7I) interfaces.
121 .LP
122 Note -
123 .sp
124 .RS 2
125 The \fBPRNIOC_RESET\fR command toggles the \fBnInit\fR signal for 2 ms,
126 followed by default negotiation.
127 .RE
128 .sp
129 .LP
130 The following \fBioctl(2)\fR calls are supported for backward compatibility and
131 are not recommended for new applications:
132 .sp
133 .ne 2
134 .na
135 \fB\fBECPPIOC_GETPARMS\fR\fR
136 .ad
137 .RS 20n
138 Get current transfer parameters. The argument is a pointer to a struct
139 \fBecpp_transfer_parms\fR. See below for a description of the elements of this
140 structure. If no parameters have been configured since the device was opened,
141 the structure will be set to its default configuration. See Default Operation
142 above for more information.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBECPPIOC_SETPARMS\fR\fR
149 .ad
150 .RS 20n
151 Set transfer parameters. The argument is a pointer to a struct
152 \fBecpp_transfer_parms\fR. If a parameter is out of range, \fBEINVAL\fR is
153 returned. If the peripheral or host device cannot support the requested mode,
154 \fBEPROTONOSUPPORT\fR is returned. See below for a description of
155 \fBecpp_transfer_parms\fR and its valid parameters.
156 .sp
157 The Transfer Parameters Structure is defined in <\fBsys/ecppio.h\fR>.
158 .sp
159 .in +2
160 .nf
161 struct ecpp_transfer_parms {
162 int write_timeout;
163 int mode;
164 };
165 .fi
166 .in -2
168 The \fBwrite_timeout\fR field is set to the value of
169 \fBecpp-transfer-timeout\fR specified in the \fBecpp.conf\fR. The
170 \fBwrite_timeout\fR field specifies how long the driver will wait for the
171 peripheral to respond to a transfer request. The value must be greater than
172 \fB0\fR and less than \fBECPP_MAX_TIMEOUT.\fR All other values are out of
173 range.
174 .sp
175 The mode field reflects the \fIIEEE 1284\fR mode to which the parallel port is
176 currently configured. The mode may be set to one of the following values only:
177 \fBECPP_CENTRONICS\fR, \fBECPP_COMPAT_MODE\fR, \fBECPP_NIBBLE_MODE\fR,
178 \fBECPP_ECP_MODE\fR. All other values are invalid. If the requested mode is not
179 supported, \fBECPPIOC_SETPARMS\fR will return \fBEPROTONOSUPPORT\fR and the
180 mode will be set to \fBECPP_CENTRONICS\fR mode. Afterwards, the application may
181 change the mode back to the original mode with \fBECPPIOC_SETPARMS\fR.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBECPPIOC_GETDEVID\fR\fR
188 .ad
189 .RS 20n
190 This ioctl gets the \fIIEEE 1284\fR device ID from the peripheral in specified
191 mode. Currently, the device ID can be retrieved only in Nibble mode. A pointer
192 to the structure defined in \fB<sys/ecppsys.h>\fR must be passed as an
193 argument.
194 .sp
195 The 1284 device ID structure:
196 .sp
197 .in +2
198 .nf
199 struct ecpp_device_id {
200 int mode; /* mode to use for reading device id */
201 int len; /* length of buffer */
202 int rlen; /* actual length of device id string */
203 char *addr; /* buffer address */
204 };
205 .fi
206 .in -2
208 The mode is the \fIIEEE 1284\fR mode into which the port will be negotiated to
209 retrieve device ID information. If the peripheral or host do not support the
210 mode, \fBEPROTONOSUPPORT\fR is returned. Applications should set mode to
211 \fBECPP_NIBBLE_MODE\fR. \fBlen\fR is the length of the buffer pointed to by
212 \fBaddr\fR. \fBrlen\fR is the actual length of the device ID string returned
213 from the peripheral. If the returned \fBrlen\fR is greater than \fBlen\fR, the
214 application can call \fBECPPIOC_GETDEVID\fR again with a buffer length equal or
215 greater than \fBrlen\fR. Note that the two length bytes of the \fIIEEE 1284\fR
216 device ID are not taken into account and are not returned in the user buffer.
217 .sp
218 After \fBECPPIOC_GETDEVID\fR successfully completes, the driver returns the
219 link to \fBECPP_COMPAT_MODE\fR. The application is responsible for determining
220 the previous mode the link was operating in and returning the link to that
221 mode.
222 .RE
224 .sp
225 .ne 2
226 .na
227 \fB\fBBPPIOC_TESTIO\fR\fR
228 .ad
229 .RS 20n
230 Tests the forward transfer readiness of a peripheral operating in Centronics or
231 Compatibility mode.
232 .sp
233 \fBTESTIO\fR determines if the peripheral is ready to receive data by checking
234 the open flags and the Centronics status signals. If the current mode of the
235 device is \fBECPP_NIBBLE_MODE\fR, the driver negotiates the link into
236 \fBECPP_COMPAT_MODE\fR, check the status signals and then return the link to
237 \fBECPP_NIBBLE_MODE\fR mode. If the current mode is \fBECPP_CENTRONICS\fR or
238 \fBECPP_COMPAT_MODE\fR, \fBTESTIO\fR examines the Centronics status signals in
239 the current mode. To receive data, the device must have the \fBnErr\fR and
240 \fBSelect\fR signals asserted and must not have the \fBPE\fR and \fBBusy\fR
241 signals asserted. If \fBecpp\fR is transferring data, \fBTESTIO\fR waits until
242 the previous data sent to the driver is delivered before executing
243 \fBTESTIO\fR. However if an error condition occurs while a \fBTESTIO\fR is
244 waiting, \fBTESTIO\fR returns immediately. If \fBTESTIO\fR determines that the
245 conditions are ok, \fB0\fR is returned. Otherwise, \fB-1\fR is returned, errno
246 is set to \fBEIO\fR and the state of the status pins is captured. The captured
247 status can be retrieved using the \fBBPPIOC_GETERR\fR \fBioctl\fR(2) call. The
248 \fBtimeout_occurred\fR and \fBbus_error\fR fields will never be set by this
249 \fBioctl\fR(2). \fBBPPIOC_TESTIO\fR and \fBBPPIOC_GETERR\fR are compatible to
250 the ioctls specified in \fBbpp\fR(7D).
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBBPPIOC_GETERR\fR\fR
257 .ad
258 .RS 20n
259 Get last error status. The argument is a pointer to a \fBstruct
260 bpp_error_status\fR defined in \fB<sys/bpp_io.h>\fR header file. The error
261 status structure is:
262 .sp
263 .in +2
264 .nf
265 struct bpp_error_status {
266 char timeout_occurred; /* 1=timeout */
267 char bus_error; /* not used */
268 uchar_t pin_status; /* status of pins which
269 /* could cause error */
270 };
271 .fi
272 .in -2
274 The pin_status field indicates possible error conditions. The valid bits for
275 pin_status are: \fBBPP_ERR_ERR\fR, \fBBPP_SLCT_ERR\fR, \fBBPP_PE_ERR\fR,
276 \fBBPP_BUSY_ERR\fR. A set bit indicates that the associated pin is asserted.
277 .sp
278 This structure indicates the status of all the appropriate status bits at the
279 time of the most recent error condition during a \fBwrite\fR(2) call, or the
280 status of the bits at the most recent \fBBPPIOC_TESTIO\fR \fBioctl\fR(2)call.
281 .sp
282 \fBpin_status\fR indicates possible error conditions under
283 \fBECPP_CENTRONICS\fR or \fBECPP_COMPAT_MODE\fR. Under these modes, the state
284 of the status pins will indicate the state of the device. For instance, many
285 Centronics printers lower the \fBnErr\fR signal when a paper jam occurs. The
286 behavior of the status pins depends on the device. Additional status
287 information may be retrieved through the backchannel.
288 .sp
289 The \fBtimeout_occurred\fR value is set when a timeout occurs during
290 \fBwrite\fR(2). \fBbus_error\fR is not used in this interface.
291 .RE
293 .sp
294 .LP
295 The following ioctls are used to directly read and write the parallel port
296 status and control signals. If the current mode of the device is
297 \fBECPP_ECP_MODE\fR or \fBECPP_NIBBLE_MODE\fR, the driver negotiates the link
298 into \fBECPP_COMPAT_MODE\fR, gets or sets the registers and then returns the
299 link to \fBECPP_NIBBLE_MODE\fR. If the current mode is \fBECPP_CENTRONICS\fR or
300 \fBECPP_COMPAT_MODE\fR, these ioctls will get/set the register values in the
301 current mode.
302 .sp
303 .ne 2
304 .na
305 \fB\fBECPPIOC_GETREGS\fR\fR
306 .ad
307 .RS 19n
308 Read register values. The argument is a pointer to a \fBstruct ecpp_regs\fR.
309 See below for a description of this structure.
310 .RE
312 .sp
313 .ne 2
314 .na
315 \fB\fBECPPIOC_SETREGS\fR\fR
316 .ad
317 .RS 19n
318 Set \fBecpp\fR register values. The argument is a pointer to a \fBstruct
319 ecpp_regs\fR. See below for a description of this structure. If a parameter is
320 out of range, \fBEINVAL\fR is returned.
321 .sp
322 The Port Register Structure is defined in <\fBsys/ecppio.h\fR>.
323 .sp
324 .in +2
325 .nf
326 struct ecpp_regs {
327 uchar dsr; /* status reg */
328 u_char dcr; /* control reg */
329 };
330 .fi
331 .in -2
333 The status register is read-only. The \fBECPPIOC_SETREGS\fR ioctl has no affect
334 on this register. Valid bit values for dsr are: \fBECPP_nERR\fR,
335 \fBECPP_SLCT\fR, \fBECPP_PE\fR, \fBECPP_nACK\fR, \fBECPP_nBUSY\fR. All other
336 bits are reserved and always return \fB1\fR.
337 .sp
338 The control register is read/write. Valid bit values for dcr are:
339 \fBECPP_STB\fR, \fBECPP_AFX\fR, \fBECPP_nINIT\fR, \fBECPP_SLCTIN\fR. All other
340 bits are reserved. Reading reserved bits always return 1. An attempt to write
341 0s into these bits results in \fBEINVAL\fR.
342 .RE
344 .SH DEVICE SPECIAL FILES
345 .sp
346 .ne 2
347 .na
348 \fB\fB/dev/lp\fIN\fR\fR\fR
349 .ad
350 .RS 19n
351 Solaris x86 only. (Backwards compatibility with former \fBlp\fR(7D) devices.)
352 .RE
354 .sp
355 .ne 2
356 .na
357 \fB\fB/dev/printers/\fIN\fR\fR\fR
358 .ad
359 .RS 19n
360 1284 compliant parallel port device special files appears in both namespaces.
361 .RE
363 .SH FILES
364 .sp
365 .ne 2
366 .na
367 \fB\fBkernel/drv/ecpp\fR\fR
368 .ad
369 .sp .6
370 .RS 4n
371 32-bit ELF kernel module
372 .RE
374 .sp
375 .ne 2
376 .na
377 \fB\fBkernel/drv/sparcv9/ecpp\fR\fR
378 .ad
379 .sp .6
380 .RS 4n
381 64-bit SPARC ELF kernel module
382 .RE
384 .sp
385 .ne 2
386 .na
387 \fB\fBkernel/drv/amd64/ecpp\fR\fR
388 .ad
389 .sp .6
390 .RS 4n
391 64-bit x86 ELF kernel module
392 .RE
394 .sp
395 .ne 2
396 .na
397 \fB\fBkernel/drv/ecpp.conf\fR\fR
398 .ad
399 .sp .6
400 .RS 4n
401 driver configuration file
402 .RE
404 .sp
405 .ne 2
406 .na
407 \fB\fBkernel/drv/sparcv9/ecpp.conf\fR\fR
408 .ad
409 .sp .6
410 .RS 4n
411 driver configuration file for 64-bit SPARC
412 .RE
414 .sp
415 .ne 2
416 .na
417 \fB\fBkernel/drv/amd64/ecpp.conf\fR\fR
418 .ad
419 .sp .6
420 .RS 4n
421 driver configuration file for 64-bit x86
422 .RE
424 .SH ERRORS
425 .sp
426 .ne 2
427 .na
428 \fB\fBEBADF\fR\fR
429 .ad
430 .RS 10n
431 The device is opened for write-only access and a read is attempted, or the
432 device is opened for read-only access and a write is attempted.
433 .RE
435 .sp
436 .ne 2
437 .na
438 \fB\fBEBUSY\fR\fR
439 .ad
440 .RS 10n
441 The device has been opened and another open is attempted. An attempt has been
442 made to unload the driver while one of the units is open.
443 .RE
445 .sp
446 .ne 2
447 .na
448 \fB\fBEINVAL\fR\fR
449 .ad
450 .RS 10n
451 A \fBECPPIOC_SETPARMS\fR \fBioctl()\fR is attempted with an out-of-range value
452 in the \fBecpp_transfer_parms\fR structure. A \fBECPPIOC_SETREGS\fR
453 \fBioctl()\fR is attempted with an invalid value in the \fBecpp_regs\fR
454 structure. An \fBioctl()\fR is attempted with an invalid value in the command
455 argument.An invalid command argument is received during \fBmodload\fR(1M) or
456 \fBmodunload\fR(1M).
457 .RE
459 .sp
460 .ne 2
461 .na
462 \fB\fBEIO\fR\fR
463 .ad
464 .RS 10n
465 The driver encountered a bus error when attempting an access. A read or write
466 did not complete properly, due to a peripheral error or a transfer timeout.
467 .RE
469 .sp
470 .ne 2
471 .na
472 \fB\fBENXIO\fR\fR
473 .ad
474 .RS 10n
475 The driver has received an open request for a unit for which the attach failed.
476 The driver has received a write request for a unit which has an active
477 peripheral error.
478 .RE
480 .SH ATTRIBUTES
481 .sp
482 .LP
483 See \fBattributes\fR(5) for descriptions of the following attributes:
484 .sp
486 .sp
487 .TS
488 box;
489 c | c
490 l | l .
491 ATTRIBUTE TYPE ATTRIBUTE VALUE
492 _
493 Architecture PCI-based systems
494 _
495 ISA-based systems (x86)
496 _
497 Interface stability Evolving
498 .TE
500 .SH SEE ALSO
501 .sp
502 .LP
503 \fBmodload\fR(1M), \fBmodunload\fR(1M), \fBupdate_drv\fR(1M)\fBioctl\fR(2),
504 \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5),
505 \fBbpp\fR(7D), \fBusbprn\fR(7D), \fBprnio\fR(7I), \fBstreamio\fR(7I)
506 .sp
507 .LP
508 \fIIEEE Std 1284-1994\fR
509 .sp
510 .LP
511 \fIhttp://www.sun.com/io\fR
512 .SH DIAGNOSTICS
513 .sp
514 .ne 2
515 .na
516 \fBParallel port controller not supported\fR
517 .ad
518 .sp .6
519 .RS 4n
520 Driver does not support parallel port controller on the given host. Attach
521 failed.
522 .RE