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