zephyr/doc/connectivity/bluetooth/bluetooth-ctlr-arch.rst

.. _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