Add link to vkernel debugging how to
[ikiwiki.git] / docs / howtos / howtonewkerneldeveloper / index.mdwn
1 # DragonFly BSD New Kernel Developers Guide
2
3
4
5 ##Introduction
6
7  While DragonFly was forked off FreeBSD and has generally
8 quite a few similarities to other *BSD, you definitely cannot rely
9 on understanding FreeBSD to understand what's going on here. At the
10 moment the only way to get an accurate picture of what's going on
11 in DragonFly is delving directly into the code. I'd recommend you
12 get cscope (and if you want some GUI, like kscope) to browse the code;
13 it makes things much easier.
14
15  Another important resource is the IRC channel \#dragonflybsd
16 on efnet, where quite a few developers hang out. If you just can't
17 figure out what some code does, or you just don't get the bigger picture
18 of something, it would probably be appropriate to ask there.
19
20  The last resource is always the mailing list. While there
21 is nothing wrong with asking anything there, it probably isn't worth
22 asking about some really minor issue. You are better off finding the
23 answer by yourself or on IRC. 
24
25  Other valuable resources can be found in the appendix Valuable
26 Resources; most of them are books that, although aren't
27 directly related to DragonFly, provide a general picture of operating
28 system internals.
29
30
31 ##How to contribute
32
33 If you are looking for something to do straight ahead, you should
34 definitely look at both the [[docs/developer/ProjectsPage/]] and at [[docs/developer/SimonsTODOs/]]. Apart
35 from this there are always other tasks at hand:
36    
37 * port drivers from other *BSD  
38 * write man pages (we are missing a lot of them)  
39
40 ##General code guidelines
41
42 Detailed style guidelines can be found in the style(9) man page. Other
43 general aims and considerations when messing with DragonFly BSD kernel
44 code are:
45    
46 * use sizeof() instead of fixed sizes whenever possible  
47 * try to avoid locking, often using lwkt messages provides a viable  alternative  
48 * try to remove any warnings that appear when compiling your code  
49 * don't reinvent the wheel; there is a lot of stuff already done that  can help you (for example basic data structures in sys/queue.h)  
50 * early returns are not bad  
51 * goto is not your enemy  
52 * use objcache instead of kmalloc for object types which you are going  to allocate (and deallocate) often  
53 * let others review your code, there is no shame in corrections  
54
55 ##Source code management
56
57 At DragonFly BSD, unlike other {*}BSDs, we use git for source control
58 management. It is very powerful, yet easy to use.
59
60 *    git clone <repo>  *Does an initial local copy of a remote repo*
61 *    git pull <repo>  *Updates the local repo from the remote repo*
62 *    git branch <foo>  *Creates a local branch named foo*
63 *    git checkout <foo>  *Changes the active local branch to foo*
64 *    git rebase <bar>  *Tries to merge the current active local branch onto bar.*
65
66 ##VKERNELs
67 Here is a [how to](http://www.dragonflybsd.org/docs/howtos/HowToDebugVKernels/).
68
69 ##Kernel debugging
70
71 If you don't want to rely on VKERNELs working properly, your best
72 option is to use VirtualBox. Be sure to pull VirtualBox OSE from the
73 repository, as it is the only one that works properly (non-OSE as
74 of this writing doesn't work with DragonFly, neither does pre-built
75 OSE).
76
77  To enable serial port debugging, change in your kernel config file
78
79      device  sio0  at  isa?  port  IO_COM1  flags  0x10  irq  4
80
81 to
82
83      device  sio0  at  isa?  port  IO_COM1  flags  0x90  irq  4
84
85
86 In VirtualBox enable the serial port 1 (COM1) as a host pipe to for
87 example /tmp/dfly. Then use socat or a similar tool to act as a proxy
88 between the unix socket /tmp/dfly and a pty device or similar that
89 gdb can access.
90
91  Once you have done all this, to enable debug at boot already,
92 skip to the command line of the boot loader and type
93
94     boot  kernel  -d
95
96 This should bring you into a kernel debugger prompt. Just type:
97
98     gdb
99
100     s
101
102 to first enable remote gdb debugging and then actually switch to the
103 remote debugger.
104
105  To be able to debug anything properly you should definitely
106 familiarize yourself with gdb first.
107
108
109 ##Adding files to to the kernel
110 When you write a new subsystem or driver, requiring new files, you will have to change some files. If your intention is to add something that is not a module and can't be compiled as such, you only have to edit /usr/src/sys/conf/files. If you intend it to be loadable, you also have to edit a few Makefiles. Generally a Makefile in your directory for the module, plus edit the Makefiles in the directories above yours. In the Makefiles above your module you only have to add your directory to the path. Your Makefile should look something like this:
111
112     SRCS=   est.c
113
114     KMOD=   est
115
116     .include <bsd.kmod.mk>
117
118
119 conf/files basically has the following format:
120
121     path/from/src/sys/to/your/code.c <optional / standard> [config_variable_which_enables_this_code]
122
123
124 "standard" means that it will always be compiled into the kernel, while "optional" means it is optional and has to be explicitly specified in the config file for it to be built in.
125 two examples would be:
126
127     dev/drm/drm_irq.c                       optional drm
128
129     libkern/strtouq.c                       standard
130
131
132 The first example will compile drm_irq.c into the kernel whenever the option or driver 'drm' is specified in the config file. The second example will always compile strtouq.c into the kernel.
133
134
135 ##Valuable Resources
136    
137 * Modern Operating Systems (Andrew S. Tanenbaum)  
138 * Operating Systems Concepts (Abraham Silberschatz)  
139 * Design and Implementation of the 4.4BSD Operating System (John S.  Quarterman)  
140 * DragonFly Kernel Mailing List Archive  
141