'\" t
.\"     Title: ieee1284_control
.\"    Author: Tim Waugh <twaugh@redhat.com>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/07/2024
.\"    Manual: Functions
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "IEEE1284_CONTROL" "3" "04/07/2024" "[FIXME: source]" "Functions"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ieee1284_read_control, ieee1284_write_control, ieee1284_frob_control, ieee1284_do_nack_handshake \- manipulate control lines
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <ieee1284\&.h>
.fi
.ft
.HP \w'int\ ieee1284_read_control('u
.BI "int ieee1284_read_control(struct\ parport\ *" "port" ");"
.HP \w'void\ ieee1284_write_control('u
.BI "void ieee1284_write_control(struct\ parport\ *" "port" ", unsigned\ char\ " "ct" ");"
.HP \w'void\ ieee1284_frob_control('u
.BI "void ieee1284_frob_control(struct\ parport\ *" "port" ", unsigned\ char\ " "mask" ", unsigned\ char\ " "val" ");"
.HP \w'int\ ieee1284_do_nack_handshake('u
.BI "int ieee1284_do_nack_handshake(struct\ parport\ *" "port" ", unsigned\ char\ " "ct_before" ", unsigned\ char\ " "ct_after" ", struct\ timeval\ *" "timeout" ");"
.SH "DESCRIPTION"
.PP
There are four control lines, three of which are usually inverted on PC\-style ports\&. Where they differ, libieee1284 operates on the IEEE 1284 values, not the PC\-style inverted values\&. The control lines are represented by the following enumeration:
.sp
.if n \{\
.RS 4
.\}
.nf
enum ieee1284_control_bits
{
  C1284_NSTROBE   = 0x01,
  C1284_NAUTOFD   = 0x02,
  C1284_NINIT     = 0x04,
  C1284_NSELECTIN = 0x08,
  /* To convert those values into PC\-style register values, use this: */
  C1284_INVERTED = (C1284_NSTROBE|
                    C1284_NAUTOFD|
                    C1284_NSELECTIN),
};
.fi
.if n \{\
.RE
.\}
.PP
These functions all act on the parallel port associated with
\fIport\fR, which must be claimed\&.
.PP
The current values on the control lines are available by calling
\fBieee1284_read_control\fR, and may be set by calling
\fBieee1284_write_control\fR\&.
.PP
To adjust the values on a set of control lines, use
\fBieee1284_frob_control\fR\&. The effect of this can be expressed by:
ctr = ((ctr & ~mask) ^ val); that is, the bits in
\fImask\fR
are unset, and then those in
\fIval\fR
are inverted\&.
.PP
The special function
\fBieee1284_do_nack_handshake\fR
is for responding very quickly in a protocol where the peripheral sets nAck and the host must respond by setting a control line\&. Its operation, which relies on the host machine knowing which interrupt nAck generates, is as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Set the control lines as indicated in
\fIct_before\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Wait for nAck interrupt\&. If
\fItimeout\fR
elapses, return
\fBE1284_TIMEDOUT\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Set the control lines as indicated in
\fIct_after\fR\&.
.RE
.PP
On Linux using the ppdev driver, this is performed by the device driver in the kernel, and so is faster than normally possible in a user\-space library\&.
.SH "RETURN VALUE"
.PP
The return value of
\fBieee1284_read_control\fR, if non\-negative, is a number representing the value on the control lines\&.
.PP
Possible error codes for
\fBieee1284_read_control\fR:
.PP
\fBE1284_NOTAVAIL\fR
.RS 4
The control lines of this port are not accessible by the application\&.
.RE
.PP
\fBE1284_INVALIDPORT\fR
.RS 4
The
\fIport\fR
parameter is invalid (for instance, perhaps it is not claimed)\&.
.RE
.PP
Possible error codes for
\fBieee1284_do_nack_handshake\fR:
.PP
\fBE1284_OK\fR
.RS 4
The handshake was successful\&.
.RE
.PP
\fBE1284_NOTAVAIL\fR
.RS 4
This operation is not available on this port type or system\&. This could be because port interrupts are not available, or because the underlying device driver does not support the operation\&.
.RE
.PP
\fBE1284_INVALIDPORT\fR
.RS 4
The
\fIport\fR
parameter is invalid (for instance, perhaps it is not claimed)\&.
.RE
.SH "AUTHOR"
.PP
\fBTim Waugh\fR <\&twaugh@redhat.com\&>
.RS 4
Author.
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2001-2003 Tim Waugh
.br