Improve target.h & target_ops & xfer_partial descriptions

Working backwards in terms of motivation for the patch:

- When accessing memory via the xfer_partial interface, the process
  that we're accessing is indicated by inferior_ptid.  This can be
  either the same process as current inferior, or a fork child which
  does not exist in the inferior list.  This is not documented
  currently.  This commit fixes that.

- For target delegation to work, we must always make the inferior we
  want to call the target method on, the current inferior.  This
  wasn't documented, AFAICT, so this commit fixes that too.  I put
  that in the intro comment to target_ops.

- I actually started writing a larger intro comment to target_ops, as
  there was seemingly none, which I did find odd.  However, I then
  noticed the description closer to the top of the file.  I missed it
  the first time, because for some reason, that intro comment is no
  longer at the top of the file, as #includes etc. have been added
  above it over the years.  This commit fixes that too, by moving that
  intro comment to the top.

Change-Id: Id21f5462947f2a0f6f3ac0c42532df62ba355914
Approved-By: Simon Marchi <simon.marchi@efficios.com>
Approved-By: Tom Tromey <tom@tromey.com>

1 files changed, 51 insertions, 24 deletions

diff --git a/gdb/target.h b/gdb/target.h
index 486a0a6..394e377 100644
--- a/gdb/target.h
+++ b/gdb/target.h
@@ -19,6 +19,28 @@
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
 
+/* This include file defines the interface between the main part of
+   the debugger, and the part which is target-specific, or specific to
+   the communications interface between us and the target.
+
+   A TARGET is an interface between the debugger and a particular
+   kind of file or process.  Targets can be STACKED in STRATA,
+   so that more than one target can potentially respond to a request.
+   In particular, memory accesses will walk down the stack of targets
+   until they find a target that is interested in handling that particular
+   address.  STRATA are artificial boundaries on the stack, within
+   which particular kinds of targets live.  Strata exist so that
+   people don't get confused by pushing e.g. a process target and then
+   a file target, and wondering why they can't see the current values
+   of variables any more (the file target is handling them and they
+   never get to the process target).  So when you push a file target,
+   it goes into the file stratum, which is always below the process
+   stratum.
+
+   Note that rather than allow an empty stack, we always have the
+   dummy target at the bottom stratum, so we can call the target
+   methods without checking them.  */
+
 #if !defined (TARGET_H)
 #define TARGET_H
 
@@ -48,30 +70,6 @@ typedef const gdb_byte const_gdb_byte;
 #include "gdbsupport/scoped_restore.h"
 #include "gdbsupport/refcounted-object.h"
 #include "target-section.h"
-
-/* This include file defines the interface between the main part
-   of the debugger, and the part which is target-specific, or
-   specific to the communications interface between us and the
-   target.
-
-   A TARGET is an interface between the debugger and a particular
-   kind of file or process.  Targets can be STACKED in STRATA,
-   so that more than one target can potentially respond to a request.
-   In particular, memory accesses will walk down the stack of targets
-   until they find a target that is interested in handling that particular
-   address.  STRATA are artificial boundaries on the stack, within
-   which particular kinds of targets live.  Strata exist so that
-   people don't get confused by pushing e.g. a process target and then
-   a file target, and wondering why they can't see the current values
-   of variables any more (the file target is handling them and they
-   never get to the process target).  So when you push a file target,
-   it goes into the file stratum, which is always below the process
-   stratum.
-
-   Note that rather than allow an empty stack, we always have the
-   dummy target at the bottom stratum, so we can call the target
-   methods without checking them.  */
-
 #include "target/target.h"
 #include "target/resume.h"
 #include "target/wait.h"
@@ -433,6 +431,24 @@ struct target_info
   const char *doc;
 };
 
+/* A GDB target.
+
+   Each inferior has a stack of these.  See overall description at the
+   top.
+
+   Most target methods traverse the current inferior's target stack;
+   you call the method on the top target (normally via one of the
+   target_foo wrapper free functions), and the implementation of said
+   method does its work and returns, or defers to the same method on
+   the target beneath on the current inferior's target stack.  Thus,
+   the inferior you want to call the target method on must be made the
+   current inferior before calling a target method, so that the stack
+   traversal works correctly.
+
+   Methods that traverse the stack have a TARGET_DEFAULT_XXX marker in
+   their declaration below.  See the macros' description above, where
+   they're defined.  */
+
 struct target_ops
   : public refcounted_object
   {
@@ -784,6 +800,17 @@ struct target_ops
        starting point.  The ANNEX can be used to provide additional
        data-specific information to the target.
 
+       When accessing memory, inferior_ptid indicates which process's
+       memory is to be accessed.  This is usually the same process as
+       the current inferior, however it may also be a process that is
+       a fork child of the current inferior, at a moment that the
+       child does not exist in GDB's inferior lists.  This happens
+       when we remove software breakpoints from the address space of a
+       fork child process that we're not going to stay attached to.
+       Because the fork child is a clone of the fork parent, we can
+       use the fork parent inferior's stack for target method
+       delegation.
+
        Return the transferred status, error or OK (an
        'enum target_xfer_status' value).  Save the number of addressable units
        actually transferred in *XFERED_LEN if transfer is successful