structure of device driver.htm

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

#define NO_DEV -1 <a name="co_id_27_rtn_3"></a><a href="#co_id_27_3"><strong>[3]</strong></a>
#define MAJOR_INSTANCE 1
</p><p>
#define MAX_NNONE 8 <a name="co_id_27_rtn_4"></a><a href="#co_id_27_4"><strong>[4]</strong></a>
</p></pre>
<p>
</p><p>
</p><ol>
<p></p><li>
<a name="co_id_27_1"></a>
Includes the header file
<tt>tc.h</tt>,
which is the header file associated with the TURBOchannel bus.
If you are writing the driver to operate on multiple bus architectures,
you must include the bus-specific header file.
For example, to write the
<tt>/dev/none</tt>
driver to operate on EISA, ISA, and PCI buses, you need to include the
following header files:
<p>
<tt>#include &lt;io/dec/eisa/eisa.h&gt;</tt>
</p><p>
<tt>#include &lt;io/dec/eisa/isa.h&gt;</tt>
</p><p>
<tt>#include &lt;io/dec/pci/pci.h&gt;</tt>
<a href="#co_id_27_rtn_1">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_27_2"></a>
Includes the device register header file, which is discussed in
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut8.html#DevDrvRegHeadFile">Section 5.1.2</a>.
The directory specification adheres to the directory created in
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut19.html#CreDirContainDrvProdFiles">Section 14.1.1</a>.
The directory specification you make here depends on where you put the
device register header file.
<p>
The previous lines include the common header files.
</p><p>
<cite>Writing Device Drivers: Reference</cite>
provides
reference page descriptions of the header files that
Digital UNIX device drivers use most frequently.
<a href="#co_id_27_rtn_2">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_27_3"></a>
This line and the next line define
constants used by the
<tt>/dev/none</tt>
driver's
<tt>register_major_number</tt>
interface when it reserves a major number. 
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut10.html#ReserveMajorNumber">Section 6.6.5.2</a>
shows how
<tt>register_major_number</tt>
uses these constants.
<a href="#co_id_27_rtn_3">[Return to example]</a>
<p></p></li><li>
<a name="co_id_27_4"></a>
Defines a constant called
<tt>MAX_NNONE</tt>
that is used to allocate data structures needed by the
<tt>/dev/none</tt>
driver.
There can be at most eight instances of the
<tt>NONE</tt>
controller on the system.
This means that
<tt>MAX_NNONE</tt>
is the maximum number of controllers that the
<tt>/dev/none</tt>
driver can support.
This is a small number of instances of the driver and the data structures
themselves are not large, so it is acceptable to allocate for the
maximum configuration.
<p>
Note that
<tt>MAX_NNONE</tt>
is used in the
<tt>none_attributes</tt>
table, specifically as the maximum value for the
<tt>numunit</tt>
attribute field.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut10.html#SetUpConfigureRelDecl">Section 6.3</a>
shows the declaration and initialization of the
<tt>none_attributes</tt>
table.
This example uses the static allocation model technique described
in
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut5.html#DynamicAlloc">Section 2.6.1</a>.
<a href="#co_id_27_rtn_4">[Return to example]</a>
</p></li></ol><p>
<a name="DeclSect"></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="structure%20of%20device%20driver_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="structure%20of%20device%20driver_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#StructDrv"><img src="structure%20of%20device%20driver_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#ExInclFilesSectdevnone"><img src="structure%20of%20device%20driver_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#DeclSectdevnone"><img src="structure%20of%20device%20driver_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/drivertut9.html"><img src="structure%20of%20device%20driver_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="structure%20of%20device%20driver_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="structure%20of%20device%20driver_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h2>
5.2&nbsp;&nbsp;&nbsp;&nbsp;Declarations Section
</h2>
<p>
<a name="nx_id_225"></a>
<a name="nx_id_226"></a>
The declarations section of a block or character device driver contains:
</p><ul>
<p></p><li>
Definitions of symbolic names
<p></p></li><li>
Variable declarations
<p></p></li><li>
Structure declarations
<p></p></li><li>
Declarations of driver interfaces
</li></ul><p>
Device drivers must initialize a
<tt>driver</tt>
structure and a
<tt>dsent</tt>
structure for block and character device drivers.
Device drivers also typically declare an array of pointers to
<tt>controller</tt>
structures.
The following example shows a typical declarations section, using the
<tt>/dev/none</tt>
driver as an example.
Following the example are sections that describe in more detail the
<tt>driver</tt>
and
<tt>dsent</tt>
structures.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut24.html#DeviceAutoconfig">Chapter 17</a>
describes the
<tt>controller</tt>
structure.
<a name="DeclSectdevnone"></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="structure%20of%20device%20driver_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="structure%20of%20device%20driver_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#StructDrv"><img src="structure%20of%20device%20driver_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#DeclSect"><img src="structure%20of%20device%20driver_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#driver_struct"><img src="structure%20of%20device%20driver_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/drivertut9.html"><img src="structure%20of%20device%20driver_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="structure%20of%20device%20driver_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="structure%20of%20device%20driver_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
5.2.1&nbsp;&nbsp;&nbsp;&nbsp;Declarations Section for the /dev/none Device Driver
</h3>
<p>
<a name="nx_id_227"></a>
The following example shows the declarations section for the
<tt>/dev/none</tt>
device driver:
</p><p>
</p><p>
</p><pre><p>
</p><p>
#define DN_RESET 0001 <a name="co_id_28_rtn_1"></a><a href="#co_id_28_1"><strong>[1]</strong></a>
#define DN_ERROR 0002 <a name="co_id_28_rtn_2"></a><a href="#co_id_28_2"><strong>[2]</strong></a> 


