Nouveau DRM modules, the Nouveau kernel tree
The kernel modules required by Nouveau (drm.ko, drm_kms_helper.ko, ttm.ko and nouveau.ko) are built from a Linux kernel tree. You have several options on how to download the source code (subsections of Section 1) and how to compile it (subsections of Section 2). See also KernelModeSetting for important KMS notes. Please, read carefully.
The Nouveau kernel git repository is called nouveau/linux-2.6 and contains one recommended branch: master. The repository name contains "2.6" because we never bothered to rename it to "3": that would either break a lot of people's git configs or we would have two names for the same repository, for no benefit. It does contain the Linux 3.x versions.
You may not be able to compile the DRM modules against your current kernel, if it is too old (might need an -rc kernel or even Linus' git kernel). The possible errors include build failure and kernel modules that cannot be loaded. It is recommended to build your whole kernel from this branch (Section 2.1).
Since the DRM code is part of the kernel since 2.6.33, you can also use Linus' git kernel for Nouveau. However, the code in Linus' kernel will always be older than Nouveau's own git, and because there are no official Nouveau releases, you may encounter compatibility issues with user space parts (libdrm, DDX, Mesa).
Contents
1. Downloading the source
The are different options to get the latest nouveau code:
- cloning the Nouveau kernel repository without history
- Good option for regular updates, fine for most users. This will download less data than the next option, but freedesktop.org can be a little slow. You get the full Linux kernel sources including the DRM modules.
- adding the Nouveau kernel repository as a new remote
- The recommended option, especially for development. If you don't have any git kernel tree yet, clone Linus' tree from kernel.org first. This is faster than cloning the Nouveau kernel tree from freedesktop.org. You get the full Linux kernel sources including the DRM modules. Not only does this give you the proper kernel history, it will also give you the official kernel release tags, which makes version information a lot more readable.
- updating an existing repository from git
- Only if you already have the Nouveau kernel repository.
- downloading a daily snapshot of only the directories needed for DRM and Nouveau kernel modules (not full kernel sources)
- More manual work, but the download size is very small. No automatic version information nor history included. Out-of-tree build only (Section 2.2). Cannot make Nouveau built-in into the kernel (built-in not recommended anyway).
NOTE: If you clone or add a new remote, you only need to do that once. Afterwards always use the update procedure. Cloning means a full copy of the remote repository including all branches.
1.1. Adding the Nouveau kernel repository as a new remote
If you don't have any git kernel tree yet, start cloning Linus' one with
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
This will contain the full Linux development history from 2.6.12 onwards. You need roughly 2 GB of disk space for the repository including the compiled kernel.
Chdir into your Linux kernel git repository.
To add Nouveau, do
git remote add nouveau git://anongit.freedesktop.org/nouveau/linux-2.6
and check with git config -l, you should have
remote.nouveau.url=git://anongit.freedesktop.org/git/nouveau/linux-2.6 remote.nouveau.fetch=+refs/heads/*:refs/remotes/nouveau/*
To actually download the Nouveau repository, do git remote update or git fetch nouveau or pass -f to the adding command in the first place. For more information, see git help remote.
Now you have a local git repository, where the remote origin is Linus' kernel tree and nouveau is the nouveau/linux-2.6 kernel tree. The only thing left is to switch to the Nouveau branch (or actually create a local version of it):
git checkout -b nouveau-master nouveau/master
1.2. Updating the Nouveau kernel git repository
git remote update
fetches all remote repositories and branches. Because nouveau/master is a rebased branch, git pull and git rebase do not work. Your local branch needs to be reset to the new nouveau/master on each update. This will lose all local changes you may have made to your local branch (checkout). Assuming your nouveau/linux-2.6 tree is called nouveau,
git reset --hard nouveau/master
to move your current local branch to the new head of nouveau/master.
1.3. Downloading a snapshot
The daily snapshots: http://people.freedesktop.org/~pq/nouveau-drm/ (the timestamp is in PDT) are named by the branch.
The archives are overwritten daily, so do not delete the file you downloaded. The command zcat master.tar.gz | git get-tar-commit-id will show the revision id of the package. The developers need to know the id, if you want to report bugs. Just download, unpack, and move on to the compiling instructions. Btw. here is the Makefile.
1.4. Cloning the Nouveau kernel repository without history
git clone --depth 1 git://anongit.freedesktop.org/nouveau/linux-2.6
Does not download any history, otherwise see above. You are still able to get updates using the normal git commands. Here nouveau/linux-2.6 kernel tree is the remote called origin. Leaving out the history will save something in the order of 50-70% in the initial download size (not disk space consumption).
Do not use this method if you want to bisect a regression!
2. Compiling the modules
There are two options. Whichever you choose remember to check you have these options enabled:
- "Framebuffer Console support" (CONFIG_FRAMEBUFFER_CONSOLE)
- "Support for binding and unbinding console drivers" (CONFIG_VT_HW_CONSOLE_BINDING)
2.1. building a complete kernel from Nouveau sources (recommended)
The Nouveau kernel tree is a full kernel source, following Linus' tree. Linus' tree is occasionally merged into the Nouveau tree to get updates from upstream. Just build and use this kernel as usual. This option is not considered here because there is nothing special about it. You can find Nouveau under the staging drivers.
2.2. out-of-tree build (alternative)
You compile the modules without touching your current kernel, assuming the kernel is compatible.
The first thing to check is that your kernel version should be at least the version that is currently merged into the Nouveau kernel tree. You can check the required (recommended) kernel version from the Nouveau kernel tree upstream Makefile, the variables VERSION, PATCHLEVEL, SUBLEVEL and EXTRAVERSION at the top of the file.
The second is that the configuration of your currently running kernel (or the target kernel) is compatible. The usual requirements are listed in file DEPENDS. There are other requirements, too, but it is hard to miss them. You have to check the requirements yourself, or you may get mysterious compile errors, or the modules may simply fail to load.
NOTE: DEPENDS file (above) instructs you to enable an fb driver to get the required FB_CFB_* kernel options enabled. Do not choose vga16fb, it will load automatically and make Nouveau misbehave. The point is to choose an fb driver, that you do not have the hardware for. You do not really want the fb driver but the modules from FB_CFB_* options. Also, not all fb drivers enable all the required FB_CFB_* options, so it is best to stick to the suggested fb driver in DEPENDS.
The out-of-tree build is done using this Makefile, download it. It is recommended to save it under a new directory nouveau in your checkout of the Nouveau kernel tree. The following assumes you did exactly that.
The build itself:
cd nouveau make make install
By default it will build the modules for your currently running kernel. If you want to build for another kernel, use
make LINUXDIR=/path/to/system/kernel/source make LINUXDIR=/path/to/system/kernel/source install
The Makefile assumes that the Nouveau kernel tree is found in the parent directory of the current working directory of make. If that is not the case, you can specify the Nouveau kernel tree location with
make NOUVEAUROOTDIR=/path/to/nouveau/linux-2.6 make NOUVEAUROOTDIR=/path/to/nouveau/linux-2.6 install
You can also specify both LINUXDIR and NOUVEAUROOTDIR, if needed.
3. 3D-accel Firmware
For the nouveau/linux-2.6 DRM modules, the goal is to never need external firmware. However, during development it may be required. The card families:
NV04 - NV30: No firmware used.
NV40 - NV50: No firmware needed. The Nouveau driver generates the ctxprogs and related state internally (commits 48c6dfb8 and 266229a5).
NVC0: Free firmware provided by the driver, presumably working.
NVD0: Free firmware provided by the driver but imperfect (commit 902530693ef38f3bb007efae594e54443d84fa56)
NVE0: Free firmware provided by the driver, presumably working (commit eca15296a9c2a5d5d7d8281a710ba4bd0c2e7cd3)
The proprietary firmware is not readily available, you need to extract it yourself (instructions).
NOTE: Whenever firmware is used, it needs to be available when the Nouveau DRM initializes (loads). The easiest way to avoid problems with firmware is to build Nouveau as a module, and not to put it into initramfs. If you put nouveau.ko into initramfs, put the firmware there, too. If you build Nouveau into the kernel (and not as a module), you need to make the firmware available before the root file system is mounted. There are several ways of doing so:
if your whole kernel is built from nouveau/linux-2.6, you can build the firmware into the kernel image by setting CONFIG_FIRMWARE_IN_KERNEL
if not, you can use CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware" and CONFIG_EXTRA_FIRMWARE="nouveau/file1 nouveau/file2", where file1 etc. need to be replaced by whatever is relevant to your hardware. To know which files you need, try to load nouveau.ko and look in the kernel log for lines
nouveau 0000:02:00.0: firmware: requesting nouveau/nvaa.ctxprog nouveau 0000:02:00.0: firmware: requesting nouveau/nvaa.ctxvals
- adding it to initramfs may be enough.
4. Video Firmwares
For now, no opensource firmwares is available, you need to use the proprietary ones. However, they are not readily available, you need to extract them yourself (instructions).
5. Installation notes
The out-of-tree build's make install step will install the modules into /lib/modules/<version>/extra. If your kernel already had drm.ko, ttm.ko or nouveau.ko in some other directory, they will conflict and should be removed. When the installation is done properly, all you need to do to load the modules is modprobe nouveau. Depending on your system, the modules may even be automatically loaded on boot, but starting X will load them, too. If nvidia.ko loads automatically on boot, you may want to remove it.