On Mon, 22 Jun 2026 16:43:36 -0400 Brian Daniels <[email protected]> wrote:
> From: Alexandre Courbot <[email protected]> > > Add the identifiers and structs used to implement the virtio interface > as described in section 5.22 of version 1.4 of the virtio spec: > > https://docs.oasis-open.org/virtio/virtio/v1.4/csprd01/virtio-v1.4-csprd01-diff-from-v1.2-cs01.html#x1-82200022 > > Signed-off-by: Alexandre Courbot <[email protected]> > Co-developed-by: Brian Daniels <[email protected]> > Signed-off-by: Brian Daniels <[email protected]> > --- > drivers/media/virtio/protocol.h | 287 ++++++++++++++++++++++++++++++++ > 1 file changed, 287 insertions(+) > create mode 100644 drivers/media/virtio/protocol.h > > diff --git a/drivers/media/virtio/protocol.h b/drivers/media/virtio/protocol.h > new file mode 100644 > index 000000000..5878d107c > --- /dev/null > +++ b/drivers/media/virtio/protocol.h > @@ -0,0 +1,287 @@ > +/* SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0+ */ > + > +/* > + * Definitions of virtio-media protocol structures. > + * > + * Copyright (c) 2024-2025 Google LLC. > + */ > + > +#ifndef __VIRTIO_MEDIA_PROTOCOL_H > +#define __VIRTIO_MEDIA_PROTOCOL_H > + > +#include <linux/videodev2.h> > +#include <linux/bits.h> > + > +/* > + * Virtio protocol definition. > + */ > + > +/** > + * struct virtio_media_cmd_header - Header for all virtio-media commands. > + * @cmd: one of VIRTIO_MEDIA_CMD_*. > + * @__reserved: must be set to zero by the driver. > + * > + * This header starts all commands from the driver to the device on the > + * commandq. > + */ > +struct virtio_media_cmd_header { > + u32 cmd; > + u32 __reserved; > +}; > + > +/** > + * struct virtio_media_resp_header - Header for all virtio-media responses. > + * @status: 0 if the command was successful, or one of the standard Linux > error > + * codes. > + * @__reserved: must be set to zero by the device. > + * > + * This header starts all responses from the device to the driver on the > + * commandq. > + */ > +struct virtio_media_resp_header { > + u32 status; > + u32 __reserved; > +}; > + > +/** > + * VIRTIO_MEDIA_CMD_OPEN - Command for creating a new session. > + * > + * This is the equivalent of calling `open` on a V4L2 device node. Upon > + * success, a session id is returned which can be used to perform other > + * commands on the session, notably ioctls. > + */ > +#define VIRTIO_MEDIA_CMD_OPEN 1 > + > +/** > + * struct virtio_media_cmd_open - Driver command for VIRTIO_MEDIA_CMD_OPEN. > + * @hdr: header with cmd member set to VIRTIO_MEDIA_CMD_OPEN. > + */ > +struct virtio_media_cmd_open { > + struct virtio_media_cmd_header hdr; > +}; > + > +/** > + * struct virtio_media_resp_open - Device response for VIRTIO_MEDIA_CMD_OPEN. > + * @hdr: header containing the status of the command. > + * @session_id: if hdr.status == 0, contains the id of the newly created > + * session. > + * @__reserved: must be set to zero by the device. > + */ > +struct virtio_media_resp_open { > + struct virtio_media_resp_header hdr; > + u32 session_id; > + u32 __reserved; > +}; > + > +/** > + * VIRTIO_MEDIA_CMD_CLOSE - Command for closing an active session. > + * > + * This is the equivalent of calling `close` on a previously opened V4L2 > + * session. All resources associated with this session will be freed and the > + * session ID shall not be used again after queueing this command. > + * > + * This command does not require a response from the device. > + */ > +#define VIRTIO_MEDIA_CMD_CLOSE 2 > + > +/** > + * struct virtio_media_cmd_close - Driver command for VIRTIO_MEDIA_CMD_CLOSE. > + * @hdr: header with cmd member set to VIRTIO_MEDIA_CMD_CLOSE. > + * @session_id: id of the session to close. > + * @__reserved: must be set to zero by the driver. > + */ > +struct virtio_media_cmd_close { > + struct virtio_media_cmd_header hdr; > + u32 session_id; > + u32 __reserved; > +}; > + > +/** > + * VIRTIO_MEDIA_CMD_IOCTL - Driver command for executing an ioctl. > + * > + * This command asks the device to run one of the `VIDIOC_*` ioctls on the > + * active session. > + * > + * The code of the ioctl is extracted from the VIDIOC_* definitions in > + * `videodev2.h`, and consists of the second argument of the `_IO*` macro. > + * > + * Each ioctl has a payload, which is defined by the third argument of the > + * `_IO*` macro defining it. It can be writable by the driver (`_IOW`), the > + * device (`_IOR`), or both (`_IOWR`). > + * > + * If an ioctl is writable by the driver, it must be followed by a > + * driver-writable descriptor containing the payload. > + * > + * If an ioctl is writable by the device, it must be followed by a > + * device-writable descriptor of the size of the payload that the device will > + * write into. > + * > + */ > +#define VIRTIO_MEDIA_CMD_IOCTL 3 > + > +/** > + * struct virtio_media_cmd_ioctl - Driver command for VIRTIO_MEDIA_CMD_IOCTL. > + * @hdr: header with cmd member set to VIRTIO_MEDIA_CMD_IOCTL. > + * @session_id: id of the session to run the ioctl on. > + * @code: code of the ioctl to run. > + */ > +struct virtio_media_cmd_ioctl { > + struct virtio_media_cmd_header hdr; > + u32 session_id; > + u32 code; > +}; > + > +/** > + * struct virtio_media_resp_ioctl - Device response for > VIRTIO_MEDIA_CMD_IOCTL. > + * @hdr: header containing the status of the ioctl. > + */ > +struct virtio_media_resp_ioctl { > + struct virtio_media_resp_header hdr; > +}; > + > +/** > + * struct virtio_media_sg_entry - Description of part of a scattered guest > + * memory. > + * @start: start guest address of the memory segment. > + * @len: length of this memory segment. > + * @__reserved: must be set to zero by the driver. > + */ > +struct virtio_media_sg_entry { > + u64 start; > + u32 len; > + u32 __reserved; > +}; > + > +#define VIRTIO_MEDIA_MMAP_FLAG_RW BIT(0) > + > +/** > + * VIRTIO_MEDIA_CMD_MMAP - Command for mapping a MMAP buffer into the > driver's > + * address space. > + * > + */ > +#define VIRTIO_MEDIA_CMD_MMAP 4 > + > +/** > + * struct virtio_media_cmd_mmap - Driver command for VIRTIO_MEDIA_CMD_MMAP. > + * @hdr: header with cmd member set to VIRTIO_MEDIA_CMD_MMAP. > + * @session_id: ID of the session we are mapping for. > + * @flags: combination of VIRTIO_MEDIA_MMAP_FLAG_*. > + * @offset: mem_offset field of the plane to map, as returned by > + * VIDIOC_QUERYBUF. > + */ > +struct virtio_media_cmd_mmap { > + struct virtio_media_cmd_header hdr; > + u32 session_id; > + u32 flags; > + u32 offset; > +}; > + > +/** > + * struct virtio_media_resp_mmap - Device response for VIRTIO_MEDIA_CMD_MMAP. > + * @hdr: header containing the status of the command. > + * @driver_addr: offset into SHM region 0 of the start of the mapping. > + * @len: length of the mapping. > + */ > +struct virtio_media_resp_mmap { > + struct virtio_media_resp_header hdr; > + u64 driver_addr; > + u64 len; > +}; > + > +/** > + * VIRTIO_MEDIA_CMD_MUNMAP - Unmap a MMAP buffer previously mapped using > + * VIRTIO_MEDIA_CMD_MMAP. > + */ > +#define VIRTIO_MEDIA_CMD_MUNMAP 5 > + > +/** > + * struct virtio_media_cmd_munmap - Driver command for > VIRTIO_MEDIA_CMD_MUNMAP. > + * @hdr: header with cmd member set to VIRTIO_MEDIA_CMD_MUNMAP. > + * @driver_addr: offset into SHM region 0 at which the buffer has been > + * previously > + * mapped. > + */ > +struct virtio_media_cmd_munmap { > + struct virtio_media_cmd_header hdr; > + u64 driver_addr; > +}; > + > +/** > + * struct virtio_media_resp_munmap - Device response for > + * VIRTIO_MEDIA_CMD_MUNMAP. > + * @hdr: header containing the status of the command. > + */ > +struct virtio_media_resp_munmap { > + struct virtio_media_resp_header hdr; > +}; > + > +/* The values for these events are set by the virtio-media specification. */ > +#define VIRTIO_MEDIA_EVT_ERROR 0 > +#define VIRTIO_MEDIA_EVT_DQBUF 1 > +#define VIRTIO_MEDIA_EVT_EVENT 2 As I mentioned on v3, media also has events. Some userspace apps may need them to do some optimizations related to buffer sync, source changes, motion detection and such. See the specs: https://linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/vidioc-dqevent.html#event-type https://linuxtv.org/downloads/v4l-dvb-apis-new/driver-api/v4l2-event.html As the virtio driver may end needing such events in the future, it needs to start numbering its private events after: #define V4L2_EVENT_PRIVATE_START 0x08000000 which is where driver-specific events should be placed. Thanks, Mauro
