|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [PATCH v5] sndif: add ABI for Para-virtual sound
This is ABI for the two halves of a Para-virtual
sound driver to communicate with each to other.
Signed-off-by: Oleksandr Dmytryshyn <oleksandr.dmytryshyn@xxxxxxxxxxxxxxx>
Signed-off-by: Iurii Konovalenko <iurii.konovalenko@xxxxxxxxxxxxxxx>
---
Changes since v1:
* removed __attribute__((__packed__)) from all structures definitions
Changes since v2:
* removed all C structures
* added protocol description between frontend and backend drivers
Changes since v3:
* fixed some typos
* renamed XENSND_PCM_FORMAT_FLOAT_** to XENSND_PCM_FORMAT_F32_**
* renamed XENSND_PCM_FORMAT_FLOAT64_** to XENSND_PCM_FORMAT_F64_**
* added 'id' field to the request and response packets
* renamed 'stream_id' to 'stream' in the packets description
* renamed 'pcm_data_rate' to 'pcm_rate' in the packets description
* renamed 'pcm_stream_type' to 'pcm_type' in the packets description
* removed 'stream_id' field from the response packets
Changes since v4:
* renamed 'stream_id' back to the to 'stream' in the packets description
* moved 'id' field to the upper position in the response packets
xen/include/public/io/sndif.h | 338 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 338 insertions(+)
create mode 100644 xen/include/public/io/sndif.h
diff --git a/xen/include/public/io/sndif.h b/xen/include/public/io/sndif.h
new file mode 100644
index 0000000..64adef0
--- /dev/null
+++ b/xen/include/public/io/sndif.h
@@ -0,0 +1,338 @@
+/******************************************************************************
+ * sndif.h
+ *
+ * Unified sound-device I/O interface for Xen guest OSes.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ *
+ * Copyright (C) 2013-2015 GlobalLogic Inc.
+ */
+
+#ifndef __XEN_PUBLIC_IO_XENSND_H__
+#define __XEN_PUBLIC_IO_XENSND_H__
+
+/*
+ * Feature and Parameter Negotiation
+ * =================================
+ * The two halves of a Para-virtual sound driver utilize nodes within the
+ * XenStore to communicate capabilities and to negotiate operating parameters.
+ * This section enumerates these nodes which reside in the respective front and
+ * backend portions of the XenStore, following the XenBus convention.
+ *
+ * All data in the XenStore is stored as strings. Nodes specifying numeric
+ * values are encoded in decimal. Integer value ranges listed below are
+ * expressed as fixed sized integer types capable of storing the conversion
+ * of a properly formated node string, without loss of information.
+ *
+ * XenStore nodes in sections marked "PRIVATE" are solely for use by the
+ * driver side whose XenBus tree contains them.
+ *
+ *****************************************************************************
+ * Backend XenBus Nodes
+ *****************************************************************************
+ *
+ *------------------ Backend Device Identification (PRIVATE) ------------------
+ *
+ * stream_id
+ * Values: <uint32_t>
+ *
+ * Each virtualized stream has own id starting from 0.
+ * Within each frontend these ids must be unique.
+ * Each stream can be opened only for playback or capture
+ * at the same time.
+ *
+ * channels_cnt
+ * Values: <uint32_t>
+ *
+ * The maximum amount of channels that can be supported by this stream.
+ *
+ *****************************************************************************
+ * Frontend XenBus Nodes
+ *****************************************************************************
+ *
+ *----------------------- Request Transport Parameters -----------------------
+ *
+ * event-channel
+ * Values: <uint32_t>
+ *
+ * The identifier of the Xen event channel used to signal activity
+ * in the ring buffer.
+ *
+ * ring-ref
+ * Values: <uint32_t>
+ *
+ * The Xen grant reference granting permission for the backend to map
+ * the sole page in a single page sized ring buffer.
+ */
+
+/*
+ * PCM FORMATS
+ *
+ * XENSND_PCM_FORMAT_<format>[_<endian>]
+ *
+ * format: <S/U/F><bits> or <name>
+ * S - signed, U - unsigned, F - float
+ * bits - 8, 16, 24, 32
+ * name - MU_LAW, GSM, etc.
+ *
+ * endian: <LE/BE>, may be absent
+ * LE - Little endian, BE - Big endian
+ */
+#define XENSND_PCM_FORMAT_S8 0
+#define XENSND_PCM_FORMAT_U8 1
+#define XENSND_PCM_FORMAT_S16_LE 2
+#define XENSND_PCM_FORMAT_S16_BE 3
+#define XENSND_PCM_FORMAT_U16_LE 4
+#define XENSND_PCM_FORMAT_U16_BE 5
+#define XENSND_PCM_FORMAT_S24_LE 6
+#define XENSND_PCM_FORMAT_S24_BE 7
+#define XENSND_PCM_FORMAT_U24_LE 8
+#define XENSND_PCM_FORMAT_U24_BE 9
+#define XENSND_PCM_FORMAT_S32_LE 10
+#define XENSND_PCM_FORMAT_S32_BE 11
+#define XENSND_PCM_FORMAT_U32_LE 12
+#define XENSND_PCM_FORMAT_U32_BE 13
+#define XENSND_PCM_FORMAT_F32_LE 14 /* 4-byte float, IEEE-754 32-bit, */
+#define XENSND_PCM_FORMAT_F32_BE 15 /* range -1.0 to 1.0 */
+#define XENSND_PCM_FORMAT_F64_LE 16 /* 8-byte float, IEEE-754 64-bit, */
+#define XENSND_PCM_FORMAT_F64_BE 17 /* range -1.0 to 1.0 */
+#define XENSND_PCM_FORMAT_IEC958_SUBFRAME_LE 18
+#define XENSND_PCM_FORMAT_IEC958_SUBFRAME_BE 19
+#define XENSND_PCM_FORMAT_MU_LAW 20
+#define XENSND_PCM_FORMAT_A_LAW 21
+#define XENSND_PCM_FORMAT_IMA_ADPCM 22
+#define XENSND_PCM_FORMAT_MPEG 23
+#define XENSND_PCM_FORMAT_GSM 24
+#define XENSND_PCM_FORMAT_SPECIAL 31 /* Any other unspecified format */
+
+/*
+ * REQUEST CODES.
+ */
+#define XENSND_OP_OPEN 0
+#define XENSND_OP_CLOSE 1
+#define XENSND_OP_READ 2
+#define XENSND_OP_WRITE 3
+#define XENSND_OP_SET_VOLUME 4
+#define XENSND_OP_GET_VOLUME 5
+
+/*
+ * The maximum amount of shared pages which can be used in any request
+ * from the frontend driver to the backend driver
+ */
+#define XENSND_MAX_PAGES_PER_REQUEST 12
+
+/* The maximum amount of channels per virtualized stream */
+#define XENSND_MAX_CHANNELS_PER_STREAM 16
+
+/*
+ * STATUS RETURN CODES.
+ */
+ /* Operation failed for some unspecified reason (e. g. -EIO). */
+#define XENSND_RSP_ERROR (-1)
+ /* Operation completed successfully. */
+#define XENSND_RSP_OKAY 0
+
+/*
+ * Description of the protocol between the frontend and the backend driver.
+ *
+ * The two halves of a Para-virtual sound driver communicates with
+ * each to other using an shared page and event channel.
+ * Shared page contains a ring with request/response packets.
+ * All fields within the packet are always in little-endian byte order.
+ * Almost all fields within the packet are unsigned except
+ * the field 'status' in the responses packets, which is signed.
+ *
+ *
+ * All request packets have the same length (80 bytes)
+ *
+ * Request open - open an pcm stream for playback or capture:
+ * 0 1 2 3 4 5 6 7 octet
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | operation | stream_id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | pcm_format | pcm_channels |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | pcm_rate | pcm_type |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/+
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ *
+ * id - private guest value, echoed in resp
+ * operation - XENSND_OP_OPEN
+ * stream_id - stream id, readed from the 'stream_id' XenBus node
+ * pcm_format - XENSND_PCM_FORMAT_???
+ * pcm_channels - channels count in stream
+ * pcm_rate - stream data rate
+ * pcm_type - 0: playback, 1: capture
+ *
+ *
+ * Request close - close an opened pcm stream:
+ * 0 1 2 3 4 5 6 7 octet
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | operation | stream_id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/+
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ *
+ * id - private guest value, echoed in resp
+ * operation - XENSND_OP_CLOSE
+ * stream_id - stream id, readed from the 'stream_id' XenBus node
+ *
+ *
+ * Request read/write - used for read (for capture) or write (for playback):
+ * 0 1 2 3 4 5 6 7 octet
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | operation | stream_id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | length | gref0 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | gref1 | gref2 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/+
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | gref11 | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ *
+ * id - private guest value, echoed in resp
+ * operation - XENSND_OP_READ or XENSND_OP_WRITE
+ * stream_id - stream id, readed from the 'stream_id' XenBus node
+ * length - read or write data length
+ * gref0 - gref11 - references to a grant entries for used pages in read/write
+ * request.
+ *
+ *
+ * Request set volume - set channels volume in stream:
+ * 0 1 2 3 4 5 6 7 octet
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | operation | stream_id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | vol_ch0 | vol_ch1 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | vol_ch2 | vol_ch3 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | vol_ch4 | vol_ch5 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/+
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | vol_ch14 | vol_ch15 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ *
+ * id - private guest value, echoed in resp
+ * operation - XENSND_OP_SET_VOLUME
+ * stream_id - stream id, readed from the 'stream_id' XenBus node
+ * vol_ch0 - vol_ch15 - volume level for channel0 - channel15
+ *
+ *
+ * Request get volume - get channels volume in stream:
+ * 0 1 2 3 4 5 6 7 octet
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | operation | stream_id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/+
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ *
+ * id - private guest value, echoed in resp
+ * operation - XENSND_OP_GET_VOLUME
+ * stream_id - stream id, readed from the 'stream_id' XenBus node
+ *
+ *
+ * All response packets have the same length (80 bytes)
+ *
+ * Response for all requests exept the XENSND_OP_GET_VOLUME:
+ * 0 1 2 3 4 5 6 7 octet
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | operation | status |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/+
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | reserved | reserved |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ *
+ * id - copied from request
+ * operation - XENSND_OP_??? - copied from request
+ * status - XENSND_RSP_???
+ *
+ *
+ * Response for XENSND_OP_GET_VOLUME request:
+ * 0 1 2 3 4 5 6 7 octet
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | id |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | operation | status |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | vol_ch0 | vol_ch1 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | vol_ch2 | vol_ch3 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * +/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/+
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ * | vol_ch14 | vol_ch15 |
+ * +-----+-----+-----+-----+-----+-----+-----+-----+
+ *
+ * id - copied from request
+ * operation - XENSND_OP_GET_VOLUME -copied from request
+ * status - XENSND_RSP_???
+ * vol_ch0 - vol_ch15 - volume level for channel0 - channel15
+ */
+
+struct xensnd_request {
+ uint8_t raw[80];
+};
+
+struct xensnd_response {
+ uint8_t raw[80];
+};
+
+DEFINE_RING_TYPES(xensnd, struct xensnd_request, struct xensnd_response);
+
+#endif /* __XEN_PUBLIC_IO_XENSND_H__ */
--
1.9.1
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |