Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit b2993570 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[media] doc-rst: add documentation for si4713 



Convert it to ReST and add it to the media/v4l-drivers book.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent b4a41387

Documentation/media/v4l-drivers/si4713.rst

+105 −91
Original line number Diff line number Diff line 
Driver for I2C radios for the Silicon Labs Si4713 FM Radio Transmitters

.. include:: <isonum.txt>



The Silicon Labs Si4713 FM Radio Transmitter Driver

===================================================



Copyright |copy| 2009 Nokia Corporation



Copyright (c) 2009 Nokia Corporation

Contact: Eduardo Valentin <eduardo.valentin@nokia.com>





Information about the Device

============================

----------------------------



This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address.

Basically, it has transmission and signal noise level measurement features.
@@ -19,7 +24,8 @@ properties which can change the behavior of this chip. 
Users must comply with local regulations on radio frequency (RF) transmission.



Device driver description

=========================

-------------------------



There are two modules to handle this device. One is a I2C device driver

and the other is a platform driver.
@@ -37,10 +43,13 @@ etc. But mostly of its properties will be present in the extended controls. 
When the v4l2 mute property is set to 1 (true), the driver will turn the chip off.



Properties description

======================

----------------------



The properties can be accessed using v4l2 extended controls.

Here is an output from v4l2-ctl util:



.. code-block:: none



	/ # v4l2-ctl -d /dev/radio0 --all -L

	Driver Info:

		Driver name   : radio-si4713
@@ -84,55 +93,57 @@ audio_compression_feature_enabl (bool) : default=1 value=1 
		pre_emphasis_settings (menu) : min=0 max=2 default=1 value=1

		tune_power_level (int)  : min=0 max=120 step=1 default=88 value=88 flags=slider

		tune_antenna_capacitor (int)  : min=0 max=191 step=1 default=0 value=110 flags=slider

/ #



Here is a summary of them:



* Pilot is an audible tone sent by the device.



pilot_frequency - Configures the frequency of the stereo pilot tone.

pilot_deviation - Configures pilot tone frequency deviation level.

pilot_enabled - Enables or disables the pilot tone feature.

- pilot_frequency - Configures the frequency of the stereo pilot tone.

- pilot_deviation - Configures pilot tone frequency deviation level.

- pilot_enabled - Enables or disables the pilot tone feature.



* The si4713 device is capable of applying audio compression to the transmitted signal.

* The si4713 device is capable of applying audio compression to the

  transmitted signal.



acomp_enabled - Enables or disables the audio dynamic range control feature.

acomp_gain - Sets the gain for audio dynamic range control.

acomp_threshold - Sets the threshold level for audio dynamic range control.

acomp_attack_time - Sets the attack time for audio dynamic range control.

acomp_release_time - Sets the release time for audio dynamic range control.

- acomp_enabled - Enables or disables the audio dynamic range control feature.

- acomp_gain - Sets the gain for audio dynamic range control.

- acomp_threshold - Sets the threshold level for audio dynamic range control.

- acomp_attack_time - Sets the attack time for audio dynamic range control.

- acomp_release_time - Sets the release time for audio dynamic range control.



* Limiter setups audio deviation limiter feature. Once a over deviation occurs,

  it is possible to adjust the front-end gain of the audio input and always

  prevent over deviation.



limiter_enabled - Enables or disables the limiter feature.

limiter_deviation - Configures audio frequency deviation level.

limiter_release_time - Sets the limiter release time.

- limiter_enabled - Enables or disables the limiter feature.

- limiter_deviation - Configures audio frequency deviation level.

- limiter_release_time - Sets the limiter release time.



* Tuning power



power_level - Sets the output power level for signal transmission.

antenna_capacitor - This selects the value of antenna tuning capacitor manually

or automatically if set to zero.

- power_level - Sets the output power level for signal transmission.

  antenna_capacitor - This selects the value of antenna tuning capacitor

  manually or automatically if set to zero.



* RDS related



rds_ps_name - Sets the RDS ps name field for transmission.

rds_radio_text - Sets the RDS radio text for transmission.

rds_pi - Sets the RDS PI field for transmission.

rds_pty - Sets the RDS PTY field for transmission.

- rds_ps_name - Sets the RDS ps name field for transmission.

- rds_radio_text - Sets the RDS radio text for transmission.

- rds_pi - Sets the RDS PI field for transmission.

- rds_pty - Sets the RDS PTY field for transmission.



* Region related



preemphasis - sets the preemphasis to be applied for transmission.

- preemphasis - sets the preemphasis to be applied for transmission.



RNL

===

---



This device also has an interface to measure received noise level. To do that, you should

ioctl the device node. Here is an code of example:



.. code-block:: none



	int main (int argc, char *argv[])

	{

		struct si4713_rnl rnl;
@@ -160,17 +171,20 @@ The struct si4713_rnl and SI4713_IOC_MEASURE_RNL are defined under 
include/linux/platform_data/media/si4713.h.



Stereo/Mono and RDS subchannels

===============================

-------------------------------



The device can also be configured using the available sub channels for

transmission. To do that use S/G_MODULATOR ioctl and configure txsubchans properly.

Refer to the V4L2 API specification for proper use of this ioctl.



Testing

=======

-------

Testing is usually done with v4l2-ctl utility for managing FM tuner cards.

The tool can be found in v4l-dvb repository under v4l2-apps/util directory.



Example for setting rds ps name:



.. code-block:: none



	# v4l2-ctl -d /dev/radio0 --set-ctrl=rds_ps_name="Dummy"