Bluetooth RTOS adaptation#

Bluetooth RTOS adaptation.

The Bluetooth RTOS adaptation component implements the relevant interfaces for running the Bluetooth stack in an RTOS. The component creates the required RTOS synchronization primitives and tasks for the Bluetooth stack and handles the inter-process communication (IPC) required when the application calls a BGAPI command.

If the Bluetooth Event System IPC component (bluetooth_event_system_ipc) is included in the application, Bluetooth events are delivered using the IPC mechanism provided by the event_system component. See Bluetooth Event System IPC for the description of that mechanism. In this configuration no event task is created by the RTOS adaptation.

If the Bluetooth Event System IPC component (bluetooth_event_system_ipc) is not included in the application, the RTOS adaptation component creates an event task that delivers the events to the application as direct callbacks to sl_bt_process_event() and sl_bt_on_event() functions.

To guarantee thread safety and avoid the risk of deadlocks, the Bluetooth RTOS adaptation implementation makes the following promises with regard to the locking mechanism provided in the API:

  1. The stack will never directly call sl_bt_process_event() or sl_bt_on_event() from within the same callstack that is calling a command function. The callbacks always come from a processing loop in an event task created for this purpose.

  2. The stack uses sli_bgapi_lock() and sli_bgapi_unlock() to synchronize the handling of individual BGAPI commands, and the application must never directly call these. Individual BGAPI commands are safe to be called from multiple threads without additional locking. See sl_bt_bluetooth_pend() for description of when an application needs to use additional locking to guarantee atomicity across multiple commands.

  3. The stack will never internally obtain the sl_bt_bluetooth_pend() lock. It is safe for the application to obtain the lock also from within the sl_bt_on_event() callback.

Variables#

sli_bgapi_component_init_func_t

BGAPI component initialization function for Bluetooth RTOS adaptation.

sli_bgapi_component_deinit_func_t

BGAPI component de-init function for Bluetooth RTOS adaptation.

Functions#

sl_status_t

Make permanent memory allocations for Bluetooth RTOS adaptation.

sl_status_t

Start the Bluetooth RTOS adaptation.

void

Prepare to stop the Bluetooth RTOS adaptation.

void

Stop the Bluetooth RTOS adaptation.

sl_status_t

Obtain the Bluetooth host stack command lock.

sl_status_t

Release the Bluetooth host stack command lock.

Variable Documentation#

sli_bt_rtos_adaptation_init#

sli_bgapi_component_init_func_t sli_bt_rtos_adaptation_init

BGAPI component initialization function for Bluetooth RTOS adaptation.

Do not call this function directly from the application. The Bluetooth host stack components call this function automatically in the right stage of initialization.


sli_bt_rtos_adaptation_deinit#

sli_bgapi_component_deinit_func_t sli_bt_rtos_adaptation_deinit

BGAPI component de-init function for Bluetooth RTOS adaptation.

Do not call this function directly from the application. The Bluetooth host stack components call this function automatically in the right stage of de-initialization.


Function Documentation#

sli_bt_rtos_adaptation_permanent_allocation#

sl_status_t sli_bt_rtos_adaptation_permanent_allocation (void )

Make permanent memory allocations for Bluetooth RTOS adaptation.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Do not call this function directly from the application. The Bluetooth host stack components call this function automatically in the right stage of initialization.

Returns

  • SL_STATUS_OK if succeeds, otherwise error


sli_bt_rtos_adaptation_start#

sl_status_t sli_bt_rtos_adaptation_start (void )

Start the Bluetooth RTOS adaptation.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Do not call this function directly from the application. The Bluetooth host stack components call this function automatically when it's time to start the RTOS adaptation.

Returns

  • SL_STATUS_OK if succeeds, otherwise error


sli_bt_rtos_adaptation_prepare_to_stop#

void sli_bt_rtos_adaptation_prepare_to_stop (void )

Prepare to stop the Bluetooth RTOS adaptation.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Do not call this function directly from the application. The Bluetooth host stack components call this function automatically when it's time to prepare for stopping the RTOS adaptation.


sli_bt_rtos_adaptation_stop#

void sli_bt_rtos_adaptation_stop (void )

Stop the Bluetooth RTOS adaptation.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Do not call this function directly from the application. The Bluetooth host stack components call this function automatically when it's time to stop the RTOS adaptation.


sl_bt_bluetooth_pend#

sl_status_t sl_bt_bluetooth_pend ()

Obtain the Bluetooth host stack command lock.

Starting from Gecko SDK v3.1.2, all BGAPI command functions have automatic locking to make them thread-safe. Using sl_bt_bluetooth_pend() and sl_bt_bluetooth_post() is therefore no longer required for individual calls to the BGAPI.

The application only needs to use sl_bt_bluetooth_pend() and sl_bt_bluetooth_post() to protect sections of code where multiple commands need to be performed atomically in a thread-safe manner. This includes cases such as using sl_bt_system_data_buffer_write() to write data to the system buffer followed by a call to sl_bt_extended_advertiser_set_long_data() to set that data to an advertiser set. To synchronize access to the shared system buffer, the application would need to lock by calling sl_bt_bluetooth_pend() before sl_bt_system_data_buffer_write(), and release the lock by calling sl_bt_bluetooth_post() after sl_bt_extended_advertiser_set_long_data().

Returns

  • SL_STATUS_OK if mutex has been obtained


sl_bt_bluetooth_post#

sl_status_t sl_bt_bluetooth_post ()

Release the Bluetooth host stack command lock.

See sl_bt_bluetooth_pend() for description of how an application needs to use the locking to guarantee thread-safety.

Returns

  • SL_STATUS_OK the mutex has been released