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