qemu/include/hw/audio/virtio-snd.h

/*
 * 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 <manos.pitsidianakis@linaro.org>
 * 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