1ecpp(7D) Devices ecpp(7D)
2
6 ecpp - IEEE 1284 compliant parallel port driver
7
9 #include <sys/types.h>
10 #include <sys/ecppio.h>
13 ecpp@unit-address
16
19 The ecpp driver provides a bi-directional interface to IEEE 1284 com‐
20 pliant 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 ECPP_COM‐
25 PAT_MODE are IEEE 1284 compliant devices. IEEE 1284 compliant devices
26 support at least ECPP_COMPAT_MODE and ECPP_NIBBLE_MODE. Centronics
27 devices support only ECPP_CENTRONICS mode.
28 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 The ecpp driver is an exclusive-use device, meaning that if the device
40 is already open, subsequent opens fail with EBUSY.
41 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 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 ECPP_CEN‐
52 TRONICS mode. Upon successfully opening the device, IEEE 1284 compliant
53 devices will be left idle in either reverse idle phase of ECPP_ECP_MODE
54 or in ECPP_NIBBLE_MODE. Subsequent calls to write(2) invokes the driver
55 to move the link into either ECPP_COMPAT_MODE or the forward phase of
56 ECPP_ECP_MODE. After the transfer completes, the link returns to idle
57 state.
58 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 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 Some Centronics peripherals and certain IEEE 1284 compatible peripher‐
73 als will not operate with the parallel port operating in a fast hand‐
74 shaking mode. If printing problems occur, set "fast-centronics" and
75 "fast-1284-compatible" to "false." See /kernel/drv/ecpp.conf for more
76 information.
77 Read/Write Operation
79 The ecpp driver is a full duplex STREAMS device driver. While an appli‐
80 cation is writing to an IEEE 1284 compliant device, another thread may
81 read from it.
82 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 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
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 The ecpp driver supports prnio(7I) interfaces.
107 Note -
109 The PRNIOC_RESET command toggles the nInit signal for 2 ms, followed
111 by default negotiation.
112 The following ioctl(2) calls are supported for backward compatibility
115 and are not recommended for new applications:
116 ECPPIOC_GETPARMS Get current transfer parameters. The argument is a
118 pointer to a struct ecpp_transfer_parms. See below
119 for a description of the elements of this struc‐
120 ture. If no parameters have been configured since
121 the device was opened, the structure will be set to
122 its default configuration. See Default Operation
123 above for more information.
124 ECPPIOC_SETPARMS Set transfer parameters. The argument is a pointer
127 to a struct ecpp_transfer_parms. If a parameter is
128 out of range, EINVAL is returned. If the peripheral
129 or host device cannot support the requested mode,
130 EPROTONOSUPPORT is returned. See below for a
131 description of ecpp_transfer_parms and its valid
132 parameters.
133 The Transfer Parameters Structure is defined in
135 <sys/ecppio.h>.
136 struct ecpp_transfer_parms {
138 int write_timeout;
139 int mode;
140 };
141 The write_timeout field is set to the value of
143 ecpp-transfer-timeout specified in the ecpp.conf.
144 The write_timeout field specifies how long the
145 driver will wait for the peripheral to respond to a
146 transfer request. The value must be greater than 0
147 and less than ECPP_MAX_TIMEOUT. All other values
148 are out of range.
149 The mode field reflects the IEEE 1284 mode to which
151 the parallel port is currently configured. The mode
152 may be set to one of the following values only:
153 ECPP_CENTRONICS, ECPP_COMPAT_MODE, ECPP_NIB‐
154 BLE_MODE, ECPP_ECP_MODE. All other values are
155 invalid. If the requested mode is not supported,
156 ECPPIOC_SETPARMS will return EPROTONOSUPPORT and
157 the mode will be set to ECPP_CENTRONICS mode.
158 Afterwards, the application may change the mode
159 back to the original mode with ECPPIOC_SETPARMS.
160 ECPPIOC_GETDEVID This ioctl gets the IEEE 1284 device ID from the
163 peripheral in specified mode. Currently, the device
164 ID can be retrieved only in Nibble mode. A pointer
165 to the structure defined in <sys/ecppsys.h> must be
166 passed as an argument.
167 The 1284 device ID structure:
169 struct ecpp_device_id {
171 int mode; /* mode to use for reading device id */
172 int len; /* length of buffer */
173 int rlen; /* actual length of device id string */
174 char *addr; /* buffer address */
175 };
176 The mode is the IEEE 1284 mode into which the port
178 will be negotiated to retrieve device ID informa‐
179 tion. If the peripheral or host do not support the
180 mode, EPROTONOSUPPORT is returned. Applications
181 should set mode to ECPP_NIBBLE_MODE. len is the
182 length of the buffer pointed to by addr. rlen is
183 the actual length of the device ID string returned
184 from the peripheral. If the returned rlen is
185 greater than len, the application can call ECP‐
186 PIOC_GETDEVID again with a buffer length equal or
187 greater than rlen. Note that the two length bytes
188 of the IEEE 1284 device ID are not taken into
189 account and are not returned in the user buffer.
190 After ECPPIOC_GETDEVID successfully completes, the
192 driver returns the link to ECPP_COMPAT_MODE. The
193 application is responsible for determining the pre‐
194 vious mode the link was operating in and returning
195 the link to that mode.
196 BPPIOC_TESTIO Tests the forward transfer readiness of a periph‐
199 eral operating in Centronics or Compatibility mode.
200 TESTIO determines if the peripheral is ready to
202 receive data by checking the open flags and the
203 Centronics status signals. If the current mode of
204 the device is ECPP_NIBBLE_MODE, the driver negoti‐
205 ates the link into ECPP_COMPAT_MODE, check the sta‐
206 tus signals and then return the link to ECPP_NIB‐
207 BLE_MODE mode. If the current mode is ECPP_CENTRON‐
208 ICS or ECPP_COMPAT_MODE, TESTIO examines the Cen‐
209 tronics status signals in the current mode. To
210 receive data, the device must have the nErr and
211 Select signals asserted and must not have the PE
212 and Busy signals asserted. If ecpp is transferring
213 data, TESTIO waits until the previous data sent to
214 the driver is delivered before executing TESTIO.
215 However if an error condition occurs while a TESTIO
216 is waiting, TESTIO returns immediately. If TESTIO
217 determines that the conditions are ok, 0 is
218 returned. Otherwise, -1 is returned, errno is set
219 to EIO and the state of the status pins is cap‐
220 tured. The captured status can be retrieved using
221 the BPPIOC_GETERR ioctl(2) call. The time‐
222 out_occurred and bus_error fields will never be set
223 by this ioctl(2). BPPIOC_TESTIO and BPPIOC_GETERR
224 are compatible to the ioctls specified in bpp(7D).
225 BPPIOC_GETERR Get last error status. The argument is a pointer to
228 a struct bpp_error_status defined in <sys/bpp_io.h>
229 header file. The error status structure is:
230 struct bpp_error_status {
232 char timeout_occurred; /* 1=timeout */
233 char bus_error; /* not used */
234 uchar_t pin_status; /* status of pins which
235 /* could cause error */
236 };
237 The pin_status field indicates possible error con‐
239 ditions. The valid bits for pin_status are:
240 BPP_ERR_ERR, BPP_SLCT_ERR, BPP_PE_ERR,
241 BPP_BUSY_ERR. A set bit indicates that the associ‐
242 ated pin is asserted.
243 This structure indicates the status of all the
245 appropriate status bits at the time of the most
246 recent error condition during a write(2) call, or
247 the status of the bits at the most recent
248 BPPIOC_TESTIO ioctl(2)call.
249 pin_status indicates possible error conditions
251 under ECPP_CENTRONICS or ECPP_COMPAT_MODE. Under
252 these modes, the state of the status pins will
253 indicate the state of the device. For instance,
254 many Centronics printers lower the nErr signal when
255 a paper jam occurs. The behavior of the status pins
256 depends on the device. Additional status informa‐
257 tion may be retrieved through the backchannel.
258 The timeout_occurred value is set when a timeout
260 occurs during write(2). bus_error is not used in
261 this interface.
262 The following ioctls are used to directly read and write the parallel
266 port status and control signals. If the current mode of the device is
267 ECPP_ECP_MODE or ECPP_NIBBLE_MODE, the driver negotiates the link into
268 ECPP_COMPAT_MODE, gets or sets the registers and then returns the link
269 to ECPP_NIBBLE_MODE. If the current mode is ECPP_CENTRONICS or
270 ECPP_COMPAT_MODE, these ioctls will get/set the register values in the
271 current mode.
272 ECPPIOC_GETREGS Read register values. The argument is a pointer to a
274 struct ecpp_regs. See below for a description of
275 this structure.
276 ECPPIOC_SETREGS Set ecpp register values. The argument is a pointer
279 to a struct ecpp_regs. See below for a description
280 of this structure. If a parameter is out of range,
281 EINVAL is returned.
282 The Port Register Structure is defined in <sys/ecp‐
284 pio.h>.
285 struct ecpp_regs {
287 uchar dsr; /* status reg */
288 u_char dcr; /* control reg */
289 };
290 The status register is read-only. The ECP‐
292 PIOC_SETREGS ioctl has no affect on this register.
293 Valid bit values for dsr are: ECPP_nERR, ECPP_SLCT,
294 ECPP_PE, ECPP_nACK, ECPP_nBUSY. All other bits are
295 reserved and always return 1.
296 The control register is read/write. Valid bit values
298 for dcr are: ECPP_STB, ECPP_AFX, ECPP_nINIT,
299 ECPP_SLCTIN. All other bits are reserved. Reading
300 reserved bits always return 1. An attempt to write
301 0s into these bits results in EINVAL.
302
305 /dev/lpN Solaris x86 only. (Backwards compatibility with for‐
306 mer lp(7D) devices.)
307 /dev/printers/N 1284 compliant parallel port device special files
310 appears in both namespaces.
311
314 kernel/drv/ecpp
315 32-bit ELF kernel module
317 kernel/drv/sparcv9/ecpp
320 64-bit SPARC ELF kernel module
322 kernel/drv/amd64/ecpp
325 64-bit x86 ELF kernel module
327 kernel/drv/ecpp.conf
330 driver configuration file
332 kernel/drv/sparcv9/ecpp.conf
335 driver configuration file for 64-bit SPARC
337 kernel/drv/amd64/ecpp.conf
340 driver configuration file for 64-bit x86
342
345 EBADF The device is opened for write-only access and a read is
346 attempted, or the device is opened for read-only access and a
347 write is attempted.
348 EBUSY 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 EINVAL A ECPPIOC_SETPARMS ioctl() is attempted with an out-of-range
356 value in the ecpp_transfer_parms structure. A ECPPIOC_SETREGS
357 ioctl() is attempted with an invalid value in the ecpp_regs
358 structure. An ioctl() is attempted with an invalid value in
359 the command argument.An invalid command argument is received
360 during modload(1M) or modunload(1M).
361 EIO The driver encountered a bus error when attempting an access.
364 A read or write did not complete properly, due to a periph‐
365 eral error or a transfer timeout.
366 ENXIO The driver has received an open request for a unit for which
369 the attach failed. The driver has received a write request
370 for a unit which has an active peripheral error.
371
374 See attributes(5) for descriptions of the following attributes:
375 ┌─────────────────────────────┬─────────────────────────────┐
380 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
381 ├─────────────────────────────┼─────────────────────────────┤
382 │Architecture │PCI-based systems │
383 ├─────────────────────────────┼─────────────────────────────┤
384 │ │ISA-based systems (x86) │
385 ├─────────────────────────────┼─────────────────────────────┤
386 │Availability │SUNWpd (Sparc) │
387 ├─────────────────────────────┼─────────────────────────────┤
388 │ │SUNWpsdcr (x86) │
389 ├─────────────────────────────┼─────────────────────────────┤
390 │Interface stability │Evolving │
391 └─────────────────────────────┴─────────────────────────────┘
392
394 modload(1M), modunload(1M), update_drv(1M)ioctl(2), open(2), read(2),
395 write(2), attributes(5), bpp(7D), usbprn(7D), prnio(7I), streamio(7I)
396 IEEE Std 1284-1994
399 http://www.sun.com/io
402
404 Parallel port controller not supported
405 Driver does not support parallel port controller on the given host.
407 Attach failed.
408SunOS 5.11 9 Oct 2004 ecpp(7D)