2229 lines
69 KiB
XML
2229 lines
69 KiB
XML
<?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>
|