xref: /openbmc/qemu/include/hw/audio/virtio-snd.h (revision 731655f8)
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