Add Kingfisher Si4689 support

Add conditionally compilable support for the Si4689 radio on the
M3ULCB Kingfisher infotainment board.  The codebase has been
refactored to allow multiple radio implementations, and when
Kingfisher support is enabled, the binding will first look for a
USB RTL-SDR adapter, then fallback to the Kingfisher Si4689 if
one is not found.  This allows easily switching to a RTL-SDR
adapter if this initial Kingfisher support encounters issues.

The back end implementation relies on a patched version of the
"si_ctl" utility from Cogent Embedded's Kingfisher BSP changes.
The modifications to it add FM band plan selection and scanning
threshold tweaking for poor radio environments.  Audio output is
achieved by looping the radio's PulseAudio source to the
appropriate sink depending on 4A or non-4A operation.  For 4A
compatibility, the PulseAudio source is created if it does not
exist, which currently is the case due to PulseAudio's udev
module being disabled when 4A is enabled.

Additionally, the FM band plan for Japan has been corrected to go
to 95 MHz, and a README.md file has been added documenting the
optional configuration that can be done via /etc/xdg/AGL.conf for
band plan selection and scanning sensitivity.

Change-Id: I204906fed741d917fc3b8be962deadb4e59989db
Signed-off-by: Scott Murray <scott.murray@konsulko.com>
Signed-off-by: Harunobu Kurokawa <harunobu.kurokawa.dn@renesas.com>

1 files changed, 78 insertions, 0 deletions

diff --git a/README.md b/README.md
index 1bfe68d..ab76ec2 100644
--- a/README.md
+++ b/README.md
@@ -31,3 +31,81 @@ JSON response has a single field **frequency** which is the currently tuned freq
 ### station_found Event JSON Response
 
 JSON response has a single field **value** of the frequency of the discovered radio station.
+
+# AGL Radio Tuner Binding
+
+## FM Band Plan Selection
+
+The FM band plan may be selected by adding:
+```
+fmbandplan=X
+```
+to the [radio] section in /etc/xdg/AGL.conf, where X is one of the
+following strings:
+
+US = United States / Canada
+JP = Japan
+EU = European Union
+ITU-1
+ITU-2
+
+Example:
+```
+[radio]
+fmbandplan=JP
+```
+
+## Implementation Specific Confguration
+
+### USB RTL-SDR adapter
+
+The scanning sensitivity can be tweaked by adding:
+```
+scan_squelch_level=X
+```
+to the [radio] section in /etc/xdg/AGL.conf, where X is an integer.  Lower
+values make the scanning more sensitive.  Default value is 140.
+
+Example:
+```
+[radio]
+scan_squelch_level=70
+```
+
+### M3ULCB Kingfisher Si4689
+
+The scanning sensitivity can be tweaked by adding:
+```
+scan_valid_snr_threshold=X
+scan_valid_rssi_threshold=Y
+```
+to the [radio] section in /etc/xdg/AGL.conf, where X and Y are integers
+between -127 and 127.  The SNR value is in units of dB, and the RSSI is in
+units of dBuV.  Lower values make the scanning more sensitive.  Default
+values in the Si4689 are 10 and 17, respectively. You may determine the
+values that the Si4689 is seeing when tuning by examining the results of
+tuning in the systemd journal, looking for lines like:
+
+Example:
+```
+[radio]
+scan_valid_snr_threshold=7
+scan_valid_rssi_threshold=10
+```
+
+## Known Issues
+
+### M3ULCB Kingfisher
+
+Initial setup for a new Kingfisher board requires booting an image with
+Kingfisher support and running the commands:
+```
+si_init
+si_firmware_update
+```
+This installs the provided firmware into the flash attached to the Si4689.
+
+Since all operations are currently done by calling a patched version of
+Cogent Embedded's si_ctl utility, scanning currently cannot be interrupted.
+Additionally, sometimes a failure in scanning seems to result in muted
+state that currently has not been debugged.