include/hw/audio/virtio-snd.h

   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