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

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

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