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 #ifndef ANDROID_RADIO_H
18 #define ANDROID_RADIO_H
19
20 #include <stdbool.h>
21 #include <stdint.h>
22 #include <stdio.h>
23 #include <sys/cdefs.h>
24 #include <sys/types.h>
25
26
27 #define RADIO_NUM_BANDS_MAX 16
28 #define RADIO_NUM_SPACINGS_MAX 16
29 #define RADIO_STRING_LEN_MAX 128
30
31 /*
32 * Radio hardware module class. A given radio hardware module HAL is of one class
33 * only. The platform can not have more than one hardware module of each class.
34 * Current version of the framework only supports RADIO_CLASS_AM_FM.
35 */
36 typedef enum {
37 RADIO_CLASS_AM_FM = 0, /* FM (including HD radio) and AM */
38 RADIO_CLASS_SAT = 1, /* Satellite Radio */
39 RADIO_CLASS_DT = 2, /* Digital Radio (DAB) */
40 } radio_class_t;
41
42 /* value for field "type" of radio band described in struct radio_hal_band_config */
43 typedef enum {
44 RADIO_BAND_AM = 0, /* Amplitude Modulation band: LW, MW, SW */
45 RADIO_BAND_FM = 1, /* Frequency Modulation band: FM */
46 RADIO_BAND_FM_HD = 2, /* FM HD Radio / DRM (IBOC) */
47 RADIO_BAND_AM_HD = 3, /* AM HD Radio / DRM (IBOC) */
48 } radio_band_t;
49
50 /* RDS variant implemented. A struct radio_hal_fm_band_config can list none or several. */
51 enum {
52 RADIO_RDS_NONE = 0x0,
53 RADIO_RDS_WORLD = 0x01,
54 RADIO_RDS_US = 0x02,
55 };
56 typedef unsigned int radio_rds_t;
57
58 /* FM deemphasis variant implemented. A struct radio_hal_fm_band_config can list one or more. */
59 enum {
60 RADIO_DEEMPHASIS_50 = 0x1,
61 RADIO_DEEMPHASIS_75 = 0x2,
62 };
63 typedef unsigned int radio_deemphasis_t;
64
65 /* Region a particular radio band configuration corresponds to. Not used at the HAL.
66 * Derived by the framework when converting the band descriptors retrieved from the HAL to
67 * individual band descriptors for each supported region. */
68 typedef enum {
69 RADIO_REGION_NONE = -1,
70 RADIO_REGION_ITU_1 = 0,
71 RADIO_REGION_ITU_2 = 1,
72 RADIO_REGION_OIRT = 2,
73 RADIO_REGION_JAPAN = 3,
74 RADIO_REGION_KOREA = 4,
75 } radio_region_t;
76
77 /* scanning direction for scan() and step() tuner APIs */
78 typedef enum {
79 RADIO_DIRECTION_UP,
80 RADIO_DIRECTION_DOWN
81 } radio_direction_t;
82
83 /* unique handle allocated to a radio module */
84 typedef uint32_t radio_handle_t;
85
86 /* Opaque meta data structure used by radio meta data API (see system/radio_metadata.h) */
87 typedef struct radio_metadata radio_metadata_t;
88
89
90 /* Additional attributes for an FM band configuration */
91 typedef struct radio_hal_fm_band_config {
92 radio_deemphasis_t deemphasis; /* deemphasis variant */
93 bool stereo; /* stereo supported */
94 radio_rds_t rds; /* RDS variants supported */
95 bool ta; /* Traffic Announcement supported */
96 bool af; /* Alternate Frequency supported */
97 bool ea; /* Emergency announcements supported */
98 } radio_hal_fm_band_config_t;
99
100 /* Additional attributes for an AM band configuration */
101 typedef struct radio_hal_am_band_config {
102 bool stereo; /* stereo supported */
103 } radio_hal_am_band_config_t;
104
105 /* Radio band configuration. Describes a given band supported by the radio module.
106 * The HAL can expose only one band per type with the the maximum range supported and all options.
107 * THe framework will derive the actual regions were this module can operate and expose separate
108 * band configurations for applications to chose from. */
109 typedef struct radio_hal_band_config {
110 radio_band_t type;
111 bool antenna_connected;
112 uint32_t lower_limit;
113 uint32_t upper_limit;
114 uint32_t num_spacings;
115 uint32_t spacings[RADIO_NUM_SPACINGS_MAX];
116 union {
117 radio_hal_fm_band_config_t fm;
118 radio_hal_am_band_config_t am;
119 };
120 } radio_hal_band_config_t;
121
122 /* Used internally by the framework to represent a band for s specific region */
123 typedef struct radio_band_config {
124 radio_region_t region;
125 radio_hal_band_config_t band;
126 } radio_band_config_t;
127
128
129 /* Exposes properties of a given hardware radio module.
130 * NOTE: current framework implementation supports only one audio source (num_audio_sources = 1).
131 * The source corresponds to AUDIO_DEVICE_IN_FM_TUNER.
132 * If more than one tuner is supported (num_tuners > 1), only one can be connected to the audio
133 * source. */
134 typedef struct radio_hal_properties {
135 radio_class_t class_id; /* Class of this module. E.g RADIO_CLASS_AM_FM */
136 char implementor[RADIO_STRING_LEN_MAX]; /* implementor name */
137 char product[RADIO_STRING_LEN_MAX]; /* product name */
138 char version[RADIO_STRING_LEN_MAX]; /* product version */
139 char serial[RADIO_STRING_LEN_MAX]; /* serial number (for subscription services) */
140 uint32_t num_tuners; /* number of tuners controllable independently */
141 uint32_t num_audio_sources; /* number of audio sources driven simultaneously */
142 bool supports_capture; /* the hardware supports capture of audio source audio HAL */
143 uint32_t num_bands; /* number of band descriptors */
144 radio_hal_band_config_t bands[RADIO_NUM_BANDS_MAX]; /* band descriptors */
145 } radio_hal_properties_t;
146
147 /* Used internally by the framework. Same information as in struct radio_hal_properties plus a
148 * unique handle and one band configuration per region. */
149 typedef struct radio_properties {
150 radio_handle_t handle;
151 radio_class_t class_id;
152 char implementor[RADIO_STRING_LEN_MAX];
153 char product[RADIO_STRING_LEN_MAX];
154 char version[RADIO_STRING_LEN_MAX];
155 char serial[RADIO_STRING_LEN_MAX];
156 uint32_t num_tuners;
157 uint32_t num_audio_sources;
158 bool supports_capture;
159 uint32_t num_bands;
160 radio_band_config_t bands[RADIO_NUM_BANDS_MAX];
161 } radio_properties_t;
162
163 /* Radio program information. Returned by the HAL with event RADIO_EVENT_TUNED.
164 * Contains information on currently tuned channel.
165 */
166 typedef struct radio_program_info {
167 uint32_t channel; /* current channel. (e.g kHz for band type RADIO_BAND_FM) */
168 uint32_t sub_channel; /* current sub channel. (used for RADIO_BAND_FM_HD) */
169 bool tuned; /* tuned to a program or not */
170 bool stereo; /* program is stereo or not */
171 bool digital; /* digital program or not (e.g HD Radio program) */
172 uint32_t signal_strength; /* signal strength from 0 to 100 */
173 /* meta data (e.g PTY, song title ...), must not be NULL */
174 __attribute__((aligned(8))) radio_metadata_t *metadata;
175 } radio_program_info_t;
176
177
178 /* Events sent to the framework via the HAL callback. An event can notify the completion of an
179 * asynchronous command (configuration, tune, scan ...) or a spontaneous change (antenna connection,
180 * failure, AF switching, meta data reception... */
181 enum {
182 RADIO_EVENT_HW_FAILURE = 0, /* hardware module failure. Requires reopening the tuner */
183 RADIO_EVENT_CONFIG = 1, /* configuration change completed */
184 RADIO_EVENT_ANTENNA = 2, /* Antenna connected, disconnected */
185 RADIO_EVENT_TUNED = 3, /* tune, step, scan completed */
186 RADIO_EVENT_METADATA = 4, /* New meta data received */
187 RADIO_EVENT_TA = 5, /* Traffic announcement start or stop */
188 RADIO_EVENT_AF_SWITCH = 6, /* Switch to Alternate Frequency */
189 RADIO_EVENT_EA = 7, /* Emergency announcement start or stop */
190 // begin framework only events
191 RADIO_EVENT_CONTROL = 100, /* loss/gain of tuner control */
192 RADIO_EVENT_SERVER_DIED = 101, /* radio service died */
193 };
194 typedef unsigned int radio_event_type_t;
195
196 /* Event passed to the framework by the HAL callback */
197 typedef struct radio_hal_event {
198 radio_event_type_t type; /* event type */
199 int32_t status; /* used by RADIO_EVENT_CONFIG, RADIO_EVENT_TUNED */
200 union {
201 /* RADIO_EVENT_ANTENNA, RADIO_EVENT_TA, RADIO_EVENT_EA */
202 bool on;
203 radio_hal_band_config_t config; /* RADIO_EVENT_CONFIG */
204 radio_program_info_t info; /* RADIO_EVENT_TUNED, RADIO_EVENT_AF_SWITCH */
205 radio_metadata_t *metadata; /* RADIO_EVENT_METADATA */
206 };
207 } radio_hal_event_t;
208
209 /* Used internally by the framework. Same information as in struct radio_hal_event */
210 typedef struct radio_event {
211 radio_event_type_t type;
212 int32_t status;
213 union {
214 bool on;
215 radio_band_config_t config;
216 radio_program_info_t info;
217 /* meta data (e.g PTY, song title ...), must not be NULL */
218 __attribute__((aligned(8))) radio_metadata_t *metadata;
219 };
220 } radio_event_t;
221
222
223 static inline
radio_rds_for_region(bool rds,radio_region_t region)224 radio_rds_t radio_rds_for_region(bool rds, radio_region_t region) {
225 if (!rds)
226 return RADIO_RDS_NONE;
227 switch(region) {
228 case RADIO_REGION_ITU_1:
229 case RADIO_REGION_OIRT:
230 case RADIO_REGION_JAPAN:
231 case RADIO_REGION_KOREA:
232 return RADIO_RDS_WORLD;
233 case RADIO_REGION_ITU_2:
234 return RADIO_RDS_US;
235 default:
236 return RADIO_REGION_NONE;
237 }
238 }
239
240 static inline
radio_demephasis_for_region(radio_region_t region)241 radio_deemphasis_t radio_demephasis_for_region(radio_region_t region) {
242 switch(region) {
243 case RADIO_REGION_KOREA:
244 case RADIO_REGION_ITU_2:
245 return RADIO_DEEMPHASIS_75;
246 case RADIO_REGION_ITU_1:
247 case RADIO_REGION_OIRT:
248 case RADIO_REGION_JAPAN:
249 default:
250 return RADIO_DEEMPHASIS_50;
251 }
252 }
253
254 #endif // ANDROID_RADIO_H
255