Using renouveau

How does the video card work?

NVidia hardware has multiple FIFOs (also called a "channel"). Each FIFO has a 8 "slots" (or "subchannels") to which you can assign objects. A command in a DMA buffer says what subchannel the command is for, and the combination of the offset in the command and the object bound to the subchannel determines what the GPU does.

There are multiple ways for the CPU to send graphics commands to a video card.

• The fastest one is the use of a fifo. This fifo is nothing more than a chunk of memory which contains commands in a format suitable for the video card. In order to control the video card, the CPU writes commands into that fifo, and tells the card to execute them. In odrer to write a driver, we need to find out what commands we need to write in a fifo to achieve the functionality we want. The fifo area is displayed by renouveau as "=> fifo" ("=> quadro fifo" in case of a quadro card)
• Another technique is the use of memory mapped registers (MMIO). Once again, these registers are just seen as a piece of memory. Each register is one word in that piece of memory, contains a value, and has a meaning. In order to write a working driver, we also have to take care of putting the right values in the right registers at the right time. The register areas are displayed by renouveau as "=> registers".

main.c basically initializes everything (from SDL to the mappings of the card into the program's address space and then calls a test function like test_default(). All tests can be found in test.c, let's have a look at the default test, which simply draw a triangle on the screen.

   void test_default(void)
   {
      TEST_PROLOGUE;
      printf("Testing default state of OpenGL context\n");
      dump_before();
      tri();
      dump_after();
      TEST_EPILOGUE;
   }

So basically in order to figure out new functionality using renouveau, a simple scheme can be followed :

• call dump_before()
• call OpenGL commands that trigger the functionnality you're looking for
• call dump_after()
• look at the changes, and try to make sense out of them. Retrying multiple times is almost mandatory before being able to make sense out of the data, and sometimes using small variations in the OpenGL commands (for example, changing a vertex color or position) can help. If you dump into different files, you'll be able to use diff or kompare (KDE) to look only for the differences.

Format of the fifo

Although registers don't have a rigid format (it's just an array of values), the fifo contents has a strict packet format described as follows :

• a 32 bit header containing the command type, the command size and the channel number as follows : ((size) << 18) | ((channel) << 13) | (command_type))
• a number of 32 bit values which are the actual data.

For example, {0x00043808,0x00000005} can be interpreted as follows :

• The header is 0x00043808
  

           0x00043808 = 0x00040000 | 0x00002000 | 0x00001808
                      = (1<<18)    | (1<<13)    | 0x00001808
  

  So here, the packet carries 1 dword (or 4 bytes) of data, is sent to channel 1, and is of type 0x1808. It turns out that 0x1808 almost means glBegin()
• The data is 0x00000005 here which means GL_TRIANGLES

A sample renouveau dump

So, you have everything compiled, have your research topic selected but still need some help? Well first go to main.c comment in the call to test_default() and decomment the test you are looking for. Compile it and run it:

br:~> ./renouveau >mydump1

Depending on the kind of test you choose, the output will be quite long, so better dump it to a file.

Now, let's say you have chosen test_clip_plane(), which defines parameters for 1 - maxClipPlanes and enables all clip planes, which were defined.

if you are using a Gforce 6600 you would see something like this (reduced to the output of 1 plane):

f96   0x00000000   0x0000002c   NV30_TCL_PRIMITIVE_3D_VP_UPLOAD_CONST         = 0x0000002c
f97   0x00000000   0x00000000            NV30_TCL_PRIMITIVE_3D      [0x1f00/4] = 0x00000000
f98   0x00000000   0x3c23d70a            NV30_TCL_PRIMITIVE_3D      [0x1f04/4] = 0x3c23d70a | UNKNOWN = 3c23d70a
f99   0x00000000   0x3ca3d70a            NV30_TCL_PRIMITIVE_3D      [0x1f08/4] = 0x3ca3d70a | UNKNOWN = 3ca3d70a
f9a   0x00000000   0x3cf5c28f            NV30_TCL_PRIMITIVE_3D      [0x1f0c/4] = 0x3cf5c28f | UNKNOWN = 3cf5c28f
...
fb9   0x00000000   0x00043478             {size: 0x1   channel: 0x1   obj: beef3097 opcode: METHOD }
fba   0x00000000   0x00000002            NV30_TCL_PRIMITIVE_3D      [0x1478/4] = 0x00000002 | UNKNOWN = 00000002

We are looking for some unknown command, often called NV30_TCL_PRIMITIVE_3D (Family name may change). If you compare the data from f97 to f9a with the data the test will send to the card, it becomes clear, that 0x00000000 = 0.0f, 0x3c23d70a = 0.01f, 0x3ca3d70a = 0.02f and 0x3cf5c28f = 0.03f, exactly the data, the program sent for plane 0. [0x1478/4] is still unclear, but could have something to do with the enabling of the clip plane.

Please note:Since I wrote the doc, the code changed somewhat, this is how the code looked like at the time:

