Documentation/admin-guide/media/si4713.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 .. include:: <isonum.txt>
   4
   5 The Silicon Labs Si4713 FM Radio Transmitter Driver
   6 ===================================================
   7
   8 Copyright |copy| 2009 Nokia Corporation
   9
  10 Contact: Eduardo Valentin <eduardo.valentin@nokia.com>
  11
  12
  13 Information about the Device
  14 ----------------------------
  15
  16 This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address.
  17 Basically, it has transmission and signal noise level measurement features.
  18
  19 The Si4713 integrates transmit functions for FM broadcast stereo transmission.
  20 The chip also allows integrated receive power scanning to identify low signal
  21 power FM channels.
  22
  23 The chip is programmed using commands and responses. There are also several
  24 properties which can change the behavior of this chip.
  25
  26 Users must comply with local regulations on radio frequency (RF) transmission.
  27
  28 Device driver description
  29 -------------------------
  30
  31 There are two modules to handle this device. One is a I2C device driver
  32 and the other is a platform driver.
  33
  34 The I2C device driver exports a v4l2-subdev interface to the kernel.
  35 All properties can also be accessed by v4l2 extended controls interface, by
  36 using the v4l2-subdev calls (g_ext_ctrls, s_ext_ctrls).
  37
  38 The platform device driver exports a v4l2 radio device interface to user land.
  39 So, it uses the I2C device driver as a sub device in order to send the user
  40 commands to the actual device. Basically it is a wrapper to the I2C device driver.
  41
  42 Applications can use v4l2 radio API to specify frequency of operation, mute state,
  43 etc. But mostly of its properties will be present in the extended controls.
  44
  45 When the v4l2 mute property is set to 1 (true), the driver will turn the chip off.
  46
  47 Properties description
  48 ----------------------
  49
  50 The properties can be accessed using v4l2 extended controls.
  51 Here is an output from v4l2-ctl util:
  52
  53 .. code-block:: none
  54
  55         / # v4l2-ctl -d /dev/radio0 --all -L
  56         Driver Info:
  57                 Driver name   : radio-si4713
  58                 Card type     : Silicon Labs Si4713 Modulator
  59                 Bus info      :
  60                 Driver version: 0
  61                 Capabilities  : 0x00080800
  62                         RDS Output
  63                         Modulator
  64         Audio output: 0 (FM Modulator Audio Out)
  65         Frequency: 1408000 (88.000000 MHz)
  66         Video Standard = 0x00000000
  67         Modulator:
  68                 Name                 : FM Modulator
  69                 Capabilities         : 62.5 Hz stereo rds
  70                 Frequency range      : 76.0 MHz - 108.0 MHz
  71                 Subchannel modulation: stereo+rds
  72
  73         User Controls
  74
  75                                 mute (bool) : default=1 value=0
  76
  77         FM Radio Modulator Controls
  78
  79                 rds_signal_deviation (int)  : min=0 max=90000 step=10 default=200 value=200 flags=slider
  80                         rds_program_id (int)  : min=0 max=65535 step=1 default=0 value=0
  81                 rds_program_type (int)  : min=0 max=31 step=1 default=0 value=0
  82                         rds_ps_name (str)  : min=0 max=96 step=8 value='si4713  '
  83                         rds_radio_text (str)  : min=0 max=384 step=32 value=''
  84         audio_limiter_feature_enabled (bool) : default=1 value=1
  85         audio_limiter_release_time (int)  : min=250 max=102390 step=50 default=5010 value=5010 flags=slider
  86                 audio_limiter_deviation (int)  : min=0 max=90000 step=10 default=66250 value=66250 flags=slider
  87         audio_compression_feature_enabl (bool) : default=1 value=1
  88                 audio_compression_gain (int)  : min=0 max=20 step=1 default=15 value=15 flags=slider
  89         audio_compression_threshold (int)  : min=-40 max=0 step=1 default=-40 value=-40 flags=slider
  90         audio_compression_attack_time (int)  : min=0 max=5000 step=500 default=0 value=0 flags=slider
  91         audio_compression_release_time (int)  : min=100000 max=1000000 step=100000 default=1000000 value=1000000 flags=slider
  92         pilot_tone_feature_enabled (bool) : default=1 value=1
  93                 pilot_tone_deviation (int)  : min=0 max=90000 step=10 default=6750 value=6750 flags=slider
  94                 pilot_tone_frequency (int)  : min=0 max=19000 step=1 default=19000 value=19000 flags=slider
  95                 pre_emphasis_settings (menu) : min=0 max=2 default=1 value=1
  96                 tune_power_level (int)  : min=0 max=120 step=1 default=88 value=88 flags=slider
  97                 tune_antenna_capacitor (int)  : min=0 max=191 step=1 default=0 value=110 flags=slider
  98
  99 Here is a summary of them:
 100
 101 * Pilot is an audible tone sent by the device.
 102
 103 - pilot_frequency - Configures the frequency of the stereo pilot tone.
 104 - pilot_deviation - Configures pilot tone frequency deviation level.
 105 - pilot_enabled - Enables or disables the pilot tone feature.
 106
 107 * The si4713 device is capable of applying audio compression to the
 108   transmitted signal.
 109
 110 - acomp_enabled - Enables or disables the audio dynamic range control feature.
 111 - acomp_gain - Sets the gain for audio dynamic range control.
 112 - acomp_threshold - Sets the threshold level for audio dynamic range control.
 113 - acomp_attack_time - Sets the attack time for audio dynamic range control.
 114 - acomp_release_time - Sets the release time for audio dynamic range control.
 115
 116 * Limiter setups audio deviation limiter feature. Once a over deviation occurs,
 117   it is possible to adjust the front-end gain of the audio input and always
 118   prevent over deviation.
 119
 120 - limiter_enabled - Enables or disables the limiter feature.
 121 - limiter_deviation - Configures audio frequency deviation level.
 122 - limiter_release_time - Sets the limiter release time.
 123
 124 * Tuning power
 125
 126 - power_level - Sets the output power level for signal transmission.
 127   antenna_capacitor - This selects the value of antenna tuning capacitor
 128   manually or automatically if set to zero.
 129
 130 * RDS related
 131
 132 - rds_ps_name - Sets the RDS ps name field for transmission.
 133 - rds_radio_text - Sets the RDS radio text for transmission.
 134 - rds_pi - Sets the RDS PI field for transmission.
 135 - rds_pty - Sets the RDS PTY field for transmission.
 136
 137 * Region related
 138
 139 - preemphasis - sets the preemphasis to be applied for transmission.
 140
 141 RNL
 142 ---
 143
 144 This device also has an interface to measure received noise level. To do that, you should
 145 ioctl the device node. Here is an code of example:
 146
 147 .. code-block:: none
 148
 149         int main (int argc, char *argv[])
 150         {
 151                 struct si4713_rnl rnl;
 152                 int fd = open("/dev/radio0", O_RDWR);
 153                 int rval;
 154
 155                 if (argc < 2)
 156                         return -EINVAL;
 157
 158                 if (fd < 0)
 159                         return fd;
 160
 161                 sscanf(argv[1], "%d", &rnl.frequency);
 162
 163                 rval = ioctl(fd, SI4713_IOC_MEASURE_RNL, &rnl);
 164                 if (rval < 0)
 165                         return rval;
 166
 167                 printf("received noise level: %d\n", rnl.rnl);
 168
 169                 close(fd);
 170         }
 171
 172 The struct si4713_rnl and SI4713_IOC_MEASURE_RNL are defined under
 173 include/linux/platform_data/media/si4713.h.
 174
 175 Stereo/Mono and RDS subchannels
 176 -------------------------------
 177
 178 The device can also be configured using the available sub channels for
 179 transmission. To do that use S/G_MODULATOR ioctl and configure txsubchans properly.
 180 Refer to the V4L2 API specification for proper use of this ioctl.
 181
 182 Testing
 183 -------
 184 Testing is usually done with v4l2-ctl utility for managing FM tuner cards.
 185 The tool can be found in v4l-dvb repository under v4l2-apps/util directory.
 186
 187 Example for setting rds ps name:
 188
 189 .. code-block:: none
 190
 191         # v4l2-ctl -d /dev/radio0 --set-ctrl=rds_ps_name="Dummy"
 192