doc/connectivity/bluetooth/bluetooth-ctlr-arch.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _bluetooth-ctlr-arch:

 LE Controller
 #############

 Overview
 ********

 .. image:: img/ctlr_overview.png

 #. HCI

    * Host Controller Interface, Bluetooth standard
    * Provides Zephyr Bluetooth HCI Driver

 #. HAL

    * Hardware Abstraction Layer
    * Vendor Specific, and Zephyr Driver usage

 #. Ticker

    * Soft real time radio/resource scheduling

 #. LL_SW

    * Software-based Link Layer implementation
    * States and roles, control procedures, packet controller

 #. Util

    * Bare metal memory pool management
    * Queues of variable count, lockless usage
    * FIFO of fixed count, lockless usage
    * Mayfly concept based deferred ISR executions


 Architecture
 ************

 Execution Overview
 ==================

 .. image:: img/ctlr_exec_overview.png


 Architecture Overview
 =====================

 .. image:: img/ctlr_arch_overview.png


 Scheduling
 **********

 .. image:: img/ctlr_sched.png


 Ticker
 ======

 .. image:: img/ctlr_sched_ticker.png


 Upper Link Layer and Lower Link Layer
 =====================================

 .. image:: img/ctlr_sched_ull_lll.png


 Scheduling Variants
 ===================

 .. image:: img/ctlr_sched_variant.png


 ULL and LLL Timing
 ==================

 .. image:: img/ctlr_sched_ull_lll_timing.png


 Event Handling
 **************

 .. image:: img/ctlr_sched_event_handling.png


 Scheduling Closely Spaced Events
 ================================

 .. image:: img/ctlr_sched_msc_close_events.png


 Aborting Active Event
 =====================

 .. image:: img/ctlr_sched_msc_event_abort.png


 Cancelling Pending Event
 ========================

 .. image:: img/ctlr_sched_msc_event_cancel.png


 Pre-emption of Active Event
 ===========================

 .. image:: img/ctlr_sched_msc_event_preempt.png


 Data Flow
 *********

 Transmit Data Flow
 ==================

 .. image:: img/ctlr_dataflow_tx.png


 Receive Data Flow
 =================

 .. image:: img/ctlr_dataflow_rx.png


 Execution Priorities
 ********************

 .. image:: img/ctlr_exec_prio.png

 - Event handle (0, 1) < Event preparation (2, 3) < Event/Rx done (4) < Tx
   request (5) < Role management (6) < Host (7).

 - LLL is vendor ISR, ULL is Mayfly ISR concept, Host is kernel thread.

 Link Layer Control Procedures
 *****************************

 Following is a brief fly in on the main concepts in the implementation of
 control procedures handling in ULL.

 Three main execution contexts
 =============================

 - HCI/LLCP API
    * Miscellaneous procedure initiation API
    * From ull_llcp.c::ull_cp_<proc>() for initiating local procedures
    * Interface with running procedures, local and remote

 - lll_prepare context to drive ull_cp_run()
    * LLCP main state machine entry/tick'er
    * From ull_peripheral.c/ull_central.c::ticker_cb via ull_conn_llcp()

 - rx_demux context to drive ull_cp_tx_ack() and ull_cp_rx()
    * LLCP tx ack handling and PDU reception
    * From ull_conn.c::ull_conn_rx()
    * Handles passing PDUs into running procedures as well as possibly initiating remote procedures

 Data structures and PDU helpers
 ===============================

 - struct llcp_struct
    * Main LLCP data store
    * Defined in ull_conn_types.h and declared as part of struct ll_conn
    * Holds local and remote procedure request queues as well as conn specific LLCP data
    * Basic conn-level abstraction

 - struct proc_ctx
    * General procedure context data, contains miscellaneous procedure data and state as well as sys_snode_t for queueing
    * Defined in ull_llcp_internal.h, declared/instantiated through ull_llcp.c::create_procedure()
    * Also holds node references used in tx_ack as well as rx_node retention mechanisms

 - struct llcp_mem_pool
    * Mem pool used to implement procedure contexts resource - instantiated in both a local and a remote version
    * Used through ull_llcp.c::create_procedure()

 - Miscellaneous pdu gymnastics
    * Encoding and decoding of control pdus done by ull_llcp_pdu.c::llcp_pdu_encode/decode_<PDU>()
    * Miscellaneous pdu validation handled by ull_llcp.c::pdu_validate_<PDU>() via ull_llcp.c::pdu_is_valid()

 LLCP local and remote request/procedure state machines
 ======================================================

 - ull_llcp_local.c
    * State machine handling local initiated procedures
    * Naming concept: lr _<...> => local request machine
    * Local procedure queue handling
    * Local run/rx/tx_ack switch

 - ull_llcp_remote.c
    * Remote versions of the above
    * Naming concept: rr_<...> => remote request machine
    * Also handling of remote procedure initiation by llcp_rx_new()
    * Miscellaneous procedure collision handling (in rr_st_idle())

 - ull_llcp_common/conn_upd/phy/enc/cc/chmu.c
    * Individual procedure implementations (ull_llcp_common.c collects the simpler ones)
    * Naming concept: lp_<...> => local initiated procedure, rp_<...> => remote initiated procedure
    * Handling of procedure flow from init (possibly through instant) to completion and host notification if applicable

 Miscellaneous concepts
 ======================

 - Procedure collision handling
    * See BT spec for explanation
    * Basically some procedures can exist in parallel but some can't - for instance only one instant based at a time
    * Spec states rules for how to handle/resolve collisions when they happen

 - Termination handling
    * Specific rules apply re. how termination is handled.
    * Since we have resource handling re. procedure contexts and terminate must always be available this is handled as a special case
    * Note also - there are miscellaneous cases where connection termination is triggered on invalid peer behavior

 - New remote procedure handling
    * Table new_proc_lut[] maps LLCP PDUs to procedures/roles used in llcp_rr_new()
    * Note - for any given connection, there can only ever be ONE remote procedure in the remote procedure queue

 - Miscellaneous minors
    * pause/resume concepts - there are two (see spec for details)
    * procedure execution can be paused by the encryption procedure
    * data TX can be paused by PHY, DLE and ENC procedure
    * RX node retention - ensures no waiting for allocation of RX node when needed for notification


 Miscellaneous unit test concepts
 ================================

 - Individual ZTEST unit test for each procedure
    * zephyr/tests/bluetooth/controller/ctrl_<proc>

 - Rx node handling is mocked
    * Different configs are handled by separate conf files (see ctrl_conn_update for example)
    * ZTEST(periph_rem_no_param_req, test_conn_update_periph_rem_accept_no_param_req)

 - Emulated versions of rx_demux/prepare context used in unit tests - testing ONLY procedure PDU flow
    * event_prepare()/event_done() helpers emulating LLL prepare/done flow
    * lt_rx()/lt_tx() 'lower tester' emulation of rx/tx
    * ut_rx_node() 'upper tester' emulation of notification flow handling
    * Bunch of helpers to generate and parse PDUs, as well as miscellaneous mocked ull_stuff()


 Lower Link Layer
 ****************

 LLL Execution
 =============

 .. image:: img/ctlr_exec_lll.png


 LLL Resume
 ----------

 .. image:: img/ctlr_exec_lll_resume_top.png

 .. image:: img/ctlr_exec_lll_resume_bottom.png


 Bare metal utilities
 ********************

 Memory FIFO and Memory Queue
 ============================

 .. image:: img/ctlr_mfifo_memq.png

 Mayfly
 ======

 .. image:: img/ctlr_mayfly.png


 * Mayfly are multi-instance scalable ISR execution contexts
 * What a Work is to a Thread, Mayfly is to an ISR
 * List of functions executing in ISRs
 * Execution priorities map to IRQ priorities
 * Facilitate cross execution context scheduling
 * Race-to-idle execution
 * Lock-less, bare metal

 Legacy Controller
 *****************

 .. image:: img/ctlr_legacy.png

 Bluetooth Low Energy Controller - Vendor Specific Details
 *********************************************************

 Hardware Requirements
 =====================

 Nordic Semiconductor
 --------------------

 The Nordic Semiconductor Bluetooth Low Energy Controller implementation
 requires the following hardware peripherals.

 .. list-table:: SoC Peripheral Use
    :header-rows: 1
    :widths: 15 15 15 10 50

    * - Resource
      - nRF Peripheral
      - # instances
      - Zephyr Driver Accessible
      - Description
    * - Clock
      - NRF_CLOCK
      - 1
      - Yes
      - * A Low Frequency Clock (LFCLOCK) or sleep clock, for low power
          consumption between Bluetooth radio events
        * A High Frequency Clock (HFCLOCK) or active clock, for high precision
          packet timing and software based transceiver state switching with
          inter-frame space (tIFS) timing inside Bluetooth radio events
    * - RTC [a]_
      - NRF_RTC0
      - 1
      - **No**
      - * Uses 2 capture/compare registers
    * - Timer
      - NRF_TIMER0 or NRF_TIMER4 [1]_, and NRF_TIMER1 [0]_
      - 2 or 1 [1]_
      - **No**
      - * 2 instances, one each for packet timing and tIFS software switching,
          respectively
        * 7 capture/compare registers (3 mandatory, 1 optional for ISR profiling,
          4 for single timer tIFS switching) on first instance
        * 4 capture/compare registers for second instance, if single tIFS timer
          is not used.
    * - PPI [b]_
      - NRF_PPI
      - 21 channels (20 [2]_), and 2 channel groups [3]_
      - Yes [4]_
      - * Used for radio mode switching to achieve tIFS timings, for PA/LNA
          control
    * - DPPI [c]_
      - NRF_DPPI
      -  20 channels, and 2 channel groups [3]_
      - Yes [4]_
      - * Used for radio mode switching to achieve tIFS timings, for PA/LNA
          control
    * - SWI [d]_
      - NRF_SWI4 and NRF_SWI5, or NRF_SWI2 and NRF_SWI3 [5]_
      - 2
      - **No**
      - * 2 instances, for Lower Link Layer and Upper Link Layer Low priority
          execution context
    * - Radio
      - NRF_RADIO
      - 1
      - **No**
      - * 2.4 GHz radio transceiver with multiple radio standards such as 1 Mbps,
          2 Mbps and Coded PHY S2/S8 Long Range Bluetooth Low Energy technology
    * - RNG [e]_
      - NRF_RNG
      - 1
      - Yes
      -
    * - ECB [f]_
      - NRF_ECB
      - 1
      - **No**
      -
    * - CBC-CCM [g]_
      - NRF_CCM
      - 1
      - **No**
      -
    * - AAR [h]_
      - NRF_AAR
      - 1
      - **No**
      -
    * - GPIO [i]_
      - NRF_GPIO
      - 2 GPIO pins for PA and LNA, 1 each
      - Yes
      - * Additionally, 10 Debug GPIO pins (optional)
    * - GPIOTE [j]_
      - NRF_GPIOTE
      - 1
      - Yes
      - * Used for PA/LNA
    * - TEMP [k]_
      - NRF_TEMP
      - 1
      - Yes
      - * For RC sourced LFCLOCK calibration
    * - UART [l]_
      - NRF_UART0
      - 1
      - Yes
      - * For HCI interface in Controller only builds
    * - IPC [m]_
      - NRF_IPC [5]_
      - 1
      - Yes
      - * For HCI interface in Controller only builds


 .. [a] Real Time Counter (RTC)
 .. [b] Programmable Peripheral Interconnect (PPI)
 .. [c] Distributed Programmable Peripheral Interconnect (DPPI)
 .. [d] Software Interrupt (SWI)
 .. [e] Random Number Generator (RNG)
 .. [f] AES Electronic Codebook Mode Encryption (ECB)
 .. [g] Cipher Block Chaining (CBC) - Message Authentication Code with Counter
        Mode encryption (CCM)
 .. [h] Accelerated Address Resolver (AAR)
 .. [i] General Purpose Input Output (GPIO)
 .. [j] GPIO tasks and events (GPIOTE)
 .. [k] Temperature sensor (TEMP)
 .. [l] Universal Asynchronous Receiver Transmitter (UART)
 .. [m] Interprocess Communication peripheral (IPC)


 .. [0] :kconfig:option:`CONFIG_BT_CTLR_TIFS_HW` ``=n``
 .. [1] :kconfig:option:`CONFIG_BT_CTLR_SW_SWITCH_SINGLE_TIMER` ``=y``
 .. [2] When not using pre-defined PPI channels
 .. [3] For software-based tIFS switching
 .. [4] Drivers that use nRFx interfaces
 .. [5] For nRF53x Series
	.. _bluetooth-ctlr-arch:

	LE Controller
	#############

	Overview
	********

	.. image:: img/ctlr_overview.png

	#. HCI

	* Host Controller Interface, Bluetooth standard
	* Provides Zephyr Bluetooth HCI Driver

	#. HAL

	* Hardware Abstraction Layer
	* Vendor Specific, and Zephyr Driver usage

	#. Ticker

	* Soft real time radio/resource scheduling

	#. LL_SW

	* Software-based Link Layer implementation
	* States and roles, control procedures, packet controller

	#. Util

	* Bare metal memory pool management
	* Queues of variable count, lockless usage
	* FIFO of fixed count, lockless usage
	* Mayfly concept based deferred ISR executions


	Architecture
	************

	Execution Overview
	==================

	.. image:: img/ctlr_exec_overview.png


	Architecture Overview
	=====================

	.. image:: img/ctlr_arch_overview.png


	Scheduling
	**********

	.. image:: img/ctlr_sched.png


	Ticker
	======

	.. image:: img/ctlr_sched_ticker.png


	Upper Link Layer and Lower Link Layer
	=====================================

	.. image:: img/ctlr_sched_ull_lll.png


	Scheduling Variants
	===================

	.. image:: img/ctlr_sched_variant.png


	ULL and LLL Timing
	==================

	.. image:: img/ctlr_sched_ull_lll_timing.png


	Event Handling
	**************

	.. image:: img/ctlr_sched_event_handling.png


	Scheduling Closely Spaced Events
	================================

	.. image:: img/ctlr_sched_msc_close_events.png


	Aborting Active Event
	=====================

	.. image:: img/ctlr_sched_msc_event_abort.png


	Cancelling Pending Event
	========================

	.. image:: img/ctlr_sched_msc_event_cancel.png


	Pre-emption of Active Event
	===========================

	.. image:: img/ctlr_sched_msc_event_preempt.png


	Data Flow
	*********

	Transmit Data Flow
	==================

	.. image:: img/ctlr_dataflow_tx.png


	Receive Data Flow
	=================

	.. image:: img/ctlr_dataflow_rx.png


	Execution Priorities
	********************

	.. image:: img/ctlr_exec_prio.png

	- Event handle (0, 1) < Event preparation (2, 3) < Event/Rx done (4) < Tx
	request (5) < Role management (6) < Host (7).

	- LLL is vendor ISR, ULL is Mayfly ISR concept, Host is kernel thread.

	Link Layer Control Procedures
	*****************************

	Following is a brief fly in on the main concepts in the implementation of
	control procedures handling in ULL.

	Three main execution contexts
	=============================

	- HCI/LLCP API
	* Miscellaneous procedure initiation API
	* From ull_llcp.c::ull_cp_<proc>() for initiating local procedures
	* Interface with running procedures, local and remote

	- lll_prepare context to drive ull_cp_run()
	* LLCP main state machine entry/tick'er
	* From ull_peripheral.c/ull_central.c::ticker_cb via ull_conn_llcp()

	- rx_demux context to drive ull_cp_tx_ack() and ull_cp_rx()
	* LLCP tx ack handling and PDU reception
	* From ull_conn.c::ull_conn_rx()
	* Handles passing PDUs into running procedures as well as possibly initiating remote procedures

	Data structures and PDU helpers
	===============================

	- struct llcp_struct
	* Main LLCP data store
	* Defined in ull_conn_types.h and declared as part of struct ll_conn
	* Holds local and remote procedure request queues as well as conn specific LLCP data
	* Basic conn-level abstraction

	- struct proc_ctx
	* General procedure context data, contains miscellaneous procedure data and state as well as sys_snode_t for queueing
	* Defined in ull_llcp_internal.h, declared/instantiated through ull_llcp.c::create_procedure()
	* Also holds node references used in tx_ack as well as rx_node retention mechanisms

	- struct llcp_mem_pool
	* Mem pool used to implement procedure contexts resource - instantiated in both a local and a remote version
	* Used through ull_llcp.c::create_procedure()

	- Miscellaneous pdu gymnastics
	* Encoding and decoding of control pdus done by ull_llcp_pdu.c::llcp_pdu_encode/decode_<PDU>()
	* Miscellaneous pdu validation handled by ull_llcp.c::pdu_validate_<PDU>() via ull_llcp.c::pdu_is_valid()

	LLCP local and remote request/procedure state machines
	======================================================

	- ull_llcp_local.c
	* State machine handling local initiated procedures
	* Naming concept: lr _<...> => local request machine
	* Local procedure queue handling
	* Local run/rx/tx_ack switch

	- ull_llcp_remote.c
	* Remote versions of the above
	* Naming concept: rr_<...> => remote request machine
	* Also handling of remote procedure initiation by llcp_rx_new()
	* Miscellaneous procedure collision handling (in rr_st_idle())

	- ull_llcp_common/conn_upd/phy/enc/cc/chmu.c
	* Individual procedure implementations (ull_llcp_common.c collects the simpler ones)
	* Naming concept: lp_<...> => local initiated procedure, rp_<...> => remote initiated procedure
	* Handling of procedure flow from init (possibly through instant) to completion and host notification if applicable

	Miscellaneous concepts
	======================

	- Procedure collision handling
	* See BT spec for explanation
	* Basically some procedures can exist in parallel but some can't - for instance only one instant based at a time
	* Spec states rules for how to handle/resolve collisions when they happen

	- Termination handling
	* Specific rules apply re. how termination is handled.
	* Since we have resource handling re. procedure contexts and terminate must always be available this is handled as a special case
	* Note also - there are miscellaneous cases where connection termination is triggered on invalid peer behavior

	- New remote procedure handling
	* Table new_proc_lut[] maps LLCP PDUs to procedures/roles used in llcp_rr_new()
	* Note - for any given connection, there can only ever be ONE remote procedure in the remote procedure queue

	- Miscellaneous minors
	* pause/resume concepts - there are two (see spec for details)
	* procedure execution can be paused by the encryption procedure
	* data TX can be paused by PHY, DLE and ENC procedure
	* RX node retention - ensures no waiting for allocation of RX node when needed for notification


	Miscellaneous unit test concepts
	================================

	- Individual ZTEST unit test for each procedure
	* zephyr/tests/bluetooth/controller/ctrl_<proc>

	- Rx node handling is mocked
	* Different configs are handled by separate conf files (see ctrl_conn_update for example)
	* ZTEST(periph_rem_no_param_req, test_conn_update_periph_rem_accept_no_param_req)

	- Emulated versions of rx_demux/prepare context used in unit tests - testing ONLY procedure PDU flow
	* event_prepare()/event_done() helpers emulating LLL prepare/done flow
	* lt_rx()/lt_tx() 'lower tester' emulation of rx/tx
	* ut_rx_node() 'upper tester' emulation of notification flow handling
	* Bunch of helpers to generate and parse PDUs, as well as miscellaneous mocked ull_stuff()




	Lower Link Layer
	****************

	LLL Execution
	=============

	.. image:: img/ctlr_exec_lll.png


	LLL Resume
	----------

	.. image:: img/ctlr_exec_lll_resume_top.png

	.. image:: img/ctlr_exec_lll_resume_bottom.png


	Bare metal utilities
	********************

	Memory FIFO and Memory Queue
	============================

	.. image:: img/ctlr_mfifo_memq.png

	Mayfly
	======

	.. image:: img/ctlr_mayfly.png


	* Mayfly are multi-instance scalable ISR execution contexts
	* What a Work is to a Thread, Mayfly is to an ISR
	* List of functions executing in ISRs
	* Execution priorities map to IRQ priorities
	* Facilitate cross execution context scheduling
	* Race-to-idle execution
	* Lock-less, bare metal

	Legacy Controller
	*****************

	.. image:: img/ctlr_legacy.png

	Bluetooth Low Energy Controller - Vendor Specific Details
	*********************************************************

	Hardware Requirements
	=====================

	Nordic Semiconductor
	--------------------

	The Nordic Semiconductor Bluetooth Low Energy Controller implementation
	requires the following hardware peripherals.

	.. list-table:: SoC Peripheral Use
	:header-rows: 1
	:widths: 15 15 15 10 50

	* - Resource
	- nRF Peripheral
	- # instances
	- Zephyr Driver Accessible
	- Description
	* - Clock
	- NRF_CLOCK
	- 1
	- Yes
	- * A Low Frequency Clock (LFCLOCK) or sleep clock, for low power
	consumption between Bluetooth radio events
	* A High Frequency Clock (HFCLOCK) or active clock, for high precision
	packet timing and software based transceiver state switching with
	inter-frame space (tIFS) timing inside Bluetooth radio events
	* - RTC [a]_
	- NRF_RTC0
	- 1
	- No
	- * Uses 2 capture/compare registers
	* - Timer
	- NRF_TIMER0 or NRF_TIMER4 [1]_, and NRF_TIMER1 [0]_
	- 2 or 1 [1]_
	- No
	- * 2 instances, one each for packet timing and tIFS software switching,
	respectively
	* 7 capture/compare registers (3 mandatory, 1 optional for ISR profiling,
	4 for single timer tIFS switching) on first instance
	* 4 capture/compare registers for second instance, if single tIFS timer
	is not used.
	* - PPI [b]_
	- NRF_PPI
	- 21 channels (20 [2]_), and 2 channel groups [3]_
	- Yes [4]_
	- * Used for radio mode switching to achieve tIFS timings, for PA/LNA
	control
	* - DPPI [c]_
	- NRF_DPPI
	- 20 channels, and 2 channel groups [3]_
	- Yes [4]_
	- * Used for radio mode switching to achieve tIFS timings, for PA/LNA
	control
	* - SWI [d]_
	- NRF_SWI4 and NRF_SWI5, or NRF_SWI2 and NRF_SWI3 [5]_
	- 2
	- No
	- * 2 instances, for Lower Link Layer and Upper Link Layer Low priority
	execution context
	* - Radio
	- NRF_RADIO
	- 1
	- No
	- * 2.4 GHz radio transceiver with multiple radio standards such as 1 Mbps,
	2 Mbps and Coded PHY S2/S8 Long Range Bluetooth Low Energy technology
	* - RNG [e]_
	- NRF_RNG
	- 1
	- Yes
	-
	* - ECB [f]_
	- NRF_ECB
	- 1
	- No
	-
	* - CBC-CCM [g]_
	- NRF_CCM
	- 1
	- No
	-
	* - AAR [h]_
	- NRF_AAR
	- 1
	- No
	-
	* - GPIO [i]_
	- NRF_GPIO
	- 2 GPIO pins for PA and LNA, 1 each
	- Yes
	- * Additionally, 10 Debug GPIO pins (optional)
	* - GPIOTE [j]_
	- NRF_GPIOTE
	- 1
	- Yes
	- * Used for PA/LNA
	* - TEMP [k]_
	- NRF_TEMP
	- 1
	- Yes
	- * For RC sourced LFCLOCK calibration
	* - UART [l]_
	- NRF_UART0
	- 1
	- Yes
	- * For HCI interface in Controller only builds
	* - IPC [m]_
	- NRF_IPC [5]_
	- 1
	- Yes
	- * For HCI interface in Controller only builds


	.. [a] Real Time Counter (RTC)
	.. [b] Programmable Peripheral Interconnect (PPI)
	.. [c] Distributed Programmable Peripheral Interconnect (DPPI)
	.. [d] Software Interrupt (SWI)
	.. [e] Random Number Generator (RNG)
	.. [f] AES Electronic Codebook Mode Encryption (ECB)
	.. [g] Cipher Block Chaining (CBC) - Message Authentication Code with Counter
	Mode encryption (CCM)
	.. [h] Accelerated Address Resolver (AAR)
	.. [i] General Purpose Input Output (GPIO)
	.. [j] GPIO tasks and events (GPIOTE)
	.. [k] Temperature sensor (TEMP)
	.. [l] Universal Asynchronous Receiver Transmitter (UART)
	.. [m] Interprocess Communication peripheral (IPC)


	.. [0] :kconfig:option:`CONFIG_BT_CTLR_TIFS_HW` ``=n``
	.. [1] :kconfig:option:`CONFIG_BT_CTLR_SW_SWITCH_SINGLE_TIMER` ``=y``
	.. [2] When not using pre-defined PPI channels
	.. [3] For software-based tIFS switching
	.. [4] Drivers that use nRFx interfaces
	.. [5] For nRF53x Series