1/*
2 * Copyright (C) 2019 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.audio@6.0;
18
19import android.hardware.audio.common@6.0;
20import IStream;
21import IStreamOutCallback;
22
23interface IStreamOut extends IStream {
24    /**
25     * Return the audio hardware driver estimated latency in milliseconds.
26     *
27     * @return latencyMs latency in milliseconds.
28     */
29    getLatency() generates (uint32_t latencyMs);
30
31    /**
32     * This method is used in situations where audio mixing is done in the
33     * hardware. This method serves as a direct interface with hardware,
34     * allowing to directly set the volume as apposed to via the framework.
35     * This method might produce multiple PCM outputs or hardware accelerated
36     * codecs, such as MP3 or AAC.
37     * Optional method
38     *
39     * @param left left channel attenuation, 1.0f is unity, 0.0f is zero.
40     * @param right right channel attenuation, 1.0f is unity, 0.0f is zero.
41     * @return retval operation completion status.
42     *        If a volume is outside [0,1], return INVALID_ARGUMENTS
43     */
44    setVolume(float left, float right) generates (Result retval);
45
46    /**
47     * Commands that can be executed on the driver writer thread.
48     */
49    enum WriteCommand : int32_t {
50        WRITE,
51        GET_PRESENTATION_POSITION,
52        GET_LATENCY
53    };
54
55    /**
56     * Data structure passed back to the client via status message queue
57     * of 'write' operation.
58     *
59     * Possible values of 'retval' field:
60     *  - OK, write operation was successful;
61     *  - INVALID_ARGUMENTS, stream was not configured properly;
62     *  - INVALID_STATE, stream is in a state that doesn't allow writes;
63     *  - INVALID_OPERATION, retrieving presentation position isn't supported.
64     */
65    struct WriteStatus {
66        Result retval;
67        WriteCommand replyTo;  // discriminator
68        union Reply {
69            uint64_t written;  // WRITE command, amount of bytes written, >= 0.
70            struct PresentationPosition {  // same as generated by
71                uint64_t frames;           // getPresentationPosition.
72                TimeSpec timeStamp;
73            } presentationPosition;
74            uint32_t latencyMs; // Same as generated by getLatency.
75        } reply;
76    };
77
78    /**
79     * Called when the metadata of the stream's source has been changed.
80     * @param sourceMetadata Description of the audio that is played by the clients.
81     */
82    updateSourceMetadata(SourceMetadata sourceMetadata);
83
84    /**
85     * Set up required transports for passing audio buffers to the driver.
86     *
87     * The transport consists of three message queues:
88     *  -- command queue is used to instruct the writer thread what operation
89     *     to perform;
90     *  -- data queue is used for passing audio data from the client
91     *     to the driver;
92     *  -- status queue is used for reporting operation status
93     *     (e.g. amount of bytes actually written or error code).
94     *
95     * The driver operates on a dedicated thread. The client must ensure that
96     * the thread is given an appropriate priority and assigned to correct
97     * scheduler and cgroup. For this purpose, the method returns identifiers
98     * of the driver thread.
99     *
100     * @param frameSize the size of a single frame, in bytes.
101     * @param framesCount the number of frames in a buffer.
102     * @return retval OK if both message queues were created successfully.
103     *                INVALID_STATE if the method was already called.
104     *                INVALID_ARGUMENTS if there was a problem setting up
105     *                                  the queues.
106     * @return commandMQ a message queue used for passing commands.
107     * @return dataMQ a message queue used for passing audio data in the format
108     *                specified at the stream opening.
109     * @return statusMQ a message queue used for passing status from the driver
110     *                  using WriteStatus structures.
111     * @return threadInfo identifiers of the driver's dedicated thread.
112     */
113    prepareForWriting(uint32_t frameSize, uint32_t framesCount)
114    generates (
115            Result retval,
116            fmq_sync<WriteCommand> commandMQ,
117            fmq_sync<uint8_t> dataMQ,
118            fmq_sync<WriteStatus> statusMQ,
119            ThreadInfo threadInfo);
120
121    /**
122     * Return the number of audio frames written by the audio DSP to DAC since
123     * the output has exited standby.
124     * Optional method
125     *
126     * @return retval operation completion status.
127     * @return dspFrames number of audio frames written.
128     */
129    getRenderPosition() generates (Result retval, uint32_t dspFrames);
130
131    /**
132     * Get the local time at which the next write to the audio driver will be
133     * presented. The units are microseconds, where the epoch is decided by the
134     * local audio HAL.
135     * Optional method
136     *
137     * @return retval operation completion status.
138     * @return timestampUs time of the next write.
139     */
140    getNextWriteTimestamp() generates (Result retval, int64_t timestampUs);
141
142    /**
143     * Set the callback interface for notifying completion of non-blocking
144     * write and drain.
145     *
146     * Calling this function implies that all future 'write' and 'drain'
147     * must be non-blocking and use the callback to signal completion.
148     *
149     * 'clearCallback' method needs to be called in order to release the local
150     * callback proxy on the server side and thus dereference the callback
151     * implementation on the client side.
152     *
153     * @return retval operation completion status.
154     */
155    setCallback(IStreamOutCallback callback) generates (Result retval);
156
157    /**
158     * Clears the callback previously set via 'setCallback' method.
159     *
160     * Warning: failure to call this method results in callback implementation
161     * on the client side being held until the HAL server termination.
162     *
163     * If no callback was previously set, the method should be a no-op
164     * and return OK.
165     *
166     * @return retval operation completion status: OK or NOT_SUPPORTED.
167     */
168    clearCallback() generates (Result retval);
169
170    /**
171     * Returns whether HAL supports pausing and resuming of streams.
172     *
173     * @return supportsPause true if pausing is supported.
174     * @return supportsResume true if resume is supported.
175     */
176    supportsPauseAndResume()
177            generates (bool supportsPause, bool supportsResume);
178
179    /**
180     * Notifies to the audio driver to stop playback however the queued buffers
181     * are retained by the hardware. Useful for implementing pause/resume. Empty
182     * implementation if not supported however must be implemented for hardware
183     * with non-trivial latency. In the pause state, some audio hardware may
184     * still be using power. Client code may consider calling 'suspend' after a
185     * timeout to prevent that excess power usage.
186     *
187     * Implementation of this function is mandatory for offloaded playback.
188     *
189     * @return retval operation completion status.
190     */
191    pause() generates (Result retval);
192
193    /**
194     * Notifies to the audio driver to resume playback following a pause.
195     * Returns error INVALID_STATE if called without matching pause.
196     *
197     * Implementation of this function is mandatory for offloaded playback.
198     *
199     * @return retval operation completion status.
200     */
201    resume() generates (Result retval);
202
203    /**
204     * Returns whether HAL supports draining of streams.
205     *
206     * @return supports true if draining is supported.
207     */
208    supportsDrain() generates (bool supports);
209
210    /**
211     * Requests notification when data buffered by the driver/hardware has been
212     * played. If 'setCallback' has previously been called to enable
213     * non-blocking mode, then 'drain' must not block, instead it must return
214     * quickly and completion of the drain is notified through the callback. If
215     * 'setCallback' has not been called, then 'drain' must block until
216     * completion.
217     *
218     * If 'type' is 'ALL', the drain completes when all previously written data
219     * has been played.
220     *
221     * If 'type' is 'EARLY_NOTIFY', the drain completes shortly before all data
222     * for the current track has played to allow time for the framework to
223     * perform a gapless track switch.
224     *
225     * Drain must return immediately on 'stop' and 'flush' calls.
226     *
227     * Implementation of this function is mandatory for offloaded playback.
228     *
229     * @param type type of drain.
230     * @return retval operation completion status.
231     */
232    drain(AudioDrain type) generates (Result retval);
233
234    /**
235     * Notifies to the audio driver to flush the queued data. Stream must
236     * already be paused before calling 'flush'.
237     * Optional method
238     *
239     * Implementation of this function is mandatory for offloaded playback.
240     *
241     * @return retval operation completion status.
242     */
243    flush() generates (Result retval);
244
245    /**
246     * Return a recent count of the number of audio frames presented to an
247     * external observer. This excludes frames which have been written but are
248     * still in the pipeline. The count is not reset to zero when output enters
249     * standby. Also returns the value of CLOCK_MONOTONIC as of this
250     * presentation count. The returned count is expected to be 'recent', but
251     * does not need to be the most recent possible value. However, the
252     * associated time must correspond to whatever count is returned.
253     *
254     * Example: assume that N+M frames have been presented, where M is a 'small'
255     * number. Then it is permissible to return N instead of N+M, and the
256     * timestamp must correspond to N rather than N+M. The terms 'recent' and
257     * 'small' are not defined. They reflect the quality of the implementation.
258     *
259     * Optional method
260     *
261     * @return retval operation completion status.
262     * @return frames count of presented audio frames.
263     * @return timeStamp associated clock time.
264     */
265    getPresentationPosition()
266            generates (Result retval, uint64_t frames, TimeSpec timeStamp);
267
268    /**
269     * Selects a presentation for decoding from a next generation media stream
270     * (as defined per ETSI TS 103 190-2) and a program within the presentation.
271     * Optional method
272     *
273     * @param presentationId selected audio presentation.
274     * @param programId refinement for the presentation.
275     * @return retval operation completion status.
276     */
277    selectPresentation(int32_t presentationId, int32_t programId)
278            generates (Result retval);
279};
280