<?xml version='1.0' ?> <!-- -*- xml -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY libieee1284 "libieee1284">
<!ENTITY e1284ok "<errorcode>E1284_OK</errorcode>">
<!ENTITY e1284nomem "<errorcode>E1284_NOMEM</errorcode>">
<!ENTITY e1284notavail "<errorcode>E1284_NOTAVAIL</errorcode>">
<!ENTITY e1284notimpl "<errorcode>E1284_NOTIMPL</errorcode>">
<!ENTITY e1284init "<errorcode>E1284_INIT</errorcode>">
<!ENTITY e1284negfailed "<errorcode>E1284_NEGFAILED</errorcode>">
<!ENTITY e1284rejected "<errorcode>E1284_REJECTED</errorcode>">
<!ENTITY e1284timedout "<errorcode>E1284_TIMEDOUT</errorcode>">
<!ENTITY e1284sys "<errorcode>E1284_SYS</errorcode>">
<!ENTITY e1284noid "<errorcode>E1284_NOID</errorcode>">
<!ENTITY e1284invalidport "<errorcode>E1284_INVALIDPORT</errorcode>">
]>
<book id="index">
<bookinfo>
<title>Public interface of &libieee1284;</title>
<subtitle>API 3.2</subtitle>
<author>
<firstname>Tim</firstname>
<surname>Waugh</surname>
<affiliation>
<address><email>twaugh@redhat.com</email></address>
</affiliation>
</author>
<copyright>
<year>2001-2003</year>
<holder>Tim Waugh</holder>
</copyright>
</bookinfo>
<preface>
<title>Introduction</title>
<refentry>
<refmeta>
<refentrytitle>&libieee1284;</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>&libieee1284;</refname>
<refpurpose>IEEE1284 communications library</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
#include <ieee1284.h>
cc files... -lieee1284</synopsis>
</refsynopsisdiv>
<refsect1><title>Overview</title>
<para>The &libieee1284; library is a library for accessing
parallel port devices.</para>
<!-- Commented out for stable release.
It is currently under development, and this is CVS ID
<literal>$Id: interface.xml,v 1.19 2003/05/30 14:39:22 twaugh Exp $</literal>.
-->
<para>The model presented to the user is fairly abstract: a
list of parallel ports with arbitrary names, with functions
to access them in various ways ranging from bit operations
to block data transfer in one of the IEEE 1284 sanctioned
protocols.</para>
<para>Although the library resides in user space the speed
penalty may not be as bad as you initially think, since the
operating system may well provide assistance with block data
transfer operations; in fact, the operating system may even
use hardware assistance to get the job done. So, using
&libieee1284;, ECP transfers using DMA are possible.</para>
<para>The normal sequence of events will be that the application
<orderedlist>
<listitem>
<para>calls <function>ieee1284_find_ports</function> to
get a list of available ports</para>
</listitem>
<listitem>
<para>then <function>ieee1284_get_deviceid</function> to
look for a device on each port that it is interested
in</para>
</listitem>
<listitem>
<para>and then <function>ieee1284_open</function> to
open each port it finds a device it can control
on.</para>
</listitem>
<listitem>
<para>The list of ports returned from
<function>ieee1284_find_ports</function> can now be
disposed of using
<function>ieee1284_free_ports</function>.</para>
</listitem>
<listitem>
<para>Then when it wants to control the device, it will
call <function>ieee1284_claim</function> to prevent
other drivers from using the port</para>
</listitem>
<listitem>
<para>then perhaps do some data transfers</para>
</listitem>
<listitem>
<para>and then <function>ieee1284_release</function>
when it is finished that that particular command.
This claim-control-release sequence will be repeated
each time it wants to tell the device to do
something.</para>
</listitem>
<listitem>
<para>Finally when the application is finished with the
device it will call
<function>ieee1284_close</function>.</para>
</listitem>
</orderedlist></para>
<para>Usually a port needs to be claimed before it can be
used. This is to prevent multiple drivers from trampling on
each other if they both want to use the same port. The
exception to this rule is the collection of IEEE 1284 Device
IDs, which has an implicit open-claim-release-close
sequence. The reason for this is that it may be possible to
collect a Device ID from the operating system, without
bothering the device with it.</para>
</refsect1>
<refsect1>
<title>Configuration</title>
<para>When <function>ieee1284_find_ports</function> is first
called, the library will look for a configuration file,
<filename>/etc/ieee1284.conf</filename>.</para>
<para>Comments begin with a '#' character and extend to the
end of the line. Everything else is freely-formatted
tokens. A non-quoted (or double-quoted) backslash character
'\' preserves the literal value of the next character, and
single and double quotes may be used for preserving
white-space. Braces and equals signs are recognised as
tokens, unless quoted or escaped.</para>
<para>The only configuration instruction that is currently
recognised is <quote>disallow method ppdev</quote>, for
preventing the use of the Linux ppdev driver.</para>
</refsect1>
<refsect1>
<title>Environment</title>
<para>You can enable debugging output from the library by
setting the environment variable
<envar>LIBIEEE1284_DEBUG</envar> to any value.</para>
</refsect1>
<refsect1>
<title>Files</title>
<variablelist>
<varlistentry>
<term><filename>/etc/ieee1284.conf</filename></term>
<listitem>
<para>Configuration file.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para><xref linkend="parport"/>,
<xref linkend="parport-list"/>,
<xref linkend="find-ports"/>,
<xref linkend="free-ports"/>,
<xref linkend="get-deviceid"/>,
<xref linkend="open"/>,
<xref linkend="close"/>,
<xref linkend="claim"/>,
<xref linkend="release"/>,
<xref linkend="data-pin-access"/>,
<xref linkend="status-pin-access"/>,
<xref linkend="control-line-access"/>,
<xref linkend="negotiation"/>,
<xref linkend="fwd-rev"/>,
<xref linkend="transfer"/>,
<xref linkend="irq"/>,
<xref linkend="timeout"/></para>
</refsect1>
</refentry>
</preface>
<reference>
<title>Structures</title>
<refentry id="parport">
<refmeta>
<refentrytitle>parport</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>parport</refname>
<refpurpose>representation of a parallel port</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis><![CDATA[#include <ieee1284.h>]]></synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>A <structname>parport</structname> structure represents
a parallel port.</para>
</refsect1>
<refsect1>
<title>Structure members</title>
<para>The structure has the following members:</para>
<programlisting><![CDATA[struct parport {
/* An artibrary name for the port. */
const char *name;
/* The base address of the port, if that has any meaning, or zero. */
unsigned long base_addr;
/* The ECR address of the port, if that has any meaning, or zero. */
unsigned long hibase_addr;
/* The filename associated with this port,
* if that has any meaning, or NULL. */
const char *filename;
};]]></programlisting>
</refsect1>
</refentry>
<refentry id="parport-list">
<refmeta>
<refentrytitle>parport_list</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>parport_list</refname>
<refpurpose>a collection of parallel ports</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis><![CDATA[#include <ieee1284.h>]]></synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>A <structname>parport_list</structname> structure is
just a vector of <structname>parport</structname>
structures.</para>
</refsect1>
<refsect1>
<title>Structure members</title>
<para>The structure has the following members:</para>
<programlisting><![CDATA[struct parport_list {
/* Number of elements in the vector. */
int portc;
/* The ports. */
struct parport **portv;
};]]></programlisting>
</refsect1>
</refentry>
</reference>
<reference>
<title>Functions</title>
<refentry id="find-ports">
<refmeta>
<refentrytitle>ieee1284_find_ports</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_find_ports</refname>
<refpurpose>find ports on the system</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int
<function>ieee1284_find_ports</function></funcdef>
<paramdef>struct parport_list
*<parameter>list</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This function should be called before the other
&libieee1284; functions. This gives the library a chance to
look around and see what's available, and gives the program a
chance to choose a port to use.</para>
<para>The <parameter>list</parameter> is a pointer to a
<structname>parport_list</structname> structure that will be
filled in on success.</para>
<para>There are no <parameter>flags</parameter> defined; use
zero for this parameter.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<variablelist>
<varlistentry>
<term>&e1284ok;</term>
<listitem>
<para>Success. <parameter>list</parameter> is filled in
and must be destroyed using
<citerefentry>
<refentrytitle>ieee1284_free_ports</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284nomem;</term>
<listitem>
<para>There is not enough memory available.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notimpl;</term>
<listitem>
<para>One or more of the supplied flags is not
supported in this implementation.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="free-ports">
<refmeta>
<refentrytitle>ieee1284_free_ports</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_free_ports</refname>
<refpurpose>safely deallocate a port list</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>ieee1284_free_ports</function></funcdef>
<paramdef>struct parport_list
*<parameter>list</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>When the port list will no longer be used, the program
should call <function>ieee1284_free_ports</function> giving
it a pointer to the <structname>parport_list</structname>
structure that holds the list of ports returned by
<citerefentry>
<refentrytitle>ieee1284_find_ports</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>. The ports are reference counted with the
<function>ieee1284_open</function> and
<function>ieee1284_close</function> functions, and so the
port list may be freed even if it contains pointers to ports
that are still open.</para>
</refsect1>
</refentry>
<refentry id="get-deviceid">
<refmeta>
<refentrytitle>ieee1284_get_deviceid</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_get_deviceid</refname>
<refpurpose>retrieve an IEEE 1284 Device ID</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_get_deviceid</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>daisy</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This function is for retrieving the IEEE 1284 Device ID
of the specified device. The device is specified by the
<parameter>port</parameter> to which it is attached, and
optionally an address (<parameter>daisy</parameter>) on the
daisy chain of devices on that port.</para>
<para><parameter>daisy</parameter> should be −1 to
indicate that the device is not participating in a IEEE
1284.3 daisy chain, meaning it is the last (or only) device
on the port, or should be a number from 0 to 3 inclusive to
indicate that it has the specified daisy chain address (0 is
next to the port).</para>
<para>The <parameter>flags</parameter> parameter should be a
bitwise union of any flags that the program wants to use.
Available flags are:</para>
<variablelist>
<varlistentry>
<term><constant>F1284_FRESH</constant></term>
<listitem>
<para>Guarantee a fresh Device ID. A cached or
OS-provided ID will not be used.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The provided <parameter>buffer</parameter> must be at
least <parameter>len</parameter> bytes long, and will contain
the Device ID including the initial two-byte length field and
a terminating zero byte on successful return, or as much of
the above as will fit into the buffer.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>A return value less than zero indicates an error as
below. Otherwise, the return value is the number of bytes of
<parameter>buffer</parameter> that have been filled. A
return value equal to the length of the buffer indicates that
the Device ID may be longer than the buffer will
allow.</para>
<variablelist>
<varlistentry>
<term>&e1284noid;</term>
<listitem>
<para>The device did not provide an IEEE 1284 Device ID
when interrogated (perhaps by the operating system if
<constant>F1284_FRESH</constant> was not
specified).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notimpl;</term>
<listitem>
<para>One or more of the supplied flags is not supported
in this implementation, or if no flags were supplied
then this function is not implemented for this type of
port or this type of system. This can also be returned
if a daisy chain address is specified but daisy chain
Device IDs are not yet supported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para><constant>F1284_FRESH</constant> was specified
and the library is unable to access the port to
interrogate the device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284nomem;</term>
<listitem>
<para>There is not enough memory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284init;</term>
<listitem>
<para>There was a problem initializing the port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>Unless the <constant>F1284_FRESH</constant> flag is
given, the library will try to find the device's ID as
unobtrusively as possible. First it will ask the operating
system if it knows it, and then it will try actually asking
the device for it. Because of this, the Device ID may be
partially computed (the length field, for example) or even
partially missing if the operating system has only remembered
some parts of the ID. To guarantee that you are getting the
bytes that the device sent, use
<constant>F1284_FRESH</constant>. Be aware that the
operating system may allow any user to inspect the Device IDs
that it provides, whereas device access is normally more
restricted.</para>
<para>The initial two-byte length field is a big-endian 16 bit
unsigned integer provided by the device and may not be
accurate. In particular, it is meant to indicate the length
of the entire string including the length field itself;
however, some manufacturers exclude the length field or just
set the length field to some arbitrary number greater than
the ID length.</para>
</refsect1>
</refentry>
<refentry id="open">
<refmeta>
<refentrytitle>ieee1284_open</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_open</refname>
<refpurpose>open a port</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_open</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int *<parameter>capabilities</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>In order to begin using a port it must be opened. Any
initial set-up of the port is done at this stage. When an
open port is no longer needed it should be closed with
<citerefentry>
<refentrytitle>ieee1284_close</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>.</para>
<para>The possible <parameter>flags</parameter> are:</para>
<variablelist>
<varlistentry>
<term><constant>F1284_EXCL</constant></term>
<listitem>
<para>This device cannot share the port with any other
device. If this is the case it must be declared at
this stage, so that other drivers trying to access the
port know not to bother; otherwise they will wait until
this driver releases the port, i.e. never.</para>
<remark>The iopl/dev-port access methods don't support
this yet, but the ppdev ones do.</remark>
</listitem>
</varlistentry>
</variablelist>
<para>If <parameter>capabilities</parameter> is not
<constant>NULL</constant> it must point to storage for an
<type>int</type>, which will be treated as a set of flags,
one per bit, which the library sets or clears as
appropriate. If a capability is present it will be used
when asked for. They are:</para>
<variablelist>
<varlistentry>
<term><constant>CAP1284_RAW</constant></term>
<listitem>
<para>Pin-level access is available. If this capability
is present then the following functions are effective:
<function>ieee1284_write_data</function>,
<function>ieee1284_read_status</function>,
<function>ieee1284_wait_status</function>,
<function>ieee1284_write_control</function>,
<function>ieee1284_read_control</function>,
<function>ieee1284_frob_control</function>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_NIBBLE</constant></term>
<listitem>
<para>There is an implementation of nibble mode for this
port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_BYTE</constant></term>
<listitem>
<para>There is an implementation of byte mode for this
port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_COMPAT</constant></term>
<listitem>
<para>There is an implementation of compatibility mode
for this port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_ECP</constant></term>
<listitem>
<para>There is a hardware implementation of ECP mode for
this port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_ECPRLE</constant></term>
<listitem>
<para>There is an RLE-aware implementation of ECP mode
for this port (the <constant>F1284_RLE</constant> flag
is recognised by the ECP transfer functions).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_ECPSWE</constant></term>
<listitem>
<para>There is a software implementation of ECP mode for
this port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_BECP</constant></term>
<listitem>
<para>There is an implementation of bounded ECP mode for
this port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_EPP</constant></term>
<listitem>
<para>There is a hardware implementation of EPP mode for
this port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_EPPSWE</constant></term>
<listitem>
<para>There is a software implementation of EPP mode for
this port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_IRQ</constant></term>
<listitem>
<para>An interrupt line is configured for this
port and interrupt notifications can be received using
<citerefentry>
<refentrytitle>ieee1284_get_irq_fd</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>CAP1284_DMA</constant></term>
<listitem>
<para>A DMA channel is configured for this port.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Return value</title>
<variablelist>
<varlistentry>
<term>&e1284ok;</term>
<listitem>
<para>The port is now opened.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284init;</term>
<listitem>
<para>There was a problem during port initialization.
This could be because another driver has opened the
port exclusively, or some other reason.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284nomem;</term>
<listitem>
<para>There is not enough memory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para>One or more of the supplied flags is not supported
by this type of port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, the <parameter>port</parameter>
may already be open).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284sys;</term>
<listitem>
<para>There was a problem at the operating system
level. The global variable <varname>errno</varname>
has been set appropriately.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See also</title>
<para><citerefentry>
<refentrytitle>ieee1284_close</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry></para>
</refsect1>
</refentry>
<refentry id="close">
<refmeta>
<refentrytitle>ieee1284_close</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_close</refname>
<refpurpose>close an open port</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_close</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>To close an open port and free any resources associated
with it, call <function>ieee1284_close</function>.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<variablelist>
<varlistentry>
<term>&e1284ok;</term>
<listitem>
<para>The port is now closed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (perhaps it is not open, for instance).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284sys;</term>
<listitem>
<para>There was a problem at the operating system
level. The global variable <varname>errno</varname>
has been set appropriately.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See also</title>
<para><citerefentry>
<refentrytitle>ieee1284_open</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry></para>
</refsect1>
</refentry>
<refentry id="ref">
<refmeta>
<refentrytitle>ieee1284_ref</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_ref</refname>
<refname>ieee1284_unref</refname>
<refpurpose>modify a port's reference count</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_ref</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>ieee1284_unref</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>If you want to free the port list from
<function>ieee1284_find_ports</function> but open one of the
ports later on, you will need to prevent it from being
destroyed in <function>ieee1284_free_ports</function>. Each
port has a reference count, and you can use
<function>ieee1284_ref</function> to increment it and
<function>ieee1284_unref</function> to decrement it.</para>
<para>If you use <function>ieee1284_ref</function> at any
stage, you must later call
<function>ieee1284_unref</function> to relinquish the extra
reference. If you do not do this, the resources associated
with the port will not be cleaned up.</para>
<para>If you have not previously used
<function>ieee1284_ref</function> on a port, you must not
use <function>ieee1284_unref</function> on it.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>These functions return the number of references held
after the increment or decrement.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para><citerefentry>
<refentrytitle>ieee1284_open</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry></para>
</refsect1>
</refentry>
<refentry id="claim">
<refmeta>
<refentrytitle>ieee1284_claim</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_claim</refname>
<refpurpose>claim access to the port</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_claim</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>With the exception of <citerefentry>
<refentrytitle>ieee1284_get_deviceid</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>, <function>ieee1284_claim</function> must be
called on an open port before any other &libieee1284;
function for accessing a device on it.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<variablelist>
<varlistentry>
<term>&e1284ok;</term>
<listitem>
<para>Success. Note that, unless the
<constant>F1284_EXCL</constant> flag was specified to
start with, the port should be released within a
<quote>reasonable</quote> amount of time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284nomem;</term>
<listitem>
<para>There is not enough memory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, it might not have been opened
yet).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284sys;</term>
<listitem>
<para>There was a problem at the operating system
level. The global variable <varname>errno</varname>
has been set appropriately.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See also</title>
<para><citerefentry>
<refentrytitle>ieee1284_release</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry></para>
</refsect1>
</refentry>
<refentry id="release">
<refmeta>
<refentrytitle>ieee1284_release</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_release</refname>
<refpurpose>release a port</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>ieee1284_release</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This function undoes the effect of
<citerefentry>
<refentrytitle>ieee1284_claim</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry> by releasing the port for use by other
drivers. It is good practice to release the port whenever
convenient. If it is never convenient to do so, the
<constant>F1284_EXCL</constant> flag should be specified at
initialization.</para>
</refsect1>
</refentry>
<refentry id="data-pin-access">
<refmeta>
<refentrytitle>ieee1284_data</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_read_data</refname>
<refname>ieee1284_write_data</refname>
<refname>ieee1284_data_dir</refname>
<refname>ieee1284_wait_data</refname>
<refpurpose>control the data lines</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_read_data</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ieee1284_write_data</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>unsigned char <parameter>dt</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>ieee1284_data_dir</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>reverse</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>ieee1284_wait_data</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>unsigned char <parameter>mask</parameter></paramdef>
<paramdef>unsigned char <parameter>val</parameter></paramdef>
<paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>These functions manipulate the data lines of the
parallel port associated with <parameter>port</parameter>
(which must have been claimed using <citerefentry>
<refentrytitle>ieee1284_claim</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>). The lines are represented by an 8-bit
number (one line per bit) and a direction. The data lines
are driven as a group; they may be all host-driven
(<firstterm>forward</firstterm> direction) or not
(<firstterm>reverse</firstterm> direction). When the
peripheral is driving them the host must not.</para>
<para>For <function>ieee1284_data_dir</function> the
<parameter>reverse</parameter> parameter should be zero to
turn the data line drivers on and non-zero to turn them off.
Some port types may be unable to switch off the data line
drivers.</para>
<para>Setting the data lines may have side effects on some
port types (for example, some Amiga ports pulse
nStrobe).</para>
<para><function>ieee1284_wait_data</function> waits, up until
the <parameter>timeout</parameter>, for the data bits
specified in <parameter>mask</parameter> to have the
corresponding values in <parameter>val</parameter>.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para><function>ieee1284_read_data</function> returns the
8-bit number representing the data lines unless it is not
possible to return such a value with this port type, in which
case it returns an error code. Possible error codes:</para>
<variablelist>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para>Bi-directional data lines are not available on
this system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (perhaps it has not been claimed, for
instance).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284sys;</term>
<listitem>
<para>There was an error at the operating system level,
and <varname>errno</varname> has been set
accordingly.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284timedout;</term>
<listitem>
<para>The <parameter>timeout</parameter> has
elapsed.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Whereas <function>ieee1284_read_data</function> may
return &e1284notavail; on its first invocation on the port,
if it does not do so then it cannot until
<function>ieee1284_close</function> is called for that
port.</para>
</refsect1>
</refentry>
<refentry id="status-pin-access">
<refmeta>
<refentrytitle>ieee1284_status</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_read_status</refname>
<refname>ieee1284_wait_status</refname>
<refpurpose>analyse status lines</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_read_status</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>ieee1284_wait_status</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>unsigned char <parameter>mask</parameter></paramdef>
<paramdef>unsigned char <parameter>val</parameter></paramdef>
<paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>There are five status lines, one of which is usually
inverted on PC-style ports. Where they differ, &libieee1284;
operates on the IEEE 1284 values, not the PC-style inverted
values. The status lines are represented by the following
enumeration:</para>
<programlisting><![CDATA[enum ieee1284_status_bits
{
S1284_NFAULT = 0x08,
S1284_SELECT = 0x10,
S1284_PERROR = 0x20,
S1284_NACK = 0x40,
S1284_BUSY = 0x80,
/* To convert those values into PC-style register values, use this: */
S1284_INVERTED = S1284_BUSY,
};]]></programlisting>
<para>These functions all act on the parallel port associated
with <parameter>port</parameter>, which must be
claimed.</para>
<para>The purpose of <function>ieee1284_wait_status</function>
is to wait until particular status lines have specified
values. Its <parameter>timeout</parameter> parameter may be
modified on return.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>For <function>ieee1284_read_status</function>, the
return value is a non-negative integer with bits set as
appropriate representing the status lines. A negative result
indicates an error.</para>
<para>For <function>ieee1284_wait_status</function>, the
return value is &e1284ok; if the status
lines now reflect the desired values (i.e. status &
<parameter>mask</parameter> is <parameter>val</parameter>),
or a negative result indicating an error.</para>
<para>Possible error codes:</para>
<variablelist>
<varlistentry>
<term>&e1284notimpl;</term>
<listitem>
<para>The <parameter>port</parameter> lacks the
required capability. This could be due to a limitation
of this version of &libieee1284;, or a hardware
limitation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para>Access to the status lines is not available on this
port type.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284timedout;</term>
<listitem>
<para>The <parameter>timeout</parameter> has
elapsed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, perhaps the
<parameter>port</parameter> is not claimed).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>The nAck pin is often able to trigger interrupts on the
host machine. With operating system help these interrupts
may be visible to the application via the file descriptor
returned by <function>ieee1284_get_irq_fd</function>.</para>
<para>Under Linux, the conditions are that the parallel port
driver knows which interrupt line to use and is using it, and
that the relevant <filename>/dev/parport</filename> device
node is accessible and backed by a device driver.</para>
</refsect1>
</refentry>
<refentry id="control-line-access">
<refmeta>
<refentrytitle>ieee1284_control</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_read_control</refname>
<refname>ieee1284_write_control</refname>
<refname>ieee1284_frob_control</refname>
<refname>ieee1284_do_nack_handshake</refname>
<refpurpose>manipulate control lines</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_read_control</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ieee1284_write_control</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>unsigned char <parameter>ct</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ieee1284_frob_control</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>unsigned char <parameter>mask</parameter></paramdef>
<paramdef>unsigned char <parameter>val</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int
<function>ieee1284_do_nack_handshake</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>unsigned char <parameter>ct_before</parameter></paramdef>
<paramdef>unsigned char <parameter>ct_after</parameter></paramdef>
<paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>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:</para>
<programlisting><![CDATA[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),
};]]></programlisting>
<para>These functions all act on the parallel port associated
with <parameter>port</parameter>, which must be
claimed.</para>
<para>The current values on the control lines are available by
calling <function>ieee1284_read_control</function>, and may
be set by calling
<function>ieee1284_write_control</function>.</para>
<para>To adjust the values on a set of control lines, use
<function>ieee1284_frob_control</function>. The effect of
this can be expressed by: <literal>ctr = ((ctr & ~mask) ^
val)</literal>; that is, the bits in
<parameter>mask</parameter> are unset, and then those in
<parameter>val</parameter> are inverted.</para>
<para>The special function
<function>ieee1284_do_nack_handshake</function> 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:</para>
<procedure>
<step>
<para>Set the control lines as indicated in
<parameter>ct_before</parameter>.</para>
</step>
<step>
<para>Wait for nAck interrupt. If
<parameter>timeout</parameter> elapses, return
&e1284timedout;.</para>
</step>
<step>
<para>Set the control lines as indicated in
<parameter>ct_after</parameter>.</para>
</step>
</procedure>
<para>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.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>The return value of
<function>ieee1284_read_control</function>, if non-negative,
is a number representing the value on the control lines.</para>
<para>Possible error codes for
<function>ieee1284_read_control</function>:</para>
<variablelist>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para>The control lines of this port are not accessible
by the application.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, perhaps it is not
claimed).</para>
</listitem>
</varlistentry>
</variablelist>
<para>Possible error codes for
<function>ieee1284_do_nack_handshake</function>:</para>
<variablelist>
<varlistentry>
<term>&e1284ok;</term>
<listitem>
<para>The handshake was successful.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, perhaps it is not
claimed).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="negotiation">
<refmeta>
<refentrytitle>ieee1284_negotiation</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_negotiate</refname>
<refname>ieee1284_terminate</refname>
<refpurpose>IEEE 1284 negotiation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_negotiate</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>mode</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ieee1284_terminate</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>These functions are for negotiating to and terminating
from IEEE 1284 data transfer modes. The default mode is
called compatibility mode, or in other words normal printer
protocol. It is a host-to-peripheral mode only. There are
special modes that allow peripheral-to-host transfer as well,
which may be negotiated to using
<function>ieee1284_negotiate</function>. IEEE 1284
negotiation is a process by which the host requests a
transfer mode and the peripheral accepts or rejects it. An
IEEE 1284-compliant device will require a successful
negotiation to a particular mode before it is used for data
transfer (but simpler devices may not if they only speak one
transfer mode).</para>
<para>To terminate the special mode and go back to
compatilibity mode use
<function>ieee1284_terminate</function>.</para>
<para>These functions act on the parallel port associated with
<parameter>port</parameter>, which must be claimed.</para>
<para>With a device strictly complying to IEEE 1284 you will
need to call <function>ieee1284_terminate</function> in
between any two calls to
<function>ieee1284_negotiate</function> for modes other than
<constant>M1284_COMPAT</constant>.</para>
</refsect1>
<refsect1>
<title>Available modes</title>
<refsect2>
<title>Uni-directional modes</title>
<itemizedlist>
<listitem>
<para><constant>M1284_COMPAT</constant>: Compatibility
mode. Normal printer protocol. This is not a
negotiated mode, but is the default mode in absence of
negotiation. <userinput>ieee1284_negotiate(port,
M1284_COMPAT)</userinput> is equivalent to
<userinput>ieee1284_terminate(port)</userinput>. This
host-to-peripheral mode is used for sending data to
printers, and is historically the mode that has been
used for that before IEEE 1284.</para>
</listitem>
<listitem>
<para><constant>M1284_NIBBLE</constant>: Nibble mode.
This peripheral-to-host mode uses the status lines to
read data from the peripheral four bits at a time.</para>
</listitem>
<listitem>
<para><constant>M1284_BYTE</constant>: Byte mode. This
peripheral-to-host mode uses the data lines in reverse
mode to read data from the peripheral a byte at a
time.</para>
</listitem>
</itemizedlist>
</refsect2>
<refsect2>
<title>Bi-directional modes</title>
<itemizedlist>
<listitem>
<para><constant>M1284_ECP</constant>: ECP mode. On
entry to ECP mode it is a host-to-peripheral
(i.e. forward) mode, but it may be set to reverse mode
using <citerefentry>
<refentrytitle>ieee1284_ecp_fwd_to_rev</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>. It is common
for PC hardware to provide assistance with this mode by
the use of a FIFO which the host (or, in reverse mode,
the peripheral) may fill, so that the hardware can do
the handshaking itself.</para>
</listitem>
<listitem>
<para><constant>M1284_EPP</constant>: EPP mode. In this
bi-directional mode the direction of data transfer is
signalled at each byte.</para>
</listitem>
</itemizedlist>
</refsect2>
<refsect2>
<title>Mode variations</title>
<itemizedlist>
<listitem>
<para><constant>M1284_FLAG_DEVICEID</constant>: Device
ID retrieval. This flag may be combined with a nibble,
byte, or ECP mode to notify the device that it should
send its IEEE 1284 Device ID when asked for
data.</para>
</listitem>
<listitem>
<para><constant>M1284_BECP</constant>: Bounded ECP is a
modification to ECP that makes it more robust at the
point that the direction is changed. (Unfortunately it
is not yet implemented in the Linux kernel
driver.)</para>
</listitem>
<listitem>
<para><constant>M1284_ECPRLE</constant>: ECP with run
length encoding. In this mode, consecutive data bytes
of the same value may be transferred in only a few
cycles.</para>
</listitem>
</itemizedlist>
</refsect2>
</refsect1>
<refsect1>
<title>Return value</title>
<variablelist>
<varlistentry>
<term>&e1284ok;</term>
<listitem>
<para>The negotiation was successful.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para>Negotiation is not available with this port
type.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284rejected;</term>
<listitem>
<para>Negotiation was rejected by the peripheral.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284negfailed;</term>
<listitem>
<para>Negotiation failed for some reason. Perhaps the
device is not IEEE 1284 compliant.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284sys;</term>
<listitem>
<para>A system error occured during negotiation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, perhaps the
<parameter>port</parameter> is not claimed).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="fwd-rev">
<refmeta>
<refentrytitle>ieee1284_ecp_fwd_to_rev</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_ecp_fwd_to_rev</refname>
<refname>ieee1284_ecp_rev_to_fwd</refname>
<refpurpose>ECP direction switching</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ieee1284_ecp_fwd_to_rev</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>ieee1284_ecp_rev_to_fwd</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>These functions are used to switch directions when in
ECP mode. On negotiation to ECP mode the direction is
forward (in other words, host-to-peripheral). Use
<function>ieee1284_ecp_fwd_to_rev</function> to switch from
forward to reverse, and
<function>ieee1284_ecp_rev_to_fwd</function> to switch from
reverse to forward.</para>
<para>They act on the parallel port associated with
<parameter>port</parameter>, which must be claimed.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<variablelist>
<varlistentry>
<term>&e1284ok;</term>
<listitem>
<para>Direction switched successfully.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notimpl;</term>
<listitem>
<para>The <parameter>port</parameter> lacks the
required capability. This could be due to a limitation
of this version of &libieee1284;, or a hardware
limitation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, perhaps the
<parameter>port</parameter> is not claimed).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="transfer">
<refmeta>
<refentrytitle>ieee1284_transfer</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_nibble_read</refname>
<refname>ieee1284_compat_write</refname>
<refname>ieee1284_byte_read</refname>
<refname>ieee1284_epp_read_data</refname>
<refname>ieee1284_epp_write_data</refname>
<refname>ieee1284_epp_read_addr</refname>
<refname>ieee1284_epp_write_addr</refname>
<refname>ieee1284_ecp_read_data</refname>
<refname>ieee1284_ecp_write_data</refname>
<refname>ieee1284_ecp_read_addr</refname>
<refname>ieee1284_ecp_write_addr</refname>
<refpurpose>data transfer functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_nibble_read</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_compat_write</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>const char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t <function>ieee1284_byte_read</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_epp_read_data</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_epp_write_data</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>const char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_epp_read_addr</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_epp_write_addr</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>const char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_ecp_read_data</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_ecp_write_data</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>const char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_ecp_read_addr</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ssize_t
<function>ieee1284_ecp_write_addr</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>const char *<parameter>buffer</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This set of functions is for tranferring bytes in the
relevant transfer mode. For ECP and EPP modes two types of
transfer are possible: <firstterm>data</firstterm> and
<firstterm>address</firstterm> (usually referred to as
<firstterm>channel</firstterm> in ECP).</para>
<para>The supplied <parameter>port</parameter> must be a
claimed port.</para>
<para>The supplied <parameter>buffer</parameter> must be at
least <parameter>len</parameter> bytes long. When reading,
the transferred data is stored in the buffer; when writing
the data to be transferred is taken from the buffer.</para>
<para>For reads (peripheral to host): if no data is available
and <constant>F1284_NONBLOCK</constant> is not in effect,
the inactivity timer is started. If data becomes available
before the inactivity time-out elapses it is read; otherwise
the return value will be &e1284timedout;.</para>
<para>For writes (host to peripheral): if the peripheral is
not willing to accept data and
<constant>F1284_NONBLOCK</constant> is not in effect, the
inactivity timer is started. If the peripheral indicates
that it is willing to accept data before the inactivity
time-out elapses it is sent; otherwise the return value will
be &e1284timedout;</para>
<para>The <parameter>flags</parameter> may alter the behaviour
slightly:</para>
<variablelist>
<varlistentry>
<term><constant>F1284_NONBLOCK</constant></term>
<listitem>
<para>For reads (peripheral to host): if no data is
available, return immediately (with
&e1284timedout;).</para>
<para>For writes (host to peripheral): if the peripheral
is not willing to accept data, return immediately (with
&e1284timedout;).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>F1284_SWE</constant></term>
<listitem>
<para>Don't use hardware assistance for the transfer,
but instead set the parallel port pins according to the
wire protocol.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>F1284_RLE</constant> (for ECP only)</term>
<listitem>
<para>Use run length encoding. If the
peripheral is in ECP mode with RLE, calls to
<function>ieee1284_ecp_read_data</function>
<emphasis>must</emphasis> set this flag in order for
the RLE from the peripheral to be interpreted
correctly, and calls to
<function>ieee1284_ecp_write_data</function>
<emphasis>may</emphasis> set this flag in order to take
advantage of RLE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>F1284_FASTEPP</constant> (for EPP only)</term>
<listitem>
<para>Use multi-byte transfers. Several bytes at a time
are transferred using hardware assistance, if
supporting hardware is present. The price of this
increased speed is that the return value will be less
reliable when this flag is used.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For ECP mode, a given direction is in force at any
particular time, and it is up to the application to ensure
that it is only writing when in forward mode, and reading
when in reverse mode.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>The return value is the number of bytes successfully
transferred or, if negative, one of:</para>
<variablelist>
<varlistentry>
<term>&e1284notimpl;</term>
<listitem>
<para>This transfer mode and flags combination is not
yet implemented in &libieee1284;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284timedout;</term>
<listitem>
<para>Timed out waiting for peripheral to
handshake.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284nomem;</term>
<listitem>
<para>Not enough memory is available.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284sys;</term>
<listitem>
<para>There was a problem at the operating system
level. The global variable <varname>errno</varname>
has been set appropriately.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, perhaps the
<parameter>port</parameter> is not claimed).</para>
</listitem>
</varlistentry>
</variablelist>
<para>If any bytes are successfully transferred, that number
is returned. An error is returned only if no bytes are
transferred.</para>
<para>For host-to-peripheral transfers, all data is at the
peripheral by the time the call returns.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para><citerefentry>
<refentrytitle>ieee1284_ecp_fwd_to_rev</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry></para>
</refsect1>
</refentry>
<refentry id="irq">
<refmeta>
<refentrytitle>ieee1284_get_irq_fd</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_get_irq_fd</refname>
<refname>ieee1284_clear_irq</refname>
<refpurpose>interrupt notification</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>ieee1284_get_irq_fd</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>ieee1284_clear_irq</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter>,
unsigned int *<parameter>count</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>If the <parameter>port</parameter> has a configured
interrupt line and the port type supports interrupt
notification, it is possible to obtain a file descriptor that
may be used for
<citerefentry>
<refentrytitle>select</refentrytitle>
<manvolnum>2</manvolnum>
</citerefentry> or <citerefentry>
<refentrytitle>poll</refentrytitle>
<manvolnum>2</manvolnum>
</citerefentry>. Any event (readable, writable
or exception) means that an interrupt has been
triggered. No operations other than
<function>select</function> or <function>poll</function> may
be performed on the file descriptor.</para>
<para>The port must be open in order to call
<function>ieee1284_get_irq_fd</function>, and must be claimed
when using <function>select</function> or
<function>poll</function>.</para>
<para>The caller must not close the file descriptor, and may
not use it at all when the port is not claimed.</para>
<para>When an interrupt has been detected, the caller must
call <function>ieee1284_clear_irq</function> to clear the
interrupt condition, at which point the number of interrupts
raised can be obtained by supplying a
non-<constant>NULL</constant>
<parameter>count</parameter>.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>For <function>ieee1284_get_irq_fd</function>: If the
return value is negative then it is an error code listed
below. Otherwise it is a valid file descriptor.
<variablelist>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para>No such file descriptor is available.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, perhaps the
<parameter>port</parameter> is not open).</para>
</listitem>
</varlistentry>
</variablelist></para>
<para>For <function>ieee1284_clear_irq</function>:
<variablelist>
<varlistentry>
<term>&e1284ok;</term>
<listitem>
<para>The interrupt has been cleared. If
<parameter>count</parameter> was not
<constant>NULL</constant> the count of interrupts has
been atomically stored to
<parameter>count</parameter> and reset.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284notavail;</term>
<listitem>
<para>The <parameter>count</parameter> parameter was
not <constant>NULL</constant> but interrupt counting
is not supported on this type of port. The interrupt
has been cleared.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284sys;</term>
<listitem>
<para>There was a problem clearing the
interrupt.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&e1284invalidport;</term>
<listitem>
<para>The <parameter>port</parameter> parameter is
invalid (for instance, perhaps the
<parameter>port</parameter> is not claimed).</para>
</listitem>
</varlistentry>
</variablelist></para>
</refsect1>
</refentry>
<refentry id="timeout">
<refmeta>
<refentrytitle>ieee1284_set_timeout</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>ieee1284_set_timeout</refname>
<refpurpose>modify inactivity timeout</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ieee1284.h></funcsynopsisinfo>
<funcprototype>
<funcdef>struct timeval
*<function>ieee1284_set_timeout</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This function sets a new value for the inactivity
timeout (used for block transfer functions), and returns the
old value.</para>
<para>The <parameter>port</parameter> must be claimed.</para>
<para>The <parameter>timeout</parameter> parameter may be
<constant>NULL</constant>, in which case the old value is
left unchanged.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>This function returns a pointer to a <structname>struct
timeval</structname> representing the old value. This uses
the same storage as the <parameter>port</parameter>
structure, and so is not valid after closing the port.</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>Note that this is an inactivity time-out, not an
absolute time-out. During a data transfer, if the peripheral
is inactive for the length of time specified then the host
gives up.</para>
<para>It is also advisory; no guarantee is made that the
transfer will ever complete.</para>
</refsect1>
</refentry>
</reference>
</book>