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