Chapter 17. Advanced Topics
Prev |  | Next

## Chapter 17. Advanced Topics

17.1. How can I learn more about FreeBSD's internals?
17.2. How can I contribute to FreeBSD?
17.3. What are snapshots and releases?
17.4. Can I follow -CURRENT with limited Internet access?
17.5. I have written a kernel extension, who do I send it to?
17.6. How can I make the most of the data I see when my kernel panics?
17.7. Why has dlsym() stopped working for ELF executables?
17.8. How can I increase or reduce the kernel address space on i386?

17.1. | How can I learn more about FreeBSD's internals?
| See the FreeBSD Architecture Handbook. Additionally, much general UNIX® knowledge is directly applicable to FreeBSD.
17.2. | How can I contribute to FreeBSD?
| Please see the article on Contributing to FreeBSD for specific advice on how to do this. Assistance is more than welcome!
17.3. | What are snapshots and releases?

There are currently four active/semi-active branches in the FreeBSD Subversion Repository. (Earlier branches are only changed very rarely, which is why there are only four active branches of development):

- RELENG_8 AKA 8-STABLE

- RELENG_9 AKA 9-STABLE

- HEAD AKA -CURRENT AKA 10-CURRENT

`HEAD` is not an actual branch tag, like the others; it is simply a symbolic constant for “the current, non-branched development stream” which we simply refer to as -CURRENT.

Right now, -CURRENT is the 10.`X` development stream; the 9-STABLE branch, RELENG_9, forked off from -CURRENT in September 2011 and the 8-STABLE branch, RELENG_8, forked off from -CURRENT in August 2009.

17.4. | Can I follow -CURRENT with limited Internet access?
| Yes, you can do this without downloading the whole source tree by using the CTM facility.
17.5. | I have written a kernel extension, who do I send it to?
| Please take a look at the article on Contributing to FreeBSD to learn how to submit code. And thanks for the thought!
17.6. | How can I make the most of the data I see when my kernel panics?

Here is typical kernel panic:

Fatal trap 12: page fault while in kernel mode fault virtual address = 0x40 fault code = supervisor read, page not present instruction pointer = 0x8:0xf014a7e5 stack pointer = 0x10:0xf4ed6f24 frame pointer = 0x10:0xf4ed6f28 code segment = base 0x0, limit 0xfffff, type 0x1b = DPL 0, pres 1, def32 1, gran 1 processor eflags = interrupt enabled, resume, IOPL = 0 current process = 80 (mount) interrupt mask = trap number = 12 panic: page fault

When you see a message like this, it is not enough to just reproduce it and send it in. The instruction pointer value is important; unfortunately, it is also configuration dependent. In other words, the value varies depending on the exact kernel image that you are using. If you are using a `GENERIC` kernel image from one of the snapshots, then it is possible for somebody else to track down the offending function, but if you are running a custom kernel then only you can tell us where the fault occurred.

What you should do is this:

1. Write down the instruction pointer value. Note that the `0x8:` part at the beginning is not significant in this case: it is the `0xf0xxxxxx` part that we want.

2. When the system reboots, do the following:

   `%` ``nm` `-n` `kernel.that.caused.the.panic` | `grep` f0xxxxxx`

   where `f0xxxxxx` is the instruction pointer value. The odds are you will not get an exact match since the symbols in the kernel symbol table are for the entry points of functions and the instruction pointer address will be somewhere inside a function, not at the start. If you do not get an exact match, omit the last digit from the instruction pointer value and try again, i.e.:

   `%` ``nm` `-n` `kernel.that.caused.the.panic` | `grep` f0xxxxx`

   If that does not yield any results, chop off another digit. Repeat until you get some sort of output. The result will be a possible list of functions which caused the panic. This is a less than exact mechanism for tracking down the point of failure, but it is better than nothing.

However, the best way to track down the cause of a panic is by capturing a crash dump, then using kgdb(1) to generate a stack trace on the crash dump.

In any case, the method is this:

1. Make sure that the following line is included in your kernel configuration file (`/usr/src/sys/`arch`/conf/`MYKERNEL``):

   makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols

