1 /*
2  * Copyright (C) 2016 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 
17 #ifndef ANDROID_HARDWARE_STREAM_HAL_INTERFACE_H
18 #define ANDROID_HARDWARE_STREAM_HAL_INTERFACE_H
19 
20 #include <vector>
21 
22 #include <media/audiohal/EffectHalInterface.h>
23 #include <media/MicrophoneInfo.h>
24 #include <system/audio.h>
25 #include <utils/Errors.h>
26 #include <utils/RefBase.h>
27 #include <utils/String8.h>
28 #include <utils/Vector.h>
29 
30 namespace android {
31 
32 class StreamHalInterface : public virtual RefBase
33 {
34   public:
35     // Return size of input/output buffer in bytes for this stream - eg. 4800.
36     virtual status_t getBufferSize(size_t *size) = 0;
37 
38     // Return the base configuration of the stream:
39     //   - channel mask;
40     //   - format - e.g. AUDIO_FORMAT_PCM_16_BIT;
41     //   - sampling rate in Hz - eg. 44100.
42     virtual status_t getAudioProperties(audio_config_base_t *configBase) = 0;
43 
44     // Convenience method.
getAudioProperties(uint32_t * sampleRate,audio_channel_mask_t * mask,audio_format_t * format)45     inline status_t getAudioProperties(
46             uint32_t *sampleRate, audio_channel_mask_t *mask, audio_format_t *format) {
47         audio_config_base_t config = AUDIO_CONFIG_BASE_INITIALIZER;
48         const status_t result = getAudioProperties(&config);
49         if (result == NO_ERROR) {
50             if (sampleRate != nullptr) *sampleRate = config.sample_rate;
51             if (mask != nullptr) *mask = config.channel_mask;
52             if (format != nullptr) *format = config.format;
53         }
54         return result;
55     }
56 
57     // Set audio stream parameters.
58     virtual status_t setParameters(const String8& kvPairs) = 0;
59 
60     // Get audio stream parameters.
61     virtual status_t getParameters(const String8& keys, String8 *values) = 0;
62 
63     // Return the frame size (number of bytes per sample) of a stream.
64     virtual status_t getFrameSize(size_t *size) = 0;
65 
66     // Add or remove the effect on the stream.
67     virtual status_t addEffect(sp<EffectHalInterface> effect) = 0;
68     virtual status_t removeEffect(sp<EffectHalInterface> effect) = 0;
69 
70     // Put the audio hardware input/output into standby mode.
71     virtual status_t standby() = 0;
72 
73     virtual status_t dump(int fd, const Vector<String16>& args = {}) = 0;
74 
75     // Start a stream operating in mmap mode.
76     virtual status_t start() = 0;
77 
78     // Stop a stream operating in mmap mode.
79     virtual status_t stop() = 0;
80 
81     // Retrieve information on the data buffer in mmap mode.
82     virtual status_t createMmapBuffer(int32_t minSizeFrames,
83                                       struct audio_mmap_buffer_info *info) = 0;
84 
85     // Get current read/write position in the mmap buffer
86     virtual status_t getMmapPosition(struct audio_mmap_position *position) = 0;
87 
88     // Set the priority of the thread that interacts with the HAL
89     // (must match the priority of the audioflinger's thread that calls 'read' / 'write')
90     virtual status_t setHalThreadPriority(int priority) = 0;
91 
92   protected:
93     // Subclasses can not be constructed directly by clients.
StreamHalInterface()94     StreamHalInterface() {}
95 
96     // The destructor automatically closes the stream.
~StreamHalInterface()97     virtual ~StreamHalInterface() {}
98 };
99 
100 class StreamOutHalInterfaceCallback : public virtual RefBase {
101   public:
onWriteReady()102     virtual void onWriteReady() {}
onDrainReady()103     virtual void onDrainReady() {}
onError()104     virtual void onError() {}
105 
106   protected:
StreamOutHalInterfaceCallback()107     StreamOutHalInterfaceCallback() {}
~StreamOutHalInterfaceCallback()108     virtual ~StreamOutHalInterfaceCallback() {}
109 };
110 
111 class StreamOutHalInterfaceEventCallback : public virtual RefBase {
112 public:
113     virtual void onCodecFormatChanged(const std::basic_string<uint8_t>& metadataBs) = 0;
114 
115 protected:
StreamOutHalInterfaceEventCallback()116     StreamOutHalInterfaceEventCallback() {}
~StreamOutHalInterfaceEventCallback()117     virtual ~StreamOutHalInterfaceEventCallback() {}
118 };
119 
120 class StreamOutHalInterface : public virtual StreamHalInterface {
121   public:
122     // Return the audio hardware driver estimated latency in milliseconds.
123     virtual status_t getLatency(uint32_t *latency) = 0;
124 
125     // Use this method in situations where audio mixing is done in the hardware.
126     virtual status_t setVolume(float left, float right) = 0;
127 
128     // Selects the audio presentation (if available).
129     virtual status_t selectPresentation(int presentationId, int programId) = 0;
130 
131     // Write audio buffer to driver.
132     virtual status_t write(const void *buffer, size_t bytes, size_t *written) = 0;
133 
134     // Return the number of audio frames written by the audio dsp to DAC since
135     // the output has exited standby.
136     virtual status_t getRenderPosition(uint32_t *dspFrames) = 0;
137 
138     // Get the local time at which the next write to the audio driver will be presented.
139     virtual status_t getNextWriteTimestamp(int64_t *timestamp) = 0;
140 
141     // Set the callback for notifying completion of non-blocking write and drain.
142     // The callback must be owned by someone else. The output stream does not own it
143     // to avoid strong pointer loops.
144     virtual status_t setCallback(wp<StreamOutHalInterfaceCallback> callback) = 0;
145 
146     // Returns whether pause and resume operations are supported.
147     virtual status_t supportsPauseAndResume(bool *supportsPause, bool *supportsResume) = 0;
148 
149     // Notifies to the audio driver to resume playback following a pause.
150     virtual status_t pause() = 0;
151 
152     // Notifies to the audio driver to resume playback following a pause.
153     virtual status_t resume() = 0;
154 
155     // Returns whether drain operation is supported.
156     virtual status_t supportsDrain(bool *supportsDrain) = 0;
157 
158     // Requests notification when data buffered by the driver/hardware has been played.
159     virtual status_t drain(bool earlyNotify) = 0;
160 
161     // Notifies to the audio driver to flush the queued data.
162     virtual status_t flush() = 0;
163 
164     // Return a recent count of the number of audio frames presented to an external observer.
165     virtual status_t getPresentationPosition(uint64_t *frames, struct timespec *timestamp) = 0;
166 
167     struct SourceMetadata {
168         std::vector<playback_track_metadata_v7_t> tracks;
169     };
170 
171     /**
172      * Called when the metadata of the stream's source has been changed.
173      * @param sourceMetadata Description of the audio that is played by the clients.
174      */
175     virtual status_t updateSourceMetadata(const SourceMetadata& sourceMetadata) = 0;
176 
177     // Returns the Dual Mono mode presentation setting.
178     virtual status_t getDualMonoMode(audio_dual_mono_mode_t* mode) = 0;
179 
180     // Sets the Dual Mono mode presentation on the output device.
181     virtual status_t setDualMonoMode(audio_dual_mono_mode_t mode) = 0;
182 
183     // Returns the Audio Description Mix level in dB.
184     virtual status_t getAudioDescriptionMixLevel(float* leveldB) = 0;
185 
186     // Sets the Audio Description Mix level in dB.
187     virtual status_t setAudioDescriptionMixLevel(float leveldB) = 0;
188 
189     // Retrieves current playback rate parameters.
190     virtual status_t getPlaybackRateParameters(audio_playback_rate_t* playbackRate) = 0;
191 
192     // Sets the playback rate parameters that control playback behavior.
193     virtual status_t setPlaybackRateParameters(const audio_playback_rate_t& playbackRate) = 0;
194 
195     virtual status_t setEventCallback(const sp<StreamOutHalInterfaceEventCallback>& callback) = 0;
196 
197   protected:
~StreamOutHalInterface()198     virtual ~StreamOutHalInterface() {}
199 };
200 
201 class StreamInHalInterface : public virtual StreamHalInterface {
202   public:
203     // Set the input gain for the audio driver.
204     virtual status_t setGain(float gain) = 0;
205 
206     // Read audio buffer in from driver.
207     virtual status_t read(void *buffer, size_t bytes, size_t *read) = 0;
208 
209     // Return the amount of input frames lost in the audio driver.
210     virtual status_t getInputFramesLost(uint32_t *framesLost) = 0;
211 
212     // Return a recent count of the number of audio frames received and
213     // the clock time associated with that frame count.
214     virtual status_t getCapturePosition(int64_t *frames, int64_t *time) = 0;
215 
216     // Get active microphones
217     virtual status_t getActiveMicrophones(std::vector<media::MicrophoneInfo> *microphones) = 0;
218 
219     // Set direction for capture processing
220     virtual status_t setPreferredMicrophoneDirection(audio_microphone_direction_t) = 0;
221 
222     // Set zoom factor for capture stream
223     virtual status_t setPreferredMicrophoneFieldDimension(float zoom) = 0;
224 
225     struct SinkMetadata {
226         std::vector<record_track_metadata_v7_t> tracks;
227     };
228     /**
229      * Called when the metadata of the stream's sink has been changed.
230      * @param sinkMetadata Description of the audio that is suggested by the clients.
231      */
232     virtual status_t updateSinkMetadata(const SinkMetadata& sinkMetadata) = 0;
233 
234   protected:
~StreamInHalInterface()235     virtual ~StreamInHalInterface() {}
236 };
237 
238 } // namespace android
239 
240 #endif // ANDROID_HARDWARE_STREAM_HAL_INTERFACE_H
241