1 // Copyright (C) 2020 The Android Open Source Project 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef DEVICE_GOOGLE_ATV_AUDIO_PROXY_PUBLIC_AUDIO_PROXY_H_ 16 #define DEVICE_GOOGLE_ATV_AUDIO_PROXY_PUBLIC_AUDIO_PROXY_H_ 17 18 #include <stdint.h> 19 #include <sys/types.h> 20 #include <time.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 // audio proxy allows the application to implement an audio HAL. It contains two 27 // components, a client library and a service. 28 // The client library is defined by this header file. Applications should 29 // integrate this library to provide audio HAL components. Currently it's only 30 // IStreamOut. 31 // The service implements IDevicesFactory and IDevice. It will register itself 32 // to audio server and forward function calls to client. 33 34 // Most of the struct/functions just converts the HIDL definitions into C 35 // definitions. 36 37 // The following enum and typedef are subset of those defined in 38 // hardware/interfaces/audio/common/$VERSION/types.hal, or 39 // hardware/interfaces/audio/$VERSION/types.hal. 40 // The selected subsets are those commonly supported by a normal audio HAL. The 41 // library won't check the validation of these enums. In other words, Audio 42 // server can still pass value not defined here to the application. 43 44 // AudioFormat 45 enum { 46 AUDIO_PROXY_FORMAT_INVALID = 0xFFFFFFFFu, 47 AUDIO_PROXY_FORMAT_PCM_16_BIT = 0x1u, 48 AUDIO_PROXY_FORMAT_PCM_8_BIT = 0x2u, 49 AUDIO_PROXY_FORMAT_PCM_32_BIT = 0x3u, 50 AUDIO_PROXY_FORMAT_PCM_8_24_BIT = 0x4u, 51 AUDIO_PROXY_FORMAT_PCM_FLOAT = 0x5u, 52 AUDIO_PROXY_FORMAT_PCM_24_BIT_PACKED = 0x6u, 53 }; 54 typedef uint32_t audio_proxy_format_t; 55 56 // AudioChannelMask 57 enum { 58 AUDIO_PROXY_CHANNEL_INVALID = 0xC0000000u, 59 AUDIO_PROXY_CHANNEL_OUT_MONO = 0x1u, 60 AUDIO_PROXY_CHANNEL_OUT_STEREO = 0x3u, 61 AUDIO_PROXY_CHANNEL_OUT_2POINT1 = 0xBu, 62 AUDIO_PROXY_CHANNEL_OUT_TRI = 0x7u, 63 AUDIO_PROXY_CHANNEL_OUT_TRI_BACK = 0x103u, 64 AUDIO_PROXY_CHANNEL_OUT_3POINT1 = 0xFu, 65 AUDIO_PROXY_CHANNEL_OUT_2POINT0POINT2 = 0xC0003u, 66 AUDIO_PROXY_CHANNEL_OUT_2POINT1POINT2 = 0xC000Bu, 67 AUDIO_PROXY_CHANNEL_OUT_3POINT0POINT2 = 0xC0007u, 68 AUDIO_PROXY_CHANNEL_OUT_3POINT1POINT2 = 0xC000Fu, 69 AUDIO_PROXY_CHANNEL_OUT_QUAD = 0x33u, 70 // AUDIO_PROXY_CHANNEL_OUT_QUAD_BACK = 0x33u, 71 AUDIO_PROXY_CHANNEL_OUT_QUAD_SIDE = 0x603u, 72 AUDIO_PROXY_CHANNEL_OUT_SURROUND = 0x107u, 73 AUDIO_PROXY_CHANNEL_OUT_PENTA = 0x37u, 74 AUDIO_PROXY_CHANNEL_OUT_5POINT1 = 0x3Fu, 75 // AUDIO_PROXY_CHANNEL_OUT_5POINT1_BACK = 0x3Fu, 76 AUDIO_PROXY_CHANNEL_OUT_5POINT1_SIDE = 0x60Fu, 77 AUDIO_PROXY_CHANNEL_OUT_5POINT1POINT2 = 0xC003Fu, 78 AUDIO_PROXY_CHANNEL_OUT_5POINT1POINT4 = 0x2D03Fu, 79 AUDIO_PROXY_CHANNEL_OUT_6POINT1 = 0x13Fu, 80 AUDIO_PROXY_CHANNEL_OUT_7POINT1 = 0x63Fu, 81 AUDIO_PROXY_CHANNEL_OUT_7POINT1POINT2 = 0xC063Fu, 82 AUDIO_PROXY_CHANNEL_OUT_7POINT1POINT4 = 0x2D63Fu, 83 AUDIO_PROXY_CHANNEL_OUT_13POINT_360RA = 0x72F607u, 84 AUDIO_PROXY_CHANNEL_OUT_22POINT2 = 0xFFFFFFu, 85 AUDIO_PROXY_CHANNEL_OUT_MONO_HAPTIC_A = 0x20000001u, 86 AUDIO_PROXY_CHANNEL_OUT_STEREO_HAPTIC_A = 0x20000003u, 87 AUDIO_PROXY_CHANNEL_OUT_HAPTIC_AB = 0x30000000u, 88 AUDIO_PROXY_CHANNEL_OUT_MONO_HAPTIC_AB = 0x30000001u, 89 AUDIO_PROXY_CHANNEL_OUT_STEREO_HAPTIC_AB = 0x30000003u, 90 }; 91 typedef uint32_t audio_proxy_channel_mask_t; 92 93 // AudioDrain 94 enum { 95 AUDIO_PROXY_DRAIN_ALL, 96 AUDIO_PROXY_DRAIN_EARLY_NOTIFY, 97 }; 98 typedef int32_t audio_proxy_drain_type_t; 99 100 // AudioOutputFlag 101 enum { 102 AUDIO_PROXY_OUTPUT_FLAG_NONE = 0x0, 103 AUDIO_PROXY_OUTPUT_FLAG_DIRECT = 0x1, 104 AUDIO_PROXY_OUTPUT_FLAG_HW_AV_SYNC = 0x40, 105 }; 106 typedef int32_t audio_proxy_output_flags_t; 107 108 // AudioConfig 109 typedef struct { 110 int64_t buffer_size_bytes; 111 int32_t latency_ms; 112 113 // Points to extra fields defined in the future versions. 114 void* extension; 115 } audio_proxy_config_v2_t; 116 117 typedef struct { 118 uint32_t sample_rate; 119 audio_proxy_channel_mask_t channel_mask; 120 audio_proxy_format_t format; 121 uint32_t frame_count; 122 123 // Points to extra fields. 124 audio_proxy_config_v2_t* v2; 125 } audio_proxy_config_t; 126 127 // Util structure for key value pair. 128 typedef struct { 129 const char* key; 130 const char* val; 131 } audio_proxy_key_val_t; 132 133 typedef void (*audio_proxy_get_parameters_callback_t)( 134 void*, const audio_proxy_key_val_t*); 135 136 enum { 137 AUDIO_PROXY_MMAP_BUFFER_FLAG_NONE = 0x0, 138 AUDIO_PROXY_MMAP_BUFFER_FLAG_APPLICATION_SHAREABLE = 0x1, 139 }; 140 typedef int32_t audio_proxy_mmap_buffer_flag_t; 141 142 typedef struct { 143 int shared_memory_fd; 144 int32_t buffer_size_frames; 145 int32_t burst_size_frames; 146 audio_proxy_mmap_buffer_flag_t flags; 147 } audio_proxy_mmap_buffer_info_t; 148 149 // IStreamOut. 150 struct audio_proxy_stream_out_v2 { 151 void (*start)(struct audio_proxy_stream_out_v2* stream); 152 void (*stop)(struct audio_proxy_stream_out_v2* stream); 153 audio_proxy_mmap_buffer_info_t (*create_mmap_buffer)( 154 struct audio_proxy_stream_out_v2* stream, int32_t min_buffer_size_frames); 155 void (*get_mmap_position)(struct audio_proxy_stream_out_v2* stream, 156 int64_t* frames, struct timespec* timestamp); 157 // Pointer to the next version structure, for compatibility. 158 void* extension; 159 }; 160 typedef struct audio_proxy_stream_out_v2 audio_proxy_stream_out_v2_t; 161 162 struct audio_proxy_stream_out { 163 size_t (*get_buffer_size)(const struct audio_proxy_stream_out* stream); 164 uint64_t (*get_frame_count)(const struct audio_proxy_stream_out* stream); 165 166 // Gets all the sample rate supported by the stream. The list is terminated 167 // by 0. The returned list should have the same life cycle of |stream|. 168 const uint32_t* (*get_supported_sample_rates)( 169 const struct audio_proxy_stream_out* stream, audio_proxy_format_t format); 170 uint32_t (*get_sample_rate)(const struct audio_proxy_stream_out* stream); 171 172 // optional. 173 int (*set_sample_rate)(struct audio_proxy_stream_out* stream, uint32_t rate); 174 175 // Gets all the channel mask supported by the stream. The list is terminated 176 // by AUDIO_PROXY_CHANNEL_INVALID. The returned list should have the same life 177 // cycle of |stream|. 178 const audio_proxy_channel_mask_t* (*get_supported_channel_masks)( 179 const struct audio_proxy_stream_out* stream, audio_proxy_format_t format); 180 audio_proxy_channel_mask_t (*get_channel_mask)( 181 const struct audio_proxy_stream_out* stream); 182 183 // optional. 184 int (*set_channel_mask)(struct audio_proxy_stream_out* stream, 185 audio_proxy_channel_mask_t mask); 186 187 // Gets all the audio formats supported by the stream. The list is terminated 188 // by AUDIO_PROXY_FORMAT_INVALID. The returned list should have the same life 189 // cycle of |stream|. 190 const audio_proxy_format_t* (*get_supported_formats)( 191 const struct audio_proxy_stream_out* stream); 192 audio_proxy_format_t (*get_format)( 193 const struct audio_proxy_stream_out* stream); 194 195 // optional. 196 int (*set_format)(struct audio_proxy_stream_out* stream, 197 audio_proxy_format_t format); 198 199 uint32_t (*get_latency)(const struct audio_proxy_stream_out* stream); 200 201 int (*standby)(struct audio_proxy_stream_out* stream); 202 203 int (*pause)(struct audio_proxy_stream_out* stream); 204 int (*resume)(struct audio_proxy_stream_out* stream); 205 206 // optional. 207 int (*drain)(struct audio_proxy_stream_out* stream, 208 audio_proxy_drain_type_t type); 209 210 int (*flush)(struct audio_proxy_stream_out* stream); 211 212 // Writes |buffer| into |stream|. This is called on an internal thread of this 213 // library. 214 ssize_t (*write)(struct audio_proxy_stream_out* self, const void* buffer, 215 size_t bytes); 216 217 // optional. 218 int (*get_render_position)(const struct audio_proxy_stream_out* stream, 219 uint32_t* dsp_frames); 220 221 // optional. 222 int (*get_next_write_timestamp)(const struct audio_proxy_stream_out* stream, 223 int64_t* timestamp); 224 225 int (*get_presentation_position)(const struct audio_proxy_stream_out* stream, 226 uint64_t* frames, 227 struct timespec* timestamp); 228 229 // opional. 230 int (*set_volume)(struct audio_proxy_stream_out* stream, float left, 231 float right); 232 233 // Sets parameters on |stream|. Both |context| and |param| are terminated 234 // by key_val_t whose key is null. They are only valid during the function 235 // call. 236 int (*set_parameters)(struct audio_proxy_stream_out* stream, 237 const audio_proxy_key_val_t* context, 238 const audio_proxy_key_val_t* param); 239 240 // Gets parameters from |stream|. 241 // |context| is key val pairs array terminated by null key 242 // audio_proxy_key_val_t. |keys| is C string array, terminated by nullptr. 243 // |on_result| is the callback to deliver the result. It must be called before 244 // this function returns, with |obj| as the first argument, and the list of 245 // caller owned list of key value pairs as the second argument. 246 // |obj| opaque object. Implementation should not touch it. 247 void (*get_parameters)(const struct audio_proxy_stream_out* stream, 248 const audio_proxy_key_val_t* context, 249 const char** keys, 250 audio_proxy_get_parameters_callback_t on_result, 251 void* obj); 252 253 // optional. 254 int (*dump)(const struct audio_proxy_stream_out* stream, int fd); 255 256 // Pointer to the next version structure. 257 audio_proxy_stream_out_v2_t* v2; 258 }; 259 260 typedef struct audio_proxy_stream_out audio_proxy_stream_out_t; 261 262 // Extension of audio_proxy_device. 263 struct audio_proxy_device_v2 { 264 // Returns the AudioProxy service name that the client wants to connect to. 265 const char* (*get_service_name)(struct audio_proxy_device_v2* device); 266 267 // Opens output stream for playback. Compared to the old version, this one 268 // will pass the address of the stream to the implementation. 269 int (*open_output_stream)(struct audio_proxy_device_v2* device, 270 const char* address, 271 audio_proxy_output_flags_t flags, 272 audio_proxy_config_t* config, 273 audio_proxy_stream_out_t** stream_out); 274 275 // Points to next version's struct. Implementation should set this field to 276 // null if next version struct is not available. 277 // This allows library to work with applications integrated with older version 278 // header. 279 void* extension; 280 }; 281 282 typedef struct audio_proxy_device_v2 audio_proxy_device_v2_t; 283 284 // Represents an audio HAL bus device. 285 struct audio_proxy_device { 286 // Returns the unique address of this device. 287 const char* (*get_address)(struct audio_proxy_device* device); 288 289 // Similar to IDevice::openOutputStream. 290 int (*open_output_stream)(struct audio_proxy_device* device, 291 audio_proxy_output_flags_t flags, 292 audio_proxy_config_t* config, 293 audio_proxy_stream_out_t** stream_out); 294 295 // Close |stream|. No more methods will be called on |stream| after this. 296 void (*close_output_stream)(struct audio_proxy_device* device, 297 struct audio_proxy_stream_out* stream); 298 299 // Pointer to the extension structure. 300 audio_proxy_device_v2_t* v2; 301 }; 302 303 typedef struct audio_proxy_device audio_proxy_device_t; 304 305 // Provides |device| to the library. It returns 0 on success. This function is 306 // supposed to be called once per process. 307 // The service behind this library will register a new audio HAL to the audio 308 // server, on the first call to the service. 309 int audio_proxy_register_device(audio_proxy_device_t* device); 310 311 #ifdef __cplusplus 312 } 313 #endif 314 315 #endif // DEVICE_GOOGLE_ATV_AUDIO_PROXY_PUBLIC_AUDIO_PROXY_H_ 316