# Baseband and Kernel Functions

To maximize the Bluetooth Low Energy connection stability, the stack must be provided sufficient processing time. We recommended that you:

1. Set the stack interrupts to the highest priority to prevent preemption or ISR processing delays.
2. Minimize the continuous time when interrupts are disabled
3. Have the application call BLE_Kernel_Process() at least once per Bluetooth connection interval.

Use of the event kernel and baseband are primarily supported by the functions described in the "Event Kernel Support Functions" table. These functions initialize and execute these components, while supporting transitions between different power modes. Function prototypes for these functions are included through ble.h, and these prototypes are defined in ble/rwip.h.

Table: Event Kernel Support Functions
Function | Description
--- | ---
BLE_Initialize | Initialize the event kernel and Bluetooth baseband for use within an application.
BLE_Baseband_Sleep | Place the Bluetooth baseband to sleep if the current Bluetooth Low Energy stack and the event kernel state indicate it is safe.
BLE_Kernel_Process | Execute any pending events that have been scheduled with the event kernel.
BLE_Baseband_Is_Awake | Check if the Bluetooth baseband is awake.

## BLE_Initialize

#### Prototype:

void BLE_Initialize(uint8_t * param_ptr)

#### Parameters:

Table: BLE_Initialize Parameters
Type | Parameters | Description
--- | --- | ---
uint8_t * | param_ptr | Reserved for future use (input/output parameter)

#### Return:

None

#### Description:

Initializes the Bluetooth Low Energy stack and the event kernel for use within an application.

#### Example

/* Initialize the kernel and Bluetooth stack */

uint8_t param;

BLE_Initialize(&param);

## BLE_Baseband_Sleep

#### Prototype:

uint8_t BLE_Baseband_Sleep(struct ble_sleep_api_param_tag *param_ptr)

#### Parameters:

Table: BLE_Baseband_Sleep Parameters
Type | Parameters | Description
--- | --- | ---
struct ble_sleep_api_param_tag * | param_ptr | param_ptr->app_sleep_request = Application sleep request; set to 1 if the Bluetooth baseband is intended to go to sleep when possible, 0 if the system is meant to stay awake param_ptr->max_sleep_duration = Requested maximum sleep duration in multiples of 312.5 μs (when this value is set to 0xFFFFFFFF, the maximum sleep duration is 36 hours and 16 minutes) param_ptr->min_sleep_duration = Requested minimum sleep duration in μs param_ptr->calculated_sleep_duration = Return value, in low power baseband clock cycles, providing the calculated sleep duration

NOTE: Minimum sleep duration that BLE_Baseband_Sleep() sets is the maximum value of min_sleep_duration and the BB_ENBPRESET_TWOSC bit field from the BB_ENBPRESET register.

#### Return:

Allowed sleep state.

- RWIP_DEEP_SLEEP if the baseband controller has been put to sleep, the baseband timer is set, and the core can switch to Sleep Mode (after saving the baseband and RF registers) or Standby Mode.

- RWIP_CPU_SLEEP if the core can be put to sleep, but the system is not meant to enter Sleep Mode or Standby Mode.

- RWIP_ACTIVE otherwise.

#### Description:

A user application calls this function to put the system into Sleep Mode. This function performs the following operations:

1. Checks the event kernel and Bluetooth Low Energy stack to decide whether it is the right time for the system to go into Sleep Mode
2. Programs and starts the low-power BB timer (if requested)
3. Puts the BB and RF hardware into Sleep Mode (if requested)
4. Returns the calculated sleep duration and sleep decision to the application

The application uses input parameter param_ptr->app_sleep_request to indicate whether it requests this function to put the BB and RF hardware into Sleep Mode when possible (0x0: not requesting; 0x1: requesting). In detail:

When the application calls this function with param_ptr->app_sleep_request set to 0x0:

- If Sleep Mode is possible, this function writes the expected baseband sleep duration (in low-power clock cycles) in the param_ptr->calculated_sleep_duration field, and returns RWIP_DEEP_SLEEP.

  NOTE: In this case, BLE_Baseband_Sleep() does not put the BB and RF hardware into Sleep Mode even if itis possible, because this has not been requested.

- If Sleep Mode is not possible, this function returns RWIP_CPU_SLEEP or RWIP_ACTIVE.

When the application calls this function with param_ptr->app_sleep_request set to 0x1:

- If Sleep Mode is possible, this function writes the expected baseband sleep duration (in low-power clock cycles) in the param_ptr->calculated_sleep_duration field, programs and starts the low-power BB timer, puts the BB and RF hardware into Sleep Mode, and finally returns RWIP_DEEP_SLEEP.
- If Sleep Mode is not possible, this function returns RWIP_CPU_SLEEP or RWIP_ACTIVE.

In other words, the application calls BLE_Baseband_Sleep() with param_ptr->app_sleep_request set to 0x0 when it simply wants to check if Sleep Mode is possible and to get the expected baseband sleep duration. If Sleep Mode is possible, the application then might want to check the expected baseband sleep duration and other application-specific contexts to decide if it wants to enter Sleep Mode or not. If the application decides to enter Sleep Mode, it needs to call BLE_Baseband_Sleep() again with param_ptr->app_sleep_request set to 0x1.

#### Example:

/* Attempt to place the device to sleep */

struct ble_sleep_api_param_tag param;

param.app_sleep_request = 1;

param.max_sleep_duration = MAX_SLEEP_DURATION;

param.min_sleep_duration = MIN_SLEEP_DURATION;

switch(BLE_Baseband_Sleep(&param))

{

case RWIP_DEEP_SLEEP:

{

/* Save the baseband and RF registers, then go to sleep */

BB_Sleep(POWER_MODE);

break;

}

case RWIP_CPU_SLEEP:

{

/* Wait for interrupt */

__WFI();

break;

}

case RWIP_ACTIVE:

default:

{

}

}

## BLE_Kernel_Process

#### Prototype:

void BLE_Kernel_Process(void)

#### Parameters:

None

#### Return:

None

#### Description:

Execute any pending events that have been scheduled with the event kernel.

#### Example:

/* Main application loop:

* - Run the kernel scheduler

* - Refresh the watchdog and wait for an interrupt before continuing */

while (1)

{

BLE_Kernel_Process();

/* Refresh the watchdog timer */

SYS_WATCHDOG_REFRESH();

/* Wait for an event before executing the scheduler again */

__WFI();

}

## BLE_Baseband_Is_Awake

#### Prototype:

bool BLE_Baseband_Is_Awake(void)

#### Parameters:

None

#### Return:

True if the Bluetooth baseband is awake, false otherwise.

#### Description:

Check if the Bluetooth baseband is awake.

#### Example:

/* Check if the Bluetooth baseband is still awake */

if (BLE_Baseband_Is_Awake())

{

BLE_Baseband_Sleep(&param);

}