docs: add RTOS Support info

Currently we have very little info about the RTOS support. This should
improve that.

We also add info about what symbols are required for each supported RTOS.
This can be a trap, certainly when trying to use FreeRTOS support.

Change-Id: Ie57858571daca97515292ff5738a5a5ef55655b7
Signed-off-by: Spencer Oliver <spen@spen-soft.co.uk>
Reviewed-on: http://openocd.zylin.com/1538
Tested-by: jenkins

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 28e69e6f56c3bdaef906c824f4c3709e80eb3e0c..78a4e8ed921255489678f9dc52cb90003ad4ac82 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -4318,9 +4318,11 @@ base @var{address} to be used when an MMU is active.
 The value should normally correspond to a static mapping for the
 @code{-work-area-phys} address, set up by the current operating system.
 
 The value should normally correspond to a static mapping for the
 @code{-work-area-phys} address, set up by the current operating system.
 

+@anchor{rtostype}

 @item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
 @var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{ThreadX}|
 @item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
 @var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{ThreadX}|

-@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}.
+@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}
+@xref{gdbrtossupport,,RTOS Support}.

 
 @end itemize
 @end deffn
 
 @end itemize
 @end deffn


@@ -8108,6 +8110,57 @@ end
 @end example
 @end itemize
 
 @end example
 @end itemize
 

+@section RTOS Support
+@cindex RTOS Support
+@anchor{gdbrtossupport}
+
+OpenOCD includes RTOS support, this will however need enabling as it defaults to disabled.
+It can be enabled by passing @option{-rtos} arg to the target @xref{rtostype,,RTOS Type}
+
+@* An example setup is below:
+
+@example
+$_TARGETNAME configure -rtos auto
+@end example
+
+This will attempt to auto detect the RTOS within your application.
+
+Currently supported rtos's include:
+@itemize @bullet
+@item @option{eCos}
+@item @option{ThreadX}
+@item @option{FreeRTOS}
+@item @option{linux}
+@item @option{ChibiOS}
+@item @option{embKernel}
+@end itemize
+
+@quotation Note
+Before an RTOS can be detected it must export certain symbols otherwise it cannot be used by
+OpenOCD. Below is a list of the required symbols for each supported RTOS.
+@end quotation
+
+@table @code
+@item eCos symbols
+Cyg_Thread::thread_list, Cyg_Scheduler_Base::current_thread.
+@item ThreadX symbols
+_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.
+@item linux symbols
+init_task.
+@item ChibiOS symbols
+rlist, ch_debug, chSysInit.
+@item embKernel symbols
+Rtos::sCurrentTask, Rtos::sListReady, Rtos::sListSleep,
+Rtos::sListSuspended, Rtos::sMaxPriorities, Rtos::sCurrentTaskCount.
+@end table
+
+For most RTOS supported the above symbols will be exported by default. However for
+some, eg. FreeRTOS @option{xTasksWaitingTermination} is only exported
+if @option{INCLUDE_vTaskDelete} is defined during the build.

 
 @node Tcl Scripting API
 @chapter Tcl Scripting API
 
 @node Tcl Scripting API
 @chapter Tcl Scripting API