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