radeonBuildHowTo

Building new version from git

It is possible to compile either stable or development version of radeon from git.

Changes to stable branch should be upgraded by distribution packages but in practice distributions don't follow the stable branch for released versions. If your distribution has failed to upgrade to the latest stable version you might get better stability by compiling new version from branch that matches your distribution version.

Development branch (master) is for bleeding edge development where you might get regression but also better performance and features. But if you decide that new features are worth of possible regression and bugs that happen in development you are more than welcome to upgrade to the latest code base. It is good idea to join our irc channel #radeon@freenode to get help for possible problems in bleeding edge code.

Contents

  1. Building new version from git
    1. Stable branch
      1. xf86-video-ati (ddx)
      2. Mesa (3D)
    2. Configuring system to load mesa and libdrm from /opt/xorg
    3. Possible problems
      1. Checking for hardware 3D acceleration
      2. Removing Catalyst/fglrx
    4. Updating git tree
    5. Removing self compiled driver
    6. Bleeding edge code from development branch
      1. Packages for distributions
    7. Kernel mode setting (KMS)
      1. Kernel mode setting for r100-r500
      2. Kernel mode setting and 3D for r600/r700
        1. Updating the source
        2. Creating patch from drm-next changes
        3. alternatively use drm-next as is
        4. List of active branches in drm-2.6.git
      3. Troubleshooting KMS problems
      4. Troubleshooting Extra Firmware for R600/R700
    8. Reporting bugs

Stable branch

xf86-video-ati (ddx)

Upgrading to the latest bug fix code is simple because you don't have to upgrade only driver packages. First it is good idea to upgrade xf86-video-ati that provide 2D and mode setting code for xserver. You will need to clone git repository from anongit.freedesktop.org. 

git clone git://anongit.freedesktop.org/xorg/driver/xf86-video-ati

Now you have cloned the git repository but code that was checked out is master branch which includes the bleeding edge code changes. But the target was to have stable updates so next step is to checkout the stable branch. You can check remote brances with git branch -r but current stable branch is 6.12-branch. We create local branch that tracks remote changes for easy of updating the source later. 

git checkout -b 6.12-branch origin/6.12-branch

This way you can easily switch back to the master branch or other branches if you want to try those. To download and track only one specific branch, in this case 6.12-branch, use the following steps. 

mkdir xf86-video-ati
cd xf86-video-ati
git init
git remote add -t 6.12-branch -m 6.12-branch origin git://anongit.freedesktop.org/xorg/driver/xf86-video-ati
git pull

Now you have to install build dependencies for driver. Your package manager should have easy functionality for installing all the necessary packages. But for example there is: 

Debian/Ubuntu: apt-get build-dep xserver-xorg-video-ati
Fedora: yum-builddep xserver-xorg-video-ati

Now you have to configure and build the code like any other program. It is good practice to install driver without overwriting files installed by package manager. This can be done using few configuration option. We want to install driver to a clean place where it is easy to remove in case you want to get rid of it. 

./autogen.sh --prefix=/opt/xorg && make && sudo make install

Then you need to add configuration instruct xserver to load your self compiled driver. Adding following lines to xorg.conf will do the trick. 

Section "Files"
        ModulePath "/opt/xorg/lib/xorg/modules,/usr/lib/xorg/modules"
EndSection

Now restart your xserver and have fun with new bug fixes :)

Mesa (3D)

The Mesa library provides OpenGL with software and hardware rendering. There are also more libraries related to hardware accelerated graphics. Installing mesa to a location outside /usr is a bit more tricky. Problem here is that it is hard to make AIGLX load the dri driver from a non-system location.

Download the latest source code using git is simple matter of cloning the repository. 

git clone git://anongit.freedesktop.org/git/mesa/mesa

There are multiple stable threads depending on your distribution so you should check your mesa version with glxinfo | grep OpenGL. Branches are named mesa_X_Y_branch where X and Y are replaced with your mesa version number. As an example we use the latest stable branch. That is 7.5. 

$ glxinfo | grep OpenGL
...
OpenGL version string: 1.3 Mesa 7.5
...
$ git checkout -b mesa_7_5_branch origin/mesa_7_5_branch

Now you need again build dependencies which you should install for package libgl1-mesa-dri (See the example above). After you have installed all build dependencies we have to configure, build and install mesa. Prefix is again /opt/xorg for easy clean up if something goes wrong. You can of course use what ever you prefer. Example case enables all radeon dri drivers but you would only need driver for your own card and swrast for software fall back in case of problems with dri driver. 

./configure --prefix=/opt/xorg --with-dri-drivers=radeon,r200,r300,r600 --disable-gallium && make && sudo make install

Remember to read the instruction how to configure loading of new driver

Configuring system to load mesa and libdrm from /opt/xorg

