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 QSIMPLEQ_HEAD(, VirtIOSoundPCMBuffer) invalid; 155 }; 156 157 /* 158 * PCM stream state machine. 159 * ------------------------- 160 * 161 * 5.14.6.6.1 PCM Command Lifecycle 162 * ================================ 163 * 164 * A PCM stream has the following command lifecycle: 165 * - `SET PARAMETERS` 166 * The driver negotiates the stream parameters (format, transport, etc) with 167 * the device. 168 * Possible valid transitions: `SET PARAMETERS`, `PREPARE`. 169 * - `PREPARE` 170 * The device prepares the stream (allocates resources, etc). 171 * Possible valid transitions: `SET PARAMETERS`, `PREPARE`, `START`, 172 * `RELEASE`. Output only: the driver transfers data for pre-buffing. 173 * - `START` 174 * The device starts the stream (unmute, putting into running state, etc). 175 * Possible valid transitions: `STOP`. 176 * The driver transfers data to/from the stream. 177 * - `STOP` 178 * The device stops the stream (mute, putting into non-running state, etc). 179 * Possible valid transitions: `START`, `RELEASE`. 180 * - `RELEASE` 181 * The device releases the stream (frees resources, etc). 182 * Possible valid transitions: `SET PARAMETERS`, `PREPARE`. 183 * 184 * +---------------+ +---------+ +---------+ +-------+ +-------+ 185 * | SetParameters | | Prepare | | Release | | Start | | Stop | 186 * +---------------+ +---------+ +---------+ +-------+ +-------+ 187 * |- | | | | 188 * || | | | | 189 * |< | | | | 190 * |------------->| | | | 191 * |<-------------| | | | 192 * | |- | | | 193 * | || | | | 194 * | |< | | | 195 * | |--------------------->| | 196 * | |---------->| | | 197 * | | | |-------->| 198 * | | | |<--------| 199 * | | |<-------------------| 200 * |<-------------------------| | | 201 * | |<----------| | | 202 * 203 * CTRL in the VirtIOSound device 204 * ============================== 205 * 206 * The control messages that affect the state of a stream arrive in the 207 * `virtio_snd_handle_ctrl()` queue callback and are of type `struct 208 * virtio_snd_ctrl_command`. They are stored in a queue field in the device 209 * type, `VirtIOSound`. This allows deferring the CTRL request completion if 210 * it's not immediately possible due to locking/state reasons. 211 * 212 * The CTRL message is finally handled in `process_cmd()`. 213 */ 214 struct VirtIOSound { 215 VirtIODevice parent_obj; 216 217 VirtQueue *queues[VIRTIO_SND_VQ_MAX]; 218 uint64_t features; 219 VirtIOSoundPCM *pcm; 220 QEMUSoundCard card; 221 VMChangeStateEntry *vmstate; 222 virtio_snd_config snd_conf; 223 QemuMutex cmdq_mutex; 224 QTAILQ_HEAD(, virtio_snd_ctrl_command) cmdq; 225 bool processing_cmdq; 226 }; 227 228 struct virtio_snd_ctrl_command { 229 VirtQueueElement *elem; 230 VirtQueue *vq; 231 virtio_snd_hdr ctrl; 232 virtio_snd_hdr resp; 233 QTAILQ_ENTRY(virtio_snd_ctrl_command) next; 234 }; 235 #endif 236