Annotation of htdocs/docs/kernel/programming.xml, revision 1.2

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

CVSweb <webmaster@jp.NetBSD.org>