docs: add RTOS Support info

[fw/openocd] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index c34ecb078b08d25f416076b826b2bb4a8bed2e30..78a4e8ed921255489678f9dc52cb90003ad4ac82 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1306,23 +1306,23 @@ hilscher_nxhx500_re.cfg   opendous_ftdi.cfg          vsllink.cfg
 hilscher_nxhx50_etm.cfg   openocd-usb.cfg            xds100v2.cfg
 
 interface/ftdi:
-axm0432.cfg               icebear.cfg                oocdlink.cfg
-calao-usb-a9260-c01.cfg   jtagkey2.cfg               opendous_ftdi.cfg
-calao-usb-a9260-c02.cfg   jtagkey2p.cfg              openocd-usb.cfg
-cortino.cfg               jtagkey.cfg                openocd-usb-hs.cfg
-dlp-usb1232h.cfg          jtag-lock-pick_tiny_2.cfg  openrd.cfg
-dp_busblaster.cfg         kt-link.cfg                redbee-econotag.cfg
-flossjtag.cfg             lisa-l.cfg                 redbee-usb.cfg
-flossjtag-noeeprom.cfg    luminary.cfg               sheevaplug.cfg
-flyswatter2.cfg           luminary-icdi.cfg          signalyzer.cfg
-flyswatter.cfg            luminary-lm3s811.cfg       signalyzer-lite.cfg
+axm0432.cfg               hitex_str9-comstick.cfg    olimex-jtag-tiny.cfg
+calao-usb-a9260-c01.cfg   icebear.cfg                oocdlink.cfg
+calao-usb-a9260-c02.cfg   jtagkey2.cfg               opendous_ftdi.cfg
+cortino.cfg               jtagkey2p.cfg              openocd-usb.cfg
+dlp-usb1232h.cfg          jtagkey.cfg                openocd-usb-hs.cfg
+dp_busblaster.cfg         jtag-lock-pick_tiny_2.cfg  openrd.cfg
+flossjtag.cfg             kt-link.cfg                redbee-econotag.cfg
+flossjtag-noeeprom.cfg    lisa-l.cfg                 redbee-usb.cfg
+flyswatter2.cfg           luminary.cfg               sheevaplug.cfg
+flyswatter.cfg            luminary-icdi.cfg          signalyzer.cfg
+gw16042.cfg               luminary-lm3s811.cfg       signalyzer-lite.cfg
 hilscher_nxhx10_etm.cfg   minimodule.cfg             stm32-stick.cfg
 hilscher_nxhx500_etm.cfg  neodb.cfg                  turtelizer2-revB.cfg
 hilscher_nxhx500_re.cfg   ngxtech.cfg                turtelizer2-revC.cfg
 hilscher_nxhx50_etm.cfg   olimex-arm-usb-ocd.cfg     vpaclink.cfg
 hilscher_nxhx50_re.cfg    olimex-arm-usb-ocd-h.cfg   xds100v2.cfg
 hitex_lpc1768stick.cfg    olimex-arm-usb-tiny-h.cfg
-hitex_str9-comstick.cfg   olimex-jtag-tiny.cfg
 $
 @end example
 @item @file{board} ...
@@ -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.
 
+@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}|
-@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}.
+@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}
+@xref{gdbrtossupport,,RTOS Support}.
 
 @end itemize
 @end deffn
@@ -8108,6 +8110,57 @@ end
 @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