1 /* 2 * Copyright (C) 2015 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 #include <system/radio.h> 18 #include <hardware/hardware.h> 19 20 #ifndef ANDROID_RADIO_HAL_H 21 #define ANDROID_RADIO_HAL_H 22 23 24 __BEGIN_DECLS 25 26 /** 27 * The id of this module 28 */ 29 #define RADIO_HARDWARE_MODULE_ID "radio" 30 31 /** 32 * Name of the audio devices to open 33 */ 34 #define RADIO_HARDWARE_DEVICE "radio_hw_device" 35 36 #define RADIO_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) 37 #define RADIO_MODULE_API_VERSION_CURRENT RADIO_MODULE_API_VERSION_1_0 38 39 40 #define RADIO_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) 41 #define RADIO_DEVICE_API_VERSION_CURRENT RADIO_DEVICE_API_VERSION_1_0 42 43 /** 44 * List of known radio HAL modules. This is the base name of the radio HAL 45 * library composed of the "radio." prefix, one of the base names below and 46 * a suffix specific to the device. 47 * E.g: radio.fm.default.so 48 */ 49 50 #define RADIO_HARDWARE_MODULE_ID_FM "fm" /* corresponds to RADIO_CLASS_AM_FM */ 51 #define RADIO_HARDWARE_MODULE_ID_SAT "sat" /* corresponds to RADIO_CLASS_SAT */ 52 #define RADIO_HARDWARE_MODULE_ID_DT "dt" /* corresponds to RADIO_CLASS_DT */ 53 54 55 /** 56 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 57 * and the fields of this data structure must begin with hw_module_t 58 * followed by module specific information. 59 */ 60 struct radio_module { 61 struct hw_module_t common; 62 }; 63 64 /* 65 * Callback function called by the HAL when one of the following occurs: 66 * - event RADIO_EVENT_HW_FAILURE: radio chip of driver failure requiring 67 * closing and reopening of the tuner interface. 68 * - event RADIO_EVENT_CONFIG: new configuration applied in response to open_tuner(), 69 * or set_configuration(). The event status is 0 (no error) if the configuration has been applied, 70 * -EINVAL is not or -ETIMEDOUT in case of time out. 71 * - event RADIO_EVENT_TUNED: tune locked on new station/frequency following scan(), 72 * step(), tune() or auto AF switching. The event status is 0 (no error) if in tune, 73 * -EINVAL is not tuned and data in radio_program_info is not valid or -ETIMEDOUT if scan() 74 * timed out. 75 * - event RADIO_EVENT_TA: at the beginning and end of traffic announcement if current 76 * configuration enables TA. 77 * - event RADIO_EVENT_AF: after automatic switching to alternate frequency if current 78 * configuration enables AF switching. 79 * - event RADIO_EVENT_ANTENNA: when the antenna is connected or disconnected. 80 * - event RADIO_EVENT_METADATA: when new meta data are received from the tuned station. 81 * The callback MUST NOT be called synchronously while executing a HAL function but from 82 * a separate thread. 83 */ 84 typedef void (*radio_callback_t)(radio_hal_event_t *event, void *cookie); 85 86 /* control interface for a radio tuner */ 87 struct radio_tuner { 88 /* 89 * Apply current radio band configuration (band, range, channel spacing ...). 90 * 91 * arguments: 92 * - config: the band configuration to apply 93 * 94 * returns: 95 * 0 if configuration could be applied 96 * -EINVAL if configuration requested is invalid 97 * 98 * Automatically cancels pending scan, step or tune. 99 * 100 * Callback function with event RADIO_EVENT_CONFIG MUST be called once the 101 * configuration is applied or a failure occurs or after a time out. 102 */ 103 int (*set_configuration)(const struct radio_tuner *tuner, 104 const radio_hal_band_config_t *config); 105 106 /* 107 * Retrieve current radio band configuration. 108 * 109 * arguments: 110 * - config: where to return the band configuration 111 * 112 * returns: 113 * 0 if valid configuration is returned 114 * -EINVAL if invalid arguments are passed 115 */ 116 int (*get_configuration)(const struct radio_tuner *tuner, 117 radio_hal_band_config_t *config); 118 119 /* 120 * Start scanning up to next valid station. 121 * Must be called when a valid configuration has been applied. 122 * 123 * arguments: 124 * - direction: RADIO_DIRECTION_UP or RADIO_DIRECTION_DOWN 125 * - skip_sub_channel: valid for HD radio or digital radios only: ignore sub channels 126 * (e.g SPS for HD radio). 127 * 128 * returns: 129 * 0 if scan successfully started 130 * -ENOSYS if called out of sequence 131 * -ENODEV if another error occurs 132 * 133 * Automatically cancels pending scan, step or tune. 134 * 135 * Callback function with event RADIO_EVENT_TUNED MUST be called once 136 * locked on a station or after a time out or full frequency scan if 137 * no station found. The event status should indicate if a valid station 138 * is tuned or not. 139 */ 140 int (*scan)(const struct radio_tuner *tuner, 141 radio_direction_t direction, bool skip_sub_channel); 142 143 /* 144 * Move one channel spacing up or down. 145 * Must be called when a valid configuration has been applied. 146 * 147 * arguments: 148 * - direction: RADIO_DIRECTION_UP or RADIO_DIRECTION_DOWN 149 * - skip_sub_channel: valid for HD radio or digital radios only: ignore sub channels 150 * (e.g SPS for HD radio). 151 * 152 * returns: 153 * 0 if step successfully started 154 * -ENOSYS if called out of sequence 155 * -ENODEV if another error occurs 156 * 157 * Automatically cancels pending scan, step or tune. 158 * 159 * Callback function with event RADIO_EVENT_TUNED MUST be called once 160 * step completed or after a time out. The event status should indicate 161 * if a valid station is tuned or not. 162 */ 163 int (*step)(const struct radio_tuner *tuner, 164 radio_direction_t direction, bool skip_sub_channel); 165 166 /* 167 * Tune to specified frequency. 168 * Must be called when a valid configuration has been applied. 169 * 170 * arguments: 171 * - channel: channel to tune to. A frequency in kHz for AM/FM/HD Radio bands. 172 * - sub_channel: valid for HD radio or digital radios only: (e.g SPS number for HD radio). 173 * 174 * returns: 175 * 0 if tune successfully started 176 * -ENOSYS if called out of sequence 177 * -EINVAL if invalid arguments are passed 178 * -ENODEV if another error occurs 179 * 180 * Automatically cancels pending scan, step or tune. 181 * 182 * Callback function with event RADIO_EVENT_TUNED MUST be called once 183 * tuned or after a time out. The event status should indicate 184 * if a valid station is tuned or not. 185 */ 186 int (*tune)(const struct radio_tuner *tuner, 187 unsigned int channel, unsigned int sub_channel); 188 189 /* 190 * Cancel a scan, step or tune operation. 191 * Must be called while a scan, step or tune operation is pending 192 * (callback not yet sent). 193 * 194 * returns: 195 * 0 if successful 196 * -ENOSYS if called out of sequence 197 * -ENODEV if another error occurs 198 * 199 * The callback is not sent. 200 */ 201 int (*cancel)(const struct radio_tuner *tuner); 202 203 /* 204 * Retrieve current station information. 205 * 206 * arguments: 207 * - info: where to return the program info. 208 * If info->metadata is NULL. no meta data should be returned. 209 * If meta data must be returned, they should be added to or cloned to 210 * info->metadata, not passed from a newly created meta data buffer. 211 * 212 * returns: 213 * 0 if tuned and information available 214 * -EINVAL if invalid arguments are passed 215 * -ENODEV if another error occurs 216 */ 217 int (*get_program_information)(const struct radio_tuner *tuner, 218 radio_program_info_t *info); 219 }; 220 221 struct radio_hw_device { 222 struct hw_device_t common; 223 224 /* 225 * Retrieve implementation properties. 226 * 227 * arguments: 228 * - properties: where to return the module properties 229 * 230 * returns: 231 * 0 if no error 232 * -EINVAL if invalid arguments are passed 233 */ 234 int (*get_properties)(const struct radio_hw_device *dev, 235 radio_hal_properties_t *properties); 236 237 /* 238 * Open a tuner interface for the requested configuration. 239 * If no other tuner is opened, this will activate the radio module. 240 * 241 * arguments: 242 * - config: the band configuration to apply 243 * - audio: this tuner will be used for live radio listening and should be connected to 244 * the radio audio source. 245 * - callback: the event callback 246 * - cookie: the cookie to pass when calling the callback 247 * - tuner: where to return the tuner interface 248 * 249 * returns: 250 * 0 if HW was powered up and configuration could be applied 251 * -EINVAL if configuration requested is invalid 252 * -ENOSYS if called out of sequence 253 * 254 * Callback function with event RADIO_EVENT_CONFIG MUST be called once the 255 * configuration is applied or a failure occurs or after a time out. 256 */ 257 int (*open_tuner)(const struct radio_hw_device *dev, 258 const radio_hal_band_config_t *config, 259 bool audio, 260 radio_callback_t callback, 261 void *cookie, 262 const struct radio_tuner **tuner); 263 264 /* 265 * Close a tuner interface. 266 * If the last tuner is closed, the radio module is deactivated. 267 * 268 * arguments: 269 * - tuner: the tuner interface to close 270 * 271 * returns: 272 * 0 if powered down successfully. 273 * -EINVAL if an invalid argument is passed 274 * -ENOSYS if called out of sequence 275 */ 276 int (*close_tuner)(const struct radio_hw_device *dev, const struct radio_tuner *tuner); 277 278 }; 279 280 typedef struct radio_hw_device radio_hw_device_t; 281 282 /** convenience API for opening and closing a supported device */ 283 284 static inline int radio_hw_device_open(const struct hw_module_t* module, 285 struct radio_hw_device** device) 286 { 287 return module->methods->open(module, RADIO_HARDWARE_DEVICE, 288 TO_HW_DEVICE_T_OPEN(device)); 289 } 290 291 static inline int radio_hw_device_close(const struct radio_hw_device* device) 292 { 293 return device->common.close((struct hw_device_t *)&device->common); 294 } 295 296 __END_DECLS 297 298 #endif // ANDROID_RADIO_HAL_H 299
