Eric Laurent | 0b76309 | 2015-03-05 12:51:04 -0800 | [diff] [blame] | 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, |
Colin Cross | cc8d9f9 | 2016-10-06 16:44:23 -0700 | [diff] [blame] | 288 | TO_HW_DEVICE_T_OPEN(device)); |
Eric Laurent | 0b76309 | 2015-03-05 12:51:04 -0800 | [diff] [blame] | 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 |