V3DLib
Version 0.2.8
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.
Recent Release Notes
- External library
CmdParameterhas changed. Please run./script/install.shwhen upgrading from a version <=0.0.8. - Upping the version - The API is still a moving target and keeps on breaking. Officially, I should be changing the major version continually, but with the project freshly released and having exactly two users, I consider this overkill. I'll up the minor version periodically as a compromise.
First Release
When I started this project, I resolved to release at the point that all examples would compile and run on the VideoCore VI. I have finally reached this point.
NOTE: This means that V3DLib has reached a level of mimimum viability. It is by no means feature-complete and can definitely use some refactoring and cleanup.
However, there are caveats.
There are some parts which will compile perfectly but not run properly; notably the Mandelbrot demo will run sometimes on a VideoCore VI, and otherwise hang. This is in part due to issues in the linux kernel, see the Issues page. There are also some unit tests which have the same problem, these are disabled when running on VideoCore VI.
I haven't been able to resolve these issues and I am waiting for a kernel update with fixes. All code for the VideoCore IV compiles and runs fine.
Credit where Credit is Due
This project builds upon the QPULib project, by Matthew Naylor. I fully acknowledge his work for the Videcore 4 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 Programming Language
V3DLib contains a high-level programming language for easing the pain of GPU-programming. The following is an example of the language (the 'Hello' example):
#include "V3DLib.h"
#include "Support/Settings.h"
using namespace V3DLib;
V3DLib::Settings settings;
// Define function that runs on the GPU.
void hello(Ptr p) {
*p = 1;
}
int main(int argc, const char *argv[]) {
auto ret = settings.init(argc, argv);
if (ret != CmdParameters::ALL_IS_WELL) return ret;
// Construct kernel
auto k = compile(hello);
// Allocate and initialise array shared between ARM and GPU
SharedArray array(16);
array.fill(100);
// Invoke the kernel
k.load(&array);
settings.process(k);
// Display the result
for (int i = 0; i < array.size(); i++) {
printf("%i: %i\n", i, array[i]);
}
return 0;
}
Getting Started
This assumes that you are building on a Raspberry Pi.
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
> git clone --depth 1 https://github.com/wimrijnders/V3DLib.git # get only latest commit
> cd V3DLib
# As long as the files don't change, you need to run this script only once.
> script/install.sh # Pull in and build external library
# After this, it's sufficient to do just the following line for a build
> make QPU=1 DEBUG=1 all # Make debug version with hardware
# GPU support.
> make QPU=1 DEBUG=1 test # Build and run the tests
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 - of special interest: v3d_gem.c, v3d_drm.h,
vc4on same level - MESA v3d driver - github,
vc4on 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
132 Dec 15, 2022
936 Jan 4, 2023
875 Jan 2, 2023
16 Nov 29, 2022
3 Jun 7, 2021
84 Dec 25, 2022
119 Dec 20, 2022
2 Jun 18, 2022
3 Aug 3, 2022
4.8k Jan 3, 2023
133 Dec 30, 2022
6.6k Jan 8, 2023
682 Dec 28, 2022
1 Nov 10, 2021
1.7k Jan 2, 2023
20.8k Jan 9, 2023
2 Jan 10, 2022
1 Oct 25, 2021
929 Jan 5, 2023
245 Dec 22, 2022