kernel interfaces with dd.htm

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

<p></p><li>
The first argument is a pointer to a byte string (array of characters).
In the example, this array is the
<tt>modulename</tt>
member of the
<tt>tc_slot</tt>
structure associated with this bus.
<p></p></li><li>
The second argument is a pointer to a buffer that is at least the size
specified in the third argument.
In the example, this buffer is represented by the pointer to the
<tt><var>cp</var></tt>
variable.
<p></p></li><li>
The third argument is the number of bytes to be copied.
In the example, the number of bytes is contained in the constant
<tt>TC_ROMNAMLEN</tt>.
</li></ul><p>
</p><p>
<br>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut25.html#figResultsbcopy">Figure 18-6</a>
shows how
<tt>bcopy</tt>
copies a series of bytes by using a sample value in the code fragment.
As the figure shows,
<tt>bcopy</tt>
copies the characters
<tt>CB</tt>
to the buffer
<tt><var>cp</var></tt>.
No check is made for null bytes.
The copy is nondestructive; that is, the address ranges of
the first two arguments can overlap.
<a href="#co_id_132_rtn_3">[Return to example]</a>
</p></li></ol><p>
</p><p>
<a name="figResultsbcopy"></a>
</p><h3>Figure 18-6: Results of the bcopy Interface</h3>
<p><img src="kernel%20interfaces%20with%20DD_files/zk-0627U.gif"></p><p>
<a name="nx_id_819"></a>
<a name="ZeroingBlkofMem"></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="#CopyByteSpecLimit"><img src="kernel%20interfaces%20with%20DD_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#CopyDataUsertoKern"><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.2.2&nbsp;&nbsp;&nbsp;&nbsp;Zeroing a Block of Memory
</h3>
<p>
<a name="nx_id_820"></a>
To zero a block of memory, call the
<tt>bzero</tt>
or
<tt>blkclr</tt>
interface.
The following code fragment shows a call to
<tt>bzero</tt>.
(The
<tt>blkclr</tt>
interface has the same arguments.)
</p><p>
</p><pre><br>.<br>.<br>.<br>
struct bus *new_bus;
<br>.<br>.<br>.<br>
bzero(new_bus, sizeof(struct bus)); <a name="co_id_133_rtn_1"></a><a href="#co_id_133_1"><strong>[1]</strong></a>
<br>.<br>.<br>.<br>
</pre>
<p>
</p><ol>
<p></p><li>
<a name="co_id_133_1"></a>
<a name="nx_id_821"></a>
Shows that the
<tt>bzero</tt>
interface takes two arguments:
<ul>
<p></p><li>
The first argument is a pointer to a string whose size is at least the
size specified in the second argument.
In the example, the first argument is a pointer to a
<tt>bus</tt>
structure.
<br>
<p></p></li><li>
The second argument is the number of bytes to be zeroed.
In the example, this size is expressed through the use of the
<tt>sizeof</tt>
operator, which
returns the size of a
<tt>bus</tt>
structure.
</li></ul><p>
</p><p>
In the example,
<tt>bzero</tt>
zeros the number of bytes associated with the size of the
<tt>bus</tt>
structure, starting at the address specified by
<tt><var>new_bus</var></tt>.
</p><p>
The
<tt>blkclr</tt>
interface performs the equivalent task.
<a href="#co_id_133_rtn_1">[Return to example]</a>
</p></li></ol><p>
<a name="CopyDataUsertoKern"></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="#ZeroingBlkofMem"><img src="kernel%20interfaces%20with%20DD_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#copydatakern_touser"><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.2.3&nbsp;&nbsp;&nbsp;&nbsp;Copying Data from User Address Space to Kernel Address Space
</h3>
<p>
<a name="nx_id_822"></a>
To copy data from the unprotected user address space to the protected
kernel address space, call the
<tt>copyin</tt>
interface.
The following code fragment shows a call to
<tt>copyin</tt>:
</p><p>
</p><pre><br>.<br>.<br>.<br>
register struct buf *bp;
int err;
caddr_t buff_addr;
caddr_t kern_addr;
<br>.<br>.<br>.<br>
if (err = copyin(buff_addr,kern_addr,bp-&gt;b_resid)) { <a name="co_id_134_rtn_1"></a><a href="#co_id_134_1"><strong>[1]</strong></a>
<br>.<br>.<br>.<br>
</pre>
<p>
</p><ol>
<p></p><li>
<a name="co_id_134_1"></a>
<a name="nx_id_823"></a>
Shows that the
<tt>copyin</tt>
interface takes three arguments:
<ul>
<p></p><li>
The first argument specifies
the address in user space of the data to be copied.
In the example, this address is the user buffer's address.
<p></p></li><li>
The second argument specifies
the address in kernel space to copy the data to.
In the example, this address is the address of the kernel buffer.
<p></p></li><li>
The third argument specifies the number of bytes to copy.
In the example, the number of bytes is contained in the
<tt>b_resid</tt>
member of the pointer to the
<tt>buf</tt>
structure.
</li></ul><p>
<a name="nx_id_824"></a>
</p><p>
The code fragment sets up a condition statement that performs some tasks
based on whether
<tt>copyin</tt>
executes successfully.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut25.html#figResultscopyin">Figure 18-7</a>
shows how
<tt>copyin</tt>
copies data from user address space to kernel address space by using sample
data.
</p><p>
As the figure shows,
<tt>copyin</tt>
copies the data from the unprotected user address space,
starting at the address specified by
<tt><var>buff_addr</var></tt>
to the protected kernel address space specified by
<tt><var>kern_addr</var></tt>.
The number of bytes is indicated by the
<tt>b_resid</tt>
member.
The figure also shows that
<tt>copyin</tt>
returns the value zero (0) upon successful completion.
<br>
If the address in user address space could not be accessed,
<tt>copyin</tt>
returns the error
<tt>EFAULT</tt>.
<a href="#co_id_134_rtn_1">[Return to example]</a>
</p></li></ol><p>
<a name="figResultscopyin"></a>
</p><h3>Figure 18-7: Results of the copyin Interface</h3>
<p><img src="kernel%20interfaces%20with%20DD_files/zk-0628U.gif"></p><p>
<a name="nx_id_825"></a>
<a name="copydatakern_touser"></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="#CopyDataUsertoKern"><img src="kernel%20interfaces%20with%20DD_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#MoveDataBetwUserandSysSpace"><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.2.4&nbsp;&nbsp;&nbsp;&nbsp;Copying Data from Kernel Address Space to User Address Space
</h3>
<p>
<a name="nx_id_826"></a>
To copy data from the protected kernel address space to the unprotected
user address space, call the
<tt>copyout</tt>
interface.
The following code fragment shows a call to
<tt>copyout</tt>:
</p><p>
</p><pre><br>.<br>.<br>.<br>
register struct buf *bp;
int err;
caddr_t buff_addr;
caddr_t kern_addr;
<br>.<br>.<br>.<br>
if (err = copyout(kern_addr,buff_addr,bp-&gt;b_resid)) { <a name="co_id_135_rtn_1"></a><a href="#co_id_135_1"><strong>[1]</strong></a>
<br>.<br>.<br>.<br>
</pre>
<p>
<br>
</p><ol>
<p></p><li>
<a name="co_id_135_1"></a>
<a name="nx_id_827"></a>
Shows that the
<tt>copyout</tt>
interface takes three arguments:
<ul>
<p></p><li>
The first argument specifies
the address in kernel space of the data to be copied.
In the example, this address is the kernel buffer's address,
which is stored in the
<tt><var>kern_addr</var></tt>
argument.
<p></p></li><li>
The second argument specifies
the address in user space to copy the data to.
In the example, this address is the user buffer's virtual address, which
is stored in the
<tt><var>buff_addr</var></tt>
argument.
<p></p></li><li>
The third argument specifies the number of bytes to copy.
In the example, the number of bytes is contained in the
<tt>b_resid</tt>
member of the pointer to the
<tt>buf</tt>
structure.
</li></ul><p>
</p><p>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut25.html#figResultscopyout">Figure 18-8</a>
shows the results of
<tt>copyout</tt>,
based on the code fragment.
As the figure shows,
<tt>copyout</tt>
copies the data from the protected kernel address space,
starting at the address specified by
<tt><var>kern_addr</var></tt>
to the unprotected user address space specified by
<tt><var>buff_addr</var></tt>.
The number of bytes is indicated by the
<tt>b_resid</tt>
member.
The figure also shows that
<tt>copyout</tt>
returns the value zero (0) upon successful completion.
If the address in kernel address space could not be accessed or if the
number of bytes to copy is invalid,
<tt>copyout</tt>
returns the error
<tt>EFAULT</tt>.
<a href="#co_id_135_rtn_1">[Return to example]</a>
</p></li></ol><p>
</p><p>
<a name="figResultscopyout"></a>
</p><h3>Figure 18-8: Results of the copyout Interface</h3>
<p><img src="kernel%20interfaces%20with%20DD_files/zk-0629U.gif"></p><p>
<a name="nx_id_828"></a>
<a name="MoveDataBetwUserandSysSpace"></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>