void test_clip_plane()
{
	TEST_PROLOGUE;
	int i, j, m;
	GLdouble planes[4*6]={
		0.0, 0.01, 0.02, 0.03,
		0.04, 0.05, 0.06, 0.07,
		0.08, 0.09, 0.10, 0.11,
		0.12, 0.13, 0.14, 0.15,
		0.16, 0.17, 0.18, 0.19,
		0.20, 0.21, 0.22, 0.23
	};
	printf("Clipping planes after short vertex program test\n");
	regl.GetIntegerv(GL_MAX_CLIP_PLANES, &m);
	printf("%d clip planes available\n", m);
	for (i=1; i<=m; i++) {
		printf("%d clip planes.\n", i);

		dump_before();
		for (j=0;j < i;j++) {
			regl.Enable(GL_CLIP_PLANE0+j);
			regl.ClipPlane(GL_CLIP_PLANE0+j,&planes[j*4]);
		}
		tri();
		for (j=0;j<i;j++) {
			regl.Disable(GL_CLIP_PLANE0+j);
		}
		dump_after(0);
	}
	TEST_EPILOGUE;

}
   

If you look at the enabling of the second plane further down, you will see again the same lines from above, but with a difference:

10fd   0x00000000   0x0000002c   NV30_TCL_PRIMITIVE_3D_VP_UPLOAD_CONST         = 0x0000002c
10fe   0x00000000   0x00000000            NV30_TCL_PRIMITIVE_3D      [0x1f00/4] = 0x00000000
10ff   0x00000000   0x3c23d70a            NV30_TCL_PRIMITIVE_3D      [0x1f04/4] = 0x3c23d70a | UNKNOWN = 3c23d70a
1100   0x00000000   0x3ca3d70a            NV30_TCL_PRIMITIVE_3D      [0x1f08/4] = 0x3ca3d70a | UNKNOWN = 3ca3d70a
1101   0x00000000   0x3cf5c28f            NV30_TCL_PRIMITIVE_3D      [0x1f0c/4] = 0x3cf5c28f | UNKNOWN = 3cf5c28f
1102   0x00000000   0x00143efc             {size: 0x5   channel: 0x1   obj: beef3097 opcode: METHOD }
1103   0x00000000   0x0000002d   NV30_TCL_PRIMITIVE_3D_VP_UPLOAD_CONST         = 0x0000002d
1104   0x00000000   0x3d23d70a            NV30_TCL_PRIMITIVE_3D      [0x1f00/4] = 0x3d23d70a | UNKNOWN = 3d23d70a
1105   0x00000000   0x3d4ccccd            NV30_TCL_PRIMITIVE_3D      [0x1f04/4] = 0x3d4ccccd | UNKNOWN = 3d4ccccd
1106   0x00000000   0x3d75c28f            NV30_TCL_PRIMITIVE_3D      [0x1f08/4] = 0x3d75c28f | UNKNOWN = 3d75c28f
1107   0x00000000   0x3d8f5c29            NV30_TCL_PRIMITIVE_3D      [0x1f0c/4] = 0x3d8f5c29 | UNKNOWN = 3d8f5c29
1108   0x00000000   0x00143efc             {size: 0x5   channel: 0x1   obj: beef3097 opcode: METHOD }
...
1121   0x00000000   0x00000022            NV30_TCL_PRIMITIVE_3D      [0x1478/4] = 0x00000022 | UNKNOWN = 00000022

Ok, a new row of values under a new NV30_TCL_PRIMITIVE_3D_VP_UPLOAD_CONST. Yes, that is the data the program sent for plane 1 and [0x1478/4] changed to 0x00000022. Seems as if bit 1 (3) is enabling plane 0 (plane 1). So time to check for the other planes, too...

Help, I can't figure it out

If there is no deducable pattern in the output, please verify:

• Don't change driver versions midway through testing
  Different versions of the driver may issue different commands
• Keep the rendering window always on the same position:
  e.g. Viewports have offsets, which are dependant on the window's position on screen. Use export SDL_VIDEO_WINDOW_POS=x,y to define the window position before running renouveau
• Don't change the Window decorations
  Changing that may change the offset of the rendering window. It may be useful, to add SDL_NOFRAME to the SDL_SetVideoMode() call.
• Don't change color depth of X11
  Running they same test under 16bpp or 24bpp will change the output of of commands.
• Don't use different video cards
  Always use the same card during a test session. a GForce 5x00 adn GForce 6x00 may / will use different commands. If you can do the test on a different card to verify your findings, or compare the differences, that's good.
• If the number of commands seems overwhelming and you can't find the "real" start for your test, try enabling both test_startup() and test_default() this should reduce the initialisation parts of your test. Just look for the output of the test start like in test_display_list() "creating a display list.".

Still no idea? Except for changing the GPU, try the tricks from above, they may give you some clues.

If you are sure about your findings, report back to the developers, they will tell you what to do next (Hint: a patch would probably be welcome)

---