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