Guide to contribute to kernel video drivers

Sat Feb 20 07:46:28 UTC 2016

Hello

Thanks a lot for a guide!

I have a few questions.

Do I right understand that the only way to debug a kernel is to crash
it and then analyze a dump using gdb? Is it possible to attach to a
running kernel remotely?

Are there any books or tutorials regarding kernel development you would
recommend? For instance are these books relevant and still actual:

* FreeBSD Architecture Handbook (2013, 178 pages)
* FreeBSD Developers' Handbook (2014, 178 pages)

?

I believe some experience with Linux kernel is required too? Same
question - which books and/or tutorials would you recommend and is a
book "Linux Kernel Development, 3rd Edition" (2010, 441 pages) still
actual?

On Fri, 19 Feb 2016 13:22:01 +0100
Jean-Sébastien Pédron <dumbbell at FreeBSD.org> wrote:

> Hi!
> 
> As promised a (too) long time ago, here are some instructions to get
> you started with kernel video drivers.
> 
> First, don't be afraid by 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.
> 
> == Requirements ==
> 
> o  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.
> 
> o  You need to setup kernel core dumps on the test computer. This is
>    step #1 here:
> 
> https://wiki.freebsd.org/Graphics/Update%20i915%20GPU%20driver%20to%20Linux%203.8#Testing_Instructions_.2F_How_To
> 
>    To test core dumps work:
>    sysctl debug.kdb.panic=1
> 
> o  You need a clone of Linux. I use the following Git remotes:
>    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 releases, such as
>    "v3.8.13". The former only provides "v3.8".
> 
> o  You need a clone of FreeBSD. You can fork this repository:
>    https://github.com/freebsd/freebsd-base-graphics
> 
>    I recommend you add this one as a second remote (in addition to
> your fork), as well as the FreeBSD official Git mirror:
>    https://github.com/freebsd/freebsd.git
> 
> == Source code locations ==
> 
> In Linux, DRM is located in three places:
>   drivers/gpu/drm
>   include/drm
>   include/uapi/drm
> 
> In FreeBSD, DRM is located in sys/dev/drm2, with the Makefiles in
> sys/modules/drm2.
> 
> == Targets ==
> 
> 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*
> next updates.
> 
> == Workflow ==
> 
> The workflow was discussed in previous threads:
> https://lists.freebsd.org/pipermail/freebsd-x11/2015-December/017056.html
> 
> The conslusion is here:
> https://lists.freebsd.org/pipermail/freebsd-x11/2016-January/017109.html
> 
> The file-by-file workflow, which was more popular in the discussion,
> was explained in the 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's 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
> (ie. one issue per file to update and an assignee). The issue even
> let 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 with "make buildkernel". Then, I can
> rebuild the DRM part with:
> make buildkernel -DKERNFAST DEBUG_FLAGS="-g -O0"
> 
> Add -j$N to accelerate the build.
> 
> You can't use "-O0" for the entire kernel otherwise the kernel will
> overflow the stack. However, use it for subsequent rebuilds (ie. 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 should move that file
> to the top of $(SRCS) in the Makefile (eg.
> sys/modules/drm2/drm2/Makefile) so other files don't prevent you from
> 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 (re)installkernel 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
> informations during kldload. To lower the log level afterward (in case
> it's too verbose), the corresponding sysctl is hw.dri.debug.
> 
> Play with several applications and use cases. I use:
>     o  glxinfo/glxgears
>     o  clinfo
>     o  Some of the games listed in the following page:
>        https://dri.freedesktop.org/wiki/Benchmarking/
>        (OpenArena and Xonotic in my case)
>     o  WebGL, I use this demo: http://www.david.li/waves/
>     o  Desktop environments (GNOME 3, KDE 4) and compositors such as
>        compton. I use compton to have a tearfree environment:
>        compton -CG --backend glx -b
>     o  Some video players with the GL and XVideo backends.
>     o  HTML5 videos. I watched this video which is exposes tearing a
>        lot:
>        https://www.youtube.com/watch?v=hpHknKaq_M0
>     o  Stellarium
>     o  xrandr(1) to manage output connectors
>     o  Suspend/resume
>     o  Piglit (from our development Ports tree; we should definitely
>        commit it)
> 
> If you find a problem, try to reduce it to the minimum, then:
>     1. From a remote computer, use tmux or screen for your session
> (not mandatory, but quite handy)
>     2. From one tab, start a plain X server:
>        Xorg
>     3. From another tab, start the bad, bad program:
>        DISPLAY=:0 bad_application
>     4. Use other tabs to look at log files, run dtrace scripts, etc.
> 
> By doing so, you limit the number of calls to the video drivers to the
> minmum. 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,
> you can: 1. Close all applications and the X server
>     2. kldunload the driver (note that it doesn't work for i915kms in
>        HEAD, the update will fix that)
>     3. 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 informations. If not, you can
> start gdb (either the one in base or the one from Ports):
>   gdb /boot/kernel/kernel /var/crash/vmcore.last
> (change /boot/kernel/kernel to match the kernel you used)
> 
> Thanks for reading! :) If something is missing, please ask! I will put
> this information on the wiki.
> 

-- 
Best regards,
Eax Melanhovich
http://eax.me/