include/hardware_legacy/AudioHardwareInterface.h

   1 /*
   2  * Copyright (C) 2007 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_AUDIO_HARDWARE_INTERFACE_H
  18 #define ANDROID_AUDIO_HARDWARE_INTERFACE_H
  19
  20 #include <stdint.h>
  21 #include <sys/types.h>
  22
  23 #include <utils/Errors.h>
  24 #include <utils/Vector.h>
  25 #include <utils/String16.h>
  26 #include <utils/String8.h>
  27
  28 #include <media/IAudioFlinger.h>
  29 #include <hardware_legacy/AudioSystemLegacy.h>
  30
  31 #include <system/audio.h>
  32 #include <hardware/audio.h>
  33
  34 #include <cutils/bitops.h>
  35
  36 namespace android_audio_legacy {
  37     using android::Vector;
  38     using android::String16;
  39     using android::String8;
  40
  41 // ----------------------------------------------------------------------------
  42
  43 /**
  44  * AudioStreamOut is the abstraction interface for the audio output hardware.
  45  *
  46  * It provides information about various properties of the audio output hardware driver.
  47  */
  48 class AudioStreamOut {
  49 public:
  50     virtual             ~AudioStreamOut() = 0;
  51
  52     /** return audio sampling rate in hz - eg. 44100 */
  53     virtual uint32_t    sampleRate() const = 0;
  54
  55     /** returns size of output buffer - eg. 4800 */
  56     virtual size_t      bufferSize() const = 0;
  57
  58     /**
  59      * returns the output channel nask
  60      */
  61     virtual uint32_t    channels() const = 0;
  62
  63     /**
  64      * return audio format in 8bit or 16bit PCM format -
  65      * eg. AudioSystem:PCM_16_BIT
  66      */
  67     virtual int         format() const = 0;
  68
  69     /**
  70      * return the frame size (number of bytes per sample).
  71      */
  72     uint32_t    frameSize() const { return popcount(channels())*((format()==AUDIO_FORMAT_PCM_16_BIT)?sizeof(int16_t):sizeof(int8_t)); }
  73
  74     /**
  75      * return the audio hardware driver latency in milli seconds.
  76      */
  77     virtual uint32_t    latency() const = 0;
  78
  79     /**
  80      * Use this method in situations where audio mixing is done in the
  81      * hardware. This method serves as a direct interface with hardware,
  82      * allowing you to directly set the volume as apposed to via the framework.
  83      * This method might produce multiple PCM outputs or hardware accelerated
  84      * codecs, such as MP3 or AAC.
  85      */
  86     virtual status_t    setVolume(float left, float right) = 0;
  87
  88     /** write audio buffer to driver. Returns number of bytes written */
  89     virtual ssize_t     write(const void* buffer, size_t bytes) = 0;
  90
  91     /**
  92      * Put the audio hardware output into standby mode. Returns
  93      * status based on include/utils/Errors.h
  94      */
  95     virtual status_t    standby() = 0;
  96
  97     /** dump the state of the audio output device */
  98     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
  99
 100     // set/get audio output parameters. The function accepts a list of parameters
 101     // key value pairs in the form: key1=value1;key2=value2;...
 102     // Some keys are reserved for standard parameters (See AudioParameter class).
 103     // If the implementation does not accept a parameter change while the output is
 104     // active but the parameter is acceptable otherwise, it must return INVALID_OPERATION.
 105     // The audio flinger will put the output in standby and then change the parameter value.
 106     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 107     virtual String8     getParameters(const String8& keys) = 0;
 108
 109     // return the number of audio frames written by the audio dsp to DAC since
 110     // the output has exited standby
 111     virtual status_t    getRenderPosition(uint32_t *dspFrames) = 0;
 112 };
 113
 114 /**
 115  * AudioStreamIn is the abstraction interface for the audio input hardware.
 116  *
 117  * It defines the various properties of the audio hardware input driver.
 118  */
 119 class AudioStreamIn {
 120 public:
 121     virtual             ~AudioStreamIn() = 0;
 122
 123     /** return audio sampling rate in hz - eg. 44100 */
 124     virtual uint32_t    sampleRate() const = 0;
 125
 126     /** return the input buffer size allowed by audio driver */
 127     virtual size_t      bufferSize() const = 0;
 128
 129     /** return input channel mask */
 130     virtual uint32_t    channels() const = 0;
 131
 132     /**
 133      * return audio format in 8bit or 16bit PCM format -
 134      * eg. AudioSystem:PCM_16_BIT
 135      */
 136     virtual int         format() const = 0;
 137
 138     /**
 139      * return the frame size (number of bytes per sample).
 140      */
 141     uint32_t    frameSize() const { return AudioSystem::popCount(channels())*((format()==AudioSystem::PCM_16_BIT)?sizeof(int16_t):sizeof(int8_t)); }
 142
 143     /** set the input gain for the audio driver. This method is for
 144      *  for future use */
 145     virtual status_t    setGain(float gain) = 0;
 146
 147     /** read audio buffer in from audio driver */
 148     virtual ssize_t     read(void* buffer, ssize_t bytes) = 0;
 149
 150     /** dump the state of the audio input device */
 151     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 152
 153     /**
 154      * Put the audio hardware input into standby mode. Returns
 155      * status based on include/utils/Errors.h
 156      */
 157     virtual status_t    standby() = 0;
 158
 159     // set/get audio input parameters. The function accepts a list of parameters
 160     // key value pairs in the form: key1=value1;key2=value2;...
 161     // Some keys are reserved for standard parameters (See AudioParameter class).
 162     // If the implementation does not accept a parameter change while the output is
 163     // active but the parameter is acceptable otherwise, it must return INVALID_OPERATION.
 164     // The audio flinger will put the input in standby and then change the parameter value.
 165     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 166     virtual String8     getParameters(const String8& keys) = 0;
 167
 168
 169     // Return the amount of input frames lost in the audio driver since the last call of this function.
 170     // Audio driver is expected to reset the value to 0 and restart counting upon returning the current value by this function call.
 171     // Such loss typically occurs when the user space process is blocked longer than the capacity of audio driver buffers.
 172     // Unit: the number of input audio frames
 173     virtual unsigned int  getInputFramesLost() const = 0;
 174
 175     virtual status_t addAudioEffect(effect_handle_t effect) = 0;
 176     virtual status_t removeAudioEffect(effect_handle_t effect) = 0;
 177 };
 178
 179 /**
 180  * AudioHardwareInterface.h defines the interface to the audio hardware abstraction layer.
 181  *
 182  * The interface supports setting and getting parameters, selecting audio routing
 183  * paths, and defining input and output streams.
 184  *
 185  * AudioFlinger initializes the audio hardware and immediately opens an output stream.
 186  * You can set Audio routing to output to handset, speaker, Bluetooth, or a headset.
 187  *
 188  * The audio input stream is initialized when AudioFlinger is called to carry out
 189  * a record operation.
 190  */
 191 class AudioHardwareInterface
 192 {
 193 public:
 194     virtual ~AudioHardwareInterface() {}
 195
 196     /**
 197      * check to see if the audio hardware interface has been initialized.
 198      * return status based on values defined in include/utils/Errors.h
 199      */
 200     virtual status_t    initCheck() = 0;
 201
 202     /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
 203     virtual status_t    setVoiceVolume(float volume) = 0;
 204
 205     /**
 206      * set the audio volume for all audio activities other than voice call.
 207      * Range between 0.0 and 1.0. If any value other than NO_ERROR is returned,
 208      * the software mixer will emulate this capability.
 209      */
 210     virtual status_t    setMasterVolume(float volume) = 0;
 211
 212     /**
 213      * setMode is called when the audio mode changes. NORMAL mode is for
 214      * standard audio playback, RINGTONE when a ringtone is playing, and IN_CALL
 215      * when a call is in progress.
 216      */
 217     virtual status_t    setMode(int mode) = 0;
 218
 219     // mic mute
 220     virtual status_t    setMicMute(bool state) = 0;
 221     virtual status_t    getMicMute(bool* state) = 0;
 222
 223     // set/get global audio parameters
 224     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 225     virtual String8     getParameters(const String8& keys) = 0;
 226
 227     // Returns audio input buffer size according to parameters passed or 0 if one of the
 228     // parameters is not supported
 229     virtual size_t    getInputBufferSize(uint32_t sampleRate, int format, int channelCount) = 0;
 230
 231     /** This method creates and opens the audio hardware output stream */
 232     virtual AudioStreamOut* openOutputStream(
 233                                 uint32_t devices,
 234                                 int *format=0,
 235                                 uint32_t *channels=0,
 236                                 uint32_t *sampleRate=0,
 237                                 status_t *status=0) = 0;
 238     virtual    void        closeOutputStream(AudioStreamOut* out) = 0;
 239     /** This method creates and opens the audio hardware input stream */
 240     virtual AudioStreamIn* openInputStream(
 241                                 uint32_t devices,
 242                                 int *format,
 243                                 uint32_t *channels,
 244                                 uint32_t *sampleRate,
 245                                 status_t *status,
 246                                 AudioSystem::audio_in_acoustics acoustics) = 0;
 247     virtual    void        closeInputStream(AudioStreamIn* in) = 0;
 248
 249     /**This method dumps the state of the audio hardware */
 250     virtual status_t dumpState(int fd, const Vector<String16>& args) = 0;
 251
 252     static AudioHardwareInterface* create();
 253
 254 protected:
 255
 256     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 257 };
 258
 259 // ----------------------------------------------------------------------------
 260
 261 extern "C" AudioHardwareInterface* createAudioHardware(void);
 262
 263 }; // namespace android
 264
 265 #endif // ANDROID_AUDIO_HARDWARE_INTERFACE_H