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.
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.
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.
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
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;
}
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.
The following works were very helpful in the development.
- The VideoCore IV Reference Manual by Broadcom. Errata.
- The documentation, demos, and assembler by Herman Hermitage.
- The FFT implementation by Andrew Holme. Blog
- 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
- vcgencmd
- doctest - unit test framework, Documentation links