Kernel development workflow [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Graphics stack: kernel development workflow ======

The workflow is being discussed: this page sums up ideas and will be updated to reflect the proposed method.

===== Use of Git and GitHub =====

We want to use [[/GitHub|GitHub]] to allow as many people as possible to contribute easily to the kernel. The work would take place in a fork of the [[https://github.com/freebsd/freebsd|official mirror]].

In this repository, we would create a ''%%drm-next%%'' branch: it would receive direct commits or pull requests. On a regular basis, we would merge HEAD in ''%%drm-next%%'' so the branch is in sync, especially if there are commits to DRM in Subversion directly. Once we feel it's in good shape, its content is committed to HEAD.

This ''%%drm-next%%'' branch should remain stable most of the time. If we need to break it for a longer period of time, we could use other branches, such as ''%%drm-next-i915%%'', ''%%drm-next-dmabuf%%'' or ''%%drm-next-3.10%%'' for instance (these are just examples). They would be created from ''%%drm-next%%'' and they would have the same relationship with ''%%drm-next%%'' than ''%%drm-next%%'' has with HEAD.

===== How to split the work =====

Milestones should be versions of Linux. For instance, the next one on the road is Linux 3.9. We have DRM core and two drivers to sync and we should try to keep the whole DRM in sync (and not have i915 at 3.15 and Radeon at 3.13 for instance).

Until now, our DRM was updated on a file-by-file basis: a file was taken from Linux 3.8 and ported it to %%FreeBSD%% from scratch, by keeping an eye on the current %%FreeBSD%% copy. Therefore, we jumped from whatever version we were at straight to 3.8, at the high cost of an unbuildable kernel before the very end.

Another approach is to update on a commit-by-commit basis: we take all commits between 3.8 and 3.9 and apply them in order. The downside are:
  * We could port code which is rewritten or removed 10 commits later.
  * Important patches are hard to prioritize if it's located 100 commits later in the history compared to the last imported commit.
  * It implies that all commits are about the same amount of work, but a single massive commit could put a hold on the process until it's completed.

In both cases, we need a complete review of the code before it's committed to HEAD: a comparison to HEAD to make sure we don't drop needed code, a comparison to Linux to make sure the update is complete.

An easy way to share the work is to split drivers: someone updates Radeon, someone else updates i915, a third contributor handles DRM. Still, this is not very parallel. If we go with the file-by-file update, it's very easy to parallelize further. With the commit-by-commit approach, it's complicated because it's obviously serialized.

Again, if we go with the file-by-file method, we could jump to a later version of Linux instead of doing one at a time. It's even more dangerous because we have more chance of breaking/losing something because of the gap between the last update and the next one.

===== File layouts =====

In Linux, files are located in three directories:
  * ''%%drivers/gpu/drm%%''
  * ''%%include/drm%%''
  * ''%%include/uapi/drm%%''

The corresponding location in %%FreeBSD%% is ''%%sys/dev/drm2%%''. Both headers and source files are in this directory.

DRM core, the device-independent code, is inside the ''%%drm_*%%'' files in ''%%sys/dev/drm2%%'' (or ''%%drivers/gpu/drm%%'' in Linux). Then this directory contains one sub-directory per driver. In the case of %%FreeBSD%%:
  * ''%%sys/dev/drm2/i915%%''
  * ''%%sys/dev/drm2/radeon%%''

Kernel modules are built from the following directories:
  * ''%%sys/modules/drm2/drm2%%'': DRM core
  * ''%%sys/modules/drm2/i915kms%%'': the i915 driver
  * ''%%sys/modules/drm2/radeonkms%%'': the Radeon driver

A basic Linux shim exists in ''%%sys/dev/drm2/drm_os_freebsd.[ch]%%''.