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_MAIN_MASK           = 0xFF000000UL, /* Deprecated. Use audio_get_main_format() */
 320     AUDIO_FORMAT_SUB_MASK            = 0x00FFFFFFUL,
 321
 322     /* Aliases */
 323     /* note != AudioFormat.ENCODING_PCM_16BIT */
 324     AUDIO_FORMAT_PCM_16_BIT          = (AUDIO_FORMAT_PCM |
 325                                         AUDIO_FORMAT_PCM_SUB_16_BIT),
 326     /* note != AudioFormat.ENCODING_PCM_8BIT */
 327     AUDIO_FORMAT_PCM_8_BIT           = (AUDIO_FORMAT_PCM |
 328                                         AUDIO_FORMAT_PCM_SUB_8_BIT),
 329     AUDIO_FORMAT_PCM_32_BIT          = (AUDIO_FORMAT_PCM |
 330                                         AUDIO_FORMAT_PCM_SUB_32_BIT),
 331     AUDIO_FORMAT_PCM_8_24_BIT        = (AUDIO_FORMAT_PCM |
 332                                         AUDIO_FORMAT_PCM_SUB_8_24_BIT),
 333     AUDIO_FORMAT_PCM_FLOAT           = (AUDIO_FORMAT_PCM |
 334                                         AUDIO_FORMAT_PCM_SUB_FLOAT),
 335     AUDIO_FORMAT_PCM_24_BIT_PACKED   = (AUDIO_FORMAT_PCM |
 336                                         AUDIO_FORMAT_PCM_SUB_24_BIT_PACKED),
 337     AUDIO_FORMAT_AAC_MAIN            = (AUDIO_FORMAT_AAC |
 338                                         AUDIO_FORMAT_AAC_SUB_MAIN),
 339     AUDIO_FORMAT_AAC_LC              = (AUDIO_FORMAT_AAC |
 340                                         AUDIO_FORMAT_AAC_SUB_LC),
 341     AUDIO_FORMAT_AAC_SSR             = (AUDIO_FORMAT_AAC |
 342                                         AUDIO_FORMAT_AAC_SUB_SSR),
 343     AUDIO_FORMAT_AAC_LTP             = (AUDIO_FORMAT_AAC |
 344                                         AUDIO_FORMAT_AAC_SUB_LTP),
 345     AUDIO_FORMAT_AAC_HE_V1           = (AUDIO_FORMAT_AAC |
 346                                         AUDIO_FORMAT_AAC_SUB_HE_V1),
 347     AUDIO_FORMAT_AAC_SCALABLE        = (AUDIO_FORMAT_AAC |
 348                                         AUDIO_FORMAT_AAC_SUB_SCALABLE),
 349     AUDIO_FORMAT_AAC_ERLC            = (AUDIO_FORMAT_AAC |
 350                                         AUDIO_FORMAT_AAC_SUB_ERLC),
 351     AUDIO_FORMAT_AAC_LD              = (AUDIO_FORMAT_AAC |
 352                                         AUDIO_FORMAT_AAC_SUB_LD),
 353     AUDIO_FORMAT_AAC_HE_V2           = (AUDIO_FORMAT_AAC |
 354                                         AUDIO_FORMAT_AAC_SUB_HE_V2),
 355     AUDIO_FORMAT_AAC_ELD             = (AUDIO_FORMAT_AAC |
 356                                         AUDIO_FORMAT_AAC_SUB_ELD),
 357 } audio_format_t;
 358
 359 /* For the channel mask for position assignment representation */
 360 enum {
 361
 362 /* These can be a complete audio_channel_mask_t. */
 363
 364     AUDIO_CHANNEL_NONE                      = 0x0,
 365     AUDIO_CHANNEL_INVALID                   = 0xC0000000,
 366
 367 /* These can be the bits portion of an audio_channel_mask_t
 368  * with representation AUDIO_CHANNEL_REPRESENTATION_POSITION.
 369  * Using these bits as a complete audio_channel_mask_t is deprecated.
 370  */
 371
 372     /* output channels */
 373     AUDIO_CHANNEL_OUT_FRONT_LEFT            = 0x1,
 374     AUDIO_CHANNEL_OUT_FRONT_RIGHT           = 0x2,
 375     AUDIO_CHANNEL_OUT_FRONT_CENTER          = 0x4,
 376     AUDIO_CHANNEL_OUT_LOW_FREQUENCY         = 0x8,
 377     AUDIO_CHANNEL_OUT_BACK_LEFT             = 0x10,
 378     AUDIO_CHANNEL_OUT_BACK_RIGHT            = 0x20,
 379     AUDIO_CHANNEL_OUT_FRONT_LEFT_OF_CENTER  = 0x40,
 380     AUDIO_CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = 0x80,
 381     AUDIO_CHANNEL_OUT_BACK_CENTER           = 0x100,
 382     AUDIO_CHANNEL_OUT_SIDE_LEFT             = 0x200,
 383     AUDIO_CHANNEL_OUT_SIDE_RIGHT            = 0x400,
 384     AUDIO_CHANNEL_OUT_TOP_CENTER            = 0x800,
 385     AUDIO_CHANNEL_OUT_TOP_FRONT_LEFT        = 0x1000,
 386     AUDIO_CHANNEL_OUT_TOP_FRONT_CENTER      = 0x2000,
 387     AUDIO_CHANNEL_OUT_TOP_FRONT_RIGHT       = 0x4000,
 388     AUDIO_CHANNEL_OUT_TOP_BACK_LEFT         = 0x8000,
 389     AUDIO_CHANNEL_OUT_TOP_BACK_CENTER       = 0x10000,
 390     AUDIO_CHANNEL_OUT_TOP_BACK_RIGHT        = 0x20000,
 391
 392 /* TODO: should these be considered complete channel masks, or only bits? */
 393
 394     AUDIO_CHANNEL_OUT_MONO     = AUDIO_CHANNEL_OUT_FRONT_LEFT,
 395     AUDIO_CHANNEL_OUT_STEREO   = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 396                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT),
 397     AUDIO_CHANNEL_OUT_QUAD     = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 398                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 399                                   AUDIO_CHANNEL_OUT_BACK_LEFT |
 400                                   AUDIO_CHANNEL_OUT_BACK_RIGHT),
 401     AUDIO_CHANNEL_OUT_QUAD_BACK = AUDIO_CHANNEL_OUT_QUAD,
 402     /* like AUDIO_CHANNEL_OUT_QUAD_BACK with *_SIDE_* instead of *_BACK_* */
 403     AUDIO_CHANNEL_OUT_QUAD_SIDE = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 404                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 405                                   AUDIO_CHANNEL_OUT_SIDE_LEFT |
 406                                   AUDIO_CHANNEL_OUT_SIDE_RIGHT),
 407     AUDIO_CHANNEL_OUT_5POINT1  = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 408                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 409                                   AUDIO_CHANNEL_OUT_FRONT_CENTER |
 410                                   AUDIO_CHANNEL_OUT_LOW_FREQUENCY |
 411                                   AUDIO_CHANNEL_OUT_BACK_LEFT |
 412                                   AUDIO_CHANNEL_OUT_BACK_RIGHT),
 413     AUDIO_CHANNEL_OUT_5POINT1_BACK = AUDIO_CHANNEL_OUT_5POINT1,
 414     /* like AUDIO_CHANNEL_OUT_5POINT1_BACK with *_SIDE_* instead of *_BACK_* */
 415     AUDIO_CHANNEL_OUT_5POINT1_SIDE = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 416                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 417                                   AUDIO_CHANNEL_OUT_FRONT_CENTER |
 418                                   AUDIO_CHANNEL_OUT_LOW_FREQUENCY |
 419                                   AUDIO_CHANNEL_OUT_SIDE_LEFT |
 420                                   AUDIO_CHANNEL_OUT_SIDE_RIGHT),
 421     // matches the correct AudioFormat.CHANNEL_OUT_7POINT1_SURROUND definition for 7.1
 422     AUDIO_CHANNEL_OUT_7POINT1  = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 423                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 424                                   AUDIO_CHANNEL_OUT_FRONT_CENTER |
 425                                   AUDIO_CHANNEL_OUT_LOW_FREQUENCY |
 426                                   AUDIO_CHANNEL_OUT_BACK_LEFT |
 427                                   AUDIO_CHANNEL_OUT_BACK_RIGHT |
 428                                   AUDIO_CHANNEL_OUT_SIDE_LEFT |
 429                                   AUDIO_CHANNEL_OUT_SIDE_RIGHT),
 430     AUDIO_CHANNEL_OUT_ALL      = (AUDIO_CHANNEL_OUT_FRONT_LEFT |
 431                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT |
 432                                   AUDIO_CHANNEL_OUT_FRONT_CENTER |
 433                                   AUDIO_CHANNEL_OUT_LOW_FREQUENCY |
 434                                   AUDIO_CHANNEL_OUT_BACK_LEFT |
 435                                   AUDIO_CHANNEL_OUT_BACK_RIGHT |
 436                                   AUDIO_CHANNEL_OUT_FRONT_LEFT_OF_CENTER |
 437                                   AUDIO_CHANNEL_OUT_FRONT_RIGHT_OF_CENTER |
 438                                   AUDIO_CHANNEL_OUT_BACK_CENTER|
 439                                   AUDIO_CHANNEL_OUT_SIDE_LEFT|
 440                                   AUDIO_CHANNEL_OUT_SIDE_RIGHT|
 441                                   AUDIO_CHANNEL_OUT_TOP_CENTER|
 442                                   AUDIO_CHANNEL_OUT_TOP_FRONT_LEFT|
 443                                   AUDIO_CHANNEL_OUT_TOP_FRONT_CENTER|
 444                                   AUDIO_CHANNEL_OUT_TOP_FRONT_RIGHT|
 445                                   AUDIO_CHANNEL_OUT_TOP_BACK_LEFT|
 446                                   AUDIO_CHANNEL_OUT_TOP_BACK_CENTER|
 447                                   AUDIO_CHANNEL_OUT_TOP_BACK_RIGHT),
 448
 449 /* These are bits only, not complete values */
 450
 451     /* input channels */
 452     AUDIO_CHANNEL_IN_LEFT            = 0x4,
 453     AUDIO_CHANNEL_IN_RIGHT           = 0x8,
 454     AUDIO_CHANNEL_IN_FRONT           = 0x10,
 455     AUDIO_CHANNEL_IN_BACK            = 0x20,
 456     AUDIO_CHANNEL_IN_LEFT_PROCESSED  = 0x40,
 457     AUDIO_CHANNEL_IN_RIGHT_PROCESSED = 0x80,
 458     AUDIO_CHANNEL_IN_FRONT_PROCESSED = 0x100,
 459     AUDIO_CHANNEL_IN_BACK_PROCESSED  = 0x200,
 460     AUDIO_CHANNEL_IN_PRESSURE        = 0x400,
 461     AUDIO_CHANNEL_IN_X_AXIS          = 0x800,
 462     AUDIO_CHANNEL_IN_Y_AXIS          = 0x1000,
 463     AUDIO_CHANNEL_IN_Z_AXIS          = 0x2000,
 464     AUDIO_CHANNEL_IN_VOICE_UPLINK    = 0x4000,
 465     AUDIO_CHANNEL_IN_VOICE_DNLINK    = 0x8000,
 466
 467 /* TODO: should these be considered complete channel masks, or only bits, or deprecated? */
 468
 469     AUDIO_CHANNEL_IN_MONO   = AUDIO_CHANNEL_IN_FRONT,
 470     AUDIO_CHANNEL_IN_STEREO = (AUDIO_CHANNEL_IN_LEFT | AUDIO_CHANNEL_IN_RIGHT),
 471     AUDIO_CHANNEL_IN_FRONT_BACK = (AUDIO_CHANNEL_IN_FRONT | AUDIO_CHANNEL_IN_BACK),
 472     AUDIO_CHANNEL_IN_ALL    = (AUDIO_CHANNEL_IN_LEFT |
 473                                AUDIO_CHANNEL_IN_RIGHT |
 474                                AUDIO_CHANNEL_IN_FRONT |
 475                                AUDIO_CHANNEL_IN_BACK|
 476                                AUDIO_CHANNEL_IN_LEFT_PROCESSED |
 477                                AUDIO_CHANNEL_IN_RIGHT_PROCESSED |
 478                                AUDIO_CHANNEL_IN_FRONT_PROCESSED |
 479                                AUDIO_CHANNEL_IN_BACK_PROCESSED|
 480                                AUDIO_CHANNEL_IN_PRESSURE |
 481                                AUDIO_CHANNEL_IN_X_AXIS |
 482                                AUDIO_CHANNEL_IN_Y_AXIS |
 483                                AUDIO_CHANNEL_IN_Z_AXIS |
 484                                AUDIO_CHANNEL_IN_VOICE_UPLINK |
 485                                AUDIO_CHANNEL_IN_VOICE_DNLINK),
 486 };
 487
 488 /* A channel mask per se only defines the presence or absence of a channel, not the order.
 489  * But see AUDIO_INTERLEAVE_* below for the platform convention of order.
 490  *
 491  * audio_channel_mask_t is an opaque type and its internal layout should not
 492  * be assumed as it may change in the future.
 493  * Instead, always use the functions declared in this header to examine.
 494  *
 495  * These are the current representations:
 496  *
 497  *   AUDIO_CHANNEL_REPRESENTATION_POSITION
 498  *     is a channel mask representation for position assignment.
 499  *     Each low-order bit corresponds to the spatial position of a transducer (output),
 500  *     or interpretation of channel (input).
 501  *     The user of a channel mask needs to know the context of whether it is for output or input.
 502  *     The constants AUDIO_CHANNEL_OUT_* or AUDIO_CHANNEL_IN_* apply to the bits portion.
 503  *     It is not permitted for no bits to be set.
 504  *
 505  *   AUDIO_CHANNEL_REPRESENTATION_INDEX
 506  *     is a channel mask representation for index assignment.
 507  *     Each low-order bit corresponds to a selected channel.
 508  *     There is no platform interpretation of the various bits.
 509  *     There is no concept of output or input.
 510  *     It is not permitted for no bits to be set.
 511  *
 512  * All other representations are reserved for future use.
 513  *
 514  * Warning: current representation distinguishes between input and output, but this will not the be
 515  * case in future revisions of the platform. Wherever there is an ambiguity between input and output
 516  * that is currently resolved by checking the channel mask, the implementer should look for ways to
 517  * fix it with additional information outside of the mask.
 518  */
 519 typedef uint32_t audio_channel_mask_t;
 520
 521 /* Maximum number of channels for all representations */
 522 #define AUDIO_CHANNEL_COUNT_MAX             30
 523
 524 /* log(2) of maximum number of representations, not part of public API */
 525 #define AUDIO_CHANNEL_REPRESENTATION_LOG2   2
 526
 527 /* Representations */
 528 typedef enum {
 529     AUDIO_CHANNEL_REPRESENTATION_POSITION    = 0,    // must be zero for compatibility
 530     // 1 is reserved for future use
 531     AUDIO_CHANNEL_REPRESENTATION_INDEX       = 2,
 532     // 3 is reserved for future use
 533 } audio_channel_representation_t;
 534
 535 /* The channel index masks defined here are the canonical masks for 1 to 8 channel
 536  * endpoints and apply to both source and sink.
 537  */
 538 enum {
 539     AUDIO_CHANNEL_INDEX_HDR  = AUDIO_CHANNEL_REPRESENTATION_INDEX << AUDIO_CHANNEL_COUNT_MAX,
 540     AUDIO_CHANNEL_INDEX_MASK_1 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 1) - 1),
 541     AUDIO_CHANNEL_INDEX_MASK_2 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 2) - 1),
 542     AUDIO_CHANNEL_INDEX_MASK_3 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 3) - 1),
 543     AUDIO_CHANNEL_INDEX_MASK_4 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 4) - 1),
 544     AUDIO_CHANNEL_INDEX_MASK_5 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 5) - 1),
 545     AUDIO_CHANNEL_INDEX_MASK_6 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 6) - 1),
 546     AUDIO_CHANNEL_INDEX_MASK_7 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 7) - 1),
 547     AUDIO_CHANNEL_INDEX_MASK_8 =  AUDIO_CHANNEL_INDEX_HDR | ((1 << 8) - 1),
 548     // FIXME FCC_8
 549 };
 550
 551 /* The return value is undefined if the channel mask is invalid. */
 552 static inline uint32_t audio_channel_mask_get_bits(audio_channel_mask_t channel)
 553 {
 554     return channel & ((1 << AUDIO_CHANNEL_COUNT_MAX) - 1);
 555 }
 556
 557 /* The return value is undefined if the channel mask is invalid. */
 558 static inline audio_channel_representation_t audio_channel_mask_get_representation(
 559         audio_channel_mask_t channel)
 560 {
 561     // The right shift should be sufficient, but also "and" for safety in case mask is not 32 bits
 562     return (audio_channel_representation_t)
 563             ((channel >> AUDIO_CHANNEL_COUNT_MAX) & ((1 << AUDIO_CHANNEL_REPRESENTATION_LOG2) - 1));
 564 }
 565
 566 /* Returns true if the channel mask is valid,
 567  * or returns false for AUDIO_CHANNEL_NONE, AUDIO_CHANNEL_INVALID, and other invalid values.
 568  * This function is unable to determine whether a channel mask for position assignment
 569  * is invalid because an output mask has an invalid output bit set,
 570  * or because an input mask has an invalid input bit set.
 571  * All other APIs that take a channel mask assume that it is valid.
 572  */
 573 static inline bool audio_channel_mask_is_valid(audio_channel_mask_t channel)
 574 {
 575     uint32_t bits = audio_channel_mask_get_bits(channel);
 576     audio_channel_representation_t representation = audio_channel_mask_get_representation(channel);
 577     switch (representation) {
 578     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
 579     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
 580         break;
 581     default:
 582         bits = 0;
 583         break;
 584     }
 585     return bits != 0;
 586 }
 587
 588 /* Not part of public API */
 589 static inline audio_channel_mask_t audio_channel_mask_from_representation_and_bits(
 590         audio_channel_representation_t representation, uint32_t bits)
 591 {
 592     return (audio_channel_mask_t) ((representation << AUDIO_CHANNEL_COUNT_MAX) | bits);
 593 }
 594
 595 /* Expresses the convention when stereo audio samples are stored interleaved
 596  * in an array.  This should improve readability by allowing code to use
 597  * symbolic indices instead of hard-coded [0] and [1].
 598  *
 599  * For multi-channel beyond stereo, the platform convention is that channels
 600  * are interleaved in order from least significant channel mask bit
 601  * to most significant channel mask bit, with unused bits skipped.
 602  * Any exceptions to this convention will be noted at the appropriate API.
 603  */
 604 enum {
 605     AUDIO_INTERLEAVE_LEFT   = 0,
 606     AUDIO_INTERLEAVE_RIGHT  = 1,
 607 };
 608
 609 typedef enum {
 610     AUDIO_MODE_INVALID          = -2,
 611     AUDIO_MODE_CURRENT          = -1,
 612     AUDIO_MODE_NORMAL           = 0,
 613     AUDIO_MODE_RINGTONE         = 1,
 614     AUDIO_MODE_IN_CALL          = 2,
 615     AUDIO_MODE_IN_COMMUNICATION = 3,
 616
 617     AUDIO_MODE_CNT,
 618     AUDIO_MODE_MAX              = AUDIO_MODE_CNT - 1,
 619 } audio_mode_t;
 620
 621 /* This enum is deprecated */
 622 typedef enum {
 623     AUDIO_IN_ACOUSTICS_NONE          = 0,
 624     AUDIO_IN_ACOUSTICS_AGC_ENABLE    = 0x0001,
 625     AUDIO_IN_ACOUSTICS_AGC_DISABLE   = 0,
 626     AUDIO_IN_ACOUSTICS_NS_ENABLE     = 0x0002,
 627     AUDIO_IN_ACOUSTICS_NS_DISABLE    = 0,
 628     AUDIO_IN_ACOUSTICS_TX_IIR_ENABLE = 0x0004,
 629     AUDIO_IN_ACOUSTICS_TX_DISABLE    = 0,
 630 } audio_in_acoustics_t;
 631
 632 enum {
 633     AUDIO_DEVICE_NONE                          = 0x0,
 634     /* reserved bits */
 635     AUDIO_DEVICE_BIT_IN                        = 0x80000000,
 636     AUDIO_DEVICE_BIT_DEFAULT                   = 0x40000000,
 637     /* output devices */
 638     AUDIO_DEVICE_OUT_EARPIECE                  = 0x1,
 639     AUDIO_DEVICE_OUT_SPEAKER                   = 0x2,
 640     AUDIO_DEVICE_OUT_WIRED_HEADSET             = 0x4,
 641     AUDIO_DEVICE_OUT_WIRED_HEADPHONE           = 0x8,
 642     AUDIO_DEVICE_OUT_BLUETOOTH_SCO             = 0x10,
 643     AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET     = 0x20,
 644     AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT      = 0x40,
 645     AUDIO_DEVICE_OUT_BLUETOOTH_A2DP            = 0x80,
 646     AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES = 0x100,
 647     AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER    = 0x200,
 648     AUDIO_DEVICE_OUT_AUX_DIGITAL               = 0x400,
 649     AUDIO_DEVICE_OUT_HDMI                      = AUDIO_DEVICE_OUT_AUX_DIGITAL,
 650     /* uses an analog connection (multiplexed over the USB connector pins for instance) */
 651     AUDIO_DEVICE_OUT_ANLG_DOCK_HEADSET         = 0x800,
 652     AUDIO_DEVICE_OUT_DGTL_DOCK_HEADSET         = 0x1000,
 653     /* USB accessory mode: your Android device is a USB device and the dock is a USB host */
 654     AUDIO_DEVICE_OUT_USB_ACCESSORY             = 0x2000,
 655     /* USB host mode: your Android device is a USB host and the dock is a USB device */
 656     AUDIO_DEVICE_OUT_USB_DEVICE                = 0x4000,
 657     AUDIO_DEVICE_OUT_REMOTE_SUBMIX             = 0x8000,
 658     /* Telephony voice TX path */
 659     AUDIO_DEVICE_OUT_TELEPHONY_TX              = 0x10000,
 660     /* Analog jack with line impedance detected */
 661     AUDIO_DEVICE_OUT_LINE                      = 0x20000,
 662     /* HDMI Audio Return Channel */
 663     AUDIO_DEVICE_OUT_HDMI_ARC                  = 0x40000,
 664     /* S/PDIF out */
 665     AUDIO_DEVICE_OUT_SPDIF                     = 0x80000,
 666     /* FM transmitter out */
 667     AUDIO_DEVICE_OUT_FM                        = 0x100000,
 668     /* Line out for av devices */
 669     AUDIO_DEVICE_OUT_AUX_LINE                  = 0x200000,
 670     /* limited-output speaker device for acoustic safety */
 671     AUDIO_DEVICE_OUT_SPEAKER_SAFE              = 0x400000,
 672     AUDIO_DEVICE_OUT_IP                        = 0x800000,
 673     /* audio bus implemented by the audio system (e.g an MOST stereo channel) */
 674     AUDIO_DEVICE_OUT_BUS                       = 0x1000000,
 675     AUDIO_DEVICE_OUT_DEFAULT                   = AUDIO_DEVICE_BIT_DEFAULT,
 676     AUDIO_DEVICE_OUT_ALL      = (AUDIO_DEVICE_OUT_EARPIECE |
 677                                  AUDIO_DEVICE_OUT_SPEAKER |
 678                                  AUDIO_DEVICE_OUT_WIRED_HEADSET |
 679                                  AUDIO_DEVICE_OUT_WIRED_HEADPHONE |
 680                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO |
 681                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET |
 682                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT |
 683                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP |
 684                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES |
 685                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER |
 686                                  AUDIO_DEVICE_OUT_HDMI |
 687                                  AUDIO_DEVICE_OUT_ANLG_DOCK_HEADSET |
 688                                  AUDIO_DEVICE_OUT_DGTL_DOCK_HEADSET |
 689                                  AUDIO_DEVICE_OUT_USB_ACCESSORY |
 690                                  AUDIO_DEVICE_OUT_USB_DEVICE |
 691                                  AUDIO_DEVICE_OUT_REMOTE_SUBMIX |
 692                                  AUDIO_DEVICE_OUT_TELEPHONY_TX |
 693                                  AUDIO_DEVICE_OUT_LINE |
 694                                  AUDIO_DEVICE_OUT_HDMI_ARC |
 695                                  AUDIO_DEVICE_OUT_SPDIF |
 696                                  AUDIO_DEVICE_OUT_FM |
 697                                  AUDIO_DEVICE_OUT_AUX_LINE |
 698                                  AUDIO_DEVICE_OUT_SPEAKER_SAFE |
 699                                  AUDIO_DEVICE_OUT_IP |
 700                                  AUDIO_DEVICE_OUT_BUS |
 701                                  AUDIO_DEVICE_OUT_DEFAULT),
 702     AUDIO_DEVICE_OUT_ALL_A2DP = (AUDIO_DEVICE_OUT_BLUETOOTH_A2DP |
 703                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES |
 704                                  AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER),
 705     AUDIO_DEVICE_OUT_ALL_SCO  = (AUDIO_DEVICE_OUT_BLUETOOTH_SCO |
 706                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET |
 707                                  AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT),
 708     AUDIO_DEVICE_OUT_ALL_USB  = (AUDIO_DEVICE_OUT_USB_ACCESSORY |
 709                                  AUDIO_DEVICE_OUT_USB_DEVICE),
 710     /* input devices */
 711     AUDIO_DEVICE_IN_COMMUNICATION         = AUDIO_DEVICE_BIT_IN | 0x1,
 712     AUDIO_DEVICE_IN_AMBIENT               = AUDIO_DEVICE_BIT_IN | 0x2,
 713     AUDIO_DEVICE_IN_BUILTIN_MIC           = AUDIO_DEVICE_BIT_IN | 0x4,
 714     AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET = AUDIO_DEVICE_BIT_IN | 0x8,
 715     AUDIO_DEVICE_IN_WIRED_HEADSET         = AUDIO_DEVICE_BIT_IN | 0x10,
 716     AUDIO_DEVICE_IN_AUX_DIGITAL           = AUDIO_DEVICE_BIT_IN | 0x20,
 717     AUDIO_DEVICE_IN_HDMI                  = AUDIO_DEVICE_IN_AUX_DIGITAL,
 718     /* Telephony voice RX path */
 719     AUDIO_DEVICE_IN_VOICE_CALL            = AUDIO_DEVICE_BIT_IN | 0x40,
 720     AUDIO_DEVICE_IN_TELEPHONY_RX          = AUDIO_DEVICE_IN_VOICE_CALL,
 721     AUDIO_DEVICE_IN_BACK_MIC              = AUDIO_DEVICE_BIT_IN | 0x80,
 722     AUDIO_DEVICE_IN_REMOTE_SUBMIX         = AUDIO_DEVICE_BIT_IN | 0x100,
 723     AUDIO_DEVICE_IN_ANLG_DOCK_HEADSET     = AUDIO_DEVICE_BIT_IN | 0x200,
 724     AUDIO_DEVICE_IN_DGTL_DOCK_HEADSET     = AUDIO_DEVICE_BIT_IN | 0x400,
 725     AUDIO_DEVICE_IN_USB_ACCESSORY         = AUDIO_DEVICE_BIT_IN | 0x800,
 726     AUDIO_DEVICE_IN_USB_DEVICE            = AUDIO_DEVICE_BIT_IN | 0x1000,
 727     /* FM tuner input */
 728     AUDIO_DEVICE_IN_FM_TUNER              = AUDIO_DEVICE_BIT_IN | 0x2000,
 729     /* TV tuner input */
 730     AUDIO_DEVICE_IN_TV_TUNER              = AUDIO_DEVICE_BIT_IN | 0x4000,
 731     /* Analog jack with line impedance detected */
 732     AUDIO_DEVICE_IN_LINE                  = AUDIO_DEVICE_BIT_IN | 0x8000,
 733     /* S/PDIF in */
 734     AUDIO_DEVICE_IN_SPDIF                 = AUDIO_DEVICE_BIT_IN | 0x10000,
 735     AUDIO_DEVICE_IN_BLUETOOTH_A2DP        = AUDIO_DEVICE_BIT_IN | 0x20000,
 736     AUDIO_DEVICE_IN_LOOPBACK              = AUDIO_DEVICE_BIT_IN | 0x40000,
 737     AUDIO_DEVICE_IN_IP                    = AUDIO_DEVICE_BIT_IN | 0x80000,
 738     /* audio bus implemented by the audio system (e.g an MOST stereo channel) */
 739     AUDIO_DEVICE_IN_BUS                   = AUDIO_DEVICE_BIT_IN | 0x100000,
 740     AUDIO_DEVICE_IN_DEFAULT               = AUDIO_DEVICE_BIT_IN | AUDIO_DEVICE_BIT_DEFAULT,
 741
 742     AUDIO_DEVICE_IN_ALL     = (AUDIO_DEVICE_IN_COMMUNICATION |
 743                                AUDIO_DEVICE_IN_AMBIENT |
 744                                AUDIO_DEVICE_IN_BUILTIN_MIC |
 745                                AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET |
 746                                AUDIO_DEVICE_IN_WIRED_HEADSET |
 747                                AUDIO_DEVICE_IN_HDMI |
 748                                AUDIO_DEVICE_IN_TELEPHONY_RX |
 749                                AUDIO_DEVICE_IN_BACK_MIC |
 750                                AUDIO_DEVICE_IN_REMOTE_SUBMIX |
 751                                AUDIO_DEVICE_IN_ANLG_DOCK_HEADSET |
 752                                AUDIO_DEVICE_IN_DGTL_DOCK_HEADSET |
 753                                AUDIO_DEVICE_IN_USB_ACCESSORY |
 754                                AUDIO_DEVICE_IN_USB_DEVICE |
 755                                AUDIO_DEVICE_IN_FM_TUNER |
 756                                AUDIO_DEVICE_IN_TV_TUNER |
 757                                AUDIO_DEVICE_IN_LINE |
 758                                AUDIO_DEVICE_IN_SPDIF |
 759                                AUDIO_DEVICE_IN_BLUETOOTH_A2DP |
 760                                AUDIO_DEVICE_IN_LOOPBACK |
 761                                AUDIO_DEVICE_IN_IP |
 762                                AUDIO_DEVICE_IN_BUS |
 763                                AUDIO_DEVICE_IN_DEFAULT),
 764     AUDIO_DEVICE_IN_ALL_SCO = AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET,
 765     AUDIO_DEVICE_IN_ALL_USB  = (AUDIO_DEVICE_IN_USB_ACCESSORY |
 766                                 AUDIO_DEVICE_IN_USB_DEVICE),
 767 };
 768
 769 typedef uint32_t audio_devices_t;
 770
 771 /* the audio output flags serve two purposes:
 772  * - when an AudioTrack is created they indicate a "wish" to be connected to an
 773  * output stream with attributes corresponding to the specified flags
 774  * - when present in an output profile descriptor listed for a particular audio
 775  * hardware module, they indicate that an output stream can be opened that
 776  * supports the attributes indicated by the flags.
 777  * the audio policy manager will try to match the flags in the request
 778  * (when getOuput() is called) to an available output stream.
 779  */
 780 typedef enum {
 781     AUDIO_OUTPUT_FLAG_NONE = 0x0,       // no attributes
 782     AUDIO_OUTPUT_FLAG_DIRECT = 0x1,     // this output directly connects a track
 783                                         // to one output stream: no software mixer
 784     AUDIO_OUTPUT_FLAG_PRIMARY = 0x2,    // this output is the primary output of
 785                                         // the device. It is unique and must be
 786                                         // present. It is opened by default and
 787                                         // receives routing, audio mode and volume
 788                                         // controls related to voice calls.
 789     AUDIO_OUTPUT_FLAG_FAST = 0x4,       // output supports "fast tracks",
 790                                         // defined elsewhere
 791     AUDIO_OUTPUT_FLAG_DEEP_BUFFER = 0x8, // use deep audio buffers
 792     AUDIO_OUTPUT_FLAG_COMPRESS_OFFLOAD = 0x10,  // offload playback of compressed
 793                                                 // streams to hardware codec
 794     AUDIO_OUTPUT_FLAG_NON_BLOCKING = 0x20, // use non-blocking write
 795     AUDIO_OUTPUT_FLAG_HW_AV_SYNC = 0x40,   // output uses a hardware A/V synchronization source
 796     AUDIO_OUTPUT_FLAG_TTS = 0x80,          // output for streams transmitted through speaker
 797                                            // at a sample rate high enough to accommodate
 798                                            // lower-range ultrasonic playback
 799     AUDIO_OUTPUT_FLAG_RAW = 0x100,         // minimize signal processing
 800     AUDIO_OUTPUT_FLAG_SYNC = 0x200,        // synchronize I/O streams
 801
 802     AUDIO_OUTPUT_FLAG_IEC958_NONAUDIO = 0x400, // Audio stream contains compressed audio in
 803                                                // SPDIF data bursts, not PCM.
 804 } audio_output_flags_t;
 805
 806 /* The audio input flags are analogous to audio output flags.
 807  * Currently they are used only when an AudioRecord is created,
 808  * to indicate a preference to be connected to an input stream with
 809  * attributes corresponding to the specified flags.
 810  */
 811 typedef enum {
 812     AUDIO_INPUT_FLAG_NONE       = 0x0,  // no attributes
 813     AUDIO_INPUT_FLAG_FAST       = 0x1,  // prefer an input that supports "fast tracks"
 814     AUDIO_INPUT_FLAG_HW_HOTWORD = 0x2,  // prefer an input that captures from hw hotword source
 815     AUDIO_INPUT_FLAG_RAW        = 0x4,  // minimize signal processing
 816     AUDIO_INPUT_FLAG_SYNC       = 0x8,  // synchronize I/O streams
 817
 818 } audio_input_flags_t;
 819
 820 /* Additional information about compressed streams offloaded to
 821  * hardware playback
 822  * The version and size fields must be initialized by the caller by using
 823  * one of the constants defined here.
 824  */
 825 typedef struct {
 826     uint16_t version;                   // version of the info structure
 827     uint16_t size;                      // total size of the structure including version and size
 828     uint32_t sample_rate;               // sample rate in Hz
 829     audio_channel_mask_t channel_mask;  // channel mask
 830     audio_format_t format;              // audio format
 831     audio_stream_type_t stream_type;    // stream type
 832     uint32_t bit_rate;                  // bit rate in bits per second
 833     int64_t duration_us;                // duration in microseconds, -1 if unknown
 834     bool has_video;                     // true if stream is tied to a video stream
 835     bool is_streaming;                  // true if streaming, false if local playback
 836 } audio_offload_info_t;
 837
 838 #define AUDIO_MAKE_OFFLOAD_INFO_VERSION(maj,min) \
 839             ((((maj) & 0xff) << 8) | ((min) & 0xff))
 840
 841 #define AUDIO_OFFLOAD_INFO_VERSION_0_1 AUDIO_MAKE_OFFLOAD_INFO_VERSION(0, 1)
 842 #define AUDIO_OFFLOAD_INFO_VERSION_CURRENT AUDIO_OFFLOAD_INFO_VERSION_0_1
 843
 844 static const audio_offload_info_t AUDIO_INFO_INITIALIZER = {
 845     version: AUDIO_OFFLOAD_INFO_VERSION_CURRENT,
 846     size: sizeof(audio_offload_info_t),
 847     sample_rate: 0,
 848     channel_mask: 0,
 849     format: AUDIO_FORMAT_DEFAULT,
 850     stream_type: AUDIO_STREAM_VOICE_CALL,
 851     bit_rate: 0,
 852     duration_us: 0,
 853     has_video: false,
 854     is_streaming: false
 855 };
 856
 857 /* common audio stream configuration parameters
 858  * You should memset() the entire structure to zero before use to
 859  * ensure forward compatibility
 860  */
 861 struct audio_config {
 862     uint32_t sample_rate;
 863     audio_channel_mask_t channel_mask;
 864     audio_format_t  format;
 865     audio_offload_info_t offload_info;
 866     size_t frame_count;
 867 };
 868 typedef struct audio_config audio_config_t;
 869
 870 static const audio_config_t AUDIO_CONFIG_INITIALIZER = {
 871     sample_rate: 0,
 872     channel_mask: AUDIO_CHANNEL_NONE,
 873     format: AUDIO_FORMAT_DEFAULT,
 874     offload_info: {
 875         version: AUDIO_OFFLOAD_INFO_VERSION_CURRENT,
 876         size: sizeof(audio_offload_info_t),
 877         sample_rate: 0,
 878         channel_mask: 0,
 879         format: AUDIO_FORMAT_DEFAULT,
 880         stream_type: AUDIO_STREAM_VOICE_CALL,
 881         bit_rate: 0,
 882         duration_us: 0,
 883         has_video: false,
 884         is_streaming: false
 885     },
 886     frame_count: 0,
 887 };
 888
 889 struct audio_config_base {
 890     uint32_t sample_rate;
 891     audio_channel_mask_t channel_mask;
 892     audio_format_t  format;
 893 };
 894
 895 typedef struct audio_config_base audio_config_base_t;
 896
 897 static const audio_config_base_t AUDIO_CONFIG_BASE_INITIALIZER = {
 898     sample_rate: 0,
 899     channel_mask: AUDIO_CHANNEL_NONE,
 900     format: AUDIO_FORMAT_DEFAULT
 901 };
 902
 903 /* audio hw module handle functions or structures referencing a module */
 904 typedef enum {
 905     AUDIO_MODULE_HANDLE_NONE = 0,
 906 } audio_module_handle_t;
 907
 908 /******************************
 909  *  Volume control
 910  *****************************/
 911
 912 /* If the audio hardware supports gain control on some audio paths,
 913  * the platform can expose them in the audio_policy.conf file. The audio HAL
 914  * will then implement gain control functions that will use the following data
 915  * structures. */
 916
 917 /* Type of gain control exposed by an audio port */
 918 #define AUDIO_GAIN_MODE_JOINT     0x1 /* supports joint channel gain control */
 919 #define AUDIO_GAIN_MODE_CHANNELS  0x2 /* supports separate channel gain control */
 920 #define AUDIO_GAIN_MODE_RAMP      0x4 /* supports gain ramps */
 921
 922 typedef uint32_t audio_gain_mode_t;
 923
 924
 925 /* An audio_gain struct is a representation of a gain stage.
 926  * A gain stage is always attached to an audio port. */
 927 struct audio_gain  {
 928     audio_gain_mode_t    mode;          /* e.g. AUDIO_GAIN_MODE_JOINT */
 929     audio_channel_mask_t channel_mask;  /* channels which gain an be controlled.
 930                                            N/A if AUDIO_GAIN_MODE_CHANNELS is not supported */
 931     int                  min_value;     /* minimum gain value in millibels */
 932     int                  max_value;     /* maximum gain value in millibels */
 933     int                  default_value; /* default gain value in millibels */
 934     unsigned int         step_value;    /* gain step in millibels */
 935     unsigned int         min_ramp_ms;   /* minimum ramp duration in ms */
 936     unsigned int         max_ramp_ms;   /* maximum ramp duration in ms */
 937 };
 938
 939 /* The gain configuration structure is used to get or set the gain values of a
 940  * given port */
 941 struct audio_gain_config  {
 942     int                  index;             /* index of the corresponding audio_gain in the
 943                                                audio_port gains[] table */
 944     audio_gain_mode_t    mode;              /* mode requested for this command */
 945     audio_channel_mask_t channel_mask;      /* channels which gain value follows.
 946                                                N/A in joint mode */
 947
 948     // note this "8" is not FCC_8, so it won't need to be changed for > 8 channels
 949     int                  values[sizeof(audio_channel_mask_t) * 8]; /* gain values in millibels
 950                                                for each channel ordered from LSb to MSb in
 951                                                channel mask. The number of values is 1 in joint
 952                                                mode or popcount(channel_mask) */
 953     unsigned int         ramp_duration_ms; /* ramp duration in ms */
 954 };
 955
 956 /******************************
 957  *  Routing control
 958  *****************************/
 959
 960 /* Types defined here are used to describe an audio source or sink at internal
 961  * framework interfaces (audio policy, patch panel) or at the audio HAL.
 962  * Sink and sources are grouped in a concept of “audio port” representing an
 963  * audio end point at the edge of the system managed by the module exposing
 964  * the interface. */
 965
 966 /* Audio port role: either source or sink */
 967 typedef enum {
 968     AUDIO_PORT_ROLE_NONE,
 969     AUDIO_PORT_ROLE_SOURCE,
 970     AUDIO_PORT_ROLE_SINK,
 971 } audio_port_role_t;
 972
 973 /* Audio port type indicates if it is a session (e.g AudioTrack),
 974  * a mix (e.g PlaybackThread output) or a physical device
 975  * (e.g AUDIO_DEVICE_OUT_SPEAKER) */
 976 typedef enum {
 977     AUDIO_PORT_TYPE_NONE,
 978     AUDIO_PORT_TYPE_DEVICE,
 979     AUDIO_PORT_TYPE_MIX,
 980     AUDIO_PORT_TYPE_SESSION,
 981 } audio_port_type_t;
 982
 983 /* Each port has a unique ID or handle allocated by policy manager */
 984 typedef int audio_port_handle_t;
 985 #define AUDIO_PORT_HANDLE_NONE 0
 986
 987 /* the maximum length for the human-readable device name */
 988 #define AUDIO_PORT_MAX_NAME_LEN 128
 989
 990 /* maximum audio device address length */
 991 #define AUDIO_DEVICE_MAX_ADDRESS_LEN 32
 992
 993 /* extension for audio port configuration structure when the audio port is a
 994  * hardware device */
 995 struct audio_port_config_device_ext {
 996     audio_module_handle_t hw_module;                /* module the device is attached to */
 997     audio_devices_t       type;                     /* device type (e.g AUDIO_DEVICE_OUT_SPEAKER) */
 998     char                  address[AUDIO_DEVICE_MAX_ADDRESS_LEN]; /* device address. "" if N/A */
 999 };
