V3DLib

Version 0.7.15

V3DLib is a C++ library for creating programs to run on the VideoCore GPU's of all versions of the Raspberry Pi.

Prior to the Pi 4, this meant compiling for just the VideoCore IV GPU. The Pi 4, however, has a VideoCore VI GPU which, although related, is significantly different. V3DLib compiles and assembles for both versions of the VideoCore GPU.

Kernel programs compile dynamically, so that a given program can run unchanged on any version of the RaspBerry Pi. The kernels are generated inline and offloaded to the GPU's at runtime.

Motivation for this Project

The Raspberry Pi's have pretty nifty on-chip capabilities for SIMD vector processing. It bothered me to no end that this is largely unused; the only thing really using it is OpenGL.

The goal of this project is to make the SIMD vector processing accessible for a larger audience, and to ease the pain of programming it.

Getting Started

Before trying to deal with any code, take a moment to view the Basics Page. This will supply you with a working model of the VideoCore and will facilitate your understanding.

Also, for starters, scan the naming conventions at the top of the Architecture and Design Page. Read the rest at your own leisure.

Compiling and Building

This assumes that you are building on a Raspberry Pi.

Please look at the Known Issues, so you have an idea what to expect.
For more extensive details on building, see Build Instructions.
Fair Warning: The first build can take a long time, especially on older Pi's. See the Build Instructions for details.

> sudo apt-get install git                                       # If not done already

> sudo apt install libexpat1-dev                                 # You need this for one lousy include file

> git clone --depth 1 https://github.com/wimrijnders/V3DLib.git  # Get only latest commit
> cd V3DLib
> make QPU=1 DEBUG=1 all                                         # Make debug versions with hardware
                                                                 # GPU support of all examples.
    
> make QPU=1 DEBUG=1 test                                        # Build and run the tests

Code Example

V3DLib contains a high-level programming language for easing the pain of GPU-programming. The following is an example of the language (the 'Hello' program):

#include "V3DLib.h"
#include "Support/Settings.h"

using namespace V3DLib;

V3DLib::Settings settings;


void hello(Int::Ptr p) {                          // The kernel definition
  *p = 1;
}


int main(int argc, const char *argv[]) {
  settings.init(argc, argv);

  auto k = compile(hello);                        // Construct the kernel

  Int::Array array(16);                           // Allocate and initialise the array shared between ARM and GPU
  array.fill(100);

  k.load(&array);                                 // Invoke the kernel
  settings.process(k);  

  for (int i = 0; i < (int) array.size(); i++) {  // Display the result
    printf("%i: %i\n", i, array[i]);
  }

  return 0;
}

Credit where Credit is Due

This project builds upon the QPULib project, by Matthew Naylor. I fully acknowledge his work for the VideoCore IV and am grateful for what he has achieved in setting up the compilation and assembly.

QPULib, however, is no longer under development, and I felt the need to expand it to support the VideoCore VI as well. Hence, V3DLib was conceived.

Useful Links

References

The following works were very helpful in the development.

VideoCore IV

The VideoCore IV Reference Manual by Broadcom. Errata.
The documentation, demos, and assembler by Herman Hermitage.
The FFT implementation by Andrew Holme. Blog

VideoCore VI

v3d driver code in the linux kernel repository - v3d in kernel on github. Of special interest: v3d_gem.c, v3d_drm.h. vc4 code is on same level
MESA v3d driver - github, vc4 on same level
py-videocore6 - Python project hacking the VideoCore VI
Broadcom code for v3d - relevant part, not sure if this is also for vc4, 2010 so probably no

Source doc for registers - contains registers not in the ref doc:
Broadcom VideoCore V QPU Instruction Set - translation
Notowaga example code - useful!
Linux doc for v3d - this is vc6

Tools

vcgencmd
doctest - unit test framework, Documentation links

wimrijnders / V3DLib