[PATCH RFC 0/2] staging: vchiq_arm: Improve documentation

[PATCH RFC 0/2] staging: vchiq_arm: Improve documentation

[Stefan Wahren]

This series addresses the TODO about vc04_services documentation.
The first patch provides some inline documentation and the second
document the IOCTL of the VCHIQ character device.

Phil Elwell (2):
  staging: vchiq_arm: Improve inline documentation
  staging: vc04_services: Document VCHIQ character device

 .../vc04_services/Documentation/vchiq-cdev    | 87 +++++++++++++++++++
 .../interface/vchiq_arm/vchiq_arm.c           |  8 +-
 .../interface/vchiq_arm/vchiq_core.h          | 56 +++++++++++-
 3 files changed, 147 insertions(+), 4 deletions(-)
 create mode 100644 drivers/staging/vc04_services/Documentation/vchiq-cdev

-- 
2.34.1

[PATCH RFC 1/2] staging: vchiq_arm: Improve inline documentation

[Stefan Wahren]

From: Phil Elwell <phil@raspberrypi.com>

Add more comments to the VCHIQ driver, which provides some
high-level descriptions how things work.

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>
---
 .../interface/vchiq_arm/vchiq_arm.c           |  8 ++-
 .../interface/vchiq_arm/vchiq_core.h          | 56 ++++++++++++++++++-
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
index 5dbf8d53db09..40c540ead66b 100644
--- a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
+++ b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_arm.c
@@ -73,7 +73,13 @@ static const struct vchiq_platform_info bcm2836_info = {
 };
 
 struct vchiq_arm_state {
-	/* Keepalive-related data */
+	/*
+	 * Keepalive-related data
+	 *
+	 * The keepalive mechanism was retro-fitted to VCHIQ to allow active
+	 * services to prevent the system from suspending.
+	 * This feature is not used on Raspberry Pi devices.
+	 */
 	struct task_struct *ka_thread;
 	struct completion ka_evt;
 	atomic_t ka_use_count;
diff --git a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
index 3b5c0618e567..3dd95e5e6557 100644
--- a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
+++ b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h
@@ -171,6 +171,21 @@ struct vchiq_slot_info {
 	short release_count;
 };
 
+/*
+ * VCHIQ is a reliable connection-oriented datagram protocol.
+ *
+ * A VCHIQ service is equivalent to a TCP connection, except:
+ * + FOURCCs are used for the rendezvous, and port numbers are assigned at the
+ *   time the connection is established.
+ * + There is less of a distinction between server and client sockets, the only
+ *   difference being which end makes the first move.
+ * + For a multi-client server, the server creates new "listening" services as
+ *   the existing one becomes connected - there is no need to specify the
+ *   maximum number of clients up front.
+ * + Data transfer is reliable but packetized (messages have defined ends).
+ * + Messages can be either short (capable of fitting in a slot) and in-band,
+ *   or copied between external buffers (bulk transfers).
+ */
 struct vchiq_service {
 	struct vchiq_service_base base;
 	unsigned int handle;
@@ -286,6 +301,23 @@ struct vchiq_shared_state {
 	int debug[DEBUG_MAX];
 };
 
+/*
+ * vchiq_slot_zero describes the memory shared between the ARM host and the
+ * VideoCore VPU. The "master" and "slave" states are owned by the respective
+ * sides but visible to the other; the slots are shared, and the remaining
+ * fields are read-only.
+ *
+ * In the configuration used by this implementation, the memory is allocated
+ * by the host, the VPU is the master (the side which controls the DMA for bulk
+ * transfers), and the host is the slave.
+ *
+ * The ownership of slots changes with use:
+ * + When empty they are owned by the sender.
+ * + When partially filled they are shared with the receiver.
+ * + When completely full they are owned by the receiver.
+ * + When the receiver has finished processing the contents, they are recycled
+ *   back to the sender.
+ */
 struct vchiq_slot_zero {
 	int magic;
 	short version;
@@ -300,6 +332,10 @@ struct vchiq_slot_zero {
 	struct vchiq_slot_info slots[VCHIQ_MAX_SLOTS];
 };
 
+/*
+ * This is the private runtime state used by each side. The same structure was
+ * originally used by both sides, but implementations have since diverged.
+ */
 struct vchiq_state {
 	struct device *dev;
 	int id;
@@ -321,13 +357,27 @@ struct vchiq_state {
 	struct mutex mutex;
 	struct vchiq_instance **instance;
 
-	/* Processes incoming messages */
+	/* Processes all incoming messages which aren't synchronous */
 	struct task_struct *slot_handler_thread;
 
-	/* Processes recycled slots */
+	/*
+	 * Slots which have been fully processed and released by the (peer)
+	 * receiver are added to the receiver queue, which is asynchronously
+	 * processed by the recycle thread.
+	 */
 	struct task_struct *recycle_thread;
 
-	/* Processes synchronous messages */
+	/*
+	 * Processes incoming synchronous messages
+	 *
+	 * The synchronous message channel is shared between all synchronous
+	 * services, and provides a way for urgent messages to bypass
+	 * potentially long queues of asynchronous messages in the normal slots.
+	 *
+	 * There can be only one outstanding synchronous message in
+	 * each direction, and as a precious shared resource synchronous
+	 * services should be used sparingly.
+	 */
 	struct task_struct *sync_thread;
 
 	/* Local implementation of the trigger remote event */
-- 
2.34.1

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

[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>
---
 .../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

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

[Stefan Wahren]

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.

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

[Greg Kroah-Hartman]

On Sat, May 10, 2025 at 12:11:52AM +0200, Stefan Wahren wrote:
> 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.

I understand the need, but this does not document the parameters to the
ioctls, so it's not all that useful.  How about just a normal
documentation file with this all written out?

thanks,

greg k-h

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

[Laurent Pinchart]

On Wed, May 21, 2025 at 01:20:54PM +0200, Greg KH wrote:
> On Sat, May 10, 2025 at 12:11:52AM +0200, Stefan Wahren wrote:
> > 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.
> 
> I understand the need, but this does not document the parameters to the
> ioctls, so it's not all that useful.  How about just a normal
> documentation file with this all written out?

That would be my preference too, somewhere in
Documentation/userspace-api/.

-- 
Regards,

Laurent Pinchart

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

[Stefan Wahren]

Hi,

Am 21.05.25 um 13:28 schrieb Laurent Pinchart:
> On Wed, May 21, 2025 at 01:20:54PM +0200, Greg KH wrote:
>> On Sat, May 10, 2025 at 12:11:52AM +0200, Stefan Wahren wrote:
>>> 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.
>> I understand the need, but this does not document the parameters to the
>> ioctls, so it's not all that useful.  How about just a normal
>> documentation file with this all written out?
> That would be my preference too, somewhere in
> Documentation/userspace-api/.
>
could you please point me to a comparable IOCTL documenation to better 
understand your expectations?

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

[Laurent Pinchart]

On Wed, May 21, 2025 at 01:39:15PM +0200, Stefan Wahren wrote:
> Am 21.05.25 um 13:28 schrieb Laurent Pinchart:
> > On Wed, May 21, 2025 at 01:20:54PM +0200, Greg KH wrote:
> >> On Sat, May 10, 2025 at 12:11:52AM +0200, Stefan Wahren wrote:
> >>> 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.
> >>
> >> I understand the need, but this does not document the parameters to the
> >> ioctls, so it's not all that useful.  How about just a normal
> >> documentation file with this all written out?
> >
> > That would be my preference too, somewhere in
> > Documentation/userspace-api/.
>
> could you please point me to a comparable IOCTL documenation to better 
> understand your expectations?

Documentation/userspace-api/gpio/ seems to be a good example. You can
split ioctls in different files, see gpio-get-chipinfo-ioctl.rst for
instance. If several ioctls are closely related they can also be
documented in the same file, see for instance
Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst.

-- 
Regards,

Laurent Pinchart