# DragonFly BSD New Kernel Developers Guide ##Introduction While DragonFly was forked off FreeBSD and has generally quite a few similarities to other *BSD, you definitely cannot rely on understanding FreeBSD to understand what's going on here. At the moment the only way to get an accurate picture of what's going on in DragonFly is delving directly into the code. I'd recommend you get cscope (and if you want some GUI, like kscope) to browse the code; it makes things much easier. Another important resource is the IRC channel \#dragonflybsd on efnet, where quite a few developers hang out. If you just can't figure out what some code does, or you just don't get the bigger picture of something, it would probably be appropriate to ask there. The last resource is always the mailing list. While there is nothing wrong with asking anything there, it probably isn't worth asking about some really minor issue. You are better off finding the answer by yourself or on IRC. Other valuable resources can be found in the appendix Valuable Resources; most of them are books that, although aren't directly related to DragonFly, provide a general picture of operating system internals. ##How to contribute If you are looking for something to do straight ahead, you should definitely look at both the [[docs/developer/ProjectsPage/]] and at [[docs/developer/SimonsTODOs/]]. Apart from this there are always other tasks at hand: * port drivers from other *BSD * write man pages (we are missing a lot of them) ##General code guidelines Detailed style guidelines can be found in the style(9) man page. Other general aims and considerations when messing with DragonFly BSD kernel code are: * use sizeof() instead of fixed sizes whenever possible * try to avoid locking, often using lwkt messages provides a viable alternative * try to remove any warnings that appear when compiling your code * 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) * early returns are not bad * goto is not your enemy * use objcache instead of kmalloc for object types which you are going to allocate (and deallocate) often * let others review your code, there is no shame in corrections ##Source code management At DragonFly BSD, unlike other {*}BSDs, we use git for source control management. It is very powerful, yet easy to use. * git clone <repo> *Does an initial local copy of a remote repo* * git pull <repo> *Updates the local repo from the remote repo* * git branch <foo> *Creates a local branch named foo* * git checkout <foo> *Changes the active local branch to foo* * git rebase <bar> *Tries to merge the current active local branch onto bar.* ##VKERNELs Here is a [how to](http://www.dragonflybsd.org/docs/howtos/HowToDebugVKernels/). ##Kernel debugging If you don't want to rely on VKERNELs working properly, your best option is to use VirtualBox. Be sure to pull VirtualBox OSE from the repository, as it is the only one that works properly (non-OSE as of this writing doesn't work with DragonFly, neither does pre-built OSE). To enable serial port debugging, change in your kernel config file device sio0 at isa? port IO_COM1 flags 0x10 irq 4 to device sio0 at isa? port IO_COM1 flags 0x90 irq 4 In VirtualBox enable the serial port 1 (COM1) as a host pipe to for example /tmp/dfly. Then use socat or a similar tool to act as a proxy between the unix socket /tmp/dfly and a pty device or similar that gdb can access. Once you have done all this, to enable debug at boot already, skip to the command line of the boot loader and type boot kernel -d This should bring you into a kernel debugger prompt. Just type: gdb s to first enable remote gdb debugging and then actually switch to the remote debugger. To be able to debug anything properly you should definitely familiarize yourself with gdb first. ##Adding files to to the kernel 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: SRCS= est.c KMOD= est .include conf/files basically has the following format: path/from/src/sys/to/your/code.c [config_variable_which_enables_this_code] "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. two examples would be: dev/drm/drm_irq.c optional drm libkern/strtouq.c standard 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. ##Valuable Resources * Modern Operating Systems (Andrew S. Tanenbaum) * Operating Systems Concepts (Abraham Silberschatz) * Design and Implementation of the 4.4BSD Operating System (John S. Quarterman) * DragonFly Kernel Mailing List Archive