1/**
2 * Copyright 2017 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
17package [email protected];
18
19import @1.0::types;
20
21typedef @1.0::Result Result;
22
23enum ProgramListResult : Result {
24    NOT_READY,
25    NOT_STARTED,
26    UNAVAILABLE,
27};
28
29/**
30 * Extra flags for program information.
31 */
32enum ProgramInfoFlags : uint32_t {
33    /**
34     * Set when the program is currently playing live stream.
35     * This may result in a slightly altered reception parameters,
36     * usually targetted at reduced latency.
37     */
38    LIVE = 1 << 0,
39
40    /**
41     * Radio stream is not playing, ie. due to bad reception conditions or
42     * buffering. In this state volume knob MAY be disabled to prevent user
43     * increasing volume too much.
44     */
45    MUTED = 1 << 1,
46
47    /**
48     * Station broadcasts traffic information regularly,
49     * but not necessarily right now.
50     */
51    TRAFFIC_PROGRAM = 1 << 2,
52
53    /**
54     * Station is broadcasting traffic information at the very moment.
55     */
56    TRAFFIC_ANNOUNCEMENT = 1 << 3,
57};
58
59/**
60 * A key-value pair for vendor-specific information to be passed as-is through
61 * Android framework to the front-end application.
62 */
63struct VendorKeyValue {
64    /**
65     * Key must be prefixed with unique vendor Java-style namespace,
66     * eg. 'com.somecompany.parameter1'.
67     */
68    string key;
69
70    /**
71     * Value must be passed through the framework without any changes.
72     * Format of this string can vary across vendors.
73     */
74    string value;
75};
76
77struct Properties {
78    @1.0::Properties base;
79
80    /**
81     * The hardware supports background scanning in general. At the given time
82     * it may not be available though, see startBackgroundScan.
83     */
84    bool supportsBackgroundScanning;
85
86    /**
87     * A list of supported ProgramType values.
88     *
89     * If a program type is supported by radio module, it means it can tune
90     * to ProgramSelector of a given type.
91     *
92     * Support for VENDOR program type does not guarantee compatibility, as
93     * other module properties (implementor, product, version) must be checked.
94     */
95    vec<uint32_t> supportedProgramTypes;
96
97    /**
98     * A list of supported IdentifierType values.
99     *
100     * If an identifier is supported by radio module, it means it can use it for
101     * tuning to ProgramSelector with either primary or secondary Identifier of
102     * a given type.
103     *
104     * Support for VENDOR identifier type does not guarantee compatibility, as
105     * other module properties (implementor, product, version) must be checked.
106     */
107    vec<uint32_t> supportedIdentifierTypes;
108
109    /**
110     * Vendor-specific information.
111     *
112     * It may be used for extra features, not supported by the platform,
113     * for example: com.me.preset-slots=6; com.me.ultra-hd-capable=false.
114     */
115    vec<VendorKeyValue> vendorInfo;
116};
117
118/**
119 * Type of modulation.
120 *
121 * Used as a value for DRMO_MODULATION IdentifierType.
122 */
123enum Modulation : uint32_t {
124    AM = 1,
125    FM,
126};
127
128/**
129 * Type of a radio technology.
130 *
131 * VENDOR program types must be opaque to the framework.
132 *
133 * There are multiple VENDOR program types just to make vendor implementation
134 * easier with multiple properitary radio technologies. They are treated the
135 * same by the framework.
136 *
137 * All other values are reserved for future use.
138 * Values not matching any enumerated constant must be ignored.
139 */
140enum ProgramType : uint32_t {
141    AM = 1,  // analogue AM radio (with or without RDS)
142    FM,      // analogue FM radio (with or without RDS)
143    AM_HD,   // AM HD Radio
144    FM_HD,   // FM HD Radio
145    DAB,     // Digital audio broadcasting
146    DRMO,    // Digital Radio Mondiale
147    SXM,     // SiriusXM Satellite Radio
148
149    // Vendor-specific, not synced across devices.
150    VENDOR_START = 1000,
151    VENDOR_END = 1999,
152};
153
154/**
155 * Type of program identifier component.
156 *
157 * It MUST match the radio technology for primary ID but does not have to match
158 * it for secondary IDs. For example, a satellite program may set AM/FM fallback
159 * frequency, if a station broadcasts both via satellite and AM/FM.
160 *
161 * VENDOR identifier types must be opaque to the framework.
162 *
163 * The value format for each (but VENDOR_PRIMARY) identifier is strictly defined
164 * to maintain interoperability between devices made by different vendors.
165 *
166 * All other values are reserved for future use.
167 * Values not matching any enumerated constant must be ignored.
168 */
169enum IdentifierType : uint32_t {
170    AMFM_FREQUENCY = 1,  // kHz
171    RDS_PI,              // 16bit
172
173    /**
174     * 64bit compound primary identifier for HD Radio.
175     *
176     * Consists of (from the LSB):
177     * - 32bit: Station ID number;
178     * - 4bit: HD_SUBCHANNEL;
179     * - 18bit: AMFM_FREQUENCY.
180     * The remaining bits should be set to zeros when writing on the chip side
181     * and ignored when read.
182     */
183    HD_STATION_ID_EXT,
184
185    /**
186     * HD Radio subchannel - a value of range 0-7.
187     *
188     * The subchannel index is 0-based (where 0 is MPS and 1..7 are SPS),
189     * as opposed to HD Radio standard (where it's 1-based).
190     */
191    HD_SUBCHANNEL,
192
193    /**
194     * 24bit compound primary identifier for DAB.
195     *
196     * Consists of (from the LSB):
197     * - 16bit: SId;
198     * - 8bit: ECC code.
199     * The remaining bits should be set to zeros when writing on the chip side
200     * and ignored when read.
201     */
202    DAB_SIDECC,
203
204    DAB_ENSEMBLE,     // 16bit
205    DAB_SCID,         // 12bit
206    DAB_FREQUENCY,    // kHz
207    DRMO_SERVICE_ID,  // 24bit
208    DRMO_FREQUENCY,   // kHz
209    DRMO_MODULATION,  // Modulation enum
210    SXM_SERVICE_ID,   // 32bit
211    SXM_CHANNEL,      // 0-999 range
212
213    /**
214     * Primary identifier for vendor-specific radio technology.
215     * The value format is determined by a vendor.
216     *
217     * It must not be used in any other programType than corresponding VENDOR
218     * type between VENDOR_START and VENDOR_END (eg. identifier type 1015 must
219     * not be used in any program type other than 1015).
220     */
221    VENDOR_PRIMARY_START = ProgramType:VENDOR_START,
222    VENDOR_PRIMARY_END = ProgramType:VENDOR_END,
223};
224
225/**
226 * A single program identifier component, eg. frequency or channel ID.
227 *
228 * The uint32_t type field maps to IdentifierType enum. It's not straight,
229 * because the enum may be extended in future versions of the HAL. Values out of
230 * the enum range must not be used when writing and ignored when reading.
231 *
232 * The uint64_t value field holds the value in format described in comments for
233 * IdentifierType enum.
234 */
235struct ProgramIdentifier {
236    uint32_t type;  // IdentifierType
237    uint64_t value;
238};
239
240/**
241 * A set of identifiers necessary to tune to a given station.
242 *
243 * This can hold various identifiers, like
244 * - AM/FM frequency
245 * - HD Radio subchannel
246 * - DAB channel info
247 *
248 * The uint32_t programType field maps to ProgramType enum. It's not straight,
249 * because the enum may be extended in future versions of the HAL. Values out of
250 * the enum range must not be used when writing and ignored when reading.
251 *
252 * The primary ID uniquely identifies a station and can be used for equality
253 * check. The secondary IDs are supplementary and can speed up tuning process,
254 * but the primary ID is sufficient (ie. after a full band scan).
255 *
256 * Two selectors with different secondary IDs, but the same primary ID are
257 * considered equal. In particular, secondary IDs vector may get updated for
258 * an entry on the program list (ie. when a better frequency for a given
259 * station is found).
260 *
261 * The primaryId of a given programType MUST be of a specific type:
262 * - AM, FM: RDS_PI if the station broadcasts RDS, AMFM_FREQUENCY otherwise;
263 * - AM_HD, FM_HD: HD_STATION_ID_EXT;
264 * - DAB: DAB_SIDECC;
265 * - DRMO: DRMO_SERVICE_ID;
266 * - SXM: SXM_SERVICE_ID;
267 * - VENDOR: VENDOR_PRIMARY.
268 */
269struct ProgramSelector {
270    uint32_t programType;  // ProgramType
271    ProgramIdentifier primaryId;  // uniquely identifies a station
272    vec<ProgramIdentifier> secondaryIds;
273
274    /**
275     * Opaque vendor-specific identifiers, to be passed to front-end
276     * without changes.
277     *
278     * The order is meaningful, ie. the first element may be defined as
279     * frequency, second as the subchannel etc.
280     *
281     * The vector is not serialized (either locally or to the cloud),
282     * unless it's a VENDOR program type.
283     */
284    vec<uint64_t> vendorIds;
285};
286
287/**
288 * Radio program information. Returned by the HAL with event RADIO_EVENT_TUNED.
289 * Contains information on currently tuned channel.
290 */
291struct ProgramInfo {
292    @1.0::ProgramInfo base;
293
294    ProgramSelector selector;
295
296    bitfield<ProgramInfoFlags> flags;
297
298    /**
299     * Vendor-specific information.
300     *
301     * It may be used for extra features, not supported by the platform,
302     * for example: paid-service=true; bitrate=320kbps.
303     */
304    vec<VendorKeyValue> vendorInfo;
305};
306