mpsl: rev 6e9b27fa323913583374e6317602072e7ad8f00c

CHANGELOG.rst contains the list of changes.

Signed-off-by: Rubin Ingwer Gerritsen <[email protected]>

mpsl/CHANGELOG.rst

@@ -18,6 +18,13 @@ Added
 =====
 
 * Added support for the Simple GPIO Front-End Module implementation on the nRF53 Series.
+* Added support and separate documentation for Bluetooth External Radio Coexistence on the nRF52 Series (DRGN-11849).
+
+Changes
+=======
+
+* References to Bluetooth support were moved away from :file:`projects/mpsl/doc/public/doc/cx.rst`.
+  Its scope is now limited to IEEE 802.15.4 External Radio Coexistence.
 
 nRF Connect SDK v1.7.0
 **********************

mpsl/README.rst

@@ -22,9 +22,10 @@ This library provides the following key features:
   It supports only the nRF52 Series.
 * SoC Temperature.
   It provides an API for obtaining the temperature measured on the SoC.
-* Radio coexistence.
-  It allows the application to interface with several types of packet traffic arbiters (PTAs).
-
+* IEEE 802.15.4 External Radio Coexistence.
+  It provides an API to control coexistence with IEEE 802.15.4.
+* Bluetooth External Radio Coexistence.
+  It provides an API to control coexistence with bluetooth.
 
 .. toctree::
    :maxdepth: 2
@@ -37,5 +38,6 @@ This library provides the following key features:
    doc/tx_power_control
    doc/fem
    doc/cx
+   doc/bluetooth_coex
    CHANGELOG
    doc/api

mpsl/doc/api.rst

@@ -70,12 +70,18 @@ MPSL FEM Simple GPIO
    :project: nrfxlib
    :members:
 
-MPSL Coexistence
-****************
+IEEE 802.15.4 External Radio Coexistence
+****************************************
 .. doxygengroup:: mpsl_cx
    :project: nrfxlib
    :members:
 
+Bluetooth External Radio Coexistence
+************************************
+.. doxygengroup:: mpsl_coex
+   :project: nrfxlib
+   :members:
+
 MPSL Temp
 *********
 

mpsl/doc/bluetooth_coex.rst

@@ -0,0 +1,82 @@
+.. _bluetooth_coex:
+
+Bluetooth External Radio Coexistence
+####################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+IEEE 802.15.2-2003 provides recommendations to facilitate coexistence.
+This implementation is based on the Packet Traffic Arbitration (PTA) solution.
+Since IEEE 802.15.2-2003 is not a standard but a recommendation, implementations may vary.
+
+The Bluetooth® stack communicates with PTA using a 3-wire hardware interface, with Bluetooth acting as a slave.
+
+.. NOTE::
+   This implementation is only supported on nRF52 devices.
+
+Protocol
+********
+
+The 3-wire interface has two lines controlled by Bluetooth, and one controlled by PTA:
+
+.. table:: 3-wire protocol pins
+
+   ==============  ==========================================================
+   Pin             Description
+   ==============  ==========================================================
+   BLE_REQUEST     Bluetooth requests radio operation.
+   BLE_PRI_STATUS  Bluetooth indicates priority and type of activity (TX/RX).
+   BLE_GRANT       PTA grants/denies request.
+   ==============  ==========================================================
+
+The 3-wire protocol has three timing parameters:
+
+.. table:: 3-wire protocol timing
+
+   =========  =================  ====================================================================================================
+   Parameter  Value              Description
+   =========  =================  ====================================================================================================
+   T1         User configurable  Time from when BLE_REQUEST is asserted until the type of transaction is indicated.
+   T2         User configurable  Time from when BLE_REQUEST is asserted until the radio can assume that the request has been granted.
+   T3         10µs               Time from when BLE_GRANT is de-asserted until the radio must shut down.
+   =========  =================  ====================================================================================================
+
+T1 and T2 are configurable through type_delay_us and radio_delay_us.
+
+.. NOTE::
+   The sum of type_delay_us and radio_delay_us cannot be more than 40us due to radio ramp-up time.
+
+.. figure:: pic/mpsl_coex_3wire_timings_delays.png
+
+   3-wire protocol timings
+
+Whenever Bluetooth requires the use of the radio for any RF activity, it will assert BLE_REQUEST.
+The BLE_PRI_STATUS pin will first indicate the priority of the request.
+After T1, the BLE_PRI_STATUS pin will indicate the type of transaction (RX/TX).
+Then, after T2 has passed, the radio will start on-air activity.
+
+When PTA detects a request, it will sample priority and type, and will grant or deny the request before T2.
+PTA may revoke a granted session at any time.
+When the grant pin de-asserts, the radio will be disabled and the request line will be de-asserted within T3.
+The grant line will stay de-asserted until the request is released.
+
+Hardware resources
+******************
+
+.. table:: 3-wire protocol HW resources
+
+   =================  =====  ========================================================================================
+   Peripheral         Count  Description
+   =================  =====  ========================================================================================
+   HF Timer instance  1      Timer instance for adhering to the timing requirements, referred to as the *coex timer*.
+   GPIO pins          3      Pin selection for the 3-wire interface.
+   GPIOTE channels    3      Each GPIOTE channel corresponds to a GPIO pin.
+   PPI channels       4      Three channels for the three GPIOTEs, and one for handling radio events.
+   =================  =====  ========================================================================================
+
+Application Programming Interface
+*********************************
+
+Details of the API can be found in file :file:`nrfxlib/mpsl/include/mpsl_coex.h`.

