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 1284 Compatibility, 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).
230
231
232 BPPIOC_GETERR
233 Get last error status. The argument is a pointer to
234 a struct bpp_error_status defined in <sys/bpp_io.h>
235 header file. The error status structure is:
236
237 struct bpp_error_status {
238 char timeout_occurred; /* 1=timeout */
239 char bus_error; /* not used */
240 uchar_t pin_status; /* status of pins which
241 /* could cause error */
242 };
243
244 The pin_status field indicates possible error
245 conditions. The valid bits for pin_status are:
246 BPP_ERR_ERR, BPP_SLCT_ERR, BPP_PE_ERR,
247 BPP_BUSY_ERR. A set bit indicates that the
248 associated pin is asserted.
249
250 This structure indicates the status of all the
251 appropriate status bits at the time of the most
252 recent error condition during a write(2) call, or
253 the status of the bits at the most recent
254 BPPIOC_TESTIO ioctl(2)call.
255
256 pin_status indicates possible error conditions
257 under ECPP_CENTRONICS or ECPP_COMPAT_MODE. Under
258 these modes, the state of the status pins will
259 indicate the state of the device. For instance,
260 many Centronics printers lower the nErr signal when
261 a paper jam occurs. The behavior of the status pins
262 depends on the device. Additional status
263 information may be retrieved through the
264 backchannel.
265
266 The timeout_occurred value is set when a timeout
267 occurs during write(2). bus_error is not used in
268 this interface.
269
270
271
272 The following ioctls are used to directly read and write the parallel
273 port status and control signals. If the current mode of the device is
274 ECPP_ECP_MODE or ECPP_NIBBLE_MODE, the driver negotiates the link into
275 ECPP_COMPAT_MODE, gets or sets the registers and then returns the link
276 to ECPP_NIBBLE_MODE. If the current mode is ECPP_CENTRONICS or
277 ECPP_COMPAT_MODE, these ioctls will get/set the register values in the
278 current mode.
279
280 ECPPIOC_GETREGS
281 Read register values. The argument is a pointer to a
282 struct ecpp_regs. See below for a description of
283 this structure.
284
285
286 ECPPIOC_SETREGS
287 Set ecpp register values. The argument is a pointer
288 to a struct ecpp_regs. See below for a description
289 of this structure. If a parameter is out of range,
290 EINVAL is returned.
291
292 The Port Register Structure is defined in
293 <sys/ecppio.h>.
294
295 struct ecpp_regs {
296 uchar dsr; /* status reg */
297 u_char dcr; /* control reg */
298 };
299
300 The status register is read-only. The
301 ECPPIOC_SETREGS ioctl has no affect on this
302 register. Valid bit values for dsr are: ECPP_nERR,
303 ECPP_SLCT, ECPP_PE, ECPP_nACK, ECPP_nBUSY. All other
304 bits are reserved and always return 1.
305
306 The control register is read/write. Valid bit values
307 for dcr are: ECPP_STB, ECPP_AFX, ECPP_nINIT,
308 ECPP_SLCTIN. All other bits are reserved. Reading
309 reserved bits always return 1. An attempt to write
310 0s into these bits results in EINVAL.
311
312
313 DEVICE SPECIAL FILES
314 /dev/lpN
315 x86 only. (Backwards compatibility with former
316 lp(7D) devices.)
317
318
319 /dev/printers/N
320 1284 compliant parallel port device special files
321 appears in both namespaces.
322
323
324 FILES
325 /kernel/drv/sparcv9/ecpp
326
327 Device driver (SPARC)
328
329
330 /kernel/drv/amd64/ecpp
331
332 Device driver (x86)
333
334
335 /kernel/drv/ecpp.conf
336
337 Driver configuration file
338
339
340 ERRORS
341 EBADF
342 The device is opened for write-only access and a read is
343 attempted, or the device is opened for read-only access and a
344 write is attempted.
345
346
347 EBUSY
348 The device has been opened and another open is attempted. An
349 attempt has been made to unload the driver while one of the
350 units is open.
351
352
353 EINVAL
354 A ECPPIOC_SETPARMS ioctl() is attempted with an out-of-range
355 value in the ecpp_transfer_parms structure. A ECPPIOC_SETREGS
356 ioctl() is attempted with an invalid value in the ecpp_regs
357 structure. An ioctl() is attempted with an invalid value in
358 the command argument.An invalid command argument is received
359 during modload(1M) or modunload(1M).
360
361
362 EIO
363 The driver encountered a bus error when attempting an access.
364 A read or write did not complete properly, due to a
365 peripheral error or a transfer timeout.
366
367
368 ENXIO
369 The driver has received an open request for a unit for which
370 the attach failed. The driver has received a write request
371 for a unit which has an active peripheral error.
372
373
374 ATTRIBUTES
375 See attributes(5) for descriptions of the following attributes:
376
377
378
379
380 +--------------------+-------------------------+
381 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
382 +--------------------+-------------------------+
383 |Architecture | PCI-based systems |
384 +--------------------+-------------------------+
385 | | ISA-based systems (x86) |
386 +--------------------+-------------------------+
387 |Interface stability | Evolving |
388 +--------------------+-------------------------+
389
390 SEE ALSO
391 modload(1M), modunload(1M), update_drv(1M), ioctl(2), open(2), read(2),
392 write(2), attributes(5), usbprn(7D), prnio(7I), streamio(7I)
393
394
395 IEEE Std 1284-1994
396
397 DIAGNOSTICS
398 Parallel port controller not supported
399
400 Driver does not support parallel port controller on the given host.
401 Attach failed.
402
403
404
405 May 17, 2020 ECPP(7D)