Annotation of htdocs/docs/kernel/programming.xml, revision 1.3
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"
1.3 ! yurix 9: value="$NetBSD: programming.xml,v 1.2 2008/05/31 10:43:42 tsutsui Exp $"/>
! 10: <config param="rcsdate" value="$Date: 2008/05/31 10:43:42 $"/>
1.1 dsieger 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:
1.3 ! yurix 73: <para>Once probe and attach routines have been written, register them using
! 74: CFATTACH_DECL_NEW. See &man.driver.9; for more details.
! 75: </para>
1.1 dsieger 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
1.2 tsutsui 339: url="bus_dma.pdf">paper</ulink> (64k, PDF)</listitem>
1.1 dsieger 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>