1000
1001 /* extension for audio port configuration structure when the audio port is a
1002  * sub mix */
1003 struct audio_port_config_mix_ext {
1004     audio_module_handle_t hw_module;    /* module the stream is attached to */
1005     audio_io_handle_t handle;           /* I/O handle of the input/output stream */
1006     union {
1007         //TODO: change use case for output streams: use strategy and mixer attributes
1008         audio_stream_type_t stream;
1009         audio_source_t      source;
1010     } usecase;
1011 };
1012
1013 /* extension for audio port configuration structure when the audio port is an
1014  * audio session */
1015 struct audio_port_config_session_ext {
1016     audio_session_t   session; /* audio session */
1017 };
1018
1019 /* Flags indicating which fields are to be considered in struct audio_port_config */
1020 #define AUDIO_PORT_CONFIG_SAMPLE_RATE  0x1
1021 #define AUDIO_PORT_CONFIG_CHANNEL_MASK 0x2
1022 #define AUDIO_PORT_CONFIG_FORMAT       0x4
1023 #define AUDIO_PORT_CONFIG_GAIN         0x8
1024 #define AUDIO_PORT_CONFIG_ALL (AUDIO_PORT_CONFIG_SAMPLE_RATE | \
1025                                AUDIO_PORT_CONFIG_CHANNEL_MASK | \
1026                                AUDIO_PORT_CONFIG_FORMAT | \
1027                                AUDIO_PORT_CONFIG_GAIN)
1028
1029 /* audio port configuration structure used to specify a particular configuration of
1030  * an audio port */
1031 struct audio_port_config {
1032     audio_port_handle_t      id;           /* port unique ID */
1033     audio_port_role_t        role;         /* sink or source */
1034     audio_port_type_t        type;         /* device, mix ... */
1035     unsigned int             config_mask;  /* e.g AUDIO_PORT_CONFIG_ALL */
1036     unsigned int             sample_rate;  /* sampling rate in Hz */
1037     audio_channel_mask_t     channel_mask; /* channel mask if applicable */
1038     audio_format_t           format;       /* format if applicable */
1039     struct audio_gain_config gain;         /* gain to apply if applicable */
1040     union {
1041         struct audio_port_config_device_ext  device;  /* device specific info */
1042         struct audio_port_config_mix_ext     mix;     /* mix specific info */
1043         struct audio_port_config_session_ext session; /* session specific info */
1044     } ext;
1045 };
1046
1047
1048 /* max number of sampling rates in audio port */
1049 #define AUDIO_PORT_MAX_SAMPLING_RATES 16
1050 /* max number of channel masks in audio port */
1051 #define AUDIO_PORT_MAX_CHANNEL_MASKS 16
1052 /* max number of audio formats in audio port */
1053 #define AUDIO_PORT_MAX_FORMATS 16
1054 /* max number of gain controls in audio port */
1055 #define AUDIO_PORT_MAX_GAINS 16
1056
1057 /* extension for audio port structure when the audio port is a hardware device */
1058 struct audio_port_device_ext {
1059     audio_module_handle_t hw_module;    /* module the device is attached to */
1060     audio_devices_t       type;         /* device type (e.g AUDIO_DEVICE_OUT_SPEAKER) */
1061     char                  address[AUDIO_DEVICE_MAX_ADDRESS_LEN];
1062 };
1063
1064 /* Latency class of the audio mix */
1065 typedef enum {
1066     AUDIO_LATENCY_LOW,
1067     AUDIO_LATENCY_NORMAL,
1068 } audio_mix_latency_class_t;
1069
1070 /* extension for audio port structure when the audio port is a sub mix */
1071 struct audio_port_mix_ext {
1072     audio_module_handle_t     hw_module;     /* module the stream is attached to */
1073     audio_io_handle_t         handle;        /* I/O handle of the input.output stream */
1074     audio_mix_latency_class_t latency_class; /* latency class */
1075     // other attributes: routing strategies
1076 };
1077
1078 /* extension for audio port structure when the audio port is an audio session */
1079 struct audio_port_session_ext {
1080     audio_session_t   session; /* audio session */
1081 };
1082
1083 struct audio_port {
1084     audio_port_handle_t      id;                /* port unique ID */
1085     audio_port_role_t        role;              /* sink or source */
1086     audio_port_type_t        type;              /* device, mix ... */
1087     char                     name[AUDIO_PORT_MAX_NAME_LEN];
1088     unsigned int             num_sample_rates;  /* number of sampling rates in following array */
1089     unsigned int             sample_rates[AUDIO_PORT_MAX_SAMPLING_RATES];
1090     unsigned int             num_channel_masks; /* number of channel masks in following array */
1091     audio_channel_mask_t     channel_masks[AUDIO_PORT_MAX_CHANNEL_MASKS];
1092     unsigned int             num_formats;       /* number of formats in following array */
1093     audio_format_t           formats[AUDIO_PORT_MAX_FORMATS];
1094     unsigned int             num_gains;         /* number of gains in following array */
1095     struct audio_gain        gains[AUDIO_PORT_MAX_GAINS];
1096     struct audio_port_config active_config;     /* current audio port configuration */
1097     union {
1098         struct audio_port_device_ext  device;
1099         struct audio_port_mix_ext     mix;
1100         struct audio_port_session_ext session;
1101     } ext;
1102 };
1103
1104 /* An audio patch represents a connection between one or more source ports and
1105  * one or more sink ports. Patches are connected and disconnected by audio policy manager or by
1106  * applications via framework APIs.
1107  * Each patch is identified by a handle at the interface used to create that patch. For instance,
1108  * when a patch is created by the audio HAL, the HAL allocates and returns a handle.
1109  * This handle is unique to a given audio HAL hardware module.
1110  * But the same patch receives another system wide unique handle allocated by the framework.
1111  * This unique handle is used for all transactions inside the framework.
1112  */
1113 typedef enum {
1114     AUDIO_PATCH_HANDLE_NONE = 0,
1115 } audio_patch_handle_t;
1116
1117 #define AUDIO_PATCH_PORTS_MAX   16
1118
1119 struct audio_patch {
1120     audio_patch_handle_t id;            /* patch unique ID */
1121     unsigned int      num_sources;      /* number of sources in following array */
1122     struct audio_port_config sources[AUDIO_PATCH_PORTS_MAX];
1123     unsigned int      num_sinks;        /* number of sinks in following array */
1124     struct audio_port_config sinks[AUDIO_PATCH_PORTS_MAX];
1125 };
1126
1127
1128
1129 /* a HW synchronization source returned by the audio HAL */
1130 typedef uint32_t audio_hw_sync_t;
1131
1132 /* an invalid HW synchronization source indicating an error */
1133 #define AUDIO_HW_SYNC_INVALID 0
1134
1135 static inline bool audio_is_output_device(audio_devices_t device)
1136 {
1137     if (((device & AUDIO_DEVICE_BIT_IN) == 0) &&
1138             (popcount(device) == 1) && ((device & ~AUDIO_DEVICE_OUT_ALL) == 0))
1139         return true;
1140     else
1141         return false;
1142 }
1143
1144 static inline bool audio_is_input_device(audio_devices_t device)
1145 {
1146     if ((device & AUDIO_DEVICE_BIT_IN) != 0) {
1147         device &= ~AUDIO_DEVICE_BIT_IN;
1148         if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_IN_ALL) == 0))
1149             return true;
1150     }
1151     return false;
1152 }
1153
1154 static inline bool audio_is_output_devices(audio_devices_t device)
1155 {
1156     return (device & AUDIO_DEVICE_BIT_IN) == 0;
1157 }
1158
1159 static inline bool audio_is_a2dp_in_device(audio_devices_t device)
1160 {
1161     if ((device & AUDIO_DEVICE_BIT_IN) != 0) {
1162         device &= ~AUDIO_DEVICE_BIT_IN;
1163         if ((popcount(device) == 1) && (device & AUDIO_DEVICE_IN_BLUETOOTH_A2DP))
1164             return true;
1165     }
1166     return false;
1167 }
1168
1169 static inline bool audio_is_a2dp_out_device(audio_devices_t device)
1170 {
1171     if ((popcount(device) == 1) && (device & AUDIO_DEVICE_OUT_ALL_A2DP))
1172         return true;
1173     else
1174         return false;
1175 }
1176
1177 // Deprecated - use audio_is_a2dp_out_device() instead
1178 static inline bool audio_is_a2dp_device(audio_devices_t device)
1179 {
1180     return audio_is_a2dp_out_device(device);
1181 }
1182
1183 static inline bool audio_is_bluetooth_sco_device(audio_devices_t device)
1184 {
1185     if ((device & AUDIO_DEVICE_BIT_IN) == 0) {
1186         if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_OUT_ALL_SCO) == 0))
1187             return true;
1188     } else {
1189         device &= ~AUDIO_DEVICE_BIT_IN;
1190         if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET) == 0))
1191             return true;
1192     }
1193
1194     return false;
1195 }
1196
1197 static inline bool audio_is_usb_out_device(audio_devices_t device)
1198 {
1199     return ((popcount(device) == 1) && (device & AUDIO_DEVICE_OUT_ALL_USB));
1200 }
1201
1202 static inline bool audio_is_usb_in_device(audio_devices_t device)
1203 {
1204     if ((device & AUDIO_DEVICE_BIT_IN) != 0) {
1205         device &= ~AUDIO_DEVICE_BIT_IN;
1206         if (popcount(device) == 1 && (device & AUDIO_DEVICE_IN_ALL_USB) != 0)
1207             return true;
1208     }
1209     return false;
1210 }
1211
1212 /* OBSOLETE - use audio_is_usb_out_device() instead. */
1213 static inline bool audio_is_usb_device(audio_devices_t device)
1214 {
1215     return audio_is_usb_out_device(device);
1216 }
1217
1218 static inline bool audio_is_remote_submix_device(audio_devices_t device)
1219 {
1220     if ((audio_is_output_devices(device) &&
1221          (device & AUDIO_DEVICE_OUT_REMOTE_SUBMIX) == AUDIO_DEVICE_OUT_REMOTE_SUBMIX)
1222         || (!audio_is_output_devices(device) &&
1223          (device & AUDIO_DEVICE_IN_REMOTE_SUBMIX) == AUDIO_DEVICE_IN_REMOTE_SUBMIX))
1224         return true;
1225     else
1226         return false;
1227 }
1228
1229 /* Returns true if:
1230  *  representation is valid, and
1231  *  there is at least one channel bit set which _could_ correspond to an input channel, and
1232  *  there are no channel bits set which could _not_ correspond to an input channel.
1233  * Otherwise returns false.
1234  */
1235 static inline bool audio_is_input_channel(audio_channel_mask_t channel)
1236 {
1237     uint32_t bits = audio_channel_mask_get_bits(channel);
1238     switch (audio_channel_mask_get_representation(channel)) {
1239     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
1240         if (bits & ~AUDIO_CHANNEL_IN_ALL) {
1241             bits = 0;
1242         }
1243         // fall through
1244     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
1245         return bits != 0;
1246     default:
1247         return false;
1248     }
1249 }
1250
1251 /* Returns true if:
1252  *  representation is valid, and
1253  *  there is at least one channel bit set which _could_ correspond to an output channel, and
1254  *  there are no channel bits set which could _not_ correspond to an output channel.
1255  * Otherwise returns false.
1256  */
1257 static inline bool audio_is_output_channel(audio_channel_mask_t channel)
1258 {
1259     uint32_t bits = audio_channel_mask_get_bits(channel);
1260     switch (audio_channel_mask_get_representation(channel)) {
1261     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
1262         if (bits & ~AUDIO_CHANNEL_OUT_ALL) {
1263             bits = 0;
1264         }
1265         // fall through
1266     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
1267         return bits != 0;
1268     default:
1269         return false;
1270     }
1271 }
1272
1273 /* Returns the number of channels from an input channel mask,
1274  * used in the context of audio input or recording.
1275  * If a channel bit is set which could _not_ correspond to an input channel,
1276  * it is excluded from the count.
1277  * Returns zero if the representation is invalid.
1278  */
1279 static inline uint32_t audio_channel_count_from_in_mask(audio_channel_mask_t channel)
1280 {
1281     uint32_t bits = audio_channel_mask_get_bits(channel);
1282     switch (audio_channel_mask_get_representation(channel)) {
1283     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
1284         // TODO: We can now merge with from_out_mask and remove anding
1285         bits &= AUDIO_CHANNEL_IN_ALL;
1286         // fall through
1287     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
1288         return popcount(bits);
1289     default:
1290         return 0;
1291     }
1292 }
1293
1294 /* Returns the number of channels from an output channel mask,
1295  * used in the context of audio output or playback.
1296  * If a channel bit is set which could _not_ correspond to an output channel,
1297  * it is excluded from the count.
1298  * Returns zero if the representation is invalid.
1299  */
1300 static inline uint32_t audio_channel_count_from_out_mask(audio_channel_mask_t channel)
1301 {
1302     uint32_t bits = audio_channel_mask_get_bits(channel);
1303     switch (audio_channel_mask_get_representation(channel)) {
1304     case AUDIO_CHANNEL_REPRESENTATION_POSITION:
1305         // TODO: We can now merge with from_in_mask and remove anding
1306         bits &= AUDIO_CHANNEL_OUT_ALL;
1307         // fall through
1308     case AUDIO_CHANNEL_REPRESENTATION_INDEX:
1309         return popcount(bits);
1310     default:
1311         return 0;
1312     }
1313 }
1314
1315 /* Derive a channel mask for index assignment from a channel count.
1316  * Returns the matching channel mask,
1317  * or AUDIO_CHANNEL_NONE if the channel count is zero,
1318  * or AUDIO_CHANNEL_INVALID if the channel count exceeds AUDIO_CHANNEL_COUNT_MAX.
1319  */
1320 static inline audio_channel_mask_t audio_channel_mask_for_index_assignment_from_count(
1321         uint32_t channel_count)
1322 {
1323     if (channel_count == 0) {
1324         return AUDIO_CHANNEL_NONE;
1325     }
1326     if (channel_count > AUDIO_CHANNEL_COUNT_MAX) {
1327         return AUDIO_CHANNEL_INVALID;
1328     }
1329     uint32_t bits = (1 << channel_count) - 1;
1330     return audio_channel_mask_from_representation_and_bits(
1331             AUDIO_CHANNEL_REPRESENTATION_INDEX, bits);
1332 }
1333
1334 /* Derive an output channel mask for position assignment from a channel count.
1335  * This is to be used when the content channel mask is unknown. The 1, 2, 4, 5, 6, 7 and 8 channel
1336  * cases are mapped to the standard game/home-theater layouts, but note that 4 is mapped to quad,
1337  * and not stereo + FC + mono surround. A channel count of 3 is arbitrarily mapped to stereo + FC
1338  * for continuity with stereo.
1339  * Returns the matching channel mask,
1340  * or AUDIO_CHANNEL_NONE if the channel count is zero,
1341  * or AUDIO_CHANNEL_INVALID if the channel count exceeds that of the
1342  * configurations for which a default output channel mask is defined.
1343  */
1344 static inline audio_channel_mask_t audio_channel_out_mask_from_count(uint32_t channel_count)
1345 {
1346     uint32_t bits;
1347     switch (channel_count) {
1348     case 0:
1349         return AUDIO_CHANNEL_NONE;
1350     case 1:
1351         bits = AUDIO_CHANNEL_OUT_MONO;
1352         break;
1353     case 2:
1354         bits = AUDIO_CHANNEL_OUT_STEREO;
1355         break;
1356     case 3:
1357         bits = AUDIO_CHANNEL_OUT_STEREO | AUDIO_CHANNEL_OUT_FRONT_CENTER;
1358         break;
1359     case 4: // 4.0
1360         bits = AUDIO_CHANNEL_OUT_QUAD;
1361         break;
1362     case 5: // 5.0
1363         bits = AUDIO_CHANNEL_OUT_QUAD | AUDIO_CHANNEL_OUT_FRONT_CENTER;
1364         break;
1365     case 6: // 5.1
1366         bits = AUDIO_CHANNEL_OUT_5POINT1;
1367         break;
1368     case 7: // 6.1
1369         bits = AUDIO_CHANNEL_OUT_5POINT1 | AUDIO_CHANNEL_OUT_BACK_CENTER;
1370         break;
1371     case 8:
1372         bits = AUDIO_CHANNEL_OUT_7POINT1;
1373         break;
1374     // FIXME FCC_8
1375     default:
1376         return AUDIO_CHANNEL_INVALID;
1377     }
1378     return audio_channel_mask_from_representation_and_bits(
1379             AUDIO_CHANNEL_REPRESENTATION_POSITION, bits);
1380 }
1381
1382 /* Derive a default input channel mask from a channel count.
1383  * Assumes a position mask for mono and stereo, or an index mask for channel counts > 2.
1384  * Returns the matching channel mask,
1385  * or AUDIO_CHANNEL_NONE if the channel count is zero,
1386  * or AUDIO_CHANNEL_INVALID if the channel count exceeds that of the
1387  * configurations for which a default input channel mask is defined.
1388  */
1389 static inline audio_channel_mask_t audio_channel_in_mask_from_count(uint32_t channel_count)
1390 {
1391     uint32_t bits;
1392     switch (channel_count) {
1393     case 0:
1394         return AUDIO_CHANNEL_NONE;
1395     case 1:
1396         bits = AUDIO_CHANNEL_IN_MONO;
1397         break;
1398     case 2:
1399         bits = AUDIO_CHANNEL_IN_STEREO;
1400         break;
1401     case 3:
1402     case 4:
1403     case 5:
1404     case 6:
1405     case 7:
1406     case 8:
1407         // FIXME FCC_8
1408         return audio_channel_mask_for_index_assignment_from_count(channel_count);
1409     default:
1410         return AUDIO_CHANNEL_INVALID;
1411     }
1412     return audio_channel_mask_from_representation_and_bits(
1413             AUDIO_CHANNEL_REPRESENTATION_POSITION, bits);
1414 }
1415
1416 static inline bool audio_is_valid_format(audio_format_t format)
1417 {
1418     switch (format & AUDIO_FORMAT_MAIN_MASK) {
1419     case AUDIO_FORMAT_PCM:
1420         switch (format) {
1421         case AUDIO_FORMAT_PCM_16_BIT:
1422         case AUDIO_FORMAT_PCM_8_BIT:
1423         case AUDIO_FORMAT_PCM_32_BIT:
1424         case AUDIO_FORMAT_PCM_8_24_BIT:
1425         case AUDIO_FORMAT_PCM_FLOAT:
1426         case AUDIO_FORMAT_PCM_24_BIT_PACKED:
1427             return true;
1428         default:
1429             return false;
1430         }
1431         /* not reached */
1432     case AUDIO_FORMAT_MP3:
1433     case AUDIO_FORMAT_AMR_NB:
1434     case AUDIO_FORMAT_AMR_WB:
1435     case AUDIO_FORMAT_AAC:
1436     case AUDIO_FORMAT_HE_AAC_V1:
1437     case AUDIO_FORMAT_HE_AAC_V2:
1438     case AUDIO_FORMAT_VORBIS:
1439     case AUDIO_FORMAT_OPUS:
1440     case AUDIO_FORMAT_AC3:
1441     case AUDIO_FORMAT_E_AC3:
1442     case AUDIO_FORMAT_DTS:
1443     case AUDIO_FORMAT_DTS_HD:
1444     case AUDIO_FORMAT_IEC61937:
1445         return true;
1446     default:
1447         return false;
1448     }
1449 }
1450
1451 /**
1452  * Extract the primary format, eg. PCM, AC3, etc.
1453  */
1454 static inline audio_format_t audio_get_main_format(audio_format_t format)
1455 {
1456     return (audio_format_t)(format & AUDIO_FORMAT_MAIN_MASK);
1457 }
1458
1459 /**
1460  * Is the data plain PCM samples that can be scaled and mixed?
1461  */
1462 static inline bool audio_is_linear_pcm(audio_format_t format)
1463 {
1464     return (audio_get_main_format(format) == AUDIO_FORMAT_PCM);
1465 }
1466
1467 /**
1468  * For this format, is the number of PCM audio frames directly proportional
1469  * to the number of data bytes?
1470  *
1471  * In other words, is the format transported as PCM audio samples,
1472  * but not necessarily scalable or mixable.
1473  * This returns true for real PCM, but also for AUDIO_FORMAT_IEC61937,
1474  * which is transported as 16 bit PCM audio, but where the encoded data
1475  * cannot be mixed or scaled.
1476  */
1477 static inline bool audio_has_proportional_frames(audio_format_t format)
1478 {
1479     audio_format_t mainFormat = audio_get_main_format(format);
1480     return (mainFormat == AUDIO_FORMAT_PCM
1481             || mainFormat == AUDIO_FORMAT_IEC61937);
1482 }
1483
1484 static inline size_t audio_bytes_per_sample(audio_format_t format)
1485 {
1486     size_t size = 0;
1487
1488     switch (format) {
1489     case AUDIO_FORMAT_PCM_32_BIT:
1490     case AUDIO_FORMAT_PCM_8_24_BIT:
1491         size = sizeof(int32_t);
1492         break;
1493     case AUDIO_FORMAT_PCM_24_BIT_PACKED:
1494         size = sizeof(uint8_t) * 3;
1495         break;
1496     case AUDIO_FORMAT_PCM_16_BIT:
1497     case AUDIO_FORMAT_IEC61937:
1498         size = sizeof(int16_t);
1499         break;
1500     case AUDIO_FORMAT_PCM_8_BIT:
1501         size = sizeof(uint8_t);
1502         break;
1503     case AUDIO_FORMAT_PCM_FLOAT:
1504         size = sizeof(float);
1505         break;
1506     default:
1507         break;
1508     }
1509     return size;
1510 }
1511
1512 /* converts device address to string sent to audio HAL via set_parameters */
1513 static inline char *audio_device_address_to_parameter(audio_devices_t device, const char *address)
1514 {
1515     const size_t kSize = AUDIO_DEVICE_MAX_ADDRESS_LEN + sizeof("a2dp_sink_address=");
1516     char param[kSize];
1517
1518     if (device & AUDIO_DEVICE_OUT_ALL_A2DP)
1519         snprintf(param, kSize, "%s=%s", "a2dp_sink_address", address);
1520     else if (device & AUDIO_DEVICE_OUT_REMOTE_SUBMIX)
1521         snprintf(param, kSize, "%s=%s", "mix", address);
1522     else
1523         snprintf(param, kSize, "%s", address);
1524
1525     return strdup(param);
1526 }
1527
1528 static inline bool audio_device_is_digital(audio_devices_t device) {
1529     if ((device & AUDIO_DEVICE_BIT_IN) != 0) {
1530         // input
1531         return (~AUDIO_DEVICE_BIT_IN & device & (AUDIO_DEVICE_IN_ALL_USB |
1532                           AUDIO_DEVICE_IN_HDMI |
1533                           AUDIO_DEVICE_IN_SPDIF |
1534                           AUDIO_DEVICE_IN_IP |
1535                           AUDIO_DEVICE_IN_BUS)) != 0;
1536     } else {
1537         // output
1538         return (device & (AUDIO_DEVICE_OUT_ALL_USB |
1539                           AUDIO_DEVICE_OUT_HDMI |
1540                           AUDIO_DEVICE_OUT_HDMI_ARC |
1541                           AUDIO_DEVICE_OUT_SPDIF |
1542                           AUDIO_DEVICE_OUT_IP |
1543                           AUDIO_DEVICE_OUT_BUS)) != 0;
1544     }
1545 }
1546
1547 __END_DECLS
1548
1549 #endif  // ANDROID_AUDIO_CORE_H