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 &lt;repo&gt;  *Does an initial local copy of a remote repo*
  61 *    git pull &lt;repo&gt;  *Updates the local repo from the remote repo*
  62 *    git branch &lt;foo&gt;  *Creates a local branch named foo*
  63 *    git checkout &lt;foo&gt;  *Changes the active local branch to foo*
  64 *    git rebase &lt;bar&gt;  *Tries to merge the current active local branch onto bar.*
  65
  66 ##VKERNELs
  67
  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 ##Valuable Resources
 110
 111 * Modern Operating Systems (Andrew S. Tanenbaum)
 112 * Operating Systems Concepts (Abraham Silberschatz)
 113 * Design and Implementation of the 4.4BSD Operating System (John S.  Quarterman)
 114 * DragonFly Kernel Mailing List Archive
 115