On Sun, Jul 12, 2026 at 3:28 AM Mauro Carvalho Chehab <[email protected]> wrote: > > 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.
The VIRTIO_MEDIA_EVT_* event IDs are supposed to be seperate from the V4L2_EVENT_* event IDs. The virtio events are for the private use of the virtio driver and are never directly exposed to the V4L2 framework or the user. They're events for the VIRTIO transport. The VIRTIO_MEDIA_EVT_EVENT is used to pass through the V4L2 events (shown in section 5.22.6.2.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-8620004]). As an example, here's the virtio message for passing through a V4L2_EVENT_VSYNC event: struct virtio_media_event_event { struct virtio_media_event_header hdr; // hdr.event = VIRTIO_MEDIA_EVT_EVENT struct v4l2_event event; // event.type = V4L2_EVENT_VSYNC }; The virtio-media driver currently doesn't send events to the V4L2 framework unless they were sent to it by the host device (through VIRTIO_MEDIA_EVT_EVENT). However, if this changes in the future, I anticipate we would have a function that mapped the virtio events to the v4l2 events if that were necessary. Does that make sense to you? Or perhaps I'm misunderstanding? > Thanks, > Mauro
