[PATCH RFC 2/2] staging: vc04_services: Document VCHIQ character device

Stefan Wahren
2025-05-09T22:12:05Z

From: Phil Elwell <phil@raspberrypi.com>

Document the IOCTLs for the VCHIQ character device, which provide
a userspace interface to access the VideoCore VPU of the
Raspberry Pi. Several ARM side libraries make use of it like EGL,
MMAL and OpenMAX.

Link: https://github.com/raspberrypi/linux/pull/6801
Signed-off-by: Phil Elwell <phil@raspberrypi.com>
[wahrenst@gmx.net: Rewrite commit log]
Signed-off-by: Stefan Wahren <wahrenst@gmx.net>
---
.../vc04_services/Documentation/vchiq-cdev | 87 +++++++++++++++++++
1 file changed, 87 insertions(+)
create mode 100644 drivers/staging/vc04_services/Documentation/vchiq-cdev

diff --git a/drivers/staging/vc04_services/Documentation/vchiq-cdev b/drivers/staging/vc04_services/Documentation/vchiq-cdev
new file mode 100644
index 000000000000..99ab2567643e
--- /dev/null
+++ b/drivers/staging/vc04_services/Documentation/vchiq-cdev
@@ -0,0 +1,87 @@
+What: /dev/vchiq
+Date: October 2016
+KernelVersion: 4.9
+Contact: kernel-list@raspberrypi.com
+Description:
+ The ioctl interface for the VCHIQ character device.
+ Following actions are supported:
+
+ * VCHIQ_IOC_CONNECT:
+ Establish/confirm the link to the VPU peer.
+
+ * VCHIQ_IOC_SHUTDOWN:
+ Close the link to the VPU peer, removing all services.
+
+ * VCHIQ_IOC_CREATE_SERVICE:
+ Create a VCHIQ service with the given FOURCC, registering a
+ callback. If is_open is true, attempt to connect to the same
+ FOURCC on the peer. If successful, populates the handle field
+ in the parameter structure, otherwise returns an error.
+
+ * VCHIQ_IOC_REMOVE_SERVICE:
+ Close and remove the service indicated by the provided
+ handle.
+
+ * VCHIQ_IOC_QUEUE_MESSAGE:
+ Adds the given in-band message for the indicated server to
+ the queue.
+
+ * VCHIQ_IOC_QUEUE_BULK_TRANSMIT:
+ Adds the given out-of-band bulk message for the indicated
+ service to the bulk queue.
+
+ * VCHIQ_IOC_QUEUE_BULK_RECEIVE:
+ Adds the given out-of-band bulk buffer for data from the
+ indicated service to the bulk queue.
+
+ * VCHIQ_IOC_AWAIT_COMPLETION:
+ The in-kernel API allows direct callbacks to client code.
+ Userspace clients rely on the equivalent of an RPC, with the
+ parameters for each callback marshalled into structures
+ called completions. This method blocks waiting for
+ completions to process.
+
+ * VCHIQ_IOC_DEQUEUE_MESSAGE:
+ Copy the next message for the indicated service, releasing
+ the space that was occupied. Optionally blocks if no message
+ is waiting.
+
+ * VCHIQ_IOC_GET_CLIENT_ID:
+ Retrieve an identifier for the client. This is intended to
+ allow instances of multiple services to be grouped. For
+ services provided by Linux the client ID is the pid. VPU
+ services have a client ID of 1.
+
+ * VCHIQ_IOC_GET_CONFIG:
+ Returns various properties of the VCHIQ configuration, such
+ as the maximum message size and version numbers.
+
+ * VCHIQ_IOC_CLOSE_SERVICE:
+ Cause a service to disconnect from the peer, returning it to
+ the closed/listening state, i.e. REMOVE_SERVICE but without
+ destroying the service.
+
+ * VCHIQ_IOC_USE_SERVICE:
+ * VCHIQ_IOC_RELEASE_SERVICE:
+ Use to mark the start and end of activity on a service. An
+ active service is intended to prevent the system from
+ suspending. N.B. Raspberry Pi devices that run VCHIQ do not
+ implement suspend/resume.
+
+ * VCHIQ_IOC_SET_SERVICE_OPTION:
+ Sets a number of per-service options: AUTOCLOSE, SLOT_QUOTA,
+ MESSAGE_QUOTA, SYNCHRONOUS mode and TRACE.
+
+ * VCHIQ_IOC_DUMP_PHYS_MEM:
+ No longer implemented.
+
+ * VCHIQ_IOC_LIB_VERSION:
+ Notify the kernel of the version of the userspace VCHIQ
+ library being used. Currently used to determine if the
+ CLOSE_DELIVERED ioctl is used, and therefore whether to
+ wait for the extra handshake on a close.
+
+ * VCHIQ_IOC_CLOSE_DELIVERED:
+ Signal that the userspace code has finished processing the
+ close. This additional handshake avoids a race on service
+ closure.
--
2.34.1