howtonewkerneldeveloper

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 ProjectsPage and at 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.

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

 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 <bsd.kmod.mk>

conf/files basically has the following format:

path/from/src/sys/to/your/code.c <optional / standard> [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