[BUG] Re-introduce uxTopUsedPriority for OpenOCD Thread Support

[dereks]

OpenOCD is a popular Open Source On-Chip Debugger:

http://openocd.org/

One of its best features is thread support (Task support). With OpenOCD, the GNU gdb debugger can view the list of Tasks, and can look at an individual Task to see its stack trace, step through code in just that one Task, etc Basically, OpenOCD enables these gdb features:

https://ftp.gnu.org/old-gnu/Manuals/gdb/html_node/gdb_24.html

(Eclipse also has desktop GUI support for walking through OpenOCD Tasks, much like a normal POSIX threaded program.)

Without thread support, gdb is very restricted and hard to use with a FreeRTOS application. For example, constant SysTick interrupts keep jumping you into the scheduler, making it very hard to follow your application code. It's basically only useful for debugging main() and ISRs.

In an older release of FreeRTOS (V7.5.3) there was a symbol removed called uxTopUsedPriority. That symbol is necessary for OpenOCD to find the list of Tasks and enable thread support.

Since that release, we developers have had to manually re-introduce that symbol so that we can debug our FreeRTOS apps. Usually this means adding a copy of this file to the build:

https://raw.githubusercontent.com/arduino/OpenOCD/master/contrib/rtos-helpers/FreeRTOS-openocd.c

Here is that entire file:

/*
 * Since at least FreeRTOS V7.5.3 uxTopUsedPriority is no longer
 * present in the kernel, so it has to be supplied by other means for
 * OpenOCD's threads awareness.
 *
 * Add this file to your project, and, if you're using --gc-sections,
 * ``--undefined=uxTopUsedPriority'' (or
 * ``-Wl,--undefined=uxTopUsedPriority'' when using gcc for final
 * linking) to your LDFLAGS; same with all the other symbols you need.
 */

#include "FreeRTOS.h"

#ifdef __GNUC__
#define USED __attribute__((used))
#else
#define USED
#endif

const int USED uxTopUsedPriority = configMAX_PRIORITIES - 1;

Some distributions of FreeRTOS, like WICED SDK, already put this back for you.

The Internet is littered with forum posts of developers asking why they can't debug FreeRTOS Tasks, and responses telling them about this annoying requirement. Just google "uxTopUsedPriority" to see what I'm talking about.

So: Could FreeRTOS please re-add the uxTopUsedPriority symbol, and then never remove it again?

[yuhui-zheng]

Being a developer myself, this issue hit my pain point. Will take a look, and thanks!

[RichardBarry]

Looking at how this was used I think you can just set it to configMAX_PRIORITIES - 1:

[code]
static const UBaseType_t uxTopUsedPriority = configMAX_PRIORITEIS - 1;
[/code]

The tricky thing will be preventing compilers removing the system as unused as the syntax required to prevent symbols being removed is dependent on the compiler. If it is removed then we would have to make it volatile and set it manually at run time.

[RichardBarry]

[note sure this is a bug, by the way, so perhaps https://forums.freertos.org would be a better place to discuss]

[dereks]

I think you can just set it to configMAX_PRIORITIES - 1:

Confirmed, that is exactly what the linked example file does (albeit with int instead of UBaseType_t).

The tricky thing will be preventing compilers removing the system as unused as the syntax required to prevent symbols being removed is dependent on the compiler. If it is removed then we would have to make it volatile and set it manually at run time.

Agree that this is tricky. The example file has a comment that discusses using the -Wl,--undefined to gcc for the final linking, to allow the keeping of this unused (at runtime) symbol. It also makes use of the following define:

#define USED __attribute__((used))

That __attribute__((used)) works on GCC and Keil, but maybe not other compilers.

I believe the best solution is that this linking issue would need to be part of the documentation, because most compilers would throw away an unused symbol by default.

As far as re-introducing uxTopUsedPriority, having it removed by the compiler during linking (by default) means it does no harm, and doesn't even introduce another 4 bytes of program space, which is actually the preferred behavior. If you want to do debugging with gdb it is not unreasonable to add a linker flag to your build time options. It's much easier than having to introduce a non-standard special file into version control just to allow debugging.

[dachalco]

I agree with Richard in that there may be a more portable way to support this with less dependency on compiler specific attributes. To add to his point, we could also initialize at declaration instead of assigning value in a runtime call, while still retaining the symbol via a void-cast. Consider the following:

#define configMAX_PRIORITIES 16

const volatile int uxTopUsedPriority = configMAX_PRIORITIES - 1;

int main(int argc, char **argv)
{
    (void)uxTopUsedPriority;
    
    return 0;
}

Tried this out with

arm-none-eabi-gcc -fdata-sections -ffunction-sections -O3 --specs=nosys.specs symbol-keep.c -o arm-symbol-keep -Wl,--gc-sections

and

clang -fdata-sections -ffunction-sections -O3 symbol-keep.c -o symbol-keep -Wl,-dead_strip

In each case arm-none-eabi-objdump and objdump respectively reported uxTopUsedPriority in executable's symbol table. Handling of volatile is mandated by c-standard but further verification would be needed into what, if any, liberties compilers have with respect to such void-casts.

[dachalco]

Thanks All,

This issue has been addressed in the merged PR #188.