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_FLOAT = 0x5u, 50 }; 51 typedef uint32_t audio_proxy_format_t; 52 53 // AudioChannelMask 54 enum { 55 AUDIO_PROXY_CHANNEL_INVALID = 0xC0000000u, 56 AUDIO_PROXY_CHANNEL_OUT_MONO = 0x1u, 57 AUDIO_PROXY_CHANNEL_OUT_STEREO = 0x3u, 58 }; 59 typedef uint32_t audio_proxy_channel_mask_t; 60 61 // AudioDrain 62 enum { 63 AUDIO_PROXY_DRAIN_ALL, 64 AUDIO_PROXY_DRAIN_EARLY_NOTIFY, 65 }; 66 typedef int32_t audio_proxy_drain_type_t; 67 68 // AudioOutputFlag 69 enum { 70 AUDIO_PROXY_OUTPUT_FLAG_NONE = 0x0, 71 AUDIO_PROXY_OUTPUT_FLAG_DIRECT = 0x1, 72 AUDIO_PROXY_OUTPUT_FLAG_HW_AV_SYNC = 0x40, 73 }; 74 typedef int32_t audio_proxy_output_flags_t; 75 76 // AudioConfig 77 typedef struct { 78 uint32_t sample_rate; 79 audio_proxy_channel_mask_t channel_mask; 80 audio_proxy_format_t format; 81 uint32_t frame_count; 82 83 // Points to extra fields defined in the future versions. 84 void* extension; 85 } audio_proxy_config_t; 86 87 // Util structure for key value pair. 88 typedef struct { 89 const char* key; 90 const char* val; 91 } audio_proxy_key_val_t; 92 93 typedef void (*audio_proxy_get_parameters_callback_t)( 94 void*, const audio_proxy_key_val_t*); 95 96 // The following struct/functions mirror those definitions in audio HAL. They 97 // should have the same requirement as audio HAL interfaces, unless specified. 98 99 // IStreamOut. 100 struct audio_proxy_stream_out { 101 size_t (*get_buffer_size)(const struct audio_proxy_stream_out* stream); 102 uint64_t (*get_frame_count)(const struct audio_proxy_stream_out* stream); 103 104 // Gets all the sample rate supported by the stream. The list is terminated 105 // by 0. The returned list should have the same life cycle of |stream|. 106 const uint32_t* (*get_supported_sample_rates)( 107 const struct audio_proxy_stream_out* stream, audio_proxy_format_t format); 108 uint32_t (*get_sample_rate)(const struct audio_proxy_stream_out* stream); 109 110 // optional. 111 int (*set_sample_rate)(struct audio_proxy_stream_out* stream, uint32_t rate); 112 113 // Gets all the channel mask supported by the stream. The list is terminated 114 // by AUDIO_PROXY_CHANNEL_INVALID. The returned list should have the same life 115 // cycle of |stream|. 116 const audio_proxy_channel_mask_t* (*get_supported_channel_masks)( 117 const struct audio_proxy_stream_out* stream, audio_proxy_format_t format); 118 audio_proxy_channel_mask_t (*get_channel_mask)( 119 const struct audio_proxy_stream_out* stream); 120 121 // optional. 122 int (*set_channel_mask)(struct audio_proxy_stream_out* stream, 123 audio_proxy_channel_mask_t mask); 124 125 // Gets all the audio formats supported by the stream. The list is terminated 126 // by AUDIO_PROXY_FORMAT_INVALID. The returned list should have the same life 127 // cycle of |stream|. 128 const audio_proxy_format_t* (*get_supported_formats)( 129 const struct audio_proxy_stream_out* stream); 130 audio_proxy_format_t (*get_format)( 131 const struct audio_proxy_stream_out* stream); 132 133 // optional. 134 int (*set_format)(struct audio_proxy_stream_out* stream, 135 audio_proxy_format_t format); 136 137 uint32_t (*get_latency)(const struct audio_proxy_stream_out* stream); 138 139 int (*standby)(struct audio_proxy_stream_out* stream); 140 141 int (*pause)(struct audio_proxy_stream_out* stream); 142 int (*resume)(struct audio_proxy_stream_out* stream); 143 144 // optional. 145 int (*drain)(struct audio_proxy_stream_out* stream, 146 audio_proxy_drain_type_t type); 147 148 int (*flush)(struct audio_proxy_stream_out* stream); 149 150 // Writes |buffer| into |stream|. This is called on an internal thread of this 151 // library. 152 ssize_t (*write)(struct audio_proxy_stream_out* self, const void* buffer, 153 size_t bytes); 154 155 // optional. 156 int (*get_render_position)(const struct audio_proxy_stream_out* stream, 157 uint32_t* dsp_frames); 158 159 // optional. 160 int (*get_next_write_timestamp)(const struct audio_proxy_stream_out* stream, 161 int64_t* timestamp); 162 163 int (*get_presentation_position)(const struct audio_proxy_stream_out* stream, 164 uint64_t* frames, 165 struct timespec* timestamp); 166 167 // opional. 168 int (*set_volume)(struct audio_proxy_stream_out* stream, float left, 169 float right); 170 171 // Sets parameters on |stream|. Both |context| and |param| are terminated 172 // by key_val_t whose key is null. They are only valid during the function 173 // call. 174 int (*set_parameters)(struct audio_proxy_stream_out* stream, 175 const audio_proxy_key_val_t* context, 176 const audio_proxy_key_val_t* param); 177 178 // Gets parameters from |stream|. 179 // |context| is key val pairs array terminated by null key 180 // audio_proxy_key_val_t. |keys| is C string array, terminated by nullptr. 181 // |on_result| is the callback to deliver the result. It must be called before 182 // this function returns, with |obj| as the first argument, and the list of 183 // caller owned list of key value pairs as the second argument. 184 // |obj| opaque object. Implementation should not touch it. 185 void (*get_parameters)(const struct audio_proxy_stream_out* stream, 186 const audio_proxy_key_val_t* context, 187 const char** keys, 188 audio_proxy_get_parameters_callback_t on_result, 189 void* obj); 190 191 // optional. 192 int (*dump)(const struct audio_proxy_stream_out* stream, int fd); 193 194 // Pointer to the next version structure, for compatibility. 195 void* extension; 196 }; 197 198 typedef struct audio_proxy_stream_out audio_proxy_stream_out_t; 199 200 // Extension of audio_proxy_device. 201 struct audio_proxy_device_v2 { 202 // Returns the AudioProxy service name that the client wants to connect to. 203 const char* (*get_service_name)(struct audio_proxy_device_v2* device); 204 205 // Opens output stream for playback. Compared to the old version, this one 206 // will pass the address of the stream to the implementation. 207 int (*open_output_stream)(struct audio_proxy_device_v2* device, 208 const char* address, 209 audio_proxy_output_flags_t flags, 210 audio_proxy_config_t* config, 211 audio_proxy_stream_out_t** stream_out); 212 213 // Points to next version's struct. Implementation should set this field to 214 // null if next version struct is not available. 215 // This allows library to work with applications integrated with older version 216 // header. 217 void* extension; 218 }; 219 220 typedef struct audio_proxy_device_v2 audio_proxy_device_v2_t; 221 222 // Represents an audio HAL bus device. 223 struct audio_proxy_device { 224 // Returns the unique address of this device. 225 const char* (*get_address)(struct audio_proxy_device* device); 226 227 // Similar to IDevice::openOutputStream. 228 int (*open_output_stream)(struct audio_proxy_device* device, 229 audio_proxy_output_flags_t flags, 230 audio_proxy_config_t* config, 231 audio_proxy_stream_out_t** stream_out); 232 233 // Close |stream|. No more methods will be called on |stream| after this. 234 void (*close_output_stream)(struct audio_proxy_device* device, 235 struct audio_proxy_stream_out* stream); 236 237 // Pointer to the extension structure. 238 audio_proxy_device_v2_t* v2; 239 }; 240 241 typedef struct audio_proxy_device audio_proxy_device_t; 242 243 // Provides |device| to the library. It returns 0 on success. This function is 244 // supposed to be called once per process. 245 // The service behind this library will register a new audio HAL to the audio 246 // server, on the first call to the service. 247 int audio_proxy_register_device(audio_proxy_device_t* device); 248 249 #ifdef __cplusplus 250 } 251 #endif 252 253 #endif // DEVICE_GOOGLE_ATV_AUDIO_PROXY_PUBLIC_AUDIO_PROXY_H_ 254