0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 .. include:: <isonum.txt>
0004
0005 The Silicon Labs Si4713 FM Radio Transmitter Driver
0006 ===================================================
0007
0008 Copyright |copy| 2009 Nokia Corporation
0009
0010 Contact: Eduardo Valentin <eduardo.valentin@nokia.com>
0011
0012
0013 Information about the Device
0014 ----------------------------
0015
0016 This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address.
0017 Basically, it has transmission and signal noise level measurement features.
0018
0019 The Si4713 integrates transmit functions for FM broadcast stereo transmission.
0020 The chip also allows integrated receive power scanning to identify low signal
0021 power FM channels.
0022
0023 The chip is programmed using commands and responses. There are also several
0024 properties which can change the behavior of this chip.
0025
0026 Users must comply with local regulations on radio frequency (RF) transmission.
0027
0028 Device driver description
0029 -------------------------
0030
0031 There are two modules to handle this device. One is a I2C device driver
0032 and the other is a platform driver.
0033
0034 The I2C device driver exports a v4l2-subdev interface to the kernel.
0035 All properties can also be accessed by v4l2 extended controls interface, by
0036 using the v4l2-subdev calls (g_ext_ctrls, s_ext_ctrls).
0037
0038 The platform device driver exports a v4l2 radio device interface to user land.
0039 So, it uses the I2C device driver as a sub device in order to send the user
0040 commands to the actual device. Basically it is a wrapper to the I2C device driver.
0041
0042 Applications can use v4l2 radio API to specify frequency of operation, mute state,
0043 etc. But mostly of its properties will be present in the extended controls.
0044
0045 When the v4l2 mute property is set to 1 (true), the driver will turn the chip off.
0046
0047 Properties description
0048 ----------------------
0049
0050 The properties can be accessed using v4l2 extended controls.
0051 Here is an output from v4l2-ctl util:
0052
0053 .. code-block:: none
0054
0055 / # v4l2-ctl -d /dev/radio0 --all -L
0056 Driver Info:
0057 Driver name : radio-si4713
0058 Card type : Silicon Labs Si4713 Modulator
0059 Bus info :
0060 Driver version: 0
0061 Capabilities : 0x00080800
0062 RDS Output
0063 Modulator
0064 Audio output: 0 (FM Modulator Audio Out)
0065 Frequency: 1408000 (88.000000 MHz)
0066 Video Standard = 0x00000000
0067 Modulator:
0068 Name : FM Modulator
0069 Capabilities : 62.5 Hz stereo rds
0070 Frequency range : 76.0 MHz - 108.0 MHz
0071 Subchannel modulation: stereo+rds
0072
0073 User Controls
0074
0075 mute (bool) : default=1 value=0
0076
0077 FM Radio Modulator Controls
0078
0079 rds_signal_deviation (int) : min=0 max=90000 step=10 default=200 value=200 flags=slider
0080 rds_program_id (int) : min=0 max=65535 step=1 default=0 value=0
0081 rds_program_type (int) : min=0 max=31 step=1 default=0 value=0
0082 rds_ps_name (str) : min=0 max=96 step=8 value='si4713 '
0083 rds_radio_text (str) : min=0 max=384 step=32 value=''
0084 audio_limiter_feature_enabled (bool) : default=1 value=1
0085 audio_limiter_release_time (int) : min=250 max=102390 step=50 default=5010 value=5010 flags=slider
0086 audio_limiter_deviation (int) : min=0 max=90000 step=10 default=66250 value=66250 flags=slider
0087 audio_compression_feature_enabl (bool) : default=1 value=1
0088 audio_compression_gain (int) : min=0 max=20 step=1 default=15 value=15 flags=slider
0089 audio_compression_threshold (int) : min=-40 max=0 step=1 default=-40 value=-40 flags=slider
0090 audio_compression_attack_time (int) : min=0 max=5000 step=500 default=0 value=0 flags=slider
0091 audio_compression_release_time (int) : min=100000 max=1000000 step=100000 default=1000000 value=1000000 flags=slider
0092 pilot_tone_feature_enabled (bool) : default=1 value=1
0093 pilot_tone_deviation (int) : min=0 max=90000 step=10 default=6750 value=6750 flags=slider
0094 pilot_tone_frequency (int) : min=0 max=19000 step=1 default=19000 value=19000 flags=slider
0095 pre_emphasis_settings (menu) : min=0 max=2 default=1 value=1
0096 tune_power_level (int) : min=0 max=120 step=1 default=88 value=88 flags=slider
0097 tune_antenna_capacitor (int) : min=0 max=191 step=1 default=0 value=110 flags=slider
0098
0099 Here is a summary of them:
0100
0101 * Pilot is an audible tone sent by the device.
0102
0103 - pilot_frequency - Configures the frequency of the stereo pilot tone.
0104 - pilot_deviation - Configures pilot tone frequency deviation level.
0105 - pilot_enabled - Enables or disables the pilot tone feature.
0106
0107 * The si4713 device is capable of applying audio compression to the
0108 transmitted signal.
0109
0110 - acomp_enabled - Enables or disables the audio dynamic range control feature.
0111 - acomp_gain - Sets the gain for audio dynamic range control.
0112 - acomp_threshold - Sets the threshold level for audio dynamic range control.
0113 - acomp_attack_time - Sets the attack time for audio dynamic range control.
0114 - acomp_release_time - Sets the release time for audio dynamic range control.
0115
0116 * Limiter setups audio deviation limiter feature. Once a over deviation occurs,
0117 it is possible to adjust the front-end gain of the audio input and always
0118 prevent over deviation.
0119
0120 - limiter_enabled - Enables or disables the limiter feature.
0121 - limiter_deviation - Configures audio frequency deviation level.
0122 - limiter_release_time - Sets the limiter release time.
0123
0124 * Tuning power
0125
0126 - power_level - Sets the output power level for signal transmission.
0127 antenna_capacitor - This selects the value of antenna tuning capacitor
0128 manually or automatically if set to zero.
0129
0130 * RDS related
0131
0132 - rds_ps_name - Sets the RDS ps name field for transmission.
0133 - rds_radio_text - Sets the RDS radio text for transmission.
0134 - rds_pi - Sets the RDS PI field for transmission.
0135 - rds_pty - Sets the RDS PTY field for transmission.
0136
0137 * Region related
0138
0139 - preemphasis - sets the preemphasis to be applied for transmission.
0140
0141 RNL
0142 ---
0143
0144 This device also has an interface to measure received noise level. To do that, you should
0145 ioctl the device node. Here is an code of example:
0146
0147 .. code-block:: none
0148
0149 int main (int argc, char *argv[])
0150 {
0151 struct si4713_rnl rnl;
0152 int fd = open("/dev/radio0", O_RDWR);
0153 int rval;
0154
0155 if (argc < 2)
0156 return -EINVAL;
0157
0158 if (fd < 0)
0159 return fd;
0160
0161 sscanf(argv[1], "%d", &rnl.frequency);
0162
0163 rval = ioctl(fd, SI4713_IOC_MEASURE_RNL, &rnl);
0164 if (rval < 0)
0165 return rval;
0166
0167 printf("received noise level: %d\n", rnl.rnl);
0168
0169 close(fd);
0170 }
0171
0172 The struct si4713_rnl and SI4713_IOC_MEASURE_RNL are defined under
0173 include/linux/platform_data/media/si4713.h.
0174
0175 Stereo/Mono and RDS subchannels
0176 -------------------------------
0177
0178 The device can also be configured using the available sub channels for
0179 transmission. To do that use S/G_MODULATOR ioctl and configure txsubchans properly.
0180 Refer to the V4L2 API specification for proper use of this ioctl.
0181
0182 Testing
0183 -------
0184 Testing is usually done with v4l2-ctl utility for managing FM tuner cards.
0185 The tool can be found in v4l-dvb repository under v4l2-apps/util directory.
0186
0187 Example for setting rds ps name:
0188
0189 .. code-block:: none
0190
0191 # v4l2-ctl -d /dev/radio0 --set-ctrl=rds_ps_name="Dummy"
0192