Now comes the tricky part because you have to configure your system to load correct librariries when any application tries to load them. You have to configure ld to load first from /opt/xorg/lib so custom mesa libraries are loaded. Another tricky part is to load dri driver which requires environment variable set to point to /opt/xorg/lib/dri.

/etc/ld.so.conf.d/a-local-xorg.conf (new file) or add to begin of /etc/ld.so.conf if directory doesn't exists. 

/opt/xorg/lib

and to /etc/environment you need to add new environment variable that tells libgl where to look for dri drivers (example r300_dri.so) 

LIBGL_DRIVERS_PATH=/opt/xorg/lib/dri/

After changes to the files you have to restart your system to make ld reload configuration. Tips to do the reload of /etc/environment and ld.so.conf in running system are welcome.

You can now test new dri driver in a terminal if you export LIBGL_DRIVERS_PATH. If everything works you can now restart to load new settings for all applications.

Problem with this configuration is that AIGLX doesn't respect it. This means that compiz doesn't get advantage of new driver.

Possible problems

Distribution packages have often extra patches applied which might break compatibility with git sources. In that case you would have to get distro patches and apply them on top of source from git.

Checking for hardware 3D acceleration

glxinfo will give details about OpenGL rendering. Old fashioned guides for checking firect rendering is a long outdated because swrast software rasterizer can do direct renering. 

glxinfo | grep OpenGL

Important part of output is renderer string that should read Mesa DRI <dri driver> <details> 

OpenGL renderer string: Mesa DRI R200 (RV280 5C61) 20090101 x86/MMX+/3DNow!+/SSE TCL DRI2

While software will output: 

OpenGL renderer string: Software Rasterizer

Removing Catalyst/fglrx

You have to first remove fglrx because it overwrites our userspace files and conflicts with our kernel modules. Maybe some day drivers can coexists but not yet :/

First remove all fglrx packages and check that fglrx.ko is not left in /lib/modules/uname -r. If it is there you can just rm it and do depmod -a.

Next step is to reinstall mesa and libdrm. Which should be handled easily by your package manager or make install.

Last but not least is removing fglrx configurations from xorg.conf. With xserver 1.6 or higher you can just rename xorg.conf and trust the auto detect to do the right things.

Now you can reboot to clean system when open driver can function correctly.

Updating git tree

Updating git repository has two phases. First part is downloading changes and updating the history data for git. Second part is updating your local branch to match remote changes. 

git fetch && git rebase origin

If you have any build problems after updating your source code run make clean and autogen.sh.

Removing self compiled driver

If you at any reason want to get rid of your self compiled driver it is simple as removing the configuration option from xorg.conf, /etc/ld.so.conf.d/ and environment. Then you can just restart computer and you are back at using the driver from package manager.

Removing the extra libraries is also easy with rm -r /opt/xorg.

Bleeding edge code from development branch

You will most likely have to upgrade a lot of stuff depending on how fresh your distro is. But minimum requirement is to have the latest xserver from the latest stable branch, latest stable kernel (some features might be only in rc kernels), libdrm master, mesa master and xf86-video-ati master.

Compiling and configuration is similar to stable branch with few exceptions. 

export PKG_CONFIG_PATH=/opt/xorg/lib/pkgconfig:/opt/xorg/share/pkgconfig
export LDFLAGS=-L/opt/xorg/lib CPPFLAGS=-I/opt/xorg/include
export ACLOCAL="/usr/bin/aclocal -I /opt/xorg/share/aclocal"

Packages for distributions

Some distributions provide easy way to install development version of all required packages from single source. This makes beta testing a lot easier when you can get fresh packages without recompiling everything.

Kernel mode setting (KMS)

Kernel mode setting moves a lot of graphics card control logic to kernel which makes it possible to write more advanced 3D and 2D drivers. Kernel side mode setting improves VT switching and provides full resolution console.

KMS also moves DRI infrastructure to version 2 which will provide better performance for 3D drivers in future. But as always is case in large rewrite of basic infrastructure performance will go down at first because of missing features and not optimized code.

Current features in kernel side are

After mode setting and memory management part has been finished there will be work to make dynamic power management work.

Kernel mode setting for r100-r500

Basic requirements are

Also might be needed depending on how fresh distro packages are

Order of build and installing packages should be:

Build order is important because first in list are required by later once to correctly build the latest development code. They will compile without too but then KMS support is most likely disabled which will cause problems when you try to boot with KMS.

It is good to have user space drivers ready before you move to new kernel. New user space drivers do work with old kernel but old user space doesn't work with new kernel (except with radeon.modeset=0).

There is huge effort to provide features to driver which causes all the time changes to all components. So if getting any build or runtime problems it is good idea to check that all of them are using latest code. Also make clean is important to guarantee that no old code is used.

If you have problems see Troubleshooting KMS problems.

