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 */
60struct 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 */
84typedef void (*radio_callback_t)(radio_hal_event_t *event, void *cookie);
85
86/* control interface for a radio tuner */
87struct 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
221struct 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
280typedef struct  radio_hw_device  radio_hw_device_t;
281
282/** convenience API for opening and closing a supported device */
283
284static 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
291static 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