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