2. Change to the `/usr/src` directory:

   `#` ``cd` `/usr/src``

3. Compile the kernel:

   `#` ``make` `buildkernel` `KERNCONF`=`MYKERNEL``

4. Wait for make(1) to finish compiling.

5. `#` ``make` `installkernel` `KERNCONF`=`MYKERNEL``

6. Reboot.

### Note:

If you do not use the `KERNCONF` make variable a `GENERIC` kernel will be built and installed.

The make(1) process will have built two kernels. `/usr/obj/usr/src/sys/`MYKERNEL`/kernel` and `/usr/obj/usr/src/sys/`MYKERNEL`/kernel.debug`. `kernel` was installed as `/boot/kernel/kernel`, while `kernel.debug` can be used as the source of debugging symbols for kgdb(1).

To make sure you capture a crash dump, you need edit `/etc/rc.conf` and set `dumpdev` to point to your swap partition (or `AUTO`). This will cause the rc(8) scripts to use the dumpon(8) command to enable crash dumps. You can also run dumpon(8) manually. After a panic, the crash dump can be recovered using savecore(8); if `dumpdev` is set in `/etc/rc.conf`, the rc(8) scripts will run savecore(8) automatically and put the crash dump in `/var/crash`.

### Note:

FreeBSD crash dumps are usually the same size as the physical RAM size of your machine. That is, if you have 512 MB of RAM, you will get a 512 MB crash dump. Therefore you must make sure there is enough space in `/var/crash` to hold the dump. Alternatively, you run savecore(8) manually and have it recover the crash dump to another directory where you have more room. It is possible to limit the size of the crash dump by using `options MAXMEM=`N`` where `N` is the size of kernel's memory usage in KBs. For example, if you have 1 GB of RAM, you can limit the kernel's memory usage to 128 MB by this way, so that your crash dump size will be 128 MB instead of 1 GB.

Once you have recovered the crash dump, you can get a stack trace with kgdb(1) as follows:

`%` ``kgdb` `/usr/obj/usr/src/sys/`MYKERNEL`/kernel.debug` `/var/crash/`vmcore.0``` `(kgdb)` `backtrace`

Note that there may be several screens worth of information; ideally you should use script(1) to capture all of them. Using the unstripped kernel image with all the debug symbols should show the exact line of kernel source code where the panic occurred. Usually you have to read the stack trace from the bottom up to trace the exact sequence of events that lead to the crash. You can also use kgdb(1) to print out the contents of various variables or structures to examine the system state at the time of the crash.

### Tip:

Now, if you are really insane and have a second computer, you can also configure kgdb(1) to do remote debugging such that you can use kgdb(1) on one system to debug the kernel on another system, including setting breakpoints, single-stepping through the kernel code, just like you can do with a normal user-mode program.

### Note:

If you have `DDB` enabled and the kernel drops into the debugger, you can force a panic (and a crash dump) just by typing `panic` at the `ddb` prompt. It may stop in the debugger again during the panic phase. If it does, type `continue` and it will finish the crash dump.

17.7. | Why has `dlsym()` stopped working for ELF executables?

The ELF toolchain does not, by default, make the symbols defined in an executable visible to the dynamic linker. Consequently `dlsym()` searches on handles obtained from calls to `dlopen(NULL, flags)` will fail to find such symbols.

If you want to search, using `dlsym()`, for symbols present in the main executable of a process, you need to link the executable using the `--export-dynamic` option to the ELF linker (ld(1)).

17.8. | How can I increase or reduce the kernel address space on i386?

By default, the kernel address space is 1 GB (2 GB for PAE) for i386. If you run a network-intensive server (e.g., a FTP or HTTP server), or you want to use ZFS, you might find that is not enough.

Add the following line to your kernel configuration file to increase available space and rebuild your kernel:

options KVA_PAGES=`N`

To find the correct value of `N`, divide the desired address space size (in megabytes) by four. (For example, it is `512` for 2 GB.)

Prev |  | Next
Chapter 16. The FreeBSD Funnies | Home | Chapter 18. Acknowledgments

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.