/* * VIRTIO Sound Device conforming to * * "Virtual I/O Device (VIRTIO) Version 1.2 * Committee Specification Draft 01 * 09 May 2022" * * Copyright (c) 2023 Emmanouil Pitsidianakis * Copyright (C) 2019 OpenSynergy GmbH * * This work is licensed under the terms of the GNU GPL, version 2 or * (at your option) any later version. See the COPYING file in the * top-level directory. */ #ifndef QEMU_VIRTIO_SOUND_H #define QEMU_VIRTIO_SOUND_H #include "hw/virtio/virtio.h" #include "audio/audio.h" #include "standard-headers/linux/virtio_ids.h" #include "standard-headers/linux/virtio_snd.h" #define TYPE_VIRTIO_SND "virtio-sound-device" #define VIRTIO_SND(obj) \ OBJECT_CHECK(VirtIOSound, (obj), TYPE_VIRTIO_SND) /* CONFIGURATION SPACE */ typedef struct virtio_snd_config virtio_snd_config; /* COMMON DEFINITIONS */ /* common header for request/response*/ typedef struct virtio_snd_hdr virtio_snd_hdr; /* event notification */ typedef struct virtio_snd_event virtio_snd_event; /* common control request to query an item information */ typedef struct virtio_snd_query_info virtio_snd_query_info; /* JACK CONTROL MESSAGES */ typedef struct virtio_snd_jack_hdr virtio_snd_jack_hdr; /* jack information structure */ typedef struct virtio_snd_jack_info virtio_snd_jack_info; /* jack remapping control request */ typedef struct virtio_snd_jack_remap virtio_snd_jack_remap; /* * PCM CONTROL MESSAGES */ typedef struct virtio_snd_pcm_hdr virtio_snd_pcm_hdr; /* PCM stream info structure */ typedef struct virtio_snd_pcm_info virtio_snd_pcm_info; /* set PCM stream params */ typedef struct virtio_snd_pcm_set_params virtio_snd_pcm_set_params; /* I/O request header */ typedef struct virtio_snd_pcm_xfer virtio_snd_pcm_xfer; /* I/O request status */ typedef struct virtio_snd_pcm_status virtio_snd_pcm_status; /* device structs */ typedef struct VirtIOSound VirtIOSound; typedef struct VirtIOSoundPCMStream VirtIOSoundPCMStream; typedef struct virtio_snd_ctrl_command virtio_snd_ctrl_command; typedef struct VirtIOSoundPCM VirtIOSoundPCM; typedef struct VirtIOSoundPCMBuffer VirtIOSoundPCMBuffer; /* * The VirtIO sound spec reuses layouts and values from the High Definition * Audio spec (virtio/v1.2: 5.14 Sound Device). This struct handles each I/O * message's buffer (virtio/v1.2: 5.14.6.8 PCM I/O Messages). * * In the case of TX (i.e. playback) buffers, we defer reading the raw PCM data * from the virtqueue until QEMU's sound backsystem calls the output callback. * This is tracked by the `bool populated;` field, which is set to true when * data has been read into our own buffer for consumption. * * VirtIOSoundPCMBuffer has a dynamic size since it includes the raw PCM data * in its allocation. It must be initialized and destroyed as follows: * * size_t size = [[derived from owned VQ element descriptor sizes]]; * buffer = g_malloc0(sizeof(VirtIOSoundPCMBuffer) + size); * buffer->elem = [[owned VQ element]]; * * [..] * * g_free(buffer->elem); * g_free(buffer); */ struct VirtIOSoundPCMBuffer { QSIMPLEQ_ENTRY(VirtIOSoundPCMBuffer) entry; VirtQueueElement *elem; VirtQueue *vq; size_t size; /* * In TX / Plaback, `offset` represents the first unused position inside * `data`. If `offset == size` then there are no unused data left. */ uint64_t offset; /* Used for the TX queue for lazy I/O copy from `elem` */ bool populated; /* * VirtIOSoundPCMBuffer is an unsized type because it ends with an array of * bytes. The size of `data` is determined from the I/O message's read-only * or write-only size when allocating VirtIOSoundPCMBuffer. */ uint8_t data[]; }; struct VirtIOSoundPCM { VirtIOSound *snd; /* * PCM parameters are a separate field instead of a VirtIOSoundPCMStream * field, because the operation of PCM control requests is first * VIRTIO_SND_R_PCM_SET_PARAMS and then VIRTIO_SND_R_PCM_PREPARE; this * means that some times we get parameters without having an allocated * stream yet. */ virtio_snd_pcm_set_params *pcm_params; VirtIOSoundPCMStream **streams; }; struct VirtIOSoundPCMStream { VirtIOSoundPCM *pcm; virtio_snd_pcm_info info; virtio_snd_pcm_set_params params; uint32_t id; /* channel position values (VIRTIO_SND_CHMAP_XXX) */ uint8_t positions[VIRTIO_SND_CHMAP_MAX_SIZE]; VirtIOSound *s; bool flushing; audsettings as; union { SWVoiceIn *in; SWVoiceOut *out; } voice; QemuMutex queue_mutex; bool active; QSIMPLEQ_HEAD(, VirtIOSoundPCMBuffer) queue; }; /* * PCM stream state machine. * ------------------------- * * 5.14.6.6.1 PCM Command Lifecycle * ================================ * * A PCM stream has the following command lifecycle: * - `SET PARAMETERS` * The driver negotiates the stream parameters (format, transport, etc) with * the device. * Possible valid transitions: `SET PARAMETERS`, `PREPARE`. * - `PREPARE` * The device prepares the stream (allocates resources, etc). * Possible valid transitions: `SET PARAMETERS`, `PREPARE`, `START`, * `RELEASE`. Output only: the driver transfers data for pre-buffing. * - `START` * The device starts the stream (unmute, putting into running state, etc). * Possible valid transitions: `STOP`. * The driver transfers data to/from the stream. * - `STOP` * The device stops the stream (mute, putting into non-running state, etc). * Possible valid transitions: `START`, `RELEASE`. * - `RELEASE` * The device releases the stream (frees resources, etc). * Possible valid transitions: `SET PARAMETERS`, `PREPARE`. * * +---------------+ +---------+ +---------+ +-------+ +-------+ * | SetParameters | | Prepare | | Release | | Start | | Stop | * +---------------+ +---------+ +---------+ +-------+ +-------+ * |- | | | | * || | | | | * |< | | | | * |------------->| | | | * |<-------------| | | | * | |- | | | * | || | | | * | |< | | | * | |--------------------->| | * | |---------->| | | * | | | |-------->| * | | | |<--------| * | | |<-------------------| * |<-------------------------| | | * | |<----------| | | * * CTRL in the VirtIOSound device * ============================== * * The control messages that affect the state of a stream arrive in the * `virtio_snd_handle_ctrl()` queue callback and are of type `struct * virtio_snd_ctrl_command`. They are stored in a queue field in the device * type, `VirtIOSound`. This allows deferring the CTRL request completion if * it's not immediately possible due to locking/state reasons. * * The CTRL message is finally handled in `process_cmd()`. */ struct VirtIOSound { VirtIODevice parent_obj; VirtQueue *queues[VIRTIO_SND_VQ_MAX]; uint64_t features; VirtIOSoundPCM *pcm; QEMUSoundCard card; VMChangeStateEntry *vmstate; virtio_snd_config snd_conf; QemuMutex cmdq_mutex; QTAILQ_HEAD(, virtio_snd_ctrl_command) cmdq; bool processing_cmdq; /* * Convenience queue to keep track of invalid tx/rx queue messages inside * the tx/rx callbacks. * * In the callbacks as a first step we are emptying the virtqueue to handle * each message and we cannot add an invalid message back to the queue: we * would re-process it in subsequent loop iterations. * * Instead, we add them to this queue and after finishing examining every * virtqueue element, we inform the guest for each invalid message. * * This queue must be empty at all times except for inside the tx/rx * callbacks. */ QSIMPLEQ_HEAD(, VirtIOSoundPCMBuffer) invalid; }; struct virtio_snd_ctrl_command { VirtQueueElement *elem; VirtQueue *vq; virtio_snd_hdr ctrl; virtio_snd_hdr resp; size_t payload_size; QTAILQ_ENTRY(virtio_snd_ctrl_command) next; }; #endif