diff --git a/components/freertos/FreeRTOS-Kernel/idf_changes.md b/components/freertos/FreeRTOS-Kernel/idf_changes.md index 0047a70e14..752d8fbbcd 100644 --- a/components/freertos/FreeRTOS-Kernel/idf_changes.md +++ b/components/freertos/FreeRTOS-Kernel/idf_changes.md @@ -147,3 +147,49 @@ List of differences between Vanilla FreeRTOS V10.5.1 and building the dual-core - Extended critical section so that SMP can check for yields while still inside critical section - `vTaskStepTick()` - Extended critical section so that SMP can access `xTickCount` while still inside critical section + +## Header File & Doxygen Changes + +List of changes made to Vanilla FreeRTOS V10.5.1 header files to allow for building in ESP-IDF documentation build system. + +- Removed leading header name line (e.g., `xxx.h`) in doxygen comment blocks. For example: + + ```c + /** + * xxx.h + * + * Documentation from some func + */ + void some_func(void); + ``` + +- Removed leading `@code{c}` blocks in containing redundant function prototypes. For example: + + ```c + /** + * @code{c} + * void some_func(int var_a, int var_b); + * @endcode + * + * Documentation from some func + */ + void some_func(int var_a, int var_b); + ``` + +- Added `/** @cond !DOC_EXCLUDE_HEADER_SECTION */` and `/** @endcond */` labels to exclude various doxygen sections from being included into documentation builds. These excluded sections include: + - In doxygen blocks that describe multiple related set of functions/macros, only the function/macro that matches the doxygen blocks parameters is included. For example: + ```c + /** + * Description that covers both some_func() and some_func_extra() + * + * @param var_a var_a description + * @param var_b var_b description + */ + /** @cond !DOC_EXCLUDE_HEADER_SECTION */ + #define some_func(var_a) #define some_func_generic(var_a, NULL) + /** @endcond */ + #define some_func_extra(var_a, var_b) #define some_func_generic(var_a, var_b) + ``` + - In functions/macros that are not meant to be directly called by users (i.e., internal), such as the various `Generic` variants of functions + +- Some types/functions/macros are manually documented, thus are documented with regular comment blocks (i.e., `/* */`) instead of doxygen comment blocks (i.e., `/** */`). Some of these blocks are changed into doxygen blocks. diff --git a/components/freertos/FreeRTOS-Kernel/include/freertos/event_groups.h b/components/freertos/FreeRTOS-Kernel/include/freertos/event_groups.h index 1f5d6e76d9..e676da7a1e 100644 --- a/components/freertos/FreeRTOS-Kernel/include/freertos/event_groups.h +++ b/components/freertos/FreeRTOS-Kernel/include/freertos/event_groups.h @@ -74,13 +74,11 @@ /** - * event_groups.h * * Type by which event groups are referenced. For example, a call to * xEventGroupCreate() returns an EventGroupHandle_t variable that can then * be used as a parameter to other event group functions. * - * \defgroup EventGroupHandle_t EventGroupHandle_t * \ingroup EventGroup */ struct EventGroupDef_t; @@ -91,16 +89,11 @@ typedef struct EventGroupDef_t * EventGroupHandle_t; * number of bits it holds is set by configUSE_16_BIT_TICKS (16 bits if set to 1, * 32 bits if set to 0. * - * \defgroup EventBits_t EventBits_t * \ingroup EventGroup */ typedef TickType_t EventBits_t; /** - * event_groups.h - * @code{c} - * EventGroupHandle_t xEventGroupCreate( void ); - * @endcode * * Create a new event group. * @@ -145,7 +138,6 @@ typedef TickType_t EventBits_t; * // The event group was created. * } * @endcode - * \defgroup xEventGroupCreate xEventGroupCreate * \ingroup EventGroup */ #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) @@ -153,10 +145,6 @@ typedef TickType_t EventBits_t; #endif /** - * event_groups.h - * @code{c} - * EventGroupHandle_t xEventGroupCreateStatic( EventGroupHandle_t * pxEventGroupBuffer ); - * @endcode * * Create a new event group. * @@ -206,14 +194,6 @@ typedef TickType_t EventBits_t; #endif /** - * event_groups.h - * @code{c} - * EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, - * const EventBits_t uxBitsToWaitFor, - * const BaseType_t xClearOnExit, - * const BaseType_t xWaitForAllBits, - * const TickType_t xTicksToWait ); - * @endcode * * [Potentially] block to wait for one or more bits to be set within a * previously created event group. @@ -295,7 +275,6 @@ typedef TickType_t EventBits_t; * } * } * @endcode - * \defgroup xEventGroupWaitBits xEventGroupWaitBits * \ingroup EventGroup */ EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, @@ -305,10 +284,6 @@ EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; /** - * event_groups.h - * @code{c} - * EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear ); - * @endcode * * Clear bits within an event group. This function cannot be called from an * interrupt. @@ -356,17 +331,12 @@ EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, * } * } * @endcode - * \defgroup xEventGroupClearBits xEventGroupClearBits * \ingroup EventGroup */ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION; /** - * event_groups.h - * @code{c} - * BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet ); - * @endcode * * A version of xEventGroupClearBits() that can be called from an interrupt. * @@ -419,7 +389,6 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, * } * } * @endcode - * \defgroup xEventGroupClearBitsFromISR xEventGroupClearBitsFromISR * \ingroup EventGroup */ #if ( configUSE_TRACE_FACILITY == 1 ) @@ -431,10 +400,6 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, #endif /** - * event_groups.h - * @code{c} - * EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet ); - * @endcode * * Set bits within an event group. * This function cannot be called from an interrupt. xEventGroupSetBitsFromISR() @@ -499,17 +464,12 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, * } * } * @endcode - * \defgroup xEventGroupSetBits xEventGroupSetBits * \ingroup EventGroup */ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet ) PRIVILEGED_FUNCTION; /** - * event_groups.h - * @code{c} - * BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * A version of xEventGroupSetBits() that can be called from an interrupt. * @@ -574,7 +534,6 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, * } * } * @endcode - * \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR * \ingroup EventGroup */ #if ( configUSE_TRACE_FACILITY == 1 ) @@ -587,13 +546,6 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, #endif /** - * event_groups.h - * @code{c} - * EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, - * const EventBits_t uxBitsToSet, - * const EventBits_t uxBitsToWaitFor, - * TickType_t xTicksToWait ); - * @endcode * * 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 @@ -707,7 +659,6 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, * } * * @endcode - * \defgroup xEventGroupSync xEventGroupSync * \ingroup EventGroup */ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, @@ -717,10 +668,6 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, /** - * event_groups.h - * @code{c} - * EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup ); - * @endcode * * Returns the current value of the bits in an event group. This function * cannot be used from an interrupt. @@ -729,16 +676,11 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, * * @return The event group bits at the time xEventGroupGetBits() was called. * - * \defgroup xEventGroupGetBits xEventGroupGetBits * \ingroup EventGroup */ #define xEventGroupGetBits( xEventGroup ) xEventGroupClearBits( ( xEventGroup ), 0 ) /** - * event_groups.h - * @code{c} - * EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ); - * @endcode * * A version of xEventGroupGetBits() that can be called from an ISR. * @@ -746,16 +688,11 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, * * @return The event group bits at the time xEventGroupGetBitsFromISR() was called. * - * \defgroup xEventGroupGetBitsFromISR xEventGroupGetBitsFromISR * \ingroup EventGroup */ EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION; /** - * event_groups.h - * @code{c} - * void xEventGroupDelete( EventGroupHandle_t xEventGroup ); - * @endcode * * Delete an event group that was previously created by a call to * xEventGroupCreate(). Tasks that are blocked on the event group will be @@ -766,11 +703,6 @@ EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ) PRIVILEG void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION; /** - * event_groups.h - * @code{c} - * BaseType_t xEventGroupGetStaticBuffer( EventGroupHandle_t xEventGroup, - * StaticEventGroup_t ** ppxEventGroupBuffer ); - * @endcode * * Retrieve a pointer to a statically created event groups's data structure * buffer. It is the same buffer that is supplied at the time of creation. @@ -787,6 +719,8 @@ void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION; StaticEventGroup_t ** ppxEventGroupBuffer ) PRIVILEGED_FUNCTION; #endif /* configSUPPORT_STATIC_ALLOCATION */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* For internal use only. */ void vEventGroupSetBitsCallback( void * pvEventGroup, const uint32_t ulBitsToSet ) PRIVILEGED_FUNCTION; @@ -800,6 +734,8 @@ void vEventGroupClearBitsCallback( void * pvEventGroup, UBaseType_t uxEventGroupNumber ) PRIVILEGED_FUNCTION; #endif +/** @endcond */ + /* *INDENT-OFF* */ #ifdef __cplusplus } diff --git a/components/freertos/FreeRTOS-Kernel/include/freertos/message_buffer.h b/components/freertos/FreeRTOS-Kernel/include/freertos/message_buffer.h index 68bc132414..269e1f7a1e 100644 --- a/components/freertos/FreeRTOS-Kernel/include/freertos/message_buffer.h +++ b/components/freertos/FreeRTOS-Kernel/include/freertos/message_buffer.h @@ -92,11 +92,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; /*-----------------------------------------------------------*/ /** - * message_buffer.h - * - * @code{c} - * MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes ); - * @endcode * * Creates a new message buffer using dynamically allocated memory. See * xMessageBufferCreateStatic() for a version that uses statically allocated @@ -156,25 +151,18 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * } * * @endcode - * \defgroup xMessageBufferCreate xMessageBufferCreate * \ingroup MessageBufferManagement */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ #define xMessageBufferCreate( xBufferSizeBytes ) \ xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( size_t ) 0, pdTRUE, NULL, NULL ) - +/** @endcond */ #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) #define xMessageBufferCreateWithCallback( xBufferSizeBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( size_t ) 0, pdTRUE, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) #endif /** - * message_buffer.h - * - * @code{c} - * MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes, - * uint8_t *pucMessageBufferStorageArea, - * StaticMessageBuffer_t *pxStaticMessageBuffer ); - * @endcode * Creates a new message buffer using statically allocated memory. See * xMessageBufferCreate() for a version that uses dynamically allocated memory. * @@ -213,7 +201,7 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * * // Used to dimension the array used to hold the messages. The available space * // will actually be one less than this, so 999. - #define STORAGE_SIZE_BYTES 1000 + * #define STORAGE_SIZE_BYTES 1000 * * // Defines the memory that will actually hold the messages within the message * // buffer. @@ -238,25 +226,18 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * } * * @endcode - * \defgroup xMessageBufferCreateStatic xMessageBufferCreateStatic * \ingroup MessageBufferManagement */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ #define xMessageBufferCreateStatic( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer ) \ xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), 0, pdTRUE, ( pucMessageBufferStorageArea ), ( pxStaticMessageBuffer ), NULL, NULL ) - +/** @endcond */ #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) #define xMessageBufferCreateStaticWithCallback( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), 0, pdTRUE, ( pucMessageBufferStorageArea ), ( pxStaticMessageBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) #endif /** - * message_buffer.h - * - * @code{c} - * BaseType_t xMessageBufferGetStaticBuffers( MessageBufferHandle_t xMessageBuffer, - * uint8_t ** ppucMessageBufferStorageArea, - * StaticMessageBuffer_t ** ppxStaticMessageBuffer ); - * @endcode * * Retrieve pointers to a statically created message buffer's data structure * buffer and storage area buffer. These are the same buffers that are supplied @@ -272,7 +253,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * * @return pdTRUE if buffers were retrieved, pdFALSE otherwise. * - * \defgroup xMessageBufferGetStaticBuffers xMessageBufferGetStaticBuffers * \ingroup MessageBufferManagement */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) @@ -281,14 +261,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * message_buffer.h - * - * @code{c} - * size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer, - * const void *pvTxData, - * size_t xDataLengthBytes, - * TickType_t xTicksToWait ); - * @endcode * * Sends a discrete message to the message buffer. The message can be any * length that fits within the buffer's free space, and is copied into the @@ -374,21 +346,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * } * } * @endcode - * \defgroup xMessageBufferSend xMessageBufferSend * \ingroup MessageBufferManagement */ #define xMessageBufferSend( xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait ) \ xStreamBufferSend( ( xMessageBuffer ), ( pvTxData ), ( xDataLengthBytes ), ( xTicksToWait ) ) /** - * message_buffer.h - * - * @code{c} - * size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer, - * const void *pvTxData, - * size_t xDataLengthBytes, - * BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * Interrupt safe version of the API function that sends a discrete message to * the message buffer. The message can be any length that fits within the @@ -479,21 +442,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); * } * @endcode - * \defgroup xMessageBufferSendFromISR xMessageBufferSendFromISR * \ingroup MessageBufferManagement */ #define xMessageBufferSendFromISR( xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken ) \ xStreamBufferSendFromISR( ( xMessageBuffer ), ( pvTxData ), ( xDataLengthBytes ), ( pxHigherPriorityTaskWoken ) ) /** - * message_buffer.h - * - * @code{c} - * size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer, - * void *pvRxData, - * size_t xBufferLengthBytes, - * TickType_t xTicksToWait ); - * @endcode * * Receives a discrete message from a message buffer. Messages can be of * variable length and are copied out of the buffer. @@ -568,7 +522,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * } * } * @endcode - * \defgroup xMessageBufferReceive xMessageBufferReceive * \ingroup MessageBufferManagement */ #define xMessageBufferReceive( xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait ) \ @@ -576,14 +529,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; /** - * message_buffer.h - * - * @code{c} - * size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer, - * void *pvRxData, - * size_t xBufferLengthBytes, - * BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * An interrupt safe version of the API function that receives a discrete * message from a message buffer. Messages can be of variable length and are @@ -670,18 +615,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); * } * @endcode - * \defgroup xMessageBufferReceiveFromISR xMessageBufferReceiveFromISR * \ingroup MessageBufferManagement */ #define xMessageBufferReceiveFromISR( xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken ) \ xStreamBufferReceiveFromISR( ( xMessageBuffer ), ( pvRxData ), ( xBufferLengthBytes ), ( pxHigherPriorityTaskWoken ) ) /** - * message_buffer.h - * - * @code{c} - * void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer ); - * @endcode * * Deletes a message buffer that was previously created using a call to * xMessageBufferCreate() or xMessageBufferCreateStatic(). If the message @@ -698,10 +637,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; vStreamBufferDelete( xMessageBuffer ) /** - * message_buffer.h - * @code{c} - * BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer ); - * @endcode * * Tests to see if a message buffer is full. A message buffer is full if it * cannot accept any more messages, of any size, until space is made available @@ -716,10 +651,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; xStreamBufferIsFull( xMessageBuffer ) /** - * message_buffer.h - * @code{c} - * BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer ); - * @endcode * * Tests to see if a message buffer is empty (does not contain any messages). * @@ -733,10 +664,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; xStreamBufferIsEmpty( xMessageBuffer ) /** - * message_buffer.h - * @code{c} - * BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer ); - * @endcode * * Resets a message buffer to its initial empty state, discarding any message it * contained. @@ -750,7 +677,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * the message queue to wait for space to become available, or to wait for a * a message to be available, then pdFAIL is returned. * - * \defgroup xMessageBufferReset xMessageBufferReset * \ingroup MessageBufferManagement */ #define xMessageBufferReset( xMessageBuffer ) \ @@ -773,7 +699,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * architecture, so if xMessageBufferSpacesAvailable() returns 10, then the size * of the largest message that can be written to the message buffer is 6 bytes. * - * \defgroup xMessageBufferSpaceAvailable xMessageBufferSpaceAvailable * \ingroup MessageBufferManagement */ #define xMessageBufferSpaceAvailable( xMessageBuffer ) \ @@ -782,10 +707,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; xStreamBufferSpacesAvailable( xMessageBuffer ) /* Corrects typo in original macro name. */ /** - * message_buffer.h - * @code{c} - * size_t xMessageBufferNextLengthBytes( MessageBufferHandle_t xMessageBuffer ); - * @endcode * Returns the length (in bytes) of the next message in a message buffer. * Useful if xMessageBufferReceive() returned 0 because the size of the buffer * passed into xMessageBufferReceive() was too small to hold the next message. @@ -795,18 +716,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * @return The length (in bytes) of the next message in the message buffer, or 0 * if the message buffer is empty. * - * \defgroup xMessageBufferNextLengthBytes xMessageBufferNextLengthBytes * \ingroup MessageBufferManagement */ #define xMessageBufferNextLengthBytes( xMessageBuffer ) \ xStreamBufferNextMessageLengthBytes( xMessageBuffer ) PRIVILEGED_FUNCTION; /** - * message_buffer.h - * - * @code{c} - * BaseType_t xMessageBufferSendCompletedFromISR( MessageBufferHandle_t xMessageBuffer, BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * For advanced users only. * @@ -835,18 +750,12 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * @return If a task was removed from the Blocked state then pdTRUE is returned. * Otherwise pdFALSE is returned. * - * \defgroup xMessageBufferSendCompletedFromISR xMessageBufferSendCompletedFromISR * \ingroup StreamBufferManagement */ #define xMessageBufferSendCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) \ xStreamBufferSendCompletedFromISR( ( xMessageBuffer ), ( pxHigherPriorityTaskWoken ) ) /** - * message_buffer.h - * - * @code{c} - * BaseType_t xMessageBufferReceiveCompletedFromISR( MessageBufferHandle_t xMessageBuffer, BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * For advanced users only. * @@ -876,7 +785,6 @@ typedef StreamBufferHandle_t MessageBufferHandle_t; * @return If a task was removed from the Blocked state then pdTRUE is returned. * Otherwise pdFALSE is returned. * - * \defgroup xMessageBufferReceiveCompletedFromISR xMessageBufferReceiveCompletedFromISR * \ingroup StreamBufferManagement */ #define xMessageBufferReceiveCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) \ diff --git a/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h b/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h index d7468a121e..4c975649ab 100644 --- a/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h +++ b/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h @@ -68,6 +68,8 @@ typedef struct QueueDefinition * QueueSetHandle_t; */ typedef struct QueueDefinition * QueueSetMemberHandle_t; +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* For internal use only. */ #define queueSEND_TO_BACK ( ( BaseType_t ) 0 ) #define queueSEND_TO_FRONT ( ( BaseType_t ) 1 ) @@ -81,14 +83,9 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; #define queueQUEUE_TYPE_BINARY_SEMAPHORE ( ( uint8_t ) 3U ) #define queueQUEUE_TYPE_RECURSIVE_MUTEX ( ( uint8_t ) 4U ) +/** @endcond */ + /** - * queue. h - * @code{c} - * QueueHandle_t xQueueCreate( - * UBaseType_t uxQueueLength, - * UBaseType_t uxItemSize - * ); - * @endcode * * Creates a new queue instance, and returns a handle by which the new queue * can be referenced. @@ -146,7 +143,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * // ... Rest of task code. * } * @endcode - * \defgroup xQueueCreate xQueueCreate * \ingroup QueueManagement */ #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) @@ -154,15 +150,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; #endif /** - * queue. h - * @code{c} - * QueueHandle_t xQueueCreateStatic( - * UBaseType_t uxQueueLength, - * UBaseType_t uxItemSize, - * uint8_t *pucQueueStorage, - * StaticQueue_t *pxQueueBuffer - * ); - * @endcode * * Creates a new queue instance, and returns a handle by which the new queue * can be referenced. @@ -206,8 +193,8 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * char ucData[ 20 ]; * }; * - #define QUEUE_LENGTH 10 - #define ITEM_SIZE sizeof( uint32_t ) + * #define QUEUE_LENGTH 10 + * #define ITEM_SIZE sizeof( uint32_t ) * * // xQueueBuffer will hold the queue structure. * StaticQueue_t xQueueBuffer; @@ -232,7 +219,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * // ... Rest of task code. * } * @endcode - * \defgroup xQueueCreateStatic xQueueCreateStatic * \ingroup QueueManagement */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) @@ -240,12 +226,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * queue. h - * @code{c} - * BaseType_t xQueueGetStaticBuffers( QueueHandle_t xQueue, - * uint8_t ** ppucQueueStorage, - * StaticQueue_t ** ppxStaticQueue ); - * @endcode * * Retrieve pointers to a statically created queue's data structure buffer * and storage area buffer. These are the same buffers that are supplied @@ -261,7 +241,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * * @return pdTRUE if buffers were retrieved, pdFALSE otherwise. * - * \defgroup xQueueGetStaticBuffers xQueueGetStaticBuffers * \ingroup QueueManagement */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) @@ -269,14 +248,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * queue. h - * @code{c} - * BaseType_t xQueueSendToToFront( - * QueueHandle_t xQueue, - * const void *pvItemToQueue, - * TickType_t xTicksToWait - * ); - * @endcode * * Post an item to the front of a queue. The item is queued by copy, not by * reference. This function must not be called from an interrupt service @@ -343,21 +314,12 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * // ... Rest of task code. * } * @endcode - * \defgroup xQueueSend xQueueSend * \ingroup QueueManagement */ #define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) \ xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_FRONT ) /** - * queue. h - * @code{c} - * BaseType_t xQueueSendToBack( - * QueueHandle_t xQueue, - * const void *pvItemToQueue, - * TickType_t xTicksToWait - * ); - * @endcode * * This is a macro that calls xQueueGenericSend(). * @@ -426,21 +388,12 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * // ... Rest of task code. * } * @endcode - * \defgroup xQueueSend xQueueSend * \ingroup QueueManagement */ #define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) \ xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK ) /** - * queue. h - * @code{c} - * BaseType_t xQueueSend( - * QueueHandle_t xQueue, - * const void * pvItemToQueue, - * TickType_t xTicksToWait - * ); - * @endcode * * This is a macro that calls xQueueGenericSend(). It is included for * backward compatibility with versions of FreeRTOS.org that did not @@ -511,20 +464,12 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * // ... Rest of task code. * } * @endcode - * \defgroup xQueueSend xQueueSend * \ingroup QueueManagement */ #define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) \ xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK ) /** - * queue. h - * @code{c} - * BaseType_t xQueueOverwrite( - * QueueHandle_t xQueue, - * const void * pvItemToQueue - * ); - * @endcode * * Only for use with queues that have a length of one - so the queue is either * empty or full. @@ -595,7 +540,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * // ... * } * @endcode - * \defgroup xQueueOverwrite xQueueOverwrite * \ingroup QueueManagement */ #define xQueueOverwrite( xQueue, pvItemToQueue ) \ @@ -603,15 +547,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; /** - * queue. h - * @code{c} - * BaseType_t xQueueGenericSend( - * QueueHandle_t xQueue, - * const void * pvItemToQueue, - * TickType_t xTicksToWait - * BaseType_t xCopyPosition - * ); - * @endcode * * It is preferred that the macros xQueueSend(), xQueueSendToFront() and * xQueueSendToBack() are used in place of calling this function directly. @@ -684,7 +619,6 @@ typedef struct QueueDefinition * QueueSetMemberHandle_t; * // ... Rest of task code. * } * @endcode - * \defgroup xQueueSend xQueueSend * \ingroup QueueManagement */ BaseType_t xQueueGenericSend( QueueHandle_t xQueue, @@ -693,14 +627,6 @@ BaseType_t xQueueGenericSend( QueueHandle_t xQueue, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * BaseType_t xQueuePeek( - * QueueHandle_t xQueue, - * void * const pvBuffer, - * TickType_t xTicksToWait - * ); - * @endcode * * Receive an item from a queue without removing the item from the queue. * The item is received by copy so a buffer of adequate size must be @@ -782,7 +708,6 @@ BaseType_t xQueueGenericSend( QueueHandle_t xQueue, * // ... Rest of task code. * } * @endcode - * \defgroup xQueuePeek xQueuePeek * \ingroup QueueManagement */ BaseType_t xQueuePeek( QueueHandle_t xQueue, @@ -790,13 +715,6 @@ BaseType_t xQueuePeek( QueueHandle_t xQueue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * BaseType_t xQueuePeekFromISR( - * QueueHandle_t xQueue, - * void *pvBuffer, - * ); - * @endcode * * A version of xQueuePeek() that can be called from an interrupt service * routine (ISR). @@ -818,21 +736,12 @@ BaseType_t xQueuePeek( QueueHandle_t xQueue, * @return pdTRUE if an item was successfully received from the queue, * otherwise pdFALSE. * - * \defgroup xQueuePeekFromISR xQueuePeekFromISR * \ingroup QueueManagement */ BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue, void * const pvBuffer ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * BaseType_t xQueueReceive( - * QueueHandle_t xQueue, - * void *pvBuffer, - * TickType_t xTicksToWait - * ); - * @endcode * * Receive an item from a queue. The item is received by copy so a buffer of * adequate size must be provided. The number of bytes copied into the buffer @@ -911,7 +820,6 @@ BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue, * // ... Rest of task code. * } * @endcode - * \defgroup xQueueReceive xQueueReceive * \ingroup QueueManagement */ BaseType_t xQueueReceive( QueueHandle_t xQueue, @@ -919,10 +827,6 @@ BaseType_t xQueueReceive( QueueHandle_t xQueue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue ); - * @endcode * * Return the number of messages stored in a queue. * @@ -930,16 +834,11 @@ BaseType_t xQueueReceive( QueueHandle_t xQueue, * * @return The number of messages available in the queue. * - * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting * \ingroup QueueManagement */ UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue ); - * @endcode * * Return the number of free spaces available in a queue. This is equal to the * number of items that can be sent to the queue before the queue becomes full @@ -949,36 +848,22 @@ UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue ) PRIVILEGED_FUNC * * @return The number of spaces available in the queue. * - * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting * \ingroup QueueManagement */ UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * void vQueueDelete( QueueHandle_t xQueue ); - * @endcode * * Delete a queue - freeing all the memory allocated for storing of items * placed on the queue. * * @param xQueue A handle to the queue to be deleted. * - * \defgroup vQueueDelete vQueueDelete * \ingroup QueueManagement */ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * BaseType_t xQueueSendToFrontFromISR( - * QueueHandle_t xQueue, - * const void *pvItemToQueue, - * BaseType_t *pxHigherPriorityTaskWoken - * ); - * @endcode * * This is a macro that calls xQueueGenericSendFromISR(). * @@ -1035,7 +920,6 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; * } * @endcode * - * \defgroup xQueueSendFromISR xQueueSendFromISR * \ingroup QueueManagement */ #define xQueueSendToFrontFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \ @@ -1043,14 +927,6 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * BaseType_t xQueueSendToBackFromISR( - * QueueHandle_t xQueue, - * const void *pvItemToQueue, - * BaseType_t *pxHigherPriorityTaskWoken - * ); - * @endcode * * This is a macro that calls xQueueGenericSendFromISR(). * @@ -1107,21 +983,12 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; * } * @endcode * - * \defgroup xQueueSendFromISR xQueueSendFromISR * \ingroup QueueManagement */ #define xQueueSendToBackFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \ xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK ) /** - * queue. h - * @code{c} - * BaseType_t xQueueOverwriteFromISR( - * QueueHandle_t xQueue, - * const void * pvItemToQueue, - * BaseType_t *pxHigherPriorityTaskWoken - * ); - * @endcode * * A version of xQueueOverwrite() that can be used in an interrupt service * routine (ISR). @@ -1195,21 +1062,12 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; * } * } * @endcode - * \defgroup xQueueOverwriteFromISR xQueueOverwriteFromISR * \ingroup QueueManagement */ #define xQueueOverwriteFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \ xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueOVERWRITE ) /** - * queue. h - * @code{c} - * BaseType_t xQueueSendFromISR( - * QueueHandle_t xQueue, - * const void *pvItemToQueue, - * BaseType_t *pxHigherPriorityTaskWoken - * ); - * @endcode * * This is a macro that calls xQueueGenericSendFromISR(). It is included * for backward compatibility with versions of FreeRTOS.org that did not @@ -1270,22 +1128,12 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; * } * @endcode * - * \defgroup xQueueSendFromISR xQueueSendFromISR * \ingroup QueueManagement */ #define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \ xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK ) /** - * queue. h - * @code{c} - * BaseType_t xQueueGenericSendFromISR( - * QueueHandle_t xQueue, - * const void *pvItemToQueue, - * BaseType_t *pxHigherPriorityTaskWoken, - * BaseType_t xCopyPosition - * ); - * @endcode * * It is preferred that the macros xQueueSendFromISR(), * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place @@ -1350,7 +1198,6 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; * } * @endcode * - * \defgroup xQueueSendFromISR xQueueSendFromISR * \ingroup QueueManagement */ BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue, @@ -1361,14 +1208,6 @@ BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; /** - * queue. h - * @code{c} - * BaseType_t xQueueReceiveFromISR( - * QueueHandle_t xQueue, - * void *pvBuffer, - * BaseType_t *pxTaskWoken - * ); - * @endcode * * Receive an item from a queue. It is safe to use this function from within an * interrupt service routine. @@ -1379,8 +1218,8 @@ BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue, * @param pvBuffer Pointer to the buffer into which the received item will * be copied. * - * @param pxTaskWoken A task may be blocked waiting for space to become - * available on the queue. If xQueueReceiveFromISR causes such a task to + * @param pxHigherPriorityTaskWoken A task may be blocked waiting for space to + * become available on the queue. If xQueueReceiveFromISR causes such a task to * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will * remain unchanged. * @@ -1444,21 +1283,38 @@ BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue, * } * } * @endcode - * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR * \ingroup QueueManagement */ BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue, void * const pvBuffer, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; -/* - * Utilities to query queues that are safe to use from an ISR. These utilities - * should be used only from within an ISR, or within a critical section. +/** + * Queries a queue to determine if the queue is empty. This function should only be used in an ISR. + * + * @param xQueue The handle of the queue being queried + * @return pdFALSE if the queue is not empty, or pdTRUE if the queue is empty. */ BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; + +/** + * Queries a queue to determine if the queue is full. This function should only be used in an ISR. + * + * @param xQueue The handle of the queue being queried + * @return pdFALSE if the queue is not full, or pdTRUE if the queue is full. + */ BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; + +/** + * A version of uxQueueMessagesWaiting() that can be called from an ISR. Return the number of messages stored in a queue. + * + * @param xQueue A handle to the queue being queried. + * @return The number of messages available in the queue. + */ UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* * The functions defined above are for passing data to and from tasks. The * functions below are the equivalents for passing data to and from @@ -1507,13 +1363,15 @@ BaseType_t xQueueTakeMutexRecursive( QueueHandle_t xMutex, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION; -/* +/** @endcond */ + +/** * Reset a queue back to its original empty state. The return value is now * obsolete and is always set to pdPASS. */ #define xQueueReset( xQueue ) xQueueGenericReset( ( xQueue ), pdFALSE ) -/* +/** * The registry is provided as a means for kernel aware debuggers to * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add * a queue, semaphore or mutex handle to the registry if you want the handle @@ -1544,7 +1402,7 @@ BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION; const char * pcQueueName ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ #endif -/* +/** * The registry is provided as a means for kernel aware debuggers to * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add * a queue, semaphore or mutex handle to the registry if you want the handle @@ -1558,7 +1416,7 @@ BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION; void vQueueUnregisterQueue( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; #endif -/* +/** * The queue registry is provided as a means for kernel aware debuggers to * locate queues, semaphores and mutexes. Call pcQueueGetName() to look * up and return the name of a queue in the queue registry from the queue's @@ -1573,6 +1431,8 @@ BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION; const char * pcQueueGetName( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ #endif +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* * Generic version of the function used to create a queue using dynamic memory * allocation. This is called by other functions and macros that create other @@ -1609,7 +1469,9 @@ BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION; StaticQueue_t ** ppxStaticQueue ) PRIVILEGED_FUNCTION; #endif -/* +/** @endcond */ + +/** * Queue sets provide a mechanism to allow a task to block (pend) on a read * operation from multiple queues or semaphores simultaneously. * @@ -1659,7 +1521,7 @@ BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION; */ QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength ) PRIVILEGED_FUNCTION; -/* +/** * Adds a queue or semaphore to a queue set that was previously created by a * call to xQueueCreateSet(). * @@ -1684,7 +1546,7 @@ QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength ) PRIVILE BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION; -/* +/** * Removes a queue or semaphore from a queue set. A queue or semaphore can only * be removed from a set if the queue or semaphore is empty. * @@ -1704,7 +1566,7 @@ BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore, BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION; -/* +/** * xQueueSelectFromSet() selects from the members of a queue set a queue or * semaphore that either contains data (in the case of a queue) or is available * to take (in the case of a semaphore). xQueueSelectFromSet() effectively @@ -1741,11 +1603,13 @@ BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; -/* +/** * A version of xQueueSelectFromSet() that can be used from an ISR. */ QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION; +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* Not public API functions. */ void vQueueWaitForMessageRestricted( QueueHandle_t xQueue, TickType_t xTicksToWait, @@ -1757,6 +1621,7 @@ void vQueueSetQueueNumber( QueueHandle_t xQueue, UBaseType_t uxQueueGetQueueNumber( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; uint8_t ucQueueGetQueueType( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; +/** @endcond */ /* *INDENT-OFF* */ #ifdef __cplusplus diff --git a/components/freertos/FreeRTOS-Kernel/include/freertos/semphr.h b/components/freertos/FreeRTOS-Kernel/include/freertos/semphr.h index 648777e947..3228e979fe 100644 --- a/components/freertos/FreeRTOS-Kernel/include/freertos/semphr.h +++ b/components/freertos/FreeRTOS-Kernel/include/freertos/semphr.h @@ -47,10 +47,6 @@ typedef QueueHandle_t SemaphoreHandle_t; /** - * semphr. h - * @code{c} - * vSemaphoreCreateBinary( SemaphoreHandle_t xSemaphore ); - * @endcode * * In many usage scenarios it is faster and more memory efficient to use a * direct to task notification in place of a binary semaphore! @@ -94,7 +90,6 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary * \ingroup Semaphores */ #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) @@ -109,10 +104,6 @@ typedef QueueHandle_t SemaphoreHandle_t; #endif /** - * semphr. h - * @code{c} - * SemaphoreHandle_t xSemaphoreCreateBinary( void ); - * @endcode * * Creates a new binary semaphore instance, and returns a handle by which the * new semaphore can be referenced. @@ -164,7 +155,6 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreCreateBinary xSemaphoreCreateBinary * \ingroup Semaphores */ #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) @@ -172,10 +162,6 @@ typedef QueueHandle_t SemaphoreHandle_t; #endif /** - * semphr. h - * @code{c} - * SemaphoreHandle_t xSemaphoreCreateBinaryStatic( StaticSemaphore_t *pxSemaphoreBuffer ); - * @endcode * * Creates a new binary semaphore instance, and returns a handle by which the * new semaphore can be referenced. @@ -200,7 +186,7 @@ typedef QueueHandle_t SemaphoreHandle_t; * semaphore does not use a priority inheritance mechanism. For an alternative * that does use priority inheritance see xSemaphoreCreateMutex(). * - * @param pxSemaphoreBuffer Must point to a variable of type StaticSemaphore_t, + * @param pxStaticSemaphore Must point to a variable of type StaticSemaphore_t, * which will then be used to hold the semaphore's data structure, removing the * need for the memory to be allocated dynamically. * @@ -225,7 +211,6 @@ typedef QueueHandle_t SemaphoreHandle_t; * // Rest of task code goes here. * } * @endcode - * \defgroup xSemaphoreCreateBinaryStatic xSemaphoreCreateBinaryStatic * \ingroup Semaphores */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) @@ -233,13 +218,6 @@ typedef QueueHandle_t SemaphoreHandle_t; #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * semphr. h - * @code{c} - * xSemaphoreTake( - * SemaphoreHandle_t xSemaphore, - * TickType_t xBlockTime - * ); - * @endcode * * Macro to obtain a semaphore. The semaphore must have previously been * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or @@ -296,19 +274,11 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreTake xSemaphoreTake * \ingroup Semaphores */ #define xSemaphoreTake( xSemaphore, xBlockTime ) xQueueSemaphoreTake( ( xSemaphore ), ( xBlockTime ) ) /** - * semphr. h - * @code{c} - * xSemaphoreTakeRecursive( - * SemaphoreHandle_t xMutex, - * TickType_t xBlockTime - * ); - * @endcode * * Macro to recursively obtain, or 'take', a mutex type semaphore. * The mutex must have previously been created using a call to @@ -391,7 +361,6 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreTakeRecursive xSemaphoreTakeRecursive * \ingroup Semaphores */ #if ( configUSE_RECURSIVE_MUTEXES == 1 ) @@ -399,10 +368,6 @@ typedef QueueHandle_t SemaphoreHandle_t; #endif /** - * semphr. h - * @code{c} - * xSemaphoreGive( SemaphoreHandle_t xSemaphore ); - * @endcode * * Macro to release a semaphore. The semaphore must have previously been * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or @@ -458,16 +423,11 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreGive xSemaphoreGive * \ingroup Semaphores */ #define xSemaphoreGive( xSemaphore ) xQueueGenericSend( ( QueueHandle_t ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK ) /** - * semphr. h - * @code{c} - * xSemaphoreGiveRecursive( SemaphoreHandle_t xMutex ); - * @endcode * * Macro to recursively release, or 'give', a mutex type semaphore. * The mutex must have previously been created using a call to @@ -544,7 +504,6 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreGiveRecursive xSemaphoreGiveRecursive * \ingroup Semaphores */ #if ( configUSE_RECURSIVE_MUTEXES == 1 ) @@ -552,13 +511,6 @@ typedef QueueHandle_t SemaphoreHandle_t; #endif /** - * semphr. h - * @code{c} - * xSemaphoreGiveFromISR( - * SemaphoreHandle_t xSemaphore, - * BaseType_t *pxHigherPriorityTaskWoken - * ); - * @endcode * * Macro to release a semaphore. The semaphore must have previously been * created with a call to xSemaphoreCreateBinary() or xSemaphoreCreateCounting(). @@ -581,8 +533,8 @@ typedef QueueHandle_t SemaphoreHandle_t; * * Example usage: * @code{c} - \#define LONG_TIME 0xffff - \#define TICKS_TO_WAIT 10 + * #define LONG_TIME 0xffff + * #define TICKS_TO_WAIT 10 * SemaphoreHandle_t xSemaphore = NULL; * * // Repetitive task. @@ -638,19 +590,11 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR * \ingroup Semaphores */ #define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueGiveFromISR( ( QueueHandle_t ) ( xSemaphore ), ( pxHigherPriorityTaskWoken ) ) /** - * semphr. h - * @code{c} - * xSemaphoreTakeFromISR( - * SemaphoreHandle_t xSemaphore, - * BaseType_t *pxHigherPriorityTaskWoken - * ); - * @endcode * * Macro to take a semaphore from an ISR. The semaphore must have * previously been created with a call to xSemaphoreCreateBinary() or @@ -679,10 +623,6 @@ typedef QueueHandle_t SemaphoreHandle_t; #define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueReceiveFromISR( ( QueueHandle_t ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) ) /** - * semphr. h - * @code{c} - * SemaphoreHandle_t xSemaphoreCreateMutex( void ); - * @endcode * * Creates a new mutex type semaphore instance, and returns a handle by which * the new mutex can be referenced. @@ -732,18 +672,13 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreCreateMutex xSemaphoreCreateMutex * \ingroup Semaphores */ -#if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configUSE_MUTEXES == 1 ) ) +#if __DOXYGEN__ || ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configUSE_MUTEXES == 1 ) ) #define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX ) #endif /** - * semphr. h - * @code{c} - * SemaphoreHandle_t xSemaphoreCreateMutexStatic( StaticSemaphore_t *pxMutexBuffer ); - * @endcode * * Creates a new mutex type semaphore instance, and returns a handle by which * the new mutex can be referenced. @@ -795,19 +730,14 @@ typedef QueueHandle_t SemaphoreHandle_t; * // so there is no need to check it. * } * @endcode - * \defgroup xSemaphoreCreateMutexStatic xSemaphoreCreateMutexStatic * \ingroup Semaphores */ -#if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configUSE_MUTEXES == 1 ) ) +#if __DOXYGEN__ || ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configUSE_MUTEXES == 1 ) ) #define xSemaphoreCreateMutexStatic( pxMutexBuffer ) xQueueCreateMutexStatic( queueQUEUE_TYPE_MUTEX, ( pxMutexBuffer ) ) #endif /** - * semphr. h - * @code{c} - * SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void ); - * @endcode * * Creates a new recursive mutex type semaphore instance, and returns a handle * by which the new recursive mutex can be referenced. @@ -865,18 +795,13 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreCreateRecursiveMutex xSemaphoreCreateRecursiveMutex * \ingroup Semaphores */ -#if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) ) +#if __DOXYGEN__ || ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) ) #define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX ) #endif /** - * semphr. h - * @code{c} - * SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic( StaticSemaphore_t *pxMutexBuffer ); - * @endcode * * Creates a new recursive mutex type semaphore instance, and returns a handle * by which the new recursive mutex can be referenced. @@ -914,13 +839,13 @@ typedef QueueHandle_t SemaphoreHandle_t; * semaphore and another always 'takes' the semaphore) and from within interrupt * service routines. * - * @param pxMutexBuffer Must point to a variable of type StaticSemaphore_t, + * @param pxStaticSemaphore Must point to a variable of type StaticSemaphore_t, * which will then be used to hold the recursive mutex's data structure, * removing the need for the memory to be allocated dynamically. * * @return If the recursive mutex was successfully created then a handle to the - * created recursive mutex is returned. If pxMutexBuffer was NULL then NULL is - * returned. + * created recursive mutex is returned. If pxStaticSemaphore was NULL then NULL + * is returned. * * Example usage: * @code{c} @@ -940,18 +865,13 @@ typedef QueueHandle_t SemaphoreHandle_t; * // so there is no need to check it. * } * @endcode - * \defgroup xSemaphoreCreateRecursiveMutexStatic xSemaphoreCreateRecursiveMutexStatic * \ingroup Semaphores */ -#if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) ) +#if __DOXYGEN__ || ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) ) #define xSemaphoreCreateRecursiveMutexStatic( pxStaticSemaphore ) xQueueCreateMutexStatic( queueQUEUE_TYPE_RECURSIVE_MUTEX, ( pxStaticSemaphore ) ) #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * semphr. h - * @code{c} - * SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount ); - * @endcode * * Creates a new counting semaphore instance, and returns a handle by which the * new counting semaphore can be referenced. @@ -1022,7 +942,6 @@ typedef QueueHandle_t SemaphoreHandle_t; * } * } * @endcode - * \defgroup xSemaphoreCreateCounting xSemaphoreCreateCounting * \ingroup Semaphores */ #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) @@ -1030,10 +949,6 @@ typedef QueueHandle_t SemaphoreHandle_t; #endif /** - * semphr. h - * @code{c} - * SemaphoreHandle_t xSemaphoreCreateCountingStatic( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount, StaticSemaphore_t *pxSemaphoreBuffer ); - * @endcode * * Creates a new counting semaphore instance, and returns a handle by which the * new counting semaphore can be referenced. @@ -1109,7 +1024,6 @@ typedef QueueHandle_t SemaphoreHandle_t; * // is no need to check its value. * } * @endcode - * \defgroup xSemaphoreCreateCountingStatic xSemaphoreCreateCountingStatic * \ingroup Semaphores */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) @@ -1117,26 +1031,17 @@ typedef QueueHandle_t SemaphoreHandle_t; #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * semphr. h - * @code{c} - * void vSemaphoreDelete( SemaphoreHandle_t xSemaphore ); - * @endcode * * Delete a semaphore. This function must be used with care. For example, * do not delete a mutex type semaphore if the mutex is held by a task. * * @param xSemaphore A handle to the semaphore to be deleted. * - * \defgroup vSemaphoreDelete vSemaphoreDelete * \ingroup Semaphores */ #define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( QueueHandle_t ) ( xSemaphore ) ) /** - * semphr.h - * @code{c} - * TaskHandle_t xSemaphoreGetMutexHolder( SemaphoreHandle_t xMutex ); - * @endcode * * If xMutex is indeed a mutex type semaphore, return the current mutex holder. * If xMutex is not a mutex type semaphore, or the mutex is available (not held @@ -1147,30 +1052,22 @@ typedef QueueHandle_t SemaphoreHandle_t; * the holder may change between the function exiting and the returned value * being tested. */ -#if ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) ) +#if __DOXYGEN__ || ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) ) #define xSemaphoreGetMutexHolder( xSemaphore ) xQueueGetMutexHolder( ( xSemaphore ) ) #endif /** - * semphr.h - * @code{c} - * TaskHandle_t xSemaphoreGetMutexHolderFromISR( SemaphoreHandle_t xMutex ); - * @endcode * * If xMutex is indeed a mutex type semaphore, return the current mutex holder. * If xMutex is not a mutex type semaphore, or the mutex is available (not held * by a task), return NULL. * */ -#if ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) ) +#if __DOXYGEN__ || ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) ) #define xSemaphoreGetMutexHolderFromISR( xSemaphore ) xQueueGetMutexHolderFromISR( ( xSemaphore ) ) #endif /** - * semphr.h - * @code{c} - * UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xSemaphore ); - * @endcode * * If the semaphore is a counting semaphore then uxSemaphoreGetCount() returns * its current count value. If the semaphore is a binary semaphore then @@ -1195,10 +1092,6 @@ typedef QueueHandle_t SemaphoreHandle_t; #define uxSemaphoreGetCountFromISR( xSemaphore ) uxQueueMessagesWaitingFromISR( ( QueueHandle_t ) ( xSemaphore ) ) /** - * semphr.h - * @code{c} - * BaseType_t xSemaphoreGetStaticBuffer( SemaphoreHandle_t xSemaphore ); - * @endcode * * Retrieve pointer to a statically created binary semaphore, counting semaphore, * or mutex semaphore's data structure buffer. This is the same buffer that is diff --git a/components/freertos/FreeRTOS-Kernel/include/freertos/stream_buffer.h b/components/freertos/FreeRTOS-Kernel/include/freertos/stream_buffer.h index 2c5fd41500..b3ec956ce9 100644 --- a/components/freertos/FreeRTOS-Kernel/include/freertos/stream_buffer.h +++ b/components/freertos/FreeRTOS-Kernel/include/freertos/stream_buffer.h @@ -83,11 +83,6 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf BaseType_t * const pxHigherPriorityTaskWoken ); /** - * stream_buffer.h - * - * @code{c} - * StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes ); - * @endcode * * Creates a new stream buffer using dynamically allocated memory. See * xStreamBufferCreateStatic() for a version that uses statically allocated @@ -154,12 +149,13 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf * } * } * @endcode - * \defgroup xStreamBufferCreate xStreamBufferCreate * \ingroup StreamBufferManagement */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ #define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) \ xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, NULL, NULL ) +/** @endcond */ #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) #define xStreamBufferCreateWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ @@ -167,14 +163,6 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf #endif /** - * stream_buffer.h - * - * @code{c} - * StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes, - * size_t xTriggerLevelBytes, - * uint8_t *pucStreamBufferStorageArea, - * StaticStreamBuffer_t *pxStaticStreamBuffer ); - * @endcode * Creates a new stream buffer using statically allocated memory. See * xStreamBufferCreate() for a version that uses dynamically allocated memory. * @@ -252,12 +240,13 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf * } * * @endcode - * \defgroup xStreamBufferCreateStatic xStreamBufferCreateStatic * \ingroup StreamBufferManagement */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ #define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) \ xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), pdFALSE, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), NULL, NULL ) +/** @endcond */ #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) #define xStreamBufferCreateStaticWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ @@ -265,13 +254,6 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf #endif /** - * stream_buffer.h - * - * @code{c} - * BaseType_t xStreamBufferGetStaticBuffers( StreamBufferHandle_t xStreamBuffer, - * uint8_t ** ppucStreamBufferStorageArea, - * StaticStreamBuffer_t ** ppxStaticStreamBuffer ); - * @endcode * * Retrieve pointers to a statically created stream buffer's data structure * buffer and storage area buffer. These are the same buffers that are supplied @@ -287,7 +269,6 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf * * @return pdTRUE if buffers were retrieved, pdFALSE otherwise. * - * \defgroup xStreamBufferGetStaticBuffers xStreamBufferGetStaticBuffers * \ingroup StreamBufferManagement */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) @@ -297,14 +278,6 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * stream_buffer.h - * - * @code{c} - * size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, - * const void *pvTxData, - * size_t xDataLengthBytes, - * TickType_t xTicksToWait ); - * @endcode * * Sends bytes to a stream buffer. The bytes are copied into the stream buffer. * @@ -385,7 +358,6 @@ typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuf * } * } * @endcode - * \defgroup xStreamBufferSend xStreamBufferSend * \ingroup StreamBufferManagement */ size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, @@ -394,14 +366,6 @@ size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, - * const void *pvTxData, - * size_t xDataLengthBytes, - * BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * Interrupt safe version of the API function that sends a stream of bytes to * the stream buffer. @@ -486,7 +450,6 @@ size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, * portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); * } * @endcode - * \defgroup xStreamBufferSendFromISR xStreamBufferSendFromISR * \ingroup StreamBufferManagement */ size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, @@ -495,14 +458,6 @@ size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, - * void *pvRxData, - * size_t xBufferLengthBytes, - * TickType_t xTicksToWait ); - * @endcode * * Receives bytes from a stream buffer. * @@ -575,7 +530,6 @@ size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, * } * } * @endcode - * \defgroup xStreamBufferReceive xStreamBufferReceive * \ingroup StreamBufferManagement */ size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, @@ -584,14 +538,6 @@ size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, - * void *pvRxData, - * size_t xBufferLengthBytes, - * BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * An interrupt safe version of the API function that receives bytes from a * stream buffer. @@ -661,7 +607,6 @@ size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, * portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); * } * @endcode - * \defgroup xStreamBufferReceiveFromISR xStreamBufferReceiveFromISR * \ingroup StreamBufferManagement */ size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, @@ -670,11 +615,6 @@ size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ); - * @endcode * * Deletes a stream buffer that was previously created using a call to * xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream @@ -686,17 +626,11 @@ size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, * * @param xStreamBuffer The handle of the stream buffer to be deleted. * - * \defgroup vStreamBufferDelete vStreamBufferDelete * \ingroup StreamBufferManagement */ void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ); - * @endcode * * Queries a stream buffer to see if it is full. A stream buffer is full if it * does not have any free space, and therefore cannot accept any more data. @@ -706,17 +640,11 @@ void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTI * @return If the stream buffer is full then pdTRUE is returned. Otherwise * pdFALSE is returned. * - * \defgroup xStreamBufferIsFull xStreamBufferIsFull * \ingroup StreamBufferManagement */ BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ); - * @endcode * * Queries a stream buffer to see if it is empty. A stream buffer is empty if * it does not contain any data. @@ -726,17 +654,11 @@ BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_ * @return If the stream buffer is empty then pdTRUE is returned. Otherwise * pdFALSE is returned. * - * \defgroup xStreamBufferIsEmpty xStreamBufferIsEmpty * \ingroup StreamBufferManagement */ BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ); - * @endcode * * Resets a stream buffer to its initial, empty, state. Any data that was in * the stream buffer is discarded. A stream buffer can only be reset if there @@ -749,17 +671,11 @@ BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED * a task blocked waiting to send to or read from the stream buffer then the * stream buffer is not reset and pdFAIL is returned. * - * \defgroup xStreamBufferReset xStreamBufferReset * \ingroup StreamBufferManagement */ BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ); - * @endcode * * Queries a stream buffer to see how much free space it contains, which is * equal to the amount of data that can be sent to the stream buffer before it @@ -770,17 +686,11 @@ BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_F * @return The number of bytes that can be written to the stream buffer before * the stream buffer would be full. * - * \defgroup xStreamBufferSpacesAvailable xStreamBufferSpacesAvailable * \ingroup StreamBufferManagement */ size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ); - * @endcode * * Queries a stream buffer to see how much data it contains, which is equal to * the number of bytes that can be read from the stream buffer before the stream @@ -791,17 +701,11 @@ size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVIL * @return The number of bytes that can be read from the stream buffer before * the stream buffer would be empty. * - * \defgroup xStreamBufferBytesAvailable xStreamBufferBytesAvailable * \ingroup StreamBufferManagement */ size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ); - * @endcode * * A stream buffer's trigger level is the number of bytes that must be in the * stream buffer before a task that is blocked on the stream buffer to @@ -828,18 +732,12 @@ size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILE * then the trigger level will be updated and pdTRUE is returned. Otherwise * pdFALSE is returned. * - * \defgroup xStreamBufferSetTriggerLevel xStreamBufferSetTriggerLevel * \ingroup StreamBufferManagement */ BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * For advanced users only. * @@ -868,18 +766,12 @@ BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, * @return If a task was removed from the Blocked state then pdTRUE is returned. * Otherwise pdFALSE is returned. * - * \defgroup xStreamBufferSendCompletedFromISR xStreamBufferSendCompletedFromISR * \ingroup StreamBufferManagement */ BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; /** - * stream_buffer.h - * - * @code{c} - * BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * For advanced users only. * @@ -909,12 +801,13 @@ BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer * @return If a task was removed from the Blocked state then pdTRUE is returned. * Otherwise pdFALSE is returned. * - * \defgroup xStreamBufferReceiveCompletedFromISR xStreamBufferReceiveCompletedFromISR * \ingroup StreamBufferManagement */ BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* Functions below here are not part of the public API. */ StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes, @@ -940,6 +833,8 @@ size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer ) uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; #endif +/** @endcond */ + /* *INDENT-OFF* */ #if defined( __cplusplus ) } diff --git a/components/freertos/FreeRTOS-Kernel/include/freertos/task.h b/components/freertos/FreeRTOS-Kernel/include/freertos/task.h index a3427087af..9da4e26cfb 100644 --- a/components/freertos/FreeRTOS-Kernel/include/freertos/task.h +++ b/components/freertos/FreeRTOS-Kernel/include/freertos/task.h @@ -50,6 +50,8 @@ * MACROS AND DEFINITIONS *----------------------------------------------------------*/ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* * If tskKERNEL_VERSION_NUMBER ends with + it represents the version in development * after the numbered release. @@ -77,46 +79,48 @@ * array. */ #define tskDEFAULT_INDEX_TO_NOTIFY ( 0 ) +/** @endcond */ + /** - * task. h * * Type by which tasks are referenced. For example, a call to xTaskCreate * returns (via a pointer parameter) an TaskHandle_t variable that can then * be used as a parameter to vTaskDelete to delete the task. * - * \defgroup TaskHandle_t TaskHandle_t * \ingroup Tasks */ struct tskTaskControlBlock; /* The old naming convention is used to prevent breaking kernel aware debuggers. */ typedef struct tskTaskControlBlock * TaskHandle_t; -/* +/** * Defines the prototype to which the application task hook function must * conform. */ typedef BaseType_t (* TaskHookFunction_t)( void * ); -/* Task states returned by eTaskGetState. */ +/** Task states returned by eTaskGetState. */ typedef enum { - eRunning = 0, /* A task is querying the state of itself, so must be running. */ - eReady, /* The task being queried is in a ready or pending ready list. */ - eBlocked, /* The task being queried is in the Blocked state. */ - eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */ - eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */ - eInvalid /* Used as an 'invalid state' value. */ + eRunning = 0, /**< A task is querying the state of itself, so must be running. */ + eReady, /**< The task being queried is in a ready or pending ready list. */ + eBlocked, /**< The task being queried is in the Blocked state. */ + eSuspended, /**< The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */ + eDeleted, /**< The task being queried has been deleted, but its TCB has not yet been freed. */ + eInvalid /**< Used as an 'invalid state' value. */ } eTaskState; -/* Actions that can be performed when vTaskNotify() is called. */ +/** Actions that can be performed when vTaskNotify() is called. */ typedef enum { - eNoAction = 0, /* Notify the task without updating its notify value. */ - eSetBits, /* Set bits in the task's notification value. */ - eIncrement, /* Increment the task's notification value. */ - eSetValueWithOverwrite, /* Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */ - eSetValueWithoutOverwrite /* Set the task's notification value if the previous value has been read by the task. */ + eNoAction = 0, /**< Notify the task without updating its notify value. */ + eSetBits, /**< Set bits in the task's notification value. */ + eIncrement, /**< Increment the task's notification value. */ + eSetValueWithOverwrite, /**< Set the task's notification value to a specific value even if the previous value has not yet been read by the task. */ + eSetValueWithoutOverwrite /**< Set the task's notification value if the previous value has been read by the task. */ } eNotifyAction; +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* * Used internally only. */ @@ -153,33 +157,35 @@ typedef struct xTASK_PARAMETERS #endif } TaskParameters_t; -/* Used with the uxTaskGetSystemState() function to return the state of each task +/** @endcond */ + +/** Used with the uxTaskGetSystemState() function to return the state of each task * in the system. */ typedef struct xTASK_STATUS { - TaskHandle_t xHandle; /* The handle of the task to which the rest of the information in the structure relates. */ - const char * pcTaskName; /* A pointer to the task's name. This value will be invalid if the task was deleted since the structure was populated! */ /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ - UBaseType_t xTaskNumber; /* A number unique to the task. */ - eTaskState eCurrentState; /* The state in which the task existed when the structure was populated. */ - UBaseType_t uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */ - UBaseType_t uxBasePriority; /* The priority to which the task will return if the task's current priority has been inherited to avoid unbounded priority inversion when obtaining a mutex. Only valid if configUSE_MUTEXES is defined as 1 in FreeRTOSConfig.h. */ - configRUN_TIME_COUNTER_TYPE ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock. See https://www.FreeRTOS.org/rtos-run-time-stats.html. Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */ - StackType_t * pxStackBase; /* Points to the lowest address of the task's stack area. */ + TaskHandle_t xHandle; /**< The handle of the task to which the rest of the information in the structure relates. */ + const char * pcTaskName; /**< A pointer to the task's name. This value will be invalid if the task was deleted since the structure was populated! */ /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ + UBaseType_t xTaskNumber; /**< A number unique to the task. */ + eTaskState eCurrentState; /**< The state in which the task existed when the structure was populated. */ + UBaseType_t uxCurrentPriority; /**< The priority at which the task was running (may be inherited) when the structure was populated. */ + UBaseType_t uxBasePriority; /**< The priority to which the task will return if the task's current priority has been inherited to avoid unbounded priority inversion when obtaining a mutex. Only valid if configUSE_MUTEXES is defined as 1 in FreeRTOSConfig.h. */ + configRUN_TIME_COUNTER_TYPE ulRunTimeCounter; /**< The total run time allocated to the task so far, as defined by the run time stats clock. See https://www.FreeRTOS.org/rtos-run-time-stats.html. Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */ + StackType_t * pxStackBase; /**< Points to the lowest address of the task's stack area. */ #if ( ( portSTACK_GROWTH > 0 ) && ( configRECORD_STACK_HIGH_ADDRESS == 1 ) ) - StackType_t * pxTopOfStack; /* Points to the top address of the task's stack area. */ - StackType_t * pxEndOfStack; /* Points to the end address of the task's stack area. */ + StackType_t * pxTopOfStack; /**< Points to the top address of the task's stack area. */ + StackType_t * pxEndOfStack; /**< Points to the end address of the task's stack area. */ #endif - configSTACK_DEPTH_TYPE usStackHighWaterMark; /* The minimum amount of stack space that has remained for the task since the task was created. The closer this value is to zero the closer the task has come to overflowing its stack. */ - BaseType_t xCoreID; /*!< Core this task is pinned to (0, 1, or tskNO_AFFINITY). If configNUMBER_OF_CORES == 1, this will always be 0. */ + configSTACK_DEPTH_TYPE usStackHighWaterMark; /**< The minimum amount of stack space that has remained for the task since the task was created. The closer this value is to zero the closer the task has come to overflowing its stack. */ + BaseType_t xCoreID; /**< Core this task is pinned to (0, 1, or tskNO_AFFINITY). If configNUMBER_OF_CORES == 1, this will always be 0. */ } TaskStatus_t; -/* Possible return values for eTaskConfirmSleepModeStatus(). */ +/** Possible return values for eTaskConfirmSleepModeStatus(). */ typedef enum { - eAbortSleep = 0, /* A task has been made ready or a context switch pended since portSUPPRESS_TICKS_AND_SLEEP() was called - abort entering a sleep mode. */ - eStandardSleep, /* Enter a sleep mode that will not last any longer than the expected idle time. */ + eAbortSleep = 0, /**< A task has been made ready or a context switch pended since portSUPPRESS_TICKS_AND_SLEEP() was called - abort entering a sleep mode. */ + eStandardSleep, /**< Enter a sleep mode that will not last any longer than the expected idle time. */ #if ( INCLUDE_vTaskSuspend == 1 ) - eNoTasksWaitingTimeout /* No tasks are waiting for a timeout so it is safe to enter a sleep mode that can only be exited by an external interrupt. */ + eNoTasksWaitingTimeout /**< No tasks are waiting for a timeout so it is safe to enter a sleep mode that can only be exited by an external interrupt. */ #endif /* INCLUDE_vTaskSuspend */ } eSleepModeStatus; @@ -199,17 +205,14 @@ typedef enum /* Todo: Update tskNO_AFFINITY value to -1 (IDF-7908) */ /** - * task. h * * Macro for forcing a context switch. * - * \defgroup taskYIELD taskYIELD * \ingroup SchedulerControl */ #define taskYIELD() portYIELD() /** - * task. h * * Macro to mark the start of a critical code region. Preemptive context * switches cannot occur when in a critical region. @@ -217,7 +220,6 @@ typedef enum * NOTE: This may alter the stack (depending on the portable implementation) * so must be used with care! * - * \defgroup taskENTER_CRITICAL taskENTER_CRITICAL * \ingroup SchedulerControl */ #define taskENTER_CRITICAL( x ) portENTER_CRITICAL( x ) @@ -225,7 +227,6 @@ typedef enum #define taskENTER_CRITICAL_ISR( x ) portENTER_CRITICAL_ISR( x ) /** - * task. h * * Macro to mark the end of a critical code region. Preemptive context * switches cannot occur when in a critical region. @@ -233,7 +234,6 @@ typedef enum * NOTE: This may alter the stack (depending on the portable implementation) * so must be used with care! * - * \defgroup taskEXIT_CRITICAL taskEXIT_CRITICAL * \ingroup SchedulerControl */ #define taskEXIT_CRITICAL( x ) portEXIT_CRITICAL( x ) @@ -241,26 +241,23 @@ typedef enum #define taskEXIT_CRITICAL_ISR( x ) portEXIT_CRITICAL_ISR( x ) /** - * task. h * * Macro to disable all maskable interrupts. * - * \defgroup taskDISABLE_INTERRUPTS taskDISABLE_INTERRUPTS * \ingroup SchedulerControl */ #define taskDISABLE_INTERRUPTS() portDISABLE_INTERRUPTS() /** - * task. h * * Macro to enable microcontroller interrupts. * - * \defgroup taskENABLE_INTERRUPTS taskENABLE_INTERRUPTS + * * \ingroup SchedulerControl */ #define taskENABLE_INTERRUPTS() portENABLE_INTERRUPTS() -/* Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is +/** Definitions returned by xTaskGetSchedulerState(). taskSCHEDULER_SUSPENDED is * 0 to generate more optimal code when configASSERT() is defined as the constant * is used in assert() statements. */ #define taskSCHEDULER_SUSPENDED ( ( BaseType_t ) 0 ) @@ -273,17 +270,6 @@ typedef enum *----------------------------------------------------------*/ /** - * task. h - * @code{c} - * BaseType_t xTaskCreate( - * TaskFunction_t pxTaskCode, - * const char *pcName, - * configSTACK_DEPTH_TYPE usStackDepth, - * void *pvParameters, - * UBaseType_t uxPriority, - * TaskHandle_t *pxCreatedTask - * ); - * @endcode * * Create a new task and add it to the list of tasks that are ready to run. * @@ -367,7 +353,6 @@ typedef enum * } * } * @endcode - * \defgroup xTaskCreate xTaskCreate * \ingroup Tasks */ #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) @@ -406,16 +391,6 @@ typedef enum #endif /* configSUPPORT_DYNAMIC_ALLOCATION == 1 */ /** - * task. h - * @code{c} - * TaskHandle_t xTaskCreateStatic( TaskFunction_t pxTaskCode, - * const char *pcName, - * uint32_t ulStackDepth, - * void *pvParameters, - * UBaseType_t uxPriority, - * StackType_t *puxStackBuffer, - * StaticTask_t *pxTaskBuffer ); - * @endcode * * Create a new task and add it to the list of tasks that are ready to run. * @@ -514,7 +489,6 @@ typedef enum * vTaskSuspend( xHandle ); * } * @endcode - * \defgroup xTaskCreateStatic xTaskCreateStatic * \ingroup Tasks */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) @@ -555,11 +529,9 @@ typedef enum } #endif /* configSUPPORT_STATIC_ALLOCATION */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /** - * task. h - * @code{c} - * BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask ); - * @endcode * * Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1. * @@ -625,7 +597,6 @@ typedef enum * for( ;; ); * } * @endcode - * \defgroup xTaskCreateRestricted xTaskCreateRestricted * \ingroup Tasks */ #if ( portUSING_MPU_WRAPPERS == 1 ) @@ -634,10 +605,6 @@ typedef enum #endif /** - * task. h - * @code{c} - * BaseType_t xTaskCreateRestrictedStatic( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask ); - * @endcode * * Only available when configSUPPORT_STATIC_ALLOCATION is set to 1. * @@ -715,7 +682,6 @@ typedef enum * for( ;; ); * } * @endcode - * \defgroup xTaskCreateRestrictedStatic xTaskCreateRestrictedStatic * \ingroup Tasks */ #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) ) @@ -723,11 +689,9 @@ typedef enum TaskHandle_t * pxCreatedTask ) PRIVILEGED_FUNCTION; #endif +/** @endcond */ + /** - * task. h - * @code{c} - * void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions ); - * @endcode * * Memory regions are assigned to a restricted task when the task is created by * a call to xTaskCreateRestricted(). These regions can be redefined using @@ -735,7 +699,7 @@ typedef enum * * @param xTask The handle of the task being updated. * - * @param xRegions A pointer to a MemoryRegion_t structure that contains the + * @param pxRegions A pointer to a MemoryRegion_t structure that contains the * new memory region definitions. * * Example usage: @@ -767,17 +731,12 @@ typedef enum * // defined or shared regions have been declared elsewhere). * } * @endcode - * \defgroup vTaskAllocateMPURegions vTaskAllocateMPURegions * \ingroup Tasks */ void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * void vTaskDelete( TaskHandle_t xTaskToDelete ); - * @endcode * * INCLUDE_vTaskDelete must be defined as 1 for this function to be available. * See the configuration section for more information. @@ -811,7 +770,6 @@ void vTaskAllocateMPURegions( TaskHandle_t xTask, * vTaskDelete( xHandle ); * } * @endcode - * \defgroup vTaskDelete vTaskDelete * \ingroup Tasks */ void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION; @@ -821,10 +779,6 @@ void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION; *----------------------------------------------------------*/ /** - * task. h - * @code{c} - * void vTaskDelay( const TickType_t xTicksToDelay ); - * @endcode * * Delay a task for a given number of ticks. The actual time that the * task remains blocked depends on the tick rate. The constant @@ -851,7 +805,7 @@ void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION; * the calling task should block. * * Example usage: - * + * @code{c} * void vTaskFunction( void * pvParameters ) * { * // Block for 500ms. @@ -864,17 +818,12 @@ void vTaskDelete( TaskHandle_t xTaskToDelete ) PRIVILEGED_FUNCTION; * vTaskDelay( xDelay ); * } * } - * - * \defgroup vTaskDelay vTaskDelay + * @endcode * \ingroup TaskCtrl */ void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * BaseType_t xTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement ); - * @endcode * * INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available. * See the configuration section for more information. @@ -932,12 +881,13 @@ void vTaskDelay( const TickType_t xTicksToDelay ) PRIVILEGED_FUNCTION; * } * } * @endcode - * \defgroup xTaskDelayUntil xTaskDelayUntil * \ingroup TaskCtrl */ BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime, const TickType_t xTimeIncrement ) PRIVILEGED_FUNCTION; +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* * vTaskDelayUntil() is the older version of xTaskDelayUntil() and does not * return a value. @@ -947,12 +897,10 @@ BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime, ( void ) xTaskDelayUntil( ( pxPreviousWakeTime ), ( xTimeIncrement ) ); \ } while( 0 ) +/** @endcond */ + /** - * task. h - * @code{c} - * BaseType_t xTaskAbortDelay( TaskHandle_t xTask ); - * @endcode * * INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this * function to be available. @@ -975,16 +923,11 @@ BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime, * @return If the task referenced by xTask was not in the Blocked state then * pdFAIL is returned. Otherwise pdPASS is returned. * - * \defgroup xTaskAbortDelay xTaskAbortDelay * \ingroup TaskCtrl */ BaseType_t xTaskAbortDelay( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask ); - * @endcode * * INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. * See the configuration section for more information. @@ -1024,26 +967,17 @@ BaseType_t xTaskAbortDelay( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; * } * } * @endcode - * \defgroup uxTaskPriorityGet uxTaskPriorityGet * \ingroup TaskCtrl */ UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask ); - * @endcode * * A version of uxTaskPriorityGet() that can be used from an ISR. */ UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * eTaskState eTaskGetState( TaskHandle_t xTask ); - * @endcode * * INCLUDE_eTaskGetState must be defined as 1 for this function to be available. * See the configuration section for more information. @@ -1060,10 +994,6 @@ UBaseType_t uxTaskPriorityGetFromISR( const TaskHandle_t xTask ) PRIVILEGED_FUNC eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState ); - * @endcode * * configUSE_TRACE_FACILITY must be defined as 1 for this function to be * available. See the configuration section for more information. @@ -1112,7 +1042,6 @@ eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; * eInvalid ); // Include the task state in xTaskDetails. * } * @endcode - * \defgroup vTaskGetInfo vTaskGetInfo * \ingroup TaskCtrl */ void vTaskGetInfo( TaskHandle_t xTask, @@ -1121,10 +1050,6 @@ void vTaskGetInfo( TaskHandle_t xTask, eTaskState eState ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ); - * @endcode * * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. * See the configuration section for more information. @@ -1159,17 +1084,12 @@ void vTaskGetInfo( TaskHandle_t xTask, * vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 ); * } * @endcode - * \defgroup vTaskPrioritySet vTaskPrioritySet * \ingroup TaskCtrl */ void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * void vTaskSuspend( TaskHandle_t xTaskToSuspend ); - * @endcode * * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. * See the configuration section for more information. @@ -1213,16 +1133,11 @@ void vTaskPrioritySet( TaskHandle_t xTask, * // with our handle as the parameter. * } * @endcode - * \defgroup vTaskSuspend vTaskSuspend * \ingroup TaskCtrl */ void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * void vTaskResume( TaskHandle_t xTaskToResume ); - * @endcode * * INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. * See the configuration section for more information. @@ -1264,16 +1179,11 @@ void vTaskSuspend( TaskHandle_t xTaskToSuspend ) PRIVILEGED_FUNCTION; * // time in accordance with its priority within the system. * } * @endcode - * \defgroup vTaskResume vTaskResume * \ingroup TaskCtrl */ void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * void xTaskResumeFromISR( TaskHandle_t xTaskToResume ); - * @endcode * * INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be * available. See the configuration section for more information. @@ -1295,7 +1205,6 @@ void vTaskResume( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; * otherwise pdFALSE. This is used by the ISR to determine if a context switch * may be required following the ISR. * - * \defgroup vTaskResumeFromISR vTaskResumeFromISR * \ingroup TaskCtrl */ BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; @@ -1304,11 +1213,9 @@ BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; * SCHEDULER CONTROL *----------------------------------------------------------*/ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /** - * task. h - * @code{c} - * void vTaskStartScheduler( void ); - * @endcode * * Starts the real time kernel tick processing. After calling the kernel * has control over which tasks are executed and when. @@ -1330,16 +1237,11 @@ BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION; * } * @endcode * - * \defgroup vTaskStartScheduler vTaskStartScheduler * \ingroup SchedulerControl */ void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * void vTaskEndScheduler( void ); - * @endcode * * NOTE: At the time of writing only the x86 real mode port, which runs on a PC * in place of DOS, implements this function. @@ -1388,16 +1290,13 @@ void vTaskStartScheduler( void ) PRIVILEGED_FUNCTION; * } * @endcode * - * \defgroup vTaskEndScheduler vTaskEndScheduler * \ingroup SchedulerControl */ void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; +/** @endcond */ + /** - * task. h - * @code{c} - * void vTaskSuspendAll( void ); - * @endcode * * Suspends the scheduler without disabling interrupts. Context switches will * not occur while the scheduler is suspended. @@ -1441,16 +1340,11 @@ void vTaskEndScheduler( void ) PRIVILEGED_FUNCTION; * } * } * @endcode - * \defgroup vTaskSuspendAll vTaskSuspendAll * \ingroup SchedulerControl */ void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * BaseType_t xTaskResumeAll( void ); - * @endcode * * Resumes scheduler activity after it was suspended by a call to * vTaskSuspendAll(). @@ -1497,7 +1391,6 @@ void vTaskSuspendAll( void ) PRIVILEGED_FUNCTION; * } * } * @endcode - * \defgroup xTaskResumeAll xTaskResumeAll * \ingroup SchedulerControl */ BaseType_t xTaskResumeAll( void ) PRIVILEGED_FUNCTION; @@ -1507,23 +1400,14 @@ BaseType_t xTaskResumeAll( void ) PRIVILEGED_FUNCTION; *----------------------------------------------------------*/ /** - * task. h - * @code{c} - * TickType_t xTaskGetTickCount( void ); - * @endcode * * @return The count of ticks since vTaskStartScheduler was called. * - * \defgroup xTaskGetTickCount xTaskGetTickCount * \ingroup TaskUtils */ TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * TickType_t xTaskGetTickCountFromISR( void ); - * @endcode * * @return The count of ticks since vTaskStartScheduler was called. * @@ -1532,47 +1416,32 @@ TickType_t xTaskGetTickCount( void ) PRIVILEGED_FUNCTION; * microcontroller being used or interrupt nesting is either not supported or * not being used. * - * \defgroup xTaskGetTickCountFromISR xTaskGetTickCountFromISR * \ingroup TaskUtils */ TickType_t xTaskGetTickCountFromISR( void ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * uint16_t uxTaskGetNumberOfTasks( void ); - * @endcode * * @return The number of tasks that the real time kernel is currently managing. * This includes all ready, blocked and suspended tasks. A task that * has been deleted but not yet freed by the idle task will also be * included in the count. * - * \defgroup uxTaskGetNumberOfTasks uxTaskGetNumberOfTasks * \ingroup TaskUtils */ UBaseType_t uxTaskGetNumberOfTasks( void ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * char *pcTaskGetName( TaskHandle_t xTaskToQuery ); - * @endcode * * @return The text (human readable) name of the task referenced by the handle * xTaskToQuery. A task can query its own name by either passing in its own * handle, or by setting xTaskToQuery to NULL. * - * \defgroup pcTaskGetName pcTaskGetName * \ingroup TaskUtils */ char * pcTaskGetName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ /** - * task. h - * @code{c} - * TaskHandle_t xTaskGetHandle( const char *pcNameToQuery ); - * @endcode * * NOTE: This function takes a relatively long time to complete and should be * used sparingly. @@ -1581,18 +1450,11 @@ char * pcTaskGetName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e * NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle * must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available. * - * \defgroup pcTaskGetHandle pcTaskGetHandle * \ingroup TaskUtils */ TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ /** - * task. h - * @code{c} - * BaseType_t xTaskGetStaticBuffers( TaskHandle_t xTask, - * StackType_t ** ppuxStackBuffer, - * StaticTask_t ** ppxTaskBuffer ); - * @endcode * * Retrieve pointers to a statically created task's data structure * buffer and stack buffer. These are the same buffers that are supplied @@ -1607,7 +1469,6 @@ TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ) PRIVILEGED_FUNCTION; / * * @return pdTRUE if buffers were retrieved, pdFALSE otherwise. * - * \defgroup xTaskGetStaticBuffers xTaskGetStaticBuffers * \ingroup TaskUtils */ #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) @@ -1617,10 +1478,6 @@ TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ) PRIVILEGED_FUNCTION; / #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * task.h - * @code{c} - * UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ); - * @endcode * * INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for * this function to be available. @@ -1646,10 +1503,6 @@ TaskHandle_t xTaskGetHandle( const char * pcNameToQuery ) PRIVILEGED_FUNCTION; / UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; /** - * task.h - * @code{c} - * configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ); - * @endcode * * INCLUDE_uxTaskGetStackHighWaterMark2 must be set to 1 in FreeRTOSConfig.h for * this function to be available. @@ -1684,10 +1537,6 @@ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVIL #if configUSE_APPLICATION_TASK_TAG == 1 /** - * task.h - * @code{c} - * void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxHookFunction ); - * @endcode * * Sets pxHookFunction to be the task hook function used by the task xTask. * Passing xTask as NULL has the effect of setting the calling tasks hook @@ -1697,10 +1546,6 @@ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVIL TaskHookFunction_t pxHookFunction ) PRIVILEGED_FUNCTION; /** - * task.h - * @code{c} - * void xTaskGetApplicationTaskTag( TaskHandle_t xTask ); - * @endcode * * Returns the pxHookFunction value assigned to the task xTask. Do not * call from an interrupt service routine - call @@ -1709,10 +1554,6 @@ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVIL TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask ) PRIVILEGED_FUNCTION; /** - * task.h - * @code{c} - * void xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask ); - * @endcode * * Returns the pxHookFunction value assigned to the task xTask. Can * be called from an interrupt service routine. @@ -1723,7 +1564,7 @@ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVIL #if ( configNUM_THREAD_LOCAL_STORAGE_POINTERS > 0 ) -/* Each task contains an array of pointers that is dimensioned by the +/** Each task contains an array of pointers that is dimensioned by the * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The * kernel does not use the pointers itself, so the application writer can use * the pointers for any purpose they wish. The following two functions are @@ -1739,10 +1580,6 @@ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVIL #if ( configCHECK_FOR_STACK_OVERFLOW > 0 ) /** - * task.h - * @code{c} - * void vApplicationStackOverflowHook( TaskHandle_t xTask char *pcTaskName); - * @endcode * * The application stack overflow hook is called when a stack overflow is detected for a task. * @@ -1759,10 +1596,6 @@ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVIL #if ( configUSE_TICK_HOOK > 0 ) /** - * task.h - * @code{c} - * void vApplicationTickHook( void ); - * @endcode * * This hook function is called in the system tick handler after any OS work is completed. */ @@ -1773,10 +1606,6 @@ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVIL #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) /** - * task.h - * @code{c} - * void vApplicationGetIdleTaskMemory( StaticTask_t ** ppxIdleTaskTCBBuffer, StackType_t ** ppxIdleTaskStackBuffer, uint32_t *pulIdleTaskStackSize ) - * @endcode * * This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Idle Task TCB. This function is required when * configSUPPORT_STATIC_ALLOCATION is set. For more information see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION @@ -1791,10 +1620,6 @@ configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask ) PRIVIL #endif /** - * task.h - * @code{c} - * BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter ); - * @endcode * * Calls the hook function associated with xTask. Passing xTask as NULL has * the effect of calling the Running tasks (the calling task) hook function. @@ -1917,10 +1742,6 @@ UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, configRUN_TIME_COUNTER_TYPE * const pulTotalRunTime ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * void vTaskList( char *pcWriteBuffer ); - * @endcode * * configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must * both be defined as 1 for this function to be available. See the @@ -1962,16 +1783,11 @@ UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, * enough to contain the generated report. Approximately 40 bytes per * task should be sufficient. * - * \defgroup vTaskList vTaskList * \ingroup TaskUtils */ void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ /** - * task. h - * @code{c} - * void vTaskGetRunTimeStats( char *pcWriteBuffer ); - * @endcode * * configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS * must both be defined as 1 for this function to be available. The application @@ -2018,17 +1834,11 @@ void vTaskList( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unquali * contain the generated report. Approximately 40 bytes per task should * be sufficient. * - * \defgroup vTaskGetRunTimeStats vTaskGetRunTimeStats * \ingroup TaskUtils */ void vTaskGetRunTimeStats( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ /** - * task. h - * @code{c} - * configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimeCounter( void ); - * configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimePercent( void ); - * @endcode * * configGENERATE_RUN_TIME_STATS, configUSE_STATS_FORMATTING_FUNCTIONS and * INCLUDE_xTaskGetIdleTaskHandle must all be defined as 1 for these functions @@ -2061,18 +1871,12 @@ void vTaskGetRunTimeStats( char * pcWriteBuffer ) PRIVILEGED_FUNCTION; /*lint !e * frequency configured using the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and * portGET_RUN_TIME_COUNTER_VALUE() macros. * - * \defgroup ulTaskGetIdleRunTimeCounter ulTaskGetIdleRunTimeCounter * \ingroup TaskUtils */ configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION; configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimePercent( void ) PRIVILEGED_FUNCTION; /** - * task. h - * @code{c} - * BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction ); - * BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction ); - * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * @@ -2172,9 +1976,9 @@ configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimePercent( void ) PRIVILEGED_FUNCT * @return Dependent on the value of eAction. See the description of the * eAction parameter. * - * \defgroup xTaskNotifyIndexed xTaskNotifyIndexed * \ingroup TaskNotifications */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, @@ -2182,15 +1986,11 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, uint32_t * pulPreviousNotificationValue ) PRIVILEGED_FUNCTION; #define xTaskNotify( xTaskToNotify, ulValue, eAction ) \ xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL ) +/** @endcond */ #define xTaskNotifyIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction ) \ xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL ) /** - * task. h - * @code{c} - * BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue ); - * BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue ); - * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * @@ -2206,20 +2006,16 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, * than when the function returns) in the additional pulPreviousNotifyValue * parameter. * - * \defgroup xTaskNotifyAndQueryIndexed xTaskNotifyAndQueryIndexed * \ingroup TaskNotifications */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ #define xTaskNotifyAndQuery( xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue ) \ xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) +/** @endcond */ #define xTaskNotifyAndQueryIndexed( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotifyValue ) \ xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotifyValue ) ) /** - * task. h - * @code{c} - * BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken ); - * BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * @@ -2324,9 +2120,9 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify, * @return Dependent on the value of eAction. See the description of the * eAction parameter. * - * \defgroup xTaskNotifyIndexedFromISR xTaskNotifyIndexedFromISR * \ingroup TaskNotifications */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, @@ -2335,15 +2131,11 @@ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; #define xTaskNotifyFromISR( xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \ xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) +/** @endcond */ #define xTaskNotifyIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pxHigherPriorityTaskWoken ) \ xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), NULL, ( pxHigherPriorityTaskWoken ) ) /** - * task. h - * @code{c} - * BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ); - * BaseType_t xTaskNotifyAndQueryFromISR( TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotificationValue, BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * @@ -2359,21 +2151,17 @@ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, * function is called rather than at the time the function returns) in the * additional pulPreviousNotifyValue parameter. * - * \defgroup xTaskNotifyAndQueryIndexedFromISR xTaskNotifyAndQueryIndexedFromISR * \ingroup TaskNotifications */ #define xTaskNotifyAndQueryIndexedFromISR( xTaskToNotify, uxIndexToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \ xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) ) +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ #define xTaskNotifyAndQueryFromISR( xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue, pxHigherPriorityTaskWoken ) \ xTaskGenericNotifyFromISR( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( ulValue ), ( eAction ), ( pulPreviousNotificationValue ), ( pxHigherPriorityTaskWoken ) ) +/** @endcond */ + /** - * task. h - * @code{c} - * BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); - * - * BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait ); - * @endcode * * Waits for a direct to task notification to be pending at a given index within * an array of direct to task notifications. @@ -2468,7 +2256,6 @@ BaseType_t xTaskGenericNotifyFromISR( TaskHandle_t xTaskToNotify, * already pending when xTaskNotifyWait was called) then pdPASS is * returned. Otherwise pdFAIL is returned. * - * \defgroup xTaskNotifyWaitIndexed xTaskNotifyWaitIndexed * \ingroup TaskNotifications */ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, @@ -2482,11 +2269,6 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, xTaskGenericNotifyWait( ( uxIndexToWaitOn ), ( ulBitsToClearOnEntry ), ( ulBitsToClearOnExit ), ( pulNotificationValue ), ( xTicksToWait ) ) /** - * task. h - * @code{c} - * BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify ); - * BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify ); - * @endcode * * Sends a direct to task notification to a particular index in the target * task's notification array in a manner similar to giving a counting semaphore. @@ -2550,20 +2332,16 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, * @return xTaskNotifyGive() is a macro that calls xTaskNotify() with the * eAction parameter set to eIncrement - so pdPASS is always returned. * - * \defgroup xTaskNotifyGiveIndexed xTaskNotifyGiveIndexed * \ingroup TaskNotifications */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ #define xTaskNotifyGive( xTaskToNotify ) \ xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL ) +/** @endcond */ #define xTaskNotifyGiveIndexed( xTaskToNotify, uxIndexToNotify ) \ xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ), eIncrement, NULL ) /** - * task. h - * @code{c} - * void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken ); - * void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken ); - * @endcode * * A version of xTaskNotifyGiveIndexed() that can be called from an interrupt * service routine (ISR). @@ -2634,7 +2412,6 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn, * requested from an ISR is dependent on the port - see the documentation page * for the port in use. * - * \defgroup vTaskNotifyGiveIndexedFromISR vTaskNotifyGiveIndexedFromISR * \ingroup TaskNotifications */ void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, @@ -2646,12 +2423,6 @@ void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, vTaskGenericNotifyGiveFromISR( ( xTaskToNotify ), ( uxIndexToNotify ), ( pxHigherPriorityTaskWoken ) ) /** - * task. h - * @code{c} - * uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait ); - * - * uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait ); - * @endcode * * Waits for a direct to task notification on a particular index in the calling * task's notification array in a manner similar to taking a counting semaphore. @@ -2740,24 +2511,19 @@ void vTaskGenericNotifyGiveFromISR( TaskHandle_t xTaskToNotify, * @return The task's notification count before it is either cleared to zero or * decremented (see the xClearCountOnExit parameter). * - * \defgroup ulTaskNotifyTakeIndexed ulTaskNotifyTakeIndexed * \ingroup TaskNotifications */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; #define ulTaskNotifyTake( xClearCountOnExit, xTicksToWait ) \ ulTaskGenericNotifyTake( ( tskDEFAULT_INDEX_TO_NOTIFY ), ( xClearCountOnExit ), ( xTicksToWait ) ) +/** @endcond */ #define ulTaskNotifyTakeIndexed( uxIndexToWaitOn, xClearCountOnExit, xTicksToWait ) \ ulTaskGenericNotifyTake( ( uxIndexToWaitOn ), ( xClearCountOnExit ), ( xTicksToWait ) ) /** - * task. h - * @code{c} - * BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToCLear ); - * - * BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask ); - * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * @@ -2805,7 +2571,6 @@ uint32_t ulTaskGenericNotifyTake( UBaseType_t uxIndexToWaitOn, * @return pdTRUE if the task's notification state was set to * eNotWaitingNotification, otherwise pdFALSE. * - * \defgroup xTaskNotifyStateClearIndexed xTaskNotifyStateClearIndexed * \ingroup TaskNotifications */ BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, @@ -2816,12 +2581,6 @@ BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, xTaskGenericNotifyStateClear( ( xTask ), ( uxIndexToClear ) ) /** - * task. h - * @code{c} - * uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear ); - * - * uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask, uint32_t ulBitsToClear ); - * @endcode * * See https://www.FreeRTOS.org/RTOS-task-notifications.html for details. * @@ -2870,7 +2629,6 @@ BaseType_t xTaskGenericNotifyStateClear( TaskHandle_t xTask, * * @return The value of the target task's notification value before the bits * specified by ulBitsToClear were cleared. - * \defgroup ulTaskNotifyValueClear ulTaskNotifyValueClear * \ingroup TaskNotifications */ uint32_t ulTaskGenericNotifyValueClear( TaskHandle_t xTask, @@ -2882,26 +2640,17 @@ uint32_t ulTaskGenericNotifyValueClear( TaskHandle_t xTask, ulTaskGenericNotifyValueClear( ( xTask ), ( uxIndexToClear ), ( ulBitsToClear ) ) /** - * task.h - * @code{c} - * void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ); - * @endcode * * Capture the current time for future use with xTaskCheckForTimeOut(). * * @param pxTimeOut Pointer to a timeout object into which the current time * is to be captured. The captured time includes the tick count and the number * of times the tick count has overflowed since the system first booted. - * \defgroup vTaskSetTimeOutState vTaskSetTimeOutState * \ingroup TaskCtrl */ void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION; /** - * task.h - * @code{c} - * BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ); - * @endcode * * Determines if pxTicksToWait ticks has passed since a time was captured * using a call to vTaskSetTimeOutState(). The captured time includes the tick @@ -2977,17 +2726,12 @@ void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION; * return uxReceived; * } * @endcode - * \defgroup xTaskCheckForTimeOut xTaskCheckForTimeOut * \ingroup TaskCtrl */ BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION; /** - * task.h - * @code{c} - * BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp ); - * @endcode * * This function corrects the tick count value after the application code has held * interrupts disabled for an extended period resulting in tick interrupts having @@ -3006,7 +2750,6 @@ BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, * @return pdTRUE if moving the tick count forward resulted in a task leaving the * blocked state and a context switch being performed. Otherwise pdFALSE. * - * \defgroup xTaskCatchUpTicks xTaskCatchUpTicks * \ingroup TaskCtrl */ BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp ) PRIVILEGED_FUNCTION; @@ -3016,6 +2759,8 @@ BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp ) PRIVILEGED_FUNCTION; * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES *----------------------------------------------------------*/ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* * THIS FUNCTION MUST NOT BE USED FROM APPLICATION CODE. IT IS ONLY * INTENDED FOR USE WHEN IMPLEMENTING A PORT OF THE SCHEDULER AND IS @@ -3222,6 +2967,7 @@ TaskHandle_t pvTaskIncrementMutexHeldCount( void ) PRIVILEGED_FUNCTION; */ void vTaskInternalSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION; +/** @endcond */ /* *INDENT-OFF* */ #ifdef __cplusplus diff --git a/components/freertos/FreeRTOS-Kernel/include/freertos/timers.h b/components/freertos/FreeRTOS-Kernel/include/freertos/timers.h index 2073c3cdd2..95e9527066 100644 --- a/components/freertos/FreeRTOS-Kernel/include/freertos/timers.h +++ b/components/freertos/FreeRTOS-Kernel/include/freertos/timers.h @@ -53,6 +53,8 @@ * MACROS AND DEFINITIONS *----------------------------------------------------------*/ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* IDs for commands that can be sent/received on the timer queue. These are to * be used solely through the macros that make up the public software timer API, * as defined below. The commands that are sent from interrupts must use the @@ -73,6 +75,7 @@ #define tmrCOMMAND_STOP_FROM_ISR ( ( BaseType_t ) 8 ) #define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR ( ( BaseType_t ) 9 ) +/** @endcond */ /** * Type by which software timers are referenced. For example, a call to @@ -83,12 +86,12 @@ struct tmrTimerControl; /* The old naming convention is used to prevent breaking kernel aware debuggers. */ typedef struct tmrTimerControl * TimerHandle_t; -/* +/** * Defines the prototype to which timer callback functions must conform. */ typedef void (* TimerCallbackFunction_t)( TimerHandle_t xTimer ); -/* +/** * Defines the prototype to which functions used with the * xTimerPendFunctionCallFromISR() function must conform. */ @@ -96,11 +99,6 @@ typedef void (* PendedFunction_t)( void *, uint32_t ); /** - * TimerHandle_t xTimerCreate( const char * const pcTimerName, - * TickType_t xTimerPeriodInTicks, - * BaseType_t xAutoReload, - * void * pvTimerID, - * TimerCallbackFunction_t pxCallbackFunction ); * * Creates a new software timer instance, and returns a handle by which the * created software timer can be referenced. @@ -241,12 +239,6 @@ typedef void (* PendedFunction_t)( void *, #endif /** - * TimerHandle_t xTimerCreateStatic(const char * const pcTimerName, - * TickType_t xTimerPeriodInTicks, - * BaseType_t xAutoReload, - * void * pvTimerID, - * TimerCallbackFunction_t pxCallbackFunction, - * StaticTimer_t *pxTimerBuffer ); * * Creates a new software timer instance, and returns a handle by which the * created software timer can be referenced. @@ -372,7 +364,6 @@ typedef void (* PendedFunction_t)( void *, #endif /* configSUPPORT_STATIC_ALLOCATION */ /** - * void *pvTimerGetTimerID( TimerHandle_t xTimer ); * * Returns the ID assigned to the timer. * @@ -394,7 +385,6 @@ typedef void (* PendedFunction_t)( void *, void * pvTimerGetTimerID( const TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /** - * void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ); * * Sets the ID assigned to the timer. * @@ -416,7 +406,6 @@ 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. * @@ -453,7 +442,6 @@ void vTimerSetTimerID( TimerHandle_t xTimer, BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /** - * TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ); * * Simply returns the handle of the timer service/daemon task. It it not valid * to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started. @@ -461,7 +449,6 @@ BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; /** - * BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait ); * * 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 @@ -514,7 +501,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; 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 * public FreeRTOS timer API functions send commands to the timer service task @@ -557,9 +543,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; 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 * public FreeRTOS timer API functions send commands to the timer service task @@ -638,7 +621,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; 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 * public FreeRTOS timer API functions send commands to the timer service task @@ -677,7 +659,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; 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 * public FreeRTOS timer API functions send commands to the timer service task @@ -802,8 +783,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; 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 * routine. @@ -889,8 +868,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; 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 * routine. @@ -953,9 +930,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; 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 * service routine. @@ -1027,8 +1001,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; 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 * routine. @@ -1115,10 +1087,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION; /** - * 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 @@ -1208,10 +1176,6 @@ BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; /** - * 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 @@ -1245,7 +1209,6 @@ BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; /** - * const char * const pcTimerGetName( TimerHandle_t xTimer ); * * Returns the name that was assigned to a timer when the timer was created. * @@ -1256,7 +1219,6 @@ BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, const char * pcTimerGetName( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */ /** - * void vTimerSetReloadMode( TimerHandle_t xTimer, const BaseType_t xAutoReload ); * * Updates a timer to be either an auto-reload timer, in which case the timer * automatically resets itself each time it expires, or a one-shot timer, in @@ -1274,7 +1236,6 @@ void vTimerSetReloadMode( TimerHandle_t xTimer, const BaseType_t xAutoReload ) PRIVILEGED_FUNCTION; /** - * BaseType_t xTimerGetReloadMode( TimerHandle_t xTimer ); * * Queries a timer to determine if it is an auto-reload timer, in which case the timer * automatically resets itself each time it expires, or a one-shot timer, in @@ -1288,7 +1249,6 @@ void vTimerSetReloadMode( TimerHandle_t xTimer, BaseType_t xTimerGetReloadMode( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /** - * UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer ); * * Queries a timer to determine if it is an auto-reload timer, in which case the timer * automatically resets itself each time it expires, or a one-shot timer, in @@ -1302,7 +1262,6 @@ BaseType_t xTimerGetReloadMode( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /** - * TickType_t xTimerGetPeriod( TimerHandle_t xTimer ); * * Returns the period of a timer. * @@ -1313,7 +1272,6 @@ UBaseType_t uxTimerGetReloadMode( 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 * than the current tick count then the expiry time has overflowed from the @@ -1328,8 +1286,6 @@ TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /** - * BaseType_t xTimerGetStaticBuffer( TimerHandle_t xTimer, - * StaticTimer_t ** ppxTimerBuffer ); * * Retrieve pointer to a statically created timer's data structure * buffer. This is the same buffer that is supplied at the time of @@ -1337,7 +1293,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; * * @param xTimer The timer for which to retrieve the buffer. * - * @param ppxTaskBuffer Used to return a pointer to the timers's data + * @param ppxTimerBuffer Used to return a pointer to the timers's data * structure buffer. * * @return pdTRUE if the buffer was retrieved, pdFALSE otherwise. @@ -1347,6 +1303,8 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; StaticTimer_t ** ppxTimerBuffer ) PRIVILEGED_FUNCTION; #endif /* configSUPPORT_STATIC_ALLOCATION */ +/** @cond !DOC_EXCLUDE_HEADER_SECTION */ + /* * Functions beyond this part are not part of the public API and are intended * for use by the kernel only. @@ -1364,13 +1322,11 @@ BaseType_t xTimerGenericCommand( TimerHandle_t xTimer, UBaseType_t uxTimerGetTimerNumber( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; #endif +/** @endcond */ + #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) /** - * task.h - * @code{c} - * void vApplicationGetTimerTaskMemory( StaticTask_t ** ppxTimerTaskTCBBuffer, StackType_t ** ppxTimerTaskStackBuffer, uint32_t *pulTimerTaskStackSize ) - * @endcode * * This function is used to provide a statically allocated block of memory to FreeRTOS to hold the Timer Task TCB. This function is required when * configSUPPORT_STATIC_ALLOCATION is set. For more information see this URI: https://www.FreeRTOS.org/a00110.html#configSUPPORT_STATIC_ALLOCATION diff --git a/docs/doxygen-known-warnings.txt b/docs/doxygen-known-warnings.txt index 24789964de..e69de29bb2 100644 --- a/docs/doxygen-known-warnings.txt +++ b/docs/doxygen-known-warnings.txt @@ -1,5 +0,0 @@ -semphr.h:line: warning: argument 'pxStaticSemaphore' of command @param is not found in the argument list of xSemaphoreCreateCounting(uxMaxCount, uxInitialCount) -task.h:line: warning: argument 'pxTaskDefinition' of command @param is not found in the argument list of vTaskAllocateMPURegions(TaskHandle_t xTask, const MemoryRegion_t *const pxRegions) -task.h:line: warning: argument 'pxCreatedTask' of command @param is not found in the argument list of vTaskAllocateMPURegions(TaskHandle_t xTask, const MemoryRegion_t *const pxRegions) -task.h:line: warning: argument 'pxTaskDefinition' of command @param is not found in the argument list of vTaskAllocateMPURegions(TaskHandle_t xTask, const MemoryRegion_t *const pxRegions) -task.h:line: warning: argument 'pxCreatedTask' of command @param is not found in the argument list of vTaskAllocateMPURegions(TaskHandle_t xTask, const MemoryRegion_t *const pxRegions) diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index f9a4a5cbb2..209f6b8d06 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -319,11 +319,13 @@ PREDEFINED = \ configSUPPORT_DYNAMIC_ALLOCATION=1 \ configSUPPORT_STATIC_ALLOCATION=1 \ configQUEUE_REGISTRY_SIZE=1 \ + configUSE_MUTEXES=1 \ configUSE_RECURSIVE_MUTEXES=1 \ configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS=1 \ configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \ configUSE_APPLICATION_TASK_TAG=1 \ configTASKLIST_INCLUDE_COREID=1 \ + configUSE_SB_COMPLETED_CALLBACK=1 \ PRIVILEGED_FUNCTION= \ "ESP_EVENT_DECLARE_BASE(x)=extern esp_event_base_t x"