1/****************************************************************************** 2 * sndif.h 3 * 4 * Unified sound-device I/O interface for Xen guest OSes. 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 22 * DEALINGS IN THE SOFTWARE. 23 * 24 * Copyright (C) 2013-2015 GlobalLogic Inc. 25 * Copyright (C) 2016-2017 EPAM Systems Inc. 26 * 27 * Authors: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com> 28 * Oleksandr Grytsov <oleksandr_grytsov@epam.com> 29 * Oleksandr Dmytryshyn <oleksandr.dmytryshyn@globallogic.com> 30 * Iurii Konovalenko <iurii.konovalenko@globallogic.com> 31 */ 32 33#ifndef __XEN_PUBLIC_IO_SNDIF_H__ 34#define __XEN_PUBLIC_IO_SNDIF_H__ 35 36#include "ring.h" 37#include "../grant_table.h" 38 39/* 40 ****************************************************************************** 41 * Protocol version 42 ****************************************************************************** 43 */ 44#define XENSND_PROTOCOL_VERSION 2 45 46/* 47 ****************************************************************************** 48 * Feature and Parameter Negotiation 49 ****************************************************************************** 50 * 51 * Front->back notifications: when enqueuing a new request, sending a 52 * notification can be made conditional on xensnd_req (i.e., the generic 53 * hold-off mechanism provided by the ring macros). Backends must set 54 * xensnd_req appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()). 55 * 56 * Back->front notifications: when enqueuing a new response, sending a 57 * notification can be made conditional on xensnd_resp (i.e., the generic 58 * hold-off mechanism provided by the ring macros). Frontends must set 59 * xensnd_resp appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()). 60 * 61 * The two halves of a para-virtual sound card driver utilize nodes within 62 * XenStore to communicate capabilities and to negotiate operating parameters. 63 * This section enumerates these nodes which reside in the respective front and 64 * backend portions of XenStore, following the XenBus convention. 65 * 66 * All data in XenStore is stored as strings. Nodes specifying numeric 67 * values are encoded in decimal. Integer value ranges listed below are 68 * expressed as fixed sized integer types capable of storing the conversion 69 * of a properly formated node string, without loss of information. 70 * 71 ****************************************************************************** 72 * Example configuration 73 ****************************************************************************** 74 * 75 * Note: depending on the use-case backend can expose more sound cards and 76 * PCM devices/streams than the underlying HW physically has by employing 77 * SW mixers, configuring virtual sound streams, channels etc. 78 * 79 * This is an example of backend and frontend configuration: 80 * 81 *--------------------------------- Backend ----------------------------------- 82 * 83 * /local/domain/0/backend/vsnd/1/0/frontend-id = "1" 84 * /local/domain/0/backend/vsnd/1/0/frontend = "/local/domain/1/device/vsnd/0" 85 * /local/domain/0/backend/vsnd/1/0/state = "4" 86 * /local/domain/0/backend/vsnd/1/0/versions = "1,2" 87 * 88 *--------------------------------- Frontend ---------------------------------- 89 * 90 * /local/domain/1/device/vsnd/0/backend-id = "0" 91 * /local/domain/1/device/vsnd/0/backend = "/local/domain/0/backend/vsnd/1/0" 92 * /local/domain/1/device/vsnd/0/state = "4" 93 * /local/domain/1/device/vsnd/0/version = "1" 94 * 95 *----------------------------- Card configuration ---------------------------- 96 * 97 * /local/domain/1/device/vsnd/0/short-name = "Card short name" 98 * /local/domain/1/device/vsnd/0/long-name = "Card long name" 99 * /local/domain/1/device/vsnd/0/sample-rates = "8000,32000,44100,48000,96000" 100 * /local/domain/1/device/vsnd/0/sample-formats = "s8,u8,s16_le,s16_be" 101 * /local/domain/1/device/vsnd/0/buffer-size = "262144" 102 * 103 *------------------------------- PCM device 0 -------------------------------- 104 * 105 * /local/domain/1/device/vsnd/0/0/name = "General analog" 106 * /local/domain/1/device/vsnd/0/0/channels-max = "5" 107 * 108 *----------------------------- Stream 0, playback ---------------------------- 109 * 110 * /local/domain/1/device/vsnd/0/0/0/type = "p" 111 * /local/domain/1/device/vsnd/0/0/0/sample-formats = "s8,u8" 112 * /local/domain/1/device/vsnd/0/0/0/unique-id = "0" 113 * 114 * /local/domain/1/device/vsnd/0/0/0/ring-ref = "386" 115 * /local/domain/1/device/vsnd/0/0/0/event-channel = "15" 116 * /local/domain/1/device/vsnd/0/0/0/evt-ring-ref = "1386" 117 * /local/domain/1/device/vsnd/0/0/0/evt-event-channel = "215" 118 * 119 *------------------------------ Stream 1, capture ---------------------------- 120 * 121 * /local/domain/1/device/vsnd/0/0/1/type = "c" 122 * /local/domain/1/device/vsnd/0/0/1/channels-max = "2" 123 * /local/domain/1/device/vsnd/0/0/1/unique-id = "1" 124 * 125 * /local/domain/1/device/vsnd/0/0/1/ring-ref = "384" 126 * /local/domain/1/device/vsnd/0/0/1/event-channel = "13" 127 * /local/domain/1/device/vsnd/0/0/1/evt-ring-ref = "1384" 128 * /local/domain/1/device/vsnd/0/0/1/evt-event-channel = "213" 129 * 130 *------------------------------- PCM device 1 -------------------------------- 131 * 132 * /local/domain/1/device/vsnd/0/1/name = "HDMI-0" 133 * /local/domain/1/device/vsnd/0/1/sample-rates = "8000,32000,44100" 134 * 135 *------------------------------ Stream 0, capture ---------------------------- 136 * 137 * /local/domain/1/device/vsnd/0/1/0/type = "c" 138 * /local/domain/1/device/vsnd/0/1/0/unique-id = "2" 139 * 140 * /local/domain/1/device/vsnd/0/1/0/ring-ref = "387" 141 * /local/domain/1/device/vsnd/0/1/0/event-channel = "151" 142 * /local/domain/1/device/vsnd/0/1/0/evt-ring-ref = "1387" 143 * /local/domain/1/device/vsnd/0/1/0/evt-event-channel = "351" 144 * 145 *------------------------------- PCM device 2 -------------------------------- 146 * 147 * /local/domain/1/device/vsnd/0/2/name = "SPDIF" 148 * 149 *----------------------------- Stream 0, playback ---------------------------- 150 * 151 * /local/domain/1/device/vsnd/0/2/0/type = "p" 152 * /local/domain/1/device/vsnd/0/2/0/unique-id = "3" 153 * 154 * /local/domain/1/device/vsnd/0/2/0/ring-ref = "389" 155 * /local/domain/1/device/vsnd/0/2/0/event-channel = "152" 156 * /local/domain/1/device/vsnd/0/2/0/evt-ring-ref = "1389" 157 * /local/domain/1/device/vsnd/0/2/0/evt-event-channel = "452" 158 * 159 ****************************************************************************** 160 * Backend XenBus Nodes 161 ****************************************************************************** 162 * 163 *----------------------------- Protocol version ------------------------------ 164 * 165 * versions 166 * Values: <string> 167 * 168 * List of XENSND_LIST_SEPARATOR separated protocol versions supported 169 * by the backend. For example "1,2,3". 170 * 171 ****************************************************************************** 172 * Frontend XenBus Nodes 173 ****************************************************************************** 174 * 175 *-------------------------------- Addressing --------------------------------- 176 * 177 * dom-id 178 * Values: <uint16_t> 179 * 180 * Domain identifier. 181 * 182 * dev-id 183 * Values: <uint16_t> 184 * 185 * Device identifier. 186 * 187 * pcm-dev-idx 188 * Values: <uint8_t> 189 * 190 * Zero based contigous index of the PCM device. 191 * 192 * stream-idx 193 * Values: <uint8_t> 194 * 195 * Zero based contigous index of the stream of the PCM device. 196 * 197 * The following pattern is used for addressing: 198 * /local/domain/<dom-id>/device/vsnd/<dev-id>/<pcm-dev-idx>/<stream-idx>/... 199 * 200 *----------------------------- Protocol version ------------------------------ 201 * 202 * version 203 * Values: <string> 204 * 205 * Protocol version, chosen among the ones supported by the backend. 206 * 207 *------------------------------- PCM settings -------------------------------- 208 * 209 * Every virtualized sound frontend has a set of PCM devices and streams, each 210 * could be individually configured. Part of the PCM configuration can be 211 * defined at higher level of the hierarchy and be fully or partially re-used 212 * by the underlying layers. These configuration values are: 213 * o number of channels (min/max) 214 * o supported sample rates 215 * o supported sample formats. 216 * E.g. one can define these values for the whole card, device or stream. 217 * Every underlying layer in turn can re-define some or all of them to better 218 * fit its needs. For example, card may define number of channels to be 219 * in [1; 8] range, and some particular stream may be limited to [1; 2] only. 220 * The rule is that the underlying layer must be a subset of the upper layer 221 * range. 222 * 223 * channels-min 224 * Values: <uint8_t> 225 * 226 * The minimum amount of channels that is supported, [1; channels-max]. 227 * Optional, if not set or omitted a value of 1 is used. 228 * 229 * channels-max 230 * Values: <uint8_t> 231 * 232 * The maximum amount of channels that is supported. 233 * Must be at least <channels-min>. 234 * 235 * sample-rates 236 * Values: <list of uint32_t> 237 * 238 * List of supported sample rates separated by XENSND_LIST_SEPARATOR. 239 * Sample rates are expressed as a list of decimal values w/o any 240 * ordering requirement. 241 * 242 * sample-formats 243 * Values: <list of XENSND_PCM_FORMAT_XXX_STR> 244 * 245 * List of supported sample formats separated by XENSND_LIST_SEPARATOR. 246 * Items must not exceed XENSND_SAMPLE_FORMAT_MAX_LEN length. 247 * 248 * buffer-size 249 * Values: <uint32_t> 250 * 251 * The maximum size in octets of the buffer to allocate per stream. 252 * 253 *----------------------- Virtual sound card settings ------------------------- 254 * short-name 255 * Values: <char[32]> 256 * 257 * Short name of the virtual sound card. Optional. 258 * 259 * long-name 260 * Values: <char[80]> 261 * 262 * Long name of the virtual sound card. Optional. 263 * 264 *----------------------------- Device settings ------------------------------- 265 * name 266 * Values: <char[80]> 267 * 268 * Name of the sound device within the virtual sound card. Optional. 269 * 270 *----------------------------- Stream settings ------------------------------- 271 * 272 * type 273 * Values: "p", "c" 274 * 275 * Stream type: "p" - playback stream, "c" - capture stream 276 * 277 * If both capture and playback are needed then two streams need to be 278 * defined under the same device. 279 * 280 * unique-id 281 * Values: <uint32_t> 282 * 283 * After stream initialization it is assigned a unique ID (within the front 284 * driver), so every stream of the frontend can be identified by the 285 * backend by this ID. This is not equal to stream-idx as the later is 286 * zero based within the device, but this index is contigous within the 287 * driver. 288 * 289 *-------------------- Stream Request Transport Parameters -------------------- 290 * 291 * event-channel 292 * Values: <uint32_t> 293 * 294 * The identifier of the Xen event channel used to signal activity 295 * in the ring buffer. 296 * 297 * ring-ref 298 * Values: <uint32_t> 299 * 300 * The Xen grant reference granting permission for the backend to map 301 * a sole page in a single page sized ring buffer. 302 * 303 *--------------------- Stream Event Transport Parameters --------------------- 304 * 305 * This communication path is used to deliver asynchronous events from backend 306 * to frontend, set up per stream. 307 * 308 * evt-event-channel 309 * Values: <uint32_t> 310 * 311 * The identifier of the Xen event channel used to signal activity 312 * in the ring buffer. 313 * 314 * evt-ring-ref 315 * Values: <uint32_t> 316 * 317 * The Xen grant reference granting permission for the backend to map 318 * a sole page in a single page sized ring buffer. 319 * 320 ****************************************************************************** 321 * STATE DIAGRAMS 322 ****************************************************************************** 323 * 324 * Tool stack creates front and back state nodes with initial state 325 * XenbusStateInitialising. 326 * Tool stack creates and sets up frontend sound configuration nodes per domain. 327 * 328 * Front Back 329 * ================================= ===================================== 330 * XenbusStateInitialising XenbusStateInitialising 331 * o Query backend device identification 332 * data. 333 * o Open and validate backend device. 334 * | 335 * | 336 * V 337 * XenbusStateInitWait 338 * 339 * o Query frontend configuration 340 * o Allocate and initialize 341 * event channels per configured 342 * playback/capture stream. 343 * o Publish transport parameters 344 * that will be in effect during 345 * this connection. 346 * | 347 * | 348 * V 349 * XenbusStateInitialised 350 * 351 * o Query frontend transport parameters. 352 * o Connect to the event channels. 353 * | 354 * | 355 * V 356 * XenbusStateConnected 357 * 358 * o Create and initialize OS 359 * virtual sound device instances 360 * as per configuration. 361 * | 362 * | 363 * V 364 * XenbusStateConnected 365 * 366 * XenbusStateUnknown 367 * XenbusStateClosed 368 * XenbusStateClosing 369 * o Remove virtual sound device 370 * o Remove event channels 371 * | 372 * | 373 * V 374 * XenbusStateClosed 375 * 376 *------------------------------- Recovery flow ------------------------------- 377 * 378 * In case of frontend unrecoverable errors backend handles that as 379 * if frontend goes into the XenbusStateClosed state. 380 * 381 * In case of backend unrecoverable errors frontend tries removing 382 * the virtualized device. If this is possible at the moment of error, 383 * then frontend goes into the XenbusStateInitialising state and is ready for 384 * new connection with backend. If the virtualized device is still in use and 385 * cannot be removed, then frontend goes into the XenbusStateReconfiguring state 386 * until either the virtualized device removed or backend initiates a new 387 * connection. On the virtualized device removal frontend goes into the 388 * XenbusStateInitialising state. 389 * 390 * Note on XenbusStateReconfiguring state of the frontend: if backend has 391 * unrecoverable errors then frontend cannot send requests to the backend 392 * and thus cannot provide functionality of the virtualized device anymore. 393 * After backend is back to normal the virtualized device may still hold some 394 * state: configuration in use, allocated buffers, client application state etc. 395 * So, in most cases, this will require frontend to implement complex recovery 396 * reconnect logic. Instead, by going into XenbusStateReconfiguring state, 397 * frontend will make sure no new clients of the virtualized device are 398 * accepted, allow existing client(s) to exit gracefully by signaling error 399 * state etc. 400 * Once all the clients are gone frontend can reinitialize the virtualized 401 * device and get into XenbusStateInitialising state again signaling the 402 * backend that a new connection can be made. 403 * 404 * There are multiple conditions possible under which frontend will go from 405 * XenbusStateReconfiguring into XenbusStateInitialising, some of them are OS 406 * specific. For example: 407 * 1. The underlying OS framework may provide callbacks to signal that the last 408 * client of the virtualized device has gone and the device can be removed 409 * 2. Frontend can schedule a deferred work (timer/tasklet/workqueue) 410 * to periodically check if this is the right time to re-try removal of 411 * the virtualized device. 412 * 3. By any other means. 413 * 414 ****************************************************************************** 415 * PCM FORMATS 416 ****************************************************************************** 417 * 418 * XENSND_PCM_FORMAT_<format>[_<endian>] 419 * 420 * format: <S/U/F><bits> or <name> 421 * S - signed, U - unsigned, F - float 422 * bits - 8, 16, 24, 32 423 * name - MU_LAW, GSM, etc. 424 * 425 * endian: <LE/BE>, may be absent 426 * LE - Little endian, BE - Big endian 427 */ 428#define XENSND_PCM_FORMAT_S8 0 429#define XENSND_PCM_FORMAT_U8 1 430#define XENSND_PCM_FORMAT_S16_LE 2 431#define XENSND_PCM_FORMAT_S16_BE 3 432#define XENSND_PCM_FORMAT_U16_LE 4 433#define XENSND_PCM_FORMAT_U16_BE 5 434#define XENSND_PCM_FORMAT_S24_LE 6 435#define XENSND_PCM_FORMAT_S24_BE 7 436#define XENSND_PCM_FORMAT_U24_LE 8 437#define XENSND_PCM_FORMAT_U24_BE 9 438#define XENSND_PCM_FORMAT_S32_LE 10 439#define XENSND_PCM_FORMAT_S32_BE 11 440#define XENSND_PCM_FORMAT_U32_LE 12 441#define XENSND_PCM_FORMAT_U32_BE 13 442#define XENSND_PCM_FORMAT_F32_LE 14 /* 4-byte float, IEEE-754 32-bit, */ 443#define XENSND_PCM_FORMAT_F32_BE 15 /* range -1.0 to 1.0 */ 444#define XENSND_PCM_FORMAT_F64_LE 16 /* 8-byte float, IEEE-754 64-bit, */ 445#define XENSND_PCM_FORMAT_F64_BE 17 /* range -1.0 to 1.0 */ 446#define XENSND_PCM_FORMAT_IEC958_SUBFRAME_LE 18 447#define XENSND_PCM_FORMAT_IEC958_SUBFRAME_BE 19 448#define XENSND_PCM_FORMAT_MU_LAW 20 449#define XENSND_PCM_FORMAT_A_LAW 21 450#define XENSND_PCM_FORMAT_IMA_ADPCM 22 451#define XENSND_PCM_FORMAT_MPEG 23 452#define XENSND_PCM_FORMAT_GSM 24 453 454/* 455 ****************************************************************************** 456 * REQUEST CODES 457 ****************************************************************************** 458 */ 459#define XENSND_OP_OPEN 0 460#define XENSND_OP_CLOSE 1 461#define XENSND_OP_READ 2 462#define XENSND_OP_WRITE 3 463#define XENSND_OP_SET_VOLUME 4 464#define XENSND_OP_GET_VOLUME 5 465#define XENSND_OP_MUTE 6 466#define XENSND_OP_UNMUTE 7 467#define XENSND_OP_TRIGGER 8 468#define XENSND_OP_HW_PARAM_QUERY 9 469 470#define XENSND_OP_TRIGGER_START 0 471#define XENSND_OP_TRIGGER_PAUSE 1 472#define XENSND_OP_TRIGGER_STOP 2 473#define XENSND_OP_TRIGGER_RESUME 3 474 475/* 476 ****************************************************************************** 477 * EVENT CODES 478 ****************************************************************************** 479 */ 480#define XENSND_EVT_CUR_POS 0 481 482/* 483 ****************************************************************************** 484 * XENSTORE FIELD AND PATH NAME STRINGS, HELPERS 485 ****************************************************************************** 486 */ 487#define XENSND_DRIVER_NAME "vsnd" 488 489#define XENSND_LIST_SEPARATOR "," 490/* Field names */ 491#define XENSND_FIELD_BE_VERSIONS "versions" 492#define XENSND_FIELD_FE_VERSION "version" 493#define XENSND_FIELD_VCARD_SHORT_NAME "short-name" 494#define XENSND_FIELD_VCARD_LONG_NAME "long-name" 495#define XENSND_FIELD_RING_REF "ring-ref" 496#define XENSND_FIELD_EVT_CHNL "event-channel" 497#define XENSND_FIELD_EVT_RING_REF "evt-ring-ref" 498#define XENSND_FIELD_EVT_EVT_CHNL "evt-event-channel" 499#define XENSND_FIELD_DEVICE_NAME "name" 500#define XENSND_FIELD_TYPE "type" 501#define XENSND_FIELD_STREAM_UNIQUE_ID "unique-id" 502#define XENSND_FIELD_CHANNELS_MIN "channels-min" 503#define XENSND_FIELD_CHANNELS_MAX "channels-max" 504#define XENSND_FIELD_SAMPLE_RATES "sample-rates" 505#define XENSND_FIELD_SAMPLE_FORMATS "sample-formats" 506#define XENSND_FIELD_BUFFER_SIZE "buffer-size" 507 508/* Stream type field values. */ 509#define XENSND_STREAM_TYPE_PLAYBACK "p" 510#define XENSND_STREAM_TYPE_CAPTURE "c" 511/* Sample rate max string length */ 512#define XENSND_SAMPLE_RATE_MAX_LEN 11 513/* Sample format field values */ 514#define XENSND_SAMPLE_FORMAT_MAX_LEN 24 515 516#define XENSND_PCM_FORMAT_S8_STR "s8" 517#define XENSND_PCM_FORMAT_U8_STR "u8" 518#define XENSND_PCM_FORMAT_S16_LE_STR "s16_le" 519#define XENSND_PCM_FORMAT_S16_BE_STR "s16_be" 520#define XENSND_PCM_FORMAT_U16_LE_STR "u16_le" 521#define XENSND_PCM_FORMAT_U16_BE_STR "u16_be" 522#define XENSND_PCM_FORMAT_S24_LE_STR "s24_le" 523#define XENSND_PCM_FORMAT_S24_BE_STR "s24_be" 524#define XENSND_PCM_FORMAT_U24_LE_STR "u24_le" 525#define XENSND_PCM_FORMAT_U24_BE_STR "u24_be" 526#define XENSND_PCM_FORMAT_S32_LE_STR "s32_le" 527#define XENSND_PCM_FORMAT_S32_BE_STR "s32_be" 528#define XENSND_PCM_FORMAT_U32_LE_STR "u32_le" 529#define XENSND_PCM_FORMAT_U32_BE_STR "u32_be" 530#define XENSND_PCM_FORMAT_F32_LE_STR "float_le" 531#define XENSND_PCM_FORMAT_F32_BE_STR "float_be" 532#define XENSND_PCM_FORMAT_F64_LE_STR "float64_le" 533#define XENSND_PCM_FORMAT_F64_BE_STR "float64_be" 534#define XENSND_PCM_FORMAT_IEC958_SUBFRAME_LE_STR "iec958_subframe_le" 535#define XENSND_PCM_FORMAT_IEC958_SUBFRAME_BE_STR "iec958_subframe_be" 536#define XENSND_PCM_FORMAT_MU_LAW_STR "mu_law" 537#define XENSND_PCM_FORMAT_A_LAW_STR "a_law" 538#define XENSND_PCM_FORMAT_IMA_ADPCM_STR "ima_adpcm" 539#define XENSND_PCM_FORMAT_MPEG_STR "mpeg" 540#define XENSND_PCM_FORMAT_GSM_STR "gsm" 541 542 543/* 544 ****************************************************************************** 545 * STATUS RETURN CODES 546 ****************************************************************************** 547 * 548 * Status return code is zero on success and -XEN_EXX on failure. 549 * 550 ****************************************************************************** 551 * Assumptions 552 ****************************************************************************** 553 * o usage of grant reference 0 as invalid grant reference: 554 * grant reference 0 is valid, but never exposed to a PV driver, 555 * because of the fact it is already in use/reserved by the PV console. 556 * o all references in this document to page sizes must be treated 557 * as pages of size XEN_PAGE_SIZE unless otherwise noted. 558 * 559 ****************************************************************************** 560 * Description of the protocol between frontend and backend driver 561 ****************************************************************************** 562 * 563 * The two halves of a Para-virtual sound driver communicate with 564 * each other using shared pages and event channels. 565 * Shared page contains a ring with request/response packets. 566 * 567 * Packets, used for input/output operations, e.g. read/write, set/get volume, 568 * etc., provide offset/length fields in order to allow asynchronous protocol 569 * operation with buffer space sharing: part of the buffer allocated at 570 * XENSND_OP_OPEN can be used for audio samples and part, for example, 571 * for volume control. 572 * 573 * All reserved fields in the structures below must be 0. 574 * 575 *---------------------------------- Requests --------------------------------- 576 * 577 * All request packets have the same length (64 octets) 578 * All request packets have common header: 579 * 0 1 2 3 octet 580 * +----------------+----------------+----------------+----------------+ 581 * | id | operation | reserved | 4 582 * +----------------+----------------+----------------+----------------+ 583 * | reserved | 8 584 * +----------------+----------------+----------------+----------------+ 585 * id - uint16_t, private guest value, echoed in response 586 * operation - uint8_t, operation code, XENSND_OP_??? 587 * 588 * For all packets which use offset and length: 589 * offset - uint32_t, read or write data offset within the shared buffer, 590 * passed with XENSND_OP_OPEN request, octets, 591 * [0; XENSND_OP_OPEN.buffer_sz - 1]. 592 * length - uint32_t, read or write data length, octets 593 * 594 * Request open - open a PCM stream for playback or capture: 595 * 596 * 0 1 2 3 octet 597 * +----------------+----------------+----------------+----------------+ 598 * | id | XENSND_OP_OPEN | reserved | 4 599 * +----------------+----------------+----------------+----------------+ 600 * | reserved | 8 601 * +----------------+----------------+----------------+----------------+ 602 * | pcm_rate | 12 603 * +----------------+----------------+----------------+----------------+ 604 * | pcm_format | pcm_channels | reserved | 16 605 * +----------------+----------------+----------------+----------------+ 606 * | buffer_sz | 20 607 * +----------------+----------------+----------------+----------------+ 608 * | gref_directory | 24 609 * +----------------+----------------+----------------+----------------+ 610 * | period_sz | 28 611 * +----------------+----------------+----------------+----------------+ 612 * | reserved | 32 613 * +----------------+----------------+----------------+----------------+ 614 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 615 * +----------------+----------------+----------------+----------------+ 616 * | reserved | 64 617 * +----------------+----------------+----------------+----------------+ 618 * 619 * pcm_rate - uint32_t, stream data rate, Hz 620 * pcm_format - uint8_t, XENSND_PCM_FORMAT_XXX value 621 * pcm_channels - uint8_t, number of channels of this stream, 622 * [channels-min; channels-max] 623 * buffer_sz - uint32_t, buffer size to be allocated, octets 624 * period_sz - uint32_t, event period size, octets 625 * This is the requested value of the period at which frontend would 626 * like to receive XENSND_EVT_CUR_POS notifications from the backend when 627 * stream position advances during playback/capture. 628 * It shows how many octets are expected to be played/captured before 629 * sending such an event. 630 * If set to 0 no XENSND_EVT_CUR_POS events are sent by the backend. 631 * 632 * gref_directory - grant_ref_t, a reference to the first shared page 633 * describing shared buffer references. At least one page exists. If shared 634 * buffer size (buffer_sz) exceeds what can be addressed by this single page, 635 * then reference to the next page must be supplied (see gref_dir_next_page 636 * below) 637 */ 638 639struct xensnd_open_req { 640 uint32_t pcm_rate; 641 uint8_t pcm_format; 642 uint8_t pcm_channels; 643 uint16_t reserved; 644 uint32_t buffer_sz; 645 grant_ref_t gref_directory; 646 uint32_t period_sz; 647}; 648 649/* 650 * Shared page for XENSND_OP_OPEN buffer descriptor (gref_directory in the 651 * request) employs a list of pages, describing all pages of the shared data 652 * buffer: 653 * 0 1 2 3 octet 654 * +----------------+----------------+----------------+----------------+ 655 * | gref_dir_next_page | 4 656 * +----------------+----------------+----------------+----------------+ 657 * | gref[0] | 8 658 * +----------------+----------------+----------------+----------------+ 659 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 660 * +----------------+----------------+----------------+----------------+ 661 * | gref[i] | i*4+8 662 * +----------------+----------------+----------------+----------------+ 663 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 664 * +----------------+----------------+----------------+----------------+ 665 * | gref[N - 1] | N*4+8 666 * +----------------+----------------+----------------+----------------+ 667 * 668 * gref_dir_next_page - grant_ref_t, reference to the next page describing 669 * page directory. Must be 0 if there are no more pages in the list. 670 * gref[i] - grant_ref_t, reference to a shared page of the buffer 671 * allocated at XENSND_OP_OPEN 672 * 673 * Number of grant_ref_t entries in the whole page directory is not 674 * passed, but instead can be calculated as: 675 * num_grefs_total = (XENSND_OP_OPEN.buffer_sz + XEN_PAGE_SIZE - 1) / 676 * XEN_PAGE_SIZE 677 */ 678 679struct xensnd_page_directory { 680 grant_ref_t gref_dir_next_page; 681 grant_ref_t gref[1]; /* Variable length */ 682}; 683 684/* 685 * Request close - close an opened pcm stream: 686 * 0 1 2 3 octet 687 * +----------------+----------------+----------------+----------------+ 688 * | id | XENSND_OP_CLOSE| reserved | 4 689 * +----------------+----------------+----------------+----------------+ 690 * | reserved | 8 691 * +----------------+----------------+----------------+----------------+ 692 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 693 * +----------------+----------------+----------------+----------------+ 694 * | reserved | 64 695 * +----------------+----------------+----------------+----------------+ 696 * 697 * Request read/write - used for read (for capture) or write (for playback): 698 * 0 1 2 3 octet 699 * +----------------+----------------+----------------+----------------+ 700 * | id | operation | reserved | 4 701 * +----------------+----------------+----------------+----------------+ 702 * | reserved | 8 703 * +----------------+----------------+----------------+----------------+ 704 * | offset | 12 705 * +----------------+----------------+----------------+----------------+ 706 * | length | 16 707 * +----------------+----------------+----------------+----------------+ 708 * | reserved | 20 709 * +----------------+----------------+----------------+----------------+ 710 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 711 * +----------------+----------------+----------------+----------------+ 712 * | reserved | 64 713 * +----------------+----------------+----------------+----------------+ 714 * 715 * operation - XENSND_OP_READ for read or XENSND_OP_WRITE for write 716 */ 717 718struct xensnd_rw_req { 719 uint32_t offset; 720 uint32_t length; 721}; 722 723/* 724 * Request set/get volume - set/get channels' volume of the stream given: 725 * 0 1 2 3 octet 726 * +----------------+----------------+----------------+----------------+ 727 * | id | operation | reserved | 4 728 * +----------------+----------------+----------------+----------------+ 729 * | reserved | 8 730 * +----------------+----------------+----------------+----------------+ 731 * | offset | 12 732 * +----------------+----------------+----------------+----------------+ 733 * | length | 16 734 * +----------------+----------------+----------------+----------------+ 735 * | reserved | 20 736 * +----------------+----------------+----------------+----------------+ 737 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 738 * +----------------+----------------+----------------+----------------+ 739 * | reserved | 64 740 * +----------------+----------------+----------------+----------------+ 741 * 742 * operation - XENSND_OP_SET_VOLUME for volume set 743 * or XENSND_OP_GET_VOLUME for volume get 744 * Buffer passed with XENSND_OP_OPEN is used to exchange volume 745 * values: 746 * 747 * 0 1 2 3 octet 748 * +----------------+----------------+----------------+----------------+ 749 * | channel[0] | 4 750 * +----------------+----------------+----------------+----------------+ 751 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 752 * +----------------+----------------+----------------+----------------+ 753 * | channel[i] | i*4 754 * +----------------+----------------+----------------+----------------+ 755 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 756 * +----------------+----------------+----------------+----------------+ 757 * | channel[N - 1] | (N-1)*4 758 * +----------------+----------------+----------------+----------------+ 759 * 760 * N = XENSND_OP_OPEN.pcm_channels 761 * i - uint8_t, index of a channel 762 * channel[i] - sint32_t, volume of i-th channel 763 * Volume is expressed as a signed value in steps of 0.001 dB, 764 * while 0 being 0 dB. 765 * 766 * Request mute/unmute - mute/unmute stream: 767 * 0 1 2 3 octet 768 * +----------------+----------------+----------------+----------------+ 769 * | id | operation | reserved | 4 770 * +----------------+----------------+----------------+----------------+ 771 * | reserved | 8 772 * +----------------+----------------+----------------+----------------+ 773 * | offset | 12 774 * +----------------+----------------+----------------+----------------+ 775 * | length | 16 776 * +----------------+----------------+----------------+----------------+ 777 * | reserved | 20 778 * +----------------+----------------+----------------+----------------+ 779 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 780 * +----------------+----------------+----------------+----------------+ 781 * | reserved | 64 782 * +----------------+----------------+----------------+----------------+ 783 * 784 * operation - XENSND_OP_MUTE for mute or XENSND_OP_UNMUTE for unmute 785 * Buffer passed with XENSND_OP_OPEN is used to exchange mute/unmute 786 * values: 787 * 788 * 0 octet 789 * +----------------+----------------+----------------+----------------+ 790 * | channel[0] | 4 791 * +----------------+----------------+----------------+----------------+ 792 * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 793 * +----------------+----------------+----------------+----------------+ 794 * | channel[i] | i*4 795 * +----------------+----------------+----------------+----------------+ 796 * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 797 * +----------------+----------------+----------------+----------------+ 798 * | channel[N - 1] | (N-1)*4 799 * +----------------+----------------+----------------+----------------+ 800 * 801 * N = XENSND_OP_OPEN.pcm_channels 802 * i - uint8_t, index of a channel 803 * channel[i] - uint8_t, non-zero if i-th channel needs to be muted/unmuted 804 * 805 *------------------------------------ N.B. ----------------------------------- 806 * 807 * The 'struct xensnd_rw_req' is also used for XENSND_OP_SET_VOLUME, 808 * XENSND_OP_GET_VOLUME, XENSND_OP_MUTE, XENSND_OP_UNMUTE. 809 * 810 * Request stream running state change - trigger PCM stream running state 811 * to start, stop, pause or resume: 812 * 813 * 0 1 2 3 octet 814 * +----------------+----------------+----------------+----------------+ 815 * | id | _OP_TRIGGER | reserved | 4 816 * +----------------+----------------+----------------+----------------+ 817 * | reserved | 8 818 * +----------------+----------------+----------------+----------------+ 819 * | type | reserved | 12 820 * +----------------+----------------+----------------+----------------+ 821 * | reserved | 16 822 * +----------------+----------------+----------------+----------------+ 823 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 824 * +----------------+----------------+----------------+----------------+ 825 * | reserved | 64 826 * +----------------+----------------+----------------+----------------+ 827 * 828 * type - uint8_t, XENSND_OP_TRIGGER_XXX value 829 */ 830 831struct xensnd_trigger_req { 832 uint8_t type; 833}; 834 835/* 836 * Request stream parameter ranges: request intervals and 837 * masks of supported ranges for stream configuration values. 838 * 839 * Sound device configuration for a particular stream is a limited subset 840 * of the multidimensional configuration available on XenStore, e.g. 841 * once the frame rate has been selected there is a limited supported range 842 * for sample rates becomes available (which might be the same set configured 843 * on XenStore or less). For example, selecting 96kHz sample rate may limit 844 * number of channels available for such configuration from 4 to 2, etc. 845 * Thus, each call to XENSND_OP_HW_PARAM_QUERY may reduce configuration 846 * space making it possible to iteratively get the final stream configuration, 847 * used in XENSND_OP_OPEN request. 848 * 849 * See response format for this request. 850 * 851 * 0 1 2 3 octet 852 * +----------------+----------------+----------------+----------------+ 853 * | id | _HW_PARAM_QUERY| reserved | 4 854 * +----------------+----------------+----------------+----------------+ 855 * | reserved | 8 856 * +----------------+----------------+----------------+----------------+ 857 * | formats mask low 32-bit | 12 858 * +----------------+----------------+----------------+----------------+ 859 * | formats mask high 32-bit | 16 860 * +----------------+----------------+----------------+----------------+ 861 * | min rate | 20 862 * +----------------+----------------+----------------+----------------+ 863 * | max rate | 24 864 * +----------------+----------------+----------------+----------------+ 865 * | min channels | 28 866 * +----------------+----------------+----------------+----------------+ 867 * | max channels | 32 868 * +----------------+----------------+----------------+----------------+ 869 * | min buffer frames | 36 870 * +----------------+----------------+----------------+----------------+ 871 * | max buffer frames | 40 872 * +----------------+----------------+----------------+----------------+ 873 * | min period frames | 44 874 * +----------------+----------------+----------------+----------------+ 875 * | max period frames | 48 876 * +----------------+----------------+----------------+----------------+ 877 * | reserved | 52 878 * +----------------+----------------+----------------+----------------+ 879 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 880 * +----------------+----------------+----------------+----------------+ 881 * | reserved | 64 882 * +----------------+----------------+----------------+----------------+ 883 * 884 * formats - uint64_t, bit mask representing values of the parameter 885 * made as bitwise OR of (1 << XENSND_PCM_FORMAT_XXX) values 886 * 887 * For interval parameters: 888 * min - uint32_t, minimum value of the parameter 889 * max - uint32_t, maximum value of the parameter 890 * 891 * Frame is defined as a product of the number of channels by the 892 * number of octets per one sample. 893 */ 894 895struct xensnd_query_hw_param { 896 uint64_t formats; 897 struct { 898 uint32_t min; 899 uint32_t max; 900 } rates; 901 struct { 902 uint32_t min; 903 uint32_t max; 904 } channels; 905 struct { 906 uint32_t min; 907 uint32_t max; 908 } buffer; 909 struct { 910 uint32_t min; 911 uint32_t max; 912 } period; 913}; 914 915/* 916 *---------------------------------- Responses -------------------------------- 917 * 918 * All response packets have the same length (64 octets) 919 * 920 * All response packets have common header: 921 * 0 1 2 3 octet 922 * +----------------+----------------+----------------+----------------+ 923 * | id | operation | reserved | 4 924 * +----------------+----------------+----------------+----------------+ 925 * | status | 8 926 * +----------------+----------------+----------------+----------------+ 927 * 928 * id - uint16_t, copied from the request 929 * operation - uint8_t, XENSND_OP_* - copied from request 930 * status - int32_t, response status, zero on success and -XEN_EXX on failure 931 * 932 * 933 * HW parameter query response - response for XENSND_OP_HW_PARAM_QUERY: 934 * 0 1 2 3 octet 935 * +----------------+----------------+----------------+----------------+ 936 * | id | operation | reserved | 4 937 * +----------------+----------------+----------------+----------------+ 938 * | status | 8 939 * +----------------+----------------+----------------+----------------+ 940 * | formats mask low 32-bit | 12 941 * +----------------+----------------+----------------+----------------+ 942 * | formats mask high 32-bit | 16 943 * +----------------+----------------+----------------+----------------+ 944 * | min rate | 20 945 * +----------------+----------------+----------------+----------------+ 946 * | max rate | 24 947 * +----------------+----------------+----------------+----------------+ 948 * | min channels | 28 949 * +----------------+----------------+----------------+----------------+ 950 * | max channels | 32 951 * +----------------+----------------+----------------+----------------+ 952 * | min buffer frames | 36 953 * +----------------+----------------+----------------+----------------+ 954 * | max buffer frames | 40 955 * +----------------+----------------+----------------+----------------+ 956 * | min period frames | 44 957 * +----------------+----------------+----------------+----------------+ 958 * | max period frames | 48 959 * +----------------+----------------+----------------+----------------+ 960 * | reserved | 52 961 * +----------------+----------------+----------------+----------------+ 962 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 963 * +----------------+----------------+----------------+----------------+ 964 * | reserved | 64 965 * +----------------+----------------+----------------+----------------+ 966 * 967 * Meaning of the values in this response is the same as for 968 * XENSND_OP_HW_PARAM_QUERY request. 969 */ 970 971/* 972 *----------------------------------- Events ---------------------------------- 973 * 974 * Events are sent via shared page allocated by the front and propagated by 975 * evt-event-channel/evt-ring-ref XenStore entries 976 * All event packets have the same length (64 octets) 977 * All event packets have common header: 978 * 0 1 2 3 octet 979 * +----------------+----------------+----------------+----------------+ 980 * | id | type | reserved | 4 981 * +----------------+----------------+----------------+----------------+ 982 * | reserved | 8 983 * +----------------+----------------+----------------+----------------+ 984 * 985 * id - uint16_t, event id, may be used by front 986 * type - uint8_t, type of the event 987 * 988 * 989 * Current stream position - event from back to front when stream's 990 * playback/capture position has advanced: 991 * 0 1 2 3 octet 992 * +----------------+----------------+----------------+----------------+ 993 * | id | _EVT_CUR_POS | reserved | 4 994 * +----------------+----------------+----------------+----------------+ 995 * | reserved | 8 996 * +----------------+----------------+----------------+----------------+ 997 * | position low 32-bit | 12 998 * +----------------+----------------+----------------+----------------+ 999 * | position high 32-bit | 16 1000 * +----------------+----------------+----------------+----------------+
1001 * | reserved | 20 1002 * +----------------+----------------+----------------+----------------+ 1003 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 1004 * +----------------+----------------+----------------+----------------+ 1005 * | reserved | 64 1006 * +----------------+----------------+----------------+----------------+ 1007 * 1008 * position - current value of stream's playback/capture position, octets 1009 * 1010 */ 1011 1012struct xensnd_cur_pos_evt { 1013 uint64_t position; 1014}; 1015 1016struct xensnd_req { 1017 uint16_t id; 1018 uint8_t operation; 1019 uint8_t reserved[5]; 1020 union { 1021 struct xensnd_open_req open; 1022 struct xensnd_rw_req rw; 1023 struct xensnd_trigger_req trigger; 1024 struct xensnd_query_hw_param hw_param; 1025 uint8_t reserved[56]; 1026 } op; 1027}; 1028 1029struct xensnd_resp { 1030 uint16_t id; 1031 uint8_t operation; 1032 uint8_t reserved; 1033 int32_t status; 1034 union { 1035 struct xensnd_query_hw_param hw_param; 1036 uint8_t reserved1[56]; 1037 } resp; 1038}; 1039 1040struct xensnd_evt { 1041 uint16_t id; 1042 uint8_t type; 1043 uint8_t reserved[5]; 1044 union { 1045 struct xensnd_cur_pos_evt cur_pos; 1046 uint8_t reserved[56]; 1047 } op; 1048}; 1049 1050DEFINE_RING_TYPES(xen_sndif, struct xensnd_req, struct xensnd_resp); 1051 1052/* 1053 ****************************************************************************** 1054 * Back to front events delivery 1055 ****************************************************************************** 1056 * In order to deliver asynchronous events from back to front a shared page is 1057 * allocated by front and its granted reference propagated to back via 1058 * XenStore entries (evt-ring-ref/evt-event-channel). 1059 * This page has a common header used by both front and back to synchronize 1060 * access and control event's ring buffer, while back being a producer of the 1061 * events and front being a consumer. The rest of the page after the header 1062 * is used for event packets. 1063 * 1064 * Upon reception of an event(s) front may confirm its reception 1065 * for either each event, group of events or none. 1066 */ 1067 1068struct xensnd_event_page { 1069 uint32_t in_cons; 1070 uint32_t in_prod; 1071 uint8_t reserved[56]; 1072}; 1073 1074#define XENSND_EVENT_PAGE_SIZE XEN_PAGE_SIZE 1075#define XENSND_IN_RING_OFFS (sizeof(struct xensnd_event_page)) 1076#define XENSND_IN_RING_SIZE (XENSND_EVENT_PAGE_SIZE - XENSND_IN_RING_OFFS) 1077#define XENSND_IN_RING_LEN (XENSND_IN_RING_SIZE / sizeof(struct xensnd_evt)) 1078#define XENSND_IN_RING(page) \ 1079 ((struct xensnd_evt *)((char *)(page) + XENSND_IN_RING_OFFS)) 1080#define XENSND_IN_RING_REF(page, idx) \ 1081 (XENSND_IN_RING((page))[(idx) % XENSND_IN_RING_LEN]) 1082 1083#endif /* __XEN_PUBLIC_IO_SNDIF_H__ */ 1084