Getting started with kernel projects
First, don't be afraid of the kernel. In the kernel, you have to live with some constraints and debugging is more challenging, but it's not an order of magnitude harder than userland. Moreover, we are porting existing working code.
Contents
Requirements
You need to run CURRENT on the test computer. I recommend you work from another computer. You only need to copy the built kernel to the test computer.
You need to set up kernel core dumps on the test computer:
# In /etc/rc.conf dumpdev="AUTO" ddb_enable="YES"
Additionally, it helps to have the following sysctl:
# In /etc/sysctl.conf debug.debugger_on_panic=0
To test core dumps work:
sysctl debug.kdb.panic=1
You need a clone of Linux. I use the following Git remotes (both of them):
git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
The second one is useful to get the patch release tags, such as "v3.8.13". The former only provides "v3.8".
You need a clone of FreeBSD. You can fork our development repository on GitHub. I recommend you add this one as a second remote (in addition to your fork), as well as the FreeBSD official Git mirror.
Source code locations
In Linux, DRM is located in three places:
drivers/gpu/drm
include/drm
include/uapi/drm
In FreeBSD, DRM is in two places:
sys/dev/drm2 (source code)
sys/modules/drm2 (Makefiles)
Targets
The workflow and target were discussed in the thread below: https://lists.freebsd.org/pipermail/freebsd-x11/2015-December/017056.html
The conclusion is in a separate thread: https://lists.freebsd.org/pipermail/freebsd-x11/2016-January/017109.html
During the discussion, some wanted to work on Linux 3.9, some on Linux 4.3/4.4.
That said, I believe we should start by moving to linuxkpi before anything. It would consist of modifying DRM to use sys/compat/linuxkpi instead of its own drm_os_freebsd.[ch] files. This would help a lot during the next updates.
Workflow
The file-by-file workflow was more popular in the discussion, and is explained in the second link above.
As for the branches, we are going to use drm-next-$target (eg. drm-next-3.9). Please send pull requests to these branches. At least in freebsd-base-graphics, master will remain the same code as Subversion's HEAD so we have a point of comparison.
Let's take drm-next-3.9 as an example. We want to update the entire DRM to Linux 3.9: DRM core (the device-independent code), the i915 driver and the Radeon driver.
As we are testing the file-by-file approach, we need to coordinate who does what. And before the task is finished, the kernel won't compile. That is the risk with the file-by-file approach.
I would like to record all the contributors on the wiki or on GitHub, I'm not sure yet. Maybe it should take the form of issues on GitHub (that is, one issue per file to update and an assignee). The issue even lets us discuss specific details about the file.
DRM core should be updated first, then the drivers.
How to build
I usually build a full kernel:
make buildkernel
Then, after some work, I can rebuild the DRM part:
make buildkernel -DKERNFAST DEBUG_FLAGS="-g -O0"
Add -j$N to accelerate the build.
You can't use -O0 for the entire kernel, it will cause stack overflows. However, use it for subsequent rebuilds (that is, when using -DKERNFAST). Otherwise, you'll get a lot of "<optimized out>" variables in gdb.
When working on the update of a single file, you move that file to the top of $(SRCS) in the Makefile (for example, sys/modules/drm2/drm2/Makefile) so other files don't prevent build-testing your work.
I (re)install the new kernel in /tmp, because I use tmpfs there (I don't care about the installed kernel on my working computer):
make installkernel DESTDIR=/tmp # or, after a first install make reinstallkernel DESTDIR=/tmp
From the test computer, I rsync the new kernel.
How to Test
Do not load the driver from /boot/loader.conf or /etc/rc.conf. Load it manually after boot.
You can set drm.debug=7 in /boot/loader.conf to have more debug information during kldload. If the log level is too verbose, it can be lowered later with the hw.dri.debug sysctl.
Play with several applications and use cases. I use:
glxinfo/glxgears
clinfo
Some of the games listed in the DRI benchmarking wiki page (OpenArena and Xonotic in my case)
WebGL; I use this demo: http://www.david.li/waves/
Desktop environments (GNOME 3, KDE 4) and compositors such as compton. I use compton to have a tearfree environment:
compton -CG --backend glx -b
- Some video players with the GL and XVideo backends.
HTML5 videos. I watched this video which is exposes a lot of tearing: https://www.youtube.com/watch?v=hpHknKaq_M0
- Stellarium
- xrandr(1) to manage output connectors
- Suspend/resume
- Piglit (from our development Ports tree; we should definitely commit it)
If you find a problem, try to reduce it to the minimum, then:
- From a remote computer, use tmux or screen for your session (not mandatory, but quite handy)
From one tab, start a plain X server:
Xorg
From another tab, start the bad, bad program:
DISPLAY=:0 bad_application
- Use other tabs to look at log files, run dtrace scripts, and so on.
By doing so, you limit the number of calls to the video drivers to the minimum. Running a full desktop environment will spam a lot of unrelated messages.
If the computer doesn't crash and you want to load a newer driver:
- Close all applications and the X server
kldunload the driver (note that it doesn't work for i915kms in HEAD, the update will fix that)
- kldload the new one.
It saves you a reboot. Again, do this from a remote computer because after kldunloading, you may not get a console back. It works with the Radeon driver, but so far, not with the updated i915 driver.
If you get a core dump, it will be available in /var/crash after the reboot. Usually, core.txt.$N has enough information. If not, you can start gdb (either the one in base or the one from Ports):
# Change "/boot/kernel/kernel" to match the kernel you used kgdb /boot/kernel/kernel /var/crash/vmcore.last
Books and documentation
I recommend the following two books:
FreeBSD Device Drivers - A Guide for the Intrepid (April 2012), by Joseph Kong. It gives you a good start.
The Design and Implementation of the FreeBSD Operating System, Second Edition (September 2014), by Marshall Kirk McKusick, George V. Neville-Neil and Robert N.M. Watson. In the context of DRM, one of the most important chapter is chapter 6, "Memory Management".
Additionally, Daniel Vetter from Intel wrote a series of nice articles about the i915 driver.