Kernel mode setting and 3D for r600/r700

You need same user space drivers as for older cards. That means mesa master, libdrm master and ddx master. But kernel has to be from Dave Airlied's drm-next branch that will be merged to 2.6.32.

Best way to get working 2.6.31 kernel with drm-next bits added to it is to have git clone from Linus' tree. Then you have to create local branch for 2.6.31 to work with it. Lastly pull drm-next into the stable kernel. 

# Clone the official stable tree. You can also use existing tree where you just create the new branch
git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-2.6.31.y.git
cd linux-2.6.31.y
# Create your local working branch with name radeon_kms
git checkout -b radeon_kms origin/master
# Setup  remote for drm-next
git remote add -t drm-next airlied_drm_remote git://git.kernel.org/pub/scm/linux/kernel/git/airlied/drm-2.6.git
# Now we just have to pull the drm-next changes from Airlied's tree
git pull airlied_drm_remote drm-next
# Now hopefully merge will operate without conflicts.

You will have to enable staging drivers and radeon kernel mode setting from there to get the correct drm driver build.

How to build kernel is not part of this guide because it is distribution specific. You should check your distribution documentations for guide.

3D works still better without KMS in DRI1 mode. So you might want to pass modeset=0 parameter for radeon module.

Updating the source

Updating both remotes happens just with 2 simple commands. They fetch new commits from remote repositories and then merge the changes to your "working branch". 

git pull airlied_drm_remote drm-next
git pull origin

Creating patch from drm-next changes

git diff origin/master HEAD

alternatively use drm-next as is

Here is example git commands to get right branch from tree. 

git clone git://git.kernel.org/pub/scm/linux/kernel/git/airlied/drm-2.6.git
cd drm-2.6
git checkout -b drm-next origin/drm-next

List of active branches in drm-2.6.git

See http://article.gmane.org/gmane.comp.video.dri.devel/40626

Troubleshooting KMS problems

First of all check that you don't load radeonfb, uvesafb or vesafb module. This includes no vga parameters for kernel when using KMS. Console is provided by fbcon and radeondrmfb frame buffer console. So it is best to make sure that fbcon module is loaded.

If you can't boot with KMS on easiest way to debug problems is to boot with radeon blacklisted to text console and then load radeon module with modprobe (preferable over ssh).

Sometimes you have to manually enable or disable mode setting using radeon.modeset=[01] kernel parameter from grub. This helps testing if bug is in new mode setting code or somewhere else if you have hard problems to debug. Good place to put persistent parameters for radeon module is /etc/modprobe.d/radeon.conf.

AGP cards have a lot of problems so if you have one it is good idea to test PCI/PCIE mode using radeon.agpmode=-1. Another common solution to agp problems is disabling accelerated download from screen. You can see details with man exa how to do this.

Acceleration disabled and your xorg.log has error 

(EE) RADEON(0): [dri] RADEONDRIGetVersion failed because of a version mismatch.
[dri] radeon kernel module version is 2.0.0 but version 1.17.0 or newer is needed.
[dri] Disabling DRI.

Your xf86-video-ati doesn't have support for KMS. You have to rebuild it against libdrm_radeon (libdrm configured with --enable-radeon-experimental-api). This also means that you have to rebuild mesa against same new libdrm because mesa doesn't have KMS support without libdrm_radeon either. Also check that you have correct versions of all components.

Troubleshooting Extra Firmware for R600/R700

Some R600/R700 gfxcards need extra firmware (ucode) files [1] to work properly. According to license issues [2] and the fact that no new firmware files will be shipped in upstream kernels, you need to activate the following kernel-config parameters: 

CONFIG_FIRMWARE_IN_KERNEL=y
CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware"
CONFIG_EXTRA_FIRMWARE="radeon/R600_rlc.bin radeon/R700_rlc.bin"

Copy R600_rlc.bin and R700_rlc.bin to /lib/firmware/radeon directory.

[1] http://people.freedesktop.org/~agd5f/radeon_ucode/ [2] http://people.freedesktop.org/~agd5f/radeon_ucode/LICENSE.radeon [3] http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg45531.html

Reporting bugs

If problem is 3D relate correct place to report it is https://bugs.freedesktop.org/enter_bug.cgi?product=Mesa.

Because driver is split between DDX and Mesa all 2D and xv related problems should be reported to https://bugs.freedesktop.org/enter_bug.cgi?product=xorg.

You should include xorg.log and dmesg at minimum. Also exact steps to reproduce the problem will help a lot in solving the problem. Any extra debugging info you have gathered is welcome too. Please select text/plain mime type for any text attachments so they are easier to read.

Debug symbols are important when submitting backtraces so you should take little bit time to install them. There is usually easy way to install them from distribution provided packages. Minimum for debug symbols is mesa, ddx and xorg core to give easily readable backtraces.