vcio2 - Kernel driver to access Raspberry Pi VideoCore IV GPU without root privileges

When using Raspberry Pi's GPU from user space (e.g. hello_fft) with the built-in vcio driver in the RPi kernel you need to have root privileges for every application.
The goal of the vcio2 driver is to overcome this restriction. Furthermore vcio2 keeps track of the resources and performs some clean-up if the application is interrupted.

▼ Features & Limitations, ▼ Installation instructions, ▶ Sample code, ▶ Programming guide, ▶ API reference, ▼ Contact

Download & history

Download DKMS kernel module, an example and this documentation or view source code @ github

V0.3

Added advanced API for memory allocation/release.
Fixed invalid memory mappings after automatic release of GPU memory.

V0.2

Rewrote the driver to support newer RPi kernels.
Added performance counter support.

V0.1

First public release.

Features

• No root privilege required to use the GPU.
• Automatic cleanup of resources like GPU memory on application termination, e.g. crash or SIGBREAK.
• Share the GPU by multiple applications.
• Enable and disable the GPU automatically.
• Read performance counters.
• Some protection against invalid memory access.
• Supports Raspberry Pi models: RPi 1, RPi 2, RPi 3, RPi Zero (all variants)

Limitations

• vcio2 does not validate the shader code. It is still a major security issue to permit users to use the vcio2 device. It just protects against some accidental misbehavior. This will never change, since VideoCore IV has no MMU. But access to vcio2 is no more risky than access to the vcio device that Raspbian grants to the video group by default as well.
• Power management events (e.g. ARM clock changes) are blocked during execution of GPU code.
  This is an restriction of the RPi firmware. It simply uses the same mailbox channel for system health and GPU execution.
• No two applications can run GPU code concurrently even if they do not use all QPUs.
  This is due to some global GPU resources like semaphores that cannot be reasonably shared.
• vcio2 is incompatible to rpi-update. This is due to the fact that rpi-update does not provide kernel headers and therefore is incompatible to dkms.

TODOs, known problems

• Power off the QPU after execution timeouts for better error recovery.

Installation instructions

Prerequisites

• Install dkms package if not yet done. (sudo apt-get install dkms)
• Install Linux kernel headers. (sudo apt-get install raspberrypi-kernel-headers)
• In fact I only tested with kernel 4.19 so far but it is likely to work with other kernels too.

Build and install the driver

• Unpack the package above to some folder.
• Open a shell.
• Go to the folder where the files are extracted. (not to sub folder src)
• sudo make

Normally this should build the kernel module using DKMS, install it for the currently running kernel, setup the driver for autostart, load the driver and grant access to the group video. So it is ready to use immediately.

If it does not work, have a look at the error messages on the screen as well as /var/dkms/vcio2/0.2/build/make.log (compilation) and /var/log/syslog (loading).

Using the driver

As soon as the driver is loaded successfully, a new device /dev/vcio2 appears.

This is the new device which offers new features. Using this device requires changes to the source code of the application. See the API reference and especially the migration guide.

See vcio2 programming guide for further details.

If someone thinks that it should be part of the RPi kernel and knows how to contribute, let me know.

Remove the driver

• Open a shell.
• Go to the folder where the files are extracted. (Not to sub folder src)
• sudo make remove

This will unload the kernel module and uninstall it.

Contact

Comments, ideas, bugs, improvements to raspi at maazl dot de.