View source for Unit VC4VCHIQ

Return to [[Unit_Reference|Unit Reference]]


=== Description ===
----

'''Ultibo Broadcom VideoCoreIV VCHIQ driver unit'''

'''VCHIQ Driver'''

VCHIQ is the VideoCore Host Interface driver which implements a messaging interface between the host running on the ARM CPU and the VC4 GPU firmware.
 
The format and content of the messages that are passed is not defined by this driver but can be found throughout the various libraries that make up the userland interface and ultimately expose standard interfaces such as OpenGL ES, OpenVG and OpenMAX IL.
 
There is no specific documentation for the VCHIQ messaging protocol or behaviour and all of the information for this driver has been obtained directly from the equivalent Linux driver. The protocol basically uses a series of memory based slots that form a circular buffer, both the master (GPU) and slave (CPU) side have their own set of slots which they write data into whenever a new message is to be sent. The other side then receives messages from those slots and signals when processing has completed so that the slot can be freed.
 
All requests from higher level interfaces are received in the form of IO control requests which are then formed into VCHIQ messages and submitted. The driver uses multiple threads to perform the message passing process, the primary ones being a slot handler thread and a slot recycle thread.
 
Because the VideoCoreIV firmware for the Raspberry Pi is under active development and future revisions may change the details of the communications between the ARM CPU and the VC4 GPU, this driver has been written to retain many of the structures used by the original Linux driver and allow easier updating in response to changes. Because of this the driver may look unusual in relation to other Pascal code and other Ultibo drivers however the functionality is as required in order to perform the task.
 
Note: The meaning and purpose of some values in this driver are unknown, the values are ported directly from the Linux driver and no other source of documentation exists.
 
Not all of the defined constants and types are required for this driver, some are made available as imports for the VC4 unit because they are identical to the definitions of the interface used by applications to communicate with VCHI or VCHIQ services using the libvchiq_arm interface.

For the available documentation of the functions supported by this unit please see:

* VideoCore APIs - http://elinux.org/Raspberry_Pi_VideoCore_APIs

* Raspberry Pi Userland - https://github.com/raspberrypi/userland
 
* VideoCore IV Documentation - https://docs.broadcom.com/docs/12358545
 
''Implementing VCHIQ in 64-bit''
 
Because the implementation of VCHIQ shares multiple structures between the ARM and the VC4 it is essential that the sizes of those structures do not change when compiling this driver for 64-bit. Of particular interest are things that refer to a memory address (a pointer) or things that are otherwise adjusted in size when changing between 32 and 64-bit.
 
One item of note in the Ultibo implementation is the THandle which is defined as LongInt in 32-bit but as Int64 in 64-bit. Some structures such as REMOTE_EVENT_T contain a TSemaphoreHandle which will need to be accounted for in the change. Potentially some form of table needs to be maintained in order to translate between a value and a handle in order for the structure member to remain the correct size.
 
At present this driver will not function correctly in 64-bit, however the userland library will also not function in 64-bit yet either. The same is true for VCHIQ and userland on the official Raspbian distribution.

=== Constants ===
----

''Refer to the available documentation links above''

=== Type definitions ===
----

''Refer to the available documentation links above''

=== Public variables ===
----

''Refer to the available documentation links above''

=== Function declarations ===
----

''Refer to the available documentation links above''


Return to [[Unit_Reference|Unit Reference]]