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

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" 
        !             9:     value="$NetBSD: programming.xml,v 1.8 2006/11/20 22:40:55 kano Exp $"/>
        !            10:   <config param="rcsdate" value="$Date: 2006/11/20 22:40:55 $"/>
        !            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
        !           339:              url="bus_dma.ps">paper</ulink> (120k, postscript)</listitem>
        !           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>