Home | History | Annotate | Download | only in audiohal
      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.
     87     StreamHalInterface() {}
     88 
     89     // The destructor automatically closes the stream.
     90     virtual ~StreamHalInterface() {}
     91 };
     92 
     93 class StreamOutHalInterfaceCallback : public virtual RefBase {
     94   public:
     95     virtual void onWriteReady() {}
     96     virtual void onDrainReady() {}
     97     virtual void onError() {}
     98 
     99   protected:
    100     StreamOutHalInterfaceCallback() {}
    101     virtual ~StreamOutHalInterfaceCallback() {}
    102 };
    103 
    104 class StreamOutHalInterface : public virtual StreamHalInterface {
    105   public:
    106     // Return the audio hardware driver estimated latency in milliseconds.
    107     virtual status_t getLatency(uint32_t *latency) = 0;
    108 
    109     // Use this method in situations where audio mixing is done in the hardware.
    110     virtual status_t setVolume(float left, float right) = 0;
    111 
    112     // Selects the audio presentation (if available).
    113     virtual status_t selectPresentation(int presentationId, int programId) = 0;
    114 
    115     // Write audio buffer to driver.
    116     virtual status_t write(const void *buffer, size_t bytes, size_t *written) = 0;
    117 
    118     // Return the number of audio frames written by the audio dsp to DAC since
    119     // the output has exited standby.
    120     virtual status_t getRenderPosition(uint32_t *dspFrames) = 0;
    121 
    122     // Get the local time at which the next write to the audio driver will be presented.
    123     virtual status_t getNextWriteTimestamp(int64_t *timestamp) = 0;
    124 
    125     // Set the callback for notifying completion of non-blocking write and drain.
    126     // The callback must be owned by someone else. The output stream does not own it
    127     // to avoid strong pointer loops.
    128     virtual status_t setCallback(wp<StreamOutHalInterfaceCallback> callback) = 0;
    129 
    130     // Returns whether pause and resume operations are supported.
    131     virtual status_t supportsPauseAndResume(bool *supportsPause, bool *supportsResume) = 0;
    132 
    133     // Notifies to the audio driver to resume playback following a pause.
    134     virtual status_t pause() = 0;
    135 
    136     // Notifies to the audio driver to resume playback following a pause.
    137     virtual status_t resume() = 0;
    138 
    139     // Returns whether drain operation is supported.
    140     virtual status_t supportsDrain(bool *supportsDrain) = 0;
    141 
    142     // Requests notification when data buffered by the driver/hardware has been played.
    143     virtual status_t drain(bool earlyNotify) = 0;
    144 
    145     // Notifies to the audio driver to flush the queued data.
    146     virtual status_t flush() = 0;
    147 
    148     // Return a recent count of the number of audio frames presented to an external observer.
    149     virtual status_t getPresentationPosition(uint64_t *frames, struct timespec *timestamp) = 0;
    150 
    151     struct SourceMetadata {
    152         std::vector<playback_track_metadata_t> tracks;
    153     };
    154     /**
    155      * Called when the metadata of the stream's source has been changed.
    156      * @param sourceMetadata Description of the audio that is played by the clients.
    157      */
    158     virtual status_t updateSourceMetadata(const SourceMetadata& sourceMetadata) = 0;
    159 
    160   protected:
    161     virtual ~StreamOutHalInterface() {}
    162 };
    163 
    164 class StreamInHalInterface : public virtual StreamHalInterface {
    165   public:
    166     // Set the input gain for the audio driver.
    167     virtual status_t setGain(float gain) = 0;
    168 
    169     // Read audio buffer in from driver.
    170     virtual status_t read(void *buffer, size_t bytes, size_t *read) = 0;
    171 
    172     // Return the amount of input frames lost in the audio driver.
    173     virtual status_t getInputFramesLost(uint32_t *framesLost) = 0;
    174 
    175     // Return a recent count of the number of audio frames received and
    176     // the clock time associated with that frame count.
    177     virtual status_t getCapturePosition(int64_t *frames, int64_t *time) = 0;
    178 
    179     // Get active microphones
    180     virtual status_t getActiveMicrophones(std::vector<media::MicrophoneInfo> *microphones) = 0;
    181 
    182     // Set direction for capture processing
    183     virtual status_t setPreferredMicrophoneDirection(audio_microphone_direction_t) = 0;
    184 
    185     // Set zoom factor for capture stream
    186     virtual status_t setPreferredMicrophoneFieldDimension(float zoom) = 0;
    187 
    188     struct SinkMetadata {
    189         std::vector<record_track_metadata_t> tracks;
    190     };
    191     /**
    192      * Called when the metadata of the stream's sink has been changed.
    193      * @param sinkMetadata Description of the audio that is suggested by the clients.
    194      */
    195     virtual status_t updateSinkMetadata(const SinkMetadata& sinkMetadata) = 0;
    196 
    197   protected:
    198     virtual ~StreamInHalInterface() {}
    199 };
    200 
    201 } // namespace android
    202 
    203 #endif // ANDROID_HARDWARE_STREAM_HAL_INTERFACE_H
    204