.\" Copyright (c) 2014 Jeff Epler
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
.\" USA.
.TH parport "3rtapi" "2006-10-12" "LinuxCNC Documentation" "RTAPI"
.SH NAME

rtapi_parport \- portable access to PC-style parallel ports

.SH SYNTAX
.HP
#include "rtapi_parport.h"
.HP
int \fBrtapi_parport_get\fR(const char *\fImodule_name\fR, rtapi_parport_t *\fIport\fR, unsigned short \fIbase\fR, unsigned short \fIbase_hi\fR, unsigned int \fImodes\fR)
.HP
void \fBrtapi_parport_release\fR(rtapi_parport_t *\fIport\fR)
.SH  ARGUMENTS
.IP \fImodule_name\fR
By convention, the name of the RTAPI module or HAL component using the parport.
.IP \fIport\fR
A pointer to a rtapi_parport_t structure
.IP \fIbase\fR
The base address of the port (if port >= 16) or the linux port number of the
port (if port < 16)
.IP \fIbase_hi\fR
The "high" address of the port (location of the ECP registers), 0 to use a
probed high address, or \-1 to disable the high address
.IP \fImodes\fR
Advise the driver of the desired port modes, from <linux/parport.h>.  If a
linux-detected port does not provide the requested modes, a warning is printed
with rtapi_print_msg.   This does not make the port request fail, because
unfortunately, many systems that have working EPP parports are not detected as
such by Linux.
.SH DESCRIPTION
\fBrtapi_parport_get\fR allocates a parallel port for exclusive use of the
named hal component.  If successful, access the port with I/O calls such as
\fRrtapi_inb\fR at address based at the \fBbase\fR or \fBbase_hi\fR addresses.
The port must be released with \fBrtapi_parport_release\fR before the component
exits with \fBrtapi_exit\fR.
.SH HIGH ADDRESS PROBING
If the port is a parallel port known to Linux, and Linux detected a high
I/O address, this value is used.  Otherwise, if base+0x400 is not registered
to any device, it is used.  Otherwise, no address is used.  If no high address
is detected, port\->base_hi is 0.
.SH PARPORT STRUCTURE
.in +4n
.nf
typedef struct
{
    unsigned short base;
    unsigned short base_hi;
    .... // and further unspecified fields
} rtapi_parport_t;
.fi
.in
.SH RETURN VALUE
\fBrtapi_parport_get\fR returns a HAL status code.  On success, \fIport\fR is
filled out with information about the allocated port.  On failure, the contents
of \fIport\fR are undefined except that it is safe (but not required) to pass
this port to \fBrtapi_parport_release\fR.

\fBrtapi_parport_release\fR does not return a value.  It always succeeds.
.SH NOTES
In new code, prefer use of rtapi_parport to rtapi_parport.