#define DN_OPEN  1 <a name="co_id_28_rtn_3"></a><a href="#co_id_28_3"><strong>[3]</strong></a>
#define DN_CLOSE 0 <a name="co_id_28_rtn_4"></a><a href="#co_id_28_4"><strong>[4]</strong></a> 



int noneprobe(), nonecattach(), noneintr();
int noneopen(),  noneclose(),   noneread(), nonewrite();
int noneioctl(), none_ctlr_unattach(); <a name="co_id_28_rtn_5"></a><a href="#co_id_28_5"><strong>[5]</strong></a>


</p><p>


struct controller *noneinfo[MAX_NNONE]; <a name="co_id_28_rtn_6"></a><a href="#co_id_28_6"><strong>[6]</strong></a>


struct driver nonedriver = {
        noneprobe,             
        0,                     
        nonecattach,           
        0,                     
        0,                     
        0,                     
        0,                     
        0,                     
        "none",                
        noneinfo,              
        0,                     
        0,                     
        0,                     
        0,                     
        0,                     
        none_ctlr_unattach,    
        0                      
}; <a name="co_id_28_rtn_7"></a><a href="#co_id_28_7"><strong>[7]</strong></a>


struct none_softc {
	int sc_openf;  
	int sc_count;  
	int sc_state;  
} none_softc[MAX_NNONE]; <a name="co_id_28_rtn_8"></a><a href="#co_id_28_8"><strong>[8]</strong></a>

int none_config = FALSE;  <a name="co_id_28_rtn_9"></a><a href="#co_id_28_9"><strong>[9]</strong></a>
int none_devno = NO_DEV; <a name="co_id_28_rtn_10"></a><a href="#co_id_28_10"><strong>[10]</strong></a>
int NNONE = 1; <a name="co_id_28_rtn_11"></a><a href="#co_id_28_11"><strong>[11]</strong></a>

ihandler_id_t *none_id_t[MAX_NNONE]; <a name="co_id_28_rtn_12"></a><a href="#co_id_28_12"><strong>[12]</strong></a>
</p><p>

</p><p>
int none_is_dynamic = 0; <a name="co_id_28_rtn_13"></a><a href="#co_id_28_13"><strong>[13]</strong></a>

int num_none = 0;   <a name="co_id_28_rtn_14"></a><a href="#co_id_28_14"><strong>[14]</strong></a>

int callback_return_status = ESUCCESS; <a name="co_id_28_rtn_15"></a><a href="#co_id_28_15"><strong>[15]</strong></a>

extern int nodev(), nulldev(); <a name="co_id_28_rtn_16"></a><a href="#co_id_28_16"><strong>[16]</strong></a>
</p><p>
</p><p>
struct dsent none_devsw_entry = {
        noneopen,        
        noneclose,       
        nodev,           
        noneread,        
        nonewrite,       
        noneioctl,       
        nodev,           
        nodev,           /* d_psize */
        nodev,           
        nodev,           
        nodev,           
        0,               
        0,               
        NULL,            
        DEV_FUNNEL,      
        0,               
        0,               
}; <a name="co_id_28_rtn_17"></a><a href="#co_id_28_17"><strong>[17]</strong></a>
</p></pre>
<p>
</p><p>
</p><ol>
<p></p><li>
<a name="co_id_28_1"></a>
Declares a constant called
<tt>DN_RESET</tt>
to indicate that the specified
<tt>NONE</tt>
device is ready for data transfer.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut11.html#probeReadandWriteData">Section 7.1.9</a>
shows that the
<tt>noneprobe</tt>
interface uses this constant to set the
<tt>NONE_CSR</tt>
device register offset associated with a specific
<tt>NONE</tt>
device.
If this driver operated on actual hardware, setting the
<tt>DN_RESET</tt>
bit could force the device to reset.
<a href="#co_id_28_rtn_1">[Return to example]</a>
<p></p></li><li>
<a name="co_id_28_2"></a>
Declares a constant called
<tt>DN_ERROR</tt>
to indicate when an error occurs.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut11.html#probeReadandWriteData">Section 7.1.9</a>
shows that the
<tt>noneprobe</tt>
interface uses this constant in a bitwise AND operation with the
<tt>NONE_CSR</tt>
device register offset associated with a specific
<tt>NONE</tt>
device.
An actual hardware device could set this bit in the
<tt>NONE_CSR</tt>
device register offset to indicate that an error condition occurred.
<a href="#co_id_28_rtn_2">[Return to example]</a>
<p></p></li><li>
<a name="co_id_28_3"></a>
Declares a constant called
<tt>DN_OPEN</tt>
to represent the device open bit.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut14.html#DetermDevOpen">Section 10.1.2</a>
shows that the
<tt>noneopen</tt>
interface uses this constant to set the open bit
for a specific
<tt>NONE</tt>
device.
This bit represents the driver's software state.
<a href="#co_id_28_rtn_3">[Return to example]</a>
<p></p></li><li>
<a name="co_id_28_4"></a>
Declares a constant called
<tt>DN_CLOSE</tt>
to represent the device close bit.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut14.html#PerformCloseDevTasks">Section 10.2.2</a>
shows that the
<tt>noneclose</tt>
interface uses this constant to clear the open bit for a
specific
<tt>NONE</tt>
device.