1 // SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0+ 2 3 /* 4 * Definitions of virtio-media protocol structures. 5 * 6 * Copyright (c) 2023-2024 Google LLC. 7 */ 8 9 #ifndef __VIRTIO_MEDIA_PROTOCOL_H 10 #define __VIRTIO_MEDIA_PROTOCOL_H 11 12 #include <linux/videodev2.h> 13 14 /* 15 * Virtio protocol definition. 16 */ 17 18 /** 19 * struct virtio_media_cmd_header - Header for all virtio commands from the driver to the device on the commandq. 20 * 21 * @cmd: one of VIRTIO_MEDIA_CMD_*. 22 * @__padding: must be set to zero by the guest. 23 */ 24 struct virtio_media_cmd_header { 25 u32 cmd; 26 u32 __padding; 27 }; 28 29 /** 30 * struct virtio_media_resp_header - Header for all virtio responses from the device to the driver on the commandq. 31 * 32 * @status: 0 if the command was successful, or one of the standard Linux error 33 * codes. 34 * @__padding: must be set to zero by the device. 35 */ 36 struct virtio_media_resp_header { 37 u32 status; 38 u32 __padding; 39 }; 40 41 /** 42 * VIRTIO_MEDIA_CMD_OPEN - Command for creating a new session. 43 * 44 * This is the equivalent of calling `open` on a V4L2 device node. Upon 45 * success, a session id is returned which can be used to perform other 46 * commands on the session, notably ioctls. 47 */ 48 #define VIRTIO_MEDIA_CMD_OPEN 1 49 50 /** 51 * struct virtio_media_cmd_open - Driver command for VIRTIO_MEDIA_CMD_OPEN. 52 * 53 * @hdr: header which cmd member is set to VIRTIO_MEDIA_CMD_OPEN. 54 */ 55 struct virtio_media_cmd_open { 56 struct virtio_media_cmd_header hdr; 57 }; 58 59 /** 60 * struct virtio_media_resp_open - Device response for VIRTIO_MEDIA_CMD_OPEN. 61 * 62 * @hdr: header containing the status of the command. 63 * @session_id: if hdr.status == 0, contains the id of the newly created session. 64 * @__padding: must be set to zero by the device. 65 */ 66 struct virtio_media_resp_open { 67 struct virtio_media_resp_header hdr; 68 u32 session_id; 69 u32 __padding; 70 }; 71 72 /** 73 * VIRTIO_MEDIA_CMD_OPEN - Command for closing an active session. 74 * 75 * This is the equivalent of calling `close` on a previously opened V4L2 FD. 76 * All resources associated with this session will be freed and the session ID shall not be used again after queueing this command. 77 * 78 * This command does not require a response from the device. 79 */ 80 #define VIRTIO_MEDIA_CMD_CLOSE 2 81 82 /** 83 * struct virtio_media_cmd_close - Driver command for VIRTIO_MEDIA_CMD_CLOSE. 84 * 85 * @hdr: header which cmd member is set to VIRTIO_MEDIA_CMD_CLOSE. 86 * @session_id: id of the session to close. 87 * @__padding: must be set to zero by the driver. 88 */ 89 struct virtio_media_cmd_close { 90 struct virtio_media_cmd_header hdr; 91 u32 session_id; 92 u32 __padding; 93 }; 94 95 /** 96 * VIRTIO_MEDIA_CMD_IOCTL - Command for executing an ioctl on an open session. 97 * 98 * This command asks the device to run one of the `VIDIOC_*` ioctls on the active session. 99 * 100 * @hdr: header which cmd member is set to VIRTIO_MEDIA_CMD_IOCTL. 101 * @session_id: id of the session to run this ioctl on. 102 * @code: code of the ioctl. 103 * 104 * The code of the ioctl is extracted from the VIDIOC_* definitions in 105 * `videodev2.h`, and consists of the second argument of the `_IO*` macro. 106 * 107 * Each ioctl has a payload, which is defined by the third argument of the 108 * `_IO*` macro defining it. It can be writable by the driver (`_IOW`), the 109 * device (`_IOR`), or both (`_IOWR`). 110 * 111 * If an ioctl is writable by the driver, it must be followed by a 112 * driver-writable descriptor containing the payload. 113 * 114 * If an ioctl is writable by the device, it must be followed by a 115 * device-writable descriptor of the size of the payload that the device will 116 * write into. 117 * 118 */ 119 #define VIRTIO_MEDIA_CMD_IOCTL 3 120 121 /** 122 * struct virtio_media_cmd_ioctl - Driver command for VIRTIO_MEDIA_CMD_IOCTL. 123 * 124 * @hdr: header which cmd member is set to VIRTIO_MEDIA_CMD_IOCTL. 125 * @session_id: id of the session to run the ioctl on. 126 * @code: code of the ioctl to run. 127 */ 128 struct virtio_media_cmd_ioctl { 129 struct virtio_media_cmd_header hdr; 130 u32 session_id; 131 u32 code; 132 }; 133 134 /** 135 * struct virtio_media_resp_ioctl - Device response for VIRTIO_MEDIA_CMD_IOCTL. 136 * 137 * @hdr: header containing the status of the ioctl. 138 */ 139 struct virtio_media_resp_ioctl { 140 struct virtio_media_resp_header hdr; 141 }; 142 143 #define VIRTIO_MEDIA_MMAP_FLAG_RW (1 << 0) 144 145 /** 146 * VIRTIO_MEDIA_CMD_MMAP - Command for mapping a MMAP buffer into the guest's address space. 147 * 148 */ 149 #define VIRTIO_MEDIA_CMD_MMAP 4 150 151 /** 152 * struct virtio_media_cmd_mmap - Driver command for VIRTIO_MEDIA_CMD_MMAP. 153 */ 154 struct virtio_media_cmd_mmap { 155 struct virtio_media_cmd_header hdr; 156 u32 session_id; 157 u32 flags; 158 u32 offset; 159 }; 160 161 /** 162 * struct virtio_media_resp_mmap - Device response for VIRTIO_MEDIA_CMD_MMAP. 163 * 164 * @hdr: header containing the status of the command. 165 * @guest_addr: offset into SHM region 0 of the start of the mapping. 166 * @len: length of the mapping. 167 */ 168 struct virtio_media_resp_mmap { 169 struct virtio_media_resp_header hdr; 170 u64 guest_addr; 171 u64 len; 172 }; 173 174 /** 175 * VIRTIO_MEDIA_CMD_MUNMAP - Unmap a MMAP buffer previously mapped using VIRTIO_MEDIA_CMD_MMAP. 176 */ 177 #define VIRTIO_MEDIA_CMD_MUNMAP 5 178 179 /** 180 * struct virtio_media_cmd_munmap - Driver command for VIRTIO_MEDIA_CMD_MUNMAP. 181 * 182 * @guest_addr: offset into SHM region 0 at which the buffer has been previously 183 * mapped. 184 */ 185 struct virtio_media_cmd_munmap { 186 struct virtio_media_cmd_header hdr; 187 u64 guest_addr; 188 }; 189 190 /** 191 * struct virtio_media_resp_munmap - Device response for VIRTIO_MEDIA_CMD_MUNMAP. 192 * 193 * @hdr: header containing the status of the command. 194 */ 195 struct virtio_media_resp_munmap { 196 struct virtio_media_resp_header hdr; 197 }; 198 199 #define VIRTIO_MEDIA_EVT_ERROR 0 200 #define VIRTIO_MEDIA_EVT_DQBUF 1 201 #define VIRTIO_MEDIA_EVT_EVENT 2 202 203 /** 204 * struct virtio_media_event_header - Header for events queued by the device for the driver on the eventq. 205 * 206 * @event: one of VIRTIO_MEDIA_EVT_* 207 * @session_id: ID of the session the event applies to. 208 */ 209 struct virtio_media_event_header { 210 u32 event; 211 u32 session_id; 212 }; 213 214 /** 215 * struct virtio_media_event_error - Device-side error. 216 * 217 * Upon receiving this event, the session mentioned in the header is considered corrupted and closed. 218 * 219 * @hdr: header for the event. 220 * @errno: error code describing the kind of error that occurred. 221 */ 222 struct virtio_media_event_error { 223 struct virtio_media_event_header hdr; 224 u32 errno; 225 u32 __padding; 226 }; 227 228 /** 229 * struct virtio_media_event_dqbuf - Signals that a buffer is not being used anymore by the device and is returned to the driver. 230 * 231 * @hdr: header for the event. 232 * @buffer: struct v4l2_buffer describing the buffer that has been dequeued. 233 */ 234 struct virtio_media_event_dqbuf { 235 struct virtio_media_event_header hdr; 236 struct v4l2_buffer buffer; 237 struct v4l2_plane planes[VIDEO_MAX_PLANES]; 238 }; 239 240 /** 241 * struct virtio_media_event_event - Signals that a V4L2 event has been emitted for a session. 242 * 243 * @hdr: header for the event. 244 * @event: description of the event that occurred. 245 */ 246 struct virtio_media_event_event { 247 struct virtio_media_event_header hdr; 248 struct v4l2_event event; 249 }; 250 251 /** 252 * Maximum size of an event. We will queue descriptors of this size on the eventq. 253 */ 254 #define VIRTIO_MEDIA_EVENT_MAX_SIZE sizeof(struct virtio_media_event_dqbuf) 255 256 #endif // __VIRTIO_MEDIA_PROTOCOL_H 257