Given the major focus of this commit is the inclusion of full support for the VideoCore IV GPU and hardware accelerated graphics then almost everything else will likely be somewhat overshadowed, there have been many other fixes and changes as well and they are detailed below for reference.
This commit is accompanied by a new release of the Ultibo core installer, not only does this installer bring us to the Beetroot release it also includes more than 20 examples to get you started with using all of this new functionality.
List of changes:
- New VC4 unit to provide the necessary interface to the Userland libraries
- New VC4VCHIQ protocol driver to communicate with the VC4 firmware
- VC4V3D unit with definitions for most known registers
- Enable GLES11 and GLES20 units from the OpenGLES package to build for Ultibo
- Add DispmanX, EGL and OpenVG units to the Ultibounits package
- Add port of libShapes to the Ultibounits package
- Add new ConditionWait function for condition variables to wait without releasing a lock
- Add new SpinLockPreempt / SpinUnlockPreempt to call the correct spin lock for the current scheduler
- Fix build errors when USB_DEBUG defined
- Allow built-in USB Hub/Keyboard/Mouse/Storage drivers to be disabled using GlobalConfig variables
- Fix Syscalls open_r to pass ShareMode as FILE_SHARE_READ or FILE_SHARE_WRITE and allow simultaneous opens
- Fix USBDeviceBind to check for bound interfaces before trying to perform device bind
- Fix use of USB bNumEndpoints to allow for zero endpoints
- Fix CreateFile with CREATE_ALWAYS to obey FILE_SHARE_* options
- Update FileCreate function to support the overloaded version with ShareMode
- Implement new Completion object similar to Linux completions
- Fix nil pointer reference in pthread_create() function
- Change PageTableGetEntry to return entry as a var parameter instead of result
- Add new PageTableGetPageSize, PageTableGetPageFlags and PageTableGetPagePhysical functions
- Add Linux compatible msleep() function to Syscalls
- Fix size of Syscalls Tpthread_attr_t structure not matched to Newlib definition which caused stack corruption
- Allow Syscalls pthread_mutex / pthread_cond / pthread_rwlock functions to initialize an object on first use
- Add symlink, chmod, truncate and ftruncate functions to Syscalls
- Fix ThreadDestroy not removing thread from termination queue if destroyed early
- Add POSIX compatible socket functions to the Syscalls unit
- Update FPC linker script to include __preinit_array, __init_array, __ctors and __dtors for C and C++ support
- Fix PL2303, FTDISerial and USBCDCACM stop transmitting if buffer becomes full
VC4 and the Userland libraries
After many requests, a lot of discussion and a huge amount of reading and research we have completed the first known fully functional port of the VideoCore IV Userland libraries to a bare metal platform.
We should make it clear from the start that this is not any sort of radical reverse engineering of the VideoCore IV, quite simply we are just using the same interfaces that Raspbian uses to access this functionality, what that means is that the Ultibo support will remain current with all fixes and enhancements added by Broadcom and the RPF because we use the official interfaces and can take advantage of new features quickly.
There are multiple parts to the interface but essentially the Userland libraries provide all of the standard graphics interfaces such as OpenGL ES, OpenVG, OpenMAX IL and a number of less well known ones such as MMAL and DispmanX. All communication with the VideoCore IV GPU is handled by the VCHIQ protocol driver which has been directly implemented in pascal using Ultibo specific interfaces and functionality.
The feature set of these libraries is enormous so we haven't tested every function, however everything that has been tested works including OpenGL 3D graphics, OpenVG 2D graphics, OpenMAX multimedia interfaces such as video and audio playback and encoding and the Broadcom specific MMAL abstraction layer which not only provides multimedia functions but also directly interfaces to the official Raspberry Pi camera (both version 1 and version 2).
At this point there are still some outstanding items, we have not yet completed the VCSM (VideoCore Shared Memory) driver and associated interfaces so any attempt to use zero copy between pipeline components in an MMAL application will currently fail. As of now no Free Pascal interfaces are available to access either the OpenMAX IL or MMAL libraries, these are very large APIs with a significant amount of functionality so creating pascal translations will require some additional work.
There are also a number of smaller libraries and internal interfaces which we have not provided Free Pascal units for at this stage, some will be completed as work continues whereas others may be left to those who require them.
Of course the VC4 support works only with the Raspberry Pi (all models) because it relies on the hardware contained in the chip.
GLES11, GLES20, DispmanX, EGL and OpenVG
Because the VC4 unit and Userland libraries provide a complete implementation of several standard graphics APIs we have included Ultibo ports of the interfaces required to use them, both OpenGL ES 1.1 and 2.0 are available as well as OpenVG, EGL and DispmanX.
The GLES11 and GLES20 units are part of the OpenGLES package and the OpenVG, DispmanX and EGL units have been added to the Ultibounits package and are now available for use by default.
We’ve also included two pure pascal OpenGL ES examples that show all of the necessary steps to create an OpenGL ES application in Ultibo.
Port of libShapes to Ultibo
As part of the work to port the VideoCore IV interfaces to Ultibo we have also created a Free Pascal port of the shapes library by A J Starks, this is a very useful utility library for working with 2D vector graphics as it provides a host of predefined shapes that can be drawn with little more than a single function call.
The library also handles all of the details of setting up the required DispmanX and EGL handles and initializing OpenVG as well as providing a method to use almost any True Type font for displaying text on screen. You can make use of the new VGShapes unit by simply including it in your project, see the new OpenVG examples for the basics of getting started.
Refer to the project page on GitHub for more details and examples and a description of each of the available functions in the library.
While not anywhere near as exciting as the VC4 support, we have implemented a new completion object type to add to the extensive list of synchronization functions already included in Ultibo. This one was added specifically to support the VCHIQ driver which relies heavily on these objects but they are now available for any suitable purpose.
The new functions are all contained within the Threads unit and include the following:
- CompletionCreate - Create a new completion object
- CompletionDestroy - Destroy an existing completion object
- CompletionState - Get the current state of a completion object
- CompletionWait - Wait on a completion object
- CompletionTryWait - Try a completion object to see if it is completed but don't wait for it
- CompletionReset - Reset (uncomplete) the state of a completion object
- CompletionComplete - Set (complete) the state of a completion object and release one waiting thread
- CompletionCompleteAll - Set (complete) the state of a completion object and release all waiting threads
For details of how to apply the latest source to your Ultibo core installation and rebuild your run time library see the wiki page Building from Source or watch the Building the RTL video on YouTube.