'\" t
.\"     Title: parport_register_device
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: January 2017
.\"    Manual: Parallel Port Devices
.\"    Source: Kernel Hackers Manual 4.8.15
.\"  Language: English
.\"
.TH "PARPORT_REGISTER_DEV" "9" "January 2017" "Kernel Hackers Manual 4\&.8\&." "Parallel Port Devices"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
parport_register_device \- register a device on a parallel port
.SH "SYNOPSIS"
.HP \w'struct\ pardevice\ *\ parport_register_device('u
.BI "struct pardevice * parport_register_device(struct\ parport\ *\ " "port" ", const\ char\ *\ " "name" ", int\ (*" "pf" ")\ (void\ *), void\ (*" "kf" ")\ (void\ *), void\ (*" "irq_func" ")\ (void\ *), int\ " "flags" ", void\ *\ " "handle" ");"
.SH "ARGUMENTS"
.PP
\fIport\fR
.RS 4
port to which the device is attached
.RE
.PP
\fIname\fR
.RS 4
a name to refer to the device
.RE
.PP
\fIpf\fR
.RS 4
preemption callback
.RE
.PP
\fIkf\fR
.RS 4
kick callback (wake\-up)
.RE
.PP
\fIirq_func\fR
.RS 4
interrupt handler
.RE
.PP
\fIflags\fR
.RS 4
registration flags
.RE
.PP
\fIhandle\fR
.RS 4
data for callback functions
.RE
.SH "DESCRIPTION"
.PP
This function, called by parallel port device drivers, declares that a device is connected to a port, and tells the system all it needs to know\&.
.PP
The
\fIname\fR
is allocated by the caller and must not be deallocated until the caller calls
\fIparport_unregister_device\fR
for that device\&.
.PP
The preemption callback function,
\fIpf\fR, is called when this device driver has claimed access to the port but another device driver wants to use it\&. It is given
\fIhandle\fR
as its parameter, and should return zero if it is willing for the system to release the port to another driver on its behalf\&. If it wants to keep control of the port it should return non\-zero, and no action will be taken\&. It is good manners for the driver to try to release the port at the earliest opportunity after its preemption callback rejects a preemption attempt\&. Note that if a preemption callback is happy for preemption to go ahead, there is no need to release the port; it is done automatically\&. This function may not block, as it may be called from interrupt context\&. If the device driver does not support preemption,
\fIpf\fR
can be
\fBNULL\fR\&.
.PP
The wake\-up (\(lqkick\(rq) callback function,
\fIkf\fR, is called when the port is available to be claimed for exclusive access; that is,
\fBparport_claim\fR
is guaranteed to succeed when called from inside the wake\-up callback function\&. If the driver wants to claim the port it should do so; otherwise, it need not take any action\&. This function may not block, as it may be called from interrupt context\&. If the device driver does not want to be explicitly invited to claim the port in this way,
\fIkf\fR
can be
\fBNULL\fR\&.
.PP
The interrupt handler,
\fIirq_func\fR, is called when an interrupt arrives from the parallel port\&. Note that if a device driver wants to use interrupts it should use
\fBparport_enable_irq\fR, and can also check the irq member of the parport structure representing the port\&.
.PP
The parallel port (lowlevel) driver is the one that has called
\fBrequest_irq\fR
and whose interrupt handler is called first\&. This handler does whatever needs to be done to the hardware to acknowledge the interrupt (for PC\-style ports there is nothing special to be done)\&. It then tells the IEEE 1284 code about the interrupt, which may involve reacting to an IEEE 1284 event depending on the current IEEE 1284 phase\&. After this, it calls
\fIirq_func\fR\&. Needless to say,
\fIirq_func\fR
will be called from interrupt context, and may not block\&.
.PP
The
\fBPARPORT_DEV_EXCL\fR
flag is for preventing port sharing, and so should only be used when sharing the port with other device drivers is impossible and would lead to incorrect behaviour\&. Use it sparingly! Normally,
\fIflags\fR
will be zero\&.
.PP
This function returns a pointer to a structure that represents the device on the port, or
\fBNULL\fR
if there is not enough memory to allocate space for that structure\&.
.SH "COPYRIGHT"
.br