Documentation/media/v4l-drivers/si476x.rst

SI476x Driver Readme
------------------------------------------------
	Copyright (C) 2013 Andrey Smirnov <andrew.smirnov@gmail.com>

TODO for the driver
------------------------------

- According to the SiLabs' datasheet it is possible to update the
  firmware of the radio chip in the run-time, thus bringing it to the
  most recent version. Unfortunately I couldn't find any mentioning of
  the said firmware update for the old chips that I tested the driver
  against, so for chips like that the driver only exposes the old
  functionality.


Parameters exposed over debugfs
-------------------------------
SI476x allow user to get multiple characteristics that can be very
useful for EoL testing/RF performance estimation, parameters that have
very little to do with V4L2 subsystem. Such parameters are exposed via
debugfs and can be accessed via regular file I/O operations.

The drivers exposes following files:

* /sys/kernel/debug/<device-name>/acf
  This file contains ACF(Automatically Controlled Features) status
  information. The contents of the file is binary data of the
  following layout:

  =============  ==============   ====================================
  Offset	  Name		  Description
  =============  ==============   ====================================
  0x00		  blend_int	  Flag, set when stereo separation has
				  crossed below the blend threshold
  0x01		  hblend_int	  Flag, set when HiBlend cutoff
				  frequency is lower than threshold
  0x02		  hicut_int	  Flag, set when HiCut cutoff
				  frequency is lower than threshold
  0x03		  chbw_int	  Flag, set when channel filter
				  bandwidth is less than threshold
  0x04		  softmute_int	  Flag indicating that softmute
				  attenuation has increased above
				  softmute threshold
  0x05		 smute		  0 - Audio is not soft muted
				  1 - Audio is soft muted
  0x06		  smattn	  Soft mute attenuation level in dB
  0x07		  chbw		  Channel filter bandwidth in kHz
  0x08		  hicut		  HiCut cutoff frequency in units of
				  100Hz
  0x09		  hiblend	  HiBlend cutoff frequency in units
				  of 100 Hz
  0x10		  pilot		  0 - Stereo pilot is not present
				  1 - Stereo pilot is present
  0x11		  stblend	  Stereo blend in %
  =============  ==============   ====================================


* /sys/kernel/debug/<device-name>/rds_blckcnt
  This file contains statistics about RDS receptions. It's binary data
  has the following layout:

  =============  ==============   ====================================
  Offset	  Name		  Description
  =============  ==============   ====================================
  0x00		  expected	  Number of expected RDS blocks
  0x02		  received	  Number of received RDS blocks
  0x04		  uncorrectable	  Number of uncorrectable RDS blocks
  =============  ==============   ====================================

* /sys/kernel/debug/<device-name>/agc
  This file contains information about parameters pertaining to
  AGC(Automatic Gain Control)

  The layout is:

  =============  ==============   ====================================
  Offset	  Name		  Description
  =============  ==============   ====================================
  0x00		  mxhi		  0 - FM Mixer PD high threshold is
				  not tripped
				  1 - FM Mixer PD high threshold is
				  tripped
  0x01		  mxlo		  ditto for FM Mixer PD low
  0x02		  lnahi		  ditto for FM LNA PD high
  0x03		  lnalo		  ditto for FM LNA PD low
  0x04		  fmagc1	  FMAGC1 attenuator resistance
				  (see datasheet for more detail)
  0x05		  fmagc2	  ditto for FMAGC2
  0x06		  pgagain	  PGA gain in dB
  0x07		  fmwblang	  FM/WB LNA Gain in dB
  =============  ==============   ====================================

* /sys/kernel/debug/<device-name>/rsq
  This file contains information about parameters pertaining to
  RSQ(Received Signal Quality)

  The layout is:

  =============  ==============   ====================================
  Offset	  Name		  Description
  =============  ==============   ====================================
  0x00		  multhint	  0 - multipath value has not crossed
				  the Multipath high threshold
				  1 - multipath value has crossed
				  the Multipath high threshold
  0x01		  multlint	  ditto for Multipath low threshold
  0x02		  snrhint	  0 - received signal's SNR has not
				  crossed high threshold
				  1 - received signal's SNR has
				  crossed high threshold
  0x03		  snrlint	  ditto for low threshold
  0x04		  rssihint	  ditto for RSSI high threshold
  0x05		  rssilint	  ditto for RSSI low threshold
  0x06		  bltf		  Flag indicating if seek command
				  reached/wrapped seek band limit
  0x07		  snr_ready	  Indicates that SNR metrics is ready
  0x08		  rssiready	  ditto for RSSI metrics
  0x09		  injside	  0 - Low-side injection is being used
				  1 - High-side injection is used
  0x10		  afcrl		  Flag indicating if AFC rails
  0x11		  valid		  Flag indicating if channel is valid
  0x12		  readfreq	  Current tuned frequency
  0x14		  freqoff	  Signed frequency offset in units of
				  2ppm
  0x15		  rssi		  Signed value of RSSI in dBuV
  0x16		  snr		  Signed RF SNR in dB
  0x17		  issi		  Signed Image Strength Signal
				  indicator
  0x18		  lassi		  Signed Low side adjacent Channel
				  Strength indicator
  0x19		  hassi		  ditto fpr High side
  0x20		  mult		  Multipath indicator
  0x21		  dev		  Frequency deviation
  0x24		  assi		  Adjacent channel SSI
  0x25		  usn		  Ultrasonic noise indicator
  0x26		  pilotdev	  Pilot deviation in units of 100 Hz
  0x27		  rdsdev	  ditto for RDS
  0x28		  assidev	  ditto for ASSI
  0x29		  strongdev	  Frequency deviation
  0x30		  rdspi		  RDS PI code
  =============  ==============   ====================================

* /sys/kernel/debug/<device-name>/rsq_primary
  This file contains information about parameters pertaining to
  RSQ(Received Signal Quality) for primary tuner only. Layout is as
  the one above.