mpsl/doc/cx.rst

@@ -1,14 +1,14 @@
 .. _mpsl_cx:
 
-Radio coexistence feature
-#########################
+IEEE 802.15.4 External Radio Coexistence
+########################################
 
 .. contents::
    :local:
    :depth: 2
 
 The radio coexistence feature allows the application to interface with several types of packet traffic arbiters (PTAs).
-This allows for better radio performance for devices using multiple interfering radios simultaneously, like a combination of |BLE| and Wi-Fi, or IEEE 802.15.4 and Wi-Fi.
+This allows for better radio performance for devices using multiple interfering radios simultaneously, like a combination of IEEE 802.15.4 and Wi-Fi.
 The PTA arbitrates the requested radio operations between all radios to avoid interference, increasing the performance of the radio protocols enabled simultaneously.
 The exact arbitration algorithm is dependent on the specific PTA used.
 
@@ -20,7 +20,6 @@ Limitations
 
 This experimental feature has several limitations:
 
-* It supports only the IEEE 802.15.4 protocol.
 * It supports only the nRF52 SoC family.
 * It does not use radio operation priorities, as the radio protocol requests each operation with a priority value of ``1``.
 * The PTA can deny only TX operations.
@@ -37,7 +36,7 @@ The radio coexistence implementation provided in nRF Connect SDK is the followin
 
 *Thread Radio Coexistence*
    This PTA interface is compatible with the 3-wire PTA interface defined in the *Thread Radio Coexistence recommendations* document available to Thread Group members.
-   It is also compatible with any IEEE 802.15.4 protocol (including Thread), with |BLE|, and with other radio protocols.
+   It is also compatible with any IEEE 802.15.4 protocol (including Thread).
 
 Configuration
 *************
@@ -51,7 +50,7 @@ To configure the Thread Radio Coexistence implementation you must define each pi
 General usage
 *************
 
-Each radio protocol using the radio coexistence feature (like IEEE 802.15.4 or |BLE|) can enable a transceiver only when the PTA allows a given radio operation.
+Each radio protocol using the radio coexistence feature (like IEEE 802.15.4) can enable a transceiver only when the PTA allows a given radio operation.
 When the PTA denies the ongoing radio operation, the radio protocol must abort this operation immediately.
 
 The radio protocol implementation must inform the radio coexistence module about which radio operations it wants to perform at that moment or shortly after, and what is the priority of each radio operation.

mpsl/doc/fem.rst

@@ -24,9 +24,6 @@ Two FEM implementations are provided:
    It is a simplified version, made to be compatible with other front-end modules.
    It implements a 2-pin interface.
 
-.. note::
-   The nRF53 Series supports only the nRF21540 GPIO Front-End Module.
-
 Both implementations use PA and LNA pins for controlling the FEM.
 Additionally, the nRF21540 GPIO implementation uses the PDN pin for powering down the FEM internal circuits, to reduce energy consumption.
 

