char device driver interfaces.htm

What is this ``device driver stuff anyway? Here s a very short introduction to the concept.

<tt>links</tt>
</td>
<td align="left" valign="top">
<tt>struct queue_entry</tt>
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>event</tt>
</td>
<td align="left" valign="top">
<tt>struct event *</tt>
</td>
</tr>
</tbody></table><p>
</p><p>
The
<tt>links</tt>
member specifies
a
<tt>queue_entry</tt>
structure.
This structure contains a generic doubly linked list (queue).
</p><p>
The
<tt>event</tt>
member specifies
a pointer to an
<tt>event</tt>
structure.
This structure is an opaque structure; that is, you do not reference
it in your device driver. 
<a name="SetUpSelectRoutine"></a>
</p><p></p><hr><p align="center">
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/Digital_UNIX_Bookshelf.html"><img src="char%20device%20driver%20interfaces_files/BOOKSHELF.GIF" alt="[Return to Library]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/TOC.html"><img src="char%20device%20driver%20interfaces_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#ImplCharDrvRoutines"><img src="char%20device%20driver%20interfaces_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#Thesel_queueStruct"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#PollingInputReadsselectRtns"><img src="char%20device%20driver%20interfaces_files/NEXT.GIF" alt="[Next Section]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut13.html"><img src="char%20device%20driver%20interfaces_files/FF.GIF" alt="[Next Chapter]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/INDEX.html"><img src="char%20device%20driver%20interfaces_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="char%20device%20driver%20interfaces_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
8.4.2&nbsp;&nbsp;&nbsp;&nbsp;Setting Up the select Interface
</h3>
<p>
<a name="nx_id_446"></a>
The following code shows you how to set up a
<tt>select</tt>
interface (and a typical declaration of the
<tt>sel_queue</tt>
structure), using the
<tt>/dev/xx</tt>
driver as an example.
</p><p>
</p><pre><br>.<br>.<br>.<br>
struct {
<br>.<br>.<br>.<br>
 sel_queue_t * sel_q;
<br>.<br>.<br>.<br>
} xx_softc[NXX]; <a name="co_id_69_rtn_1"></a><a href="#co_id_69_1"><strong>[1]</strong></a>

