README: Rework a short version of the build instructions

[Why]
The full version is now available in the wiki on GitHub. That location
might change and the link here will be updated.

Sponsored by: FreeBSD Foundation

Author: dumbbell

README.md

@@ -1,33 +1,92 @@
 # drm-kmod
-The DRM drivers ported from Linux to FreeBSD using LinuxKPI
 
-## Contributing
+The DRM drivers ported from Linux to FreeBSD using *linuxkpi*.
+
+## Installing from sources
+
+### Requirements
+
+You need to have the sources of FreeBSD kernel available and they MUST
+correspond to the installed version of FreeBSD.
+
+There are several ways to get them:
+* by using the FreeBSD installer
+* by using the `FreeBSD-src-sys` package if you use PkgBase
+* by cloning the Git repository from https://git.FreeBSD.org/src.git or any mirror
 
-### Linux source code
-Folders `amd`, `drm`, `i915`, `radeon` contain FreeBSD Makefiles for the driver modules.  
+By default, Makefiles expect the sources of the kernel to be in `/usr/src/sys`.
+The installer and the PkgBase package will install them in that directory. If
+you clone from Git, you can set `SYSDIR=/path/to/FreeBSD/src/sys` on the
+make(1) command line or in the environment when compiling the drivers and their
+firmwares.
 
-Folder `drivers` contain source code from Linux, patched (minimally) to run on FreeBSD with LinuxKPI.
-Try to keep changes to the code to a minimum but if you have to patch it, leave the Linux source code intact like so:
+### Building
 
+```sh
+make -j12 DEBUG_FLAGS=-g SYSDIR=/usr/src/sys
 ```
-#ifdef __linux__
-...intact linux code...
-#elif defined(__FreeBSD__)
-bsd code
-#endif
+
+As stated in the requirements section, set `SYSDIR` to the location where you
+put the FreeBSD kernel sources. The example above shows the default value.
+
+### Installing
+
+```sh
+sudo make install DEBUG_FLAGS=-g SYSDIR=/usr/src/sys KMODDIR=/boot/modules
 ```
 
-When updating and patching this code with code from Linux there are often merge conflicts where the code has been changed. If there are no markers it is difficult to know what code to keep and what to throw away.
+As stated in the requirements section, set `SYSDIR` to the location where you
+put the FreeBSD kernel sources. The example above shows the default value.
+
+Likewise, set `KMODDIR` to the location of the kernel you want to install the
+drivers for. The example above shows the default value which is the global
+directory, used by all installed kernels
+
+> [!IMPORTANT]
+> The DRM drivers MUST be compiled against the kernel sources corresponding to
+> the installed kernel you want to use them with.
+
+### GPU firmwares
+
+DRM drivers depend on binary firmwares. They are maintained in a separate Git
+repository at https://github.com/freebsd/drm-kmod-firmware.
+
+The binary firmwares are packaged into kernel modules and loaded automatically
+by the DRM drivers when needed.
+
+The kernel modules can be compiled by following the same instructions as the
+DRM drivers. The same constraint applies: use the matching kernel sources.
+
+## Contributing
+
+> [!TIP]
+> This part is a TL;DR version of the porting process. For the full version,
+> please visit
+> https://github.com/freebsd/drm-kmod/wiki/Porting-a-new-version-of-DRM-drivers-from-Linux.
+
+1. Clone Linux:
+
+    ```sh
+    git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git /path/to/linux-src
+    ```
+
+2. Extract Linux patches:
 
-Pull requests that do not follow this will not be accepted. 
+    ```sh
+    ./scripts/drmgeneratepatch \
+        /path/to/linux-src \
+        /path/to/patches-6.7 \
+        v6.6..v6.7
+    ```
 
-Unless obvious what your code does, please leave a comment to explain to fellow developers why you patched it. The source code is the documentation!
+3. Filter out already applied patches:
 
-If the patch can be avoided by adding functionality to LinuxKPI, please consider the latter. Sooner or later, there will be more places where the functionality is used and having it in LinuxKPI mean we don't have to patch twice.
+    ```sh
+    ./scripts/drmcheckapplied /path/to/patches-6.7
+    ```
 
-### FreeBSD source code
-Folders `linuxkpi`
+4. Apply patches to `drm-kmod`:
 
-Code style and rules same as FreeBSD kernel.
-No new code should be added there, all new linuxkpi functions should be
-added in FreeBSD base.
+    ```sh
+    ./scripts/drmpatch /path/to/patches-6.7
+    ```