mpsl/include/mpsl_coex.h

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2021 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+/**
+ * @file mpsl_coex.h
+ *
+ * @defgroup mpsl_coex MPSL interface for Bluetooth External Radio Coexistence
+ * @ingroup  mpsl
+ *
+ * This module provides the necessary interface for communication between the Bluetooth stack and a Packet Traffic Arbitrator.
+ * @{
+ */
+
+
+#ifndef MPSL_COEX_H__
+#define MPSL_COEX_H__
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include "nrf.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Ids of the supported coexistence interfaces.
+ */
+typedef enum
+{
+  MPSL_COEX_802152_3WIRE_GPIOTE_ID = 0, /**< 3-wire GPIO coexistence interface
+                                             based on IEEE 802.15.2-2003, subclause 6.
+                                             To support this interface,
+                                             @ref mpsl_coex_support_802152_3wire_gpiote_if()
+                                             must be called. */
+} mpsl_coex_if_id_t;
+
+/**
+ * @brief Configuration parameters for one wire of the 3-wire coexistence interface GPIOTE based interface.
+ */
+typedef struct
+{
+  uint8_t gpio_pin;        /**< The GPIO pin number. */
+  uint8_t active_high;     /**< Active pin level: 1 - high level, 0 - low level. */
+  uint8_t ppi_ch_id;       /**< PPI channel number. */
+  uint8_t gpiote_ch_id;    /**< GPIOTE channel number. */
+} mpsl_coex_gpiote_cfg_t;
+
+/**
+ * @brief GPIOs configuration for 3-wire coexistence arbitrator.
+ *
+ * 3-wire coexistence protocol applies the packet traffic arbitration recommendation
+ * based on IEEE Std 802.15.2-2003, subclause 6.
+ * 3-wire interface is exposed by following signals:
+ * REQUEST  -   Asserted whenever the user of MPSL wants to transmit or receive.
+ *              The signal must remain asserted till the end of TX/RX or the request is rejected by PTA controller.
+ * PRI_STATUS - Asserted to indicate the priority (high or low) of the intended
+ *              traffic immediately following REQUEST. After that, it is changed to indicate TX or RX.
+ * GRANT      - Asserted to indicate whether the request is granted or rejected.
+ *
+ * The request is made at @p type_delay_us + @p radio_delay_us before the radio activity starts. The Priority and Status line will
+ * first indicate the priority of the request, then after @p type_delay_us, it'll switch to showing the type of transaction (RX/TX).
+ * The radio will start transmitting or receiving @p radio_delay_us after this.
+ * Sum of @p type_delay_us + @p radio_delay_us cannot be more than 40us due to radio ramp-up time.
+ */
+typedef struct
+{
+  mpsl_coex_gpiote_cfg_t request_cfg;   /**< Request line configuration. */
+  mpsl_coex_gpiote_cfg_t priority_cfg;  /**< Priority and Status line configuration. */
+  mpsl_coex_gpiote_cfg_t grant_cfg;     /**< Grant line configuration. */
+
+  uint8_t  additional_ppi_ch_id;     /**< PPI channel used to set the priority level at the correct time.
+                                          Since Priority and Status are combined functional, it requires separate PPI channel to handle both.  */
+  uint8_t  is_rx_active_level : 1;   /**< Since Priority and Status are combined functional, the signal of the high priority is active level on the pin.
+                                          Which active level to use for the RX/TX signal is set by this variable. */
+  uint32_t type_delay_us;            /**< Delay in us from the request pin is raised until the Priority and Status line shows the type of transaction (RX/TX). */
+  uint32_t radio_delay_us;           /**< Delay in us from the Priority and Status line shows the type of transaction, to the radio starts its on-air activity. */
+  NRF_TIMER_Type *p_timer_instance;  /**< Pointer to a timer instance. Timer should not be shared with any other functionality. */
+} mpsl_coex_802152_3wire_gpiote_if_t;
+
+/**
+ * @brief Configuration of the coexistence interface.
+ *
+ * This option configures MPSL to support interface for requesting and granting access to the media
+ * and status notification in case of coexistence with another wireless standard.
+ */
+typedef struct
+{
+  mpsl_coex_if_id_t if_id;                                   /**<  Identification number of configured interface. */
+  union
+  {
+    mpsl_coex_802152_3wire_gpiote_if_t coex_3wire_gpiote;    /**<  Configuration parameters of 3-wire GPIO based coexistence. */
+  } interfaces;                                              /**<  Union with supported coexistence interfaces. */
+} mpsl_coex_if_t;
+
+/** @brief Type of callback invoked from coexistence interface upon completion
+ *         of enable or disable procedure.
+ * The callback must accept calls in both high- and low-priority threads.
+ */
+typedef void mpsl_coex_on_complete_callback_t(void);
+
+/** @brief Enable support for the 802.15.2 3-Wire coexistence interface.
+ *
+ * After this API is called, it is possible to configure MPSL with the coexistence interface
+ * @ref MPSL_COEX_802152_3WIRE_GPIOTE_ID.
+ */
+void mpsl_coex_support_802152_3wire_gpiote_if(void);
+
+/** @brief Configures and enables the coexistence interface.
+ *
+ *  @note The function configures the interface and maps
+ *        the other interface functions on exact coexistence implementation
+ *
+ *  @param[in] p_cfg
+ *      Pointer to coexistence interface configuration structure. Any
+ *      configuration with if_id set to MPSL_COEX_IDS_NUMBER is invalid.
+ *  @param[in] enable_complete_callback
+ *      Callback to be invoked when the coexistence interface completes the
+ *      enabling procedure. The callback must accept calls in both high- and
+ *      low-priority threads.
+ *
+ *  @retval  0              The configuration for the coexistence interface was
+ *                          successfully set and the enabling procedure operation
+ *                          was initiated. The supplied callback will be called
+ *                          when the enabling procedure is completed.
+ *  @retval -NRF_EINVAL     Invalid configuration or NULL callback provided.
+ *  @retval -NRF_EAGAIN     Enabling was not allowed at the time because the
+ *                          coexistence interface was already enabled or in an
+ *                          ongoing enable or disable procedure. The call aborted
+ *                          without any effect.
+ *  @retval -NRF_EOPNOTSUPP The provided interface is not supported.
+ *                          All interfaces must be explicitly enabled. See @ref mpsl_coex_if_id_t.
+ */
+int32_t mpsl_coex_enable(const mpsl_coex_if_t *p_cfg,
+                         mpsl_coex_on_complete_callback_t enable_complete_callback);
+
+/** @brief Disables the coexistence interface.
+ *
+ *  This releases all peripherals supplied to @ref mpsl_coex_enable for
+ *  application use. The released GPIOs will be reset to high-impedance mode
+ *  with no pull.
+ *
+ * @param[in] disable_complete_callback
+ *      Callback to be invoked when coexistence interface completes the
+ *      disabling procedure. The callback must accept calls in both high- and
+ *      low-priority threads.
+ *
+ * @retval 0            The disabling procedure for the coexistence interface
+ *                      was initiated. The supplied callback will be called when
+ *                      the disable procedure is completed.
+ * @retval -NRF_EAGAIN  Disabling was not allowed at the time because the
+ *                      coexistence interface was already disabled or in an
+ *                      ongoing enable or disable procedure. The call aborted
+ *                      without any effect.
+ * @retval -NRF_EINVAL  Invalid NULL callback provided.
+ */
+int32_t mpsl_coex_disable(mpsl_coex_on_complete_callback_t disable_complete_callback);
+
+#ifdef __cplusplus
+}
+#endif
+#endif // MPSL_COEX_H__
+
+/**
+  @}
+ */

