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 unsigned int radio_handle_t;
85
86 /* Opaque meta data structure used by radio meta data API (see system/radio_metadata.h) */
87 typedef struct radio_medtadata 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 unsigned int lower_limit;
113 unsigned int upper_limit;
114 unsigned int num_spacings;
115 unsigned int 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 unsigned int num_tuners; /* number of tuners controllable independently */
141 unsigned int num_audio_sources; /* number of audio sources driven simultaneously */
142 bool supports_capture; /* the hardware supports capture of audio source audio HAL */
143 unsigned int 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 unsigned int num_tuners;
157 unsigned int num_audio_sources;
158 bool supports_capture;
159 unsigned int 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 unsigned int channel; /* current channel. (e.g kHz for band type RADIO_BAND_FM) */
168 unsigned int 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 unsigned int signal_strength; /* signal strength from 0 to 100 */
173 radio_metadata_t *metadata; /* non null if meta data are present (e.g PTY, song title ...) */
174 } radio_program_info_t;
175
176
177 /* Events sent to the framework via the HAL callback. An event can notify the completion of an
178 * asynchronous command (configuration, tune, scan ...) or a spontaneous change (antenna connection,
179 * failure, AF switching, meta data reception... */
180 enum {
181 RADIO_EVENT_HW_FAILURE = 0, /* hardware module failure. Requires reopening the tuner */
182 RADIO_EVENT_CONFIG = 1, /* configuration change completed */
183 RADIO_EVENT_ANTENNA = 2, /* Antenna connected, disconnected */
184 RADIO_EVENT_TUNED = 3, /* tune, step, scan completed */
185 RADIO_EVENT_METADATA = 4, /* New meta data received */
186 RADIO_EVENT_TA = 5, /* Traffic announcement start or stop */
187 RADIO_EVENT_AF_SWITCH = 6, /* Switch to Alternate Frequency */
188 RADIO_EVENT_EA = 7, /* Emergency announcement start or stop */
189 // begin framework only events
190 RADIO_EVENT_CONTROL = 100, /* loss/gain of tuner control */
191 RADIO_EVENT_SERVER_DIED = 101, /* radio service died */
192 };
193 typedef unsigned int radio_event_type_t;
194
195 /* Event passed to the framework by the HAL callback */
196 typedef struct radio_hal_event {
197 radio_event_type_t type; /* event type */
198 int status; /* used by RADIO_EVENT_CONFIG, RADIO_EVENT_TUNED */
199 union {
200 /* RADIO_EVENT_ANTENNA, RADIO_EVENT_TA, RADIO_EVENT_EA */
201 bool on;
202 radio_hal_band_config_t config; /* RADIO_EVENT_CONFIG */
203 radio_program_info_t info; /* RADIO_EVENT_TUNED, RADIO_EVENT_AF_SWITCH */
204 radio_metadata_t *metadata; /* RADIO_EVENT_METADATA */
205 };
206 } radio_hal_event_t;
207
208 /* Used internally by the framework. Same information as in struct radio_hal_event */
209 typedef struct radio_event {
210 radio_event_type_t type;
211 int status;
212 union {
213 bool on;
214 radio_band_config_t config;
215 radio_program_info_t info;
216 radio_metadata_t *metadata; /* offset from start of struct when in shared memory */
217 };
218 } radio_event_t;
219
220
radio_rds_for_region(bool rds,radio_region_t region)221 static radio_rds_t radio_rds_for_region(bool rds, radio_region_t region) {
222 if (!rds)
223 return RADIO_RDS_NONE;
224 switch(region) {
225 case RADIO_REGION_ITU_1:
226 case RADIO_REGION_OIRT:
227 case RADIO_REGION_JAPAN:
228 case RADIO_REGION_KOREA:
229 return RADIO_RDS_WORLD;
230 case RADIO_REGION_ITU_2:
231 return RADIO_RDS_US;
232 default:
233 return RADIO_REGION_NONE;
234 }
235 }
236
radio_demephasis_for_region(radio_region_t region)237 static radio_deemphasis_t radio_demephasis_for_region(radio_region_t region) {
238 switch(region) {
239 case RADIO_REGION_KOREA:
240 case RADIO_REGION_ITU_2:
241 return RADIO_DEEMPHASIS_75;
242 case RADIO_REGION_ITU_1:
243 case RADIO_REGION_OIRT:
244 case RADIO_REGION_JAPAN:
245 default:
246 return RADIO_DEEMPHASIS_50;
247 }
248 }
249
250 #endif // ANDROID_RADIO_H
251