[PATCH] Add OSE operating system support [4/5] doc of remote relocation support

[Hui Zhu]

This is the doc of packet that make remote support relocation.

Thanks,
Hui

2013-03-05  Luis Machado  <lgustavo@codesourcery.com>

	* gdb.texinfo (General Query Packets): Add qXfer:load-map:read.
	(Tools/Packages Optional for Building gdb): Add protocol load
	maps.
	(gdb Remote Serial Protocol): Add load map format.
-------------- next part --------------
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18186,6 +18186,10 @@ are:
 @tab @code{qXfer:libraries:read}
 @tab @code{info sharedlibrary}
 
+@item @code{load-map}
+@tab @code{qXfer:load-map:read}
+@tab Target load addresses
+
 @item @code{memory-map}
 @tab @code{qXfer:memory-map:read}
 @tab @code{info mem}
@@ -34756,6 +34760,8 @@ Expat is used for:
 @item
 Remote protocol memory maps (@pxref{Memory Map Format})
 @item
+Remote protocol load maps (@pxref{Load Map Format})
+@item
 Target descriptions (@pxref{Target Descriptions})
 @item
 Remote shared library lists (@xref{Library List Format},
@@ -35622,6 +35628,7 @@ Show the current setting of the target w
 * File-I/O Remote Protocol Extension::
 * Library List Format::
 * Library List Format for SVR4 Targets::
+* Load Map Format::
 * Memory Map Format::
 * Thread List Format::
 * Traceframe Info Format::
@@ -36913,6 +36920,7 @@ digits).  See @code{remote.c:parse_threa
 @item qOffsets
 @cindex section offsets, remote request
 @cindex @samp{qOffsets} packet
+@anchor{qOffsets}
 Get section offsets that the target used when relocating the downloaded
 image.
 
@@ -36940,6 +36948,10 @@ as many segments as mentioned in the rep
 kept at fixed offsets relative to the last relocated segment.
 @end table
 
+See @ref{qXfer load map read} for an alternative packet that allows
+reporting absolute section load addresses, and a variable number of
+section or segment load addresses.
+
 @item qP @var{mode} @var{thread-id}
 @cindex thread information, remote request
 @cindex @samp{qP} packet
@@ -37258,6 +37270,11 @@ These are the currently defined stub fea
 @tab @samp{-}
 @tab Yes
 
+@item @samp{qXfer:load-map:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
 @item @samp{qXfer:memory-map:read}
 @tab No
 @tab @samp{-}
@@ -37415,6 +37432,10 @@ The remote stub understands the @samp{qX
 The remote stub understands the @samp{qXfer:libraries-svr4:read} packet
 (@pxref{qXfer svr4 library list read}).
 
+@item qXfer:load-map:read
+The remote stub understands the @samp{qXfer:load-map:read} packet
+(@pxref{qXfer load map read}).
+
 @item qXfer:memory-map:read
 The remote stub understands the @samp{qXfer:memory-map:read} packet
 (@pxref{qXfer memory map read}).
@@ -37689,6 +37710,22 @@ This packet is optional for better perfo
 This packet is not probed by default; the remote stub must request it,
 by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
 
+@item qXfer:load-map:read::@var{offset},@var{length}
+@anchor{qXfer load map read}
+
+Return the list of segment or section load addresses of the main
+executable, which report where the program was loaded in memory.
+@xref{Load Map Format}.  The annex part of the generic @samp{qXfer}
+packet must be empty (@pxref{qXfer read}).
+
+@emph{Note: This packet presently does not support relative section
+offsets.  @xref{qOffsets}, for an alternative packet that should suit
+most simple needs.}
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}).
+
 @item qXfer:memory-map:read::@var{offset},@var{length}
 @anchor{qXfer memory map read}
 Access the target's @dfn{memory-map}.  @xref{Memory Map Format}.  The
@@ -40179,6 +40216,60 @@ The format of an SVR4 library list is de
 <!ATTLIST library            l_ld    CDATA   #REQUIRED>
 @end smallexample
 
+@node Load Map Format
+@section Load Map Format
+@cindex load map format, remote protocol
+
+On some platforms, the target relocates the downloaded image to load
+addresses different from the image's VMAs.
+
+The @samp{qXfer:load-map:read} packet returns an XML document which
+lists the segment or section load addresses of the main executable,
+which report where the program was loaded in memory.
+
+The segment or section bases are start addresses, not relocation
+offsets; they do not depend on the program's link-time base addresses.
+
+@value{GDBN} must be linked with the Expat library to support XML load
+maps.  @xref{Expat}.
+
+A simple load map, where the executable is relocated by a single
+offset, looks like this:
+
+@smallexample
+<load-map>
+  <segment address="0x10000000"/>
+</load-map>
+@end smallexample
+
+Another simple load map, for a program with three allocated sections
+(.text, .data, .bss), looks like this:
+
+@smallexample
+<load-map>
+  <section address="0x10000000"/>
+  <section address="0x20000000"/>
+  <section address="0x30000000"/>
+</load-map>
+@end smallexample
+
+The format of the offsets list is described by this DTD:
+
+@smallexample
+<!-- load-map: Root element with versioning -->
+<!ELEMENT load-map  (segment*, section*)>
+<!ATTLIST load-map  version CDATA   #FIXED  "1.0">
+
+<!ELEMENT segment       EMPTY>
+<!ATTLIST segment       address CDATA   #REQUIRED>
+
+<!ELEMENT section       EMPTY>
+<!ATTLIST section       address CDATA   #REQUIRED>
+@end smallexample
+
+In addition, segments and section descriptors cannot be mixed within
+the load map, and you must supply at least one segment or section.
+
 @node Memory Map Format
 @section Memory Map Format
 @cindex memory map format