xxselect(dev, events, revents, scanning)
 dev_t dev;      <a name="co_id_69_rtn_2"></a><a href="#co_id_69_2"><strong>[2]</strong></a>
 short *events;  <a name="co_id_69_rtn_3"></a><a href="#co_id_69_3"><strong>[3]</strong></a>
 short *revents; <a name="co_id_69_rtn_4"></a><a href="#co_id_69_4"><strong>[4]</strong></a>
 int scanning;   <a name="co_id_69_rtn_5"></a><a href="#co_id_69_5"><strong>[5]</strong></a>
{
</pre>
<p>
<a name="nx_id_447"></a>
</p><ol>
<p></p><li>
<a name="co_id_69_1"></a>
Declares an array of
<tt>softc</tt>
structures and calls it
<tt>xx_softc</tt>.
One of the members of the
<tt>xx_softc</tt>
structure is a pointer to a
<tt>sel_queue</tt>
data structure.
The
<tt>sel_queue</tt>
data structure provides device driver writers with a generic queue of
select events.
You must initialize the
<tt>links</tt>
member by calling the
<tt>queue_init</tt>
interface prior to using the
<tt>select_enqueue</tt>
and
<tt>select_dequeue</tt>
interfaces.
<a href="#co_id_69_rtn_1">[Return to example]</a>
<p></p></li><li>
<a name="co_id_69_2"></a>
Declares an argument that specifies the major and minor device numbers
for a specific
<tt>XX</tt>
device.
The minor device number is used to determine the logical unit number for
the
<tt>XX</tt>
device on which the select call is to be performed.
<a href="#co_id_69_rtn_2">[Return to example]</a>
<p></p></li><li>
<a name="co_id_69_3"></a>
Declares a pointer to an argument that specifies
the events to be polled.
This argument is an input to the device driver.
A user-level process issues a
<tt>select</tt>
system call.
The
<tt>select</tt>
system call then causes the kernel to call the driver's
<tt>select</tt>
interface.
The kernel can set this argument to the bitwise inclusive OR of one or
more of the polling bit masks defined in the file
<tt>/usr/sys/include/sys/poll.h</tt>:
<tt>POLLNORM</tt>,
<tt>POLLOUT</tt>,
and
<tt>POLLPRI</tt>.
<a href="#co_id_69_rtn_3">[Return to example]</a>
<p></p></li><li>
<a name="co_id_69_4"></a>
Declares a pointer to an argument that specifies
the events that are ready.
The driver writer sets this value in the driver's
<tt>select</tt>
interface.
The driver writer can set this argument to the bitwise inclusive OR of one or
more of the polling bit masks defined in
<tt>/usr/sys/include/sys/poll.h</tt>:
<tt>POLLNVAL</tt>,
<tt>POLLHUP</tt>,
<tt>POLLNORM</tt>,
and
<tt>POLLOUT</tt>.
<a href="#co_id_69_rtn_4">[Return to example]</a>
<p></p></li><li>
<a name="co_id_69_5"></a>
Declares an argument that specifies
the initiation and termination of a select call.
The kernel sets this argument to the value 1 to indicate initiation
of a select call.
A user-level process issues a
<tt>select</tt>
system call.
The
<tt>select</tt>
system call then causes the kernel to call the driver's
<tt>select</tt>
interface.
<a href="#co_id_69_rtn_5">[Return to example]</a>
</li></ol><p>
<a name="PollingInputReadsselectRtns"></a>
</p><p></p><hr><p align="center">
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/Digital_UNIX_Bookshelf.html"><img src="char%20device%20driver%20interfaces_files/BOOKSHELF.GIF" alt="[Return to Library]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/TOC.html"><img src="char%20device%20driver%20interfaces_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#ImplCharDrvRoutines"><img src="char%20device%20driver%20interfaces_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#SetUpSelectRoutine"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#PollingOutputWritesselectRtns"><img src="char%20device%20driver%20interfaces_files/NEXT.GIF" alt="[Next Section]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut13.html"><img src="char%20device%20driver%20interfaces_files/FF.GIF" alt="[Next Chapter]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/INDEX.html"><img src="char%20device%20driver%20interfaces_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="char%20device%20driver%20interfaces_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
8.4.3&nbsp;&nbsp;&nbsp;&nbsp;Using the select Interfaces to poll for Input Reads
</h3>
<p>
<a name="nx_id_448"></a>
<a name="nx_id_449"></a>
<a name="nx_id_450"></a>
One task that a device driver's
<tt>select</tt>
interface can perform is to poll for input reads.
A device driver typically calls two kernel support interfaces when
polling for input reads:
<tt>select_enqueue</tt>
and
<tt>select_dequeue</tt>.
In addition, a device driver calls the
<tt>queue_init</tt>
kernel support interface to initialize the specified queue.
The
<tt>minor</tt>
interface is used to obtain the minor device number associated with a
specific device.
The following code shows you how to call these interfaces when polling
for input reads, using the
<tt>/dev/xx</tt>
driver as an example.
</p><p>
<br>
<tt>.</tt>
<br>
<tt>.</tt>
<br>
<tt>.</tt>
<br>
</p><p>
</p><pre>xxcattach (ctlr)
struct controller *ctlr;
<br>.<br>.<br>.<br>
        queue_init(&amp;sc-&gt;sel_q.links); <a name="co_id_70_rtn_1"></a><a href="#co_id_70_1"><strong>[1]</strong></a>
<br>.<br>.<br>.<br>
        int nread; <a name="co_id_70_rtn_2"></a><a href="#co_id_70_2"><strong>[2]</strong></a>
        register int unit = minor(dev); <a name="co_id_70_rtn_3"></a><a href="#co_id_70_3"><strong>[3]</strong></a>
        struct xx_softc *sc = &amp;xx_softc[unit]; <a name="co_id_70_rtn_4"></a><a href="#co_id_70_4"><strong>[4]</strong></a>
        if (*events &amp; POLLNORM) { <a name="co_id_70_rtn_5"></a><a href="#co_id_70_5"><strong>[5]</strong></a>
                if (scanning) { <a name="co_id_70_rtn_6"></a><a href="#co_id_70_6"><strong>[6]</strong></a>
                        nread = xxnread(dev); <a name="co_id_70_rtn_7"></a><a href="#co_id_70_7"><strong>[7]</strong></a>
                        if (nread &gt; 0)
                                *revents |= POLLNORM; <a name="co_id_70_rtn_8"></a><a href="#co_id_70_8"><strong>[8]</strong></a>
                        else
                                select_enqueue(&amp;sc-&gt;sel_q); <a name="co_id_70_rtn_9"></a><a href="#co_id_70_9"><strong>[9]</strong></a>
                } else
                        select_dequeue(&amp;sc-&gt;sel_q); <a name="co_id_70_rtn_10"></a><a href="#co_id_70_10"><strong>[10]</strong></a>
        }
</pre>
<p>
<br>
<tt>.</tt>
<br>
<tt>.</tt>
<br>
<tt>.</tt>
<br>
</p><p>
</p><ol>
<p></p><li>
<a name="co_id_70_1"></a>
Calls the
<tt>queue_init</tt>
interface.
The
<tt>queue_init</tt>
interface initializes the specified queue.
Device drivers call this interface prior to calling
<tt>select_enqueue</tt>
to initialize the
<tt>links</tt>
member of the
<tt>sel_queue</tt>
data structure.
This member specifies
a
<tt>queue_entry</tt>
structure.
This structure contains a generic doubly linked list (queue).
<p>
The
<tt>queue_init</tt>
interface takes one argument:
a pointer to a
<tt>queue_entry</tt>
structure.
This structure contains a
<tt>links</tt>
member that specifies
a
<tt>queue_entry</tt>
structure.
This structure contains a generic doubly linked list (queue).
</p><p>
In the example, the
<tt>links</tt>
member passed to
<tt>queue_init</tt>
is referenced through the
<tt>sel_q</tt>
member of the
<tt>softc</tt>
structure.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html#SetUpSelectRoutine">Section 8.4.2</a>
shows the declaration of the
<tt>/dev/xx</tt>
driver's
<tt>softc</tt>
structure.
<a name="nx_id_451"></a>
<a href="#co_id_70_rtn_1">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_70_2"></a>
Declares a variable to contain the number of characters available for
input.
<a href="#co_id_70_rtn_2">[Return to example]</a>
<p></p></li><li>
<a name="co_id_70_3"></a>
Calls the
<tt>minor</tt>
interface to obtain the minor device number associated with this
<tt>XX</tt>
device.
The minor interface takes one argument:
the number of the device whose associated minor device number the
<tt>minor</tt>
interface will obtain.
Upon successful completion,
<tt>minor</tt>
returns the minor number portion of the
<tt>dev_t</tt>
passed as the argument.
<a name="nx_id_452"></a>