1.. _bluetooth-ctlr-arch:
2
3LE Controller
4#############
5
6Overview
7********
8
9.. image:: img/ctlr_overview.png
10
11#. HCI
12
13   * Host Controller Interface, Bluetooth standard
14   * Provides Zephyr Bluetooth HCI Driver
15
16#. HAL
17
18   * Hardware Abstraction Layer
19   * Vendor Specific, and Zephyr Driver usage
20
21#. Ticker
22
23   * Soft real time radio/resource scheduling
24
25#. LL_SW
26
27   * Software-based Link Layer implementation
28   * States and roles, control procedures, packet controller
29
30#. Util
31
32   * Bare metal memory pool management
33   * Queues of variable count, lockless usage
34   * FIFO of fixed count, lockless usage
35   * Mayfly concept based deferred ISR executions
36
37
38Architecture
39************
40
41Execution Overview
42==================
43
44.. image:: img/ctlr_exec_overview.png
45
46
47Architecture Overview
48=====================
49
50.. image:: img/ctlr_arch_overview.png
51
52
53Scheduling
54**********
55
56.. image:: img/ctlr_sched.png
57
58
59Ticker
60======
61
62.. image:: img/ctlr_sched_ticker.png
63
64
65Upper Link Layer and Lower Link Layer
66=====================================
67
68.. image:: img/ctlr_sched_ull_lll.png
69
70
71Scheduling Variants
72===================
73
74.. image:: img/ctlr_sched_variant.png
75
76
77ULL and LLL Timing
78==================
79
80.. image:: img/ctlr_sched_ull_lll_timing.png
81
82
83Event Handling
84**************
85
86.. image:: img/ctlr_sched_event_handling.png
87
88
89Scheduling Closely Spaced Events
90================================
91
92.. image:: img/ctlr_sched_msc_close_events.png
93
94
95Aborting Active Event
96=====================
97
98.. image:: img/ctlr_sched_msc_event_abort.png
99
100
101Cancelling Pending Event
102========================
103
104.. image:: img/ctlr_sched_msc_event_cancel.png
105
106
107Pre-emption of Active Event
108===========================
109
110.. image:: img/ctlr_sched_msc_event_preempt.png
111
112
113Data Flow
114*********
115
116Transmit Data Flow
117==================
118
119.. image:: img/ctlr_dataflow_tx.png
120
121
122Receive Data Flow
123=================
124
125.. image:: img/ctlr_dataflow_rx.png
126
127
128Execution Priorities
129********************
130
131.. image:: img/ctlr_exec_prio.png
132
133- Event handle (0, 1) < Event preparation (2, 3) < Event/Rx done (4) < Tx
134  request (5) < Role management (6) < Host (7).
135
136- LLL is vendor ISR, ULL is Mayfly ISR concept, Host is kernel thread.
137
138Link Layer Control Procedures
139*****************************
140
141Following is a brief fly in on the main concepts in the implementation of
142control procedures handling in ULL.
143
144Three main execution contexts
145=============================
146
147- HCI/LLCP API
148   * Miscellaneous procedure initiation API
149   * From ull_llcp.c::ull_cp_<proc>() for initiating local procedures
150   * Interface with running procedures, local and remote
151
152- lll_prepare context to drive ull_cp_run()
153   * LLCP main state machine entry/tick'er
154   * From ull_peripheral.c/ull_central.c::ticker_cb via ull_conn_llcp()
155
156- rx_demux context to drive ull_cp_tx_ack() and ull_cp_rx()
157   * LLCP tx ack handling and PDU reception
158   * From ull_conn.c::ull_conn_rx()
159   * Handles passing PDUs into running procedures as well as possibly initiating remote procedures
160
161Data structures and PDU helpers
162===============================
163
164- struct llcp_struct
165   * Main LLCP data store
166   * Defined in ull_conn_types.h and declared as part of struct ll_conn
167   * Holds local and remote procedure request queues as well as conn specific LLCP data
168   * Basic conn-level abstraction
169
170- struct proc_ctx
171   * General procedure context data, contains miscellaneous procedure data and state as well as sys_snode_t for queueing
172   * Defined in ull_llcp_internal.h, declared/instantiated through ull_llcp.c::create_procedure()
173   * Also holds node references used in tx_ack as well as rx_node retention mechanisms
174
175- struct llcp_mem_pool
176   * Mem pool used to implement procedure contexts resource - instantiated in both a local and a remote version
177   * Used through ull_llcp.c::create_procedure()
178
179- Miscellaneous pdu gymnastics
180   * Encoding and decoding of control pdus done by ull_llcp_pdu.c::llcp_pdu_encode/decode_<PDU>()
181   * Miscellaneous pdu validation handled by ull_llcp.c::pdu_validate_<PDU>() via ull_llcp.c::pdu_is_valid()
182
183LLCP local and remote request/procedure state machines
184======================================================
185
186- ull_llcp_local.c
187   * State machine handling local initiated procedures
188   * Naming concept: lr _<...> => local request machine
189   * Local procedure queue handling
190   * Local run/rx/tx_ack switch
191
192- ull_llcp_remote.c
193   * Remote versions of the above
194   * Naming concept: rr_<...> => remote request machine
195   * Also handling of remote procedure initiation by llcp_rx_new()
196   * Miscellaneous procedure collision handling (in rr_st_idle())
197
198- ull_llcp_common/conn_upd/phy/enc/cc/chmu.c
199   * Individual procedure implementations (ull_llcp_common.c collects the simpler ones)
200   * Naming concept: lp_<...> => local initiated procedure, rp_<...> => remote initiated procedure
201   * Handling of procedure flow from init (possibly through instant) to completion and host notification if applicable
202
203Miscellaneous concepts
204======================
205
206- Procedure collision handling
207   * See BT spec for explanation
208   * Basically some procedures can exist in parallel but some can't - for instance only one instant based at a time
209   * Spec states rules for how to handle/resolve collisions when they happen
210
211- Termination handling
212   * Specific rules apply re. how termination is handled.
213   * Since we have resource handling re. procedure contexts and terminate must always be available this is handled as a special case
214   * Note also - there are miscellaneous cases where connection termination is triggered on invalid peer behavior
215
216- New remote procedure handling
217   * Table new_proc_lut[] maps LLCP PDUs to procedures/roles used in llcp_rr_new()
218   * Note - for any given connection, there can only ever be ONE remote procedure in the remote procedure queue
219
220- Miscellaneous minors
221   * pause/resume concepts - there are two (see spec for details)
222   * procedure execution can be paused by the encryption procedure
223   * data TX can be paused by PHY, DLE and ENC procedure
224   * RX node retention - ensures no waiting for allocation of RX node when needed for notification
225
226
227Miscellaneous unit test concepts
228================================
229
230- Individual ZTEST unit test for each procedure
231   * zephyr/tests/bluetooth/controller/ctrl_<proc>
232
233- Rx node handling is mocked
234   * Different configs are handled by separate conf files (see ctrl_conn_update for example)
235   * ZTEST(periph_rem_no_param_req, test_conn_update_periph_rem_accept_no_param_req)
236
237- Emulated versions of rx_demux/prepare context used in unit tests - testing ONLY procedure PDU flow
238   * event_prepare()/event_done() helpers emulating LLL prepare/done flow
239   * lt_rx()/lt_tx() 'lower tester' emulation of rx/tx
240   * ut_rx_node() 'upper tester' emulation of notification flow handling
241   * Bunch of helpers to generate and parse PDUs, as well as miscellaneous mocked ull_stuff()
242
243
244
245
246Lower Link Layer
247****************
248
249LLL Execution
250=============
251
252.. image:: img/ctlr_exec_lll.png
253
254
255LLL Resume
256----------
257
258.. image:: img/ctlr_exec_lll_resume_top.png
259
260.. image:: img/ctlr_exec_lll_resume_bottom.png
261
262
263Bare metal utilities
264********************
265
266Memory FIFO and Memory Queue
267============================
268
269.. image:: img/ctlr_mfifo_memq.png
270
271Mayfly
272======
273
274.. image:: img/ctlr_mayfly.png
275
276
277* Mayfly are multi-instance scalable ISR execution contexts
278* What a Work is to a Thread, Mayfly is to an ISR
279* List of functions executing in ISRs
280* Execution priorities map to IRQ priorities
281* Facilitate cross execution context scheduling
282* Race-to-idle execution
283* Lock-less, bare metal
284
285Legacy Controller
286*****************
287
288.. image:: img/ctlr_legacy.png
289
290Bluetooth Low Energy Controller - Vendor Specific Details
291*********************************************************
292
293Hardware Requirements
294=====================
295
296Nordic Semiconductor
297--------------------
298
299The Nordic Semiconductor Bluetooth Low Energy Controller implementation
300requires the following hardware peripherals.
301
302.. list-table:: SoC Peripheral Use
303   :header-rows: 1
304   :widths: 15 15 15 10 50
305
306   * - Resource
307     - nRF Peripheral
308     - # instances
309     - Zephyr Driver Accessible
310     - Description
311   * - Clock
312     - NRF_CLOCK
313     - 1
314     - Yes
315     - * A Low Frequency Clock (LFCLOCK) or sleep clock, for low power
316         consumption between Bluetooth radio events
317       * A High Frequency Clock (HFCLOCK) or active clock, for high precision
318         packet timing and software based transceiver state switching with
319         inter-frame space (tIFS) timing inside Bluetooth radio events
320   * - RTC [a]_
321     - NRF_RTC0
322     - 1
323     - **No**
324     - * Uses 2 capture/compare registers
325   * - Timer
326     - NRF_TIMER0 or NRF_TIMER4 [1]_, and NRF_TIMER1 [0]_
327     - 2 or 1 [1]_
328     - **No**
329     - * 2 instances, one each for packet timing and tIFS software switching,
330         respectively
331       * 7 capture/compare registers (3 mandatory, 1 optional for ISR profiling,
332         4 for single timer tIFS switching) on first instance
333       * 4 capture/compare registers for second instance, if single tIFS timer
334         is not used.
335   * - PPI [b]_
336     - NRF_PPI
337     - 21 channels (20 [2]_), and 2 channel groups [3]_
338     - Yes [4]_
339     - * Used for radio mode switching to achieve tIFS timings, for PA/LNA
340         control
341   * - DPPI [c]_
342     - NRF_DPPI
343     -  20 channels, and 2 channel groups [3]_
344     - Yes [4]_
345     - * Used for radio mode switching to achieve tIFS timings, for PA/LNA
346         control
347   * - SWI [d]_
348     - NRF_SWI4 and NRF_SWI5, or NRF_SWI2 and NRF_SWI3 [5]_
349     - 2
350     - **No**
351     - * 2 instances, for Lower Link Layer and Upper Link Layer Low priority
352         execution context
353   * - Radio
354     - NRF_RADIO
355     - 1
356     - **No**
357     - * 2.4 GHz radio transceiver with multiple radio standards such as 1 Mbps,
358         2 Mbps and Coded PHY S2/S8 Long Range Bluetooth Low Energy technology
359   * - RNG [e]_
360     - NRF_RNG
361     - 1
362     - Yes
363     -
364   * - ECB [f]_
365     - NRF_ECB
366     - 1
367     - **No**
368     -
369   * - CBC-CCM [g]_
370     - NRF_CCM
371     - 1
372     - **No**
373     -
374   * - AAR [h]_
375     - NRF_AAR
376     - 1
377     - **No**
378     -
379   * - GPIO [i]_
380     - NRF_GPIO
381     - 2 GPIO pins for PA and LNA, 1 each
382     - Yes
383     - * Additionally, 10 Debug GPIO pins (optional)
384   * - GPIOTE [j]_
385     - NRF_GPIOTE
386     - 1
387     - Yes
388     - * Used for PA/LNA
389   * - TEMP [k]_
390     - NRF_TEMP
391     - 1
392     - Yes
393     - * For RC sourced LFCLOCK calibration
394   * - UART [l]_
395     - NRF_UART0
396     - 1
397     - Yes
398     - * For HCI interface in Controller only builds
399   * - IPC [m]_
400     - NRF_IPC [5]_
401     - 1
402     - Yes
403     - * For HCI interface in Controller only builds
404
405
406.. [a] Real Time Counter (RTC)
407.. [b] Programmable Peripheral Interconnect (PPI)
408.. [c] Distributed Programmable Peripheral Interconnect (DPPI)
409.. [d] Software Interrupt (SWI)
410.. [e] Random Number Generator (RNG)
411.. [f] AES Electronic Codebook Mode Encryption (ECB)
412.. [g] Cipher Block Chaining (CBC) - Message Authentication Code with Counter
413       Mode encryption (CCM)
414.. [h] Accelerated Address Resolver (AAR)
415.. [i] General Purpose Input Output (GPIO)
416.. [j] GPIO tasks and events (GPIOTE)
417.. [k] Temperature sensor (TEMP)
418.. [l] Universal Asynchronous Receiver Transmitter (UART)
419.. [m] Interprocess Communication peripheral (IPC)
420
421
422.. [0] :kconfig:option:`CONFIG_BT_CTLR_TIFS_HW` ``=n``
423.. [1] :kconfig:option:`CONFIG_BT_CTLR_SW_SWITCH_SINGLE_TIMER` ``=y``
424.. [2] When not using pre-defined PPI channels
425.. [3] For software-based tIFS switching
426.. [4] Drivers that use nRFx interfaces
427.. [5] For nRF53x Series
428