Guide to contribute to kernel video drivers

Fri Feb 19 21:45:50 UTC 2016

Hi Jean-Sébastien,

huge thanks for the guide! :)
So far, I just used a rather blunt approach for my testing and I think 
your guide will help me a lot for improving my workflow.

BR,

Ruediger

PS:
I also appreciate the very welcoming attitude I see here in the list.

On 02/19/2016 13:22, Jean-Sébastien Pédron 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.
>