rtos: add instructions and helper code to make FreeRTOS work again

Run-time tested with FreeRTOS V8.1.2 (current version).

For the time being I propose this way of dealing with RTOSes that do
not export necessary information on their own.

I also suggest implementing a similar scheme for ChibiOS, exporting
the necessary struct fields' offsets via an OpenOCD-specific helper.

Change-Id: Iacf8b88004d62206215fe80011fd7592438446a3
Signed-off-by: Paul Fertser <fercerpav@gmail.com>
Signed-off-by: Andreas Fritiofson <andreas.fritiofson@gmail.com>
Reviewed-on: http://openocd.zylin.com/2347
Tested-by: jenkins

contrib/rtos-helpers/FreeRTOS-openocd.c

@@ -0,0 +1,20 @@
+/*
+ * 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;

doc/openocd.texi

@@ -8617,7 +8617,7 @@ _tx_thread_current_ptr, _tx_thread_created_ptr, _tx_thread_created_count.
 @item FreeRTOS symbols
 pxCurrentTCB, pxReadyTasksLists, xDelayedTaskList1, xDelayedTaskList2,
 pxDelayedTaskList, pxOverflowDelayedTaskList, xPendingReadyList,
-xTasksWaitingTermination, xSuspendedTaskList, uxCurrentNumberOfTasks, uxTopUsedPriority.
+uxCurrentNumberOfTasks, uxTopUsedPriority.
 @item linux symbols
 init_task.
 @item ChibiOS symbols
@@ -8630,8 +8630,15 @@ _mqx_kernel_data, MQX_init_struct.
 @end table
 
 For most RTOS supported the above symbols will be exported by default. However for
-some, eg. FreeRTOS @option{xTasksWaitingTermination} is only exported
+some, eg. FreeRTOS, extra steps must be taken.
-if @option{INCLUDE_vTaskDelete} is defined during the build.
+
+These RTOSes may require additional OpenOCD-specific file to be linked
+along with the project:
+
+@table @code
+@item FreeRTOS
+contrib/rtos-helpers/FreeRTOS-openocd.c
+@end table
 
 @node Tcl Scripting API
 @chapter Tcl Scripting API

src/rtos/FreeRTOS.c

@@ -135,7 +135,7 @@ static const struct symbols FreeRTOS_symbol_list[] = {
 	{ "xTasksWaitingTermination", true }, /* Only if INCLUDE_vTaskDelete */
 	{ "xSuspendedTaskList", true }, /* Only if INCLUDE_vTaskSuspend */
 	{ "uxCurrentNumberOfTasks", false },
-	{ "uxTopUsedPriority", false },
+	{ "uxTopUsedPriority", true }, /* Unavailable since v7.5.3 */
 	{ NULL, false }
 };
 
@@ -231,6 +231,10 @@ static int FreeRTOS_update_threads(struct rtos *rtos)
 	}
 
 	/* Find out how many lists are needed to be read from pxReadyTasksLists, */
+	if (rtos->symbols[FreeRTOS_VAL_uxTopUsedPriority].address == 0) {
+		LOG_ERROR("FreeRTOS: uxTopUsedPriority is not defined, consult the OpenOCD manual for a work-around");
+		return ERROR_FAIL;
+	}
 	int64_t max_used_priority = 0;
 	retval = target_read_buffer(rtos->target,
 			rtos->symbols[FreeRTOS_VAL_uxTopUsedPriority].address,