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

Stefan Wahren
2025-05-16T10:55:15Z

Hi,

[add Jonathan & linux-doc]

Am 10.05.25 um 00:11 schrieb Stefan Wahren:
> 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>
I sent this series as RFC because I don't know if this is the right
place and/or form of IOCTL documentation for a staging driver.
> ---
> .../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.