audio/include/system/audio.h

   1 /*
   2  * Copyright (C) 2011 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
  18 #ifndef ANDROID_AUDIO_CORE_H
  19 #define ANDROID_AUDIO_CORE_H
  20
  21 #include <stdbool.h>
  22 #include <stdint.h>
  23 #include <stdio.h>
  24 #include <sys/cdefs.h>
  25 #include <sys/types.h>
  26
  27 #include <cutils/bitops.h>
  28
  29 __BEGIN_DECLS
  30
  31 /* The macro FCC_2 highlights places where there are 2-channel assumptions.
  32  * This is typically due to legacy implementation of stereo input or output.
  33  * Search also for "2", "left", "right", "[0]", "[1]", ">> 16", "<< 16", etc.
  34  * Do not change this value.
  35  */
  36 #define FCC_2 2     // FCC_2 = Fixed Channel Count 2
  37
  38 /* The macro FCC_8 highlights places where there are 8-channel assumptions.
  39  * This is typically due to audio mixer and resampler limitations.
  40  * Do not change this value without verifying all locations that use it.
  41  */
  42 #define FCC_8 8     // FCC_8 = Fixed Channel Count 8
  43
  44 /* The enums were moved here mostly from
  45  * frameworks/base/include/media/AudioSystem.h
  46  */
  47
  48 /* device address used to refer to the standard remote submix */
  49 #define AUDIO_REMOTE_SUBMIX_DEVICE_ADDRESS "0"
  50
  51 /* AudioFlinger and AudioPolicy services use I/O handles to identify audio sources and sinks */
  52 typedef int audio_io_handle_t;
  53 #define AUDIO_IO_HANDLE_NONE    0
  54
  55 /* Audio stream types */
  56 typedef enum {
  57     /* These values must kept in sync with
  58      * frameworks/base/media/java/android/media/AudioSystem.java
  59      */
  60     AUDIO_STREAM_DEFAULT          = -1,
  61     AUDIO_STREAM_MIN              = 0,
  62     AUDIO_STREAM_VOICE_CALL       = 0,
  63     AUDIO_STREAM_SYSTEM           = 1,
  64     AUDIO_STREAM_RING             = 2,
  65     AUDIO_STREAM_MUSIC            = 3,
  66     AUDIO_STREAM_ALARM            = 4,
  67     AUDIO_STREAM_NOTIFICATION     = 5,
  68     AUDIO_STREAM_BLUETOOTH_SCO    = 6,
  69     AUDIO_STREAM_ENFORCED_AUDIBLE = 7, /* Sounds that cannot be muted by user
  70                                         * and must be routed to speaker
  71                                         */
  72     AUDIO_STREAM_DTMF             = 8,
  73     AUDIO_STREAM_TTS              = 9,  /* Transmitted Through Speaker.
  74                                          * Plays over speaker only, silent on other devices.
  75                                          */
  76     AUDIO_STREAM_ACCESSIBILITY    = 10, /* For accessibility talk back prompts */
  77     AUDIO_STREAM_REROUTING        = 11, /* For dynamic policy output mixes */
  78     AUDIO_STREAM_PATCH            = 12, /* For internal audio flinger tracks. Fixed volume */
  79     AUDIO_STREAM_PUBLIC_CNT       = AUDIO_STREAM_TTS + 1,
  80     AUDIO_STREAM_FOR_POLICY_CNT   = AUDIO_STREAM_PATCH, /* number of streams considered by
  81                                            audio policy for volume and routing */
  82     AUDIO_STREAM_CNT              = AUDIO_STREAM_PATCH + 1,
  83 } audio_stream_type_t;
  84
  85 /* Do not change these values without updating their counterparts
  86  * in frameworks/base/media/java/android/media/AudioAttributes.java
  87  */
  88 typedef enum {
  89     AUDIO_CONTENT_TYPE_UNKNOWN      = 0,
  90     AUDIO_CONTENT_TYPE_SPEECH       = 1,
  91     AUDIO_CONTENT_TYPE_MUSIC        = 2,
  92     AUDIO_CONTENT_TYPE_MOVIE        = 3,
  93     AUDIO_CONTENT_TYPE_SONIFICATION = 4,
  94
  95     AUDIO_CONTENT_TYPE_CNT,
  96     AUDIO_CONTENT_TYPE_MAX          = AUDIO_CONTENT_TYPE_CNT - 1,
  97 } audio_content_type_t;
  98
  99 /* Do not change these values without updating their counterparts
 100  * in frameworks/base/media/java/android/media/AudioAttributes.java
 101  */
 102 typedef enum {
 103     AUDIO_USAGE_UNKNOWN                            = 0,
 104     AUDIO_USAGE_MEDIA                              = 1,
 105     AUDIO_USAGE_VOICE_COMMUNICATION                = 2,
 106     AUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING     = 3,
 107     AUDIO_USAGE_ALARM                              = 4,
 108     AUDIO_USAGE_NOTIFICATION                       = 5,
 109     AUDIO_USAGE_NOTIFICATION_TELEPHONY_RINGTONE    = 6,
 110     AUDIO_USAGE_NOTIFICATION_COMMUNICATION_REQUEST = 7,
 111     AUDIO_USAGE_NOTIFICATION_COMMUNICATION_INSTANT = 8,
 112     AUDIO_USAGE_NOTIFICATION_COMMUNICATION_DELAYED = 9,
 113     AUDIO_USAGE_NOTIFICATION_EVENT                 = 10,
 114     AUDIO_USAGE_ASSISTANCE_ACCESSIBILITY           = 11,
 115     AUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE     = 12,
 116     AUDIO_USAGE_ASSISTANCE_SONIFICATION            = 13,
 117     AUDIO_USAGE_GAME                               = 14,
 118     AUDIO_USAGE_VIRTUAL_SOURCE                     = 15,
 119
 120     AUDIO_USAGE_CNT,
 121     AUDIO_USAGE_MAX                                = AUDIO_USAGE_CNT - 1,
 122 } audio_usage_t;
 123
 124 typedef uint32_t audio_flags_mask_t;
 125
 126 /* Do not change these values without updating their counterparts
 127  * in frameworks/base/media/java/android/media/AudioAttributes.java
 128  */
 129 enum {
 130     AUDIO_FLAG_AUDIBILITY_ENFORCED        = 0x1,
 131     AUDIO_FLAG_SECURE                     = 0x2,
 132     AUDIO_FLAG_SCO                        = 0x4,
 133     AUDIO_FLAG_BEACON                     = 0x8,
 134     AUDIO_FLAG_HW_AV_SYNC                 = 0x10,
 135     AUDIO_FLAG_HW_HOTWORD                 = 0x20,
 136     AUDIO_FLAG_BYPASS_INTERRUPTION_POLICY = 0x40,
 137     AUDIO_FLAG_BYPASS_MUTE                = 0x80,
 138     AUDIO_FLAG_LOW_LATENCY                = 0x100,
 139 };
 140
 141 /* Do not change these values without updating their counterparts
 142  * in frameworks/base/media/java/android/media/MediaRecorder.java,
 143  * frameworks/av/services/audiopolicy/AudioPolicyService.cpp,
 144  * and system/media/audio_effects/include/audio_effects/audio_effects_conf.h!
 145  */
 146 typedef enum {
 147     AUDIO_SOURCE_DEFAULT             = 0,
 148     AUDIO_SOURCE_MIC                 = 1,
 149     AUDIO_SOURCE_VOICE_UPLINK        = 2,
 150     AUDIO_SOURCE_VOICE_DOWNLINK      = 3,
 151     AUDIO_SOURCE_VOICE_CALL          = 4,
 152     AUDIO_SOURCE_CAMCORDER           = 5,
 153     AUDIO_SOURCE_VOICE_RECOGNITION   = 6,
 154     AUDIO_SOURCE_VOICE_COMMUNICATION = 7,
 155     AUDIO_SOURCE_REMOTE_SUBMIX       = 8, /* Source for the mix to be presented remotely.      */
 156                                           /* An example of remote presentation is Wifi Display */
 157                                           /*  where a dongle attached to a TV can be used to   */
 158                                           /*  play the mix captured by this audio source.      */
 159     AUDIO_SOURCE_UNPROCESSED         = 9, /* Source for unprocessed sound.
 160                                              Usage examples include level measurement and raw
 161                                              signal analysis. */
 162     AUDIO_SOURCE_CNT,
 163     AUDIO_SOURCE_MAX                 = AUDIO_SOURCE_CNT - 1,
 164     AUDIO_SOURCE_FM_TUNER            = 1998,
 165     AUDIO_SOURCE_HOTWORD             = 1999, /* A low-priority, preemptible audio source for
 166                                                 for background software hotword detection.
 167                                                 Same tuning as AUDIO_SOURCE_VOICE_RECOGNITION.
 168                                                 Used only internally to the framework. Not exposed
 169                                                 at the audio HAL. */
 170 } audio_source_t;
 171
 172 /* Audio attributes */
 173 #define AUDIO_ATTRIBUTES_TAGS_MAX_SIZE 256
 174 typedef struct {
 175     audio_content_type_t content_type;
 176     audio_usage_t        usage;
 177     audio_source_t       source;
 178     audio_flags_mask_t   flags;
 179     char                 tags[AUDIO_ATTRIBUTES_TAGS_MAX_SIZE]; /* UTF8 */
 180 } audio_attributes_t;
 181
 182 /* special audio session values
 183  * do not need to have audio_unique_id_get_use(session) == AUDIO_UNIQUE_ID_USE_SESSION
 184  * (XXX: should this be living in the audio effects land?)
 185  */
 186 typedef enum {
 187     /* session for effects attached to a particular output stream
 188      * (value must be less than 0)
 189      */
 190     AUDIO_SESSION_OUTPUT_STAGE = -1,
 191
 192     /* session for effects applied to output mix. These effects can
 193      * be moved by audio policy manager to another output stream
 194      * (value must be 0)
 195      */
 196     AUDIO_SESSION_OUTPUT_MIX = 0,
 197
 198     /* application does not specify an explicit session ID to be used,
 199      * and requests a new session ID to be allocated
 200      * TODO use unique values for AUDIO_SESSION_OUTPUT_MIX and AUDIO_SESSION_ALLOCATE,
 201      * after all uses have been updated from 0 to the appropriate symbol, and have been tested.
 202      * Corresponds to AudioManager.AUDIO_SESSION_ID_GENERATE and AudioSystem.AUDIO_SESSION_ALLOCATE.
 203      */
 204     AUDIO_SESSION_ALLOCATE = 0,
 205
 206     /* For use with AudioRecord::start(), this indicates no trigger session.
 207      * It is also used with output tracks and patch tracks, which never have a session.
 208      */
 209     AUDIO_SESSION_NONE = 0,
 210 } audio_session_t;
 211
 212 /* a unique ID allocated by AudioFlinger for use as an audio_io_handle_t, audio_session_t,
 213  * effect ID (int), audio_module_handle_t, and audio_patch_handle_t.
 214  * Audio port IDs (audio_port_handle_t) are allocated by AudioPolicy
 215  * in a different namespace than AudioFlinger unique IDs.
 216  */
 217 typedef int audio_unique_id_t;
 218
 219 /* Possible uses for an audio_unique_id_t */
 220 typedef enum {
 221     AUDIO_UNIQUE_ID_USE_UNSPECIFIED = 0,
 222     AUDIO_UNIQUE_ID_USE_SESSION = 1,    // for allocated sessions, not special AUDIO_SESSION_*
 223     AUDIO_UNIQUE_ID_USE_MODULE = 2,
 224     AUDIO_UNIQUE_ID_USE_EFFECT = 3,
 225     AUDIO_UNIQUE_ID_USE_PATCH = 4,
 226     AUDIO_UNIQUE_ID_USE_OUTPUT = 5,
 227     AUDIO_UNIQUE_ID_USE_INPUT = 6,
 228     // 7 is available
 229     AUDIO_UNIQUE_ID_USE_MAX = 8,  // must be a power-of-two
 230     AUDIO_UNIQUE_ID_USE_MASK = AUDIO_UNIQUE_ID_USE_MAX - 1
 231 } audio_unique_id_use_t;
 232
 233 /* Return the use of an audio_unique_id_t */
 234 static inline audio_unique_id_use_t audio_unique_id_get_use(audio_unique_id_t id)
 235 {
 236     return (audio_unique_id_use_t) (id & AUDIO_UNIQUE_ID_USE_MASK);
 237 }
 238
 239 /* Reserved audio_unique_id_t values.  FIXME: not a complete list. */
 240 #define AUDIO_UNIQUE_ID_ALLOCATE AUDIO_SESSION_ALLOCATE
 241
 242 /* Audio sub formats (see enum audio_format). */
 243
 244 /* PCM sub formats */
 245 typedef enum {
 246     /* All of these are in native byte order */
 247     AUDIO_FORMAT_PCM_SUB_16_BIT          = 0x1, /* DO NOT CHANGE - PCM signed 16 bits */
 248     AUDIO_FORMAT_PCM_SUB_8_BIT           = 0x2, /* DO NOT CHANGE - PCM unsigned 8 bits */
 249     AUDIO_FORMAT_PCM_SUB_32_BIT          = 0x3, /* PCM signed .31 fixed point */
 250     AUDIO_FORMAT_PCM_SUB_8_24_BIT        = 0x4, /* PCM signed 8.23 fixed point */
 251     AUDIO_FORMAT_PCM_SUB_FLOAT           = 0x5, /* PCM single-precision floating point */
 252     AUDIO_FORMAT_PCM_SUB_24_BIT_PACKED   = 0x6, /* PCM signed .23 fixed point packed in 3 bytes */
 253 } audio_format_pcm_sub_fmt_t;
 254
 255 /* The audio_format_*_sub_fmt_t declarations are not currently used */
 256
 257 /* MP3 sub format field definition : can use 11 LSBs in the same way as MP3
 258  * frame header to specify bit rate, stereo mode, version...
 259  */
 260 typedef enum {
 261     AUDIO_FORMAT_MP3_SUB_NONE            = 0x0,
 262 } audio_format_mp3_sub_fmt_t;
 263
 264 /* AMR NB/WB sub format field definition: specify frame block interleaving,
 265  * bandwidth efficient or octet aligned, encoding mode for recording...
 266  */
 267 typedef enum {
 268     AUDIO_FORMAT_AMR_SUB_NONE            = 0x0,
 269 } audio_format_amr_sub_fmt_t;
 270
 271 /* AAC sub format field definition: specify profile or bitrate for recording... */
 272 typedef enum {
 273     AUDIO_FORMAT_AAC_SUB_MAIN            = 0x1,
 274     AUDIO_FORMAT_AAC_SUB_LC              = 0x2,
 275     AUDIO_FORMAT_AAC_SUB_SSR             = 0x4,
 276     AUDIO_FORMAT_AAC_SUB_LTP             = 0x8,
 277     AUDIO_FORMAT_AAC_SUB_HE_V1           = 0x10,
 278     AUDIO_FORMAT_AAC_SUB_SCALABLE        = 0x20,
 279     AUDIO_FORMAT_AAC_SUB_ERLC            = 0x40,
 280     AUDIO_FORMAT_AAC_SUB_LD              = 0x80,
 281     AUDIO_FORMAT_AAC_SUB_HE_V2           = 0x100,
 282     AUDIO_FORMAT_AAC_SUB_ELD             = 0x200,
 283 } audio_format_aac_sub_fmt_t;
 284
 285 /* VORBIS sub format field definition: specify quality for recording... */
 286 typedef enum {
 287     AUDIO_FORMAT_VORBIS_SUB_NONE         = 0x0,
 288 } audio_format_vorbis_sub_fmt_t;
 289
 290
 291 /* Audio format  is a 32-bit word that consists of:
 292  *   main format field (upper 8 bits)
 293  *   sub format field (lower 24 bits).
 294  *
 295  * The main format indicates the main codec type. The sub format field
 296  * indicates options and parameters for each format. The sub format is mainly
 297  * used for record to indicate for instance the requested bitrate or profile.
 298  * It can also be used for certain formats to give informations not present in
 299  * the encoded audio stream (e.g. octet alignement for AMR).
 300  */
 301 typedef enum {
 302     AUDIO_FORMAT_INVALID             = 0xFFFFFFFFUL,
 303     AUDIO_FORMAT_DEFAULT             = 0,
 304     AUDIO_FORMAT_PCM                 = 0x00000000UL, /* DO NOT CHANGE */
 305     AUDIO_FORMAT_MP3                 = 0x01000000UL,
 306     AUDIO_FORMAT_AMR_NB              = 0x02000000UL,
 307     AUDIO_FORMAT_AMR_WB              = 0x03000000UL,
 308     AUDIO_FORMAT_AAC                 = 0x04000000UL,
 309     AUDIO_FORMAT_HE_AAC_V1           = 0x05000000UL, /* Deprecated, Use AUDIO_FORMAT_AAC_HE_V1*/
 310     AUDIO_FORMAT_HE_AAC_V2           = 0x06000000UL, /* Deprecated, Use AUDIO_FORMAT_AAC_HE_V2*/
 311     AUDIO_FORMAT_VORBIS              = 0x07000000UL,
 312     AUDIO_FORMAT_OPUS                = 0x08000000UL,
 313     AUDIO_FORMAT_AC3                 = 0x09000000UL,
 314     AUDIO_FORMAT_E_AC3               = 0x0A000000UL,
 315     AUDIO_FORMAT_DTS                 = 0x0B000000UL,
 316     AUDIO_FORMAT_DTS_HD              = 0x0C000000UL,
 317     // IEC61937 is encoded audio wrapped in 16-bit PCM.
 318     AUDIO_FORMAT_IEC61937            = 0x0D000000UL,
 319     AUDIO_FORMAT_DOLBY_TRUEHD        = 0x0E000000UL,
 320     AUDIO_FORMAT_MAIN_MASK           = 0xFF000000UL, /* Deprecated. Use audio_get_main_format() */
 321     AUDIO_FORMAT_SUB_MASK            = 0x00FFFFFFUL,
 322
 323     /* Aliases */
 324     /* note != AudioFormat.ENCODING_PCM_16BIT */
 325     AUDIO_FORMAT_PCM_16_BIT          = (AUDIO_FORMAT_PCM |
 326                                         AUDIO_FORMAT_PCM_SUB_16_BIT),
 327     /* note != AudioFormat.ENCODING_PCM_8BIT */
 328     AUDIO_FORMAT_PCM_8_BIT           = (AUDIO_FORMAT_PCM |
 329                                         AUDIO_FORMAT_PCM_SUB_8_BIT),
 330     AUDIO_FORMAT_PCM_32_BIT          = (AUDIO_FORMAT_PCM |
 331                                         AUDIO_FORMAT_PCM_SUB_32_BIT),
 332     AUDIO_FORMAT_PCM_8_24_BIT        = (AUDIO_FORMAT_PCM |
 333                                         AUDIO_FORMAT_PCM_SUB_8_24_BIT),
 334     AUDIO_FORMAT_PCM_FLOAT           = (AUDIO_FORMAT_PCM |
 335                                         AUDIO_FORMAT_PCM_SUB_FLOAT),
 336     AUDIO_FORMAT_PCM_24_BIT_PACKED   = (AUDIO_FORMAT_PCM |
 337                                         AUDIO_FORMAT_PCM_SUB_24_BIT_PACKED),
 338     AUDIO_FORMAT_AAC_MAIN            = (AUDIO_FORMAT_AAC |
 339                                         AUDIO_FORMAT_AAC_SUB_MAIN),
 340     AUDIO_FORMAT_AAC_LC              = (AUDIO_FORMAT_AAC |
 341                                         AUDIO_FORMAT_AAC_SUB_LC),
 342     AUDIO_FORMAT_AAC_SSR             = (AUDIO_FORMAT_AAC |
 343                                         AUDIO_FORMAT_AAC_SUB_SSR),
 344     AUDIO_FORMAT_AAC_LTP             = (AUDIO_FORMAT_AAC |
 345                                         AUDIO_FORMAT_AAC_SUB_LTP),
 346     AUDIO_FORMAT_AAC_HE_V1           = (AUDIO_FORMAT_AAC |
 347                                         AUDIO_FORMAT_AAC_SUB_HE_V1),
 348     AUDIO_FORMAT_AAC_SCALABLE        = (AUDIO_FORMAT_AAC |
 349                                         AUDIO_FORMAT_AAC_SUB_SCALABLE),
 350     AUDIO_FORMAT_AAC_ERLC            = (AUDIO_FORMAT_AAC |
 351                                         AUDIO_FORMAT_AAC_SUB_ERLC),
 352     AUDIO_FORMAT_AAC_LD              = (AUDIO_FORMAT_AAC |
 353                                         AUDIO_FORMAT_AAC_SUB_LD),
 354     AUDIO_FORMAT_AAC_HE_V2           = (AUDIO_FORMAT_AAC |
 355                                         AUDIO_FORMAT_AAC_SUB_HE_V2),
 356     AUDIO_FORMAT_AAC_ELD             = (AUDIO_FORMAT_AAC |
 357                                         AUDIO_FORMAT_AAC_SUB_ELD),
 358 } audio_format_t;
 359
 360 /* For the channel mask for position assignment representation */
 361 enum {
 362
 363 /* These can be a complete audio_channel_mask_t. */
 364
 365     AUDIO_CHANNEL_NONE                      = 0x0,
 366     AUDIO_CHANNEL_INVALID                   = 0xC0000000,
 367
 368 /* These can be the bits portion of an audio_channel_mask_t
 369  * with representation AUDIO_CHANNEL_REPRESENTATION_POSITION.
 370  * Using these bits as a complete audio_channel_mask_t is deprecated.
 371  */
 372
 373     /* output channels */
 374     AUDIO_CHANNEL_OUT_FRONT_LEFT            = 0x1,
 375     AUDIO_CHANNEL_OUT_FRONT_RIGHT           = 0x2,
 376     AUDIO_CHANNEL_OUT_FRONT_CENTER          = 0x4,
 377     AUDIO_CHANNEL_OUT_LOW_FREQUENCY         = 0x8,
 378     AUDIO_CHANNEL_OUT_BACK_LEFT             = 0x10,
 379     AUDIO_CHANNEL_OUT_BACK_RIGHT            = 0x20,
 380     AUDIO_CHANNEL_OUT_FRONT_LEFT_OF_CENTER  = 0x40,
 381     AUDIO_CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = 0x80,
 382     AUDIO_CHANNEL_OUT_BACK_CENTER           = 0x100,
 383     AUDIO_CHANNEL_OUT_SIDE_LEFT             = 0x200,
 384     AUDIO_CHANNEL_OUT_SIDE_RIGHT            = 0x400,
 385     AUDIO_CHANNEL_OUT_TOP_CENTER            = 0x800,
 386     AUDIO_CHANNEL_OUT_TOP_FRONT_LEFT        = 0x1000,
 387     AUDIO_CHANNEL_OUT_TOP_FRONT_CENTER      = 0x2000,
 388     AUDIO_CHANNEL_OUT_TOP_FRONT_RIGHT       = 0x4000,
 389     AUDIO_CHANNEL_OUT_TOP_BACK_LEFT         = 0x8000,
 390     AUDIO_CHANNEL_OUT_TOP_BACK_CENTER       = 0x10000,
 391     AUDIO_CHANNEL_OUT_TOP_BACK_RIGHT        = 0x20000,
 392
 393 /* TODO: should these be considered complete channel masks, or only bits? */
 394
 395     AUDIO_CHANNEL_OUT_MONO     = AUDIO_CHANNEL_OUT_FRONT_LEFT,
 396     AUDIO_CHANNEL_OUT_STEREO   = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 397                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT),
 398     AUDIO_CHANNEL_OUT_QUAD     = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 399                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 400                                   AUDIO_CHANNEL_OUT_BACK_LEFT |
 401                                   AUDIO_CHANNEL_OUT_BACK_RIGHT),
 402     AUDIO_CHANNEL_OUT_QUAD_BACK = AUDIO_CHANNEL_OUT_QUAD,
 403     /* like AUDIO_CHANNEL_OUT_QUAD_BACK with *_SIDE_* instead of *_BACK_* */
 404     AUDIO_CHANNEL_OUT_QUAD_SIDE = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 405                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 406                                   AUDIO_CHANNEL_OUT_SIDE_LEFT |
 407                                   AUDIO_CHANNEL_OUT_SIDE_RIGHT),
 408     AUDIO_CHANNEL_OUT_5POINT1  = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 409                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 410                                   AUDIO_CHANNEL_OUT_FRONT_CENTER |
 411                                   AUDIO_CHANNEL_OUT_LOW_FREQUENCY |
 412                                   AUDIO_CHANNEL_OUT_BACK_LEFT |
 413                                   AUDIO_CHANNEL_OUT_BACK_RIGHT),
 414     AUDIO_CHANNEL_OUT_5POINT1_BACK = AUDIO_CHANNEL_OUT_5POINT1,
 415     /* like AUDIO_CHANNEL_OUT_5POINT1_BACK with *_SIDE_* instead of *_BACK_* */
 416     AUDIO_CHANNEL_OUT_5POINT1_SIDE = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 417                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 418                                   AUDIO_CHANNEL_OUT_FRONT_CENTER |
 419                                   AUDIO_CHANNEL_OUT_LOW_FREQUENCY |
 420                                   AUDIO_CHANNEL_OUT_SIDE_LEFT |
 421                                   AUDIO_CHANNEL_OUT_SIDE_RIGHT),
 422     // matches the correct AudioFormat.CHANNEL_OUT_7POINT1_SURROUND definition for 7.1
 423     AUDIO_CHANNEL_OUT_7POINT1  = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 424                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 425                                   AUDIO_CHANNEL_OUT_FRONT_CENTER |
 426                                   AUDIO_CHANNEL_OUT_LOW_FREQUENCY |
 427                                   AUDIO_CHANNEL_OUT_BACK_LEFT |
 428                                   AUDIO_CHANNEL_OUT_BACK_RIGHT |
 429                                   AUDIO_CHANNEL_OUT_SIDE_LEFT |
 430                                   AUDIO_CHANNEL_OUT_SIDE_RIGHT),
 431     AUDIO_CHANNEL_OUT_ALL      = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 432                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 433                                   AUDIO_CHANNEL_OUT_FRONT_CENTER |
 434                                   AUDIO_CHANNEL_OUT_LOW_FREQUENCY |
 435                                   AUDIO_CHANNEL_OUT_BACK_LEFT |
 436                                   AUDIO_CHANNEL_OUT_BACK_RIGHT |
 437                                   AUDIO_CHANNEL_OUT_FRONT_LEFT_OF_CENTER |
 438                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT_OF_CENTER |
 439                                   AUDIO_CHANNEL_OUT_BACK_CENTER|
 440                                   AUDIO_CHANNEL_OUT_SIDE_LEFT|
 441                                   AUDIO_CHANNEL_OUT_SIDE_RIGHT|
 442                                   AUDIO_CHANNEL_OUT_TOP_CENTER|
 443                                   AUDIO_CHANNEL_OUT_TOP_FRONT_LEFT|
 444                                   AUDIO_CHANNEL_OUT_TOP_FRONT_CENTER|
 445                                   AUDIO_CHANNEL_OUT_TOP_FRONT_RIGHT|
 446                                   AUDIO_CHANNEL_OUT_TOP_BACK_LEFT|
 447                                   AUDIO_CHANNEL_OUT_TOP_BACK_CENTER|
 448                                   AUDIO_CHANNEL_OUT_TOP_BACK_RIGHT),
 449
 450 /* These are bits only, not complete values */
 451
 452     /* input channels */
 453     AUDIO_CHANNEL_IN_LEFT            = 0x4,
 454     AUDIO_CHANNEL_IN_RIGHT           = 0x8,
 455     AUDIO_CHANNEL_IN_FRONT           = 0x10,
 456     AUDIO_CHANNEL_IN_BACK            = 0x20,
 457     AUDIO_CHANNEL_IN_LEFT_PROCESSED  = 0x40,
 458     AUDIO_CHANNEL_IN_RIGHT_PROCESSED = 0x80,
 459     AUDIO_CHANNEL_IN_FRONT_PROCESSED = 0x100,
 460     AUDIO_CHANNEL_IN_BACK_PROCESSED  = 0x200,
 461     AUDIO_CHANNEL_IN_PRESSURE        = 0x400,
 462     AUDIO_CHANNEL_IN_X_AXIS          = 0x800,
 463     AUDIO_CHANNEL_IN_Y_AXIS          = 0x1000,
 464     AUDIO_CHANNEL_IN_Z_AXIS          = 0x2000,
 465     AUDIO_CHANNEL_IN_VOICE_UPLINK    = 0x4000,
 466     AUDIO_CHANNEL_IN_VOICE_DNLINK    = 0x8000,
 467
 468 /* TODO: should these be considered complete channel masks, or only bits, or deprecated? */
 469
 470     AUDIO_CHANNEL_IN_MONO   = AUDIO_CHANNEL_IN_FRONT,
 471     AUDIO_CHANNEL_IN_STEREO = (AUDIO_CHANNEL_IN_LEFT | AUDIO_CHANNEL_IN_RIGHT),
 472     AUDIO_CHANNEL_IN_FRONT_BACK = (AUDIO_CHANNEL_IN_FRONT | AUDIO_CHANNEL_IN_BACK),
 473     AUDIO_CHANNEL_IN_ALL    = (AUDIO_CHANNEL_IN_LEFT |
 474                                AUDIO_CHANNEL_IN_RIGHT |
 475                                AUDIO_CHANNEL_IN_FRONT |
 476                                AUDIO_CHANNEL_IN_BACK|
 477                                AUDIO_CHANNEL_IN_LEFT_PROCESSED |
 478                                AUDIO_CHANNEL_IN_RIGHT_PROCESSED |
 479                                AUDIO_CHANNEL_IN_FRONT_PROCESSED |
 480                                AUDIO_CHANNEL_IN_BACK_PROCESSED|
 481                                AUDIO_CHANNEL_IN_PRESSURE |
 482                                AUDIO_CHANNEL_IN_X_AXIS |
 483                                AUDIO_CHANNEL_IN_Y_AXIS |
 484                                AUDIO_CHANNEL_IN_Z_AXIS |
 485                                AUDIO_CHANNEL_IN_VOICE_UPLINK |
 486                                AUDIO_CHANNEL_IN_VOICE_DNLINK),
 487 };
 488
 489 /* A channel mask per se only defines the presence or absence of a channel, not the order.
 490  * But see AUDIO_INTERLEAVE_* below for the platform convention of order.
 491  *
 492  * audio_channel_mask_t is an opaque type and its internal layout should not
 493  * be assumed as it may change in the future.
 494  * Instead, always use the functions declared in this header to examine.
 495  *
 496  * These are the current representations:
 497  *
 498  *   AUDIO_CHANNEL_REPRESENTATION_POSITION
 499  *     is a channel mask representation for position assignment.
 500  *     Each low-order bit corresponds to the spatial position of a transducer (output),
 501  *     or interpretation of channel (input).
 502  *     The user of a channel mask needs to know the context of whether it is for output or input.
 503  *     The constants AUDIO_CHANNEL_OUT_* or AUDIO_CHANNEL_IN_* apply to the bits portion.
 504  *     It is not permitted for no bits to be set.
 505  *
 506  *   AUDIO_CHANNEL_REPRESENTATION_INDEX
 507  *     is a channel mask representation for index assignment.
 508  *     Each low-order bit corresponds to a selected channel.
 509  *     There is no platform interpretation of the various bits.
 510  *     There is no concept of output or input.
 511  *     It is not permitted for no bits to be set.
 512  *
 513  * All other representations are reserved for future use.
 514  *
 515  * Warning: current representation distinguishes between input and output, but this will not the be
 516  * case in future revisions of the platform. Wherever there is an ambiguity between input and output
 517  * that is currently resolved by checking the channel mask, the implementer should look for ways to
 518  * fix it with additional information outside of the mask.
 519  */
 520 typedef uint32_t audio_channel_mask_t;
 521
 522 /* Maximum number of channels for all representations */
 523 #define AUDIO_CHANNEL_COUNT_MAX             30
 524
 525 /* log(2) of maximum number of representations, not part of public API */
 526 #define AUDIO_CHANNEL_REPRESENTATION_LOG2   2
 527
 528 /* Representations */
 529 typedef enum {
 530     AUDIO_CHANNEL_REPRESENTATION_POSITION    = 0,    // must be zero for compatibility
 531     // 1 is reserved for future use
 532     AUDIO_CHANNEL_REPRESENTATION_INDEX       = 2,
 533     // 3 is reserved for future use
 534 } audio_channel_representation_t;
 535
 536 /* The channel index masks defined here are the canonical masks for 1 to 8 channel
 537  * endpoints and apply to both source and sink.
 538  */
 539 enum {
 540     AUDIO_CHANNEL_INDEX_HDR  = AUDIO_CHANNEL_REPRESENTATION_INDEX << AUDIO_CHANNEL_COUNT_MAX,
 541     AUDIO_CHANNEL_INDEX_MASK_1 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 1) - 1),
 542     AUDIO_CHANNEL_INDEX_MASK_2 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 2) - 1),
 543     AUDIO_CHANNEL_INDEX_MASK_3 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 3) - 1),
 544     AUDIO_CHANNEL_INDEX_MASK_4 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 4) - 1),
 545     AUDIO_CHANNEL_INDEX_MASK_5 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 5) - 1),
 546     AUDIO_CHANNEL_INDEX_MASK_6 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 6) - 1),
 547     AUDIO_CHANNEL_INDEX_MASK_7 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 7) - 1),
 548     AUDIO_CHANNEL_INDEX_MASK_8 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 8) - 1),
 549     // FIXME FCC_8
 550 };
 551
 552 /* The return value is undefined if the channel mask is invalid. */
 553 static inline uint32_t audio_channel_mask_get_bits(audio_channel_mask_t channel)
 554 {
 555     return channel & ((1 << AUDIO_CHANNEL_COUNT_MAX) - 1);
 556 }
 557
 558 /* The return value is undefined if the channel mask is invalid. */
 559 static inline audio_channel_representation_t audio_channel_mask_get_representation(
 560         audio_channel_mask_t channel)
 561 {
 562     // The right shift should be sufficient, but also "and" for safety in case mask is not 32 bits
 563     return (audio_channel_representation_t)
 564             ((channel >> AUDIO_CHANNEL_COUNT_MAX) & ((1 << AUDIO_CHANNEL_REPRESENTATION_LOG2) - 1));
 565 }
 566
 567 /* Returns true if the channel mask is valid,
 568  * or returns false for AUDIO_CHANNEL_NONE, AUDIO_CHANNEL_INVALID, and other invalid values.
 569  * This function is unable to determine whether a channel mask for position assignment
 570  * is invalid because an output mask has an invalid output bit set,
 571  * or because an input mask has an invalid input bit set.
 572  * All other APIs that take a channel mask assume that it is valid.
 573  */
 574 static inline bool audio_channel_mask_is_valid(audio_channel_mask_t channel)
 575 {
 576     uint32_t bits = audio_channel_mask_get_bits(channel);
 577     audio_channel_representation_t representation = audio_channel_mask_get_representation(channel);
 578     switch (representation) {
 579     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
 580     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
 581         break;
 582     default:
 583         bits = 0;
 584         break;
 585     }
 586     return bits != 0;
 587 }
 588
 589 /* Not part of public API */
 590 static inline audio_channel_mask_t audio_channel_mask_from_representation_and_bits(
 591         audio_channel_representation_t representation, uint32_t bits)
 592 {
 593     return (audio_channel_mask_t) ((representation << AUDIO_CHANNEL_COUNT_MAX) | bits);
 594 }
 595
 596 /* Expresses the convention when stereo audio samples are stored interleaved
 597  * in an array.  This should improve readability by allowing code to use
 598  * symbolic indices instead of hard-coded [0] and [1].
 599  *
 600  * For multi-channel beyond stereo, the platform convention is that channels
 601  * are interleaved in order from least significant channel mask bit
 602  * to most significant channel mask bit, with unused bits skipped.
 603  * Any exceptions to this convention will be noted at the appropriate API.
 604  */
 605 enum {
 606     AUDIO_INTERLEAVE_LEFT   = 0,
 607     AUDIO_INTERLEAVE_RIGHT  = 1,
 608 };
 609
 610 typedef enum {
 611     AUDIO_MODE_INVALID          = -2,
 612     AUDIO_MODE_CURRENT          = -1,
 613     AUDIO_MODE_NORMAL           = 0,
 614     AUDIO_MODE_RINGTONE         = 1,
 615     AUDIO_MODE_IN_CALL          = 2,
 616     AUDIO_MODE_IN_COMMUNICATION = 3,
 617
 618     AUDIO_MODE_CNT,
 619     AUDIO_MODE_MAX              = AUDIO_MODE_CNT - 1,
 620 } audio_mode_t;
 621
 622 /* This enum is deprecated */
 623 typedef enum {
 624     AUDIO_IN_ACOUSTICS_NONE          = 0,
 625     AUDIO_IN_ACOUSTICS_AGC_ENABLE    = 0x0001,
 626     AUDIO_IN_ACOUSTICS_AGC_DISABLE   = 0,
 627     AUDIO_IN_ACOUSTICS_NS_ENABLE     = 0x0002,
 628     AUDIO_IN_ACOUSTICS_NS_DISABLE    = 0,
 629     AUDIO_IN_ACOUSTICS_TX_IIR_ENABLE = 0x0004,
 630     AUDIO_IN_ACOUSTICS_TX_DISABLE    = 0,
 631 } audio_in_acoustics_t;
 632
 633 enum {
 634     AUDIO_DEVICE_NONE                          = 0x0,
 635     /* reserved bits */
 636     AUDIO_DEVICE_BIT_IN                        = 0x80000000,
 637     AUDIO_DEVICE_BIT_DEFAULT                   = 0x40000000,
 638     /* output devices */
 639     AUDIO_DEVICE_OUT_EARPIECE                  = 0x1,
 640     AUDIO_DEVICE_OUT_SPEAKER                   = 0x2,
 641     AUDIO_DEVICE_OUT_WIRED_HEADSET             = 0x4,
 642     AUDIO_DEVICE_OUT_WIRED_HEADPHONE           = 0x8,
 643     AUDIO_DEVICE_OUT_BLUETOOTH_SCO             = 0x10,
 644     AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET     = 0x20,
 645     AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT      = 0x40,
 646     AUDIO_DEVICE_OUT_BLUETOOTH_A2DP            = 0x80,
 647     AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES = 0x100,
 648     AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER    = 0x200,
 649     AUDIO_DEVICE_OUT_AUX_DIGITAL               = 0x400,
 650     AUDIO_DEVICE_OUT_HDMI                      = AUDIO_DEVICE_OUT_AUX_DIGITAL,
 651     /* uses an analog connection (multiplexed over the USB connector pins for instance) */
 652     AUDIO_DEVICE_OUT_ANLG_DOCK_HEADSET         = 0x800,
 653     AUDIO_DEVICE_OUT_DGTL_DOCK_HEADSET         = 0x1000,
 654     /* USB accessory mode: your Android device is a USB device and the dock is a USB host */
 655     AUDIO_DEVICE_OUT_USB_ACCESSORY             = 0x2000,
 656     /* USB host mode: your Android device is a USB host and the dock is a USB device */
 657     AUDIO_DEVICE_OUT_USB_DEVICE                = 0x4000,
 658     AUDIO_DEVICE_OUT_REMOTE_SUBMIX             = 0x8000,
 659     /* Telephony voice TX path */
 660     AUDIO_DEVICE_OUT_TELEPHONY_TX              = 0x10000,
 661     /* Analog jack with line impedance detected */
 662     AUDIO_DEVICE_OUT_LINE                      = 0x20000,
 663     /* HDMI Audio Return Channel */
 664     AUDIO_DEVICE_OUT_HDMI_ARC                  = 0x40000,
 665     /* S/PDIF out */
 666     AUDIO_DEVICE_OUT_SPDIF                     = 0x80000,
 667     /* FM transmitter out */
 668     AUDIO_DEVICE_OUT_FM                        = 0x100000,
 669     /* Line out for av devices */
 670     AUDIO_DEVICE_OUT_AUX_LINE                  = 0x200000,
 671     /* limited-output speaker device for acoustic safety */
 672     AUDIO_DEVICE_OUT_SPEAKER_SAFE              = 0x400000,
 673     AUDIO_DEVICE_OUT_IP                        = 0x800000,
 674     /* audio bus implemented by the audio system (e.g an MOST stereo channel) */
 675     AUDIO_DEVICE_OUT_BUS                       = 0x1000000,
 676     AUDIO_DEVICE_OUT_DEFAULT                   = AUDIO_DEVICE_BIT_DEFAULT,
 677     AUDIO_DEVICE_OUT_ALL      = (AUDIO_DEVICE_OUT_EARPIECE |
 678                                  AUDIO_DEVICE_OUT_SPEAKER |
 679                                  AUDIO_DEVICE_OUT_WIRED_HEADSET |
 680                                  AUDIO_DEVICE_OUT_WIRED_HEADPHONE |
 681                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO |
 682                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET |
 683                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT |
 684                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP |
 685                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES |
 686                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER |
 687                                  AUDIO_DEVICE_OUT_HDMI |
 688                                  AUDIO_DEVICE_OUT_ANLG_DOCK_HEADSET |
 689                                  AUDIO_DEVICE_OUT_DGTL_DOCK_HEADSET |
 690                                  AUDIO_DEVICE_OUT_USB_ACCESSORY |
 691                                  AUDIO_DEVICE_OUT_USB_DEVICE |
 692                                  AUDIO_DEVICE_OUT_REMOTE_SUBMIX |
 693                                  AUDIO_DEVICE_OUT_TELEPHONY_TX |
 694                                  AUDIO_DEVICE_OUT_LINE |
 695                                  AUDIO_DEVICE_OUT_HDMI_ARC |
 696                                  AUDIO_DEVICE_OUT_SPDIF |
 697                                  AUDIO_DEVICE_OUT_FM |
 698                                  AUDIO_DEVICE_OUT_AUX_LINE |
 699                                  AUDIO_DEVICE_OUT_SPEAKER_SAFE |
 700                                  AUDIO_DEVICE_OUT_IP |
 701                                  AUDIO_DEVICE_OUT_BUS |
 702                                  AUDIO_DEVICE_OUT_DEFAULT),
 703     AUDIO_DEVICE_OUT_ALL_A2DP = (AUDIO_DEVICE_OUT_BLUETOOTH_A2DP |
 704                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES |
 705                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER),
 706     AUDIO_DEVICE_OUT_ALL_SCO  = (AUDIO_DEVICE_OUT_BLUETOOTH_SCO |
 707                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET |
 708                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT),
 709     AUDIO_DEVICE_OUT_ALL_USB  = (AUDIO_DEVICE_OUT_USB_ACCESSORY |
 710                                  AUDIO_DEVICE_OUT_USB_DEVICE),
 711     /* input devices */
 712     AUDIO_DEVICE_IN_COMMUNICATION         = AUDIO_DEVICE_BIT_IN | 0x1,
 713     AUDIO_DEVICE_IN_AMBIENT               = AUDIO_DEVICE_BIT_IN | 0x2,
 714     AUDIO_DEVICE_IN_BUILTIN_MIC           = AUDIO_DEVICE_BIT_IN | 0x4,
 715     AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET = AUDIO_DEVICE_BIT_IN | 0x8,
 716     AUDIO_DEVICE_IN_WIRED_HEADSET         = AUDIO_DEVICE_BIT_IN | 0x10,
 717     AUDIO_DEVICE_IN_AUX_DIGITAL           = AUDIO_DEVICE_BIT_IN | 0x20,
 718     AUDIO_DEVICE_IN_HDMI                  = AUDIO_DEVICE_IN_AUX_DIGITAL,
 719     /* Telephony voice RX path */
 720     AUDIO_DEVICE_IN_VOICE_CALL            = AUDIO_DEVICE_BIT_IN | 0x40,
 721     AUDIO_DEVICE_IN_TELEPHONY_RX          = AUDIO_DEVICE_IN_VOICE_CALL,
 722     AUDIO_DEVICE_IN_BACK_MIC              = AUDIO_DEVICE_BIT_IN | 0x80,
 723     AUDIO_DEVICE_IN_REMOTE_SUBMIX         = AUDIO_DEVICE_BIT_IN | 0x100,
 724     AUDIO_DEVICE_IN_ANLG_DOCK_HEADSET     = AUDIO_DEVICE_BIT_IN | 0x200,
 725     AUDIO_DEVICE_IN_DGTL_DOCK_HEADSET     = AUDIO_DEVICE_BIT_IN | 0x400,
 726     AUDIO_DEVICE_IN_USB_ACCESSORY         = AUDIO_DEVICE_BIT_IN | 0x800,
 727     AUDIO_DEVICE_IN_USB_DEVICE            = AUDIO_DEVICE_BIT_IN | 0x1000,
 728     /* FM tuner input */
 729     AUDIO_DEVICE_IN_FM_TUNER              = AUDIO_DEVICE_BIT_IN | 0x2000,
 730     /* TV tuner input */
 731     AUDIO_DEVICE_IN_TV_TUNER              = AUDIO_DEVICE_BIT_IN | 0x4000,
 732     /* Analog jack with line impedance detected */
 733     AUDIO_DEVICE_IN_LINE                  = AUDIO_DEVICE_BIT_IN | 0x8000,
 734     /* S/PDIF in */
 735     AUDIO_DEVICE_IN_SPDIF                 = AUDIO_DEVICE_BIT_IN | 0x10000,
 736     AUDIO_DEVICE_IN_BLUETOOTH_A2DP        = AUDIO_DEVICE_BIT_IN | 0x20000,
 737     AUDIO_DEVICE_IN_LOOPBACK              = AUDIO_DEVICE_BIT_IN | 0x40000,
 738     AUDIO_DEVICE_IN_IP                    = AUDIO_DEVICE_BIT_IN | 0x80000,
 739     /* audio bus implemented by the audio system (e.g an MOST stereo channel) */
 740     AUDIO_DEVICE_IN_BUS                   = AUDIO_DEVICE_BIT_IN | 0x100000,
 741     AUDIO_DEVICE_IN_DEFAULT               = AUDIO_DEVICE_BIT_IN | AUDIO_DEVICE_BIT_DEFAULT,
 742
 743     AUDIO_DEVICE_IN_ALL     = (AUDIO_DEVICE_IN_COMMUNICATION |
 744                                AUDIO_DEVICE_IN_AMBIENT |
 745                                AUDIO_DEVICE_IN_BUILTIN_MIC |
 746                                AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET |
 747                                AUDIO_DEVICE_IN_WIRED_HEADSET |
 748                                AUDIO_DEVICE_IN_HDMI |
 749                                AUDIO_DEVICE_IN_TELEPHONY_RX |
 750                                AUDIO_DEVICE_IN_BACK_MIC |
 751                                AUDIO_DEVICE_IN_REMOTE_SUBMIX |
 752                                AUDIO_DEVICE_IN_ANLG_DOCK_HEADSET |
 753                                AUDIO_DEVICE_IN_DGTL_DOCK_HEADSET |
 754                                AUDIO_DEVICE_IN_USB_ACCESSORY |
 755                                AUDIO_DEVICE_IN_USB_DEVICE |
 756                                AUDIO_DEVICE_IN_FM_TUNER |
 757                                AUDIO_DEVICE_IN_TV_TUNER |
 758                                AUDIO_DEVICE_IN_LINE |
 759                                AUDIO_DEVICE_IN_SPDIF |
 760                                AUDIO_DEVICE_IN_BLUETOOTH_A2DP |
 761                                AUDIO_DEVICE_IN_LOOPBACK |
 762                                AUDIO_DEVICE_IN_IP |
 763                                AUDIO_DEVICE_IN_BUS |
 764                                AUDIO_DEVICE_IN_DEFAULT),
 765     AUDIO_DEVICE_IN_ALL_SCO = AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET,
 766     AUDIO_DEVICE_IN_ALL_USB  = (AUDIO_DEVICE_IN_USB_ACCESSORY |
 767                                 AUDIO_DEVICE_IN_USB_DEVICE),
 768 };
 769
 770 typedef uint32_t audio_devices_t;
 771
 772 /* the audio output flags serve two purposes:
 773  * - when an AudioTrack is created they indicate a "wish" to be connected to an
 774  * output stream with attributes corresponding to the specified flags
 775  * - when present in an output profile descriptor listed for a particular audio
 776  * hardware module, they indicate that an output stream can be opened that
 777  * supports the attributes indicated by the flags.
 778  * the audio policy manager will try to match the flags in the request
 779  * (when getOuput() is called) to an available output stream.
 780  */
 781 typedef enum {
 782     AUDIO_OUTPUT_FLAG_NONE = 0x0,       // no attributes
 783     AUDIO_OUTPUT_FLAG_DIRECT = 0x1,     // this output directly connects a track
 784                                         // to one output stream: no software mixer
 785     AUDIO_OUTPUT_FLAG_PRIMARY = 0x2,    // this output is the primary output of
 786                                         // the device. It is unique and must be
 787                                         // present. It is opened by default and
 788                                         // receives routing, audio mode and volume
 789                                         // controls related to voice calls.
 790     AUDIO_OUTPUT_FLAG_FAST = 0x4,       // output supports "fast tracks",
 791                                         // defined elsewhere
 792     AUDIO_OUTPUT_FLAG_DEEP_BUFFER = 0x8, // use deep audio buffers
 793     AUDIO_OUTPUT_FLAG_COMPRESS_OFFLOAD = 0x10,  // offload playback of compressed
 794                                                 // streams to hardware codec
 795     AUDIO_OUTPUT_FLAG_NON_BLOCKING = 0x20, // use non-blocking write
 796     AUDIO_OUTPUT_FLAG_HW_AV_SYNC = 0x40,   // output uses a hardware A/V synchronization source
 797     AUDIO_OUTPUT_FLAG_TTS = 0x80,          // output for streams transmitted through speaker
 798                                            // at a sample rate high enough to accommodate
 799                                            // lower-range ultrasonic playback
 800     AUDIO_OUTPUT_FLAG_RAW = 0x100,         // minimize signal processing
 801     AUDIO_OUTPUT_FLAG_SYNC = 0x200,        // synchronize I/O streams
 802
 803     AUDIO_OUTPUT_FLAG_IEC958_NONAUDIO = 0x400, // Audio stream contains compressed audio in
 804                                                // SPDIF data bursts, not PCM.
 805 } audio_output_flags_t;
 806
 807 /* The audio input flags are analogous to audio output flags.
 808  * Currently they are used only when an AudioRecord is created,
 809  * to indicate a preference to be connected to an input stream with
 810  * attributes corresponding to the specified flags.
 811  */
 812 typedef enum {
 813     AUDIO_INPUT_FLAG_NONE       = 0x0,  // no attributes
 814     AUDIO_INPUT_FLAG_FAST       = 0x1,  // prefer an input that supports "fast tracks"
 815     AUDIO_INPUT_FLAG_HW_HOTWORD = 0x2,  // prefer an input that captures from hw hotword source
 816     AUDIO_INPUT_FLAG_RAW        = 0x4,  // minimize signal processing
 817     AUDIO_INPUT_FLAG_SYNC       = 0x8,  // synchronize I/O streams
 818
 819 } audio_input_flags_t;
 820
 821 /* Additional information about compressed streams offloaded to
 822  * hardware playback
 823  * The version and size fields must be initialized by the caller by using
 824  * one of the constants defined here.
 825  */
 826 typedef struct {
 827     uint16_t version;                   // version of the info structure
 828     uint16_t size;                      // total size of the structure including version and size
 829     uint32_t sample_rate;               // sample rate in Hz
 830     audio_channel_mask_t channel_mask;  // channel mask
 831     audio_format_t format;              // audio format
 832     audio_stream_type_t stream_type;    // stream type
 833     uint32_t bit_rate;                  // bit rate in bits per second
 834     int64_t duration_us;                // duration in microseconds, -1 if unknown
 835     bool has_video;                     // true if stream is tied to a video stream
 836     bool is_streaming;                  // true if streaming, false if local playback
 837 } audio_offload_info_t;
 838
 839 #define AUDIO_MAKE_OFFLOAD_INFO_VERSION(maj,min) \
 840             ((((maj) & 0xff) << 8) | ((min) & 0xff))
 841
 842 #define AUDIO_OFFLOAD_INFO_VERSION_0_1 AUDIO_MAKE_OFFLOAD_INFO_VERSION(0, 1)
 843 #define AUDIO_OFFLOAD_INFO_VERSION_CURRENT AUDIO_OFFLOAD_INFO_VERSION_0_1
 844
 845 static const audio_offload_info_t AUDIO_INFO_INITIALIZER = {
 846     /* .version = */ AUDIO_OFFLOAD_INFO_VERSION_CURRENT,
 847     /* .size = */ sizeof(audio_offload_info_t),
 848     /* .sample_rate = */ 0,
 849     /* .channel_mask = */ 0,
 850     /* .format = */ AUDIO_FORMAT_DEFAULT,
 851     /* .stream_type = */ AUDIO_STREAM_VOICE_CALL,
 852     /* .bit_rate = */ 0,
 853     /* .duration_us = */ 0,
 854     /* .has_video = */ false,
 855     /* .is_streaming = */ false
 856 };
 857
 858 /* common audio stream configuration parameters
 859  * You should memset() the entire structure to zero before use to
 860  * ensure forward compatibility
 861  */
 862 struct audio_config {
 863     uint32_t sample_rate;
 864     audio_channel_mask_t channel_mask;
 865     audio_format_t  format;
 866     audio_offload_info_t offload_info;
 867     size_t frame_count;
 868 };
 869 typedef struct audio_config audio_config_t;
 870
 871 static const audio_config_t AUDIO_CONFIG_INITIALIZER = {
 872     /* .sample_rate = */ 0,
 873     /* .channel_mask = */ AUDIO_CHANNEL_NONE,
 874     /* .format = */ AUDIO_FORMAT_DEFAULT,
 875     /* .offload_info = */ {
 876         /* .version = */ AUDIO_OFFLOAD_INFO_VERSION_CURRENT,
 877         /* .size = */ sizeof(audio_offload_info_t),
 878         /* .sample_rate = */ 0,
 879         /* .channel_mask = */ 0,
 880         /* .format = */ AUDIO_FORMAT_DEFAULT,
 881         /* .stream_type = */ AUDIO_STREAM_VOICE_CALL,
 882         /* .bit_rate = */ 0,
 883         /* .duration_us = */ 0,
 884         /* .has_video = */ false,
 885         /* .is_streaming = */ false
 886     },
 887     /* .frame_count = */ 0,
 888 };
 889
 890 struct audio_config_base {
 891     uint32_t sample_rate;
 892     audio_channel_mask_t channel_mask;
 893     audio_format_t  format;
 894 };
 895
 896 typedef struct audio_config_base audio_config_base_t;
 897
 898 static const audio_config_base_t AUDIO_CONFIG_BASE_INITIALIZER = {
 899     /* .sample_rate = */ 0,
 900     /* .channel_mask = */ AUDIO_CHANNEL_NONE,
 901     /* .format = */ AUDIO_FORMAT_DEFAULT
 902 };
 903
 904 /* audio hw module handle functions or structures referencing a module */
 905 typedef enum {
 906     AUDIO_MODULE_HANDLE_NONE = 0,
 907 } audio_module_handle_t;
 908
 909 /******************************
 910  *  Volume control
 911  *****************************/
 912
 913 /* If the audio hardware supports gain control on some audio paths,
 914  * the platform can expose them in the audio_policy.conf file. The audio HAL
 915  * will then implement gain control functions that will use the following data
 916  * structures. */
 917
 918 /* Type of gain control exposed by an audio port */
 919 #define AUDIO_GAIN_MODE_JOINT     0x1 /* supports joint channel gain control */
 920 #define AUDIO_GAIN_MODE_CHANNELS  0x2 /* supports separate channel gain control */
 921 #define AUDIO_GAIN_MODE_RAMP      0x4 /* supports gain ramps */
 922
 923 typedef uint32_t audio_gain_mode_t;
 924
 925
 926 /* An audio_gain struct is a representation of a gain stage.
 927  * A gain stage is always attached to an audio port. */
 928 struct audio_gain  {
 929     audio_gain_mode_t    mode;          /* e.g. AUDIO_GAIN_MODE_JOINT */
 930     audio_channel_mask_t channel_mask;  /* channels which gain an be controlled.
 931                                            N/A if AUDIO_GAIN_MODE_CHANNELS is not supported */
 932     int                  min_value;     /* minimum gain value in millibels */
 933     int                  max_value;     /* maximum gain value in millibels */
 934     int                  default_value; /* default gain value in millibels */
 935     unsigned int         step_value;    /* gain step in millibels */
 936     unsigned int         min_ramp_ms;   /* minimum ramp duration in ms */
 937     unsigned int         max_ramp_ms;   /* maximum ramp duration in ms */
 938 };
 939
 940 /* The gain configuration structure is used to get or set the gain values of a
 941  * given port */
 942 struct audio_gain_config  {
 943     int                  index;             /* index of the corresponding audio_gain in the
 944                                                audio_port gains[] table */
 945     audio_gain_mode_t    mode;              /* mode requested for this command */
 946     audio_channel_mask_t channel_mask;      /* channels which gain value follows.
 947                                                N/A in joint mode */
 948
 949     // note this "8" is not FCC_8, so it won't need to be changed for > 8 channels
 950     int                  values[sizeof(audio_channel_mask_t) * 8]; /* gain values in millibels
 951                                                for each channel ordered from LSb to MSb in
 952                                                channel mask. The number of values is 1 in joint
 953                                                mode or popcount(channel_mask) */
 954     unsigned int         ramp_duration_ms; /* ramp duration in ms */
 955 };
 956
 957 /******************************
 958  *  Routing control
 959  *****************************/
 960
 961 /* Types defined here are used to describe an audio source or sink at internal
 962  * framework interfaces (audio policy, patch panel) or at the audio HAL.
 963  * Sink and sources are grouped in a concept of “audio port” representing an
 964  * audio end point at the edge of the system managed by the module exposing
 965  * the interface. */
 966
 967 /* Audio port role: either source or sink */
 968 typedef enum {
 969     AUDIO_PORT_ROLE_NONE,
 970     AUDIO_PORT_ROLE_SOURCE,
 971     AUDIO_PORT_ROLE_SINK,
 972 } audio_port_role_t;
 973
 974 /* Audio port type indicates if it is a session (e.g AudioTrack),
 975  * a mix (e.g PlaybackThread output) or a physical device
 976  * (e.g AUDIO_DEVICE_OUT_SPEAKER) */
 977 typedef enum {
 978     AUDIO_PORT_TYPE_NONE,
 979     AUDIO_PORT_TYPE_DEVICE,
 980     AUDIO_PORT_TYPE_MIX,
 981     AUDIO_PORT_TYPE_SESSION,
 982 } audio_port_type_t;
 983
 984 /* Each port has a unique ID or handle allocated by policy manager */
 985 typedef int audio_port_handle_t;
 986 #define AUDIO_PORT_HANDLE_NONE 0
 987
 988 /* the maximum length for the human-readable device name */
 989 #define AUDIO_PORT_MAX_NAME_LEN 128
 990
 991 /* maximum audio device address length */
 992 #define AUDIO_DEVICE_MAX_ADDRESS_LEN 32
 993
 994 /* extension for audio port configuration structure when the audio port is a
 995  * hardware device */
 996 struct audio_port_config_device_ext {
 997     audio_module_handle_t hw_module;                /* module the device is attached to */
 998     audio_devices_t       type;                     /* device type (e.g AUDIO_DEVICE_OUT_SPEAKER) */
 999     char                  address[AUDIO_DEVICE_MAX_ADDRESS_LEN]; /* device address. "" if N/A */
1000 };
1001
1002 /* extension for audio port configuration structure when the audio port is a
1003  * sub mix */
1004 struct audio_port_config_mix_ext {
1005     audio_module_handle_t hw_module;    /* module the stream is attached to */
1006     audio_io_handle_t handle;           /* I/O handle of the input/output stream */
1007     union {
1008         //TODO: change use case for output streams: use strategy and mixer attributes
1009         audio_stream_type_t stream;
1010         audio_source_t      source;
1011     } usecase;
1012 };
1013
1014 /* extension for audio port configuration structure when the audio port is an
1015  * audio session */
1016 struct audio_port_config_session_ext {
1017     audio_session_t   session; /* audio session */
1018 };
1019
1020 /* Flags indicating which fields are to be considered in struct audio_port_config */
1021 #define AUDIO_PORT_CONFIG_SAMPLE_RATE  0x1
1022 #define AUDIO_PORT_CONFIG_CHANNEL_MASK 0x2
1023 #define AUDIO_PORT_CONFIG_FORMAT       0x4
1024 #define AUDIO_PORT_CONFIG_GAIN         0x8
1025 #define AUDIO_PORT_CONFIG_ALL (AUDIO_PORT_CONFIG_SAMPLE_RATE | \
1026                                AUDIO_PORT_CONFIG_CHANNEL_MASK | \
1027                                AUDIO_PORT_CONFIG_FORMAT | \
1028                                AUDIO_PORT_CONFIG_GAIN)
1029
1030 /* audio port configuration structure used to specify a particular configuration of
1031  * an audio port */
1032 struct audio_port_config {
1033     audio_port_handle_t      id;           /* port unique ID */
1034     audio_port_role_t        role;         /* sink or source */
1035     audio_port_type_t        type;         /* device, mix ... */
1036     unsigned int             config_mask;  /* e.g AUDIO_PORT_CONFIG_ALL */
1037     unsigned int             sample_rate;  /* sampling rate in Hz */
1038     audio_channel_mask_t     channel_mask; /* channel mask if applicable */
1039     audio_format_t           format;       /* format if applicable */
1040     struct audio_gain_config gain;         /* gain to apply if applicable */
1041     union {
1042         struct audio_port_config_device_ext  device;  /* device specific info */
1043         struct audio_port_config_mix_ext     mix;     /* mix specific info */
1044         struct audio_port_config_session_ext session; /* session specific info */
1045     } ext;
1046 };
1047
1048
1049 /* max number of sampling rates in audio port */
1050 #define AUDIO_PORT_MAX_SAMPLING_RATES 16
1051 /* max number of channel masks in audio port */
1052 #define AUDIO_PORT_MAX_CHANNEL_MASKS 16
1053 /* max number of audio formats in audio port */
1054 #define AUDIO_PORT_MAX_FORMATS 16
1055 /* max number of gain controls in audio port */
1056 #define AUDIO_PORT_MAX_GAINS 16
1057
1058 /* extension for audio port structure when the audio port is a hardware device */
1059 struct audio_port_device_ext {
1060     audio_module_handle_t hw_module;    /* module the device is attached to */
1061     audio_devices_t       type;         /* device type (e.g AUDIO_DEVICE_OUT_SPEAKER) */
1062     char                  address[AUDIO_DEVICE_MAX_ADDRESS_LEN];
1063 };
1064
1065 /* Latency class of the audio mix */
1066 typedef enum {
1067     AUDIO_LATENCY_LOW,
1068     AUDIO_LATENCY_NORMAL,
1069 } audio_mix_latency_class_t;
1070
1071 /* extension for audio port structure when the audio port is a sub mix */
1072 struct audio_port_mix_ext {
1073     audio_module_handle_t     hw_module;     /* module the stream is attached to */
1074     audio_io_handle_t         handle;        /* I/O handle of the input.output stream */
1075     audio_mix_latency_class_t latency_class; /* latency class */
1076     // other attributes: routing strategies
1077 };
1078
1079 /* extension for audio port structure when the audio port is an audio session */
1080 struct audio_port_session_ext {
1081     audio_session_t   session; /* audio session */
1082 };
1083
1084 struct audio_port {
1085     audio_port_handle_t      id;                /* port unique ID */
1086     audio_port_role_t        role;              /* sink or source */
1087     audio_port_type_t        type;              /* device, mix ... */
1088     char                     name[AUDIO_PORT_MAX_NAME_LEN];
1089     unsigned int             num_sample_rates;  /* number of sampling rates in following array */
1090     unsigned int             sample_rates[AUDIO_PORT_MAX_SAMPLING_RATES];
1091     unsigned int             num_channel_masks; /* number of channel masks in following array */
1092     audio_channel_mask_t     channel_masks[AUDIO_PORT_MAX_CHANNEL_MASKS];
1093     unsigned int             num_formats;       /* number of formats in following array */
1094     audio_format_t           formats[AUDIO_PORT_MAX_FORMATS];
1095     unsigned int             num_gains;         /* number of gains in following array */
1096     struct audio_gain        gains[AUDIO_PORT_MAX_GAINS];
1097     struct audio_port_config active_config;     /* current audio port configuration */
1098     union {
1099         struct audio_port_device_ext  device;
1100         struct audio_port_mix_ext     mix;
1101         struct audio_port_session_ext session;
1102     } ext;
1103 };
1104
1105 /* An audio patch represents a connection between one or more source ports and
1106  * one or more sink ports. Patches are connected and disconnected by audio policy manager or by
1107  * applications via framework APIs.
1108  * Each patch is identified by a handle at the interface used to create that patch. For instance,
1109  * when a patch is created by the audio HAL, the HAL allocates and returns a handle.
1110  * This handle is unique to a given audio HAL hardware module.
1111  * But the same patch receives another system wide unique handle allocated by the framework.
1112  * This unique handle is used for all transactions inside the framework.
1113  */
1114 typedef enum {
1115     AUDIO_PATCH_HANDLE_NONE = 0,
1116 } audio_patch_handle_t;
1117
1118 #define AUDIO_PATCH_PORTS_MAX   16
1119
1120 struct audio_patch {
1121     audio_patch_handle_t id;            /* patch unique ID */
1122     unsigned int      num_sources;      /* number of sources in following array */
1123     struct audio_port_config sources[AUDIO_PATCH_PORTS_MAX];
1124     unsigned int      num_sinks;        /* number of sinks in following array */
1125     struct audio_port_config sinks[AUDIO_PATCH_PORTS_MAX];
1126 };
1127
1128
1129
1130 /* a HW synchronization source returned by the audio HAL */
1131 typedef uint32_t audio_hw_sync_t;
1132
1133 /* an invalid HW synchronization source indicating an error */
1134 #define AUDIO_HW_SYNC_INVALID 0
1135
1136 static inline bool audio_is_output_device(audio_devices_t device)
1137 {
1138     if (((device & AUDIO_DEVICE_BIT_IN) == 0) &&
1139             (popcount(device) == 1) && ((device & ~AUDIO_DEVICE_OUT_ALL) == 0))
1140         return true;
1141     else
1142         return false;
1143 }
1144
1145 static inline bool audio_is_input_device(audio_devices_t device)
1146 {
1147     if ((device & AUDIO_DEVICE_BIT_IN) != 0) {
1148         device &= ~AUDIO_DEVICE_BIT_IN;
1149         if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_IN_ALL) == 0))
1150             return true;
1151     }
1152     return false;
1153 }
1154
1155 static inline bool audio_is_output_devices(audio_devices_t device)
1156 {
1157     return (device & AUDIO_DEVICE_BIT_IN) == 0;
1158 }
1159
1160 static inline bool audio_is_a2dp_in_device(audio_devices_t device)
1161 {
1162     if ((device & AUDIO_DEVICE_BIT_IN) != 0) {
1163         device &= ~AUDIO_DEVICE_BIT_IN;
1164         if ((popcount(device) == 1) && (device & AUDIO_DEVICE_IN_BLUETOOTH_A2DP))
1165             return true;
1166     }
1167     return false;
1168 }
1169
1170 static inline bool audio_is_a2dp_out_device(audio_devices_t device)
1171 {
1172     if ((popcount(device) == 1) && (device & AUDIO_DEVICE_OUT_ALL_A2DP))
1173         return true;
1174     else
1175         return false;
1176 }
1177
1178 // Deprecated - use audio_is_a2dp_out_device() instead
1179 static inline bool audio_is_a2dp_device(audio_devices_t device)
1180 {
1181     return audio_is_a2dp_out_device(device);
1182 }
1183
1184 static inline bool audio_is_bluetooth_sco_device(audio_devices_t device)
1185 {
1186     if ((device & AUDIO_DEVICE_BIT_IN) == 0) {
1187         if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_OUT_ALL_SCO) == 0))
1188             return true;
1189     } else {
1190         device &= ~AUDIO_DEVICE_BIT_IN;
1191         if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET) == 0))
1192             return true;
1193     }
1194
1195     return false;
1196 }
1197
1198 static inline bool audio_is_usb_out_device(audio_devices_t device)
1199 {
1200     return ((popcount(device) == 1) && (device & AUDIO_DEVICE_OUT_ALL_USB));
1201 }
1202
1203 static inline bool audio_is_usb_in_device(audio_devices_t device)
1204 {
1205     if ((device & AUDIO_DEVICE_BIT_IN) != 0) {
1206         device &= ~AUDIO_DEVICE_BIT_IN;
1207         if (popcount(device) == 1 && (device & AUDIO_DEVICE_IN_ALL_USB) != 0)
1208             return true;
1209     }
1210     return false;
1211 }
1212
1213 /* OBSOLETE - use audio_is_usb_out_device() instead. */
1214 static inline bool audio_is_usb_device(audio_devices_t device)
1215 {
1216     return audio_is_usb_out_device(device);
1217 }
1218
1219 static inline bool audio_is_remote_submix_device(audio_devices_t device)
1220 {
1221     if ((audio_is_output_devices(device) &&
1222          (device & AUDIO_DEVICE_OUT_REMOTE_SUBMIX) == AUDIO_DEVICE_OUT_REMOTE_SUBMIX)
1223         || (!audio_is_output_devices(device) &&
1224          (device & AUDIO_DEVICE_IN_REMOTE_SUBMIX) == AUDIO_DEVICE_IN_REMOTE_SUBMIX))
1225         return true;
1226     else
1227         return false;
1228 }
1229
1230 /* Returns true if:
1231  *  representation is valid, and
1232  *  there is at least one channel bit set which _could_ correspond to an input channel, and
1233  *  there are no channel bits set which could _not_ correspond to an input channel.
1234  * Otherwise returns false.
1235  */
1236 static inline bool audio_is_input_channel(audio_channel_mask_t channel)
1237 {
1238     uint32_t bits = audio_channel_mask_get_bits(channel);
1239     switch (audio_channel_mask_get_representation(channel)) {
1240     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
1241         if (bits & ~AUDIO_CHANNEL_IN_ALL) {
1242             bits = 0;
1243         }
1244         // fall through
1245     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
1246         return bits != 0;
1247     default:
1248         return false;
1249     }
1250 }
1251
1252 /* Returns true if:
1253  *  representation is valid, and
1254  *  there is at least one channel bit set which _could_ correspond to an output channel, and
1255  *  there are no channel bits set which could _not_ correspond to an output channel.
1256  * Otherwise returns false.
1257  */
1258 static inline bool audio_is_output_channel(audio_channel_mask_t channel)
1259 {
1260     uint32_t bits = audio_channel_mask_get_bits(channel);
1261     switch (audio_channel_mask_get_representation(channel)) {
1262     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
1263         if (bits & ~AUDIO_CHANNEL_OUT_ALL) {
1264             bits = 0;
1265         }
1266         // fall through
1267     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
1268         return bits != 0;
1269     default:
1270         return false;
1271     }
1272 }
1273
1274 /* Returns the number of channels from an input channel mask,
1275  * used in the context of audio input or recording.
1276  * If a channel bit is set which could _not_ correspond to an input channel,
1277  * it is excluded from the count.
1278  * Returns zero if the representation is invalid.
1279  */
1280 static inline uint32_t audio_channel_count_from_in_mask(audio_channel_mask_t channel)
1281 {
1282     uint32_t bits = audio_channel_mask_get_bits(channel);
1283     switch (audio_channel_mask_get_representation(channel)) {
1284     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
1285         // TODO: We can now merge with from_out_mask and remove anding
1286         bits &= AUDIO_CHANNEL_IN_ALL;
1287         // fall through
1288     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
1289         return popcount(bits);
1290     default:
1291         return 0;
1292     }
1293 }
1294
1295 /* Returns the number of channels from an output channel mask,
1296  * used in the context of audio output or playback.
1297  * If a channel bit is set which could _not_ correspond to an output channel,
1298  * it is excluded from the count.
1299  * Returns zero if the representation is invalid.
1300  */
1301 static inline uint32_t audio_channel_count_from_out_mask(audio_channel_mask_t channel)
1302 {
1303     uint32_t bits = audio_channel_mask_get_bits(channel);
1304     switch (audio_channel_mask_get_representation(channel)) {
1305     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
1306         // TODO: We can now merge with from_in_mask and remove anding
1307         bits &= AUDIO_CHANNEL_OUT_ALL;
1308         // fall through
1309     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
1310         return popcount(bits);
1311     default:
1312         return 0;
1313     }
1314 }
1315
1316 /* Derive a channel mask for index assignment from a channel count.
1317  * Returns the matching channel mask,
1318  * or AUDIO_CHANNEL_NONE if the channel count is zero,
1319  * or AUDIO_CHANNEL_INVALID if the channel count exceeds AUDIO_CHANNEL_COUNT_MAX.
1320  */
1321 static inline audio_channel_mask_t audio_channel_mask_for_index_assignment_from_count(
1322         uint32_t channel_count)
1323 {
1324     if (channel_count == 0) {
1325         return AUDIO_CHANNEL_NONE;
1326     }
1327     if (channel_count > AUDIO_CHANNEL_COUNT_MAX) {
1328         return AUDIO_CHANNEL_INVALID;
1329     }
1330     uint32_t bits = (1 << channel_count) - 1;
1331     return audio_channel_mask_from_representation_and_bits(
1332             AUDIO_CHANNEL_REPRESENTATION_INDEX, bits);
1333 }
1334
1335 /* Derive an output channel mask for position assignment from a channel count.
1336  * This is to be used when the content channel mask is unknown. The 1, 2, 4, 5, 6, 7 and 8 channel
1337  * cases are mapped to the standard game/home-theater layouts, but note that 4 is mapped to quad,
1338  * and not stereo + FC + mono surround. A channel count of 3 is arbitrarily mapped to stereo + FC
1339  * for continuity with stereo.
1340  * Returns the matching channel mask,
1341  * or AUDIO_CHANNEL_NONE if the channel count is zero,
1342  * or AUDIO_CHANNEL_INVALID if the channel count exceeds that of the
1343  * configurations for which a default output channel mask is defined.
1344  */
1345 static inline audio_channel_mask_t audio_channel_out_mask_from_count(uint32_t channel_count)
1346 {
1347     uint32_t bits;
1348     switch (channel_count) {
1349     case 0:
1350         return AUDIO_CHANNEL_NONE;
1351     case 1:
1352         bits = AUDIO_CHANNEL_OUT_MONO;
1353         break;
1354     case 2:
1355         bits = AUDIO_CHANNEL_OUT_STEREO;
1356         break;
1357     case 3:
1358         bits = AUDIO_CHANNEL_OUT_STEREO | AUDIO_CHANNEL_OUT_FRONT_CENTER;
1359         break;
1360     case 4: // 4.0
1361         bits = AUDIO_CHANNEL_OUT_QUAD;
1362         break;
1363     case 5: // 5.0
1364         bits = AUDIO_CHANNEL_OUT_QUAD | AUDIO_CHANNEL_OUT_FRONT_CENTER;
1365         break;
1366     case 6: // 5.1
1367         bits = AUDIO_CHANNEL_OUT_5POINT1;
1368         break;
1369     case 7: // 6.1
1370         bits = AUDIO_CHANNEL_OUT_5POINT1 | AUDIO_CHANNEL_OUT_BACK_CENTER;
1371         break;
1372     case 8:
1373         bits = AUDIO_CHANNEL_OUT_7POINT1;
1374         break;
1375     // FIXME FCC_8
1376     default:
1377         return AUDIO_CHANNEL_INVALID;
1378     }
1379     return audio_channel_mask_from_representation_and_bits(
1380             AUDIO_CHANNEL_REPRESENTATION_POSITION, bits);
1381 }
1382
1383 /* Derive a default input channel mask from a channel count.
1384  * Assumes a position mask for mono and stereo, or an index mask for channel counts > 2.
1385  * Returns the matching channel mask,
1386  * or AUDIO_CHANNEL_NONE if the channel count is zero,
1387  * or AUDIO_CHANNEL_INVALID if the channel count exceeds that of the
1388  * configurations for which a default input channel mask is defined.
1389  */
1390 static inline audio_channel_mask_t audio_channel_in_mask_from_count(uint32_t channel_count)
1391 {
1392     uint32_t bits;
1393     switch (channel_count) {
1394     case 0:
1395         return AUDIO_CHANNEL_NONE;
1396     case 1:
1397         bits = AUDIO_CHANNEL_IN_MONO;
1398         break;
1399     case 2:
1400         bits = AUDIO_CHANNEL_IN_STEREO;
1401         break;
1402     case 3:
1403     case 4:
1404     case 5:
1405     case 6:
1406     case 7:
1407     case 8:
1408         // FIXME FCC_8
1409         return audio_channel_mask_for_index_assignment_from_count(channel_count);
1410     default:
1411         return AUDIO_CHANNEL_INVALID;
1412     }
1413     return audio_channel_mask_from_representation_and_bits(
1414             AUDIO_CHANNEL_REPRESENTATION_POSITION, bits);
1415 }
1416
1417 static inline bool audio_is_valid_format(audio_format_t format)
1418 {
1419     switch (format & AUDIO_FORMAT_MAIN_MASK) {
1420     case AUDIO_FORMAT_PCM:
1421         switch (format) {
1422         case AUDIO_FORMAT_PCM_16_BIT:
1423         case AUDIO_FORMAT_PCM_8_BIT:
1424         case AUDIO_FORMAT_PCM_32_BIT:
1425         case AUDIO_FORMAT_PCM_8_24_BIT:
1426         case AUDIO_FORMAT_PCM_FLOAT:
1427         case AUDIO_FORMAT_PCM_24_BIT_PACKED:
1428             return true;
1429         default:
1430             return false;
1431         }
1432         /* not reached */
1433     case AUDIO_FORMAT_MP3:
1434     case AUDIO_FORMAT_AMR_NB:
1435     case AUDIO_FORMAT_AMR_WB:
1436     case AUDIO_FORMAT_AAC:
1437     case AUDIO_FORMAT_HE_AAC_V1:
1438     case AUDIO_FORMAT_HE_AAC_V2:
1439     case AUDIO_FORMAT_VORBIS:
1440     case AUDIO_FORMAT_OPUS:
1441     case AUDIO_FORMAT_AC3:
1442     case AUDIO_FORMAT_E_AC3:
1443     case AUDIO_FORMAT_DTS:
1444     case AUDIO_FORMAT_DTS_HD:
1445     case AUDIO_FORMAT_IEC61937:
1446     case AUDIO_FORMAT_DOLBY_TRUEHD:
1447         return true;
1448     default:
1449         return false;
1450     }
1451 }
1452
1453 /**
1454  * Extract the primary format, eg. PCM, AC3, etc.
1455  */
1456 static inline audio_format_t audio_get_main_format(audio_format_t format)
1457 {
1458     return (audio_format_t)(format & AUDIO_FORMAT_MAIN_MASK);
1459 }
1460
1461 /**
1462  * Is the data plain PCM samples that can be scaled and mixed?
1463  */
1464 static inline bool audio_is_linear_pcm(audio_format_t format)
1465 {
1466     return (audio_get_main_format(format) == AUDIO_FORMAT_PCM);
1467 }
1468
1469 /**
1470  * For this format, is the number of PCM audio frames directly proportional
1471  * to the number of data bytes?
1472  *
1473  * In other words, is the format transported as PCM audio samples,
1474  * but not necessarily scalable or mixable.
1475  * This returns true for real PCM, but also for AUDIO_FORMAT_IEC61937,
1476  * which is transported as 16 bit PCM audio, but where the encoded data
1477  * cannot be mixed or scaled.
1478  */
1479 static inline bool audio_has_proportional_frames(audio_format_t format)
1480 {
1481     audio_format_t mainFormat = audio_get_main_format(format);
1482     return (mainFormat == AUDIO_FORMAT_PCM
1483             || mainFormat == AUDIO_FORMAT_IEC61937);
1484 }
1485
1486 static inline size_t audio_bytes_per_sample(audio_format_t format)
1487 {
1488     size_t size = 0;
1489
1490     switch (format) {
1491     case AUDIO_FORMAT_PCM_32_BIT:
1492     case AUDIO_FORMAT_PCM_8_24_BIT:
1493         size = sizeof(int32_t);
1494         break;
1495     case AUDIO_FORMAT_PCM_24_BIT_PACKED:
1496         size = sizeof(uint8_t) * 3;
1497         break;
1498     case AUDIO_FORMAT_PCM_16_BIT:
1499     case AUDIO_FORMAT_IEC61937:
1500         size = sizeof(int16_t);
1501         break;
1502     case AUDIO_FORMAT_PCM_8_BIT:
1503         size = sizeof(uint8_t);
1504         break;
1505     case AUDIO_FORMAT_PCM_FLOAT:
1506         size = sizeof(float);
1507         break;
1508     default:
1509         break;
1510     }
1511     return size;
1512 }
1513
1514 /* converts device address to string sent to audio HAL via set_parameters */
1515 static inline char *audio_device_address_to_parameter(audio_devices_t device, const char *address)
1516 {
1517     const size_t kSize = AUDIO_DEVICE_MAX_ADDRESS_LEN + sizeof("a2dp_sink_address=");
1518     char param[kSize];
1519
1520     if (device & AUDIO_DEVICE_OUT_ALL_A2DP)
1521         snprintf(param, kSize, "%s=%s", "a2dp_sink_address", address);
1522     else if (device & AUDIO_DEVICE_OUT_REMOTE_SUBMIX)
1523         snprintf(param, kSize, "%s=%s", "mix", address);
1524     else
1525         snprintf(param, kSize, "%s", address);
1526
1527     return strdup(param);
1528 }
1529
1530 static inline bool audio_device_is_digital(audio_devices_t device) {
1531     if ((device & AUDIO_DEVICE_BIT_IN) != 0) {
1532         // input
1533         return (~AUDIO_DEVICE_BIT_IN & device & (AUDIO_DEVICE_IN_ALL_USB |
1534                           AUDIO_DEVICE_IN_HDMI |
1535                           AUDIO_DEVICE_IN_SPDIF |
1536                           AUDIO_DEVICE_IN_IP |
1537                           AUDIO_DEVICE_IN_BUS)) != 0;
1538     } else {
1539         // output
1540         return (device & (AUDIO_DEVICE_OUT_ALL_USB |
1541                           AUDIO_DEVICE_OUT_HDMI |
1542                           AUDIO_DEVICE_OUT_HDMI_ARC |
1543                           AUDIO_DEVICE_OUT_SPDIF |
1544                           AUDIO_DEVICE_OUT_IP |
1545                           AUDIO_DEVICE_OUT_BUS)) != 0;
1546     }
1547 }
1548
1549 __END_DECLS
1550
1551 #endif  // ANDROID_AUDIO_CORE_H