MmioTraceHowto

These are instructions to trace Nvidia's proprietary driver for Nouveau reverse engineering effort. More information about mmio-trace can be found on the page MmioTrace.

Before following this howto, take a look at the usage notes.

HowTo

  1. Get an up-to-date copy of the mmio-trace git repository's master branch.

    • git clone git://people.freedesktop.org/~pq/mmio-trace

    • cd mmio-trace

    • The default active branch is master so you do not need to change it.

  2. Make sure your kernel has DebugFS (CONFIG_DEBUG_FS) and RelayFS (CONFIG_RELAY) enabled. You can try the command zcat /proc/config.gz | grep "CONFIG_DEBUG_FS\|CONFIG_RELAY" or grep "CONFIG_DEBUG_FS\|CONFIG_RELAY" /boot/config-`uname -r` # on debian. If not:

    1. Get a copy of a the Linux kernel source code, versions 2.6.19 - 2.6.23 are preferred. Versions 2.6.24 and 2.6.25 should also work, but you have to patch the kernel and this guide does not completely apply (see MmioTrace). Versions prior to 2.6.19 are not supported.

    2. Configure your kernel, enable DebugFS (CONFIG_DEBUG_FS) and RelayFS (CONFIG_RELAY)
      • To find these options in menuconfig, hit / and as search term use DEBUG_FS and RELAY, respectively. Some of them might have dependencies shown on the search page which need to be enabled first, you can search for them the same way.
    3. Build and install your kernel, reboot.

  3. If you have a SMP system, specify maxcpus=1 on the kernel command line when booting, or disable all but one CPU via the sysfs interface (disabling a cpu is done with echo 0 > /sys/devices/system/cpu/cpu<number>/online, and reenabling is with echo 1 > /sys/devices/system/cpu/cpu<number>/online)

  4. Build the nvidia blob for the kernel if you didn't already do so. Make sure the nvidia module is not loaded (lsmod). You can unload it (and later also the hooked module) with rmmod nvidia. (You must not be running X to unload it.)

  5. Build mmio-trace (just call make in the directory)

  6. Hook the nvidia module

    • e.g. ./hook-module /lib/modules/2.6.20-rc6-kmmio/nvidia/nvidia.ko nvidia-hook.ko (where . is the source directory of mmio-trace)

  7. Mount debugfs to /debug

    • mkdir -p /debug

    • mount -t debugfs debugfs /debug

  8. load the mmio module

    • insmod mmio.ko

  9. Start ./mmio-trace, it will create file cpu0 on the current directory, and the file will grow fairly fast after you start X.

  10. load the hooked nvidia module

    • insmod nvidia-hook.ko

  11. Start Xorg, run glxgears for a few seconds, and quit Xorg. Now you have a trace, and all that is left is to shut down tracing.

  12. Unload the hooked module: rmmod nvidia

  13. Kill the mmio-trace process. Ctrl-c, for instance.

  14. Unload mmio module: rmmod mmio

Steps 3, 4, 7-10, and 12-14 require root privileges.

You should have a file called cpu0 in the directory in which mmio-trace was running. This file is text (you can view it if you like) and it compresses considerably. Previously you were required to run mmio-parse on this file, but not anymore.

Sending results

If you want to send mmio-trace dumps to us, please send them to mmio dot dumps at gmail dot com. Please, pack into a compressed archive the cpu0 file and a free description about what you do during the trace. The output of lspci is already included in the cpu0 file, but do add the output of uname -a and the driver version into your description. Tell also what display connectors you have, what kind of monitors you have connected to what outputs, whether it has tv-in/out, and what display mode you used. The name of the archive file should contain the PCI id and GPU family, or the commercial name of your card. Thank you.