Add file missing from r11791 due to insufficient coffee.

#214909 c 101.  (Philippe Waroquiers, philippe.waroquiers@skynet.be)



git-svn-id: svn://svn.valgrind.org/valgrind/trunk@11792

docs/Makefile.am

@@ -25,6 +25,7 @@ EXTRA_DIST = \
 	internals/3_3_BUGSTATUS.txt \
 	internals/3_4_BUGSTATUS.txt \
 	internals/3_5_BUGSTATUS.txt \
+	internals/arm_thumb_notes_gdbserver.txt \
 	internals/BIG_APP_NOTES.txt \
 	internals/Darwin-notes.txt \
 	internals/directory-structure.txt \

docs/internals/arm_thumb_notes_gdbserver.txt

@@ -0,0 +1,90 @@
+(for general information
+  about gdbserver, read coregrind/m_gdbserver/README_DEVELOPPERS
+  about gdbserver tests, read gdbserver_tests/README_DEVELOPPERS).
+
+ARM thumb and gdbserver
+-----------------------
+
+When executing thumb code, the ARM cpu program counter value is
+not equal to the address of the instruction being executed: the fact
+that the instruction being executed is a thumb instruction is
+encoded in the bit0 of the program counter.
+For more information about this, see VEX/pub/libvex_guest_arm.h.
+
+This additional bit set in the ARM guest_IP caused some difficulties
+at several places in the gdbserver code.
+
+
+* breakpoint handling:
+  gdbsrv code detects that a breakpoint is reached
+  by comparing the current guest_IP with the breakpoint addresses given
+  by gdb. As gdb is giving breakpoints without the thumb bit set,
+  the gdbsrv code has to ensure breakpoint comparisons are done without
+  the thumb bit.
+  => the breakpoints are stored in the gdbserver breakpoints hash table
+  without the thumb bit.
+  => when the guest_IP is compared with these breakpoints, the thumb bit
+  must be masked.
+
+* Thumb bit in IstMark:
+  When instrumenting a SB for gdbserver, a PUT of the current instruction
+  address is done to the IP, to ensure that the gdbserver helper call
+  sees the correct IP. This PUT must be done with the thumb bit set,
+  as this value will be given back to gdb. gdb uses the thumb bit a.o.
+  to guess the next program counter after this instruction.
+  Such a guess is needed for gdb commands such as next/step/...
+  If the thumb bit is not properly set, these commands are not working.
+  As gdbserver instrumentation code uses the IstMark to find the IP
+  of the instruction being instrumented, the thumb bit must be accessible
+  or found. Multiple approaches were tried (see below) before the
+  current one (which is to have a field Delta in IstMark which encodes
+  the thumb bit).
+
+* Thumb bit in extents
+  When a breakpoint is placed at an instruction, the translation for this
+  instruction must be discarded to have the SB re-instrumented for gdbserver.
+  At least at this moment (r2155/r11786), the extents for ARM/thumb blocks
+  contains addresses with the thumb bit set. It is not clear that this is
+  a good thing: extents should preferrably reference the real address range of
+  instructions, not an adress range which can be "off by one" due to the
+  fact that the instruction is a thumb instruction.
+ 
+  Due to this "off by one", gdbserver is discarding a range of two bytes
+  to ensure it is not sensitive to the presence (or not) of the thumb
+  bit in the range being discarded.
+
+* Handling of monitor vg.translate
+  When the translation is requested, the thumb bit must be properly set
+  in the address, as this bit is used by the Valgrind translator
+  to decide to decode in ARM or in thumb mode.
+  The monitor command guesses the thumb bit based on the debug information.
+
+* gdb 7.0 is buggy with thumb code
+  The logic of gdb to guess the next PC in thumb code is not working
+  properly in version gdb 7.0. Several gdbserver tests are disabled
+  on ARM if gdb version is < 7.1.
+
+* The (historical) list of difficulties encountered is the following:
+  - initially, IstMark contained the thumb bit in the addr.
+    This caused the breakpoints to not work (comparison between
+    gdb address and gdbserver failed).
+    (see breakpoint handling above).
+  - A change was done to mask the thumb bit in the IstMark
+    This made breakpoints work, but then gdb next/step/... was then failing
+    (see Thumb bit in IstMark above).
+  - So, it was needed to have the thumb bit when instrumenting an
+    IstMark. 3 solutions were looked at:
+     * use the debug info : this solution was discarded as often debug
+       info does not allow a 100% correct solution. debug info is acceptable
+       for vg.translate (which is only for internal valgrind debugging),
+       but is better not used for 'end user functionnality'.
+     * Derive the thumb bit for a SB from the extent address.
+       This was discarded as this implies that an SB cannot mix thumb
+       and ARM code. This implied to disable chasing at transition between
+       ARM/thumb code, which potentially decreases performance.
+       Also, it would oblige to keep the thumb bit in the extents, which
+       seems not nice.
+     * the final solution implemented was to add a Delta fied in IstMark.
+       This Delta field gives the delta to add to the IstMark addr field
+       to obtain the guest_IP : for thumb code, this field is 1,
+       and is 0 for ARM code and for all other architectures.