include/standard-headers/linux/virtio_snd.h

   1 /* SPDX-License-Identifier: BSD-3-Clause */
   2 /*
   3  * Copyright (C) 2021 OpenSynergy GmbH
   4  */
   5 #ifndef VIRTIO_SND_IF_H
   6 #define VIRTIO_SND_IF_H
   7
   8 #include "standard-headers/linux/virtio_types.h"
   9
  10 /*******************************************************************************
  11  * FEATURE BITS
  12  */
  13 enum {
  14         /* device supports control elements */
  15         VIRTIO_SND_F_CTLS = 0
  16 };
  17
  18 /*******************************************************************************
  19  * CONFIGURATION SPACE
  20  */
  21 struct virtio_snd_config {
  22         /* # of available physical jacks */
  23         uint32_t jacks;
  24         /* # of available PCM streams */
  25         uint32_t streams;
  26         /* # of available channel maps */
  27         uint32_t chmaps;
  28         /* # of available control elements */
  29         uint32_t controls;
  30 };
  31
  32 enum {
  33         /* device virtqueue indexes */
  34         VIRTIO_SND_VQ_CONTROL = 0,
  35         VIRTIO_SND_VQ_EVENT,
  36         VIRTIO_SND_VQ_TX,
  37         VIRTIO_SND_VQ_RX,
  38         /* # of device virtqueues */
  39         VIRTIO_SND_VQ_MAX
  40 };
  41
  42 /*******************************************************************************
  43  * COMMON DEFINITIONS
  44  */
  45
  46 /* supported dataflow directions */
  47 enum {
  48         VIRTIO_SND_D_OUTPUT = 0,
  49         VIRTIO_SND_D_INPUT
  50 };
  51
  52 enum {
  53         /* jack control request types */
  54         VIRTIO_SND_R_JACK_INFO = 1,
  55         VIRTIO_SND_R_JACK_REMAP,
  56
  57         /* PCM control request types */
  58         VIRTIO_SND_R_PCM_INFO = 0x0100,
  59         VIRTIO_SND_R_PCM_SET_PARAMS,
  60         VIRTIO_SND_R_PCM_PREPARE,
  61         VIRTIO_SND_R_PCM_RELEASE,
  62         VIRTIO_SND_R_PCM_START,
  63         VIRTIO_SND_R_PCM_STOP,
  64
  65         /* channel map control request types */
  66         VIRTIO_SND_R_CHMAP_INFO = 0x0200,
  67
  68         /* control element request types */
  69         VIRTIO_SND_R_CTL_INFO = 0x0300,
  70         VIRTIO_SND_R_CTL_ENUM_ITEMS,
  71         VIRTIO_SND_R_CTL_READ,
  72         VIRTIO_SND_R_CTL_WRITE,
  73         VIRTIO_SND_R_CTL_TLV_READ,
  74         VIRTIO_SND_R_CTL_TLV_WRITE,
  75         VIRTIO_SND_R_CTL_TLV_COMMAND,
  76
  77         /* jack event types */
  78         VIRTIO_SND_EVT_JACK_CONNECTED = 0x1000,
  79         VIRTIO_SND_EVT_JACK_DISCONNECTED,
  80
  81         /* PCM event types */
  82         VIRTIO_SND_EVT_PCM_PERIOD_ELAPSED = 0x1100,
  83         VIRTIO_SND_EVT_PCM_XRUN,
  84
  85         /* control element event types */
  86         VIRTIO_SND_EVT_CTL_NOTIFY = 0x1200,
  87
  88         /* common status codes */
  89         VIRTIO_SND_S_OK = 0x8000,
  90         VIRTIO_SND_S_BAD_MSG,
  91         VIRTIO_SND_S_NOT_SUPP,
  92         VIRTIO_SND_S_IO_ERR
  93 };
  94
  95 /* common header */
  96 struct virtio_snd_hdr {
  97         uint32_t code;
  98 };
  99
 100 /* event notification */
 101 struct virtio_snd_event {
 102         /* VIRTIO_SND_EVT_XXX */
 103         struct virtio_snd_hdr hdr;
 104         /* optional event data */
 105         uint32_t data;
 106 };
 107
 108 /* common control request to query an item information */
 109 struct virtio_snd_query_info {
 110         /* VIRTIO_SND_R_XXX_INFO */
 111         struct virtio_snd_hdr hdr;
 112         /* item start identifier */
 113         uint32_t start_id;
 114         /* item count to query */
 115         uint32_t count;
 116         /* item information size in bytes */
 117         uint32_t size;
 118 };
 119
 120 /* common item information header */
 121 struct virtio_snd_info {
 122         /* function group node id (High Definition Audio Specification 7.1.2) */
 123         uint32_t hda_fn_nid;
 124 };
 125
 126 /*******************************************************************************
 127  * JACK CONTROL MESSAGES
 128  */
 129 struct virtio_snd_jack_hdr {
 130         /* VIRTIO_SND_R_JACK_XXX */
 131         struct virtio_snd_hdr hdr;
 132         /* 0 ... virtio_snd_config::jacks - 1 */
 133         uint32_t jack_id;
 134 };
 135
 136 /* supported jack features */
 137 enum {
 138         VIRTIO_SND_JACK_F_REMAP = 0
 139 };
 140
 141 struct virtio_snd_jack_info {
 142         /* common header */
 143         struct virtio_snd_info hdr;
 144         /* supported feature bit map (1 << VIRTIO_SND_JACK_F_XXX) */
 145         uint32_t features;
 146         /* pin configuration (High Definition Audio Specification 7.3.3.31) */
 147         uint32_t hda_reg_defconf;
 148         /* pin capabilities (High Definition Audio Specification 7.3.4.9) */
 149         uint32_t hda_reg_caps;
 150         /* current jack connection status (0: disconnected, 1: connected) */
 151         uint8_t connected;
 152
 153         uint8_t padding[7];
 154 };
 155
 156 /* jack remapping control request */
 157 struct virtio_snd_jack_remap {
 158         /* .code = VIRTIO_SND_R_JACK_REMAP */
 159         struct virtio_snd_jack_hdr hdr;
 160         /* selected association number */
 161         uint32_t association;
 162         /* selected sequence number */
 163         uint32_t sequence;
 164 };
 165
 166 /*******************************************************************************
 167  * PCM CONTROL MESSAGES
 168  */
 169 struct virtio_snd_pcm_hdr {
 170         /* VIRTIO_SND_R_PCM_XXX */
 171         struct virtio_snd_hdr hdr;
 172         /* 0 ... virtio_snd_config::streams - 1 */
 173         uint32_t stream_id;
 174 };
 175
 176 /* supported PCM stream features */
 177 enum {
 178         VIRTIO_SND_PCM_F_SHMEM_HOST = 0,
 179         VIRTIO_SND_PCM_F_SHMEM_GUEST,
 180         VIRTIO_SND_PCM_F_MSG_POLLING,
 181         VIRTIO_SND_PCM_F_EVT_SHMEM_PERIODS,
 182         VIRTIO_SND_PCM_F_EVT_XRUNS
 183 };
 184
 185 /* supported PCM sample formats */
 186 enum {
 187         /* analog formats (width / physical width) */
 188         VIRTIO_SND_PCM_FMT_IMA_ADPCM = 0,       /*  4 /  4 bits */
 189         VIRTIO_SND_PCM_FMT_MU_LAW,              /*  8 /  8 bits */
 190         VIRTIO_SND_PCM_FMT_A_LAW,               /*  8 /  8 bits */
 191         VIRTIO_SND_PCM_FMT_S8,                  /*  8 /  8 bits */
 192         VIRTIO_SND_PCM_FMT_U8,                  /*  8 /  8 bits */
 193         VIRTIO_SND_PCM_FMT_S16,                 /* 16 / 16 bits */
 194         VIRTIO_SND_PCM_FMT_U16,                 /* 16 / 16 bits */
 195         VIRTIO_SND_PCM_FMT_S18_3,               /* 18 / 24 bits */
 196         VIRTIO_SND_PCM_FMT_U18_3,               /* 18 / 24 bits */
 197         VIRTIO_SND_PCM_FMT_S20_3,               /* 20 / 24 bits */
 198         VIRTIO_SND_PCM_FMT_U20_3,               /* 20 / 24 bits */
 199         VIRTIO_SND_PCM_FMT_S24_3,               /* 24 / 24 bits */
 200         VIRTIO_SND_PCM_FMT_U24_3,               /* 24 / 24 bits */
 201         VIRTIO_SND_PCM_FMT_S20,                 /* 20 / 32 bits */
 202         VIRTIO_SND_PCM_FMT_U20,                 /* 20 / 32 bits */
 203         VIRTIO_SND_PCM_FMT_S24,                 /* 24 / 32 bits */
 204         VIRTIO_SND_PCM_FMT_U24,                 /* 24 / 32 bits */
 205         VIRTIO_SND_PCM_FMT_S32,                 /* 32 / 32 bits */
 206         VIRTIO_SND_PCM_FMT_U32,                 /* 32 / 32 bits */
 207         VIRTIO_SND_PCM_FMT_FLOAT,               /* 32 / 32 bits */
 208         VIRTIO_SND_PCM_FMT_FLOAT64,             /* 64 / 64 bits */
 209         /* digital formats (width / physical width) */
 210         VIRTIO_SND_PCM_FMT_DSD_U8,              /*  8 /  8 bits */
 211         VIRTIO_SND_PCM_FMT_DSD_U16,             /* 16 / 16 bits */
 212         VIRTIO_SND_PCM_FMT_DSD_U32,             /* 32 / 32 bits */
 213         VIRTIO_SND_PCM_FMT_IEC958_SUBFRAME      /* 32 / 32 bits */
 214 };
 215
 216 /* supported PCM frame rates */
 217 enum {
 218         VIRTIO_SND_PCM_RATE_5512 = 0,
 219         VIRTIO_SND_PCM_RATE_8000,
 220         VIRTIO_SND_PCM_RATE_11025,
 221         VIRTIO_SND_PCM_RATE_16000,
 222         VIRTIO_SND_PCM_RATE_22050,
 223         VIRTIO_SND_PCM_RATE_32000,
 224         VIRTIO_SND_PCM_RATE_44100,
 225         VIRTIO_SND_PCM_RATE_48000,
 226         VIRTIO_SND_PCM_RATE_64000,
 227         VIRTIO_SND_PCM_RATE_88200,
 228         VIRTIO_SND_PCM_RATE_96000,
 229         VIRTIO_SND_PCM_RATE_176400,
 230         VIRTIO_SND_PCM_RATE_192000,
 231         VIRTIO_SND_PCM_RATE_384000
 232 };
 233
 234 struct virtio_snd_pcm_info {
 235         /* common header */
 236         struct virtio_snd_info hdr;
 237         /* supported feature bit map (1 << VIRTIO_SND_PCM_F_XXX) */
 238         uint32_t features;
 239         /* supported sample format bit map (1 << VIRTIO_SND_PCM_FMT_XXX) */
 240         uint64_t formats;
 241         /* supported frame rate bit map (1 << VIRTIO_SND_PCM_RATE_XXX) */
 242         uint64_t rates;
 243         /* dataflow direction (VIRTIO_SND_D_XXX) */
 244         uint8_t direction;
 245         /* minimum # of supported channels */
 246         uint8_t channels_min;
 247         /* maximum # of supported channels */
 248         uint8_t channels_max;
 249
 250         uint8_t padding[5];
 251 };
 252
 253 /* set PCM stream format */
 254 struct virtio_snd_pcm_set_params {
 255         /* .code = VIRTIO_SND_R_PCM_SET_PARAMS */
 256         struct virtio_snd_pcm_hdr hdr;
 257         /* size of the hardware buffer */
 258         uint32_t buffer_bytes;
 259         /* size of the hardware period */
 260         uint32_t period_bytes;
 261         /* selected feature bit map (1 << VIRTIO_SND_PCM_F_XXX) */
 262         uint32_t features;
 263         /* selected # of channels */
 264         uint8_t channels;
 265         /* selected sample format (VIRTIO_SND_PCM_FMT_XXX) */
 266         uint8_t format;
 267         /* selected frame rate (VIRTIO_SND_PCM_RATE_XXX) */
 268         uint8_t rate;
 269
 270         uint8_t padding;
 271 };
 272
 273 /*******************************************************************************
 274  * PCM I/O MESSAGES
 275  */
 276
 277 /* I/O request header */
 278 struct virtio_snd_pcm_xfer {
 279         /* 0 ... virtio_snd_config::streams - 1 */
 280         uint32_t stream_id;
 281 };
 282
 283 /* I/O request status */
 284 struct virtio_snd_pcm_status {
 285         /* VIRTIO_SND_S_XXX */
 286         uint32_t status;
 287         /* current device latency */
 288         uint32_t latency_bytes;
 289 };
 290
 291 /*******************************************************************************
 292  * CHANNEL MAP CONTROL MESSAGES
 293  */
 294 struct virtio_snd_chmap_hdr {
 295         /* VIRTIO_SND_R_CHMAP_XXX */
 296         struct virtio_snd_hdr hdr;
 297         /* 0 ... virtio_snd_config::chmaps - 1 */
 298         uint32_t chmap_id;
 299 };
 300
 301 /* standard channel position definition */
 302 enum {
 303         VIRTIO_SND_CHMAP_NONE = 0,      /* undefined */
 304         VIRTIO_SND_CHMAP_NA,            /* silent */
 305         VIRTIO_SND_CHMAP_MONO,          /* mono stream */
 306         VIRTIO_SND_CHMAP_FL,            /* front left */
 307         VIRTIO_SND_CHMAP_FR,            /* front right */
 308         VIRTIO_SND_CHMAP_RL,            /* rear left */
 309         VIRTIO_SND_CHMAP_RR,            /* rear right */
 310         VIRTIO_SND_CHMAP_FC,            /* front center */
 311         VIRTIO_SND_CHMAP_LFE,           /* low frequency (LFE) */
 312         VIRTIO_SND_CHMAP_SL,            /* side left */
 313         VIRTIO_SND_CHMAP_SR,            /* side right */
 314         VIRTIO_SND_CHMAP_RC,            /* rear center */
 315         VIRTIO_SND_CHMAP_FLC,           /* front left center */
 316         VIRTIO_SND_CHMAP_FRC,           /* front right center */
 317         VIRTIO_SND_CHMAP_RLC,           /* rear left center */
 318         VIRTIO_SND_CHMAP_RRC,           /* rear right center */
 319         VIRTIO_SND_CHMAP_FLW,           /* front left wide */
 320         VIRTIO_SND_CHMAP_FRW,           /* front right wide */
 321         VIRTIO_SND_CHMAP_FLH,           /* front left high */
 322         VIRTIO_SND_CHMAP_FCH,           /* front center high */
 323         VIRTIO_SND_CHMAP_FRH,           /* front right high */
 324         VIRTIO_SND_CHMAP_TC,            /* top center */
 325         VIRTIO_SND_CHMAP_TFL,           /* top front left */
 326         VIRTIO_SND_CHMAP_TFR,           /* top front right */
 327         VIRTIO_SND_CHMAP_TFC,           /* top front center */
 328         VIRTIO_SND_CHMAP_TRL,           /* top rear left */
 329         VIRTIO_SND_CHMAP_TRR,           /* top rear right */
 330         VIRTIO_SND_CHMAP_TRC,           /* top rear center */
 331         VIRTIO_SND_CHMAP_TFLC,          /* top front left center */
 332         VIRTIO_SND_CHMAP_TFRC,          /* top front right center */
 333         VIRTIO_SND_CHMAP_TSL,           /* top side left */
 334         VIRTIO_SND_CHMAP_TSR,           /* top side right */
 335         VIRTIO_SND_CHMAP_LLFE,          /* left LFE */
 336         VIRTIO_SND_CHMAP_RLFE,          /* right LFE */
 337         VIRTIO_SND_CHMAP_BC,            /* bottom center */
 338         VIRTIO_SND_CHMAP_BLC,           /* bottom left center */
 339         VIRTIO_SND_CHMAP_BRC            /* bottom right center */
 340 };
 341
 342 /* maximum possible number of channels */
 343 #define VIRTIO_SND_CHMAP_MAX_SIZE       18
 344
 345 struct virtio_snd_chmap_info {
 346         /* common header */
 347         struct virtio_snd_info hdr;
 348         /* dataflow direction (VIRTIO_SND_D_XXX) */
 349         uint8_t direction;
 350         /* # of valid channel position values */
 351         uint8_t channels;
 352         /* channel position values (VIRTIO_SND_CHMAP_XXX) */
 353         uint8_t positions[VIRTIO_SND_CHMAP_MAX_SIZE];
 354 };
 355
 356 /*******************************************************************************
 357  * CONTROL ELEMENTS MESSAGES
 358  */
 359 struct virtio_snd_ctl_hdr {
 360         /* VIRTIO_SND_R_CTL_XXX */
 361         struct virtio_snd_hdr hdr;
 362         /* 0 ... virtio_snd_config::controls - 1 */
 363         uint32_t control_id;
 364 };
 365
 366 /* supported roles for control elements */
 367 enum {
 368         VIRTIO_SND_CTL_ROLE_UNDEFINED = 0,
 369         VIRTIO_SND_CTL_ROLE_VOLUME,
 370         VIRTIO_SND_CTL_ROLE_MUTE,
 371         VIRTIO_SND_CTL_ROLE_GAIN
 372 };
 373
 374 /* supported value types for control elements */
 375 enum {
 376         VIRTIO_SND_CTL_TYPE_BOOLEAN = 0,
 377         VIRTIO_SND_CTL_TYPE_INTEGER,
 378         VIRTIO_SND_CTL_TYPE_INTEGER64,
 379         VIRTIO_SND_CTL_TYPE_ENUMERATED,
 380         VIRTIO_SND_CTL_TYPE_BYTES,
 381         VIRTIO_SND_CTL_TYPE_IEC958
 382 };
 383
 384 /* supported access rights for control elements */
 385 enum {
 386         VIRTIO_SND_CTL_ACCESS_READ = 0,
 387         VIRTIO_SND_CTL_ACCESS_WRITE,
 388         VIRTIO_SND_CTL_ACCESS_VOLATILE,
 389         VIRTIO_SND_CTL_ACCESS_INACTIVE,
 390         VIRTIO_SND_CTL_ACCESS_TLV_READ,
 391         VIRTIO_SND_CTL_ACCESS_TLV_WRITE,
 392         VIRTIO_SND_CTL_ACCESS_TLV_COMMAND
 393 };
 394
 395 struct virtio_snd_ctl_info {
 396         /* common header */
 397         struct virtio_snd_info hdr;
 398         /* element role (VIRTIO_SND_CTL_ROLE_XXX) */
 399         uint32_t role;
 400         /* element value type (VIRTIO_SND_CTL_TYPE_XXX) */
 401         uint32_t type;
 402         /* element access right bit map (1 << VIRTIO_SND_CTL_ACCESS_XXX) */
 403         uint32_t access;
 404         /* # of members in the element value */
 405         uint32_t count;
 406         /* index for an element with a non-unique name */
 407         uint32_t index;
 408         /* name identifier string for the element */
 409         uint8_t name[44];
 410         /* additional information about the element's value */
 411         union {
 412                 /* VIRTIO_SND_CTL_TYPE_INTEGER */
 413                 struct {
 414                         /* minimum supported value */
 415                         uint32_t min;
 416                         /* maximum supported value */
 417                         uint32_t max;
 418                         /* fixed step size for value (0 = variable size) */
 419                         uint32_t step;
 420                 } integer;
 421                 /* VIRTIO_SND_CTL_TYPE_INTEGER64 */
 422                 struct {
 423                         /* minimum supported value */
 424                         uint64_t min;
 425                         /* maximum supported value */
 426                         uint64_t max;
 427                         /* fixed step size for value (0 = variable size) */
 428                         uint64_t step;
 429                 } integer64;
 430                 /* VIRTIO_SND_CTL_TYPE_ENUMERATED */
 431                 struct {
 432                         /* # of options supported for value */
 433                         uint32_t items;
 434                 } enumerated;
 435         } value;
 436 };
 437
 438 struct virtio_snd_ctl_enum_item {
 439         /* option name */
 440         uint8_t item[64];
 441 };
 442
 443 struct virtio_snd_ctl_iec958 {
 444         /* AES/IEC958 channel status bits */
 445         uint8_t status[24];
 446         /* AES/IEC958 subcode bits */
 447         uint8_t subcode[147];
 448         /* nothing */
 449         uint8_t pad;
 450         /* AES/IEC958 subframe bits */
 451         uint8_t dig_subframe[4];
 452 };
 453
 454 struct virtio_snd_ctl_value {
 455         union {
 456                 /* VIRTIO_SND_CTL_TYPE_BOOLEAN|INTEGER value */
 457                 uint32_t integer[128];
 458                 /* VIRTIO_SND_CTL_TYPE_INTEGER64 value */
 459                 uint64_t integer64[64];
 460                 /* VIRTIO_SND_CTL_TYPE_ENUMERATED value (option indexes) */
 461                 uint32_t enumerated[128];
 462                 /* VIRTIO_SND_CTL_TYPE_BYTES value */
 463                 uint8_t bytes[512];
 464                 /* VIRTIO_SND_CTL_TYPE_IEC958 value */
 465                 struct virtio_snd_ctl_iec958 iec958;
 466         } value;
 467 };
 468
 469 /* supported event reason types */
 470 enum {
 471         /* element's value has changed */
 472         VIRTIO_SND_CTL_EVT_MASK_VALUE = 0,
 473         /* element's information has changed */
 474         VIRTIO_SND_CTL_EVT_MASK_INFO,
 475         /* element's metadata has changed */
 476         VIRTIO_SND_CTL_EVT_MASK_TLV
 477 };
 478
 479 struct virtio_snd_ctl_event {
 480         /* VIRTIO_SND_EVT_CTL_NOTIFY */
 481         struct virtio_snd_hdr hdr;
 482         /* 0 ... virtio_snd_config::controls - 1 */
 483         uint16_t control_id;
 484         /* event reason bit map (1 << VIRTIO_SND_CTL_EVT_MASK_XXX) */
 485         uint16_t mask;
 486 };
 487
 488 #endif /* VIRTIO_SND_IF_H */