| 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 "qemu/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 | /* |
| 126 | * PCM parameters are a separate field instead of a VirtIOSoundPCMStream |
| 127 | * field, because the operation of PCM control requests is first |
| 128 | * VIRTIO_SND_R_PCM_SET_PARAMS and then VIRTIO_SND_R_PCM_PREPARE; this |
| 129 | * means that some times we get parameters without having an allocated |
| 130 | * stream yet. |
| 131 | */ |
| 132 | virtio_snd_pcm_set_params *pcm_params; |
| 133 | VirtIOSoundPCMStream **streams; |
| 134 | }; |
| 135 | |
| 136 | struct VirtIOSoundPCMStream { |
| 137 | virtio_snd_pcm_info info; |
| 138 | virtio_snd_pcm_set_params params; |
| 139 | uint32_t id; |
| 140 | /* channel position values (VIRTIO_SND_CHMAP_XXX) */ |
| 141 | uint8_t positions[VIRTIO_SND_CHMAP_MAX_SIZE]; |
| 142 | VirtIOSound *s; |
| 143 | bool flushing; |
| 144 | audsettings as; |
| 145 | union { |
| 146 | SWVoiceIn *in; |
| 147 | SWVoiceOut *out; |
| 148 | } voice; |
| 149 | QemuMutex queue_mutex; |
| 150 | bool active; |
| 151 | uint32_t latency_bytes; |
| 152 | QSIMPLEQ_HEAD(, VirtIOSoundPCMBuffer) queue; |
| 153 | }; |
| 154 | |
| 155 | /* |
| 156 | * PCM stream state machine. |
| 157 | * ------------------------- |
| 158 | * |
| 159 | * 5.14.6.6.1 PCM Command Lifecycle |
| 160 | * ================================ |
| 161 | * |
| 162 | * A PCM stream has the following command lifecycle: |
| 163 | * - `SET PARAMETERS` |
| 164 | * The driver negotiates the stream parameters (format, transport, etc) with |
| 165 | * the device. |
| 166 | * Possible valid transitions: `SET PARAMETERS`, `PREPARE`. |
| 167 | * - `PREPARE` |
| 168 | * The device prepares the stream (allocates resources, etc). |
| 169 | * Possible valid transitions: `SET PARAMETERS`, `PREPARE`, `START`, |
| 170 | * `RELEASE`. Output only: the driver transfers data for pre-buffing. |
| 171 | * - `START` |
| 172 | * The device starts the stream (unmute, putting into running state, etc). |
| 173 | * Possible valid transitions: `STOP`. |
| 174 | * The driver transfers data to/from the stream. |
| 175 | * - `STOP` |
| 176 | * The device stops the stream (mute, putting into non-running state, etc). |
| 177 | * Possible valid transitions: `START`, `RELEASE`. |
| 178 | * - `RELEASE` |
| 179 | * The device releases the stream (frees resources, etc). |
| 180 | * Possible valid transitions: `SET PARAMETERS`, `PREPARE`. |
| 181 | * |
| 182 | * +---------------+ +---------+ +---------+ +-------+ +-------+ |
| 183 | * | SetParameters | | Prepare | | Release | | Start | | Stop | |
| 184 | * +---------------+ +---------+ +---------+ +-------+ +-------+ |
| 185 | * |- | | | | |
| 186 | * || | | | | |
| 187 | * |< | | | | |
| 188 | * |------------->| | | | |
| 189 | * |<-------------| | | | |
| 190 | * | |- | | | |
| 191 | * | || | | | |
| 192 | * | |< | | | |
| 193 | * | |--------------------->| | |
| 194 | * | |---------->| | | |
| 195 | * | | | |-------->| |
| 196 | * | | | |<--------| |
| 197 | * | | |<-------------------| |
| 198 | * |<-------------------------| | | |
| 199 | * | |<----------| | | |
| 200 | * |
| 201 | * CTRL in the VirtIOSound device |
| 202 | * ============================== |
| 203 | * |
| 204 | * The control messages that affect the state of a stream arrive in the |
| 205 | * `virtio_snd_handle_ctrl()` queue callback and are of type `struct |
| 206 | * virtio_snd_ctrl_command`. They are stored in a queue field in the device |
| 207 | * type, `VirtIOSound`. This allows deferring the CTRL request completion if |
| 208 | * it's not immediately possible due to locking/state reasons. |
| 209 | * |
| 210 | * The CTRL message is finally handled in `process_cmd()`. |
| 211 | */ |
| 212 | struct VirtIOSound { |
| 213 | VirtIODevice parent_obj; |
| 214 | |
| 215 | VirtQueue *queues[VIRTIO_SND_VQ_MAX]; |
| 216 | uint64_t features; |
| 217 | VirtIOSoundPCM pcm; |
| 218 | AudioBackend *audio_be; |
| 219 | VMChangeStateEntry *vmstate; |
| 220 | virtio_snd_config snd_conf; |
| 221 | QemuMutex cmdq_mutex; |
| 222 | QTAILQ_HEAD(, virtio_snd_ctrl_command) cmdq; |
| 223 | bool processing_cmdq; |
| 224 | /* |
| 225 | * Convenience queue to keep track of invalid tx/rx queue messages inside |
| 226 | * the tx/rx callbacks. |
| 227 | * |
| 228 | * In the callbacks as a first step we are emptying the virtqueue to handle |
| 229 | * each message and we cannot add an invalid message back to the queue: we |
| 230 | * would re-process it in subsequent loop iterations. |
| 231 | * |
| 232 | * Instead, we add them to this queue and after finishing examining every |
| 233 | * virtqueue element, we inform the guest for each invalid message. |
| 234 | * |
| 235 | * This queue must be empty at all times except for inside the tx/rx |
| 236 | * callbacks. |
| 237 | */ |
| 238 | QSIMPLEQ_HEAD(, VirtIOSoundPCMBuffer) invalid; |
| 239 | }; |
| 240 | |
| 241 | struct virtio_snd_ctrl_command { |
| 242 | VirtQueueElement *elem; |
| 243 | VirtQueue *vq; |
| 244 | virtio_snd_hdr ctrl; |
| 245 | virtio_snd_hdr resp; |
| 246 | size_t payload_size; |
| 247 | QTAILQ_ENTRY(virtio_snd_ctrl_command) next; |
| 248 | }; |
| 249 | #endif |