char device driver interfaces.htm

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

<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html#tbluioStructMembers">Table 8-1</a>
lists the members of the
<tt>uio</tt>
structure along with their associated data types that you might need to
understand.
</p><p>
<a name="tbluioStructMembers"></a>
</p><h3>
Table 8-1: Members of the uio Structure
</h3>
<a name="nx_id_425"></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">
<tt>uio_iov</tt>
</td>
<td align="left" valign="top">
<tt>struct iovec *</tt>
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>uio_iovcnt</tt>
</td>
<td align="left" valign="top">
<tt>int</tt>
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>uio_offset</tt>
</td>
<td align="left" valign="top">
<tt>off_t</tt>
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>uio_segflg</tt>
</td>
<td align="left" valign="top">
<tt>enum uio_seg</tt>
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>uio_resid</tt>
</td>
<td align="left" valign="top">
<tt>int</tt>
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>uio_rw</tt>
</td>
<td align="left" valign="top">
<tt>enum uio_rw</tt>
</td>
</tr>
</tbody></table><p>
</p><p>
The following character driver interfaces take a pointer to a
<tt>uio</tt>
structure as an argument:
<tt>read</tt>
and
<tt>write</tt>.
The following sections discuss each of these members.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html#CopyDataWriteRoutine">Section 8.2.2</a>
shows how the
<tt>/dev/none</tt>
driver's
<tt>write</tt>
interface uses the
<tt>uio</tt>
structure.
<a name="Theuio_iovMembers"></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="#theuio_struct"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#Theuio_offsetMembers"><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.1.2.1&nbsp;&nbsp;&nbsp;&nbsp;The uio_iov and uio_iovcnt Members
</h3>
<p>
<a name="nx_id_426"></a>
<a name="nx_id_427"></a>
The
<tt>uio_iov</tt>
member specifies
a pointer to the first
<tt>iovec</tt>
structure.
The
<tt>iovec</tt>
structure has two members: one that specifies the address of the segment
and another that specifies the size of the segment.
The system allocates contiguous
<tt>iovec</tt>
structures for a given transfer. 
</p><p>
The
<tt>uio_iovcnt</tt>
member specifies the number of 
<tt>iovec</tt>
structures for this transfer.
<a name="Theuio_offsetMembers"></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="#Theuio_iovMembers"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#Theuio_residMembers"><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.1.2.2&nbsp;&nbsp;&nbsp;&nbsp;The uio_offset and uio_segflg Members
</h3>
<p>
<a name="nx_id_428"></a>
<a name="nx_id_429"></a>
The
<tt>uio_offset</tt>
member specifies the offset within the file.
</p><p>
The
<tt>uio_segflg</tt>
member specifies
the segment type.
This member can be set to one of the following values:
<tt>UIO_USERSPACE</tt>
(the segment is from the user data space),
<tt>UIO_SYSSPACE</tt>
(the segment is from the system space),
or
<tt>UIO_USERISPACE</tt>
(the segment is from the user I space).
<a name="Theuio_residMembers"></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="#Theuio_offsetMembers"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#SetUpReadRoutine"><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.1.2.3&nbsp;&nbsp;&nbsp;&nbsp;The uio_resid and uio_rw Members
</h3>
<p>
<a name="nx_id_430"></a>
<a name="nx_id_431"></a>
The
<tt>uio_resid</tt>
member specifies the number of bytes that still need to be transferred.
</p><p>
The
<tt>uio_rw</tt>
member specifies
whether the transfer is a read or a write.
This member is set by
<tt>read</tt>
and
<tt>write</tt>
system calls according to the corresponding field in the file
descriptor.
This member can be set to one of the following values:
<tt>UIO_READ</tt>
(read transfer),
<tt>UIO_WRITE</tt>
(write transfer),
or
<tt>UIO_AIORW</tt>
(Alpha I/O read/write transfer).
<a name="SetUpReadRoutine"></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="#Theuio_residMembers"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#ImplementTheWriteRoutine"><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.1.3&nbsp;&nbsp;&nbsp;&nbsp;Setting Up the read Interface
</h3>
<p>
<a name="nx_id_432"></a>
The following code shows you how to set up a
<tt>read</tt>
interface, using the
<tt>/dev/none</tt>
driver as an example:
</p><p>
</p><p>
</p><pre><p>
noneread(dev, uio, flag)
dev_t dev;       <a name="co_id_65_rtn_1"></a><a href="#co_id_65_1"><strong>[1]</strong></a>
struct uio *uio; <a name="co_id_65_rtn_2"></a><a href="#co_id_65_2"><strong>[2]</strong></a>
int flag; <a name="co_id_65_rtn_3"></a><a href="#co_id_65_3"><strong>[3]</strong></a>
{
	return (ESUCCESS); <a name="co_id_65_rtn_4"></a><a href="#co_id_65_4"><strong>[4]</strong></a>
}
</p></pre>
<p>
<br>
<tt>.</tt>
<br>
<tt>.</tt>
<br>
<tt>.</tt>
<br>
</p><p>
</p><ol>
<p></p><li>
<a name="co_id_65_1"></a>
Declares an
argument that specifies the major and minor device numbers for
a specific
<tt>NONE</tt>
device.
The minor device number is used to determine the logical unit number for
the
<tt>NONE</tt>
device on which the read operation is performed.
<a href="#co_id_65_rtn_1">[Return to example]</a>
<p></p></li><li>
<a name="co_id_65_2"></a>
Declares a pointer to a
<tt>uio</tt>
structure.
This structure contains the information for transferring data to and
from the address space of the user's process.
You typically
pass this pointer unmodified to the
<tt>uiomove</tt>
or
<tt>physio</tt>
kernel interface.
<a href="#co_id_65_rtn_2">[Return to example]</a>
<p></p></li><li>
<a name="co_id_65_3"></a>
Specifies the access mode of the device.
The access modes are represented by a bit mask of flags defined in the
file
<tt>/usr/sys/include/sys/fcntl.h</tt>.
<a href="#co_id_65_rtn_3">[Return to example]</a>
<p></p></li><li>
<a name="co_id_65_4"></a>
Because the
<tt>/dev/none</tt>
driver always returns EOF (end-of-file) on read operations, the
<tt>noneread</tt>
interface simply returns
<tt>ESUCCESS</tt>.
More complicated drivers would need to copy data from the device into
the address space pointed to by the
<tt>uio</tt>
structure.
<a href="#co_id_65_rtn_4">[Return to example]</a>
</li></ol><p>
<a name="ImplementTheWriteRoutine"></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="#SetUpReadRoutine"><img src="char%20device%20driver%20interfaces_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#SetUpWriteRoutine"><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.2&nbsp;&nbsp;&nbsp;&nbsp;Implementing the write Interface
</h2>
<p>
<a name="nx_id_433"></a>
A device driver's
<tt>write</tt>
interface performs the tasks necessary to write data to a device.
The kernel calls the driver's
<tt>write</tt>
interface for character device drivers
on behalf of applications that make a
<tt>write</tt>
system call.
The code associated with a
<tt>write</tt>
interface resides in the read and write device section of the device