<dd><p class="ListV"><a name="85127"> </a>[1]    The driver calls <b class="routine"><i class="routine">iosDrvInstall</i></b><b>(</b>&nbsp;<b>)</b>, specifying the addresses of the driver's routines for the seven basic I/O functions.</p></dl><dd><p class="Body"><a name="85128"> </a>The I/O system:</p><dl class="margin"><dd><p class="ListV"><a name="85129"> </a>[2]    Locates the next available slot in the driver table, in this case slot 2.</p><dd><p class="ListV"><a name="85130"> </a>[3]    Enters the addresses of the driver routines in the driver table.</p><dd><p class="ListV"><a name="89869"> </a>[4]    Returns the slot number as the driver number of the newly installed driver. </p><dd><p class="ListV"><a name="93716"> </a><div class="frame"><h4 class="EntityTitle"><a name="89802"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 3-2:&nbsp;&nbsp;Example - Driver Initialization for Non-Block Devices </font></a></h4><dl class="margin"><div class="Anchor"><a name="89868"> </a><img class="figure" border="0" src="images/c-iosysa2.gif"></div></dl></div></p></dl></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="89870">3.9.2  &nbsp;&nbsp;Devices</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="89871"> </a>Some drivers are capable of servicing many instances of a particular kind of device. For example, a single driver for a serial communications device can often handle many separate channels that differ only in a few parameters, such as device address.</p><dd><p class="Body"><a name="89886"> </a>In the VxWorks I/O system, devices are defined by a data structure called a <i class="term">device header</i> (<b class="symbol_UC">DEV_HDR</b>). This data structure contains the device name string and the driver number for the driver that services this device. The device headers for all the devices in the system are kept in a memory-resident linked list called the <i class="term">device list</i>. The device header is the initial part of a larger structure determined by the individual drivers. This larger structure, called a <i class="term">device descriptor</i>, contains additional device-specific data such as device addresses, buffers, and semaphores.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="89890">The Device List and Adding Devices</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="89891"> </a>Non-block devices are added to the I/O system dynamically by calling the internal I/O routine <b class="routine"><i class="routine">iosDevAdd</i></b><b>(</b>&nbsp;<b>)</b>. The arguments to <b class="routine"><i class="routine">iosDevAdd</i></b><b>(</b>&nbsp;<b>)</b> are the address of the device descriptor for the new device, the device's name, and the driver number of the driver that services the device. The device descriptor specified by the driver can contain any necessary device-dependent information, as long as it begins with a device header. The driver does not need to fill in the device header, only the device-dependent information. The <b class="routine"><i class="routine">iosDevAdd</i></b><b>(</b>&nbsp;<b>)</b> routine enters the specified device name and the driver number in the device header and adds it to the system device list.</p><dd><p class="Body"><a name="85215"> </a>To add a block device to the I/O system, call the device initialization routine for the file system required on that device (<b class="routine"><i class="routine">dosFsDevInit</i></b><b>(</b>&nbsp;<b>)</b>, <b class="routine"><i class="routine">rt11FsDevInit</i></b><b>(</b>&nbsp;<b>)</b>, or <b class="routine"><i class="routine">rawFsDevInit</i></b><b>(</b>&nbsp;<b>)</b>). The device initialization routine then calls <b class="routine"><i class="routine">iosDevAdd</i></b><b>(</b>&nbsp;<b>)</b> automatically.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85216">Example of Adding Devices</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85220"> </a>In <a href="c-iosys9.html#85305">Figure&nbsp;3-3</a>, the example driver's device creation routine <i class="textVariable">xx</i><b class="routine"><i class="routine">DevCreate</i></b><b>(</b>&nbsp;<b>)</b> adds devices to the I/O system by calling <b class="routine"><i class="routine">iosDevAdd</i></b><b>(</b>&nbsp;<b>)</b>.&nbsp;&nbsp;&nbsp;&nbsp;<div class="frame"><h4 class="EntityTitle"><a name="85305"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 3-3:&nbsp;&nbsp;Example - Addition of Devices to I/O System</font></a></h4><dl class="margin"><div class="Anchor"><a name="89980"> </a><img class="figure" border="0" src="images/c-iosysa3.gif"></div></dl></div></p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="85307">3.9.3  &nbsp;&nbsp;File Descriptors<i class="i"></i></a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85308"> </a>Several <i class="acronym_lc">fd</i>s can be open to a single device at one time. A device driver can maintain additional information associated with an <i class="acronym_lc">fd</i> beyond the I/O system's device information. In particular, devices on which multiple files can be open at one time have file-specific information (for example, file offset) associated with each <i class="acronym_lc">fd</i>. You can also have several <i class="acronym_lc">fd</i>s open to a non-block device, such as a <i class="acronym_lc">tty</i>; typically there is no additional information, and thus writing on any of the <i class="acronym_lc">fd</i>s produces identical results.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85310">The Fd Table</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85311"> </a>Files are opened with <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b> (or <b class="routine"><i class="routine">creat</i></b><b>(</b>&nbsp;<b>)</b>). The I/O system searches the device list for a device name that matches the file name (or an initial substring) specified by the caller. If a match is found, the I/O system uses the driver number contained in the corresponding device header to locate and call the driver's open routine in the driver table.</p><dd><p class="Body"><a name="85312"> </a>The I/O system must establish an association between the file descriptor used by the caller in subsequent I/O calls, and the driver that services it. Additionally, the driver must associate some data structure per descriptor. In the case of non-block devices, this is usually the device descriptor that was located by the I/O system. </p><dd><p class="Body"><a name="85314"> </a>The I/O system maintains these associations in a table called the <i class="term">fd table</i>. This table contains the driver number and an additional driver-determined 4-byte value. The driver value is the internal descriptor returned by the driver's open routine, and can be any nonnegative value the driver requires to identify the file. In subsequent calls to the driver's other I/O functions (<b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b>, <b class="routine"><i class="routine">write</i></b><b>(</b>&nbsp;<b>)</b>, <b class="routine"><i class="routine">ioctl</i></b><b>(</b>&nbsp;<b>)</b>, and <b class="routine"><i class="routine">close</i></b><b>(</b>&nbsp;<b>)</b>), this value is supplied to the driver in place of the <i class="acronym_lc">fd</i> in the application-level I/O call.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85316">Example of Opening a File</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85324"> </a>In <a href="c-iosys9.html#85443">Figure&nbsp;3-4</a> and <a href="c-iosys9.html#93441">Figure&nbsp;3-5</a>, a user calls <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b> to open the file <b class="file">/</b><i class="textVariable">xx</i><b class="file">0</b>. The I/O system takes the following series of actions:</p><dl class="margin"><dd><p class="ListV"><a name="85325"> </a>[1]    It searches the device list for a device name that matches the specified file name (or an initial substring). In this case, a complete device name matches.&nbsp;<div class="frame"><h4 class="EntityTitle"><a name="85443"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 3-4:&nbsp;&nbsp;Example: Call to I/O Routine <b class="routine"><i class="routine">open</i></b><b>(&nbsp;)</b> [<i class="i">Part 1</i>]</font></a></h4><dl class="margin"><div class="Anchor"><a name="85440"> </a><img class="figure" border="0" src="images/c-iosysa4.gif"></div></dl></div></p><dd><p class="ListV"><a name="85444"> </a>[2]    It reserves a slot in the <i class="acronym_lc">fd</i> table, which is used if the open is successful.<div class="frame"><h4 class="EntityTitle"><a name="93441"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 3-5:&nbsp;&nbsp;Example: Call to I/O Routine <b class="routine"><i class="routine">open</i></b><b>(&nbsp;)</b> [<i class="i">Part 2</i>] </font></a></h4><dl class="margin"><div class="Anchor"><a name="93559"> </a><img class="figure" border="0" src="images/c-iosysa5.gif"></div></dl></div></p><dd><p class="ListV"><a name="85445"> </a>[3]    It then looks up the address of the driver's open routine, <i class="textVariable">xx</i><b class="routine"><i class="routine">Open</i></b><b>(</b>&nbsp;<b>)</b>, and calls that routine. Note that the arguments to<i class="textVariable"> xx</i><b class="routine"><i class="routine">Open</i></b><b>(</b>&nbsp;<b>)</b> are transformed by the I/O system from the user's original arguments to <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b>. The first argument to <i class="textVariable">xx</i><b class="routine"><i class="routine">Open</i></b><b>(</b>&nbsp;<b>)</b> is a pointer to the device descriptor the I/O system located in the full file name search. The next parameter is the <i class="emphasis">remainder</i> of the file name specified by the user, after removing the initial substring that matched the device name. In this case, because the device name matched the entire file name, the remainder passed to the driver is a null string. The driver is free to interpret this remainder in any way it wants. In the case of block devices, this remainder is the name of a file on the device. In the case of non-block devices like this one, it is usually an error for the remainder to be anything <i class="emphasis">but</i> the null string. The last parameter is the file access flag, in this case <b class="symbol_UC">O_RDONLY</b>; that is, the file is opened for reading only. </p><dd><p class="ListV"><a name="85568"> </a>[4]    It executes <i class="textVariable">xx</i><b class="routine"><i class="routine">Open</i></b><b>(</b>&nbsp;<b>)</b>, which returns a value that subsequently identifies the newly opened file. In this case, the value is the pointer to the device descriptor. This value is supplied to the driver in subsequent I/O calls that refer to the file being opened. Note that if the driver returns only the device descriptor, the driver cannot distinguish multiple files opened to the same device. In the case of non-block device drivers, this is usually appropriate. </p><dd><p class="ListV"><a name="85569"> </a>[5]    The I/O system then enters the driver number and the value returned by <i class="textVariable">xx</i><b class="routine"><i class="routine">Open</i></b><b>(</b>&nbsp;<b>)</b> in the reserved slot in the <i class="acronym_lc">fd</i> table. Again, the value entered in the <i class="acronym_lc">fd</i> table has meaning only for the driver, and is arbitrary as far as the I/O system is concerned.</p><dd><p class="ListV"><a name="85571"> </a>[6]    Finally, it returns to the user the index of the slot in the <i class="acronym_lc">fd</i> table, in this case 3.</p></dl></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85573">Example of Reading Data from the File</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85578"> </a>In <a href="c-iosys9.html#85686">Figure&nbsp;3-6</a>, the user calls <b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b> to obtain input data from the file. The specified <i class="acronym_lc">fd</i> is the index into the <i class="acronym_lc">fd</i> table for this file. The I/O system uses the driver number contained in the table to locate the driver's read routine, <i class="textVariable">xx</i><b class="routine"><i class="routine">Read</i></b><b>(</b>&nbsp;<b>)</b>. The I/O system calls <i class="textVariable">xx</i><b class="routine"><i class="routine">Read</i></b><b>(</b>&nbsp;<b>)</b>, passing it the identifying value in the <i class="acronym_lc">fd</i> table that was returned by the driver's open routine,<i class="textVariable"> xx</i><b class="routine"><i class="routine">Open</i></b><b>(</b>&nbsp;<b>)</b>. Again, in this case the value is the pointer to the device descriptor. The driver's read routine then does whatever is necessary to read data from the device. <div class="frame"><h4 class="EntityTitle"><a name="85686"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 3-6:&nbsp;&nbsp;Example: Call to I/O Routine <b class="routine"><i class="routine">read</i></b><b>(&nbsp;)</b></font></a></h4><dl class="margin"><div class="Anchor"><a name="85682"> </a><img class="figure" border="0" src="images/c-iosysa6.gif"></div></dl></div></p><dd><p class="Body"><a name="85687"> </a>The process for user calls to <b class="routine"><i class="routine">write</i></b><b>(</b>&nbsp;<b>)</b> and <b class="routine"><i class="routine">ioctl</i></b><b>(</b>&nbsp;<b>)</b> follow the same procedure.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85689">Example of Closing a File</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85691"> </a>The user terminates the use of a file by calling <b class="routine"><i class="routine">close</i></b><b>(</b>&nbsp;<b>)</b>. As in the case of <b class="routine"><i class="routine">read</i></b><b>(</b>&nbsp;<b>)</b>, the I/O system uses the driver number contained in the <i class="acronym_lc">fd</i> table to locate the driver's close routine. In the example driver, no close routine is specified; thus no driver routines are called. Instead, the I/O system marks the slot in the <i class="acronym_lc">fd</i> table as being available. Any subsequent references to that <i class="acronym_lc">fd</i> cause an error. However, subsequent calls to <b class="routine"><i class="routine">open</i></b><b>(</b>&nbsp;<b>)</b> can reuse that slot. </p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85695">Implementing <b class="routine"><i class="routine">select</i></b><b>(&nbsp;)</b></a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85698"> </a>Supporting <b class="routine"><i class="routine">select</i></b><b>(</b>&nbsp;<b>)</b> in your driver allows tasks to wait for input from multiple devices or to specify a maximum time to wait for the device to become ready for I/O. Writing a driver that supports <b class="routine"><i class="routine">select</i></b><b>(</b>&nbsp;<b>)</b> is simple, because most of the functionality is provided in <b class="library">selectLib</b>. You might want your driver to support <b class="routine"><i class="routine">select</i></b><b>(</b>&nbsp;<b>)</b> if any of the following is appropriate for the device:</p></dl><dl class="margin">