interface/io/sndif.h

1 /* SPDX-License-Identifier: MIT */
5  * Unified sound-device I/O interface for Xen guest OSes.
7  * Copyright (C) 2013-2015 GlobalLogic Inc.
8  * Copyright (C) 2016-2017 EPAM Systems Inc.
34  * Front->back notifications: when enqueuing a new request, sending a
36  * hold-off mechanism provided by the ring macros). Backends must set
39  * Back->front notifications: when enqueuing a new response, sending a
41  * hold-off mechanism provided by the ring macros). Frontends must set
44  * The two halves of a para-virtual sound card driver utilize nodes within
58  * Note: depending on the use-case backend can expose more sound cards and
64  *--------------------------------- Backend -----------------------------------
66  * /local/domain/0/backend/vsnd/1/0/frontend-id = "1"
71  *--------------------------------- Frontend ----------------------------------
73  * /local/domain/1/device/vsnd/0/backend-id = "0"
78  *----------------------------- Card configuration ----------------------------
80  * /local/domain/1/device/vsnd/0/short-name = "Card short name"
81  * /local/domain/1/device/vsnd/0/long-name = "Card long name"
82  * /local/domain/1/device/vsnd/0/sample-rates = "8000,32000,44100,48000,96000"
83  * /local/domain/1/device/vsnd/0/sample-formats = "s8,u8,s16_le,s16_be"
84  * /local/domain/1/device/vsnd/0/buffer-size = "262144"
86  *------------------------------- PCM device 0 --------------------------------
89  * /local/domain/1/device/vsnd/0/0/channels-max = "5"
91  *----------------------------- Stream 0, playback ----------------------------
94  * /local/domain/1/device/vsnd/0/0/0/sample-formats = "s8,u8"
95  * /local/domain/1/device/vsnd/0/0/0/unique-id = "0"
97  * /local/domain/1/device/vsnd/0/0/0/ring-ref = "386"
98  * /local/domain/1/device/vsnd/0/0/0/event-channel = "15"
99  * /local/domain/1/device/vsnd/0/0/0/evt-ring-ref = "1386"
100  * /local/domain/1/device/vsnd/0/0/0/evt-event-channel = "215"
102  *------------------------------ Stream 1, capture ----------------------------
105  * /local/domain/1/device/vsnd/0/0/1/channels-max = "2"
106  * /local/domain/1/device/vsnd/0/0/1/unique-id = "1"
108  * /local/domain/1/device/vsnd/0/0/1/ring-ref = "384"
109  * /local/domain/1/device/vsnd/0/0/1/event-channel = "13"
110  * /local/domain/1/device/vsnd/0/0/1/evt-ring-ref = "1384"
111  * /local/domain/1/device/vsnd/0/0/1/evt-event-channel = "213"
113  *------------------------------- PCM device 1 --------------------------------
115  * /local/domain/1/device/vsnd/0/1/name = "HDMI-0"
116  * /local/domain/1/device/vsnd/0/1/sample-rates = "8000,32000,44100"
118  *------------------------------ Stream 0, capture ----------------------------
121  * /local/domain/1/device/vsnd/0/1/0/unique-id = "2"
123  * /local/domain/1/device/vsnd/0/1/0/ring-ref = "387"
124  * /local/domain/1/device/vsnd/0/1/0/event-channel = "151"
125  * /local/domain/1/device/vsnd/0/1/0/evt-ring-ref = "1387"
126  * /local/domain/1/device/vsnd/0/1/0/evt-event-channel = "351"
128  *------------------------------- PCM device 2 --------------------------------
132  *----------------------------- Stream 0, playback ----------------------------
135  * /local/domain/1/device/vsnd/0/2/0/unique-id = "3"
137  * /local/domain/1/device/vsnd/0/2/0/ring-ref = "389"
138  * /local/domain/1/device/vsnd/0/2/0/event-channel = "152"
139  * /local/domain/1/device/vsnd/0/2/0/evt-ring-ref = "1389"
140  * /local/domain/1/device/vsnd/0/2/0/evt-event-channel = "452"
146  *----------------------------- Protocol version ------------------------------
158  *-------------------------------- Addressing ---------------------------------
160  * dom-id
165  * dev-id
170  * pcm-dev-idx
175  * stream-idx
181  *   /local/domain/<dom-id>/device/vsnd/<dev-id>/<pcm-dev-idx>/<stream-idx>/...
183  *----------------------------- Protocol version ------------------------------
190  *------------------------------- PCM settings --------------------------------
194  * defined at higher level of the hierarchy and be fully or partially re-used
200  * Every underlying layer in turn can re-define some or all of them to better
206  * channels-min
209  *      The minimum amount of channels that is supported, [1; channels-max].
212  * channels-max
216  *      Must be at least <channels-min>.
218  * sample-rates
225  * sample-formats
231  * buffer-size
236  *----------------------- Virtual sound card settings -------------------------
237  * short-name
242  * long-name
247  *----------------------------- Device settings -------------------------------
253  *----------------------------- Stream settings -------------------------------
258  *      Stream type: "p" - playback stream, "c" - capture stream
263  * unique-id
270  *-------------------- Stream Request Transport Parameters --------------------
272  * event-channel
278  * ring-ref
284  *--------------------- Stream Event Transport Parameters ---------------------
289  * evt-event-channel
295  * evt-ring-ref
357  *------------------------------- Recovery flow -------------------------------
391  *    to periodically check if this is the right time to re-try removal of
402  *     S - signed, U - unsigned, F - float
403  *     bits - 8, 16, 24, 32
404  *     name - MU_LAW, GSM, etc.
407  *     LE - Little endian, BE - Big endian
423 #define XENSND_PCM_FORMAT_F32_LE	14 /* 4-byte float, IEEE-754 32-bit, */
424 #define XENSND_PCM_FORMAT_F32_BE	15 /* range -1.0 to 1.0              */
425 #define XENSND_PCM_FORMAT_F64_LE	16 /* 8-byte float, IEEE-754 64-bit, */
426 #define XENSND_PCM_FORMAT_F64_BE	17 /* range -1.0 to 1.0              */
474 #define XENSND_FIELD_VCARD_SHORT_NAME	"short-name"
475 #define XENSND_FIELD_VCARD_LONG_NAME	"long-name"
476 #define XENSND_FIELD_RING_REF		"ring-ref"
477 #define XENSND_FIELD_EVT_CHNL		"event-channel"
478 #define XENSND_FIELD_EVT_RING_REF	"evt-ring-ref"
479 #define XENSND_FIELD_EVT_EVT_CHNL	"evt-event-channel"
482 #define XENSND_FIELD_STREAM_UNIQUE_ID	"unique-id"
483 #define XENSND_FIELD_CHANNELS_MIN	"channels-min"
484 #define XENSND_FIELD_CHANNELS_MAX	"channels-max"
485 #define XENSND_FIELD_SAMPLE_RATES	"sample-rates"
486 #define XENSND_FIELD_SAMPLE_FORMATS	"sample-formats"
487 #define XENSND_FIELD_BUFFER_SIZE	"buffer-size"
529  * Status return code is zero on success and -XEN_EXX on failure.
544  * The two halves of a Para-virtual sound driver communicate with
556  *---------------------------------- Requests ---------------------------------
561  * +----------------+----------------+----------------+----------------+
563  * +----------------+----------------+----------------+----------------+
565  * +----------------+----------------+----------------+----------------+
566  *   id - uint16_t, private guest value, echoed in response
567  *   operation - uint8_t, operation code, XENSND_OP_???
570  *   offset - uint32_t, read or write data offset within the shared buffer,
572  *     [0; XENSND_OP_OPEN.buffer_sz - 1].
573  *   length - uint32_t, read or write data length, octets
575  * Request open - open a PCM stream for playback or capture:
578  * +----------------+----------------+----------------+----------------+
580  * +----------------+----------------+----------------+----------------+
582  * +----------------+----------------+----------------+----------------+
584  * +----------------+----------------+----------------+----------------+
586  * +----------------+----------------+----------------+----------------+
588  * +----------------+----------------+----------------+----------------+
590  * +----------------+----------------+----------------+----------------+
592  * +----------------+----------------+----------------+----------------+
594  * +----------------+----------------+----------------+----------------+
596  * +----------------+----------------+----------------+----------------+
598  * +----------------+----------------+----------------+----------------+
600  * pcm_rate - uint32_t, stream data rate, Hz
601  * pcm_format - uint8_t, XENSND_PCM_FORMAT_XXX value
602  * pcm_channels - uint8_t, number of channels of this stream,
603  *   [channels-min; channels-max]
604  * buffer_sz - uint32_t, buffer size to be allocated, octets
605  * period_sz - uint32_t, event period size, octets
613  * gref_directory - grant_ref_t, a reference to the first shared page
635  * +----------------+----------------+----------------+----------------+
637  * +----------------+----------------+----------------+----------------+
639  * +----------------+----------------+----------------+----------------+
641  * +----------------+----------------+----------------+----------------+
643  * +----------------+----------------+----------------+----------------+
645  * +----------------+----------------+----------------+----------------+
646  * |                             gref[N - 1]                           | N*4+8
647  * +----------------+----------------+----------------+----------------+
649  * gref_dir_next_page - grant_ref_t, reference to the next page describing
651  * gref[i] - grant_ref_t, reference to a shared page of the buffer
656  *   num_grefs_total = (XENSND_OP_OPEN.buffer_sz + XEN_PAGE_SIZE - 1) /
666  *  Request close - close an opened pcm stream:
668  * +----------------+----------------+----------------+----------------+
670  * +----------------+----------------+----------------+----------------+
672  * +----------------+----------------+----------------+----------------+
674  * +----------------+----------------+----------------+----------------+
676  * +----------------+----------------+----------------+----------------+
678  * Request read/write - used for read (for capture) or write (for playback):
680  * +----------------+----------------+----------------+----------------+
682  * +----------------+----------------+----------------+----------------+
684  * +----------------+----------------+----------------+----------------+
686  * +----------------+----------------+----------------+----------------+
688  * +----------------+----------------+----------------+----------------+
690  * +----------------+----------------+----------------+----------------+
692  * +----------------+----------------+----------------+----------------+
694  * +----------------+----------------+----------------+----------------+
696  * operation - XENSND_OP_READ for read or XENSND_OP_WRITE for write
705  * Request set/get volume - set/get channels' volume of the stream given:
707  * +----------------+----------------+----------------+----------------+
709  * +----------------+----------------+----------------+----------------+
711  * +----------------+----------------+----------------+----------------+
713  * +----------------+----------------+----------------+----------------+
715  * +----------------+----------------+----------------+----------------+
717  * +----------------+----------------+----------------+----------------+
719  * +----------------+----------------+----------------+----------------+
721  * +----------------+----------------+----------------+----------------+
723  * operation - XENSND_OP_SET_VOLUME for volume set
729  * +----------------+----------------+----------------+----------------+
731  * +----------------+----------------+----------------+----------------+
733  * +----------------+----------------+----------------+----------------+
735  * +----------------+----------------+----------------+----------------+
737  * +----------------+----------------+----------------+----------------+
738  * |                           channel[N - 1]                          | (N-1)*4
739  * +----------------+----------------+----------------+----------------+
742  * i - uint8_t, index of a channel
743  * channel[i] - sint32_t, volume of i-th channel
747  * Request mute/unmute - mute/unmute stream:
749  * +----------------+----------------+----------------+----------------+
751  * +----------------+----------------+----------------+----------------+
753  * +----------------+----------------+----------------+----------------+
755  * +----------------+----------------+----------------+----------------+
757  * +----------------+----------------+----------------+----------------+
759  * +----------------+----------------+----------------+----------------+
761  * +----------------+----------------+----------------+----------------+
763  * +----------------+----------------+----------------+----------------+
765  * operation - XENSND_OP_MUTE for mute or XENSND_OP_UNMUTE for unmute
770  * +----------------+----------------+----------------+----------------+
772  * +----------------+----------------+----------------+----------------+
774  * +----------------+----------------+----------------+----------------+
776  * +----------------+----------------+----------------+----------------+
778  * +----------------+----------------+----------------+----------------+
779  * |                           channel[N - 1]                          | (N-1)*4
780  * +----------------+----------------+----------------+----------------+
783  * i - uint8_t, index of a channel
784  * channel[i] - uint8_t, non-zero if i-th channel needs to be muted/unmuted
786  *------------------------------------ N.B. -----------------------------------
791  * Request stream running state change - trigger PCM stream running state
795  * +----------------+----------------+----------------+----------------+
797  * +----------------+----------------+----------------+----------------+
799  * +----------------+----------------+----------------+----------------+
801  * +----------------+----------------+----------------+----------------+
803  * +----------------+----------------+----------------+----------------+
805  * +----------------+----------------+----------------+----------------+
807  * +----------------+----------------+----------------+----------------+
809  * type - uint8_t, XENSND_OP_TRIGGER_XXX value
833  * +----------------+----------------+----------------+----------------+
835  * +----------------+----------------+----------------+----------------+
837  * +----------------+----------------+----------------+----------------+
838  * |                     formats mask low 32-bit                       | 12
839  * +----------------+----------------+----------------+----------------+
840  * |                     formats mask high 32-bit                      | 16
841  * +----------------+----------------+----------------+----------------+
843  * +----------------+----------------+----------------+----------------+
845  * +----------------+----------------+----------------+----------------+
847  * +----------------+----------------+----------------+----------------+
849  * +----------------+----------------+----------------+----------------+
851  * +----------------+----------------+----------------+----------------+
853  * +----------------+----------------+----------------+----------------+
855  * +----------------+----------------+----------------+----------------+
857  * +----------------+----------------+----------------+----------------+
859  * +----------------+----------------+----------------+----------------+
861  * +----------------+----------------+----------------+----------------+
863  * +----------------+----------------+----------------+----------------+
865  * formats - uint64_t, bit mask representing values of the parameter
869  *   min - uint32_t, minimum value of the parameter
870  *   max - uint32_t, maximum value of the parameter
897  *---------------------------------- Responses --------------------------------
903  * +----------------+----------------+----------------+----------------+
905  * +----------------+----------------+----------------+----------------+
907  * +----------------+----------------+----------------+----------------+
909  * id - uint16_t, copied from the request
910  * operation - uint8_t, XENSND_OP_* - copied from request
911  * status - int32_t, response status, zero on success and -XEN_EXX on failure
914  * HW parameter query response - response for XENSND_OP_HW_PARAM_QUERY:
916  * +----------------+----------------+----------------+----------------+
918  * +----------------+----------------+----------------+----------------+
920  * +----------------+----------------+----------------+----------------+
921  * |                     formats mask low 32-bit                       | 12
922  * +----------------+----------------+----------------+----------------+
923  * |                     formats mask high 32-bit                      | 16
924  * +----------------+----------------+----------------+----------------+
926  * +----------------+----------------+----------------+----------------+
928  * +----------------+----------------+----------------+----------------+
930  * +----------------+----------------+----------------+----------------+
932  * +----------------+----------------+----------------+----------------+
934  * +----------------+----------------+----------------+----------------+
936  * +----------------+----------------+----------------+----------------+
938  * +----------------+----------------+----------------+----------------+
940  * +----------------+----------------+----------------+----------------+
942  * +----------------+----------------+----------------+----------------+
944  * +----------------+----------------+----------------+----------------+
946  * +----------------+----------------+----------------+----------------+
953  *----------------------------------- Events ----------------------------------
956  *   evt-event-channel/evt-ring-ref XenStore entries
960  * +----------------+----------------+----------------+----------------+
962  * +----------------+----------------+----------------+----------------+
964  * +----------------+----------------+----------------+----------------+
966  * id - uint16_t, event id, may be used by front
967  * type - uint8_t, type of the event
970  * Current stream position - event from back to front when stream's
973  * +----------------+----------------+----------------+----------------+
975  * +----------------+----------------+----------------+----------------+
977  * +----------------+----------------+----------------+----------------+
978  * |                         position low 32-bit                       | 12
979  * +----------------+----------------+----------------+----------------+
980  * |                         position high 32-bit                      | 16
981  * +----------------+----------------+----------------+----------------+
983  * +----------------+----------------+----------------+----------------+
985  * +----------------+----------------+----------------+----------------+
987  * +----------------+----------------+----------------+----------------+
989  * position - current value of stream's playback/capture position, octets
1039  * XenStore entries (evt-ring-ref/evt-event-channel).
1057 #define XENSND_IN_RING_SIZE (XENSND_EVENT_PAGE_SIZE - XENSND_IN_RING_OFFS)