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