Home | History | Annotate | Download | only in system
      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 
    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 
    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