kernel interfaces with dd.htm

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

<tt>splvm</tt>
</td>
<td align="left" valign="top">
Masks all virtual memory clock interrupts.
</td>
</tr>
<tr>
<td align="left" valign="top">
<tt>splx</tt>
</td>
<td align="left" valign="top">
Resets the CPU priority to the level specified by the argument.
</td>
</tr>
</tbody></table><p>
<a name="nx_id_833"></a>
The
<tt>spl</tt>
interfaces set the CPU priority to various interrupt levels.
The current CPU priority level determines which types of interrupts are
masked (disabled) and which are unmasked (enabled).
Historically, seven levels of interrupts were supported, with eight
different
<tt>spl</tt>
interfaces to handle the possible cases.
For example, calling
<tt>spl0</tt>
would unmask all interrupts and calling
<tt>spl7</tt>
would mask all interrupts.
Calling an
<tt>spl</tt>
interface between 0 and 7 would mask all interrupts at that level
and at all lower levels.
</p><p>
Specific interrupt levels were assigned for different device types.
For example, before handling a given interrupt, a device driver would set
the CPU priority level to mask all other interrupts of the same level or
lower.
This setting meant that the device driver could be interrupted only by interrupt
requests from devices of a higher priority.
</p><p>
Digital UNIX currently supports the naming of
<tt>spl</tt>
interfaces to indicate the associated device types.
Named
<tt>spl</tt>
interfaces make it easier to determine which interface you should use to
set the priority level for a given device type.
</p><p>
<br>
The following code fragment shows the use of
<tt>spl</tt>
interfaces as part of a disk
<tt>strategy</tt>
interface:
</p><p>
</p><pre><br>.<br>.<br>.<br>
int s;
<br>.<br>.<br>.<br>
s = splbio(); <a name="co_id_138_rtn_1"></a><a href="#co_id_138_1"><strong>[1]</strong></a>
<br>.<br>.<br>.<br>
[Code to deal with data that can be modified by the disk interrupt
code]
splx(s); <a name="co_id_138_rtn_2"></a><a href="#co_id_138_2"><strong>[2]</strong></a>
<br>.<br>.<br>.<br>
</pre>
<p>
</p><ol>
<p></p><li>
<a name="co_id_138_1"></a>
<a name="nx_id_834"></a>
<a name="nx_id_835"></a>
Calls the
<tt>splbio</tt>
interface to mask (disable) all disk interrupts.
This interface does not take an argument.
<a href="#co_id_138_rtn_1">[Return to example]</a>
<p></p></li><li>
<a name="co_id_138_2"></a>
Calls the
<tt>splx</tt>
interface to reset the CPU priority to the level specified by the
<tt><var>s</var></tt>
argument.
Note that the one argument associated with
<tt>splx</tt>
is a CPU priority level, which in the example is the value returned by
<tt>splbio</tt>.
(The
<tt>splx</tt>
interface is the only one of the
<tt>spl</tt>
interfaces that takes an argument.)
Upon successful completion, each
<tt>spl</tt>
interface returns an integer value that represents the CPU priority
level that existed before it was changed by a call to the specified
<tt>spl</tt>
interface.
<p>
The binding of any
<tt>spl</tt>
interface with a specific CPU priority level is highly machine dependent.
With the exceptions of the
<tt>splhigh</tt>
and
<tt>splnone</tt>
interfaces, knowledge of the explicit bindings is not required to create
new device drivers.
You always use
<tt>splhigh</tt>
to mask (disable) all interrupts and
<tt>splnone</tt>
to unmask (enable) all interrupts.
<a href="#co_id_138_rtn_2">[Return to example]</a>
</p></li></ol><p>
<a name="KernRelInter"></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="kernel%20interfaces%20with%20DD_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="kernel%20interfaces%20with%20DD_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#UsingKernRtnswithDrvs"><img src="kernel%20interfaces%20with%20DD_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#SetProcPriorityMask"><img src="kernel%20interfaces%20with%20DD_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#PrintTxttoConsandErrLog"><img src="kernel%20interfaces%20with%20DD_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/drivertut26.html"><img src="kernel%20interfaces%20with%20DD_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="kernel%20interfaces%20with%20DD_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="kernel%20interfaces%20with%20DD_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h2>
18.4&nbsp;&nbsp;&nbsp;&nbsp;Kernel-Related Interfaces
</h2>
<p>
<a name="nx_id_836"></a>
The kernel-related interfaces allow device drivers to:
</p><ul>
<p></p><li>
Print text to the console and error logger
<p></p></li><li>
Put a calling process to sleep
<p></p></li><li>
Wake up a sleeping process
<p></p></li><li>
Initialize a callout queue element
<p></p></li><li>
Remove the scheduled interface from the callout queues
</li></ul><p>
The following sections describe the kernel interfaces that perform these tasks.
<a name="PrintTxttoConsandErrLog"></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="kernel%20interfaces%20with%20DD_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="kernel%20interfaces%20with%20DD_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#UsingKernRtnswithDrvs"><img src="kernel%20interfaces%20with%20DD_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#KernRelInter"><img src="kernel%20interfaces%20with%20DD_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#PutCallProctoSleep"><img src="kernel%20interfaces%20with%20DD_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/drivertut26.html"><img src="kernel%20interfaces%20with%20DD_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="kernel%20interfaces%20with%20DD_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="kernel%20interfaces%20with%20DD_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
18.4.1&nbsp;&nbsp;&nbsp;&nbsp;Printing Text to the Console and Error Logger
</h3>
<p>
To print text to the console terminal and the error logger, call the
<tt>printf</tt>
interface.
The
kernel
<tt>printf</tt>
interface is a scaled-down version of the C library
<tt>printf</tt>
interface.
The
<tt>printf</tt>
interface prints diagnostic information directly on the console terminal and
writes ASCII text to the error logger.
Because
<tt>printf</tt>
is not interrupt driven, all system activities are suspended when you
call it.
Only a limited number of characters (currently 128)
can be sent to the console display during each call to any section of a
driver.
The reason is that the characters are buffered until the driver
returns to the kernel, at which time they are actually sent to the
console display.
If more than 128 characters are sent to the console display,
the storage pointer may wrap around, discarding all previous characters;
or it may discard all characters following the first 128.
</p><p>
If you need to see the results on the console terminal,
limit the message size to the maximum of 128 whenever you send a message
from within the driver.
However,
<tt>printf</tt>
also stores the messages in an error log file.
You can use the
<tt>uerf</tt>
command to view the text of this error log file.
See the reference page for this command.
The messages are easier to read if you use
<tt>uerf</tt>
with the
<tt>-o</tt>
<tt>terse</tt>
option.
</p><p>
The following code fragment shows a call to this interface:
</p><p>
</p><pre><br>.<br>.<br>.<br>
#ifdef CB_DEBUG
printf("CBprobe @ %8x, vbaddr = %8x, ctlr = %8x\n",cbprobe,vbaddr,ctlr); <a name="co_id_139_rtn_1"></a><a href="#co_id_139_1"><strong>[1]</strong></a>
#endif /*CB_DEBUG*/
<br>.<br>.<br>.<br>
</pre>
<p>
</p><ol>
<p></p><li>
<a name="co_id_139_1"></a>
<a name="nx_id_837"></a>
Shows a typical use for the
<tt>printf</tt>
interface in the debugging of device drivers.
<p>
The example shows that
<tt>printf</tt>
takes two arguments:
</p><ul>
<p></p><li>
The first argument specifies
a pointer to a string that contains two types of objects.
One object is ordinary characters such as ``hello, world'', which
are copied to the output stream.
The other object is a conversion specification such as %d,
%o, or %x.
<p></p></li><li>
The second argument specifies the argument list.
In this example, the argument list consists of the arguments
<tt><var>cbprobe</var></tt>,
<tt><var>vbaddr</var></tt>,
and
<tt><var>ctlr</var></tt>.
</li></ul><p>
</p><p>
Digital UNIX also supports the
<tt>uprintf</tt>
interface.
The
<tt>uprintf</tt>
interface prints to the current user's terminal.
Interrupt service interfaces should never call
<tt>uprintf</tt>.
It does not perform any space checking, so you should not use this
interface to print verbose messages.
The
<tt>uprintf</tt>
interface does not log messages to the error logger.
<a href="#co_id_139_rtn_1">[Return to example]</a>
</p></li></ol><p>
<a name="PutCallProctoSleep"></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="kernel%20interfaces%20with%20DD_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="kernel%20interfaces%20with%20DD_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#UsingKernRtnswithDrvs"><img src="kernel%20interfaces%20with%20DD_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#PrintTxttoConsandErrLog"><img src="kernel%20interfaces%20with%20DD_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#WakeSleepProc"><img src="kernel%20interfaces%20with%20DD_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/drivertut26.html"><img src="kernel%20interfaces%20with%20DD_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="kernel%20interfaces%20with%20DD_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="kernel%20interfaces%20with%20DD_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
18.4.2&nbsp;&nbsp;&nbsp;&nbsp;Putting a Calling Process to Sleep
</h3>
<p>
To put a calling process to sleep, call the
<tt>sleep</tt>
interface.
The
<tt>sleep</tt>
and
<tt>wakeup</tt>
interfaces block and then wake up a process.
Generally, device drivers call these interfaces to wait for the transfer
to complete an interrupt from the device.
That is, the
<tt>write</tt>
interface of the device driver sleeps on the address of a known location,
and the device's interrupt service interface wakes the process when the
device interrupts.
It is the responsibility of the wakened process to check if the
condition for which it was sleeping has been removed.
The following code fragment shows a call to this interface:
</p><p>
</p><pre><br>.<br>.<br>.<br>
sleep(&amp;ctlr-&gt;bus_name, PCATCH); <a name="co_id_140_rtn_1"></a><a href="#co_id_140_1"><strong>[1]</strong></a>
<br>.<br>.<br>.<br>
</pre>
<p>
</p><ol>
<p></p><li>
<a name="co_id_140_1"></a>
<a name="nx_id_838"></a>
Sho