13a9fd824SRoger Pau Monné /****************************************************************************** 23a9fd824SRoger Pau Monné * sndif.h 33a9fd824SRoger Pau Monné * 43a9fd824SRoger Pau Monné * Unified sound-device I/O interface for Xen guest OSes. 53a9fd824SRoger Pau Monné * 63a9fd824SRoger Pau Monné * Permission is hereby granted, free of charge, to any person obtaining a copy 73a9fd824SRoger Pau Monné * of this software and associated documentation files (the "Software"), to 83a9fd824SRoger Pau Monné * deal in the Software without restriction, including without limitation the 93a9fd824SRoger Pau Monné * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 103a9fd824SRoger Pau Monné * sell copies of the Software, and to permit persons to whom the Software is 113a9fd824SRoger Pau Monné * furnished to do so, subject to the following conditions: 123a9fd824SRoger Pau Monné * 133a9fd824SRoger Pau Monné * The above copyright notice and this permission notice shall be included in 143a9fd824SRoger Pau Monné * all copies or substantial portions of the Software. 153a9fd824SRoger Pau Monné * 163a9fd824SRoger Pau Monné * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 173a9fd824SRoger Pau Monné * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 183a9fd824SRoger Pau Monné * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 193a9fd824SRoger Pau Monné * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 203a9fd824SRoger Pau Monné * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 213a9fd824SRoger Pau Monné * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 223a9fd824SRoger Pau Monné * DEALINGS IN THE SOFTWARE. 233a9fd824SRoger Pau Monné * 243a9fd824SRoger Pau Monné * Copyright (C) 2013-2015 GlobalLogic Inc. 253a9fd824SRoger Pau Monné * Copyright (C) 2016-2017 EPAM Systems Inc. 263a9fd824SRoger Pau Monné * 273a9fd824SRoger Pau Monné * Authors: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com> 283a9fd824SRoger Pau Monné * Oleksandr Grytsov <oleksandr_grytsov@epam.com> 293a9fd824SRoger Pau Monné * Oleksandr Dmytryshyn <oleksandr.dmytryshyn@globallogic.com> 303a9fd824SRoger Pau Monné * Iurii Konovalenko <iurii.konovalenko@globallogic.com> 313a9fd824SRoger Pau Monné */ 323a9fd824SRoger Pau Monné 333a9fd824SRoger Pau Monné #ifndef __XEN_PUBLIC_IO_SNDIF_H__ 343a9fd824SRoger Pau Monné #define __XEN_PUBLIC_IO_SNDIF_H__ 353a9fd824SRoger Pau Monné 363a9fd824SRoger Pau Monné #include "ring.h" 373a9fd824SRoger Pau Monné #include "../grant_table.h" 383a9fd824SRoger Pau Monné 393a9fd824SRoger Pau Monné /* 403a9fd824SRoger Pau Monné ****************************************************************************** 413a9fd824SRoger Pau Monné * Protocol version 423a9fd824SRoger Pau Monné ****************************************************************************** 433a9fd824SRoger Pau Monné */ 443a9fd824SRoger Pau Monné #define XENSND_PROTOCOL_VERSION 2 453a9fd824SRoger Pau Monné 463a9fd824SRoger Pau Monné /* 473a9fd824SRoger Pau Monné ****************************************************************************** 483a9fd824SRoger Pau Monné * Feature and Parameter Negotiation 493a9fd824SRoger Pau Monné ****************************************************************************** 503a9fd824SRoger Pau Monné * 513a9fd824SRoger Pau Monné * Front->back notifications: when enqueuing a new request, sending a 523a9fd824SRoger Pau Monné * notification can be made conditional on xensnd_req (i.e., the generic 533a9fd824SRoger Pau Monné * hold-off mechanism provided by the ring macros). Backends must set 543a9fd824SRoger Pau Monné * xensnd_req appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()). 553a9fd824SRoger Pau Monné * 563a9fd824SRoger Pau Monné * Back->front notifications: when enqueuing a new response, sending a 573a9fd824SRoger Pau Monné * notification can be made conditional on xensnd_resp (i.e., the generic 583a9fd824SRoger Pau Monné * hold-off mechanism provided by the ring macros). Frontends must set 593a9fd824SRoger Pau Monné * xensnd_resp appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()). 603a9fd824SRoger Pau Monné * 613a9fd824SRoger Pau Monné * The two halves of a para-virtual sound card driver utilize nodes within 623a9fd824SRoger Pau Monné * XenStore to communicate capabilities and to negotiate operating parameters. 633a9fd824SRoger Pau Monné * This section enumerates these nodes which reside in the respective front and 643a9fd824SRoger Pau Monné * backend portions of XenStore, following the XenBus convention. 653a9fd824SRoger Pau Monné * 663a9fd824SRoger Pau Monné * All data in XenStore is stored as strings. Nodes specifying numeric 673a9fd824SRoger Pau Monné * values are encoded in decimal. Integer value ranges listed below are 683a9fd824SRoger Pau Monné * expressed as fixed sized integer types capable of storing the conversion 693a9fd824SRoger Pau Monné * of a properly formated node string, without loss of information. 703a9fd824SRoger Pau Monné * 713a9fd824SRoger Pau Monné ****************************************************************************** 723a9fd824SRoger Pau Monné * Example configuration 733a9fd824SRoger Pau Monné ****************************************************************************** 743a9fd824SRoger Pau Monné * 753a9fd824SRoger Pau Monné * Note: depending on the use-case backend can expose more sound cards and 763a9fd824SRoger Pau Monné * PCM devices/streams than the underlying HW physically has by employing 773a9fd824SRoger Pau Monné * SW mixers, configuring virtual sound streams, channels etc. 783a9fd824SRoger Pau Monné * 793a9fd824SRoger Pau Monné * This is an example of backend and frontend configuration: 803a9fd824SRoger Pau Monné * 813a9fd824SRoger Pau Monné *--------------------------------- Backend ----------------------------------- 823a9fd824SRoger Pau Monné * 833a9fd824SRoger Pau Monné * /local/domain/0/backend/vsnd/1/0/frontend-id = "1" 843a9fd824SRoger Pau Monné * /local/domain/0/backend/vsnd/1/0/frontend = "/local/domain/1/device/vsnd/0" 853a9fd824SRoger Pau Monné * /local/domain/0/backend/vsnd/1/0/state = "4" 863a9fd824SRoger Pau Monné * /local/domain/0/backend/vsnd/1/0/versions = "1,2" 873a9fd824SRoger Pau Monné * 883a9fd824SRoger Pau Monné *--------------------------------- Frontend ---------------------------------- 893a9fd824SRoger Pau Monné * 903a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/backend-id = "0" 913a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/backend = "/local/domain/0/backend/vsnd/1/0" 923a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/state = "4" 933a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/version = "1" 943a9fd824SRoger Pau Monné * 953a9fd824SRoger Pau Monné *----------------------------- Card configuration ---------------------------- 963a9fd824SRoger Pau Monné * 973a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/short-name = "Card short name" 983a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/long-name = "Card long name" 993a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/sample-rates = "8000,32000,44100,48000,96000" 1003a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/sample-formats = "s8,u8,s16_le,s16_be" 1013a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/buffer-size = "262144" 1023a9fd824SRoger Pau Monné * 1033a9fd824SRoger Pau Monné *------------------------------- PCM device 0 -------------------------------- 1043a9fd824SRoger Pau Monné * 1053a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/name = "General analog" 1063a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/channels-max = "5" 1073a9fd824SRoger Pau Monné * 1083a9fd824SRoger Pau Monné *----------------------------- Stream 0, playback ---------------------------- 1093a9fd824SRoger Pau Monné * 1103a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/0/type = "p" 1113a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/0/sample-formats = "s8,u8" 1123a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/0/unique-id = "0" 1133a9fd824SRoger Pau Monné * 1143a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/0/ring-ref = "386" 1153a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/0/event-channel = "15" 1163a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/0/evt-ring-ref = "1386" 1173a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/0/evt-event-channel = "215" 1183a9fd824SRoger Pau Monné * 1193a9fd824SRoger Pau Monné *------------------------------ Stream 1, capture ---------------------------- 1203a9fd824SRoger Pau Monné * 1213a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/1/type = "c" 1223a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/1/channels-max = "2" 1233a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/1/unique-id = "1" 1243a9fd824SRoger Pau Monné * 1253a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/1/ring-ref = "384" 1263a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/1/event-channel = "13" 1273a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/1/evt-ring-ref = "1384" 1283a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/0/1/evt-event-channel = "213" 1293a9fd824SRoger Pau Monné * 1303a9fd824SRoger Pau Monné *------------------------------- PCM device 1 -------------------------------- 1313a9fd824SRoger Pau Monné * 1323a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/1/name = "HDMI-0" 1333a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/1/sample-rates = "8000,32000,44100" 1343a9fd824SRoger Pau Monné * 1353a9fd824SRoger Pau Monné *------------------------------ Stream 0, capture ---------------------------- 1363a9fd824SRoger Pau Monné * 1373a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/1/0/type = "c" 1383a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/1/0/unique-id = "2" 1393a9fd824SRoger Pau Monné * 1403a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/1/0/ring-ref = "387" 1413a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/1/0/event-channel = "151" 1423a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/1/0/evt-ring-ref = "1387" 1433a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/1/0/evt-event-channel = "351" 1443a9fd824SRoger Pau Monné * 1453a9fd824SRoger Pau Monné *------------------------------- PCM device 2 -------------------------------- 1463a9fd824SRoger Pau Monné * 1473a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/2/name = "SPDIF" 1483a9fd824SRoger Pau Monné * 1493a9fd824SRoger Pau Monné *----------------------------- Stream 0, playback ---------------------------- 1503a9fd824SRoger Pau Monné * 1513a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/2/0/type = "p" 1523a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/2/0/unique-id = "3" 1533a9fd824SRoger Pau Monné * 1543a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/2/0/ring-ref = "389" 1553a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/2/0/event-channel = "152" 1563a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/2/0/evt-ring-ref = "1389" 1573a9fd824SRoger Pau Monné * /local/domain/1/device/vsnd/0/2/0/evt-event-channel = "452" 1583a9fd824SRoger Pau Monné * 1593a9fd824SRoger Pau Monné ****************************************************************************** 1603a9fd824SRoger Pau Monné * Backend XenBus Nodes 1613a9fd824SRoger Pau Monné ****************************************************************************** 1623a9fd824SRoger Pau Monné * 1633a9fd824SRoger Pau Monné *----------------------------- Protocol version ------------------------------ 1643a9fd824SRoger Pau Monné * 1653a9fd824SRoger Pau Monné * versions 1663a9fd824SRoger Pau Monné * Values: <string> 1673a9fd824SRoger Pau Monné * 1683a9fd824SRoger Pau Monné * List of XENSND_LIST_SEPARATOR separated protocol versions supported 1693a9fd824SRoger Pau Monné * by the backend. For example "1,2,3". 1703a9fd824SRoger Pau Monné * 1713a9fd824SRoger Pau Monné ****************************************************************************** 1723a9fd824SRoger Pau Monné * Frontend XenBus Nodes 1733a9fd824SRoger Pau Monné ****************************************************************************** 1743a9fd824SRoger Pau Monné * 1753a9fd824SRoger Pau Monné *-------------------------------- Addressing --------------------------------- 1763a9fd824SRoger Pau Monné * 1773a9fd824SRoger Pau Monné * dom-id 1783a9fd824SRoger Pau Monné * Values: <uint16_t> 1793a9fd824SRoger Pau Monné * 1803a9fd824SRoger Pau Monné * Domain identifier. 1813a9fd824SRoger Pau Monné * 1823a9fd824SRoger Pau Monné * dev-id 1833a9fd824SRoger Pau Monné * Values: <uint16_t> 1843a9fd824SRoger Pau Monné * 1853a9fd824SRoger Pau Monné * Device identifier. 1863a9fd824SRoger Pau Monné * 1873a9fd824SRoger Pau Monné * pcm-dev-idx 1883a9fd824SRoger Pau Monné * Values: <uint8_t> 1893a9fd824SRoger Pau Monné * 1903a9fd824SRoger Pau Monné * Zero based contigous index of the PCM device. 1913a9fd824SRoger Pau Monné * 1923a9fd824SRoger Pau Monné * stream-idx 1933a9fd824SRoger Pau Monné * Values: <uint8_t> 1943a9fd824SRoger Pau Monné * 1953a9fd824SRoger Pau Monné * Zero based contigous index of the stream of the PCM device. 1963a9fd824SRoger Pau Monné * 1973a9fd824SRoger Pau Monné * The following pattern is used for addressing: 1983a9fd824SRoger Pau Monné * /local/domain/<dom-id>/device/vsnd/<dev-id>/<pcm-dev-idx>/<stream-idx>/... 1993a9fd824SRoger Pau Monné * 2003a9fd824SRoger Pau Monné *----------------------------- Protocol version ------------------------------ 2013a9fd824SRoger Pau Monné * 2023a9fd824SRoger Pau Monné * version 2033a9fd824SRoger Pau Monné * Values: <string> 2043a9fd824SRoger Pau Monné * 2053a9fd824SRoger Pau Monné * Protocol version, chosen among the ones supported by the backend. 2063a9fd824SRoger Pau Monné * 2073a9fd824SRoger Pau Monné *------------------------------- PCM settings -------------------------------- 2083a9fd824SRoger Pau Monné * 2093a9fd824SRoger Pau Monné * Every virtualized sound frontend has a set of PCM devices and streams, each 2103a9fd824SRoger Pau Monné * could be individually configured. Part of the PCM configuration can be 2113a9fd824SRoger Pau Monné * defined at higher level of the hierarchy and be fully or partially re-used 2123a9fd824SRoger Pau Monné * by the underlying layers. These configuration values are: 2133a9fd824SRoger Pau Monné * o number of channels (min/max) 2143a9fd824SRoger Pau Monné * o supported sample rates 2153a9fd824SRoger Pau Monné * o supported sample formats. 2163a9fd824SRoger Pau Monné * E.g. one can define these values for the whole card, device or stream. 2173a9fd824SRoger Pau Monné * Every underlying layer in turn can re-define some or all of them to better 2183a9fd824SRoger Pau Monné * fit its needs. For example, card may define number of channels to be 2193a9fd824SRoger Pau Monné * in [1; 8] range, and some particular stream may be limited to [1; 2] only. 2203a9fd824SRoger Pau Monné * The rule is that the underlying layer must be a subset of the upper layer 2213a9fd824SRoger Pau Monné * range. 2223a9fd824SRoger Pau Monné * 2233a9fd824SRoger Pau Monné * channels-min 2243a9fd824SRoger Pau Monné * Values: <uint8_t> 2253a9fd824SRoger Pau Monné * 2263a9fd824SRoger Pau Monné * The minimum amount of channels that is supported, [1; channels-max]. 2273a9fd824SRoger Pau Monné * Optional, if not set or omitted a value of 1 is used. 2283a9fd824SRoger Pau Monné * 2293a9fd824SRoger Pau Monné * channels-max 2303a9fd824SRoger Pau Monné * Values: <uint8_t> 2313a9fd824SRoger Pau Monné * 2323a9fd824SRoger Pau Monné * The maximum amount of channels that is supported. 2333a9fd824SRoger Pau Monné * Must be at least <channels-min>. 2343a9fd824SRoger Pau Monné * 2353a9fd824SRoger Pau Monné * sample-rates 2363a9fd824SRoger Pau Monné * Values: <list of uint32_t> 2373a9fd824SRoger Pau Monné * 2383a9fd824SRoger Pau Monné * List of supported sample rates separated by XENSND_LIST_SEPARATOR. 2393a9fd824SRoger Pau Monné * Sample rates are expressed as a list of decimal values w/o any 2403a9fd824SRoger Pau Monné * ordering requirement. 2413a9fd824SRoger Pau Monné * 2423a9fd824SRoger Pau Monné * sample-formats 2433a9fd824SRoger Pau Monné * Values: <list of XENSND_PCM_FORMAT_XXX_STR> 2443a9fd824SRoger Pau Monné * 2453a9fd824SRoger Pau Monné * List of supported sample formats separated by XENSND_LIST_SEPARATOR. 2463a9fd824SRoger Pau Monné * Items must not exceed XENSND_SAMPLE_FORMAT_MAX_LEN length. 2473a9fd824SRoger Pau Monné * 2483a9fd824SRoger Pau Monné * buffer-size 2493a9fd824SRoger Pau Monné * Values: <uint32_t> 2503a9fd824SRoger Pau Monné * 2513a9fd824SRoger Pau Monné * The maximum size in octets of the buffer to allocate per stream. 2523a9fd824SRoger Pau Monné * 2533a9fd824SRoger Pau Monné *----------------------- Virtual sound card settings ------------------------- 2543a9fd824SRoger Pau Monné * short-name 2553a9fd824SRoger Pau Monné * Values: <char[32]> 2563a9fd824SRoger Pau Monné * 2573a9fd824SRoger Pau Monné * Short name of the virtual sound card. Optional. 2583a9fd824SRoger Pau Monné * 2593a9fd824SRoger Pau Monné * long-name 2603a9fd824SRoger Pau Monné * Values: <char[80]> 2613a9fd824SRoger Pau Monné * 2623a9fd824SRoger Pau Monné * Long name of the virtual sound card. Optional. 2633a9fd824SRoger Pau Monné * 2643a9fd824SRoger Pau Monné *----------------------------- Device settings ------------------------------- 2653a9fd824SRoger Pau Monné * name 2663a9fd824SRoger Pau Monné * Values: <char[80]> 2673a9fd824SRoger Pau Monné * 2683a9fd824SRoger Pau Monné * Name of the sound device within the virtual sound card. Optional. 2693a9fd824SRoger Pau Monné * 2703a9fd824SRoger Pau Monné *----------------------------- Stream settings ------------------------------- 2713a9fd824SRoger Pau Monné * 2723a9fd824SRoger Pau Monné * type 2733a9fd824SRoger Pau Monné * Values: "p", "c" 2743a9fd824SRoger Pau Monné * 2753a9fd824SRoger Pau Monné * Stream type: "p" - playback stream, "c" - capture stream 2763a9fd824SRoger Pau Monné * 2773a9fd824SRoger Pau Monné * If both capture and playback are needed then two streams need to be 2783a9fd824SRoger Pau Monné * defined under the same device. 2793a9fd824SRoger Pau Monné * 2803a9fd824SRoger Pau Monné * unique-id 2813a9fd824SRoger Pau Monné * Values: <string> 2823a9fd824SRoger Pau Monné * 2833a9fd824SRoger Pau Monné * After stream initialization it is assigned a unique ID, so every 2843a9fd824SRoger Pau Monné * stream of the frontend can be identified by the backend by this ID. 2853a9fd824SRoger Pau Monné * This can be UUID or such. 2863a9fd824SRoger Pau Monné * 2873a9fd824SRoger Pau Monné *-------------------- Stream Request Transport Parameters -------------------- 2883a9fd824SRoger Pau Monné * 2893a9fd824SRoger Pau Monné * event-channel 2903a9fd824SRoger Pau Monné * Values: <uint32_t> 2913a9fd824SRoger Pau Monné * 2923a9fd824SRoger Pau Monné * The identifier of the Xen event channel used to signal activity 2933a9fd824SRoger Pau Monné * in the ring buffer. 2943a9fd824SRoger Pau Monné * 2953a9fd824SRoger Pau Monné * ring-ref 2963a9fd824SRoger Pau Monné * Values: <uint32_t> 2973a9fd824SRoger Pau Monné * 2983a9fd824SRoger Pau Monné * The Xen grant reference granting permission for the backend to map 2993a9fd824SRoger Pau Monné * a sole page in a single page sized ring buffer. 3003a9fd824SRoger Pau Monné * 3013a9fd824SRoger Pau Monné *--------------------- Stream Event Transport Parameters --------------------- 3023a9fd824SRoger Pau Monné * 3033a9fd824SRoger Pau Monné * This communication path is used to deliver asynchronous events from backend 3043a9fd824SRoger Pau Monné * to frontend, set up per stream. 3053a9fd824SRoger Pau Monné * 3063a9fd824SRoger Pau Monné * evt-event-channel 3073a9fd824SRoger Pau Monné * Values: <uint32_t> 3083a9fd824SRoger Pau Monné * 3093a9fd824SRoger Pau Monné * The identifier of the Xen event channel used to signal activity 3103a9fd824SRoger Pau Monné * in the ring buffer. 3113a9fd824SRoger Pau Monné * 3123a9fd824SRoger Pau Monné * evt-ring-ref 3133a9fd824SRoger Pau Monné * Values: <uint32_t> 3143a9fd824SRoger Pau Monné * 3153a9fd824SRoger Pau Monné * The Xen grant reference granting permission for the backend to map 3163a9fd824SRoger Pau Monné * a sole page in a single page sized ring buffer. 3173a9fd824SRoger Pau Monné * 3183a9fd824SRoger Pau Monné ****************************************************************************** 3193a9fd824SRoger Pau Monné * STATE DIAGRAMS 3203a9fd824SRoger Pau Monné ****************************************************************************** 3213a9fd824SRoger Pau Monné * 3223a9fd824SRoger Pau Monné * Tool stack creates front and back state nodes with initial state 3233a9fd824SRoger Pau Monné * XenbusStateInitialising. 3243a9fd824SRoger Pau Monné * Tool stack creates and sets up frontend sound configuration nodes per domain. 3253a9fd824SRoger Pau Monné * 3263a9fd824SRoger Pau Monné * Front Back 3273a9fd824SRoger Pau Monné * ================================= ===================================== 3283a9fd824SRoger Pau Monné * XenbusStateInitialising XenbusStateInitialising 3293a9fd824SRoger Pau Monné * o Query backend device identification 3303a9fd824SRoger Pau Monné * data. 3313a9fd824SRoger Pau Monné * o Open and validate backend device. 3323a9fd824SRoger Pau Monné * | 3333a9fd824SRoger Pau Monné * | 3343a9fd824SRoger Pau Monné * V 3353a9fd824SRoger Pau Monné * XenbusStateInitWait 3363a9fd824SRoger Pau Monné * 3373a9fd824SRoger Pau Monné * o Query frontend configuration 3383a9fd824SRoger Pau Monné * o Allocate and initialize 3393a9fd824SRoger Pau Monné * event channels per configured 3403a9fd824SRoger Pau Monné * playback/capture stream. 3413a9fd824SRoger Pau Monné * o Publish transport parameters 3423a9fd824SRoger Pau Monné * that will be in effect during 3433a9fd824SRoger Pau Monné * this connection. 3443a9fd824SRoger Pau Monné * | 3453a9fd824SRoger Pau Monné * | 3463a9fd824SRoger Pau Monné * V 3473a9fd824SRoger Pau Monné * XenbusStateInitialised 3483a9fd824SRoger Pau Monné * 3493a9fd824SRoger Pau Monné * o Query frontend transport parameters. 3503a9fd824SRoger Pau Monné * o Connect to the event channels. 3513a9fd824SRoger Pau Monné * | 3523a9fd824SRoger Pau Monné * | 3533a9fd824SRoger Pau Monné * V 3543a9fd824SRoger Pau Monné * XenbusStateConnected 3553a9fd824SRoger Pau Monné * 3563a9fd824SRoger Pau Monné * o Create and initialize OS 3573a9fd824SRoger Pau Monné * virtual sound device instances 3583a9fd824SRoger Pau Monné * as per configuration. 3593a9fd824SRoger Pau Monné * | 3603a9fd824SRoger Pau Monné * | 3613a9fd824SRoger Pau Monné * V 3623a9fd824SRoger Pau Monné * XenbusStateConnected 3633a9fd824SRoger Pau Monné * 3643a9fd824SRoger Pau Monné * XenbusStateUnknown 3653a9fd824SRoger Pau Monné * XenbusStateClosed 3663a9fd824SRoger Pau Monné * XenbusStateClosing 3673a9fd824SRoger Pau Monné * o Remove virtual sound device 3683a9fd824SRoger Pau Monné * o Remove event channels 3693a9fd824SRoger Pau Monné * | 3703a9fd824SRoger Pau Monné * | 3713a9fd824SRoger Pau Monné * V 3723a9fd824SRoger Pau Monné * XenbusStateClosed 3733a9fd824SRoger Pau Monné * 3743a9fd824SRoger Pau Monné *------------------------------- Recovery flow ------------------------------- 3753a9fd824SRoger Pau Monné * 3763a9fd824SRoger Pau Monné * In case of frontend unrecoverable errors backend handles that as 3773a9fd824SRoger Pau Monné * if frontend goes into the XenbusStateClosed state. 3783a9fd824SRoger Pau Monné * 3793a9fd824SRoger Pau Monné * In case of backend unrecoverable errors frontend tries removing 3803a9fd824SRoger Pau Monné * the virtualized device. If this is possible at the moment of error, 3813a9fd824SRoger Pau Monné * then frontend goes into the XenbusStateInitialising state and is ready for 3823a9fd824SRoger Pau Monné * new connection with backend. If the virtualized device is still in use and 3833a9fd824SRoger Pau Monné * cannot be removed, then frontend goes into the XenbusStateReconfiguring state 3843a9fd824SRoger Pau Monné * until either the virtualized device removed or backend initiates a new 3853a9fd824SRoger Pau Monné * connection. On the virtualized device removal frontend goes into the 3863a9fd824SRoger Pau Monné * XenbusStateInitialising state. 3873a9fd824SRoger Pau Monné * 3883a9fd824SRoger Pau Monné * Note on XenbusStateReconfiguring state of the frontend: if backend has 3893a9fd824SRoger Pau Monné * unrecoverable errors then frontend cannot send requests to the backend 3903a9fd824SRoger Pau Monné * and thus cannot provide functionality of the virtualized device anymore. 3913a9fd824SRoger Pau Monné * After backend is back to normal the virtualized device may still hold some 3923a9fd824SRoger Pau Monné * state: configuration in use, allocated buffers, client application state etc. 3933a9fd824SRoger Pau Monné * So, in most cases, this will require frontend to implement complex recovery 3943a9fd824SRoger Pau Monné * reconnect logic. Instead, by going into XenbusStateReconfiguring state, 3953a9fd824SRoger Pau Monné * frontend will make sure no new clients of the virtualized device are 3963a9fd824SRoger Pau Monné * accepted, allow existing client(s) to exit gracefully by signaling error 3973a9fd824SRoger Pau Monné * state etc. 3983a9fd824SRoger Pau Monné * Once all the clients are gone frontend can reinitialize the virtualized 3993a9fd824SRoger Pau Monné * device and get into XenbusStateInitialising state again signaling the 4003a9fd824SRoger Pau Monné * backend that a new connection can be made. 4013a9fd824SRoger Pau Monné * 4023a9fd824SRoger Pau Monné * There are multiple conditions possible under which frontend will go from 4033a9fd824SRoger Pau Monné * XenbusStateReconfiguring into XenbusStateInitialising, some of them are OS 4043a9fd824SRoger Pau Monné * specific. For example: 4053a9fd824SRoger Pau Monné * 1. The underlying OS framework may provide callbacks to signal that the last 4063a9fd824SRoger Pau Monné * client of the virtualized device has gone and the device can be removed 4073a9fd824SRoger Pau Monné * 2. Frontend can schedule a deferred work (timer/tasklet/workqueue) 4083a9fd824SRoger Pau Monné * to periodically check if this is the right time to re-try removal of 4093a9fd824SRoger Pau Monné * the virtualized device. 4103a9fd824SRoger Pau Monné * 3. By any other means. 4113a9fd824SRoger Pau Monné * 4123a9fd824SRoger Pau Monné ****************************************************************************** 4133a9fd824SRoger Pau Monné * PCM FORMATS 4143a9fd824SRoger Pau Monné ****************************************************************************** 4153a9fd824SRoger Pau Monné * 4163a9fd824SRoger Pau Monné * XENSND_PCM_FORMAT_<format>[_<endian>] 4173a9fd824SRoger Pau Monné * 4183a9fd824SRoger Pau Monné * format: <S/U/F><bits> or <name> 4193a9fd824SRoger Pau Monné * S - signed, U - unsigned, F - float 4203a9fd824SRoger Pau Monné * bits - 8, 16, 24, 32 4213a9fd824SRoger Pau Monné * name - MU_LAW, GSM, etc. 4223a9fd824SRoger Pau Monné * 4233a9fd824SRoger Pau Monné * endian: <LE/BE>, may be absent 4243a9fd824SRoger Pau Monné * LE - Little endian, BE - Big endian 4253a9fd824SRoger Pau Monné */ 4263a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S8 0 4273a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U8 1 4283a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S16_LE 2 4293a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S16_BE 3 4303a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U16_LE 4 4313a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U16_BE 5 4323a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S24_LE 6 4333a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S24_BE 7 4343a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U24_LE 8 4353a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U24_BE 9 4363a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S32_LE 10 4373a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S32_BE 11 4383a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U32_LE 12 4393a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U32_BE 13 4403a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_F32_LE 14 /* 4-byte float, IEEE-754 32-bit, */ 4413a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_F32_BE 15 /* range -1.0 to 1.0 */ 4423a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_F64_LE 16 /* 8-byte float, IEEE-754 64-bit, */ 4433a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_F64_BE 17 /* range -1.0 to 1.0 */ 4443a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_IEC958_SUBFRAME_LE 18 4453a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_IEC958_SUBFRAME_BE 19 4463a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_MU_LAW 20 4473a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_A_LAW 21 4483a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_IMA_ADPCM 22 4493a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_MPEG 23 4503a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_GSM 24 4513a9fd824SRoger Pau Monné 4523a9fd824SRoger Pau Monné /* 4533a9fd824SRoger Pau Monné ****************************************************************************** 4543a9fd824SRoger Pau Monné * REQUEST CODES 4553a9fd824SRoger Pau Monné ****************************************************************************** 4563a9fd824SRoger Pau Monné */ 4573a9fd824SRoger Pau Monné #define XENSND_OP_OPEN 0 4583a9fd824SRoger Pau Monné #define XENSND_OP_CLOSE 1 4593a9fd824SRoger Pau Monné #define XENSND_OP_READ 2 4603a9fd824SRoger Pau Monné #define XENSND_OP_WRITE 3 4613a9fd824SRoger Pau Monné #define XENSND_OP_SET_VOLUME 4 4623a9fd824SRoger Pau Monné #define XENSND_OP_GET_VOLUME 5 4633a9fd824SRoger Pau Monné #define XENSND_OP_MUTE 6 4643a9fd824SRoger Pau Monné #define XENSND_OP_UNMUTE 7 4653a9fd824SRoger Pau Monné #define XENSND_OP_TRIGGER 8 4663a9fd824SRoger Pau Monné #define XENSND_OP_HW_PARAM_QUERY 9 4673a9fd824SRoger Pau Monné 4683a9fd824SRoger Pau Monné #define XENSND_OP_TRIGGER_START 0 4693a9fd824SRoger Pau Monné #define XENSND_OP_TRIGGER_PAUSE 1 4703a9fd824SRoger Pau Monné #define XENSND_OP_TRIGGER_STOP 2 4713a9fd824SRoger Pau Monné #define XENSND_OP_TRIGGER_RESUME 3 4723a9fd824SRoger Pau Monné 4733a9fd824SRoger Pau Monné /* 4743a9fd824SRoger Pau Monné ****************************************************************************** 4753a9fd824SRoger Pau Monné * EVENT CODES 4763a9fd824SRoger Pau Monné ****************************************************************************** 4773a9fd824SRoger Pau Monné */ 4783a9fd824SRoger Pau Monné #define XENSND_EVT_CUR_POS 0 4793a9fd824SRoger Pau Monné 4803a9fd824SRoger Pau Monné /* 4813a9fd824SRoger Pau Monné ****************************************************************************** 4823a9fd824SRoger Pau Monné * XENSTORE FIELD AND PATH NAME STRINGS, HELPERS 4833a9fd824SRoger Pau Monné ****************************************************************************** 4843a9fd824SRoger Pau Monné */ 4853a9fd824SRoger Pau Monné #define XENSND_DRIVER_NAME "vsnd" 4863a9fd824SRoger Pau Monné 4873a9fd824SRoger Pau Monné #define XENSND_LIST_SEPARATOR "," 4883a9fd824SRoger Pau Monné /* Field names */ 4893a9fd824SRoger Pau Monné #define XENSND_FIELD_BE_VERSIONS "versions" 4903a9fd824SRoger Pau Monné #define XENSND_FIELD_FE_VERSION "version" 4913a9fd824SRoger Pau Monné #define XENSND_FIELD_VCARD_SHORT_NAME "short-name" 4923a9fd824SRoger Pau Monné #define XENSND_FIELD_VCARD_LONG_NAME "long-name" 4933a9fd824SRoger Pau Monné #define XENSND_FIELD_RING_REF "ring-ref" 4943a9fd824SRoger Pau Monné #define XENSND_FIELD_EVT_CHNL "event-channel" 4953a9fd824SRoger Pau Monné #define XENSND_FIELD_EVT_RING_REF "evt-ring-ref" 4963a9fd824SRoger Pau Monné #define XENSND_FIELD_EVT_EVT_CHNL "evt-event-channel" 4973a9fd824SRoger Pau Monné #define XENSND_FIELD_DEVICE_NAME "name" 4983a9fd824SRoger Pau Monné #define XENSND_FIELD_TYPE "type" 4993a9fd824SRoger Pau Monné #define XENSND_FIELD_STREAM_UNIQUE_ID "unique-id" 5003a9fd824SRoger Pau Monné #define XENSND_FIELD_CHANNELS_MIN "channels-min" 5013a9fd824SRoger Pau Monné #define XENSND_FIELD_CHANNELS_MAX "channels-max" 5023a9fd824SRoger Pau Monné #define XENSND_FIELD_SAMPLE_RATES "sample-rates" 5033a9fd824SRoger Pau Monné #define XENSND_FIELD_SAMPLE_FORMATS "sample-formats" 5043a9fd824SRoger Pau Monné #define XENSND_FIELD_BUFFER_SIZE "buffer-size" 5053a9fd824SRoger Pau Monné 5063a9fd824SRoger Pau Monné /* Stream type field values. */ 5073a9fd824SRoger Pau Monné #define XENSND_STREAM_TYPE_PLAYBACK "p" 5083a9fd824SRoger Pau Monné #define XENSND_STREAM_TYPE_CAPTURE "c" 5093a9fd824SRoger Pau Monné /* Sample rate max string length */ 5103a9fd824SRoger Pau Monné #define XENSND_SAMPLE_RATE_MAX_LEN 11 5113a9fd824SRoger Pau Monné /* Sample format field values */ 5123a9fd824SRoger Pau Monné #define XENSND_SAMPLE_FORMAT_MAX_LEN 24 5133a9fd824SRoger Pau Monné 5143a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S8_STR "s8" 5153a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U8_STR "u8" 5163a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S16_LE_STR "s16_le" 5173a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S16_BE_STR "s16_be" 5183a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U16_LE_STR "u16_le" 5193a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U16_BE_STR "u16_be" 5203a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S24_LE_STR "s24_le" 5213a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S24_BE_STR "s24_be" 5223a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U24_LE_STR "u24_le" 5233a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U24_BE_STR "u24_be" 5243a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S32_LE_STR "s32_le" 5253a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_S32_BE_STR "s32_be" 5263a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U32_LE_STR "u32_le" 5273a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_U32_BE_STR "u32_be" 5283a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_F32_LE_STR "float_le" 5293a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_F32_BE_STR "float_be" 5303a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_F64_LE_STR "float64_le" 5313a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_F64_BE_STR "float64_be" 5323a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_IEC958_SUBFRAME_LE_STR "iec958_subframe_le" 5333a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_IEC958_SUBFRAME_BE_STR "iec958_subframe_be" 5343a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_MU_LAW_STR "mu_law" 5353a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_A_LAW_STR "a_law" 5363a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_IMA_ADPCM_STR "ima_adpcm" 5373a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_MPEG_STR "mpeg" 5383a9fd824SRoger Pau Monné #define XENSND_PCM_FORMAT_GSM_STR "gsm" 5393a9fd824SRoger Pau Monné 5403a9fd824SRoger Pau Monné 5413a9fd824SRoger Pau Monné /* 5423a9fd824SRoger Pau Monné ****************************************************************************** 5433a9fd824SRoger Pau Monné * STATUS RETURN CODES 5443a9fd824SRoger Pau Monné ****************************************************************************** 5453a9fd824SRoger Pau Monné * 5463a9fd824SRoger Pau Monné * Status return code is zero on success and -XEN_EXX on failure. 5473a9fd824SRoger Pau Monné * 5483a9fd824SRoger Pau Monné ****************************************************************************** 5493a9fd824SRoger Pau Monné * Assumptions 5503a9fd824SRoger Pau Monné ****************************************************************************** 5513a9fd824SRoger Pau Monné * o usage of grant reference 0 as invalid grant reference: 5523a9fd824SRoger Pau Monné * grant reference 0 is valid, but never exposed to a PV driver, 5533a9fd824SRoger Pau Monné * because of the fact it is already in use/reserved by the PV console. 5543a9fd824SRoger Pau Monné * o all references in this document to page sizes must be treated 5553a9fd824SRoger Pau Monné * as pages of size XEN_PAGE_SIZE unless otherwise noted. 5563a9fd824SRoger Pau Monné * 5573a9fd824SRoger Pau Monné ****************************************************************************** 5583a9fd824SRoger Pau Monné * Description of the protocol between frontend and backend driver 5593a9fd824SRoger Pau Monné ****************************************************************************** 5603a9fd824SRoger Pau Monné * 5613a9fd824SRoger Pau Monné * The two halves of a Para-virtual sound driver communicate with 5623a9fd824SRoger Pau Monné * each other using shared pages and event channels. 5633a9fd824SRoger Pau Monné * Shared page contains a ring with request/response packets. 5643a9fd824SRoger Pau Monné * 5653a9fd824SRoger Pau Monné * Packets, used for input/output operations, e.g. read/write, set/get volume, 5663a9fd824SRoger Pau Monné * etc., provide offset/length fields in order to allow asynchronous protocol 5673a9fd824SRoger Pau Monné * operation with buffer space sharing: part of the buffer allocated at 5683a9fd824SRoger Pau Monné * XENSND_OP_OPEN can be used for audio samples and part, for example, 5693a9fd824SRoger Pau Monné * for volume control. 5703a9fd824SRoger Pau Monné * 5713a9fd824SRoger Pau Monné * All reserved fields in the structures below must be 0. 5723a9fd824SRoger Pau Monné * 5733a9fd824SRoger Pau Monné *---------------------------------- Requests --------------------------------- 5743a9fd824SRoger Pau Monné * 5753a9fd824SRoger Pau Monné * All request packets have the same length (64 octets) 5763a9fd824SRoger Pau Monné * All request packets have common header: 5773a9fd824SRoger Pau Monné * 0 1 2 3 octet 5783a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5793a9fd824SRoger Pau Monné * | id | operation | reserved | 4 5803a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5813a9fd824SRoger Pau Monné * | reserved | 8 5823a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5833a9fd824SRoger Pau Monné * id - uint16_t, private guest value, echoed in response 5843a9fd824SRoger Pau Monné * operation - uint8_t, operation code, XENSND_OP_??? 5853a9fd824SRoger Pau Monné * 5863a9fd824SRoger Pau Monné * For all packets which use offset and length: 5873a9fd824SRoger Pau Monné * offset - uint32_t, read or write data offset within the shared buffer, 5883a9fd824SRoger Pau Monné * passed with XENSND_OP_OPEN request, octets, 5893a9fd824SRoger Pau Monné * [0; XENSND_OP_OPEN.buffer_sz - 1]. 5903a9fd824SRoger Pau Monné * length - uint32_t, read or write data length, octets 5913a9fd824SRoger Pau Monné * 5923a9fd824SRoger Pau Monné * Request open - open a PCM stream for playback or capture: 5933a9fd824SRoger Pau Monné * 5943a9fd824SRoger Pau Monné * 0 1 2 3 octet 5953a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5963a9fd824SRoger Pau Monné * | id | XENSND_OP_OPEN | reserved | 4 5973a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5983a9fd824SRoger Pau Monné * | reserved | 8 5993a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6003a9fd824SRoger Pau Monné * | pcm_rate | 12 6013a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6023a9fd824SRoger Pau Monné * | pcm_format | pcm_channels | reserved | 16 6033a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6043a9fd824SRoger Pau Monné * | buffer_sz | 20 6053a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6063a9fd824SRoger Pau Monné * | gref_directory | 24 6073a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6083a9fd824SRoger Pau Monné * | period_sz | 28 6093a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6103a9fd824SRoger Pau Monné * | reserved | 32 6113a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6123a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 6133a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6143a9fd824SRoger Pau Monné * | reserved | 64 6153a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6163a9fd824SRoger Pau Monné * 6173a9fd824SRoger Pau Monné * pcm_rate - uint32_t, stream data rate, Hz 6183a9fd824SRoger Pau Monné * pcm_format - uint8_t, XENSND_PCM_FORMAT_XXX value 6193a9fd824SRoger Pau Monné * pcm_channels - uint8_t, number of channels of this stream, 6203a9fd824SRoger Pau Monné * [channels-min; channels-max] 6213a9fd824SRoger Pau Monné * buffer_sz - uint32_t, buffer size to be allocated, octets 6223a9fd824SRoger Pau Monné * period_sz - uint32_t, event period size, octets 6233a9fd824SRoger Pau Monné * This is the requested value of the period at which frontend would 6243a9fd824SRoger Pau Monné * like to receive XENSND_EVT_CUR_POS notifications from the backend when 6253a9fd824SRoger Pau Monné * stream position advances during playback/capture. 6263a9fd824SRoger Pau Monné * It shows how many octets are expected to be played/captured before 6273a9fd824SRoger Pau Monné * sending such an event. 6283a9fd824SRoger Pau Monné * If set to 0 no XENSND_EVT_CUR_POS events are sent by the backend. 6293a9fd824SRoger Pau Monné * 6303a9fd824SRoger Pau Monné * gref_directory - grant_ref_t, a reference to the first shared page 6313a9fd824SRoger Pau Monné * describing shared buffer references. At least one page exists. If shared 6323a9fd824SRoger Pau Monné * buffer size (buffer_sz) exceeds what can be addressed by this single page, 6333a9fd824SRoger Pau Monné * then reference to the next page must be supplied (see gref_dir_next_page 6343a9fd824SRoger Pau Monné * below) 6353a9fd824SRoger Pau Monné */ 6363a9fd824SRoger Pau Monné 6373a9fd824SRoger Pau Monné struct xensnd_open_req { 6383a9fd824SRoger Pau Monné uint32_t pcm_rate; 6393a9fd824SRoger Pau Monné uint8_t pcm_format; 6403a9fd824SRoger Pau Monné uint8_t pcm_channels; 6413a9fd824SRoger Pau Monné uint16_t reserved; 6423a9fd824SRoger Pau Monné uint32_t buffer_sz; 6433a9fd824SRoger Pau Monné grant_ref_t gref_directory; 6443a9fd824SRoger Pau Monné uint32_t period_sz; 6453a9fd824SRoger Pau Monné }; 6463a9fd824SRoger Pau Monné 6473a9fd824SRoger Pau Monné /* 6483a9fd824SRoger Pau Monné * Shared page for XENSND_OP_OPEN buffer descriptor (gref_directory in the 6493a9fd824SRoger Pau Monné * request) employs a list of pages, describing all pages of the shared data 6503a9fd824SRoger Pau Monné * buffer: 6513a9fd824SRoger Pau Monné * 0 1 2 3 octet 6523a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6533a9fd824SRoger Pau Monné * | gref_dir_next_page | 4 6543a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6553a9fd824SRoger Pau Monné * | gref[0] | 8 6563a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6573a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 6583a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6593a9fd824SRoger Pau Monné * | gref[i] | i*4+8 6603a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6613a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 6623a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6633a9fd824SRoger Pau Monné * | gref[N - 1] | N*4+8 6643a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6653a9fd824SRoger Pau Monné * 6663a9fd824SRoger Pau Monné * gref_dir_next_page - grant_ref_t, reference to the next page describing 6673a9fd824SRoger Pau Monné * page directory. Must be 0 if there are no more pages in the list. 6683a9fd824SRoger Pau Monné * gref[i] - grant_ref_t, reference to a shared page of the buffer 6693a9fd824SRoger Pau Monné * allocated at XENSND_OP_OPEN 6703a9fd824SRoger Pau Monné * 6713a9fd824SRoger Pau Monné * Number of grant_ref_t entries in the whole page directory is not 6723a9fd824SRoger Pau Monné * passed, but instead can be calculated as: 6733a9fd824SRoger Pau Monné * num_grefs_total = (XENSND_OP_OPEN.buffer_sz + XEN_PAGE_SIZE - 1) / 6743a9fd824SRoger Pau Monné * XEN_PAGE_SIZE 6753a9fd824SRoger Pau Monné */ 6763a9fd824SRoger Pau Monné 6773a9fd824SRoger Pau Monné struct xensnd_page_directory { 6783a9fd824SRoger Pau Monné grant_ref_t gref_dir_next_page; 6793a9fd824SRoger Pau Monné grant_ref_t gref[1]; /* Variable length */ 6803a9fd824SRoger Pau Monné }; 6813a9fd824SRoger Pau Monné 6823a9fd824SRoger Pau Monné /* 6833a9fd824SRoger Pau Monné * Request close - close an opened pcm stream: 6843a9fd824SRoger Pau Monné * 0 1 2 3 octet 6853a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6863a9fd824SRoger Pau Monné * | id | XENSND_OP_CLOSE| reserved | 4 6873a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6883a9fd824SRoger Pau Monné * | reserved | 8 6893a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6903a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 6913a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6923a9fd824SRoger Pau Monné * | reserved | 64 6933a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6943a9fd824SRoger Pau Monné * 6953a9fd824SRoger Pau Monné * Request read/write - used for read (for capture) or write (for playback): 6963a9fd824SRoger Pau Monné * 0 1 2 3 octet 6973a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6983a9fd824SRoger Pau Monné * | id | operation | reserved | 4 6993a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7003a9fd824SRoger Pau Monné * | reserved | 8 7013a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7023a9fd824SRoger Pau Monné * | offset | 12 7033a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7043a9fd824SRoger Pau Monné * | length | 16 7053a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7063a9fd824SRoger Pau Monné * | reserved | 20 7073a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7083a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7093a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7103a9fd824SRoger Pau Monné * | reserved | 64 7113a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7123a9fd824SRoger Pau Monné * 7133a9fd824SRoger Pau Monné * operation - XENSND_OP_READ for read or XENSND_OP_WRITE for write 7143a9fd824SRoger Pau Monné */ 7153a9fd824SRoger Pau Monné 7163a9fd824SRoger Pau Monné struct xensnd_rw_req { 7173a9fd824SRoger Pau Monné uint32_t offset; 7183a9fd824SRoger Pau Monné uint32_t length; 7193a9fd824SRoger Pau Monné }; 7203a9fd824SRoger Pau Monné 7213a9fd824SRoger Pau Monné /* 7223a9fd824SRoger Pau Monné * Request set/get volume - set/get channels' volume of the stream given: 7233a9fd824SRoger Pau Monné * 0 1 2 3 octet 7243a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7253a9fd824SRoger Pau Monné * | id | operation | reserved | 4 7263a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7273a9fd824SRoger Pau Monné * | reserved | 8 7283a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7293a9fd824SRoger Pau Monné * | offset | 12 7303a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7313a9fd824SRoger Pau Monné * | length | 16 7323a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7333a9fd824SRoger Pau Monné * | reserved | 20 7343a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7353a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7363a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7373a9fd824SRoger Pau Monné * | reserved | 64 7383a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7393a9fd824SRoger Pau Monné * 7403a9fd824SRoger Pau Monné * operation - XENSND_OP_SET_VOLUME for volume set 7413a9fd824SRoger Pau Monné * or XENSND_OP_GET_VOLUME for volume get 7423a9fd824SRoger Pau Monné * Buffer passed with XENSND_OP_OPEN is used to exchange volume 7433a9fd824SRoger Pau Monné * values: 7443a9fd824SRoger Pau Monné * 7453a9fd824SRoger Pau Monné * 0 1 2 3 octet 7463a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7473a9fd824SRoger Pau Monné * | channel[0] | 4 7483a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7493a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7503a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7513a9fd824SRoger Pau Monné * | channel[i] | i*4 7523a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7533a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7543a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7553a9fd824SRoger Pau Monné * | channel[N - 1] | (N-1)*4 7563a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7573a9fd824SRoger Pau Monné * 7583a9fd824SRoger Pau Monné * N = XENSND_OP_OPEN.pcm_channels 7593a9fd824SRoger Pau Monné * i - uint8_t, index of a channel 7603a9fd824SRoger Pau Monné * channel[i] - sint32_t, volume of i-th channel 7613a9fd824SRoger Pau Monné * Volume is expressed as a signed value in steps of 0.001 dB, 7623a9fd824SRoger Pau Monné * while 0 being 0 dB. 7633a9fd824SRoger Pau Monné * 7643a9fd824SRoger Pau Monné * Request mute/unmute - mute/unmute stream: 7653a9fd824SRoger Pau Monné * 0 1 2 3 octet 7663a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7673a9fd824SRoger Pau Monné * | id | operation | reserved | 4 7683a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7693a9fd824SRoger Pau Monné * | reserved | 8 7703a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7713a9fd824SRoger Pau Monné * | offset | 12 7723a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7733a9fd824SRoger Pau Monné * | length | 16 7743a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7753a9fd824SRoger Pau Monné * | reserved | 20 7763a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7773a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7783a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7793a9fd824SRoger Pau Monné * | reserved | 64 7803a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7813a9fd824SRoger Pau Monné * 7823a9fd824SRoger Pau Monné * operation - XENSND_OP_MUTE for mute or XENSND_OP_UNMUTE for unmute 7833a9fd824SRoger Pau Monné * Buffer passed with XENSND_OP_OPEN is used to exchange mute/unmute 7843a9fd824SRoger Pau Monné * values: 7853a9fd824SRoger Pau Monné * 7863a9fd824SRoger Pau Monné * 0 octet 7873a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7883a9fd824SRoger Pau Monné * | channel[0] | 4 7893a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7903a9fd824SRoger Pau Monné * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7913a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7923a9fd824SRoger Pau Monné * | channel[i] | i*4 7933a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7943a9fd824SRoger Pau Monné * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7953a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7963a9fd824SRoger Pau Monné * | channel[N - 1] | (N-1)*4 7973a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7983a9fd824SRoger Pau Monné * 7993a9fd824SRoger Pau Monné * N = XENSND_OP_OPEN.pcm_channels 8003a9fd824SRoger Pau Monné * i - uint8_t, index of a channel 8013a9fd824SRoger Pau Monné * channel[i] - uint8_t, non-zero if i-th channel needs to be muted/unmuted 8023a9fd824SRoger Pau Monné * 8033a9fd824SRoger Pau Monné *------------------------------------ N.B. ----------------------------------- 8043a9fd824SRoger Pau Monné * 8053a9fd824SRoger Pau Monné * The 'struct xensnd_rw_req' is also used for XENSND_OP_SET_VOLUME, 8063a9fd824SRoger Pau Monné * XENSND_OP_GET_VOLUME, XENSND_OP_MUTE, XENSND_OP_UNMUTE. 8073a9fd824SRoger Pau Monné * 8083a9fd824SRoger Pau Monné * Request stream running state change - trigger PCM stream running state 8093a9fd824SRoger Pau Monné * to start, stop, pause or resume: 8103a9fd824SRoger Pau Monné * 8113a9fd824SRoger Pau Monné * 0 1 2 3 octet 8123a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8133a9fd824SRoger Pau Monné * | id | _OP_TRIGGER | reserved | 4 8143a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8153a9fd824SRoger Pau Monné * | reserved | 8 8163a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8173a9fd824SRoger Pau Monné * | type | reserved | 12 8183a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8193a9fd824SRoger Pau Monné * | reserved | 16 8203a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8213a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 8223a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8233a9fd824SRoger Pau Monné * | reserved | 64 8243a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8253a9fd824SRoger Pau Monné * 8263a9fd824SRoger Pau Monné * type - uint8_t, XENSND_OP_TRIGGER_XXX value 8273a9fd824SRoger Pau Monné */ 8283a9fd824SRoger Pau Monné 8293a9fd824SRoger Pau Monné struct xensnd_trigger_req { 8303a9fd824SRoger Pau Monné uint8_t type; 8313a9fd824SRoger Pau Monné }; 8323a9fd824SRoger Pau Monné 8333a9fd824SRoger Pau Monné /* 8343a9fd824SRoger Pau Monné * Request stream parameter ranges: request intervals and 8353a9fd824SRoger Pau Monné * masks of supported ranges for stream configuration values. 8363a9fd824SRoger Pau Monné * 8373a9fd824SRoger Pau Monné * Sound device configuration for a particular stream is a limited subset 8383a9fd824SRoger Pau Monné * of the multidimensional configuration available on XenStore, e.g. 8393a9fd824SRoger Pau Monné * once the frame rate has been selected there is a limited supported range 8403a9fd824SRoger Pau Monné * for sample rates becomes available (which might be the same set configured 8413a9fd824SRoger Pau Monné * on XenStore or less). For example, selecting 96kHz sample rate may limit 8423a9fd824SRoger Pau Monné * number of channels available for such configuration from 4 to 2, etc. 8433a9fd824SRoger Pau Monné * Thus, each call to XENSND_OP_HW_PARAM_QUERY may reduce configuration 8443a9fd824SRoger Pau Monné * space making it possible to iteratively get the final stream configuration, 8453a9fd824SRoger Pau Monné * used in XENSND_OP_OPEN request. 8463a9fd824SRoger Pau Monné * 8473a9fd824SRoger Pau Monné * See response format for this request. 8483a9fd824SRoger Pau Monné * 8493a9fd824SRoger Pau Monné * 0 1 2 3 octet 8503a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8513a9fd824SRoger Pau Monné * | id | _HW_PARAM_QUERY| reserved | 4 8523a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8533a9fd824SRoger Pau Monné * | reserved | 8 8543a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8553a9fd824SRoger Pau Monné * | formats mask low 32-bit | 12 8563a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8573a9fd824SRoger Pau Monné * | formats mask high 32-bit | 16 8583a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8593a9fd824SRoger Pau Monné * | min rate | 20 8603a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8613a9fd824SRoger Pau Monné * | max rate | 24 8623a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8633a9fd824SRoger Pau Monné * | min channels | 28 8643a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8653a9fd824SRoger Pau Monné * | max channels | 32 8663a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8673a9fd824SRoger Pau Monné * | min buffer frames | 36 8683a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8693a9fd824SRoger Pau Monné * | max buffer frames | 40 8703a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8713a9fd824SRoger Pau Monné * | min period frames | 44 8723a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8733a9fd824SRoger Pau Monné * | max period frames | 48 8743a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8753a9fd824SRoger Pau Monné * | reserved | 52 8763a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8773a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 8783a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8793a9fd824SRoger Pau Monné * | reserved | 64 8803a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8813a9fd824SRoger Pau Monné * 8823a9fd824SRoger Pau Monné * formats - uint64_t, bit mask representing values of the parameter 8833a9fd824SRoger Pau Monné * made as bitwise OR of (1 << XENSND_PCM_FORMAT_XXX) values 8843a9fd824SRoger Pau Monné * 8853a9fd824SRoger Pau Monné * For interval parameters: 8863a9fd824SRoger Pau Monné * min - uint32_t, minimum value of the parameter 8873a9fd824SRoger Pau Monné * max - uint32_t, maximum value of the parameter 8883a9fd824SRoger Pau Monné * 8893a9fd824SRoger Pau Monné * Frame is defined as a product of the number of channels by the 8903a9fd824SRoger Pau Monné * number of octets per one sample. 8913a9fd824SRoger Pau Monné */ 8923a9fd824SRoger Pau Monné 8933a9fd824SRoger Pau Monné struct xensnd_query_hw_param { 8943a9fd824SRoger Pau Monné uint64_t formats; 8953a9fd824SRoger Pau Monné struct { 8963a9fd824SRoger Pau Monné uint32_t min; 8973a9fd824SRoger Pau Monné uint32_t max; 8983a9fd824SRoger Pau Monné } rates; 8993a9fd824SRoger Pau Monné struct { 9003a9fd824SRoger Pau Monné uint32_t min; 9013a9fd824SRoger Pau Monné uint32_t max; 9023a9fd824SRoger Pau Monné } channels; 9033a9fd824SRoger Pau Monné struct { 9043a9fd824SRoger Pau Monné uint32_t min; 9053a9fd824SRoger Pau Monné uint32_t max; 9063a9fd824SRoger Pau Monné } buffer; 9073a9fd824SRoger Pau Monné struct { 9083a9fd824SRoger Pau Monné uint32_t min; 9093a9fd824SRoger Pau Monné uint32_t max; 9103a9fd824SRoger Pau Monné } period; 9113a9fd824SRoger Pau Monné }; 9123a9fd824SRoger Pau Monné 9133a9fd824SRoger Pau Monné /* 9143a9fd824SRoger Pau Monné *---------------------------------- Responses -------------------------------- 9153a9fd824SRoger Pau Monné * 9163a9fd824SRoger Pau Monné * All response packets have the same length (64 octets) 9173a9fd824SRoger Pau Monné * 9183a9fd824SRoger Pau Monné * All response packets have common header: 9193a9fd824SRoger Pau Monné * 0 1 2 3 octet 9203a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9213a9fd824SRoger Pau Monné * | id | operation | reserved | 4 9223a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9233a9fd824SRoger Pau Monné * | status | 8 9243a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9253a9fd824SRoger Pau Monné * 9263a9fd824SRoger Pau Monné * id - uint16_t, copied from the request 9273a9fd824SRoger Pau Monné * operation - uint8_t, XENSND_OP_* - copied from request 9283a9fd824SRoger Pau Monné * status - int32_t, response status, zero on success and -XEN_EXX on failure 9293a9fd824SRoger Pau Monné * 9303a9fd824SRoger Pau Monné * 9313a9fd824SRoger Pau Monné * HW parameter query response - response for XENSND_OP_HW_PARAM_QUERY: 9323a9fd824SRoger Pau Monné * 0 1 2 3 octet 9333a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9343a9fd824SRoger Pau Monné * | id | operation | reserved | 4 9353a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9363a9fd824SRoger Pau Monné * | status | 8 9373a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9383a9fd824SRoger Pau Monné * | formats mask low 32-bit | 12 9393a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9403a9fd824SRoger Pau Monné * | formats mask high 32-bit | 16 9413a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9423a9fd824SRoger Pau Monné * | min rate | 20 9433a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9443a9fd824SRoger Pau Monné * | max rate | 24 9453a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9463a9fd824SRoger Pau Monné * | min channels | 28 9473a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9483a9fd824SRoger Pau Monné * | max channels | 32 9493a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9503a9fd824SRoger Pau Monné * | min buffer frames | 36 9513a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9523a9fd824SRoger Pau Monné * | max buffer frames | 40 9533a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9543a9fd824SRoger Pau Monné * | min period frames | 44 9553a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9563a9fd824SRoger Pau Monné * | max period frames | 48 9573a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9583a9fd824SRoger Pau Monné * | reserved | 52 9593a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9603a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 9613a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9623a9fd824SRoger Pau Monné * | reserved | 64 9633a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9643a9fd824SRoger Pau Monné * 9653a9fd824SRoger Pau Monné * Meaning of the values in this response is the same as for 9663a9fd824SRoger Pau Monné * XENSND_OP_HW_PARAM_QUERY request. 9673a9fd824SRoger Pau Monné */ 9683a9fd824SRoger Pau Monné 9693a9fd824SRoger Pau Monné /* 9703a9fd824SRoger Pau Monné *----------------------------------- Events ---------------------------------- 9713a9fd824SRoger Pau Monné * 9723a9fd824SRoger Pau Monné * Events are sent via shared page allocated by the front and propagated by 9733a9fd824SRoger Pau Monné * evt-event-channel/evt-ring-ref XenStore entries 9743a9fd824SRoger Pau Monné * All event packets have the same length (64 octets) 9753a9fd824SRoger Pau Monné * All event packets have common header: 9763a9fd824SRoger Pau Monné * 0 1 2 3 octet 9773a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9783a9fd824SRoger Pau Monné * | id | type | reserved | 4 9793a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9803a9fd824SRoger Pau Monné * | reserved | 8 9813a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9823a9fd824SRoger Pau Monné * 9833a9fd824SRoger Pau Monné * id - uint16_t, event id, may be used by front 9843a9fd824SRoger Pau Monné * type - uint8_t, type of the event 9853a9fd824SRoger Pau Monné * 9863a9fd824SRoger Pau Monné * 9873a9fd824SRoger Pau Monné * Current stream position - event from back to front when stream's 9883a9fd824SRoger Pau Monné * playback/capture position has advanced: 9893a9fd824SRoger Pau Monné * 0 1 2 3 octet 9903a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9913a9fd824SRoger Pau Monné * | id | _EVT_CUR_POS | reserved | 4 9923a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9933a9fd824SRoger Pau Monné * | reserved | 8 9943a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9953a9fd824SRoger Pau Monné * | position low 32-bit | 12 9963a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9973a9fd824SRoger Pau Monné * | position high 32-bit | 16 9983a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 9993a9fd824SRoger Pau Monné * | reserved | 20 10003a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 10013a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 10023a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 10033a9fd824SRoger Pau Monné * | reserved | 64 10043a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 10053a9fd824SRoger Pau Monné * 10063a9fd824SRoger Pau Monné * position - current value of stream's playback/capture position, octets 10073a9fd824SRoger Pau Monné * 10083a9fd824SRoger Pau Monné */ 10093a9fd824SRoger Pau Monné 10103a9fd824SRoger Pau Monné struct xensnd_cur_pos_evt { 10113a9fd824SRoger Pau Monné uint64_t position; 10123a9fd824SRoger Pau Monné }; 10133a9fd824SRoger Pau Monné 10143a9fd824SRoger Pau Monné struct xensnd_req { 10153a9fd824SRoger Pau Monné uint16_t id; 10163a9fd824SRoger Pau Monné uint8_t operation; 10173a9fd824SRoger Pau Monné uint8_t reserved[5]; 10183a9fd824SRoger Pau Monné union { 10193a9fd824SRoger Pau Monné struct xensnd_open_req open; 10203a9fd824SRoger Pau Monné struct xensnd_rw_req rw; 10213a9fd824SRoger Pau Monné struct xensnd_trigger_req trigger; 10223a9fd824SRoger Pau Monné struct xensnd_query_hw_param hw_param; 10233a9fd824SRoger Pau Monné uint8_t reserved[56]; 10243a9fd824SRoger Pau Monné } op; 10253a9fd824SRoger Pau Monné }; 10263a9fd824SRoger Pau Monné 10273a9fd824SRoger Pau Monné struct xensnd_resp { 10283a9fd824SRoger Pau Monné uint16_t id; 10293a9fd824SRoger Pau Monné uint8_t operation; 10303a9fd824SRoger Pau Monné uint8_t reserved; 10313a9fd824SRoger Pau Monné int32_t status; 10323a9fd824SRoger Pau Monné union { 10333a9fd824SRoger Pau Monné struct xensnd_query_hw_param hw_param; 10343a9fd824SRoger Pau Monné uint8_t reserved1[56]; 10353a9fd824SRoger Pau Monné } resp; 10363a9fd824SRoger Pau Monné }; 10373a9fd824SRoger Pau Monné 10383a9fd824SRoger Pau Monné struct xensnd_evt { 10393a9fd824SRoger Pau Monné uint16_t id; 10403a9fd824SRoger Pau Monné uint8_t type; 10413a9fd824SRoger Pau Monné uint8_t reserved[5]; 10423a9fd824SRoger Pau Monné union { 10433a9fd824SRoger Pau Monné struct xensnd_cur_pos_evt cur_pos; 10443a9fd824SRoger Pau Monné uint8_t reserved[56]; 10453a9fd824SRoger Pau Monné } op; 10463a9fd824SRoger Pau Monné }; 10473a9fd824SRoger Pau Monné 10483a9fd824SRoger Pau Monné DEFINE_RING_TYPES(xen_sndif, struct xensnd_req, struct xensnd_resp); 10493a9fd824SRoger Pau Monné 10503a9fd824SRoger Pau Monné /* 10513a9fd824SRoger Pau Monné ****************************************************************************** 10523a9fd824SRoger Pau Monné * Back to front events delivery 10533a9fd824SRoger Pau Monné ****************************************************************************** 10543a9fd824SRoger Pau Monné * In order to deliver asynchronous events from back to front a shared page is 10553a9fd824SRoger Pau Monné * allocated by front and its granted reference propagated to back via 10563a9fd824SRoger Pau Monné * XenStore entries (evt-ring-ref/evt-event-channel). 10573a9fd824SRoger Pau Monné * This page has a common header used by both front and back to synchronize 10583a9fd824SRoger Pau Monné * access and control event's ring buffer, while back being a producer of the 10593a9fd824SRoger Pau Monné * events and front being a consumer. The rest of the page after the header 10603a9fd824SRoger Pau Monné * is used for event packets. 10613a9fd824SRoger Pau Monné * 10623a9fd824SRoger Pau Monné * Upon reception of an event(s) front may confirm its reception 10633a9fd824SRoger Pau Monné * for either each event, group of events or none. 10643a9fd824SRoger Pau Monné */ 10653a9fd824SRoger Pau Monné 10663a9fd824SRoger Pau Monné struct xensnd_event_page { 10673a9fd824SRoger Pau Monné uint32_t in_cons; 10683a9fd824SRoger Pau Monné uint32_t in_prod; 10693a9fd824SRoger Pau Monné uint8_t reserved[56]; 10703a9fd824SRoger Pau Monné }; 10713a9fd824SRoger Pau Monné 10723a9fd824SRoger Pau Monné #define XENSND_EVENT_PAGE_SIZE 4096 10733a9fd824SRoger Pau Monné #define XENSND_IN_RING_OFFS (sizeof(struct xensnd_event_page)) 10743a9fd824SRoger Pau Monné #define XENSND_IN_RING_SIZE (XENSND_EVENT_PAGE_SIZE - XENSND_IN_RING_OFFS) 10753a9fd824SRoger Pau Monné #define XENSND_IN_RING_LEN (XENSND_IN_RING_SIZE / sizeof(struct xensnd_evt)) 10763a9fd824SRoger Pau Monné #define XENSND_IN_RING(page) \ 10773a9fd824SRoger Pau Monné ((struct xensnd_evt *)((char *)(page) + XENSND_IN_RING_OFFS)) 10783a9fd824SRoger Pau Monné #define XENSND_IN_RING_REF(page, idx) \ 10793a9fd824SRoger Pau Monné (XENSND_IN_RING((page))[(idx) % XENSND_IN_RING_LEN]) 10803a9fd824SRoger Pau Monné 10813a9fd824SRoger Pau Monné #endif /* __XEN_PUBLIC_IO_SNDIF_H__ */ 10823a9fd824SRoger Pau Monné 10833a9fd824SRoger Pau Monné /* 10843a9fd824SRoger Pau Monné * Local variables: 10853a9fd824SRoger Pau Monné * mode: C 10863a9fd824SRoger Pau Monné * c-file-style: "BSD" 10873a9fd824SRoger Pau Monné * c-basic-offset: 4 10883a9fd824SRoger Pau Monné * tab-width: 4 10893a9fd824SRoger Pau Monné * indent-tabs-mode: nil 10903a9fd824SRoger Pau Monné * End: 10913a9fd824SRoger Pau Monné */ 1092