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