Skip to content
Permalink
Browse files

doc: add brief info on FreeRTOS run loop

  • Loading branch information...
mringwal committed Aug 16, 2019
1 parent c682b8e commit 0b058bd72c33483d2f374e8fe27781b0daa40bd9
Showing with 19 additions and 2 deletions.
  1. +19 −2 doc/manual/docs/how_to.md
@@ -199,7 +199,7 @@ The source tree has been organized to easily setup new projects.

Path | Description
--------------------|---------------
chipset | Support for individual Bluetooth chipsets
chipset | Support for individual Bluetooth Controller chipsets
doc | Sources for BTstack documentation
example | Example applications available for all ports
platform | Support for special OSs and/or MCU architectures
@@ -246,12 +246,13 @@ tick hardware abstraction.
BTstack provides different run loop implementations that implement the *btstack_run_loop_t* interface:

- Embedded: the main implementation for embedded systems, especially without an RTOS.
- FreeRTOS: implementation to run BTstack on a dedicated FreeRTOS thread
- POSIX: implementation for POSIX systems based on the select() call.
- CoreFoundation: implementation for iOS and OS X applications
- WICED: implementation for the Broadcom WICED SDK RTOS abstraction that wraps FreeRTOS or ThreadX.
- Windows: implementation for Windows based on Event objects and WaitForMultipleObjects() call.

Depending on the platform, data sources are either polled (embedded), or the platform provides a way
Depending on the platform, data sources are either polled (embedded, FreeRTOS), or the platform provides a way
to wait for a data source to become ready for read or write (POSIX, CoreFoundation, Windows), or,
are not used as the HCI transport driver and the run loop is implemented in a different way (WICED).
In any case, the callbacks must be to explicitly enabled with the *btstack_run_loop_enable_data_source_callbacks(..)* function.
@@ -294,6 +295,22 @@ entering sleep mode causing another run loop cycle.
To enable the use of timers, make sure that you defined HAVE_EMBEDDED_TICK or HAVE_EMBEDDED_TIME_MS in the
config file.

### Run loop FreeRTOS

The FreeRTOS run loop is used on a dedicated FreeRTOS thread and it uses a FreeRTOS queue to schedule callbacks on the run loop.
In each iteration:

- all data sources are polled
- all scheduled callbacks are executed
- all expired timers are called
- finally, it gets the next timeout. It then waits for a 'trigger' or the next timeout, if set.

To trigger the run loop, *btstack_run_loop_freertos_trigger* and *btstack_run_loop_freertos_trigger_from_isr* can be called.
This causes the data sources to get polled.

Alternatively. *btstack_run_loop_freertos_execute_code_on_main_thread* can be used to schedule a callback on the main loop.
Please note that the queue is finite (see *RUN_LOOP_QUEUE_LENGTH* in btstack_run_loop_embedded).

### Run loop POSIX

The data sources are standard File Descriptors. In the run loop execute implementation,

0 comments on commit 0b058bd

Please sign in to comment.
You can’t perform that action at this time.