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/<your-arch>/<your-arch>/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 & PAGE_MASK)
! 243: panic("foommap");
! 244:
! 245: if ((u_int)off >= FOO_REGION1_MMAP_OFFSET &&
! 246: (u_int)off < (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 >= FOO_REGION2_MMAP_OFFSET &&
! 251: (u_int)off < (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 >= <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 & PAGE_MASK)
! 280: panic("foommap: offset not page aligned");
! 281:
! 282: if ((u_int)off >= FOO_REGION1_MMAP_OFFSET &&
! 283: (u_int)off < (FOO_REGION1_MMAP_OFFSET + FOO_REGION1_SIZE)) {
! 284: if ((vaddr_t)foo_object1 & 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, &pa) == FALSE)
! 288: panic("foommap: foo_object1 page not mapped");
! 289: return (atop(pa));
! 290: }
! 291:
! 292: if ((u_int)off >= FOO_REGION2_MMAP_OFFSET &&
! 293: (u_int)off < (FOO_REGION2_MMAP_OFFSET + FOO_REGION2_SIZE)) {
! 294: if ((vaddr_t)foo_object2 & 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, &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>