1 /* 2 * VIRTIO Sound Device conforming to 3 * 4 * "Virtual I/O Device (VIRTIO) Version 1.2 5 * Committee Specification Draft 01 6 * 09 May 2022" 7 * 8 * Copyright (c) 2023 Emmanouil Pitsidianakis <manos.pitsidianakis@linaro.org> 9 * Copyright (C) 2019 OpenSynergy GmbH 10 * 11 * This work is licensed under the terms of the GNU GPL, version 2 or 12 * (at your option) any later version. See the COPYING file in the 13 * top-level directory. 14 */ 15 16 #ifndef QEMU_VIRTIO_SOUND_H 17 #define QEMU_VIRTIO_SOUND_H 18 19 #include "hw/virtio/virtio.h" 20 #include "audio/audio.h" 21 #include "standard-headers/linux/virtio_ids.h" 22 #include "standard-headers/linux/virtio_snd.h" 23 24 #define TYPE_VIRTIO_SND "virtio-sound-device" 25 #define VIRTIO_SND(obj) \ 26 OBJECT_CHECK(VirtIOSound, (obj), TYPE_VIRTIO_SND) 27 28 /* CONFIGURATION SPACE */ 29 30 typedef struct virtio_snd_config virtio_snd_config; 31 32 /* COMMON DEFINITIONS */ 33 34 /* common header for request/response*/ 35 typedef struct virtio_snd_hdr virtio_snd_hdr; 36 37 /* event notification */ 38 typedef struct virtio_snd_event virtio_snd_event; 39 40 /* common control request to query an item information */ 41 typedef struct virtio_snd_query_info virtio_snd_query_info; 42 43 /* JACK CONTROL MESSAGES */ 44 45 typedef struct virtio_snd_jack_hdr virtio_snd_jack_hdr; 46 47 /* jack information structure */ 48 typedef struct virtio_snd_jack_info virtio_snd_jack_info; 49 50 /* jack remapping control request */ 51 typedef struct virtio_snd_jack_remap virtio_snd_jack_remap; 52 53 /* 54 * PCM CONTROL MESSAGES 55 */ 56 typedef struct virtio_snd_pcm_hdr virtio_snd_pcm_hdr; 57 58 /* PCM stream info structure */ 59 typedef struct virtio_snd_pcm_info virtio_snd_pcm_info; 60 61 /* set PCM stream params */ 62 typedef struct virtio_snd_pcm_set_params virtio_snd_pcm_set_params; 63 64 /* I/O request header */ 65 typedef struct virtio_snd_pcm_xfer virtio_snd_pcm_xfer; 66 67 /* I/O request status */ 68 typedef struct virtio_snd_pcm_status virtio_snd_pcm_status; 69 70 /* device structs */ 71 72 typedef struct VirtIOSound VirtIOSound; 73 74 typedef struct VirtIOSoundPCMStream VirtIOSoundPCMStream; 75 76 typedef struct virtio_snd_ctrl_command virtio_snd_ctrl_command; 77 78 typedef struct VirtIOSoundPCM VirtIOSoundPCM; 79 80 typedef struct VirtIOSoundPCMBuffer VirtIOSoundPCMBuffer; 81 82 /* 83 * The VirtIO sound spec reuses layouts and values from the High Definition 84 * Audio spec (virtio/v1.2: 5.14 Sound Device). This struct handles each I/O 85 * message's buffer (virtio/v1.2: 5.14.6.8 PCM I/O Messages). 86 * 87 * In the case of TX (i.e. playback) buffers, we defer reading the raw PCM data 88 * from the virtqueue until QEMU's sound backsystem calls the output callback. 89 * This is tracked by the `bool populated;` field, which is set to true when 90 * data has been read into our own buffer for consumption. 91 * 92 * VirtIOSoundPCMBuffer has a dynamic size since it includes the raw PCM data 93 * in its allocation. It must be initialized and destroyed as follows: 94 * 95 * size_t size = [[derived from owned VQ element descriptor sizes]]; 96 * buffer = g_malloc0(sizeof(VirtIOSoundPCMBuffer) + size); 97 * buffer->elem = [[owned VQ element]]; 98 * 99 * [..] 100 * 101 * g_free(buffer->elem); 102 * g_free(buffer); 103 */ 104 struct VirtIOSoundPCMBuffer { 105 QSIMPLEQ_ENTRY(VirtIOSoundPCMBuffer) entry; 106 VirtQueueElement *elem; 107 VirtQueue *vq; 108 size_t size; 109 /* 110 * In TX / Plaback, `offset` represents the first unused position inside 111 * `data`. If `offset == size` then there are no unused data left. 112 */ 113 uint64_t offset; 114 /* Used for the TX queue for lazy I/O copy from `elem` */ 115 bool populated; 116 /* 117 * VirtIOSoundPCMBuffer is an unsized type because it ends with an array of 118 * bytes. The size of `data` is determined from the I/O message's read-only 119 * or write-only size when allocating VirtIOSoundPCMBuffer. 120 */ 121 uint8_t data[]; 122 }; 123 124 struct VirtIOSoundPCM { 125 VirtIOSound *snd; 126 /* 127 * PCM parameters are a separate field instead of a VirtIOSoundPCMStream 128 * field, because the operation of PCM control requests is first 129 * VIRTIO_SND_R_PCM_SET_PARAMS and then VIRTIO_SND_R_PCM_PREPARE; this 130 * means that some times we get parameters without having an allocated 131 * stream yet. 132 */ 133 virtio_snd_pcm_set_params *pcm_params; 134 VirtIOSoundPCMStream **streams; 135 }; 136 137 struct VirtIOSoundPCMStream { 138 VirtIOSoundPCM *pcm; 139 virtio_snd_pcm_info info; 140 virtio_snd_pcm_set_params params; 141 uint32_t id; 142 /* channel position values (VIRTIO_SND_CHMAP_XXX) */ 143 uint8_t positions[VIRTIO_SND_CHMAP_MAX_SIZE]; 144 VirtIOSound *s; 145 bool flushing; 146 audsettings as; 147 union { 148 SWVoiceIn *in; 149 SWVoiceOut *out; 150 } voice; 151 QemuMutex queue_mutex; 152 bool active; 153 QSIMPLEQ_HEAD(, VirtIOSoundPCMBuffer) queue; 154 }; 155 156 /* 157 * PCM stream state machine. 158 * ------------------------- 159 * 160 * 5.14.6.6.1 PCM Command Lifecycle 161 * ================================ 162 * 163 * A PCM stream has the following command lifecycle: 164 * - `SET PARAMETERS` 165 * The driver negotiates the stream parameters (format, transport, etc) with 166 * the device. 167 * Possible valid transitions: `SET PARAMETERS`, `PREPARE`. 168 * - `PREPARE` 169 * The device prepares the stream (allocates resources, etc). 170 * Possible valid transitions: `SET PARAMETERS`, `PREPARE`, `START`, 171 * `RELEASE`. Output only: the driver transfers data for pre-buffing. 172 * - `START` 173 * The device starts the stream (unmute, putting into running state, etc). 174 * Possible valid transitions: `STOP`. 175 * The driver transfers data to/from the stream. 176 * - `STOP` 177 * The device stops the stream (mute, putting into non-running state, etc). 178 * Possible valid transitions: `START`, `RELEASE`. 179 * - `RELEASE` 180 * The device releases the stream (frees resources, etc). 181 * Possible valid transitions: `SET PARAMETERS`, `PREPARE`. 182 * 183 * +---------------+ +---------+ +---------+ +-------+ +-------+ 184 * | SetParameters | | Prepare | | Release | | Start | | Stop | 185 * +---------------+ +---------+ +---------+ +-------+ +-------+ 186 * |- | | | | 187 * || | | | | 188 * |< | | | | 189 * |------------->| | | | 190 * |<-------------| | | | 191 * | |- | | | 192 * | || | | | 193 * | |< | | | 194 * | |--------------------->| | 195 * | |---------->| | | 196 * | | | |-------->| 197 * | | | |<--------| 198 * | | |<-------------------| 199 * |<-------------------------| | | 200 * | |<----------| | | 201 * 202 * CTRL in the VirtIOSound device 203 * ============================== 204 * 205 * The control messages that affect the state of a stream arrive in the 206 * `virtio_snd_handle_ctrl()` queue callback and are of type `struct 207 * virtio_snd_ctrl_command`. They are stored in a queue field in the device 208 * type, `VirtIOSound`. This allows deferring the CTRL request completion if 209 * it's not immediately possible due to locking/state reasons. 210 * 211 * The CTRL message is finally handled in `process_cmd()`. 212 */ 213 struct VirtIOSound { 214 VirtIODevice parent_obj; 215 216 VirtQueue *queues[VIRTIO_SND_VQ_MAX]; 217 uint64_t features; 218 VirtIOSoundPCM *pcm; 219 QEMUSoundCard card; 220 VMChangeStateEntry *vmstate; 221 virtio_snd_config snd_conf; 222 QemuMutex cmdq_mutex; 223 QTAILQ_HEAD(, virtio_snd_ctrl_command) cmdq; 224 bool processing_cmdq; 225 /* 226 * Convenience queue to keep track of invalid tx/rx queue messages inside 227 * the tx/rx callbacks. 228 * 229 * In the callbacks as a first step we are emptying the virtqueue to handle 230 * each message and we cannot add an invalid message back to the queue: we 231 * would re-process it in subsequent loop iterations. 232 * 233 * Instead, we add them to this queue and after finishing examining every 234 * virtqueue element, we inform the guest for each invalid message. 235 * 236 * This queue must be empty at all times except for inside the tx/rx 237 * callbacks. 238 */ 239 QSIMPLEQ_HEAD(, VirtIOSoundPCMBuffer) invalid; 240 }; 241 242 struct virtio_snd_ctrl_command { 243 VirtQueueElement *elem; 244 VirtQueue *vq; 245 virtio_snd_hdr ctrl; 246 virtio_snd_hdr resp; 247 size_t payload_size; 248 QTAILQ_ENTRY(virtio_snd_ctrl_command) next; 249 }; 250 #endif 251