Lines Matching full:-
4 * Unified sound-device I/O interface for Xen guest OSes.
24 * Copyright (C) 2013-2015 GlobalLogic Inc.
25 * Copyright (C) 2016-2017 EPAM Systems Inc.
51 * Front->back notifications: when enqueuing a new request, sending a
53 * hold-off mechanism provided by the ring macros). Backends must set
56 * Back->front notifications: when enqueuing a new response, sending a
58 * hold-off mechanism provided by the ring macros). Frontends must set
61 * The two halves of a para-virtual sound card driver utilize nodes within
75 * Note: depending on the use-case backend can expose more sound cards and
81 *--------------------------------- Backend -----------------------------------
83 * /local/domain/0/backend/vsnd/1/0/frontend-id = "1"
88 *--------------------------------- Frontend ----------------------------------
90 * /local/domain/1/device/vsnd/0/backend-id = "0"
95 *----------------------------- Card configuration ----------------------------
97 * /local/domain/1/device/vsnd/0/short-name = "Card short name"
98 * /local/domain/1/device/vsnd/0/long-name = "Card long name"
99 * /local/domain/1/device/vsnd/0/sample-rates = "8000,32000,44100,48000,96000"
100 * /local/domain/1/device/vsnd/0/sample-formats = "s8,u8,s16_le,s16_be"
101 * /local/domain/1/device/vsnd/0/buffer-size = "262144"
103 *------------------------------- PCM device 0 --------------------------------
106 * /local/domain/1/device/vsnd/0/0/channels-max = "5"
108 *----------------------------- Stream 0, playback ----------------------------
111 * /local/domain/1/device/vsnd/0/0/0/sample-formats = "s8,u8"
112 * /local/domain/1/device/vsnd/0/0/0/unique-id = "0"
114 * /local/domain/1/device/vsnd/0/0/0/ring-ref = "386"
115 * /local/domain/1/device/vsnd/0/0/0/event-channel = "15"
116 * /local/domain/1/device/vsnd/0/0/0/evt-ring-ref = "1386"
117 * /local/domain/1/device/vsnd/0/0/0/evt-event-channel = "215"
119 *------------------------------ Stream 1, capture ----------------------------
122 * /local/domain/1/device/vsnd/0/0/1/channels-max = "2"
123 * /local/domain/1/device/vsnd/0/0/1/unique-id = "1"
125 * /local/domain/1/device/vsnd/0/0/1/ring-ref = "384"
126 * /local/domain/1/device/vsnd/0/0/1/event-channel = "13"
127 * /local/domain/1/device/vsnd/0/0/1/evt-ring-ref = "1384"
128 * /local/domain/1/device/vsnd/0/0/1/evt-event-channel = "213"
130 *------------------------------- PCM device 1 --------------------------------
132 * /local/domain/1/device/vsnd/0/1/name = "HDMI-0"
133 * /local/domain/1/device/vsnd/0/1/sample-rates = "8000,32000,44100"
135 *------------------------------ Stream 0, capture ----------------------------
138 * /local/domain/1/device/vsnd/0/1/0/unique-id = "2"
140 * /local/domain/1/device/vsnd/0/1/0/ring-ref = "387"
141 * /local/domain/1/device/vsnd/0/1/0/event-channel = "151"
142 * /local/domain/1/device/vsnd/0/1/0/evt-ring-ref = "1387"
143 * /local/domain/1/device/vsnd/0/1/0/evt-event-channel = "351"
145 *------------------------------- PCM device 2 --------------------------------
149 *----------------------------- Stream 0, playback ----------------------------
152 * /local/domain/1/device/vsnd/0/2/0/unique-id = "3"
154 * /local/domain/1/device/vsnd/0/2/0/ring-ref = "389"
155 * /local/domain/1/device/vsnd/0/2/0/event-channel = "152"
156 * /local/domain/1/device/vsnd/0/2/0/evt-ring-ref = "1389"
157 * /local/domain/1/device/vsnd/0/2/0/evt-event-channel = "452"
163 *----------------------------- Protocol version ------------------------------
175 *-------------------------------- Addressing ---------------------------------
177 * dom-id
182 * dev-id
187 * pcm-dev-idx
192 * stream-idx
198 * /local/domain/<dom-id>/device/vsnd/<dev-id>/<pcm-dev-idx>/<stream-idx>/...
200 *----------------------------- Protocol version ------------------------------
207 *------------------------------- PCM settings --------------------------------
211 * defined at higher level of the hierarchy and be fully or partially re-used
217 * Every underlying layer in turn can re-define some or all of them to better
223 * channels-min
226 * The minimum amount of channels that is supported, [1; channels-max].
229 * channels-max
233 * Must be at least <channels-min>.
235 * sample-rates
242 * sample-formats
248 * buffer-size
253 *----------------------- Virtual sound card settings -------------------------
254 * short-name
259 * long-name
264 *----------------------------- Device settings -------------------------------
270 *----------------------------- Stream settings -------------------------------
275 * Stream type: "p" - playback stream, "c" - capture stream
280 * unique-id
287 *-------------------- Stream Request Transport Parameters --------------------
289 * event-channel
295 * ring-ref
301 *--------------------- Stream Event Transport Parameters ---------------------
306 * evt-event-channel
312 * evt-ring-ref
374 *------------------------------- Recovery flow -------------------------------
408 * to periodically check if this is the right time to re-try removal of
419 * S - signed, U - unsigned, F - float
420 * bits - 8, 16, 24, 32
421 * name - MU_LAW, GSM, etc.
424 * LE - Little endian, BE - Big endian
440 #define XENSND_PCM_FORMAT_F32_LE 14 /* 4-byte float, IEEE-754 32-bit, */
441 #define XENSND_PCM_FORMAT_F32_BE 15 /* range -1.0 to 1.0 */
442 #define XENSND_PCM_FORMAT_F64_LE 16 /* 8-byte float, IEEE-754 64-bit, */
443 #define XENSND_PCM_FORMAT_F64_BE 17 /* range -1.0 to 1.0 */
491 #define XENSND_FIELD_VCARD_SHORT_NAME "short-name"
492 #define XENSND_FIELD_VCARD_LONG_NAME "long-name"
493 #define XENSND_FIELD_RING_REF "ring-ref"
494 #define XENSND_FIELD_EVT_CHNL "event-channel"
495 #define XENSND_FIELD_EVT_RING_REF "evt-ring-ref"
496 #define XENSND_FIELD_EVT_EVT_CHNL "evt-event-channel"
499 #define XENSND_FIELD_STREAM_UNIQUE_ID "unique-id"
500 #define XENSND_FIELD_CHANNELS_MIN "channels-min"
501 #define XENSND_FIELD_CHANNELS_MAX "channels-max"
502 #define XENSND_FIELD_SAMPLE_RATES "sample-rates"
503 #define XENSND_FIELD_SAMPLE_FORMATS "sample-formats"
504 #define XENSND_FIELD_BUFFER_SIZE "buffer-size"
546 * Status return code is zero on success and -XEN_EXX on failure.
561 * The two halves of a Para-virtual sound driver communicate with
573 *---------------------------------- Requests ---------------------------------
578 * +----------------+----------------+----------------+----------------+
580 * +----------------+----------------+----------------+----------------+
582 * +----------------+----------------+----------------+----------------+
583 * id - uint16_t, private guest value, echoed in response
584 * operation - uint8_t, operation code, XENSND_OP_???
587 * offset - uint32_t, read or write data offset within the shared buffer,
589 * [0; XENSND_OP_OPEN.buffer_sz - 1].
590 * length - uint32_t, read or write data length, octets
592 * Request open - open a PCM stream for playback or capture:
595 * +----------------+----------------+----------------+----------------+
597 * +----------------+----------------+----------------+----------------+
599 * +----------------+----------------+----------------+----------------+
601 * +----------------+----------------+----------------+----------------+
603 * +----------------+----------------+----------------+----------------+
605 * +----------------+----------------+----------------+----------------+
607 * +----------------+----------------+----------------+----------------+
609 * +----------------+----------------+----------------+----------------+
611 * +----------------+----------------+----------------+----------------+
613 * +----------------+----------------+----------------+----------------+
615 * +----------------+----------------+----------------+----------------+
617 * pcm_rate - uint32_t, stream data rate, Hz
618 * pcm_format - uint8_t, XENSND_PCM_FORMAT_XXX value
619 * pcm_channels - uint8_t, number of channels of this stream,
620 * [channels-min; channels-max]
621 * buffer_sz - uint32_t, buffer size to be allocated, octets
622 * period_sz - uint32_t, event period size, octets
630 * gref_directory - grant_ref_t, a reference to the first shared page
652 * +----------------+----------------+----------------+----------------+
654 * +----------------+----------------+----------------+----------------+
656 * +----------------+----------------+----------------+----------------+
658 * +----------------+----------------+----------------+----------------+
660 * +----------------+----------------+----------------+----------------+
662 * +----------------+----------------+----------------+----------------+
663 * | gref[N - 1] | N*4+8
664 * +----------------+----------------+----------------+----------------+
666 * gref_dir_next_page - grant_ref_t, reference to the next page describing
668 * gref[i] - grant_ref_t, reference to a shared page of the buffer
673 * num_grefs_total = (XENSND_OP_OPEN.buffer_sz + XEN_PAGE_SIZE - 1) /
683 * Request close - close an opened pcm stream:
685 * +----------------+----------------+----------------+----------------+
687 * +----------------+----------------+----------------+----------------+
689 * +----------------+----------------+----------------+----------------+
691 * +----------------+----------------+----------------+----------------+
693 * +----------------+----------------+----------------+----------------+
695 * Request read/write - used for read (for capture) or write (for playback):
697 * +----------------+----------------+----------------+----------------+
699 * +----------------+----------------+----------------+----------------+
701 * +----------------+----------------+----------------+----------------+
703 * +----------------+----------------+----------------+----------------+
705 * +----------------+----------------+----------------+----------------+
707 * +----------------+----------------+----------------+----------------+
709 * +----------------+----------------+----------------+----------------+
711 * +----------------+----------------+----------------+----------------+
713 * operation - XENSND_OP_READ for read or XENSND_OP_WRITE for write
722 * Request set/get volume - set/get channels' volume of the stream given:
724 * +----------------+----------------+----------------+----------------+
726 * +----------------+----------------+----------------+----------------+
728 * +----------------+----------------+----------------+----------------+
730 * +----------------+----------------+----------------+----------------+
732 * +----------------+----------------+----------------+----------------+
734 * +----------------+----------------+----------------+----------------+
736 * +----------------+----------------+----------------+----------------+
738 * +----------------+----------------+----------------+----------------+
740 * operation - XENSND_OP_SET_VOLUME for volume set
746 * +----------------+----------------+----------------+----------------+
748 * +----------------+----------------+----------------+----------------+
750 * +----------------+----------------+----------------+----------------+
752 * +----------------+----------------+----------------+----------------+
754 * +----------------+----------------+----------------+----------------+
755 * | channel[N - 1] | (N-1)*4
756 * +----------------+----------------+----------------+----------------+
759 * i - uint8_t, index of a channel
760 * channel[i] - sint32_t, volume of i-th channel
764 * Request mute/unmute - mute/unmute stream:
766 * +----------------+----------------+----------------+----------------+
768 * +----------------+----------------+----------------+----------------+
770 * +----------------+----------------+----------------+----------------+
772 * +----------------+----------------+----------------+----------------+
774 * +----------------+----------------+----------------+----------------+
776 * +----------------+----------------+----------------+----------------+
778 * +----------------+----------------+----------------+----------------+
780 * +----------------+----------------+----------------+----------------+
782 * operation - XENSND_OP_MUTE for mute or XENSND_OP_UNMUTE for unmute
787 * +----------------+----------------+----------------+----------------+
789 * +----------------+----------------+----------------+----------------+
791 * +----------------+----------------+----------------+----------------+
793 * +----------------+----------------+----------------+----------------+
795 * +----------------+----------------+----------------+----------------+
796 * | channel[N - 1] | (N-1)*4
797 * +----------------+----------------+----------------+----------------+
800 * i - uint8_t, index of a channel
801 * channel[i] - uint8_t, non-zero if i-th channel needs to be muted/unmuted
803 *------------------------------------ N.B. -----------------------------------
808 * Request stream running state change - trigger PCM stream running state
812 * +----------------+----------------+----------------+----------------+
814 * +----------------+----------------+----------------+----------------+
816 * +----------------+----------------+----------------+----------------+
818 * +----------------+----------------+----------------+----------------+
820 * +----------------+----------------+----------------+----------------+
822 * +----------------+----------------+----------------+----------------+
824 * +----------------+----------------+----------------+----------------+
826 * type - uint8_t, XENSND_OP_TRIGGER_XXX value
850 * +----------------+----------------+----------------+----------------+
852 * +----------------+----------------+----------------+----------------+
854 * +----------------+----------------+----------------+----------------+
855 * | formats mask low 32-bit | 12
856 * +----------------+----------------+----------------+----------------+
857 * | formats mask high 32-bit | 16
858 * +----------------+----------------+----------------+----------------+
860 * +----------------+----------------+----------------+----------------+
862 * +----------------+----------------+----------------+----------------+
864 * +----------------+----------------+----------------+----------------+
866 * +----------------+----------------+----------------+----------------+
868 * +----------------+----------------+----------------+----------------+
870 * +----------------+----------------+----------------+----------------+
872 * +----------------+----------------+----------------+----------------+
874 * +----------------+----------------+----------------+----------------+
876 * +----------------+----------------+----------------+----------------+
878 * +----------------+----------------+----------------+----------------+
880 * +----------------+----------------+----------------+----------------+
882 * formats - uint64_t, bit mask representing values of the parameter
886 * min - uint32_t, minimum value of the parameter
887 * max - uint32_t, maximum value of the parameter
914 *---------------------------------- Responses --------------------------------
920 * +----------------+----------------+----------------+----------------+
922 * +----------------+----------------+----------------+----------------+
924 * +----------------+----------------+----------------+----------------+
926 * id - uint16_t, copied from the request
927 * operation - uint8_t, XENSND_OP_* - copied from request
928 * status - int32_t, response status, zero on success and -XEN_EXX on failure
931 * HW parameter query response - response for XENSND_OP_HW_PARAM_QUERY:
933 * +----------------+----------------+----------------+----------------+
935 * +----------------+----------------+----------------+----------------+
937 * +----------------+----------------+----------------+----------------+
938 * | formats mask low 32-bit | 12
939 * +----------------+----------------+----------------+----------------+
940 * | formats mask high 32-bit | 16
941 * +----------------+----------------+----------------+----------------+
943 * +----------------+----------------+----------------+----------------+
945 * +----------------+----------------+----------------+----------------+
947 * +----------------+----------------+----------------+----------------+
949 * +----------------+----------------+----------------+----------------+
951 * +----------------+----------------+----------------+----------------+
953 * +----------------+----------------+----------------+----------------+
955 * +----------------+----------------+----------------+----------------+
957 * +----------------+----------------+----------------+----------------+
959 * +----------------+----------------+----------------+----------------+
961 * +----------------+----------------+----------------+----------------+
963 * +----------------+----------------+----------------+----------------+
970 *----------------------------------- Events ----------------------------------
973 * evt-event-channel/evt-ring-ref XenStore entries
977 * +----------------+----------------+----------------+----------------+
979 * +----------------+----------------+----------------+----------------+
981 * +----------------+----------------+----------------+----------------+
983 * id - uint16_t, event id, may be used by front
984 * type - uint8_t, type of the event
987 * Current stream position - event from back to front when stream's
990 * +----------------+----------------+----------------+----------------+
992 * +----------------+----------------+----------------+----------------+
994 * +----------------+----------------+----------------+----------------+
995 * | position low 32-bit | 12
996 * +----------------+----------------+----------------+----------------+
997 * | position high 32-bit | 16
998 * +----------------+----------------+----------------+----------------+
1000 * +----------------+----------------+----------------+----------------+
1002 * +----------------+----------------+----------------+----------------+
1004 * +----------------+----------------+----------------+----------------+
1006 * position - current value of stream's playback/capture position, octets
1056 * XenStore entries (evt-ring-ref/evt-event-channel).
1074 #define XENSND_IN_RING_SIZE (XENSND_EVENT_PAGE_SIZE - XENSND_IN_RING_OFFS)