char device driver interfaces.htm

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

member)
and decrements the number of
remaining logical buffer segments (represented by the
<tt>uio_iovcnt</tt>
member).
<a href="#co_id_67_rtn_8">[Return to example]</a>
<p></p></li><li>
<a name="co_id_67_9"></a>
If the number of remaining logical buffer segments is less than zero
(0), there
is no data to write; therefore, the
<tt>/dev/none</tt>
driver calls the
<tt>panic</tt>
interface to cause a system crash and displays the message ``none
write''
on the console terminal.
This code represents an error condition that should never occur.
<p>
The
<tt>panic</tt>
interface takes one argument:
the message you want the
<tt>panic</tt>
interface to display on the console terminal.
<a name="nx_id_437"></a>
<a href="#co_id_67_rtn_9">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_67_10"></a>
Sets the
<tt><var>count</var></tt>
variable to the number of bytes contained in the current segment
(represented by the
<tt>iov_len</tt>
member).
This value is the size of the write request.
<a href="#co_id_67_rtn_10">[Return to example]</a>
<p></p></li><li>
<a name="co_id_67_11"></a>
Adds the number of bytes in the write request
to the address of the current byte within the logical buffer segment
(represented by the
<tt>iov_base</tt>
member).
<a href="#co_id_67_rtn_11">[Return to example]</a>
<p></p></li><li>
<a name="co_id_67_12"></a>
Subtracts the number of bytes in the write request from the
current segment (represented by the
<tt>iov_len</tt>
member).
<a href="#co_id_67_rtn_12">[Return to example]</a>
<p></p></li><li>
<a name="co_id_67_13"></a>
Adds the number of bytes in the write request to the current
offset into the full logical buffer (represented by the
<tt>uio_offset</tt>
member).
<a href="#co_id_67_rtn_13">[Return to example]</a>
<p></p></li><li>
<a name="co_id_67_14"></a>
Subtracts the number of bytes in the write request from the
size of the remaining logical buffer (represented by the
<tt>uio_resid</tt>
member).
<a href="#co_id_67_rtn_14">[Return to example]</a>
<p></p></li><li>
<a name="co_id_67_15"></a>
Adds the number of bytes in the write request to the
<tt>sc_count</tt>
member of the
<tt>sc</tt>
pointer.
When there are no more bytes,
<tt>nonewrite</tt>
returns
<tt>ESUCCESS</tt>
to indicate a successful write.
Otherwise, it returns an appropriate error code that identifies the
problem.
You obtain the error codes from the file
<tt>/usr/sys/include/sys/errno.h</tt>.
Because there is no physical device associated with
<tt>/dev/none</tt>,
<tt>nonewrite</tt>
does not actually copy data anywhere.
<a href="#co_id_67_rtn_15">[Return to example]</a>
</li></ol><p>
<a name="ImplementTheResetRoutine"></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="#CopyDataWriteRoutine"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#SetUpResetRoutine"><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><h2>
8.3&nbsp;&nbsp;&nbsp;&nbsp;Implementing the reset Interface
</h2>
<p>
<a name="nx_id_438"></a>
A device driver's
<tt>reset</tt>
interface performs the tasks necessary to force a device reset to place
the device in a known state after a bus reset operation.
The bus adapter code calls the driver's
<tt>reset</tt>
interface after completion of a bus reset operation.
The code associated with a
<tt>reset</tt>
interface resides in the reset section of the device
driver.
You specify the entry point for a driver's
<tt>reset</tt>
interface in a
<tt>dsent</tt>
structure.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut10.html#dsentDataStruct">Section 6.6.5.1</a>
describes the
<tt>dsent</tt>
structure.
<cite>Writing Device Drivers: Reference</cite>
provides a reference page that gives additional information on the
arguments and tasks associated with
a
<tt>reset</tt>
interface.
The following section describes how to set up a 
<tt>reset</tt>
inteface, using the
<tt>/dev/xx</tt>
driver as an example.
<a name="SetUpResetRoutine"></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="#ImplementTheResetRoutine"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#ImplementTheSelectRoutine"><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.3.1&nbsp;&nbsp;&nbsp;&nbsp;Setting Up the reset Interface
</h3>
<p>
<a name="nx_id_439"></a>
The following code shows you how to set up a
<tt>reset</tt>
interface, using the
<tt>/dev/xx</tt>
driver as an example:
</p><p>
</p><p>
</p><pre>xxreset(busnum)
int busnum; <a name="co_id_68_rtn_1"></a><a href="#co_id_68_1"><strong>[1]</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_68_1"></a>
Declares an argument that specifies
the logical unit number of the bus on which the bus reset
occurred.
<a href="#co_id_68_rtn_1">[Return to example]</a>
</li></ol><p>
<a name="ImplementTheSelectRoutine"></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="#SetUpResetRoutine"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#Thesel_queueStruct"><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><h2>
8.4&nbsp;&nbsp;&nbsp;&nbsp;Implementing the select Interface
</h2>
<p>
<a name="nx_id_440"></a>
A device driver's
<tt>select</tt>
interface performs the tasks necessary to determine whether data is
available for reading and whether space is available for writing data.
The kernel calls a driver's
<tt>select</tt>
interface on behalf of applications that make a
<tt>select</tt>
system call.
The code associated with a
<tt>select</tt>
interface resides in the select section of the device
driver.
You specify the entry point for a driver's
<tt>select</tt>
interface in a
<tt>dsent</tt>
structure.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut10.html#dsentDataStruct">Section 6.6.5.1</a>
describes the
<tt>dsent</tt>
structure.
<cite>Writing Device Drivers: Reference</cite>
provides a reference page that gives additional information on the
arguments and tasks associated with
a
<tt>select</tt>
interface.
</p><p>
<a name="nx_id_441"></a>
</p><p>
The following list describes some typical tasks that you perform when
implementing
a
<tt>select</tt>
interface.
</p><ul>
<p></p><li>
Use the
<tt>sel_queue</tt>
data structure
<p></p></li><li>
Set up the
<tt>select</tt>
interface
<p></p></li><li>
Poll for input reads and output writes
</li></ul><p>
Your
<tt>select</tt>
interface will probably perform most of these tasks and, possibly, some
additional ones.
The following sections describe each of these tasks, using the
<tt>/dev/xx</tt>
driver as an example.
<a name="Thesel_queueStruct"></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="#ImplementTheSelectRoutine"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#SetUpSelectRoutine"><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.1&nbsp;&nbsp;&nbsp;&nbsp;Using the sel_queue Data Structure
</h3>
<p>
<a name="nx_id_442"></a>
<a name="nx_id_443"></a>
<a name="nx_id_444"></a>
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="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html#PollingInputReadsselectRtns">Section 8.4.3</a>
and
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html#PollingOutputWritesselectRtns">Section 8.4.4</a>
show how the
<tt>/dev/xx</tt>
driver's
<tt>select</tt>
interface calls these interfaces.
</p><p>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html#Tblsel_queueStructMembers">Table 8-2</a>
lists the members of the
<tt>sel_queue</tt>
structure along with their associated data types.
<a name="Tblsel_queueStructMembers"></a>
</p><h3>
Table 8-2: Members of the sel_queue Structure
</h3>
<a name="nx_id_445"></a>
<table border="4" cellpadding="4">
<tbody><tr>
<td align="left" valign="top">
<strong>
Member Name
</strong>
</td>
<td align="left" valign="top">
<strong>
Data Type
</strong>
</td>
</tr>
<tr>
<td align="left" valign="top">