The kernel modules required by Nouveau (
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).
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.
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
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
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
git reset --hard nouveau/master
to move your current local branch to the new head of
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.
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!
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)
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.
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
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
NOUVEAUROOTDIR, if needed.
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
if not, you can use
CONFIG_EXTRA_FIRMWARE="nouveau/file1 nouveau/file2", where
file1etc. need to be replaced by whatever is relevant to your hardware. To know which files you need, try to load
nouveau.koand 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.
For now, there is no opensource firmware available, you need to use the proprietary one. You can find instructions for obtaining it at VideoAcceleration.
The out-of-tree build's
make install step will install the modules into
/lib/modules/<version>/extra. If your kernel already had
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.