Blame doc/interface.xml

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