cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

si4713.rst (6888B)


      1.. SPDX-License-Identifier: GPL-2.0
      2
      3.. include:: <isonum.txt>
      4
      5The Silicon Labs Si4713 FM Radio Transmitter Driver
      6===================================================
      7
      8Copyright |copy| 2009 Nokia Corporation
      9
     10Contact: Eduardo Valentin <eduardo.valentin@nokia.com>
     11
     12
     13Information about the Device
     14----------------------------
     15
     16This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address.
     17Basically, it has transmission and signal noise level measurement features.
     18
     19The Si4713 integrates transmit functions for FM broadcast stereo transmission.
     20The chip also allows integrated receive power scanning to identify low signal
     21power FM channels.
     22
     23The chip is programmed using commands and responses. There are also several
     24properties which can change the behavior of this chip.
     25
     26Users must comply with local regulations on radio frequency (RF) transmission.
     27
     28Device driver description
     29-------------------------
     30
     31There are two modules to handle this device. One is a I2C device driver
     32and the other is a platform driver.
     33
     34The I2C device driver exports a v4l2-subdev interface to the kernel.
     35All properties can also be accessed by v4l2 extended controls interface, by
     36using the v4l2-subdev calls (g_ext_ctrls, s_ext_ctrls).
     37
     38The platform device driver exports a v4l2 radio device interface to user land.
     39So, it uses the I2C device driver as a sub device in order to send the user
     40commands to the actual device. Basically it is a wrapper to the I2C device driver.
     41
     42Applications can use v4l2 radio API to specify frequency of operation, mute state,
     43etc. But mostly of its properties will be present in the extended controls.
     44
     45When the v4l2 mute property is set to 1 (true), the driver will turn the chip off.
     46
     47Properties description
     48----------------------
     49
     50The properties can be accessed using v4l2 extended controls.
     51Here 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
     99Here 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
    141RNL
    142---
    143
    144This device also has an interface to measure received noise level. To do that, you should
    145ioctl 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
    172The struct si4713_rnl and SI4713_IOC_MEASURE_RNL are defined under
    173include/linux/platform_data/media/si4713.h.
    174
    175Stereo/Mono and RDS subchannels
    176-------------------------------
    177
    178The device can also be configured using the available sub channels for
    179transmission. To do that use S/G_MODULATOR ioctl and configure txsubchans properly.
    180Refer to the V4L2 API specification for proper use of this ioctl.
    181
    182Testing
    183-------
    184Testing is usually done with v4l2-ctl utility for managing FM tuner cards.
    185The tool can be found in v4l-dvb repository under v4l2-apps/util directory.
    186
    187Example for setting rds ps name:
    188
    189.. code-block:: none
    190
    191	# v4l2-ctl -d /dev/radio0 --set-ctrl=rds_ps_name="Dummy"
    192