Clarify documentation of xTaskNumber in TaskStatus_t. #1081
Conversation
|
Hi @schilkp |
include/task.h
Outdated
| @@ -161,7 +161,7 @@ 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! */ | |||
| UBaseType_t xTaskNumber; /* A number unique to the task. */ | |||
| UBaseType_t xTaskNumber; /* A number unique to the task. Note that this is not the task number that may be modified using vTaskSetTaskNumber() and vTaskGetTaskNumber, but a separate TCB-specific and unique identifier automatically assigned on task generation. */ | |||
There was a problem hiding this comment.
- uxTaskGetTaskNumber() instead of vTaskGetTaskNumber .
- We should also change
xTaskNumbertouxTasknumberfor naming convention, since its of typeUBaseType_t. I can update this in a separate PR.
There was a problem hiding this comment.
uxTaskGetTaskNumber() instead of vTaskGetTaskNumber.
Good catch. Fixed.
We should also change xTaskNumber to uxTasknumber for naming convention, since its of type UBaseType_t . I can update this in a separate PR.
My original proposal was to rename this member to uxTCBNumber which matches the internal implementation. The member uxTCBNumber in a TCB is the unique ID for each TCB, while uxTaskNumber is the value accessed using the above mentioned functions.
It was my understanding from some posts buried in my discussion (here)[https://forums.freertos.org/t/tracing-improvements/20097/7] that changing the name was not an option because it broken compatibility/kernel-aware debuggers.
If a rename is on the table, I would push for making this much less confusing :)
There was a problem hiding this comment.
I saw this , thanks , yes it will be breaking change in some of the ports.
Discussed here: https://forums.freertos.org/t/tracing-improvements/20097 Adds a note to the (confusingly named) xTaskNumber member of TaskStatus_t explaining that the value is different to the TaskNumber that can be accessed using the vTaskSetTaskNumber and vTaskGetTaskNumber functions. The value returned is actually the value of uxTCBNumber in the TCB.
schilkp
force-pushed
the
schilkp/taskstatus_documentation
branch
from
cefdf25 to
881c540
Compare
|
Discussed here: https://forums.freertos.org/t/tracing-improvements/20097 Adds a note to the (confusingly named) xTaskNumber member of TaskStatus_t explaining that the value is different to the TaskNumber that can be accessed using the vTaskSetTaskNumber and vTaskGetTaskNumber functions. The value returned is actually the value of uxTCBNumber in the TCB.
Description
Discussed here: https://forums.freertos.org/t/tracing-improvements/20097
Adds a note to the (confusingly named) xTaskNumber member of TaskStatus_t explaining that the value is different to the TaskNumber that can be accessed using the vTaskSetTaskNumber and vTaskGetTaskNumber functions.
The value returned is actually the value of uxTCBNumber in the TCB.
Note that documentation on the website should also be updated (https://www.freertos.org/vTaskGetInfo.html#TaskStatus_t). Is this done automatically based on code comments or does this need to be done manually?
Thanks!
Test Steps
N/A
Checklist:
N/A
Related Issue
N/A
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.