mpsl/lib/cortex-m33+nodsp/soft-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: Multi-Protocol Service Layer (MPSL)
-git_revision: ad8e1af6841ba05a748abe0602af836c097a6539
-timestamp: '2021-10-05T08:22:04Z'
+git_revision: 6e9b27fa323913583374e6317602072e7ad8f00c
+timestamp: '2021-10-27T08:59:15Z'

mpsl/lib/cortex-m4/hard-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: Multi-Protocol Service Layer (MPSL)
-git_revision: ad8e1af6841ba05a748abe0602af836c097a6539
-timestamp: '2021-10-05T08:21:19Z'
+git_revision: 6e9b27fa323913583374e6317602072e7ad8f00c
+timestamp: '2021-10-27T09:00:55Z'

mpsl/lib/cortex-m4/soft-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: Multi-Protocol Service Layer (MPSL)
-git_revision: ad8e1af6841ba05a748abe0602af836c097a6539
-timestamp: '2021-10-05T08:21:19Z'
+git_revision: 6e9b27fa323913583374e6317602072e7ad8f00c
+timestamp: '2021-10-27T09:00:55Z'

mpsl/lib/cortex-m4/softfp-float/manifest.yaml

@@ -1,3 +1,3 @@
 description: Multi-Protocol Service Layer (MPSL)
-git_revision: ad8e1af6841ba05a748abe0602af836c097a6539
-timestamp: '2021-10-05T08:21:19Z'
+git_revision: 6e9b27fa323913583374e6317602072e7ad8f00c
+timestamp: '2021-10-27T09:00:55Z'