Merge "RootCanal: Update README.md"

tools/rootcanal/README.md

-# RootCanal
+# Introduction
 
-RootCanal is a virtual Bluetooth Controller.
-Its goals include, but are not limited to: Bluetooth Testing and Emulation.
+RootCanal is a virtual Bluetooth Controller. RootCanal aims reducing the
+overhead of writing and deploying end-to-end tests on Bluetooth devices
+by taking away the physical layer.
+
+## Feature emulation
+
+The emulation of Bluetooth features on RootCanal _is limited to features
+that have direct consequences on connected hosts_. The accurate implementation
+of HCI commands and events is thus critical to RootCanal's goal, while accurate
+emulation of the scheduler and base-band is out of scope.
 
 ## Usage
 
-RootCanal is usable:
-- With the Cuttlefish Virtual Device.
-- As a Host standalone binary.
-- As a Bluetooth HAL.
-- As a library.
+### Emulator integration
 
-### Cuttlefish Virtual Device
+RootCanal is natively integrated in the Cuttlefish and Goldfish emulators.
+Bluetooth is enabled by default on these platforms. External hosts can connect
+to the HCI port 7300 to interact with the emulated device.
 
-Cuttlefish enables RootCanal by default, refer to the Cuttlefish documentation
-for more informations
+### Standalone tool
 
-### Host standalone binary
+RootCanal can be built and started as a standalone tool.
+Instructions to build and run root-canal from an AOSP instance:
 
 ```bash
-m root-canal # Build RootCanal
-out/host/linux-x86/bin/root-canal # Run RootCanal
+source build/envsetup.sh
+lunch aosp_cf_x86_64_phone-userdebug
+m root-canal
+./out/host/linux-x86/bin/root-canal
 ```
+Note: You can also find a prebuilt version inside
+[cvd-host_package.tar.gz from Android CI][cvd-host_package]
+The following configuration options are implemented:
 
-Note: You can also find a prebuilt version inside [cvd-host_package.tar.gz from Android CI][cvd-host_package]
+* `--test_port` (default `6401`) Configure the TCP port for the test channel.
 
-[cvd-host_package]: https://ci.android.com/builds/latest/branches/aosp-master/targets/aosp_cf_x86_64_phone-userdebug/view/cvd-host_package.tar.gz
+* `--hci_port` (default `6402`) Configure the TCP port for the HCI server.
+
+* `--link_port` (default `6403`) Configure the TCP port for the link server.
+
+* `--link_ble_port` (default `6404`) Configure the TCP port for the BLE link server.
+
+* `--controller_properties_file` (default `""`) Configure the path to
+a custom Controller configuration file. All properties defined in
+`model/controller/controller_properties.h` can be edited to test with a
+specific controller setup.
 
-RootCanal when run as a host tool, exposes 4 ports by default:
-- 6401: Test channel port
-- 6402: HCI port
-- 6403: BR_EDR Phy port
-- 6404: LE Phy port
+* `--enable_hci_sniffer` (default `false`) Capture PCAP traces for all
+connected HCI hosts. The PCAP traces are saved in the current directory.
 
-### Bluetooth HAL
+* `--enable_baseband_sniffer` (default `false`) Capture PCAP traces for all
+base-band packets exchanged between connection HCI hosts. The PCAP traces are
+saved in the current directory. This option is useful to inspect and debug
+RootCanal's implementation.
 
-A HAL using RootCanal is available as `android.hardware.bluetooth@1.1-service.sim`
+# Architecture
 
-## Channels
+All RootCanal instances expose four TCP ports:
+- _HCI channel_
+- _Test channel_
+- _BR_EDR Phy channel_
+- _LE Phy channel_
 
-### HCI Channel
+## HCI Channel
 
-The HCI channel uses the standard Bluetooth UART transport protocol (also known as H4) over TCP.
-You can refer to Vol 4, Part A, 2 of the Bluetooth Core Specification for more information.
-Each connection on the HCI channel creates a new virtual controller.
+The HCI channel implements the Bluetooth UART transport protocol
+(a.k.a. H4) over TCP. Each new connection on the HCI port spawns a new virtual
+controller.
 
-### Test Channel
+## Test Channel
 
-The test channel uses a simple custom protocol to send test commands to RootCanal.
-You can connect to it using [scripts/test_channel.py](scripts/test_channel.py).
+The test channel uses a simple custom protocol to send control commands
+to RootCanal. You can connect to it using [scripts/test_channel.py](scripts/test_channel.py).
 
 ### Phy Channels
 
-The physical channels uses a custom protocol described in [packets/link_layer_packets.pdl](packets/link_layer_packets.pdl)
-with a custom framing.
-**Warning:** The protocol can change in backward incompatible ways, be careful when depending on it.
+The physical channels use a custom protocol described in [packets/link_layer_packets.pdl](packets/link_layer_packets.pdl).
+The protocol simplifies the LL and LMP protocol packets defined in the Bluetooth
+specification to abstract over negotiation details.
+
+**Warning** The protocol can change in backward incompatible ways,
+be careful when depending on it.
+
+Controllers can exchanges link layer packets only when they are part of the
+same phy. One controller can be added to multiple phys, the simplest example
+begin BR/EDR and LE dual phys.
+
+# Links
+
+[cvd-host_package]: https://ci.android.com/builds/latest/branches/aosp-master/targets/aosp_cf_x86_64_phone-userdebug/view/cvd-host_package.tar.gz