vcio2 programming guide

▲ Top, ▼ Migrating vcio applications, ▼ Concurrent use of vcio2, ▼ Sample code, ▶ API reference

Use the GPU with vcio2

  1. Open /dev/vcio2 with open.
  2. Allocate an appropriate amount of GPU memory with IOCTL_MEM_ALLOCATE.
    You should allocate large amounts of GPU memory in smaller chunks to avoid fragmentation of free GPU memory.
  3. Lock the memory segment with IOCTL_MEM_LOCK.
  4. Map the memory with mmap.
  5. Place the shader code, the uniforms and the control blocks into the allocated GPU memory. Don't forget that the GPU only accepts physical addresses and cannot access the applications memory.
    Although the GPU can access all physical memory there is no reasonable way to use application memory directly, since it may be fragmented in physical memory and the GPU cannot use scatter gather lists.
  6. Run your code on the GPU with IOCTL_EXEC_QPU.
    Use an appropriate timeout. This will recover from GPU crashes in most cases.
  7. Repeat the last two steps as needed.
  8. Close the device when you don't need it anymore. This releases all GPU memory allocated by this handle.

See sample program for further details.

See also vc4asm for a powerful and free QPU macro assembler.

Migrating from hello_fft style mailbox

If you have an application that uses the old vcio driver, e.g. hello_fft, you need to do the following steps to migrate to vcio2:

  1. Copy mach/vcio2.h to your source files.
  2. Replace the files mailbox.h and mailbox.c with the ones from the sample directory.
  3. Adjust include path of vcio2.h in mailbox.c.
  4. Comment all occurrences of calls to qpu_enable. They are deprecated.
  5. Add an additional first parameter with the device handle returned from mbox_open to any call to mapmem.
  6. Compile and run.

Now you application should use the new kernel driver it does no longer require root privileges to run if you grant access to /dev/vcio2.

Using vcio2 concurrently

The vcio2 device may be opened as often as you like. The only limiting factor is the amount of GPU memory available.

Calls to IOCTL_EXEC_QPU are strictly serialized. So no two applications can run code on the GPU simultaneously. However, they can run code alternately.

You should not use the /dev/vcio device or a character device of the built-in vcio driver concurrently to /dev/vcio2. The calls to this devices are not understood by vcio2 and may seriously interfere with /dev/vcio2 access. E.g. the application using /dev/vcio might disable the power of the GPU while another application is running GPU code. Future versions of vcio2 might lock the other devices while /dev/vcio2 is open at least once.
This restriction does not apply to calls that are independant, e.g. reading the GPU memory size or even GPU memory allocations. The vcio2 driver and the vcio driver share a common mutex for this purpose. Only indirect dependencies are not tracked.

There are no more restrictions that I know of.

Sample application

In the sample folder there is a simple sample application that utilizes the vcio2 device. It does some stupid computations by applying all available QPU operators to a bunch of constants.

How to build

Now the test application should print some pages of results to the console. Of course, you need to install the vcio2 driver before.