Annotation of htdocs/docs/kernel/programming.html, revision 1.1
1.1 ! dsieger 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
! 2: <html>
! 3: <head>
! 4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
! 5: <meta name="generator" content="Website XSL Stylesheet V2.6.0">
! 6: <link rel="home" href="../../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
! 7: <link rel="up" href="../../docs/kernel/." title="NetBSD Documentation: Kernel">
! 8: <link rel="previous" href="../../docs/kernel/pseudo/." title="NetBSD Documentation: Writing a pseudo device">
! 9: <link rel="next" href="../../docs/kernel/uvm.html" title="NetBSD Documentation: UVM, the new Virtual Memory system">
! 10: <link rel="first" href="../../docs/kernel/lazyfpu.html" title="NetBSD Documentation: How lazy FPU context switch works">
! 11: <link rel="last" href="../../docs/kernel/elf-notes.html" title="NetBSD Documentation: Vendor-specific ELF Note Elements">
! 12: <link rel="stylesheet" href="/NetBSD.css" type="text/css">
! 13:
! 14:
! 15:
! 16: <title>NetBSD Documentation: Kernel Programming FAQ</title>
! 17: </head>
! 18: <body class="website"><div class="webpage">
! 19: <a name="docs-kernel-programming"></a><h1>NetBSD Documentation: Kernel Programming FAQ</h1>
! 20: <h3 class="title"><a name="misc">Misc</a></h3>
! 21: <ul>
! 22: <li><a href="#knf">What is KNF</a></li>
! 23: <li><a href="#packed-attribute">Using the `packed' attribute</a></li>
! 24: <li><a href="#printf">Using printf() for debugging</a></li>
! 25: <li><a href="#forcing-ddb">Forcing code to enter DDB</a></li>
! 26: <li><a href="#adding_a_new_driver">Adding a new driver to the kernel</a></li>
! 27: <li><a href="#autoconf">How does all this autoconf stuff work?</a></li>
! 28: <li><a href="#adding_a_system_call">Adding a system call</a></li>
! 29: <li><a href="#adding_a_sysctl">Adding a sysctl</a></li>
! 30: <li><a href="#mmap_in_pseudo-device">How to implement mmap(2) in a pseudo-device</a></li>
! 31: <li><a href="#accessing_a_kernel_structure_from_userland">Accessing a kernel structure from userland</a></li>
! 32: <li><a href="#sample_driver">Is there a simple PCI driver I can use as an example?</a></li>
! 33: <li><a href="#other-related-links">Other related links</a></li>
! 34: </ul>
! 35: <hr>
! 36: <h3 class="title">Misc</h3>
! 37: <h4 class="title">
! 38: <a name="knf"></a>What is KNF (<a href="#misc">top</a>)
! 39: </h4>
! 40:
! 41: <p>KNF stands for "Kernel Normal Form" - it's a C coding
! 42: style documented in
! 43: <code class="filename">/usr/share/misc/style</code>, which is
! 44: included in the source tree as <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/share/misc/style?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/share/misc/style</code></a>.</p>
! 45:
! 46: <h4 class="title">
! 47: <a name="packed-attribute"></a>Using the `packed' attribute (<a href="#misc">top</a>)
! 48: </h4>
! 49:
! 50: <p>Always use the <code class="code">`packed'</code> attribute in
! 51: structures which describe wire protocol data formats.</p>
! 52:
! 53: <h4 class="title">
! 54: <a name="printf"></a>Using <code class="code">printf()</code> for debugging (<a href="#misc">top</a>)
! 55: </h4>
! 56:
! 57: <p>Probably the simplest way of generating debugging
! 58: information from a kernel driver is to use
! 59: <code class="code">printf()</code>. The kernel printf will send output to
! 60: the console, so beware of generating too much output and
! 61: making the system unusable.</p>
! 62:
! 63: <h4 class="title">
! 64: <a name="forcing-ddb"></a>Forcing code to enter DDB (<a href="#misc">top</a>)
! 65: </h4>
! 66:
! 67: <p>Ensure your kernel config file contains
! 68: '<code class="code">options DDB</code>', the file has
! 69: '<code class="code">#include "opt_ddb.h"</code>', then use
! 70: '<code class="code">Debugger()</code>'.</p>
! 71:
! 72: <h4 class="title">
! 73: <a name="adding_a_new_driver"></a>Adding a new driver to the kernel (<a href="#misc">top</a>)
! 74: </h4>
! 75:
! 76: <p>Every driver needs at least:
! 77: </p>
! 78: <div class="itemizedlist"><ul type="disc">
! 79: <li>
! 80: <code class="code"><span class="emphasis"><em>xxx</em></span>probe()</code> (
! 81: during which NetBSD will attempt to determine if the
! 82: device is present)</li>
! 83: <li>
! 84: <code class="code"><span class="emphasis"><em>xxx</em></span>attach()</code>
! 85: routine which will configure and attach the
! 86: device.</li>
! 87: </ul></div>
! 88: <p>
! 89: </p>
! 90:
! 91: <p>Once probe and attach routines have been written, add
! 92: an entry to
! 93: <code class="filename">/usr/src/sys/arch/<your-arch>/<your-arch>/conf.c</code>.</p>
! 94:
! 95: <p>There are two tables:
! 96: </p>
! 97: <div class="itemizedlist"><ul type="disc">
! 98: <li>
! 99: <code class="code">cdevsw</code> for character devices.</li>
! 100: <li>
! 101: <code class="code">bdevsw</code> for block devices (for those
! 102: that also perform "block" I/O and use a strategy
! 103: routine).</li>
! 104: </ul></div>
! 105:
! 106: <p>Most entries will be of the form
! 107: <code class="code">cdev_<span class="emphasis"><em>xxx</em></span>_init()</code>, which
! 108: is a macro handling prototyping of the standard Unix
! 109: device switch routines.</p>
! 110:
! 111: <p>The probe/attach routines are called at boot time. The
! 112: <code class="code">open()</code>, <code class="code">close()</code>,
! 113: <code class="code">read()</code>, and <code class="code">write()</code> routines are
! 114: called when you open up the device special file who's major
! 115: number corresponds to the index into that table. For
! 116: example, if you open up a device who's major number is 18,
! 117: the "open" routine for device number 18 in
! 118: <code class="code">cdevsw[]/bdevsw</code> will be called.</p>
! 119:
! 120: <p>Most drivers are split between bus specific attach code, and
! 121: a machine independent core. As an example, the driver for
! 122: the PCI lance ethernet chip has entries in the following files:
! 123:
! 124: </p>
! 125: <div class="itemizedlist"><ul type="disc">
! 126: <li>
! 127: <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/dev/pci/files.pci?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/sys/dev/pci/files.pci</code></a>
! 128: - attach information (look for 'le at pci').</li>
! 129: <li>
! 130: <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/dev/pci/if_le_pci.c?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/sys/dev/pci/if_le_pci.c</code></a>
! 131: - PCI bus attach code for the driver.</li>
! 132: </ul></div>
! 133: <p>
! 134: </p>
! 135:
! 136: <p>
! 137: </p>
! 138: <div class="itemizedlist"><ul type="disc">
! 139: <li>
! 140: <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/conf/files?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/sys/conf/files</code></a>
! 141: - MI core attach information (look for 'le:').</li>
! 142: <li>
! 143: <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/dev/ic/am7990.c?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/sys/dev/ic/am7990.c</code></a>
! 144: - MI driver 24bit access code.</li>
! 145: <li>
! 146: <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/dev/ic/am79900.c?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/sys/dev/ic/am79900.c</code></a>
! 147: - MI driver 32bit access code.</li>
! 148: <li>
! 149: <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/sys/dev/ic/lance.c?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/sys/dev/ic/lance.c</code></a>
! 150: - MI core driver code.</li>
! 151: </ul></div>
! 152: <p>
! 153: </p>
! 154:
! 155: <p>See also <a href="#autoconf" target="_top">the autoconf explanation</a>.</p>
! 156:
! 157: <h4 class="title">
! 158: <a name="autoconf"></a>How does all this autoconf stuff work? (<a href="#misc">top</a>)
! 159: </h4>
! 160:
! 161: <p>The autoconf machinery is quite simple once you figure
! 162: out the way it works. If you want to ignore the exact
! 163: details of how the device probe tree is built and walked
! 164: on runtime, the bits needed for each individual
! 165: “<span class="quote">leaf</span>” driver are like this:
! 166:
! 167: </p>
! 168: <div class="orderedlist"><ol type="1">
! 169: <li>each driver specifies a structure holding
! 170: three things - size of its private structure, probe
! 171: function and attach function; this is compiled in and
! 172: used in runtime - example:
! 173: <pre class="programlisting">
! 174: struct cfattach foo_baz_ca = {
! 175: sizeof(struct foo_baz_softc), foo_baz_match, foo_baz_attach
! 176: };</pre>
! 177: </li>
! 178: <li>on kernel startup, once the time comes to
! 179: attach the device, autoconf code calls device's
! 180: probe routine and passes it pointer to parent
! 181: (<code class="code">struct device *parent</code>), pointer
! 182: to attach tag structure (<code class="code">void *aux</code>),
! 183: and appropriate autoconf node (<code class="code">struct cfdata
! 184: *cf</code>). The driver is expected to find out if
! 185: it's where it's supposed to be (commonly, the location
! 186: and configuration information is passed by the attach
! 187: tag). If yes, the probe routine should return 1. If
! 188: device is not there, probe routine has to return 0.
! 189: <span class="bold"><strong>NO STATE SHOULD BE KEPT</strong></span>
! 190: in either case.</li>
! 191: <li>if probe returned success, autoconf allocates
! 192: chunk of memory sized as specified in device's *_ca
! 193: and calls its attach routine, passing it pointer to
! 194: parent (<code class="code">struct device *parent</code>),
! 195: pointer to the freshly allocated memory
! 196: (<code class="code">struct device *self</code>) and the attach tag
! 197: (<code class="code">void *aux</code>). Driver is expected to find
! 198: out exact ports and memory, allocate resources and
! 199: initialize its internal structure
! 200: accordingly. Preferably, all driver instance specific
! 201: information should be kept in the allocated
! 202: memory.</li>
! 203: </ol></div>
! 204: <p>
! 205: </p>
! 206:
! 207: <p>Example: Let's have a PCI ethernet device 'baz',
! 208: kernel config chunk looks like this:
! 209: </p>
! 210: <pre class="programlisting">
! 211: pci* at mainbus?
! 212: baz* at pci? dev ? function ?</pre>
! 213: <p>
! 214:
! 215: At runtime, autoconf iterates over all physical devices
! 216: present on machine's PCI bus. For each physical device, it
! 217: iterates over all devices registered in kernel to be on
! 218: pci bus, and calls drivers' probe routine. If any probe
! 219: routine claims the device by returning 1, autoconf stops
! 220: iterating and does the job described under 3). Once the
! 221: attach function returns, autoconf continues with next
! 222: physical device.</p>
! 223:
! 224: <p>See also <a href="#adding_a_new_driver" target="_top">Adding a new driver</a>.</p>
! 225:
! 226: <h4 class="title">
! 227: <a name="adding_a_system_call"></a>Adding a system call (<a href="#misc">top</a>)
! 228: </h4>
! 229:
! 230: <p>Add an entry in <code class="code">syscalls.master</code>, and add
! 231: the syscall stub to the appropriate place in
! 232: <code class="code"><a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/lib/libc/sys/Makefile.inc?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/lib/libc/sys/Makefile.inc</code></a></code>.</p>
! 233: <p>See the <a href="../internals/en/chap-processes.html#syscall_howto" target="_top">
! 234: HOWTO</a> and related documentation in the <a href="../internals/en/" target="_top">
! 235: NetBSD Internals Guide</a> for more information.
! 236: </p>
! 237:
! 238: <h4 class="title">
! 239: <a name="adding_a_sysctl"></a>Adding a sysctl (<a href="#misc">top</a>)
! 240: </h4>
! 241:
! 242: <p>See a <a href="http://mail-index.NetBSD.org/tech-kern/2001/06/24/0000.html" target="_top">posting</a>
! 243: answering this question on <a href="http://mail-index.NetBSD.org/tech-kern/" target="_top">tech-kern</a>.</p>
! 244:
! 245: <p>Note that NetBSD 1.6 and up has a special
! 246: “<span class="quote">vendor</span>” sysctl category that is reserved for vendor
! 247: specific entries. See <a href="http://netbsd.gw.com/cgi-bin/man-cgi?sysctl+8+NetBSD-current">sysctl(8)</a> for more
! 248: information.</p>
! 249:
! 250: <h4 class="title">
! 251: <a name="mmap_in_pseudo-device"></a>How to implement <a href="http://netbsd.gw.com/cgi-bin/man-cgi?mmap+2+NetBSD-current">mmap(2)</a> in a pseudo-device (<a href="#misc">top</a>)
! 252: </h4>
! 253:
! 254: <p>Your device is most likely a character device, so
! 255: you will be using the device pager (the VM system hides
! 256: all of this from you, don't worry).</p>
! 257:
! 258: <p>The first thing you need to do is pick some
! 259: arbitrary offsets for your mmap interface. Something
! 260: like "mmap offset 0-M gives object A, N-O gives object
! 261: B", etc.</p>
! 262:
! 263: <p>After that, your mmap routine would look something
! 264: like this:
! 265: </p>
! 266: <pre class="programlisting">
! 267: int
! 268: foommap(dev_t dev, int off, int prot)
! 269: {
! 270:
! 271: if (off & PAGE_MASK)
! 272: panic("foommap");
! 273:
! 274: if ((u_int)off >= FOO_REGION1_MMAP_OFFSET &&
! 275: (u_int)off < (FOO_REGION1_MMAP_OFFSET + FOO_REGION1_SIZE))
! 276: return (atop(FOO_REGION1_ADDR + ((u_int)off -
! 277: FOO_REGION1_MMAP_OFFSET)));
! 278:
! 279: if ((u_int)off >= FOO_REGION2_MMAP_OFFSET &&
! 280: (u_int)off < (FOO_REGION2_MMAP_OFFSET + FOO_REGION2_SIZE))
! 281: return (atop(FOO_REGION1_ADDR + ((u_int)off -
! 282: FOO_REGION2_MMAP_OFFSET)));
! 283:
! 284: /* Page not found. */
! 285: return (-1);
! 286: }</pre>
! 287:
! 288: <p>Now, this is slightly more complicated by the fact
! 289: that you are going to be mmap'ing what are simply
! 290: kernel memory objects (it is a pseudo-device after
! 291: all).</p>
! 292:
! 293: <p>In order to make this work, you're going to want
! 294: to make sure you allocate the memory objects to be
! 295: mmap'd on page-aligned boundaries. If you are
! 296: allocating something >= <code class="code">PAGE_SIZE</code> in
! 297: size, this is guaranteed. Otherwise, you are going to
! 298: have to use <code class="code">uvm_km_alloc()</code>, and round
! 299: your allocation size up to page size.</p>
! 300:
! 301: <p>Then it would look a bit more like this:
! 302: </p>
! 303: <pre class="programlisting">
! 304: int
! 305: foommap(dev_t dev, int off, int prot)
! 306: {
! 307: paddr_t pa;
! 308:
! 309: if (off & PAGE_MASK)
! 310: panic("foommap: offset not page aligned");
! 311:
! 312: if ((u_int)off >= FOO_REGION1_MMAP_OFFSET &&
! 313: (u_int)off < (FOO_REGION1_MMAP_OFFSET + FOO_REGION1_SIZE)) {
! 314: if ((vaddr_t)foo_object1 & PAGE_MASK)
! 315: panic("foommap: foo_object1 not page aligned");
! 316: if (pmap_extract(pmap_kernel(), foo_object1 +
! 317: (u_int)off - FOO_REGION1_MMAP_OFFSET, &pa) == FALSE)
! 318: panic("foommap: foo_object1 page not mapped");
! 319: return (atop(pa));
! 320: }
! 321:
! 322: if ((u_int)off >= FOO_REGION2_MMAP_OFFSET &&
! 323: (u_int)off < (FOO_REGION2_MMAP_OFFSET + FOO_REGION2_SIZE)) {
! 324: if ((vaddr_t)foo_object2 & PAGE_MASK)
! 325: panic("foommap: foo_object2 not page aligned");
! 326: if (pmap_extract(pmap_kernel(), foo_object2 +
! 327: (u_int)off - FOO_REGION2_MMAP_OFFSET, &pa) == FALSE)
! 328: panic("foommap: foo_object2 page not mapped");
! 329: return (atop(pa));
! 330: }
! 331:
! 332: /* Page not found. */
! 333: return (-1);
! 334: }</pre>
! 335:
! 336: <h4 class="title">
! 337: <a name="accessing_a_kernel_structure_from_userland"></a>Accessing a kernel structure from userland (<a href="#misc">top</a>)
! 338: </h4>
! 339:
! 340: <p>The canonical example for this is: <code class="code">
! 341: <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/usr.bin/vmstat/dkstats.c?rev=HEAD&content-type=text/x-cvsweb-markup" target="_top"><code class="filename">src/usr.bin/vmstat/dkstats.c</code></a></code>
! 342: , which reads disk statistics.</p>
! 343:
! 344: <h4 class="title">
! 345: <a name="sample_driver"></a>Is there a simple PCI driver I can use as an example? (<a href="#misc">top</a>)
! 346: </h4>
! 347: <p>You can look at
! 348: <code class="filename">sys/dev/pci/puc.c</code>, which is one of
! 349: the simplest drivers. PUCs are devices with one or more
! 350: serial or parallel ports on it, usually using standard
! 351: chips (e.g. 16550 UART for serial). This driver just
! 352: locates the I/O addresses of the registers of the serial or
! 353: parallel controller and passes it to the serial or
! 354: parallel driver.</p>
! 355:
! 356: <h4 class="title">
! 357: <a name="other-related-links"></a>Other related links (<a href="#misc">top</a>)
! 358: </h4>
! 359:
! 360: <div class="itemizedlist"><ul type="disc">
! 361: <li>
! 362: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?driver+9+NetBSD-current">driver(9)</a> - NetBSD autoconfiguration
! 363: interface utilised by device drivers</li>
! 364: <li>
! 365: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?autoconf+9+NetBSD-current">autoconf(9)</a> - General description on the
! 366: NetBSD autoconfiguration framework</li>
! 367: <li>
! 368: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?config+9+NetBSD-current">config(9)</a> - The autoconfiguration
! 369: framework ``device definition'' language</li>
! 370: <li>
! 371: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?bus_dma+9+NetBSD-current">bus_dma(9)</a> - NetBSD's bus and machine
! 372: independent DMA framework, described in its own <a href="bus_dma.ps" target="_top">paper</a> (120k, postscript)</li>
! 373: <li>
! 374: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?bus_space+9+NetBSD-current">bus_space(9)</a> - NetBSD's bus space
! 375: manipulation interface</li>
! 376: <li>
! 377: <a href="scsidma.html" target="_top">How SCSI DMA
! 378: works</a> - by Tohru Nishimura</li>
! 379: <li>
! 380: <a href="lazyfpu.html" target="_top">How lazy FPU context
! 381: switch works</a> - by Tohru Nishimura</li>
! 382: <li><a href="converting-ethernet-drivers.html" target="_top">Converting ancient BSD Ethernet drivers to NetBSD-1.2D and later</a></li>
! 383: <li><a href="porting-freebsd-net.html" target="_top">Notes on porting FreeBSD network drivers to NetBSD</a></li>
! 384: </ul></div>
! 385: <hr>Back to <em><a href="./">NetBSD Documentation: Kernel</a></em><div class="navfoot">
! 386: <hr>
! 387: <table border="0" summary="Footer navigation"><tr>
! 388: <td class="foothome"><span class="foothome"><a href="../../."><img src="/images/NetBSD-flag.png" alt="[NetBSD flag]" border="0" width="90" height="90"></a></span></td>
! 389: <td class="foothome">
! 390: <span class="foothome"><a href="../../.">Home page</a></span><br>
! 391: </td>
! 392: </tr></table>
! 393: <hr>
! 394: </div>
! 395: <p></p>
! 396: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">(contact us)</a></span>
! 397:
! 398:
! 399: <span class="foottag">Generated from <em>%NetBSD: programming.xml,v 1.8 2006/11/20 22:40:55 kano Exp %</em></span><br><span class="footcopy"><a href="/Misc/disclaimer.html"><span class="copyright">Copyright © 1994-2007 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
! 400: Foundation, Inc.</a></span>
! 401: </div></body>
! 402: </html>
CVSweb <webmaster@jp.NetBSD.org>