drivertut7.html

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

<tr>
<td align="left" valign="top">
<tt>bufflush</tt>
</td>
<td align="left" valign="top">
ULTRIX BSD device drivers written for platforms
based on MIPS use
the
<tt>bufflush</tt>
interface.
This interface is not used for Alpha platforms.
Therefore, delete this interface from your device driver. 
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>KM_ALLOC</tt>
</td>
<td align="left" valign="top">
A previous version of the operating system
instructed you to replace calls to
<tt>KM_ALLOC</tt>
with calls to
<tt>kalloc</tt>.
Digital UNIX supports a new memory allocator.
Thus, replace calls to
<tt>KM_ALLOC</tt>
with calls to
<tt>MALLOC</tt>.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>KM_FREE</tt>
</td>
<td align="left" valign="top">
A previous version of the operating system
instructed you to replace calls to
<tt>KM_FREE</tt>
with calls to
<tt>kfree</tt>.
Digital UNIX supports a new memory allocator.
Thus, replace calls to
<tt>KM_FREE</tt>
with calls to
<tt>FREE</tt>.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>printf</tt>
interfaces
</td>
<td align="left" valign="top">
ULTRIX device drivers can call
<tt>cprintf</tt>,
<tt>mprintf</tt>,
<tt>printf</tt>,
and
<tt>uprintf</tt>.
Digital UNIX device drivers can call
<tt>printf</tt>
and
<tt>uprintf</tt>.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>selwakeup</tt>
</td>
<td align="left" valign="top">
The
<tt>selwakeup</tt>
interface is not used in Digital UNIX.
Replace calls to
<tt>selwakeup</tt>
with calls to
<tt>select_wakeup</tt>.
Note that the formal parameters for the two interfaces are different.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>vslock</tt>
</td>
<td align="left" valign="top">
The
<tt>vslock</tt>
interface is obsolete on Digital UNIX.
Therefore, replace calls to
<tt>vslock</tt>
with calls to
<tt>vm_map_pageable</tt>.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>vsunlock</tt>
</td>
<td align="left" valign="top">
The
<tt>vsunlock</tt>
interface is obsolete on Digital UNIX.
Therefore, replace calls to
<tt>vsunlock</tt>
with calls to
<tt>vm_map_pageable</tt>.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>useracc</tt>
</td>
<td align="left" valign="top">
The
<tt>useracc</tt>
interface is obsolete on Digital UNIX.
If you called
<tt>useracc</tt>
with
<tt>vslock</tt>,
replace both interfaces with a call to
<tt>vm_map_pageable</tt>.
Typically, the
<tt>useracc</tt>
interface was called by the driver's
<tt>strategy</tt>
interface.
In most cases, the driver's
<tt>strategy</tt>
interface would be called indirectly from the
<tt>physio</tt>
interface (in response to
<tt>read</tt>
and
<tt>write</tt>
system calls or file-system access).
<p>
In Digital UNIX, the
<tt>physio</tt>
interface verifies access permissions to the user buffer and locks down
the memory.
For this reason, in existing drivers that may have historically called
<tt>useracc</tt>,
it is no longer necessary to perform such a check and subsequent locking
of memory with
<tt>vslock</tt>.
The general rule is that any interface called
from the
<tt>physio</tt>
interface (that is, the driver's
<tt>strategy</tt>
interface) should not call
<tt>useracc</tt>
or its replacement
<tt>vm_map_pageable</tt>
because the
<tt>physio</tt>
interface
performs those functions.
</p><p>
If you called
<tt>useracc</tt>
prior to accessing user data, replace it with calls to
<tt>copyin</tt>
and
<tt>copyout</tt>
to access user space.
Calling
<tt>useracc</tt>
simply verifies access permissions to the specified memory at the time the
<tt>useracc</tt>
interface is called.
It is possible that immediately after the
<tt>useracc</tt>
interface has returned back to the driver that the corresponding memory
could be invalid.
The memory could be invalid if it was swapped out or otherwise remapped
by the virtual memory management portion of the kernel.
Therefore, a driver should not assume that the memory region whose access
permissions are verified through a call to
<tt>useracc</tt>
is persistent.
</p><p>
In Digital UNIX,
calls to
<tt>useracc</tt>
are either unnecessary (as previously explained) or should
be replaced by direct calls to
<tt>vm_map_pageable</tt>.
This interface performs functions for both verifying access permissions
and for locking down the memory so that it cannot be invalidated until it
is unlocked by subsequent calls to
<tt>vm_map_pageable</tt>
for this memory region.
</p></td>
</tr>
</tbody></table><p>
<a name="CheckDataStructs"></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="drivertut7_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="drivertut7_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#PortUNIXDrvs"><img src="drivertut7_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#CheckKernelInter"><img src="drivertut7_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#PortingDevDrvsCurVersUNIX"><img src="drivertut7_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/drivertut8.html"><img src="drivertut7_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="drivertut7_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="drivertut7_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
4.1.6&nbsp;&nbsp;&nbsp;&nbsp;Checking Data Structures
</h3>
<p>
<a name="nx_id_159"></a>
You need to compare the data structures that ULTRIX device drivers use
with those that Digital UNIX device drivers use.
<cite>Writing Device Drivers: Reference</cite>
provides
reference page descriptions of the data structures that
Digital UNIX device drivers use.
Use this information to compare the data structure's members with its
associated ULTRIX data structure. 
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut7.html#tblDifferDataStructs">Table 4-2</a>
lists some of these differences.
</p><p>
<a name="tblDifferDataStructs"></a>
</p><h3>
Table 4-2: Highlights of Differences Between Digital UNIX and ULTRIX Data Structures
</h3>
<a name="nx_id_160"></a>
<table border="4" cellpadding="4">
<tbody><tr>
<td align="left" valign="top">
<strong>
Data Structure
</strong>
</td>
<td align="left" valign="top">
<strong>
Remarks
</strong>
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>uba_ctlr</tt>
</td>
<td align="left" valign="top">
Replace references to the
<tt>uba_ctlr</tt>
structure and its associated members with references to the
<tt>controller</tt>
structure and its associated members.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>uba_device</tt>
</td>
<td align="left" valign="top">
Replace references to the
<tt>uba_device</tt>
structure and its associated members with references to the
<tt>device</tt>
structure and its associated members.
Make sure that the reference is to a slave, for example, a disk or tape
drive.
If the reference is to a controller, reference the
<tt>controller</tt>
structure, not the
<tt>device</tt>
structure.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>uba_driver</tt>
</td>
<td align="left" valign="top">
Replace references to the
<tt>uba_driver</tt>
structure and its associated members with references to the
<tt>driver</tt>