broadcastradio/1.0/types.hal

   1 /*
   2  * Copyright 2016 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 package android.hardware.broadcastradio@1.0;
  18
  19 enum Result : int32_t {
  20     OK,
  21     NOT_INITIALIZED,
  22     INVALID_ARGUMENTS,
  23     INVALID_STATE,
  24     TIMEOUT,
  25 };
  26
  27 /**
  28  * Radio hardware module class. A given radio hardware module HAL is of one
  29  * class only. The platform can not have more than one hardware module of
  30  * each class. Current version of the framework only supports RADIO_CLASS_AM_FM.
  31  */
  32 enum Class : uint32_t {
  33     /** FM (including HD radio) and AM */
  34     AM_FM = 0,
  35     /** Satellite Radio */
  36     SAT   = 1,
  37     /** Digital Radio (DAB) */
  38     DT    = 2,
  39 };
  40
  41 /** value for field "type" of radio band described in struct radio_hal_band_config */
  42 enum Band : uint32_t {
  43     /** Amplitude Modulation band: LW, MW, SW */
  44     AM     = 0,
  45     /** Frequency Modulation band: FM */
  46     FM     = 1,
  47     /** FM HD Radio / DRM (IBOC) */
  48     FM_HD  = 2,
  49     /** AM HD Radio / DRM (IBOC) */
  50     AM_HD  = 3,
  51 };
  52
  53 /** RDS variant implemented. A struct FmBandConfig can list none or several. */
  54 enum Rds : uint32_t {
  55     NONE   = 0,
  56     WORLD  = (1<<0),
  57     US = (1<<1),
  58 };
  59
  60
  61 /* FM deemphasis variant implemented.
  62  * A struct FmBandConfig can list one or more. */
  63 enum Deemphasis : uint32_t {
  64     D50   = (1<<0),
  65     D75   = (1<<1),
  66 };
  67
  68 /** Scanning direction for scan() and step() tuner APIs */
  69 enum Direction : uint32_t {
  70     UP,
  71     DOWN
  72 };
  73
  74 /** Unique handle allocated to a radio module */
  75 typedef uint32_t Handle;
  76
  77
  78 /** Additional attributes for an FM band configuration */
  79 struct FmBandConfig {
  80     /** deemphasis variant */
  81     Deemphasis deemphasis;
  82     /** stereo supported */
  83     bool       stereo;
  84     /** RDS variants supported */
  85     Rds        rds;
  86     /** Traffic Announcement supported */
  87     bool       ta;
  88     /** Alternate Frequency supported */
  89     bool       af;
  90     /** Emergency announcements supported */
  91     bool       ea;
  92 };
  93
  94 /** Additional attributes for an AM band configuration */
  95 struct AmBandConfig {
  96     /** Stereo supported */
  97     bool       stereo;
  98 };
  99
 100 /* Radio band configuration. Describes a given band supported by the radio
 101  * module. The HAL can expose only one band per type with the the maximum range
 102  * supported and all options. The framework will derive the actual regions were
 103  * this module can operate and expose separate band configurations for
 104  * applications to chose from. */
 105 struct BandConfig {
 106     Band type;
 107     bool antennaConnected;
 108     uint32_t lowerLimit;
 109     uint32_t upperLimit;
 110     vec<uint32_t> spacings;
 111     union Ext {
 112         FmBandConfig fm;
 113         AmBandConfig am;
 114     } ext;
 115 };
 116
 117 /* Exposes properties of a given hardware radio module.
 118  * NOTE: current framework implementation supports only one audio source
 119  * (num_audio_sources = 1). The source corresponds to AUDIO_DEVICE_IN_FM_TUNER.
 120  * If more than one tuner is supported (num_tuners > 1), only one can be
 121  * connected to the audio source. */
 122 struct Properties {
 123     /** Class of this module. E.g AM_FM */
 124     Class           classId;
 125     /** implementor name */
 126     string          implementor;
 127     /** product name */
 128     string          product;
 129     /** product version */
 130     string          version;
 131     /** serial number (for subscription services) */
 132     string          serial;
 133     /** number of tuners controllable independently */
 134     uint32_t        numTuners;
 135     /** number of audio sources driven simultaneously */
 136     uint32_t        numAudioSources;
 137     /** the hardware supports capture of audio source from audio HAL */
 138     bool            supportsCapture;
 139     vec<BandConfig> bands; /** band descriptors */
 140 };
 141
 142 enum MetadataType : int32_t {
 143     INVALID    = -1,
 144     /** Signed 32 bit integer  */
 145     INT        = 0,
 146     /** String */
 147     TEXT       = 1,
 148     /**
 149      * Raw binary data (icon or art).
 150      *
 151      * The data should be a valid PNG, JPEG, GIF or BMP file.
 152      * Invalid format must be handled gracefully as if the field was missing.
 153      */
 154     RAW        = 2,
 155     /** clock data, see MetaDataClock */
 156     CLOCK      = 3,
 157 };
 158
 159 enum MetadataKey : int32_t {
 160     INVALID      = -1,
 161     /** RDS PI                 - int32_t  */
 162     RDS_PI       = 0,
 163     /** RDS PS                 - string */
 164     RDS_PS       = 1,
 165     /** RDS PTY                - int32_t  */
 166     RDS_PTY      = 2,
 167     /** RBDS PTY               - int32_t  */
 168     RBDS_PTY     = 3,
 169     /** RDS RT                 - string  */
 170     RDS_RT       = 4,
 171     /** Song title             - string  */
 172     TITLE        = 5,
 173     /** Artist name            - string  */
 174     ARTIST       = 6,
 175     /** Album name             - string  */
 176     ALBUM        = 7,
 177     /** Musical genre          - string  */
 178     GENRE        = 8,
 179     /** Station icon           - raw (int32_t for HAL 1.1) */
 180     ICON         = 9,
 181     /** Album art              - raw (int32_t for HAL 1.1) */
 182     ART          = 10,
 183     /** Clock                  - MetaDataClock */
 184     CLOCK        = 11,
 185 };
 186
 187 struct MetaDataClock {
 188      /** Seconds since epoch at GMT + 0. */
 189     uint64_t utcSecondsSinceEpoch;
 190     /** Minutes offset from the GMT. */
 191     int32_t timezoneOffsetInMinutes;
 192 };
 193
 194 struct MetaData {
 195     MetadataType type;
 196     MetadataKey key;
 197     /** Value used for type MetadataType.INT */
 198     int32_t intValue;
 199     /** Value used for type MetadataType.CLOCK */
 200     MetaDataClock  clockValue;
 201     /** Value used for type MetadataType.TEXT */
 202     string  stringValue;
 203     /** Value used for type MetadataType.RAW */
 204     vec<uint8_t> rawValue;
 205 };
 206
 207
 208 /* Radio program information. Returned by the HAL with event RADIO_EVENT_TUNED.
 209  * Contains information on currently tuned channel.
 210  */
 211 struct ProgramInfo {
 212     uint32_t     channel;   /** current channel. (e.g kHz for band type AM_FM) */
 213     uint32_t     subChannel; /** current sub channel. (FM_HD) */
 214
 215     /**
 216      * Tuned to a program (not a noise). It's the same condition that would
 217      * stop scan operation.
 218      */
 219     bool         tuned;
 220
 221     bool         stereo;    /** program is stereo or not */
 222     bool         digital;   /** digital program or not (e.g HD Radio program) */
 223
 224     /**
 225      * Signal quality measured in 0% to 100% range.
 226      *
 227      * Despite the name, this is not a signal strength.
 228      * The purpose of this field is primarily informative.
 229      */
 230     uint32_t signalStrength;
 231
 232     vec<MetaData> metadata; /** Metadata: PTY, song title etc. */
 233 };
 234