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&amp;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/&lt;your-arch&gt;/&lt;your-arch&gt;/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&amp;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&amp;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&amp;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&amp;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&amp;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&amp;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:          &#8220;<span class="quote">leaf</span>&#8221; 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&amp;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:          &#8220;<span class="quote">vendor</span>&#8221; 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 &amp; PAGE_MASK)
        !           272:                 panic("foommap");
        !           273: 
        !           274:         if ((u_int)off &gt;= FOO_REGION1_MMAP_OFFSET &amp;&amp;
        !           275:             (u_int)off &lt; (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 &gt;= FOO_REGION2_MMAP_OFFSET &amp;&amp;
        !           280:             (u_int)off &lt; (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 &gt;= <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 &amp; PAGE_MASK)
        !           310:                 panic("foommap: offset not page aligned");
        !           311: 
        !           312:         if ((u_int)off &gt;= FOO_REGION1_MMAP_OFFSET &amp;&amp;
        !           313:             (u_int)off &lt; (FOO_REGION1_MMAP_OFFSET + FOO_REGION1_SIZE)) {
        !           314:                 if ((vaddr_t)foo_object1 &amp; 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, &amp;pa) == FALSE)
        !           318:                         panic("foommap: foo_object1 page not mapped");
        !           319:                 return (atop(pa));
        !           320:         }
        !           321: 
        !           322:         if ((u_int)off &gt;= FOO_REGION2_MMAP_OFFSET &amp;&amp;
        !           323:             (u_int)off &lt; (FOO_REGION2_MMAP_OFFSET + FOO_REGION2_SIZE)) {
        !           324:                 if ((vaddr_t)foo_object2 &amp; 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, &amp;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&amp;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>