feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

Merge branch 'feature/freertos_api_doc' into 'master'

Browse Source 
Add FreeRTOS API documentation

See merge request !1634
This commit is contained in:
Ivan Grokhotkov
2017-12-07 13:50:10 +08:00
parent 2b92119840 d6525fb3e6
commit b46d4ab632
11 changed files with 2481 additions and 2688 deletions
Download Patch File Download Diff File Expand all files Collapse all files

617
components/freertos/include/freertos/event_groups.h
View File

@@ -104,7 +104,6 @@ extern "C" {
* used to create a synchronisation point between multiple tasks (a * used to create a synchronisation point between multiple tasks (a
* 'rendezvous'). * 'rendezvous').
* *
* \defgroup EventGroup
*/ */
@@ -116,7 +115,6 @@ extern "C" {
* xEventGroupCreate() returns an EventGroupHandle_t variable that can then * xEventGroupCreate() returns an EventGroupHandle_t variable that can then
* be used as a parameter to other event group functions. * be used as a parameter to other event group functions.
* *
* \defgroup EventGroupHandle_t EventGroupHandle_t
* \ingroup EventGroup * \ingroup EventGroup
*/ */
typedef void * EventGroupHandle_t; typedef void * EventGroupHandle_t;
@@ -126,17 +124,11 @@ typedef void * EventGroupHandle_t;
* number of bits it holds is set by configUSE_16_BIT_TICKS (16 bits if set to 1, * number of bits it holds is set by configUSE_16_BIT_TICKS (16 bits if set to 1,
* 32 bits if set to 0. * 32 bits if set to 0.
* *
* \defgroup EventBits_t EventBits_t
* \ingroup EventGroup * \ingroup EventGroup
*/ */
typedef TickType_t EventBits_t; typedef TickType_t EventBits_t;
/** /**
* event_groups.h
*<pre>
EventGroupHandle_t xEventGroupCreate( void );
</pre>
*
* Create a new event group. * Create a new event group.
* *
* Internally, within the FreeRTOS implementation, event groups use a [small] * Internally, within the FreeRTOS implementation, event groups use a [small]
@@ -162,25 +154,24 @@ typedef TickType_t EventBits_t;
* event group then NULL is returned. See http://www.freertos.org/a00111.html * event group then NULL is returned. See http://www.freertos.org/a00111.html
* *
* Example usage: * Example usage:
<pre> * @code{c}
// Declare a variable to hold the created event group. * // Declare a variable to hold the created event group.
EventGroupHandle_t xCreatedEventGroup; * EventGroupHandle_t xCreatedEventGroup;
*
// Attempt to create the event group. * // Attempt to create the event group.
xCreatedEventGroup = xEventGroupCreate(); * xCreatedEventGroup = xEventGroupCreate();
*
// Was the event group created successfully? * // Was the event group created successfully?
if( xCreatedEventGroup == NULL ) * if( xCreatedEventGroup == NULL )
{ * {
// The event group was not created because there was insufficient * // The event group was not created because there was insufficient
// FreeRTOS heap available. * // FreeRTOS heap available.
} * }
else * else
{ * {
// The event group was created. * // The event group was created.
} * }
</pre> * @endcode
* \defgroup xEventGroupCreate xEventGroupCreate
* \ingroup EventGroup * \ingroup EventGroup
*/ */
#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
@@ -188,11 +179,6 @@ typedef TickType_t EventBits_t;
#endif #endif
/** /**
* event_groups.h
*<pre>
EventGroupHandle_t xEventGroupCreateStatic( EventGroupHandle_t * pxEventGroupBuffer );
</pre>
*
* Create a new event group. * Create a new event group.
* *
* Internally, within the FreeRTOS implementation, event groups use a [small] * Internally, within the FreeRTOS implementation, event groups use a [small]
@@ -221,35 +207,26 @@ typedef TickType_t EventBits_t;
* returned. If pxEventGroupBuffer was NULL then NULL is returned. * returned. If pxEventGroupBuffer was NULL then NULL is returned.
* *
* Example usage: * Example usage:
<pre> * @code{c}
// StaticEventGroup_t is a publicly accessible structure that has the same * // StaticEventGroup_t is a publicly accessible structure that has the same
// size and alignment requirements as the real event group structure. It is * // size and alignment requirements as the real event group structure. It is
// provided as a mechanism for applications to know the size of the event * // provided as a mechanism for applications to know the size of the event
// group (which is dependent on the architecture and configuration file * // group (which is dependent on the architecture and configuration file
// settings) without breaking the strict data hiding policy by exposing the * // settings) without breaking the strict data hiding policy by exposing the
// real event group internals. This StaticEventGroup_t variable is passed * // real event group internals. This StaticEventGroup_t variable is passed
// into the xSemaphoreCreateEventGroupStatic() function and is used to store * // into the xSemaphoreCreateEventGroupStatic() function and is used to store
// the event group's data structures * // the event group's data structures
StaticEventGroup_t xEventGroupBuffer; * StaticEventGroup_t xEventGroupBuffer;
*
// Create the event group without dynamically allocating any memory. * // Create the event group without dynamically allocating any memory.
xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer ); * xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
</pre> * @endcode
*/ */
#if( configSUPPORT_STATIC_ALLOCATION == 1 ) #if( configSUPPORT_STATIC_ALLOCATION == 1 )
EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer ) PRIVILEGED_FUNCTION; EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer ) PRIVILEGED_FUNCTION;
#endif #endif
/** /**
* event_groups.h
*<pre>
EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToWaitFor,
const BaseType_t xClearOnExit,
const BaseType_t xWaitForAllBits,
const TickType_t xTicksToWait );
</pre>
*
* [Potentially] block to wait for one or more bits to be set within a * [Potentially] block to wait for one or more bits to be set within a
* previously created event group. * previously created event group.
* *
@@ -292,54 +269,48 @@ typedef TickType_t EventBits_t;
* pdTRUE. * pdTRUE.
* *
* Example usage: * Example usage:
<pre> * @code{c}
#define BIT_0 ( 1 << 0 ) * #define BIT_0 ( 1 << 0 )
#define BIT_4 ( 1 << 4 ) * #define BIT_4 ( 1 << 4 )
*
void aFunction( EventGroupHandle_t xEventGroup ) * void aFunction( EventGroupHandle_t xEventGroup )
{ * {
EventBits_t uxBits; * EventBits_t uxBits;
const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS; * const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
*
// Wait a maximum of 100ms for either bit 0 or bit 4 to be set within * // Wait a maximum of 100ms for either bit 0 or bit 4 to be set within
// the event group. Clear the bits before exiting. * // the event group. Clear the bits before exiting.
uxBits = xEventGroupWaitBits( * uxBits = xEventGroupWaitBits(
xEventGroup, // The event group being tested. * xEventGroup, // The event group being tested.
BIT_0 | BIT_4, // The bits within the event group to wait for. * BIT_0 | BIT_4, // The bits within the event group to wait for.
pdTRUE, // BIT_0 and BIT_4 should be cleared before returning. * pdTRUE, // BIT_0 and BIT_4 should be cleared before returning.
pdFALSE, // Don't wait for both bits, either bit will do. * pdFALSE, // Don't wait for both bits, either bit will do.
xTicksToWait ); // Wait a maximum of 100ms for either bit to be set. * xTicksToWait ); // Wait a maximum of 100ms for either bit to be set.
*
if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) ) * if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
{ * {
// xEventGroupWaitBits() returned because both bits were set. * // xEventGroupWaitBits() returned because both bits were set.
} * }
else if( ( uxBits & BIT_0 ) != 0 ) * else if( ( uxBits & BIT_0 ) != 0 )
{ * {
// xEventGroupWaitBits() returned because just BIT_0 was set. * // xEventGroupWaitBits() returned because just BIT_0 was set.
} * }
else if( ( uxBits & BIT_4 ) != 0 ) * else if( ( uxBits & BIT_4 ) != 0 )
{ * {
// xEventGroupWaitBits() returned because just BIT_4 was set. * // xEventGroupWaitBits() returned because just BIT_4 was set.
} * }
else * else
{ * {
// xEventGroupWaitBits() returned because xTicksToWait ticks passed * // xEventGroupWaitBits() returned because xTicksToWait ticks passed
// without either BIT_0 or BIT_4 becoming set. * // without either BIT_0 or BIT_4 becoming set.
} * }
} * }
</pre> * @endcode{c}
* \defgroup xEventGroupWaitBits xEventGroupWaitBits
* \ingroup EventGroup * \ingroup EventGroup
*/ */
EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
/** /**
* event_groups.h
*<pre>
EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );
</pre>
*
* Clear bits within an event group. This function cannot be called from an * Clear bits within an event group. This function cannot be called from an
* interrupt. * interrupt.
* *
@@ -352,51 +323,45 @@ EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, const EventBits
* @return The value of the event group before the specified bits were cleared. * @return The value of the event group before the specified bits were cleared.
* *
* Example usage: * Example usage:
<pre> * @code{c}
#define BIT_0 ( 1 << 0 ) * #define BIT_0 ( 1 << 0 )
#define BIT_4 ( 1 << 4 ) * #define BIT_4 ( 1 << 4 )
*
void aFunction( EventGroupHandle_t xEventGroup ) * void aFunction( EventGroupHandle_t xEventGroup )
{ * {
EventBits_t uxBits; * EventBits_t uxBits;
*
// Clear bit 0 and bit 4 in xEventGroup. * // Clear bit 0 and bit 4 in xEventGroup.
uxBits = xEventGroupClearBits( * uxBits = xEventGroupClearBits(
xEventGroup, // The event group being updated. * xEventGroup, // The event group being updated.
BIT_0 | BIT_4 );// The bits being cleared. * BIT_0 | BIT_4 );// The bits being cleared.
*
if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) ) * if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
{ * {
// Both bit 0 and bit 4 were set before xEventGroupClearBits() was * // Both bit 0 and bit 4 were set before xEventGroupClearBits() was
// called. Both will now be clear (not set). * // called. Both will now be clear (not set).
} * }
else if( ( uxBits & BIT_0 ) != 0 ) * else if( ( uxBits & BIT_0 ) != 0 )
{ * {
// Bit 0 was set before xEventGroupClearBits() was called. It will * // Bit 0 was set before xEventGroupClearBits() was called. It will
// now be clear. * // now be clear.
} * }
else if( ( uxBits & BIT_4 ) != 0 ) * else if( ( uxBits & BIT_4 ) != 0 )
{ * {
// Bit 4 was set before xEventGroupClearBits() was called. It will * // Bit 4 was set before xEventGroupClearBits() was called. It will
// now be clear. * // now be clear.
} * }
else * else
{ * {
// Neither bit 0 nor bit 4 were set in the first place. * // Neither bit 0 nor bit 4 were set in the first place.
} * }
} * }
</pre> * @endcode
* \defgroup xEventGroupClearBits xEventGroupClearBits
* \ingroup EventGroup * \ingroup EventGroup
*/ */
EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION; EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION;
/** /**
* event_groups.h
*<pre>
BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
</pre>
*
* A version of xEventGroupClearBits() that can be called from an interrupt. * A version of xEventGroupClearBits() that can be called from an interrupt.
* *
* Setting bits in an event group is not a deterministic operation because there * Setting bits in an event group is not a deterministic operation because there
@@ -420,28 +385,27 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBit
* if the timer service queue was full. * if the timer service queue was full.
* *
* Example usage: * Example usage:
<pre> * @code{c}
#define BIT_0 ( 1 << 0 ) * #define BIT_0 ( 1 << 0 )
#define BIT_4 ( 1 << 4 ) * #define BIT_4 ( 1 << 4 )
*
// An event group which it is assumed has already been created by a call to * // An event group which it is assumed has already been created by a call to
// xEventGroupCreate(). * // xEventGroupCreate().
EventGroupHandle_t xEventGroup; * EventGroupHandle_t xEventGroup;
*
void anInterruptHandler( void ) * void anInterruptHandler( void )
{ * {
// Clear bit 0 and bit 4 in xEventGroup. * // Clear bit 0 and bit 4 in xEventGroup.
xResult = xEventGroupClearBitsFromISR( * xResult = xEventGroupClearBitsFromISR(
xEventGroup, // The event group being updated. * xEventGroup, // The event group being updated.
BIT_0 | BIT_4 ); // The bits being set. * BIT_0 | BIT_4 ); // The bits being set.
*
if( xResult == pdPASS ) * if( xResult == pdPASS )
{ * {
// The message was posted successfully. * // The message was posted successfully.
} * }
} * }
</pre> * @endcode
* \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR
* \ingroup EventGroup * \ingroup EventGroup
*/ */
#if( configUSE_TRACE_FACILITY == 1 ) #if( configUSE_TRACE_FACILITY == 1 )
@@ -451,11 +415,6 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBit
#endif #endif
/** /**
* event_groups.h
*<pre>
EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
</pre>
*
* Set bits within an event group. * Set bits within an event group.
* This function cannot be called from an interrupt. xEventGroupSetBitsFromISR() * This function cannot be called from an interrupt. xEventGroupSetBitsFromISR()
* is a version that can be called from an interrupt. * is a version that can be called from an interrupt.
@@ -480,56 +439,50 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBit
* event group value before the call to xEventGroupSetBits() returns. * event group value before the call to xEventGroupSetBits() returns.
* *
* Example usage: * Example usage:
<pre> * @code{c}
#define BIT_0 ( 1 << 0 ) * #define BIT_0 ( 1 << 0 )
#define BIT_4 ( 1 << 4 ) * #define BIT_4 ( 1 << 4 )
*
void aFunction( EventGroupHandle_t xEventGroup ) * void aFunction( EventGroupHandle_t xEventGroup )
{ * {
EventBits_t uxBits; * EventBits_t uxBits;
*
// Set bit 0 and bit 4 in xEventGroup. * // Set bit 0 and bit 4 in xEventGroup.
uxBits = xEventGroupSetBits( * uxBits = xEventGroupSetBits(
xEventGroup, // The event group being updated. * xEventGroup, // The event group being updated.
BIT_0 | BIT_4 );// The bits being set. * BIT_0 | BIT_4 );// The bits being set.
*
if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) ) * if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
{ * {
// Both bit 0 and bit 4 remained set when the function returned. * // Both bit 0 and bit 4 remained set when the function returned.
} * }
else if( ( uxBits & BIT_0 ) != 0 ) * else if( ( uxBits & BIT_0 ) != 0 )
{ * {
// Bit 0 remained set when the function returned, but bit 4 was * // Bit 0 remained set when the function returned, but bit 4 was
// cleared. It might be that bit 4 was cleared automatically as a * // cleared. It might be that bit 4 was cleared automatically as a
// task that was waiting for bit 4 was removed from the Blocked * // task that was waiting for bit 4 was removed from the Blocked
// state. * // state.
} * }
else if( ( uxBits & BIT_4 ) != 0 ) * else if( ( uxBits & BIT_4 ) != 0 )
{ * {
// Bit 4 remained set when the function returned, but bit 0 was * // Bit 4 remained set when the function returned, but bit 0 was
// cleared. It might be that bit 0 was cleared automatically as a * // cleared. It might be that bit 0 was cleared automatically as a
// task that was waiting for bit 0 was removed from the Blocked * // task that was waiting for bit 0 was removed from the Blocked
// state. * // state.
} * }
else * else
{ * {
// Neither bit 0 nor bit 4 remained set. It might be that a task * // Neither bit 0 nor bit 4 remained set. It might be that a task
// was waiting for both of the bits to be set, and the bits were * // was waiting for both of the bits to be set, and the bits were
// cleared as the task left the Blocked state. * // cleared as the task left the Blocked state.
} * }
} * }
</pre> * @endcode{c}
* \defgroup xEventGroupSetBits xEventGroupSetBits
* \ingroup EventGroup * \ingroup EventGroup
*/ */
EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet ) PRIVILEGED_FUNCTION; EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet ) PRIVILEGED_FUNCTION;
/** /**
* event_groups.h
*<pre>
BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken );
</pre>
*
* A version of xEventGroupSetBits() that can be called from an interrupt. * A version of xEventGroupSetBits() that can be called from an interrupt.
* *
* Setting bits in an event group is not a deterministic operation because there * Setting bits in an event group is not a deterministic operation because there
@@ -561,39 +514,38 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_
* if the timer service queue was full. * if the timer service queue was full.
* *
* Example usage: * Example usage:
<pre> * @code{c}
#define BIT_0 ( 1 << 0 ) * #define BIT_0 ( 1 << 0 )
#define BIT_4 ( 1 << 4 ) * #define BIT_4 ( 1 << 4 )
*
// An event group which it is assumed has already been created by a call to * // An event group which it is assumed has already been created by a call to
// xEventGroupCreate(). * // xEventGroupCreate().
EventGroupHandle_t xEventGroup; * EventGroupHandle_t xEventGroup;
*
void anInterruptHandler( void ) * void anInterruptHandler( void )
{ * {
BaseType_t xHigherPriorityTaskWoken, xResult; * BaseType_t xHigherPriorityTaskWoken, xResult;
*
// xHigherPriorityTaskWoken must be initialised to pdFALSE. * // xHigherPriorityTaskWoken must be initialised to pdFALSE.
xHigherPriorityTaskWoken = pdFALSE; * xHigherPriorityTaskWoken = pdFALSE;
*
// Set bit 0 and bit 4 in xEventGroup. * // Set bit 0 and bit 4 in xEventGroup.
xResult = xEventGroupSetBitsFromISR( * xResult = xEventGroupSetBitsFromISR(
xEventGroup, // The event group being updated. * xEventGroup, // The event group being updated.
BIT_0 | BIT_4 // The bits being set. * BIT_0 | BIT_4 // The bits being set.
&xHigherPriorityTaskWoken ); * &xHigherPriorityTaskWoken );
*
// Was the message posted successfully? * // Was the message posted successfully?
if( xResult == pdPASS ) * if( xResult == pdPASS )
{ * {
// If xHigherPriorityTaskWoken is now set to pdTRUE then a context * // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
// switch should be requested. The macro used is port specific and * // switch should be requested. The macro used is port specific and
// will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - * // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
// refer to the documentation page for the port being used. * // refer to the documentation page for the port being used.
portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); * portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
} * }
} * }
</pre> * @endcode
* \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR
* \ingroup EventGroup * \ingroup EventGroup
*/ */
#if( configUSE_TRACE_FACILITY == 1 ) #if( configUSE_TRACE_FACILITY == 1 )
@@ -603,14 +555,6 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_
#endif #endif
/** /**
* event_groups.h
*<pre>
EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet,
const EventBits_t uxBitsToWaitFor,
TickType_t xTicksToWait );
</pre>
*
* Atomically set bits within an event group, then wait for a combination of * Atomically set bits within an event group, then wait for a combination of
* bits to be set within the same event group. This functionality is typically * bits to be set within the same event group. This functionality is typically
* used to synchronise multiple tasks, where each task has to wait for the other * used to synchronise multiple tasks, where each task has to wait for the other
@@ -648,93 +592,87 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_
* automatically cleared. * automatically cleared.
* *
* Example usage: * Example usage:
<pre> * @code{c}
// Bits used by the three tasks. * // Bits used by the three tasks.
#define TASK_0_BIT ( 1 << 0 ) * #define TASK_0_BIT ( 1 << 0 )
#define TASK_1_BIT ( 1 << 1 ) * #define TASK_1_BIT ( 1 << 1 )
#define TASK_2_BIT ( 1 << 2 ) * #define TASK_2_BIT ( 1 << 2 )
*
#define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT ) * #define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT )
*
// Use an event group to synchronise three tasks. It is assumed this event * // Use an event group to synchronise three tasks. It is assumed this event
// group has already been created elsewhere. * // group has already been created elsewhere.
EventGroupHandle_t xEventBits; * EventGroupHandle_t xEventBits;
*
void vTask0( void *pvParameters ) * void vTask0( void *pvParameters )
{ * {
EventBits_t uxReturn; * EventBits_t uxReturn;
TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS; * TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
*
for( ;; ) * for( ;; )
{ * {
// Perform task functionality here. * // Perform task functionality here.
*
// Set bit 0 in the event flag to note this task has reached the * // Set bit 0 in the event flag to note this task has reached the
// sync point. The other two tasks will set the other two bits defined * // sync point. The other two tasks will set the other two bits defined
// by ALL_SYNC_BITS. All three tasks have reached the synchronisation * // by ALL_SYNC_BITS. All three tasks have reached the synchronisation
// point when all the ALL_SYNC_BITS are set. Wait a maximum of 100ms * // point when all the ALL_SYNC_BITS are set. Wait a maximum of 100ms
// for this to happen. * // for this to happen.
uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS, xTicksToWait ); * uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS, xTicksToWait );
*
if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS ) * if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS )
{ * {
// All three tasks reached the synchronisation point before the call * // All three tasks reached the synchronisation point before the call
// to xEventGroupSync() timed out. * // to xEventGroupSync() timed out.
} * }
} * }
} * }
*
void vTask1( void *pvParameters ) * void vTask1( void *pvParameters )
{ * {
for( ;; ) * for( ;; )
{ * {
// Perform task functionality here. * // Perform task functionality here.
*
// Set bit 1 in the event flag to note this task has reached the * // Set bit 1 in the event flag to note this task has reached the
// synchronisation point. The other two tasks will set the other two * // synchronisation point. The other two tasks will set the other two
// bits defined by ALL_SYNC_BITS. All three tasks have reached the * // bits defined by ALL_SYNC_BITS. All three tasks have reached the
// synchronisation point when all the ALL_SYNC_BITS are set. Wait * // synchronisation point when all the ALL_SYNC_BITS are set. Wait
// indefinitely for this to happen. * // indefinitely for this to happen.
xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY ); * xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY );
*
// xEventGroupSync() was called with an indefinite block time, so * // xEventGroupSync() was called with an indefinite block time, so
// this task will only reach here if the syncrhonisation was made by all * // this task will only reach here if the syncrhonisation was made by all
// three tasks, so there is no need to test the return value. * // three tasks, so there is no need to test the return value.
} * }
} * }
*
void vTask2( void *pvParameters ) * void vTask2( void *pvParameters )
{ * {
for( ;; ) * for( ;; )
{ * {
// Perform task functionality here. * // Perform task functionality here.
*
// Set bit 2 in the event flag to note this task has reached the * // Set bit 2 in the event flag to note this task has reached the
// synchronisation point. The other two tasks will set the other two * // synchronisation point. The other two tasks will set the other two
// bits defined by ALL_SYNC_BITS. All three tasks have reached the * // bits defined by ALL_SYNC_BITS. All three tasks have reached the
// synchronisation point when all the ALL_SYNC_BITS are set. Wait * // synchronisation point when all the ALL_SYNC_BITS are set. Wait
// indefinitely for this to happen. * // indefinitely for this to happen.
xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY ); * xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY );
*
// xEventGroupSync() was called with an indefinite block time, so * // xEventGroupSync() was called with an indefinite block time, so
// this task will only reach here if the syncrhonisation was made by all * // this task will only reach here if the syncrhonisation was made by all
// three tasks, so there is no need to test the return value. * // three tasks, so there is no need to test the return value.
} * }
} * }
*
</pre> * @endcode
* \defgroup xEventGroupSync xEventGroupSync
* \ingroup EventGroup * \ingroup EventGroup
*/ */
EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
/** /**
* event_groups.h
*<pre>
EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup );
</pre>
*
* Returns the current value of the bits in an event group. This function * Returns the current value of the bits in an event group. This function
* cannot be used from an interrupt. * cannot be used from an interrupt.
* *
@@ -742,33 +680,22 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t u
* *
* @return The event group bits at the time xEventGroupGetBits() was called. * @return The event group bits at the time xEventGroupGetBits() was called.
* *
* \defgroup xEventGroupGetBits xEventGroupGetBits
* \ingroup EventGroup * \ingroup EventGroup
*/ */
#define xEventGroupGetBits( xEventGroup ) xEventGroupClearBits( xEventGroup, 0 ) #define xEventGroupGetBits( xEventGroup ) xEventGroupClearBits( xEventGroup, 0 )
/** /**
* event_groups.h
*<pre>
EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
</pre>
*
* A version of xEventGroupGetBits() that can be called from an ISR. * A version of xEventGroupGetBits() that can be called from an ISR.
* *
* @param xEventGroup The event group being queried. * @param xEventGroup The event group being queried.
* *
* @return The event group bits at the time xEventGroupGetBitsFromISR() was called. * @return The event group bits at the time xEventGroupGetBitsFromISR() was called.
* *
* \defgroup xEventGroupGetBitsFromISR xEventGroupGetBitsFromISR
* \ingroup EventGroup * \ingroup EventGroup
*/ */
EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ); EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
/** /**
* event_groups.h
*<pre>
void xEventGroupDelete( EventGroupHandle_t xEventGroup );
</pre>
* *
* Delete an event group that was previously created by a call to * Delete an event group that was previously created by a call to
* xEventGroupCreate(). Tasks that are blocked on the event group will be * xEventGroupCreate(). Tasks that are blocked on the event group will be
@@ -778,6 +705,8 @@ EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
*/ */
void vEventGroupDelete( EventGroupHandle_t xEventGroup ); void vEventGroupDelete( EventGroupHandle_t xEventGroup );
/** @cond */
/* For internal use only. */ /* For internal use only. */
void vEventGroupSetBitsCallback( void *pvEventGroup, const uint32_t ulBitsToSet ); void vEventGroupSetBitsCallback( void *pvEventGroup, const uint32_t ulBitsToSet );
void vEventGroupClearBitsCallback( void *pvEventGroup, const uint32_t ulBitsToClear ); void vEventGroupClearBitsCallback( void *pvEventGroup, const uint32_t ulBitsToClear );
@@ -786,6 +715,8 @@ void vEventGroupClearBitsCallback( void *pvEventGroup, const uint32_t ulBitsToCl
UBaseType_t uxEventGroupGetNumber( void* xEventGroup ); UBaseType_t uxEventGroupGetNumber( void* xEventGroup );
#endif #endif
/** @endcond */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif

1518
components/freertos/include/freertos/queue.h
View File

File diff suppressed because it is too large Load Diff

254
components/freertos/include/freertos/ringbuf.h
View File

@@ -9,50 +9,58 @@
extern "C" { extern "C" {
#endif #endif
/*
Header definitions for a FreeRTOS ringbuffer object
A ringbuffer instantiated by these functions essentially acts like a FreeRTOS queue, with the
difference that it's strictly FIFO and with the main advantage that you can put in randomly-sized
items. The capacity, accordingly, isn't measured in the amount of items, but the amount of memory
that is used for storing the items. Dependent on the size of the items, more or less of them will
fit in the ring buffer.
This ringbuffer tries to be efficient with memory: when inserting an item, the item data will
be copied to the ringbuffer memory. When retrieving an item, however, a reference to ringbuffer
memory will be returned. The returned memory is guaranteed to be 32-bit aligned and contiguous.
The application can use this memory, but as long as it does, ringbuffer writes that would write
to this bit of memory will block.
The requirement for items to be contiguous is slightly problematic when the only way to place
the next item would involve a wraparound from the end to the beginning of the ringbuffer. This can
be solved (or not) in a few ways:
- type = RINGBUF_TYPE_ALLOWSPLIT: The insertion code will split the item in two items; one which fits
in the space left at the end of the ringbuffer, one that contains the remaining data which is placed
in the beginning. Two xRingbufferReceive calls will be needed to retrieve the data.
- type = RINGBUF_TYPE_NOSPLIT: The insertion code will leave the room at the end of the ringbuffer
unused and instead will put the entire item at the start of the ringbuffer, as soon as there is
enough free space.
- type = RINGBUF_TYPE_BYTEBUF: This is your conventional byte-based ringbuffer. It does have no
overhead, but it has no item contiguousness either: a read will just give you the entire written
buffer space, or the space up to the end of the buffer, and writes can be broken up in any way
possible. Note that this type cannot do a 2nd read before returning the memory of the 1st.
The maximum size of an item will be affected by this decision. When split items are allowed, it's
acceptable to push items of (buffer_size)-16 bytes into the buffer. When it's not allowed, the
maximum size is (buffer_size/2)-8 bytes. The bytebuf can fill the entire buffer with data, it has
no overhead.
*/
#include <freertos/queue.h> #include <freertos/queue.h>
//An opaque handle for a ringbuff object. //An opaque handle for a ringbuff object.
typedef void * RingbufHandle_t; typedef void * RingbufHandle_t;
//The various types of buffer /**
* @brief The various types of buffer
*
* A ringbuffer instantiated by these functions essentially acts like a
* FreeRTOS queue, with the difference that it's strictly FIFO and with
* the main advantage that you can put in randomly-sized items. The capacity,
* accordingly, isn't measured in the amount of items, but the amount of
* memory that is used for storing the items. Dependent on the size of
* the items, more or less of them will fit in the ring buffer.
*
* This ringbuffer tries to be efficient with memory: when inserting an item,
* the item data will be copied to the ringbuffer memory. When retrieving
* an item, however, a reference to ringbuffer memory will be returned.
* The returned memory is guaranteed to be 32-bit aligned and contiguous.
* The application can use this memory, but as long as it does, ringbuffer
* writes that would write to this bit of memory will block.
*
* The requirement for items to be contiguous is slightly problematic when
* the only way to place the next item would involve a wraparound from the end
* to the beginning of the ringbuffer. This can be solved (or not) in a few ways,
* see descriptions of possible ringbuf_type_t types below.
*
* The maximum size of an item will be affected by ringbuffer type.
* When split items are allowed, it is acceptable to push items of
* (buffer_size)-16 bytes into the buffer.
* When it's not allowed, the maximum size is (buffer_size/2)-8 bytes.
* The bytebuf can fill the entire buffer with data, it has no overhead.
*/
typedef enum { typedef enum {
/** The insertion code will leave the room at the end of the ringbuffer
* unused and instead will put the entire item at the start of the ringbuffer,
* as soon as there is enough free space.
*/
RINGBUF_TYPE_NOSPLIT = 0, RINGBUF_TYPE_NOSPLIT = 0,
/** The insertion code will split the item in two items; one which fits
* in the space left at the end of the ringbuffer, one that contains
* the remaining data which is placed in the beginning.
* Two xRingbufferReceive calls will be needed to retrieve the data.
*/
RINGBUF_TYPE_ALLOWSPLIT, RINGBUF_TYPE_ALLOWSPLIT,
/** This is your conventional byte-based ringbuffer. It does have no
* overhead, but it has no item contiguousness either: a read will just
* give you the entire written buffer space, or the space up to the end
* of the buffer, and writes can be broken up in any way possible.
* Note that this type cannot do a 2nd read before returning the memory
* of the 1st.
*/
RINGBUF_TYPE_BYTEBUF RINGBUF_TYPE_BYTEBUF
} ringbuf_type_t; } ringbuf_type_t;
@@ -60,22 +68,19 @@ typedef enum {
/** /**
* @brief Create a ring buffer * @brief Create a ring buffer
* *
* @param buf_length : Length of circular buffer, in bytes. Each entry will take up its own length, plus a header * @param buf_length Length of circular buffer, in bytes. Each entry will
* that at the moment is equal to sizeof(size_t). * take up its own length, plus a header that at the moment
* @param allow_split_items : pdTRUE if it is acceptable that item data is inserted as two * is equal to sizeof(size_t).
* items instead of one. * @param type Type of ring buffer, see ringbuf_type_t.
* *
* @return A RingbufHandle_t handle to the created ringbuffer, or NULL in case of error. * @return A RingbufHandle_t handle to the created ringbuffer, or NULL in case of error.
*/ */
RingbufHandle_t xRingbufferCreate(size_t buf_length, ringbuf_type_t type); RingbufHandle_t xRingbufferCreate(size_t buf_length, ringbuf_type_t type);
/** /**
* @brief Delete a ring buffer * @brief Delete a ring buffer
* *
* @param ringbuf - Ring buffer to delete * @param ringbuf Ring buffer to delete
*
* @return void
*/ */
void vRingbufferDelete(RingbufHandle_t ringbuf); void vRingbufferDelete(RingbufHandle_t ringbuf);
@@ -83,7 +88,7 @@ void vRingbufferDelete(RingbufHandle_t ringbuf);
/** /**
* @brief Get maximum size of an item that can be placed in the ring buffer * @brief Get maximum size of an item that can be placed in the ring buffer
* *
* @param ringbuf - Ring buffer to query * @param ringbuf Ring buffer to query
* *
* @return Maximum size, in bytes, of an item that can be placed in a ring buffer. * @return Maximum size, in bytes, of an item that can be placed in a ring buffer.
*/ */
@@ -93,13 +98,15 @@ size_t xRingbufferGetMaxItemSize(RingbufHandle_t ringbuf);
/** /**
* @brief Insert an item into the ring buffer * @brief Insert an item into the ring buffer
* *
* @param ringbuf - Ring buffer to insert the item into * @param ringbuf Ring buffer to insert the item into
* @param data - Pointer to data to insert. NULL is allowed if data_size is 0. * @param data Pointer to data to insert. NULL is allowed if data_size is 0.
* @param data_size - Size of data to insert. A value of 0 is allowed. * @param data_size Size of data to insert. A value of 0 is allowed.
* @param xTicksToWait - Ticks to wait for room in the ringbuffer. * @param ticks_to_wait Ticks to wait for room in the ringbuffer.
* *
* @return pdTRUE if succeeded, pdFALSE on time-out or when the buffer is larger * @return
* than indicated by xRingbufferGetMaxItemSize(ringbuf). * - pdTRUE if succeeded
* - pdFALSE on time-out or when the buffer is larger than indicated
* by xRingbufferGetMaxItemSize(ringbuf).
*/ */
BaseType_t xRingbufferSend(RingbufHandle_t ringbuf, void *data, size_t data_size, TickType_t ticks_to_wait); BaseType_t xRingbufferSend(RingbufHandle_t ringbuf, void *data, size_t data_size, TickType_t ticks_to_wait);
@@ -107,11 +114,11 @@ BaseType_t xRingbufferSend(RingbufHandle_t ringbuf, void *data, size_t data_size
/** /**
* @brief Insert an item into the ring buffer from an ISR * @brief Insert an item into the ring buffer from an ISR
* *
* @param ringbuf - Ring buffer to insert the item into * @param ringbuf Ring buffer to insert the item into
* @param data - Pointer to data to insert. NULL is allowed if data_size is 0. * @param data Pointer to data to insert. NULL is allowed if data_size is 0.
* @param data_size - Size of data to insert. A value of 0 is allowed. * @param data_size Size of data to insert. A value of 0 is allowed.
* @param higher_prio_task_awoken - Value pointed to will be set to pdTRUE if the push woke up a higher * @param[out] higher_prio_task_awoken Value pointed to will be set to pdTRUE
* priority task. * if the push woke up a higher priority task.
* *
* @return pdTRUE if succeeded, pdFALSE when the ring buffer does not have space. * @return pdTRUE if succeeded, pdFALSE when the ring buffer does not have space.
*/ */
@@ -120,14 +127,18 @@ BaseType_t xRingbufferSendFromISR(RingbufHandle_t ringbuf, void *data, size_t da
/** /**
* @brief Retrieve an item from the ring buffer * @brief Retrieve an item from the ring buffer
* *
* @note A call to vRingbufferReturnItem() is required after this to free up the data received. * @note A call to vRingbufferReturnItem() is required after this to free up
* the data received.
* *
* @param ringbuf - Ring buffer to retrieve the item from * @param ringbuf Ring buffer to retrieve the item from
* @param item_size - Pointer to a variable to which the size of the retrieved item will be written. * @param[out] item_size Pointer to a variable to which the size of the
* @param xTicksToWait - Ticks to wait for items in the ringbuffer. * retrieved item will be written.
* @param ticks_to_wait Ticks to wait for items in the ringbuffer.
* *
* @return Pointer to the retrieved item on success; *item_size filled with the length of the * @return
* item. NULL on timeout, *item_size is untouched in that case. * - pointer to the retrieved item on success; *item_size filled with
* the length of the item.
* - NULL on timeout, *item_size is untouched in that case.
*/ */
void *xRingbufferReceive(RingbufHandle_t ringbuf, size_t *item_size, TickType_t ticks_to_wait); void *xRingbufferReceive(RingbufHandle_t ringbuf, size_t *item_size, TickType_t ticks_to_wait);
@@ -135,44 +146,58 @@ void *xRingbufferReceive(RingbufHandle_t ringbuf, size_t *item_size, TickType_t
/** /**
* @brief Retrieve an item from the ring buffer from an ISR * @brief Retrieve an item from the ring buffer from an ISR
* *
* @note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received * @note A call to vRingbufferReturnItemFromISR() is required after this to
* free up the data received
* *
* @param ringbuf - Ring buffer to retrieve the item from * @param ringbuf Ring buffer to retrieve the item from
* @param item_size - Pointer to a variable to which the size of the retrieved item will be written. * @param[out] item_size Pointer to a variable to which the size of the
* retrieved item will be written.
* *
* @return Pointer to the retrieved item on success; *item_size filled with the length of the * @return
* item. NULL when the ringbuffer is empty, *item_size is untouched in that case. * - Pointer to the retrieved item on success; *item_size filled with
* the length of the item.
* - NULL when the ringbuffer is empty, *item_size is untouched in that case.
*/ */
void *xRingbufferReceiveFromISR(RingbufHandle_t ringbuf, size_t *item_size); void *xRingbufferReceiveFromISR(RingbufHandle_t ringbuf, size_t *item_size);
/** /**
* @brief Retrieve bytes from a ByteBuf type of ring buffer, specifying the maximum amount of bytes * @brief Retrieve bytes from a ByteBuf type of ring buffer,
* to return * specifying the maximum amount of bytes to return
* @note A call to vRingbufferReturnItem() is required after this to free up the data received.
* *
* @param ringbuf - Ring buffer to retrieve the item from * @note A call to vRingbufferReturnItem() is required after this to free up
* @param item_size - Pointer to a variable to which the size of the retrieved item will be written. * the data received.
* @param xTicksToWait - Ticks to wait for items in the ringbuffer.
* *
* @return Pointer to the retrieved item on success; *item_size filled with the length of the * @param ringbuf Ring buffer to retrieve the item from
* item. NULL on timeout, *item_size is untouched in that case. * @param[out] item_size Pointer to a variable to which the size
* of the retrieved item will be written.
* @param ticks_to_wait Ticks to wait for items in the ringbuffer.
* @param wanted_size Maximum number of bytes to return.
*
* @return
* - Pointer to the retrieved item on success; *item_size filled with
* the length of the item.
* - NULL on timeout, *item_size is untouched in that case.
*/ */
void *xRingbufferReceiveUpTo(RingbufHandle_t ringbuf, size_t *item_size, TickType_t ticks_to_wait, size_t wanted_size); void *xRingbufferReceiveUpTo(RingbufHandle_t ringbuf, size_t *item_size, TickType_t ticks_to_wait, size_t wanted_size);
/** /**
* @brief Retrieve bytes from a ByteBuf type of ring buffer, specifying the maximum amount of bytes * @brief Retrieve bytes from a ByteBuf type of ring buffer,
* to return. Call this from an ISR. * specifying the maximum amount of bytes to return. Call this from an ISR.
* *
* @note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received * @note A call to vRingbufferReturnItemFromISR() is required after this
* to free up the data received.
* *
* @param ringbuf - Ring buffer to retrieve the item from * @param ringbuf Ring buffer to retrieve the item from
* @param item_size - Pointer to a variable to which the size of the retrieved item will be written. * @param[out] item_size Pointer to a variable to which the size of the
* retrieved item will be written.
* @param wanted_size Maximum number of bytes to return.
* *
* @return Pointer to the retrieved item on success; *item_size filled with the length of the * @return
* item. NULL when the ringbuffer is empty, *item_size is untouched in that case. * - Pointer to the retrieved item on success; *item_size filled with
* the length of the item.
* - NULL when the ringbuffer is empty, *item_size is untouched in that case.
*/ */
void *xRingbufferReceiveUpToFromISR(RingbufHandle_t ringbuf, size_t *item_size, size_t wanted_size); void *xRingbufferReceiveUpToFromISR(RingbufHandle_t ringbuf, size_t *item_size, size_t wanted_size);
@@ -181,10 +206,8 @@ void *xRingbufferReceiveUpToFromISR(RingbufHandle_t ringbuf, size_t *item_size,
/** /**
* @brief Return a previously-retrieved item to the ringbuffer * @brief Return a previously-retrieved item to the ringbuffer
* *
* @param ringbuf - Ring buffer the item was retrieved from * @param ringbuf Ring buffer the item was retrieved from
* @param item - Item that was received earlier * @param item Item that was received earlier
*
* @return void
*/ */
void vRingbufferReturnItem(RingbufHandle_t ringbuf, void *item); void vRingbufferReturnItem(RingbufHandle_t ringbuf, void *item);
@@ -193,34 +216,37 @@ void vRingbufferReturnItem(RingbufHandle_t ringbuf, void *item);
/** /**
* @brief Return a previously-retrieved item to the ringbuffer from an ISR * @brief Return a previously-retrieved item to the ringbuffer from an ISR
* *
* @param ringbuf - Ring buffer the item was retrieved from * @param ringbuf Ring buffer the item was retrieved from
* @param item - Item that was received earlier * @param item Item that was received earlier
* @param higher_prio_task_awoken - Value pointed to will be set to pdTRUE if the push woke up a higher * @param[out] higher_prio_task_awoken Value pointed to will be set to pdTRUE
* priority task. * if the push woke up a higher priority task.
*
* @return void
*/ */
void vRingbufferReturnItemFromISR(RingbufHandle_t ringbuf, void *item, BaseType_t *higher_prio_task_awoken); void vRingbufferReturnItemFromISR(RingbufHandle_t ringbuf, void *item, BaseType_t *higher_prio_task_awoken);
/** /**
* @brief Add the ringbuffer to a queue set. This specifically adds the semaphore that indicates * @brief Add the ringbuffer to a queue set.
* more space has become available in the ringbuffer.
* *
* @param ringbuf - Ring buffer to add to the queue set * This specifically adds the semaphore that indicates more space
* @param xQueueSet - Queue set to add the ringbuffer to * has become available in the ringbuffer.
* *
* @return pdTRUE on success, pdFALSE otherwise * @param ringbuf Ring buffer to add to the queue set
* @param xQueueSet Queue set to add the ringbuffer to
*
* @return
* - pdTRUE on success, pdFALSE otherwise
*/ */
BaseType_t xRingbufferAddToQueueSetRead(RingbufHandle_t ringbuf, QueueSetHandle_t xQueueSet); BaseType_t xRingbufferAddToQueueSetRead(RingbufHandle_t ringbuf, QueueSetHandle_t xQueueSet);
/** /**
* @brief Add the ringbuffer to a queue set. This specifically adds the semaphore that indicates * @brief Add the ringbuffer to a queue set.
* something has been written into the ringbuffer.
* *
* @param ringbuf - Ring buffer to add to the queue set * This specifically adds the semaphore that indicates something has been
* @param xQueueSet - Queue set to add the ringbuffer to * written into the ringbuffer.
*
* @param ringbuf Ring buffer to add to the queue set
* @param xQueueSet Queue set to add the ringbuffer to
* *
* @return pdTRUE on success, pdFALSE otherwise * @return pdTRUE on success, pdFALSE otherwise
*/ */
@@ -228,11 +254,13 @@ BaseType_t xRingbufferAddToQueueSetWrite(RingbufHandle_t ringbuf, QueueSetHandle
/** /**
* @brief Remove the ringbuffer from a queue set. This specifically removes the semaphore that indicates * @brief Remove the ringbuffer from a queue set.
* more space has become available in the ringbuffer.
* *
* @param ringbuf - Ring buffer to remove from the queue set * This specifically removes the semaphore that indicates more space
* @param xQueueSet - Queue set to remove the ringbuffer from * has become available in the ringbuffer.
*
* @param ringbuf Ring buffer to remove from the queue set
* @param xQueueSet Queue set to remove the ringbuffer from
* *
* @return pdTRUE on success, pdFALSE otherwise * @return pdTRUE on success, pdFALSE otherwise
*/ */
@@ -240,11 +268,13 @@ BaseType_t xRingbufferRemoveFromQueueSetRead(RingbufHandle_t ringbuf, QueueSetHa
/** /**
* @brief Remove the ringbuffer from a queue set. This specifically removes the semaphore that indicates * @brief Remove the ringbuffer from a queue set.
* something has been written to the ringbuffer.
* *
* @param ringbuf - Ring buffer to remove from the queue set * This specifically removes the semaphore that indicates something
* @param xQueueSet - Queue set to remove the ringbuffer from * has been written to the ringbuffer.
*
* @param ringbuf Ring buffer to remove from the queue set
* @param xQueueSet Queue set to remove the ringbuffer from
* *
* @return pdTRUE on success, pdFALSE otherwise * @return pdTRUE on success, pdFALSE otherwise
*/ */
@@ -254,9 +284,7 @@ BaseType_t xRingbufferRemoveFromQueueSetWrite(RingbufHandle_t ringbuf, QueueSetH
/** /**
* @brief Debugging function to print the internal pointers in the ring buffer * @brief Debugging function to print the internal pointers in the ring buffer
* *
* @param ringbuf - Ring buffer to show * @param ringbuf Ring buffer to show
*
* @return void
*/ */
void xRingbufferPrintInfo(RingbufHandle_t ringbuf); void xRingbufferPrintInfo(RingbufHandle_t ringbuf);

876
components/freertos/include/freertos/semphr.h
View File

File diff suppressed because it is too large Load Diff

1577
components/freertos/include/freertos/task.h
View File

File diff suppressed because it is too large Load Diff

125
components/freertos/include/freertos/timers.h
View File

@@ -117,24 +117,18 @@ or interrupt version of the queue send function should be used. */
*/ */
typedef void * TimerHandle_t; typedef void * TimerHandle_t;
/* /**
* Defines the prototype to which timer callback functions must conform. * Defines the prototype to which timer callback functions must conform.
*/ */
typedef void (*TimerCallbackFunction_t)( TimerHandle_t xTimer ); typedef void (*TimerCallbackFunction_t)( TimerHandle_t xTimer );
/* /**
* Defines the prototype to which functions used with the * Defines the prototype to which functions used with the
* xTimerPendFunctionCallFromISR() function must conform. * xTimerPendFunctionCallFromISR() function must conform.
*/ */
typedef void (*PendedFunction_t)( void *, uint32_t ); typedef void (*PendedFunction_t)( void *, uint32_t );
/** /**
* TimerHandle_t xTimerCreate( const char * const pcTimerName,
* TickType_t xTimerPeriodInTicks,
* UBaseType_t uxAutoReload,
* void * pvTimerID,
* TimerCallbackFunction_t pxCallbackFunction );
*
* Creates a new software timer instance, and returns a handle by which the * Creates a new software timer instance, and returns a handle by which the
* created software timer can be referenced. * created software timer can be referenced.
* *
@@ -184,7 +178,7 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
* structures, or the timer period was set to 0) then NULL is returned. * structures, or the timer period was set to 0) then NULL is returned.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* #define NUM_TIMERS 5 * #define NUM_TIMERS 5
* *
* // An array to hold handles to the created timers. * // An array to hold handles to the created timers.
@@ -263,7 +257,7 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
* // Should not reach here. * // Should not reach here.
* for( ;; ); * for( ;; );
* } * }
* @endverbatim * @endcode
*/ */
#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
TimerHandle_t xTimerCreate( const char * const pcTimerName, TimerHandle_t xTimerCreate( const char * const pcTimerName,
@@ -274,13 +268,6 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
#endif #endif
/** /**
* TimerHandle_t xTimerCreateStatic(const char * const pcTimerName,
* TickType_t xTimerPeriodInTicks,
* UBaseType_t uxAutoReload,
* void * pvTimerID,
* TimerCallbackFunction_t pxCallbackFunction,
* StaticTimer_t *pxTimerBuffer );
*
* Creates a new software timer instance, and returns a handle by which the * Creates a new software timer instance, and returns a handle by which the
* created software timer can be referenced. * created software timer can be referenced.
* *
@@ -332,7 +319,7 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
* returned. If pxTimerBuffer was NULL then NULL is returned. * returned. If pxTimerBuffer was NULL then NULL is returned.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* *
* // The buffer used to hold the software timer's data structure. * // The buffer used to hold the software timer's data structure.
* static StaticTimer_t xTimerBuffer; * static StaticTimer_t xTimerBuffer;
@@ -393,20 +380,18 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
* // Should not reach here. * // Should not reach here.
* for( ;; ); * for( ;; );
* } * }
* @endverbatim * @endcode
*/ */
#if( configSUPPORT_STATIC_ALLOCATION == 1 ) #if( configSUPPORT_STATIC_ALLOCATION == 1 )
TimerHandle_t xTimerCreateStatic( const char * const pcTimerName, TimerHandle_t xTimerCreateStatic( const char * const pcTimerName,
const TickType_t xTimerPeriodInTicks, const TickType_t xTimerPeriodInTicks,
const UBaseType_t uxAutoReload, const UBaseType_t uxAutoReload,
void * const pvTimerID, void * const pvTimerID,
TimerCallbackFunction_t pxCallbackFunction, TimerCallbackFunction_t pxCallbackFunction,
StaticTimer_t *pxTimerBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ StaticTimer_t *pxTimerBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
#endif /* configSUPPORT_STATIC_ALLOCATION */ #endif /* configSUPPORT_STATIC_ALLOCATION */
/** /**
* void *pvTimerGetTimerID( TimerHandle_t xTimer );
*
* Returns the ID assigned to the timer. * Returns the ID assigned to the timer.
* *
* IDs are assigned to timers using the pvTimerID parameter of the call to * IDs are assigned to timers using the pvTimerID parameter of the call to
@@ -427,8 +412,6 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
void *pvTimerGetTimerID( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; void *pvTimerGetTimerID( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
/** /**
* void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );
*
* Sets the ID assigned to the timer. * Sets the ID assigned to the timer.
* *
* IDs are assigned to timers using the pvTimerID parameter of the call to * IDs are assigned to timers using the pvTimerID parameter of the call to
@@ -448,12 +431,12 @@ void *pvTimerGetTimerID( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION; void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION;
/** /**
* BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );
*
* Queries a timer to see if it is active or dormant. * Queries a timer to see if it is active or dormant.
* *
* A timer will be dormant if: * A timer will be dormant if:
*
* 1) It has been created but not started, or * 1) It has been created but not started, or
*
* 2) It is an expired one-shot timer that has not been restarted. * 2) It is an expired one-shot timer that has not been restarted.
* *
* Timers are created in the dormant state. The xTimerStart(), xTimerReset(), * Timers are created in the dormant state. The xTimerStart(), xTimerReset(),
@@ -467,7 +450,7 @@ void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION
* pdFALSE will be returned if the timer is active. * pdFALSE will be returned if the timer is active.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* // This function assumes xTimer has already been created. * // This function assumes xTimer has already been created.
* void vAFunction( TimerHandle_t xTimer ) * void vAFunction( TimerHandle_t xTimer )
* { * {
@@ -480,13 +463,11 @@ void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION
* // xTimer is not active, do something else. * // xTimer is not active, do something else.
* } * }
* } * }
* @endverbatim * @endcode
*/ */
BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
/** /**
* TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
*
* xTimerGetTimerDaemonTaskHandle() is only available if * xTimerGetTimerDaemonTaskHandle() is only available if
* INCLUDE_xTimerGetTimerDaemonTaskHandle is set to 1 in FreeRTOSConfig.h. * INCLUDE_xTimerGetTimerDaemonTaskHandle is set to 1 in FreeRTOSConfig.h.
* *
@@ -496,8 +477,6 @@ BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ); TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
/** /**
* TickType_t xTimerGetPeriod( TimerHandle_t xTimer );
*
* Returns the period of a timer. * Returns the period of a timer.
* *
* @param xTimer The handle of the timer being queried. * @param xTimer The handle of the timer being queried.
@@ -507,8 +486,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
/** /**
* TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );
*
* Returns the time in ticks at which the timer will expire. If this is less * Returns the time in ticks at which the timer will expire. If this is less
* than the current tick count then the expiry time has overflowed from the * than the current tick count then the expiry time has overflowed from the
* current time. * current time.
@@ -522,8 +499,6 @@ TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
/** /**
* BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
*
* Timer functionality is provided by a timer service/daemon task. Many of the * Timer functionality is provided by a timer service/daemon task. Many of the
* public FreeRTOS timer API functions send commands to the timer service task * public FreeRTOS timer API functions send commands to the timer service task
* through a queue called the timer command queue. The timer command queue is * through a queue called the timer command queue. The timer command queue is
@@ -574,8 +549,6 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
#define xTimerStart( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) ) #define xTimerStart( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
/** /**
* BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );
*
* Timer functionality is provided by a timer service/daemon task. Many of the * Timer functionality is provided by a timer service/daemon task. Many of the
* public FreeRTOS timer API functions send commands to the timer service task * public FreeRTOS timer API functions send commands to the timer service task
* through a queue called the timer command queue. The timer command queue is * through a queue called the timer command queue. The timer command queue is
@@ -616,10 +589,6 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
#define xTimerStop( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xTicksToWait ) ) #define xTimerStop( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xTicksToWait ) )
/** /**
* BaseType_t xTimerChangePeriod( TimerHandle_t xTimer,
* TickType_t xNewPeriod,
* TickType_t xTicksToWait );
*
* Timer functionality is provided by a timer service/daemon task. Many of the * Timer functionality is provided by a timer service/daemon task. Many of the
* public FreeRTOS timer API functions send commands to the timer service task * public FreeRTOS timer API functions send commands to the timer service task
* through a queue called the timer command queue. The timer command queue is * through a queue called the timer command queue. The timer command queue is
@@ -661,7 +630,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* configTIMER_TASK_PRIORITY configuration constant. * configTIMER_TASK_PRIORITY configuration constant.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* // This function assumes xTimer has already been created. If the timer * // This function assumes xTimer has already been created. If the timer
* // referenced by xTimer is already active when it is called, then the timer * // referenced by xTimer is already active when it is called, then the timer
* // is deleted. If the timer referenced by xTimer is not active when it is * // is deleted. If the timer referenced by xTimer is not active when it is
@@ -691,13 +660,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* } * }
* } * }
* } * }
* @endverbatim * @endcode
*/ */
#define xTimerChangePeriod( xTimer, xNewPeriod, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xTicksToWait ) ) #define xTimerChangePeriod( xTimer, xNewPeriod, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xTicksToWait ) )
/** /**
* BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );
*
* Timer functionality is provided by a timer service/daemon task. Many of the * Timer functionality is provided by a timer service/daemon task. Many of the
* public FreeRTOS timer API functions send commands to the timer service task * public FreeRTOS timer API functions send commands to the timer service task
* through a queue called the timer command queue. The timer command queue is * through a queue called the timer command queue. The timer command queue is
@@ -734,8 +701,6 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
#define xTimerDelete( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xTicksToWait ) ) #define xTimerDelete( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xTicksToWait ) )
/** /**
* BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
*
* Timer functionality is provided by a timer service/daemon task. Many of the * Timer functionality is provided by a timer service/daemon task. Many of the
* public FreeRTOS timer API functions send commands to the timer service task * public FreeRTOS timer API functions send commands to the timer service task
* through a queue called the timer command queue. The timer command queue is * through a queue called the timer command queue. The timer command queue is
@@ -781,7 +746,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* configuration constant. * configuration constant.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* // When a key is pressed, an LCD back-light is switched on. If 5 seconds pass * // When a key is pressed, an LCD back-light is switched on. If 5 seconds pass
* // without a key being pressed, then the LCD back-light is switched off. In * // without a key being pressed, then the LCD back-light is switched off. In
* // this case, the timer is a one-shot timer. * // this case, the timer is a one-shot timer.
@@ -853,14 +818,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* // Should not reach here. * // Should not reach here.
* for( ;; ); * for( ;; );
* } * }
* @endverbatim * @endcode
*/ */
#define xTimerReset( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) ) #define xTimerReset( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
/** /**
* BaseType_t xTimerStartFromISR( TimerHandle_t xTimer,
* BaseType_t *pxHigherPriorityTaskWoken );
*
* A version of xTimerStart() that can be called from an interrupt service * A version of xTimerStart() that can be called from an interrupt service
* routine. * routine.
* *
@@ -888,7 +850,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* configuration constant. * configuration constant.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* // This scenario assumes xBacklightTimer has already been created. When a * // This scenario assumes xBacklightTimer has already been created. When a
* // key is pressed, an LCD back-light is switched on. If 5 seconds pass * // key is pressed, an LCD back-light is switched on. If 5 seconds pass
* // without a key being pressed, then the LCD back-light is switched off. In * // without a key being pressed, then the LCD back-light is switched off. In
@@ -939,14 +901,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* // depends on the FreeRTOS port being used). * // depends on the FreeRTOS port being used).
* } * }
* } * }
* @endverbatim * @endcode
*/ */
#define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U ) #define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
/** /**
* BaseType_t xTimerStopFromISR( TimerHandle_t xTimer,
* BaseType_t *pxHigherPriorityTaskWoken );
*
* A version of xTimerStop() that can be called from an interrupt service * A version of xTimerStop() that can be called from an interrupt service
* routine. * routine.
* *
@@ -972,7 +931,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* priority is set by the configTIMER_TASK_PRIORITY configuration constant. * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* // This scenario assumes xTimer has already been created and started. When * // This scenario assumes xTimer has already been created and started. When
* // an interrupt occurs, the timer should be simply stopped. * // an interrupt occurs, the timer should be simply stopped.
* *
@@ -1002,15 +961,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* // depends on the FreeRTOS port being used). * // depends on the FreeRTOS port being used).
* } * }
* } * }
* @endverbatim * @endcode
*/ */
#define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U ) #define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U )
/** /**
* BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer,
* TickType_t xNewPeriod,
* BaseType_t *pxHigherPriorityTaskWoken );
*
* A version of xTimerChangePeriod() that can be called from an interrupt * A version of xTimerChangePeriod() that can be called from an interrupt
* service routine. * service routine.
* *
@@ -1045,7 +1000,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* priority is set by the configTIMER_TASK_PRIORITY configuration constant. * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* // This scenario assumes xTimer has already been created and started. When * // This scenario assumes xTimer has already been created and started. When
* // an interrupt occurs, the period of xTimer should be changed to 500ms. * // an interrupt occurs, the period of xTimer should be changed to 500ms.
* *
@@ -1075,14 +1030,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* // depends on the FreeRTOS port being used). * // depends on the FreeRTOS port being used).
* } * }
* } * }
* @endverbatim * @endcode
*/ */
#define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U ) #define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )
/** /**
* BaseType_t xTimerResetFromISR( TimerHandle_t xTimer,
* BaseType_t *pxHigherPriorityTaskWoken );
*
* A version of xTimerReset() that can be called from an interrupt service * A version of xTimerReset() that can be called from an interrupt service
* routine. * routine.
* *
@@ -1110,7 +1062,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* task priority is set by the configTIMER_TASK_PRIORITY configuration constant. * task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* // This scenario assumes xBacklightTimer has already been created. When a * // This scenario assumes xBacklightTimer has already been created. When a
* // key is pressed, an LCD back-light is switched on. If 5 seconds pass * // key is pressed, an LCD back-light is switched on. If 5 seconds pass
* // without a key being pressed, then the LCD back-light is switched off. In * // without a key being pressed, then the LCD back-light is switched off. In
@@ -1161,18 +1113,12 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* // depends on the FreeRTOS port being used). * // depends on the FreeRTOS port being used).
* } * }
* } * }
* @endverbatim * @endcode
*/ */
#define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U ) #define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
/** /**
* BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,
* void *pvParameter1,
* uint32_t ulParameter2,
* BaseType_t *pxHigherPriorityTaskWoken );
*
*
* Used from application interrupt service routines to defer the execution of a * Used from application interrupt service routines to defer the execution of a
* function to the RTOS daemon task (the timer service task, hence this function * function to the RTOS daemon task (the timer service task, hence this function
* is implemented in timers.c and is prefixed with 'Timer'). * is implemented in timers.c and is prefixed with 'Timer').
@@ -1214,7 +1160,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* timer daemon task, otherwise pdFALSE is returned. * timer daemon task, otherwise pdFALSE is returned.
* *
* Example usage: * Example usage:
* @verbatim * @code{c}
* *
* // The callback function that will execute in the context of the daemon task. * // The callback function that will execute in the context of the daemon task.
* // Note callback functions must all use this same prototype. * // Note callback functions must all use this same prototype.
@@ -1252,17 +1198,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
* portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); * portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
* *
* } * }
* @endverbatim * @endcode
*/ */
BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken ); BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken );
/** /**
* BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,
* void *pvParameter1,
* uint32_t ulParameter2,
* TickType_t xTicksToWait );
*
*
* Used to defer the execution of a function to the RTOS daemon task (the timer * Used to defer the execution of a function to the RTOS daemon task (the timer
* service task, hence this function is implemented in timers.c and is prefixed * service task, hence this function is implemented in timers.c and is prefixed
* with 'Timer'). * with 'Timer').
@@ -1291,8 +1231,6 @@ BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void
BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait ); BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait );
/** /**
* const char * const pcTimerGetTimerName( TimerHandle_t xTimer );
*
* Returns the name that was assigned to a timer when the timer was created. * Returns the name that was assigned to a timer when the timer was created.
* *
* @param xTimer The handle of the timer being queried. * @param xTimer The handle of the timer being queried.
@@ -1301,6 +1239,7 @@ BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvPar
*/ */
const char * pcTimerGetTimerName( TimerHandle_t xTimer ); /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ const char * pcTimerGetTimerName( TimerHandle_t xTimer ); /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
/** @cond */
/* /*
* Functions beyond this part are not part of the public API and are intended * Functions beyond this part are not part of the public API and are intended
* for use by the kernel only. * for use by the kernel only.
@@ -1308,6 +1247,8 @@ const char * pcTimerGetTimerName( TimerHandle_t xTimer ); /*lint !e971 Unqualifi
BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION; BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;
BaseType_t xTimerGenericCommand( TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t * const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; BaseType_t xTimerGenericCommand( TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t * const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
/** @endcond */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif

23
docs/Doxyfile
View File

@@ -153,7 +153,17 @@ INPUT = \
../components/esp32/include/esp_pm.h \ ../components/esp32/include/esp_pm.h \
../components/esp32/include/esp32/pm.h \ ../components/esp32/include/esp32/pm.h \
### esp_timer, High Resolution Timer ### esp_timer, High Resolution Timer
../components/esp32/include/esp_timer.h ../components/esp32/include/esp_timer.h \
###
### FreeRTOS
###
../components/freertos/include/freertos/task.h \
../components/freertos/include/freertos/queue.h \
../components/freertos/include/freertos/semphr.h \
../components/freertos/include/freertos/timers.h \
../components/freertos/include/freertos/event_groups.h \
../components/freertos/include/freertos/ringbuf.h
## Get warnings for functions that have no documentation for their parameters or return value ## Get warnings for functions that have no documentation for their parameters or return value
@@ -165,7 +175,16 @@ WARN_NO_PARAMDOC = YES
ENABLE_PREPROCESSING = YES ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES EXPAND_ONLY_PREDEF = YES
PREDEFINED = __attribute__(x)= PREDEFINED = \
__attribute__(x)= \
IRAM_ATTR= \
configSUPPORT_DYNAMIC_ALLOCATION=1 \
configSUPPORT_STATIC_ALLOCATION=1 \
configQUEUE_REGISTRY_SIZE=1 \
configUSE_RECURSIVE_MUTEXES=1 \
configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS=1 \
configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \
configUSE_APPLICATION_TASK_TAG=1
## Do not complain about not having dot ## Do not complain about not having dot
## ##

122
docs/api-guides/freertos-smp.rst
View File

@@ -20,8 +20,8 @@ found via http://www.freertos.org/a00106.html
port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported
to ESP-IDF. to ESP-IDF.
:ref:`tasks-and-task-creation`: Use ``xTaskCreatePinnedToCore()`` or :ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or
``xTaskCreateStaticPinnedToCore()`` to create tasks in ESP-IDF FreeRTOS. The :cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The
last parameter of the two functions is ``xCoreID``. This parameter specifies last parameter of the two functions is ``xCoreID``. This parameter specifies
which core the task is pinned to. Acceptable values are ``0`` for **PRO_CPU**, which core the task is pinned to. Acceptable values are ``0`` for **PRO_CPU**,
``1`` for **APP_CPU**, or ``tskNO_AFFINITY`` which allows the task to run on ``1`` for **APP_CPU**, or ``tskNO_AFFINITY`` which allows the task to run on
@@ -34,13 +34,13 @@ enter a blocked state, or are distributed across a wider range of priorities.
:ref:`scheduler-suspension`: Suspending the scheduler in ESP-IDF FreeRTOS will only :ref:`scheduler-suspension`: Suspending the scheduler in ESP-IDF FreeRTOS will only
affect the scheduler on the the calling core. In other words, calling affect the scheduler on the the calling core. In other words, calling
``vTaskSuspendAll()`` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and :cpp:func:`vTaskSuspendAll` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and
vice versa. Use critical sections or semaphores instead for simultaneous vice versa. Use critical sections or semaphores instead for simultaneous
access protection. access protection.
:ref:`tick-interrupt-synchronicity`: Tick interrupts of **PRO_CPU** and **APP_CPU** :ref:`tick-interrupt-synchronicity`: Tick interrupts of **PRO_CPU** and **APP_CPU**
are not synchronized. Do not expect to use ``vTaskDelay`` or are not synchronized. Do not expect to use :cpp:func:`vTaskDelay` or
``vTaskDelayUntil`` as an accurate method of synchronizing task execution :cpp:func:`vTaskDelayUntil` as an accurate method of synchronizing task execution
between the two cores. Use a counting semaphore instead as their context between the two cores. Use a counting semaphore instead as their context
switches are not tied to tick interrupts due to preemption. switches are not tied to tick interrupts due to preemption.
@@ -51,15 +51,15 @@ unaffected. If the other core attemps to take same mutex, it will spin until
the calling core has released the mutex by exiting the critical section. the calling core has released the mutex by exiting the critical section.
:ref:`floating-points`: The ESP32 supports hardware acceleration of single :ref:`floating-points`: The ESP32 supports hardware acceleration of single
precision floating point arithmetic (`float`). However the use of hardware precision floating point arithmetic (``float``). However the use of hardware
acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS. acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS.
Therefore, tasks that utilize `float` will automatically be pinned to a core if Therefore, tasks that utilize ``float`` will automatically be pinned to a core if
not done so already. Furthermore, `float` cannot be used in interrupt service not done so already. Furthermore, ``float`` cannot be used in interrupt service
routines. routines.
:ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS :ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS
v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately
when `vTaskDelete()` is called to delete a task that is not currently running when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running
and not pinned to the other core. Otherwise, freeing of task memory will still and not pinned to the other core. Otherwise, freeing of task memory will still
be delegated to the Idle Task. be delegated to the Idle Task.
@@ -67,7 +67,7 @@ be delegated to the Idle Task.
Storage Pointers (TLSP) feature. However the extra feature of Deletion Callbacks has been Storage Pointers (TLSP) feature. However the extra feature of Deletion Callbacks has been
added. Deletion callbacks are called automatically during task deletion and are added. Deletion callbacks are called automatically during task deletion and are
used to free memory pointed to by TLSP. Call used to free memory pointed to by TLSP. Call
``vTaskSetThreadLocalStoragePointerAndDelCallback()`` to set TLSP and Deletion :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback()` to set TLSP and Deletion
Callbacks. Callbacks.
:ref:`FreeRTOS Hooks<hooks_api_reference>`: Vanilla FreeRTOS Hooks were not designed for SMP. :ref:`FreeRTOS Hooks<hooks_api_reference>`: Vanilla FreeRTOS Hooks were not designed for SMP.
@@ -94,34 +94,34 @@ This feature has been backported from FreeRTOS v9.0.0 to ESP-IDF. The
in order for static allocation functions to be available. Once enabled, the in order for static allocation functions to be available. Once enabled, the
following functions can be called... following functions can be called...
- ``xTaskCreateStatic()`` See :ref:`backporting-notes` below - :cpp:func:`xTaskCreateStatic` (see :ref:`backporting-notes` below)
- ``xQueueCreateStatic()`` - :c:macro:`xQueueCreateStatic`
- ``xSemaphoreCreateBinaryStatic()`` - :c:macro:`xSemaphoreCreateBinaryStatic`
- ``xSemaphoreCreateCountingStatic()`` - :c:macro:`xSemaphoreCreateCountingStatic`
- ``xSemaphoreCreateMutexStatic()`` - :c:macro:`xSemaphoreCreateMutexStatic`
- ``xSemaphoreCreateRecursiveMutexStatic()`` - :c:macro:`xSemaphoreCreateRecursiveMutexStatic`
- ``xTimerCreateStatic()`` See :ref:`backporting-notes` below - :cpp:func:`xTimerCreateStatic` (see :ref:`backporting-notes` below)
- ``xEventGroupCreateStatic()`` - :cpp:func:`xEventGroupCreateStatic`
Other Features Other Features
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
- ``vTaskSetThreadLocalStoragePointer()`` See :ref:`backporting-notes` below - :cpp:func:`vTaskSetThreadLocalStoragePointer` (see :ref:`backporting-notes` below)
- ``pvTaskGetThreadLocalStoragePointer()`` See :ref:`backporting-notes` below - :cpp:func:`pvTaskGetThreadLocalStoragePointer` (see :ref:`backporting-notes` below)
- ``vTimerSetTimerID()`` - :cpp:func:`vTimerSetTimerID`
- ``xTimerGetPeriod()`` - :cpp:func:`xTimerGetPeriod`
- ``xTimerGetExpiryTime()`` - :cpp:func:`xTimerGetExpiryTime`
- ``pcQueueGetName()`` - :cpp:func:`pcQueueGetName`
- ``uxSemaphoreGetCount()`` - :c:macro:`uxSemaphoreGetCount`
.. _backporting-notes: .. _backporting-notes:
Backporting Notes Backporting Notes
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
**1)** ``xTaskCreateStatic`` has been made SMP compatible in a similar **1)** :cpp:func:`xTaskCreateStatic` has been made SMP compatible in a similar
fashion to ``xTaskCreate`` (see :ref:`tasks-and-task-creation`). Therefore fashion to :cpp:func:`xTaskCreate` (see :ref:`tasks-and-task-creation`). Therefore
``xTaskCreateStaticPinnedToCore()`` can also be called. :cpp:func:`xTaskCreateStaticPinnedToCore` can also be called.
**2)** Although vanilla FreeRTOS allows the Timer feature's daemon task to **2)** Although vanilla FreeRTOS allows the Timer feature's daemon task to
be statically allocated, the daemon task is always dynamically allocated in be statically allocated, the daemon task is always dynamically allocated in
@@ -130,7 +130,7 @@ defined when using statically allocated timers in ESP-IDF FreeRTOS.
**3)** The Thread Local Storage Pointer feature has been modified in ESP-IDF **3)** The Thread Local Storage Pointer feature has been modified in ESP-IDF
FreeRTOS to include Deletion Callbacks (see :ref:`deletion-callbacks`). Therefore FreeRTOS to include Deletion Callbacks (see :ref:`deletion-callbacks`). Therefore
the function ``vTaskSetThreadLocalStoragePointerAndDelCallback()`` can also be the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can also be
called. called.
@@ -142,9 +142,9 @@ Tasks and Task Creation
Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore
two new task creation functions have been added to ESP-IDF FreeRTOS by two new task creation functions have been added to ESP-IDF FreeRTOS by
appending ``PinnedToCore`` to the names of the task creation functions in appending ``PinnedToCore`` to the names of the task creation functions in
vanilla FreeRTOS. The vanilla FreeRTOS functions of ``xTaskCreate()`` vanilla FreeRTOS. The vanilla FreeRTOS functions of :cpp:func:`xTaskCreate`
and ``xTaskCreateStatic()`` have led to the addition of and :cpp:func:`xTaskCreateStatic` have led to the addition of
``xTaskCreatePinnedToCore()`` and ``xTaskCreateStaticPinnedToCore()`` in :cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` in
ESP-IDF FreeRTOS (see :ref:`backported-features`). ESP-IDF FreeRTOS (see :ref:`backported-features`).
For more details see :component_file:`freertos/task.c` For more details see :component_file:`freertos/task.c`
@@ -164,9 +164,9 @@ of 1000 bytes. It should be noted that the ``uxStackDepth`` parameter in
vanilla FreeRTOS specifies a task’s stack depth in terms of the number of vanilla FreeRTOS specifies a task’s stack depth in terms of the number of
words, whereas ESP-IDF FreeRTOS specifies the stack depth in terms of bytes. words, whereas ESP-IDF FreeRTOS specifies the stack depth in terms of bytes.
Note that the vanilla FreeRTOS functions ``xTaskCreate`` and Note that the vanilla FreeRTOS functions :cpp:func:`xTaskCreate` and
``xTaskCreateStatic`` have been macro defined in ESP-IDF FreeRTOS to call :cpp:func:`xTaskCreateStatic` have been defined in ESP-IDF FreeRTOS as inline functions which call
``xTaskCreatePinnedToCore()`` and ``xTaskCreateStaticPinnedToCore()`` :cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore`
respectively with ``tskNO_AFFINITY`` as the ``xCoreID`` value. respectively with ``tskNO_AFFINITY`` as the ``xCoreID`` value.
Each Task Control Block (TCB) in ESP-IDF stores the ``xCoreID`` as a member. Each Task Control Block (TCB) in ESP-IDF stores the ``xCoreID`` as a member.
@@ -283,18 +283,18 @@ different cores.
Scheduler Suspension Scheduler Suspension
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
In vanilla FreeRTOS, suspending the scheduler via ``vTaskSuspendAll()`` will In vanilla FreeRTOS, suspending the scheduler via :cpp:func:`vTaskSuspendAll` will
prevent calls of ``vTaskSwitchContext()`` from context switching until the prevent calls of ``vTaskSwitchContext`` from context switching until the
scheduler has been resumed with ``vTaskResumeAll()``. However servicing ISRs scheduler has been resumed with :cpp:func:`xTaskResumeAll`. However servicing ISRs
are still permitted. Therefore any changes in task states as a result from the are still permitted. Therefore any changes in task states as a result from the
current running task or ISRSs will not be executed until the scheduler is current running task or ISRSs will not be executed until the scheduler is
resumed. Scheduler suspension in vanilla FreeRTOS is a common protection method resumed. Scheduler suspension in vanilla FreeRTOS is a common protection method
against simultaneous access of data shared between tasks, whilst still allowing against simultaneous access of data shared between tasks, whilst still allowing
ISRs to be serviced. ISRs to be serviced.
In ESP-IDF FreeRTOS, ``vTaskSuspendAll()`` will only prevent calls of In ESP-IDF FreeRTOS, :cpp:func:`xTaskResumeAll` will only prevent calls of
``vTaskSwitchContext()`` from switching contexts on the core that called for the ``vTaskSwitchContext()`` from switching contexts on the core that called for the
suspension. Hence if **PRO_CPU** calls ``vTaskSuspendAll()``, **APP_CPU** will suspension. Hence if **PRO_CPU** calls :cpp:func:`vTaskSuspendAll`, **APP_CPU** will
still be able to switch contexts. If data is shared between tasks that are still be able to switch contexts. If data is shared between tasks that are
pinned to different cores, scheduler suspension is **NOT** a valid method of pinned to different cores, scheduler suspension is **NOT** a valid method of
protection against simultaneous access. Consider using critical sections protection against simultaneous access. Consider using critical sections
@@ -302,7 +302,7 @@ protection against simultaneous access. Consider using critical sections
protecting shared resources in ESP-IDF FreeRTOS. protecting shared resources in ESP-IDF FreeRTOS.
In general, it's better to use other RTOS primitives like mutex semaphores to protect In general, it's better to use other RTOS primitives like mutex semaphores to protect
against data shared between tasks, rather than ``vTaskSuspendAll()``. against data shared between tasks, rather than :cpp:func:`vTaskSuspendAll`.
.. _tick-interrupt-synchronicity: .. _tick-interrupt-synchronicity:
@@ -316,8 +316,8 @@ each core being independent, and the tick interrupts to each core being
unsynchronized. unsynchronized.
In vanilla FreeRTOS the tick interrupt triggers a call to In vanilla FreeRTOS the tick interrupt triggers a call to
``xTaskIncrementTick()`` which is responsible for incrementing the tick :cpp:func:`xTaskIncrementTick` which is responsible for incrementing the tick
counter, checking if tasks which have called ``vTaskDelay()`` have fulfilled counter, checking if tasks which have called :cpp:func:`vTaskDelay` have fulfilled
their delay period, and moving those tasks from the Delayed Task List to the their delay period, and moving those tasks from the Delayed Task List to the
Ready Task List. The tick interrupt will then call the scheduler if a context Ready Task List. The tick interrupt will then call the scheduler if a context
switch is necessary. switch is necessary.
@@ -372,11 +372,11 @@ The ESP-IDF FreeRTOS critical section functions have been modified as follows…
- ``taskENTER_CRITICAL(mux)``, ``taskENTER_CRITICAL_ISR(mux)``, - ``taskENTER_CRITICAL(mux)``, ``taskENTER_CRITICAL_ISR(mux)``,
``portENTER_CRITICAL(mux)``, ``portENTER_CRITICAL_ISR(mux)`` are all macro ``portENTER_CRITICAL(mux)``, ``portENTER_CRITICAL_ISR(mux)`` are all macro
defined to call ``vTaskEnterCritical()`` defined to call :cpp:func:`vTaskEnterCritical`
- ``taskEXIT_CRITICAL(mux)``, ``taskEXIT_CRITICAL_ISR(mux)``, - ``taskEXIT_CRITICAL(mux)``, ``taskEXIT_CRITICAL_ISR(mux)``,
``portEXIT_CRITICAL(mux)``, ``portEXIT_CRITICAL_ISR(mux)`` are all macro ``portEXIT_CRITICAL(mux)``, ``portEXIT_CRITICAL_ISR(mux)`` are all macro
defined to call ``vTaskExitCritical()`` defined to call :cpp:func:`vTaskExitCritical`
For more details see :component_file:`freertos/include/freertos/portmacro.h` For more details see :component_file:`freertos/include/freertos/portmacro.h`
and :component_file:`freertos/task.c` and :component_file:`freertos/task.c`
@@ -394,23 +394,23 @@ Floating Point Aritmetic
------------------------ ------------------------
The ESP32 supports hardware acceleration of single precision floating point The ESP32 supports hardware acceleration of single precision floating point
arithmetic (`float`) via Floating Point Units (FPU, also known as coprocessors) arithmetic (``float``) via Floating Point Units (FPU, also known as coprocessors)
attached to each core. The use of the FPUs imposes some behavioral restrictions attached to each core. The use of the FPUs imposes some behavioral restrictions
on ESP-IDF FreeRTOS. on ESP-IDF FreeRTOS.
ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words, ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words,
the state of a core's FPU registers are not immediately saved when a context the state of a core's FPU registers are not immediately saved when a context
switch occurs. Therefore, tasks that utilize `float` must be pinned to a switch occurs. Therefore, tasks that utilize ``float`` must be pinned to a
particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin
the task in question to whichever core the task was running on upon the task's the task in question to whichever core the task was running on upon the task's
first use of `float`. Likewise due to Lazy Context Switching, interrupt service first use of ``float``. Likewise due to Lazy Context Switching, interrupt service
routines must also not use `float`. routines must also not use ``float``.
ESP32 does not support hardware acceleration for double precision floating point ESP32 does not support hardware acceleration for double precision floating point
arithmetic (`double`). Instead `double` is implemented via software hence the arithmetic (``double``). Instead ``double`` is implemented via software hence the
behavioral restrictions with regards to `float` do not apply to `double`. Note behavioral restrictions with regards to ``float`` do not apply to ``double``. Note
that due to the lack of hardware acceleration, `double` operations may consume that due to the lack of hardware acceleration, ``double`` operations may consume
significantly larger amount of CPU time in comparison to `float`. significantly larger amount of CPU time in comparison to ``float``.
.. _task-deletion: .. _task-deletion:
@@ -420,12 +420,12 @@ Task Deletion
FreeRTOS task deletion prior to v9.0.0 delegated the freeing of task memory FreeRTOS task deletion prior to v9.0.0 delegated the freeing of task memory
entirely to the Idle Task. Currently, the freeing of task memory will occur entirely to the Idle Task. Currently, the freeing of task memory will occur
immediately (within `vTaskDelete()`) if the task being deleted is not currently immediately (within :cpp:func:`vTaskDelete`) if the task being deleted is not currently
running or is not pinned to the other core (with respect to the core running or is not pinned to the other core (with respect to the core
`vTaskDelete()` is called on). TLSP deletion callbacks will also run immediately :cpp:func:`vTaskDelete` is called on). TLSP deletion callbacks will also run immediately
if the same conditions are met. if the same conditions are met.
However, calling `vTaskDelete()` to delete a task that is either currently However, calling :cpp:func:`vTaskDelete` to delete a task that is either currently
running or pinned to the other core will still result in the freeing of memory running or pinned to the other core will still result in the freeing of memory
being delegated to the Idle Task. being delegated to the Idle Task.
@@ -456,8 +456,8 @@ is the index number of the associated TLSP, and the second parameter is the
TLSP itself. TLSP itself.
Deletion callbacks are set alongside TLSP by calling Deletion callbacks are set alongside TLSP by calling
``vTaskSetThreadLocalStoragePointerAndDelCallback()``. Calling the vanilla :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`. Calling the vanilla
FreeRTOS function ``vTaskSetThreadLocalStoragePointer()`` will simply set the FreeRTOS function :cpp:func:`vTaskSetThreadLocalStoragePointer` will simply set the
TLSP's associated Deletion Callback to `NULL` meaning that no callback will be TLSP's associated Deletion Callback to `NULL` meaning that no callback will be
called for that TLSP during task deletion. If a deletion callback is `NULL`, called for that TLSP during task deletion. If a deletion callback is `NULL`,
users should manually free the memory pointed to by the associated TLSP before users should manually free the memory pointed to by the associated TLSP before
@@ -466,7 +466,7 @@ task deletion in order to avoid memory leak.
:ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` in menuconfig can be used :ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` in menuconfig can be used
to configure the number TLSP and Deletion Callbacks a TCB will have. to configure the number TLSP and Deletion Callbacks a TCB will have.
For more details see :component_file:`freertos/include/freertos/task.h` For more details see :doc:`FreeRTOS API reference<../api-reference/system/freertos>`.
.. _esp-idf-freertos-configuration: .. _esp-idf-freertos-configuration:
@@ -491,9 +491,9 @@ number of Thread Local Storage Pointers each task will have in ESP-IDF
FreeRTOS. FreeRTOS.
:ref:`CONFIG_SUPPORT_STATIC_ALLOCATION` will enable the backported :ref:`CONFIG_SUPPORT_STATIC_ALLOCATION` will enable the backported
functionality of ``xTaskCreateStaticPinnedToCore()`` in ESP-IDF FreeRTOS functionality of :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS
:ref:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in :ref:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in
particular functions in ESP-IDF FreeRTOS which have not been fully tested particular functions in ESP-IDF FreeRTOS which have not been fully tested
in an SMP context. in an SMP context.

42
docs/api-reference/system/freertos.rst Normal file
View File

@@ -0,0 +1,42 @@
FreeRTOS
========
Overview
--------
This section contains documentation of FreeRTOS types, functions, and macros. It is automatically generated from FreeRTOS header files.
For more information about FreeRTOS features specific to ESP-IDF, see :doc:`ESP-IDF FreeRTOS SMP Changes<../../api-guides/freertos-smp>`.
Task API
--------
.. include:: /_build/inc/task.inc
Queue API
---------
.. include:: /_build/inc/queue.inc
Semaphore API
-------------
.. include:: /_build/inc/semphr.inc
Timer API
---------
.. include:: /_build/inc/timers.inc
Event Group API
---------------
.. include:: /_build/inc/event_groups.inc
Ringbuffer API
--------------
.. include:: /_build/inc/ringbuf.inc

4
docs/api-reference/system/hooks.rst
View File

@@ -1,7 +1,7 @@
.. _hooks_api_reference: .. _hooks_api_reference:
ESP-IDF FreeRTOS Hooks FreeRTOS Hooks
====================== ==============
Overview Overview
-------- --------

11
docs/api-reference/system/index.rst
View File

@@ -4,19 +4,20 @@ System API
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
FreeRTOS <freertos>
FreeRTOS Hooks <hooks>
Heap Memory Allocation <mem_alloc> Heap Memory Allocation <mem_alloc>
Heap Memory Debugging <heap_debug> Heap Memory Debugging <heap_debug>
Interrupt Allocation <intr_alloc> Interrupt Allocation <intr_alloc>
Watchdogs <wdts> Watchdogs <wdts>
Hooks <hooks>
Inter-Processor Call <ipc> Inter-Processor Call <ipc>
High Resolution Timer <esp_timer> High Resolution Timer <esp_timer>
Over The Air Updates (OTA) <ota>
Sleep Modes <sleep_modes>
Power Management <power_management>
Logging <log> Logging <log>
Base MAC address <base_mac_address>
Application Level Tracing <app_trace> Application Level Tracing <app_trace>
Power Management <power_management>
Sleep Modes <sleep_modes>
Base MAC address <base_mac_address>
Over The Air Updates (OTA) <ota>
Example code for this API section is provided in :example:`system` directory of ESP-IDF examples. Example code for this API section is provided in :example:`system` directory of ESP-IDF examples.