From 53c0fb6ef5edd2292c29d048c93f73e2be5fa4ba Mon Sep 17 00:00:00 2001
From: Michel Jaouen <michel.jaouen@stericsson.com>
Date: Mon, 9 May 2011 17:30:55 +0200
Subject: [PATCH] cortex a : smp doc update

---
 doc/openocd.texi | 107 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 2c09febd..892661fd 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1679,6 +1679,64 @@ Again using the at91sam7 as an example, this can look like:
 $_TARGETNAME configure -work-area-phys 0x00200000 \
              -work-area-size 0x4000 -work-area-backup 0
 @end example
+@pxref{Define CPU targets working in SMP}
+@anchor{Define CPU targets working in SMP}
+@subsection Define CPU targets working in SMP
+@cindex SMP
+After setting targets, you can define a list of targets working in SMP.
+
+@example 
+set _TARGETNAME_1 $_CHIPNAME.cpu1
+set _TARGETNAME_2 $_CHIPNAME.cpu2
+target create $_TARGETNAME_1 cortex_a8 -chain-position $_CHIPNAME.dap \
+-coreid 0 -dbgbase $_DAP_DBG1 
+target create $_TARGETNAME_2 cortex_a8 -chain-position $_CHIPNAME.dap \
+-coreid 1 -dbgbase $_DAP_DBG2 
+#define 2 targets working in smp. 
+target smp $_CHIPNAME.cpu2 $_CHIPNAME.cpu1
+@end example
+In the above example on cortex_a8, 2 cpus are working in SMP.
+In SMP only one GDB instance is created and :
+@itemize @bullet
+@item a set of hardware breakpoint sets the same breakpoint on all targets in the list.
+@item halt command triggers the halt of all targets in the list.
+@item resume command triggers the write context and the restart of all targets in the list.
+@item following a breakpoint: the target stopped by the breakpoint is displayed to the GDB session.
+@item dedicated GDB serial protocol packets are implemented for switching/retrieving the target 
+displayed by the GDB session @pxref{Using openocd SMP with GDB}.
+@end itemize
+
+The SMP behaviour can be disabled/enabled dynamically. On cortex_a8 following
+command have been implemented.
+@itemize @bullet
+@item cortex_a8 smp_on : enable SMP mode, behaviour is as described above.
+@item cortex_a8 smp_off : disable SMP mode, the current target is the one
+displayed in the GDB session, only this target is now controlled by GDB
+session. This behaviour is useful during system boot up.
+@item cortex_a8 smp_gdb : display/fix the core id displayed in GDB session see
+following example.
+@end itemize
+
+@example
+>cortex_a8 smp_gdb
+gdb coreid  0 -> -1  
+#0 : coreid 0 is displayed to GDB ,
+#-> -1 : next resume triggers a real resume
+> cortex_a8 smp_gdb 1
+gdb coreid  0 -> 1   
+#0 :coreid 0 is displayed to GDB ,
+#->1  : next resume displays coreid 1 to GDB 
+> resume
+> cortex_a8 smp_gdb  
+gdb coreid  1 -> 1
+#1 :coreid 1 is displayed to GDB ,
+#->1 : next resume displays coreid 1 to GDB
+> cortex_a8 smp_gdb -1
+gdb coreid  1 -> -1
+#1 :coreid 1 is displayed to GDB,
+#->-1 : next resume triggers a real resume
+@end example
+
 
 @subsection Chip Reset Setup
 
@@ -7275,6 +7333,55 @@ $_TARGETNAME configure -event EVENTNAME BODY
 
 To verify any flash programming the GDB command @option{compare-sections}
 can be used.
+@anchor{Using openocd SMP with GDB}
+@section Using openocd SMP with GDB
+@cindex SMP
+For SMP support following GDB serial protocol packet have been defined :
+@itemize @bullet
+@item j - smp status request 
+@item J - smp set request
+@end itemize
+
+OpenOCD implements :
+@itemize @bullet
+@item @option{jc} packet for reading core id displayed by
+GDB connection. Reply is  @option{XXXXXXXX} (8 hex digits giving core id) or
+ @option{E01} for target not smp.
+@item  @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue 
+(core id -1 is reserved for returning to normal resume mode). Reply  @option{E01} 
+for target not smp or @option{OK} on success.
+@end itemize
+
+Handling of this packet within GDB can be done :
+@itemize @bullet
+@item by the creation of an internal variable (i.e @option{_core}) by mean 
+of function allocate_computed_value allowing following GDB command.
+@example
+set $_core 1 
+#Jc01 packet is sent
+print $_core 
+#jc packet is sent and result is affected in $ 
+@end example
+
+@item by the usage of GDB maintenance command as described in following example (2
+cpus in SMP with core id 0 and 1  @pxref{Define CPU targets working in SMP}).
+
+@example
+# toggle0 : force display of coreid 0 
+define toggle0 
+maint packet Jc0 
+continue 
+main packet Jc-1 
+end 
+# toggle1 : force display of coreid 1 
+define toggle1 
+maint packet Jc1 
+continue 
+main packet Jc-1 
+end 
+@end example
+@end itemize
+
 
 @node Tcl Scripting API
 @chapter Tcl Scripting API
-- 
2.39.5