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
radio_hw_device_open(const struct hw_module_t * module,struct radio_hw_device ** device)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
radio_hw_device_close(const struct radio_hw_device * device)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