README.fuchsia.md
1Name: bt-hci-virtual
2
3License File: licenses.spdx.json
4 -> License File Format: SPDX
5
6Description:
7TODO(b/305983301): Automatically generate this file.
8
README.md
1# Bluetooth Virtual Driver
2
3## About
4
5The Bluetooth virtual driver is a Bluetooth controller emulator that allows
6system Bluetooth components to be tested in integration against the Bluetooth
7HCI protocol.
8
9The virtual driver currently supports the LoopbackDevice and EmulatorDevice.
10
11The driver is created by the VirtualController class. VirtualController uses
12DFv2 to create a virtual driver node (bt-hci-virtual) that can then have
13children nodes (LoopbackDevice and/or EmulatorDevice). This allows the DFv2
14logic to be contained to VirtualController.
15
16## LoopbackDevice
17
18LoopbackDevice is used by RootCanal, which is used by PTS-bot. The step numbers
19below are correlated with the numbers in the diagram.
20
21### Steps
22
231. `ffx emu start` creates bt-hci-emulator device
242. VirtualController driver binds to bt-hci-emulator device (specified in
25 [bt-hci-virtual.bind](//src/connectivity/bluetooth/hci/virtual/bt-hci-virtual.bind))
263. VirtualController driver is started by DFv2
274. VirtualController is added as a device node (bt-hci-virtual) to the node
28 graph inside `/dev/sys/platform/00:00:30`
295. RootCanal detects bt-hci-virtual in `/dev/sys/platform/00:00:30` and calls
30 `create_loopback_device()`
316. bt-hci-virtual uses the LoopbackDevice class to add a device node (loopback)
32 to the node graph inside `/dev/class/bt-hci`
337. bt-init detects the LoopbackDevice in `/dev/class/bt-hci` and creates a new
34 bt-host component
35
36```
37 2. bt-hci-virtual.bind dictates
38 ┌───────────────────────┐ that bt-hci-virtual will bind ┌───────────────────┐
39 │ bt-hci-emulator ├─────────────────────────────────│ VirtualController |
40 │ 1. Created by ffx emu │ to bt-hci-emulator └─────────┬─────────┘
41 └───────────┬───────────┘ │
42 │ │
43 │ │
44 ▼ 3. DriverBase::Start() |
45┌─────────────────────────────────────────┐◄────────────────────────────────┘
46│ bt-hci-virtual │
47│ 4. Added to /dev/sys/platform/00:00:30/ │ 5. create_loopback_device()
48└───────────────────┬─────────────────────┘◄────────────────────────────────┐
49 │ │
50 │ |
51 ▼ ┌──────────────┐
52 ┌───────────────────────────────┐ │ bt-rootcanal │
53 │ loopback │ | Server |
54 │ 6. Added to /dev/class/bt-hci │ └──────────────┘
55 └───────────────┬───────────────┘
56 │
57 │
58 ▼
59 ┌────────────────────┐
60 │ bt-host │
61 └────────────────────┘
62```
63
64## EmulatorDevice
65
66EmulatorDevice is used for Bluetooth integration tests. The
67[fuchsia.hardware.bluetooth.Emulator](//sdk/fidl/fuchsia.hardware.bluetooth/virtual.fidl)
68API is used to establish and interact with the EmulatorDevice. The step numbers
69below are correlated with the numbers in the diagram. Please note that the term
70“emulator” is heavily overloaded, so it’s important to be precise when using the
71term.
72
73### Steps
74
751. `ffx emu start` creates bt-hci-emulator device
762. VirtualController driver binds to bt-hci-emulator device (specified in
77 [bt-hci-virtual.bind](//src/connectivity/bluetooth/hci/virtual/bt-hci-virtual.bind))
783. VirtualController driver is started by DFv2
794. VirtualController is added as a device node (bt-hci-virtual) to the node
80 graph inside `/dev/sys/platform/00:00:30`
815. The hci-emulator-client detects bt-hci-virtual in
82 `/dev/sys/platform/00:00:30` and calls `create_emulator()`
836. bt-hci-virtual uses the EmulatorDevice class to add a device node (emulator)
84 to the node graph inside `/dev/class/bt-emulator`
857. Use the Emulator.Publish method publishes a bt-hci device as a child of the
86 EmulatorDevice
878. The EmulatorDevice adds a device node (bt-hci-device) to the node graph
88 inside `/dev/class/bt-hci`
899. Other Emulator API calls can be made
9010. bt-init detects bt-hci-device in `/dev/class/bt-hci` and creates a new
91 bt-host component using a FakeController to mimic the BT controller
92
93```
94 2. bt-hci-virtual.bind dictates
95 ┌───────────────────────┐ that bt-hci-virtual will bind ┌───────────────────┐
96 │ bt-hci-emulator ├─────────────────────────────────│ VirtualController |
97 │ 1. Created by ffx emu │ to bt-hci-emulator └─────────┬─────────┘
98 └───────────┬───────────┘ │
99 │ │
100 │ │
101 ▼ 3. DriverBase::Start() |
102┌─────────────────────────────────────────┐◄────────────────────────────────┘
103│ bt-hci-virtual │
104│ 4. Added to /dev/sys/platform/00:00:30/ │ 5. create_emulator()
105└───────────────────┬─────────────────────┘◄────────────────────────────────┐
106 │ │
107 │ |
108┌───────────────────────────────────────────┐ |
109| EmulatorDevice class | |
110| | | |
111| ▼ | ┌─────────────────────┐
112| ┌────────────────────────────────────┐ | │ hci-emulator-client │
113| │ emulator │ | └──────────┬──────────┘
114| │ 6. Added to /dev/class/bt-emulator │ | 7. Emulator::Publish() |
115| │ │◄─|───────────────────────────────┘
116| └───────────────┬────────────────────┘◄─|───────────────────────────────┐
117| │ | 9 . Other Emulator API calls |
118| │ | |
119| ▼ | ┌──────────────────────┐
120| ┌───────────────────────────────┐ | | BT Integration Tests |
121| │ bt-hci-device │ | └──────────────────────┘
122| │ 8. Added to /dev/class/bt-hci | |
123| └───────────────┬───────────────┘ |
124| │ |
125| │ |
126| ▼ |
127| ┌────────────────────┐ |
128| │ bt-host │ |
129| │ ┌──────────────┐ │ |
130| | |FakeController| | |
131| | └──────────────┘ | |
132| └────────────────────┘ |
133└───────────────────────────────────────────┘
134```
135