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