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