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 mask
  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 audio_channel_count_from_out_mask(channels())*
  73                             ((format()==AUDIO_FORMAT_PCM_16_BIT)?sizeof(int16_t):sizeof(int8_t)); }
  74
  75     /**
  76      * return the audio hardware driver latency in milli seconds.
  77      */
  78     virtual uint32_t    latency() const = 0;
  79
  80     /**
  81      * Use this method in situations where audio mixing is done in the
  82      * hardware. This method serves as a direct interface with hardware,
  83      * allowing you to directly set the volume as apposed to via the framework.
  84      * This method might produce multiple PCM outputs or hardware accelerated
  85      * codecs, such as MP3 or AAC.
  86      */
  87     virtual status_t    setVolume(float left, float right) = 0;
  88
  89     /** write audio buffer to driver. Returns number of bytes written */
  90     virtual ssize_t     write(const void* buffer, size_t bytes) = 0;
  91
  92     /**
  93      * Put the audio hardware output into standby mode. Returns
  94      * status based on include/utils/Errors.h
  95      */
  96     virtual status_t    standby() = 0;
  97
  98     /** dump the state of the audio output device */
  99     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 100
 101     // set/get audio output parameters. The function accepts a list of parameters
 102     // key value pairs in the form: key1=value1;key2=value2;...
 103     // Some keys are reserved for standard parameters (See AudioParameter class).
 104     // If the implementation does not accept a parameter change while the output is
 105     // active but the parameter is acceptable otherwise, it must return INVALID_OPERATION.
 106     // The audio flinger will put the output in standby and then change the parameter value.
 107     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 108     virtual String8     getParameters(const String8& keys) = 0;
 109
 110     // return the number of audio frames written by the audio dsp to DAC since
 111     // the output has exited standby
 112     virtual status_t    getRenderPosition(uint32_t *dspFrames) = 0;
 113
 114     /**
 115      * get the local time at which the next write to the audio driver will be
 116      * presented
 117      */
 118     virtual status_t    getNextWriteTimestamp(int64_t *timestamp);
 119
 120 };
 121
 122 /**
 123  * AudioStreamIn is the abstraction interface for the audio input hardware.
 124  *
 125  * It defines the various properties of the audio hardware input driver.
 126  */
 127 class AudioStreamIn {
 128 public:
 129     virtual             ~AudioStreamIn() = 0;
 130
 131     /** return audio sampling rate in hz - eg. 44100 */
 132     virtual uint32_t    sampleRate() const = 0;
 133
 134     /** return the input buffer size allowed by audio driver */
 135     virtual size_t      bufferSize() const = 0;
 136
 137     /** return input channel mask */
 138     virtual uint32_t    channels() const = 0;
 139
 140     /**
 141      * return audio format in 8bit or 16bit PCM format -
 142      * eg. AudioSystem:PCM_16_BIT
 143      */
 144     virtual int         format() const = 0;
 145
 146     /**
 147      * return the frame size (number of bytes per sample).
 148      */
 149     uint32_t    frameSize() const { return audio_channel_count_from_in_mask(channels())*
 150                             ((format()==AudioSystem::PCM_16_BIT)?sizeof(int16_t):sizeof(int8_t)); }
 151
 152     /** set the input gain for the audio driver. This method is for
 153      *  for future use */
 154     virtual status_t    setGain(float gain) = 0;
 155
 156     /** read audio buffer in from audio driver */
 157     virtual ssize_t     read(void* buffer, ssize_t bytes) = 0;
 158
 159     /** dump the state of the audio input device */
 160     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 161
 162     /**
 163      * Put the audio hardware input into standby mode. Returns
 164      * status based on include/utils/Errors.h
 165      */
 166     virtual status_t    standby() = 0;
 167
 168     // set/get audio input parameters. The function accepts a list of parameters
 169     // key value pairs in the form: key1=value1;key2=value2;...
 170     // Some keys are reserved for standard parameters (See AudioParameter class).
 171     // If the implementation does not accept a parameter change while the output is
 172     // active but the parameter is acceptable otherwise, it must return INVALID_OPERATION.
 173     // The audio flinger will put the input in standby and then change the parameter value.
 174     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 175     virtual String8     getParameters(const String8& keys) = 0;
 176
 177
 178     // Return the number of input frames lost in the audio driver since the last call of this function.
 179     // Audio driver is expected to reset the value to 0 and restart counting upon returning the current value by this function call.
 180     // Such loss typically occurs when the user space process is blocked longer than the capacity of audio driver buffers.
 181     // Unit: the number of input audio frames
 182     virtual unsigned int  getInputFramesLost() const = 0;
 183
 184     virtual status_t addAudioEffect(effect_handle_t effect) = 0;
 185     virtual status_t removeAudioEffect(effect_handle_t effect) = 0;
 186 };
 187
 188 /**
 189  * AudioHardwareInterface.h defines the interface to the audio hardware abstraction layer.
 190  *
 191  * The interface supports setting and getting parameters, selecting audio routing
 192  * paths, and defining input and output streams.
 193  *
 194  * AudioFlinger initializes the audio hardware and immediately opens an output stream.
 195  * You can set Audio routing to output to handset, speaker, Bluetooth, or a headset.
 196  *
 197  * The audio input stream is initialized when AudioFlinger is called to carry out
 198  * a record operation.
 199  */
 200 class AudioHardwareInterface
 201 {
 202 public:
 203     virtual ~AudioHardwareInterface() {}
 204
 205     /**
 206      * check to see if the audio hardware interface has been initialized.
 207      * return status based on values defined in include/utils/Errors.h
 208      */
 209     virtual status_t    initCheck() = 0;
 210
 211     /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
 212     virtual status_t    setVoiceVolume(float volume) = 0;
 213
 214     /**
 215      * set the audio volume for all audio activities other than voice call.
 216      * Range between 0.0 and 1.0. If any value other than NO_ERROR is returned,
 217      * the software mixer will emulate this capability.
 218      */
 219     virtual status_t    setMasterVolume(float volume) = 0;
 220
 221     /**
 222      * Get the current master volume value for the HAL, if the HAL supports
 223      * master volume control.  AudioFlinger will query this value from the
 224      * primary audio HAL when the service starts and use the value for setting
 225      * the initial master volume across all HALs.
 226      */
 227     virtual status_t    getMasterVolume(float *volume) = 0;
 228
 229     /**
 230      * setMode is called when the audio mode changes. NORMAL mode is for
 231      * standard audio playback, RINGTONE when a ringtone is playing, and IN_CALL
 232      * when a call is in progress.
 233      */
 234     virtual status_t    setMode(int mode) = 0;
 235
 236     // mic mute
 237     virtual status_t    setMicMute(bool state) = 0;
 238     virtual status_t    getMicMute(bool* state) = 0;
 239
 240     // set/get global audio parameters
 241     virtual status_t    setParameters(const String8& keyValuePairs) = 0;
 242     virtual String8     getParameters(const String8& keys) = 0;
 243
 244     // Returns audio input buffer size according to parameters passed or 0 if one of the
 245     // parameters is not supported
 246     virtual size_t    getInputBufferSize(uint32_t sampleRate, int format, int channelCount) = 0;
 247
 248     /** This method creates and opens the audio hardware output stream */
 249     virtual AudioStreamOut* openOutputStream(
 250                                 uint32_t devices,
 251                                 int *format=0,
 252                                 uint32_t *channels=0,
 253                                 uint32_t *sampleRate=0,
 254                                 status_t *status=0) = 0;
 255     virtual AudioStreamOut* openOutputStreamWithFlags(
 256                                 uint32_t devices,
 257                                 audio_output_flags_t flags=(audio_output_flags_t)0,
 258                                 int *format=0,
 259                                 uint32_t *channels=0,
 260                                 uint32_t *sampleRate=0,
 261                                 status_t *status=0) = 0;
 262     virtual    void        closeOutputStream(AudioStreamOut* out) = 0;
 263
 264     /** This method creates and opens the audio hardware input stream */
 265     virtual AudioStreamIn* openInputStream(
 266                                 uint32_t devices,
 267                                 int *format,
 268                                 uint32_t *channels,
 269                                 uint32_t *sampleRate,
 270                                 status_t *status,
 271                                 AudioSystem::audio_in_acoustics acoustics) = 0;
 272     virtual    void        closeInputStream(AudioStreamIn* in) = 0;
 273
 274     /**This method dumps the state of the audio hardware */
 275     virtual status_t dumpState(int fd, const Vector<String16>& args) = 0;
 276
 277     static AudioHardwareInterface* create();
 278
 279 protected:
 280
 281     virtual status_t dump(int fd, const Vector<String16>& args) = 0;
 282 };
 283
 284 // ----------------------------------------------------------------------------
 285
 286 extern "C" AudioHardwareInterface* createAudioHardware(void);
 287
 288 }; // namespace android
 289
 290 #endif // ANDROID_AUDIO_HARDWARE_INTERFACE_H