[binutils-gdb] Add comment describing continuable/steppable/non-steppable watchpoints

[Pedro Alves <palves at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=7ea65f08fa1b8279b65133a958de02fe84767eb9

commit 7ea65f08fa1b8279b65133a958de02fe84767eb9
Author: Pedro Alves <palves@redhat.com>
Date:   Fri Aug 31 14:24:13 2018 +0100

    Add comment describing continuable/steppable/non-steppable watchpoints
    
    These weren't described anywhere in the sources.
    
    gdb/ChangeLog:
    2018-08-31  Pedro Alves  <palves@redhat.com>
    
    	* gdbarch.sh (have_nonsteppable_watchpoint): Add comment.
    	* target.h (Hardware watchpoint interfaces): Describe
    	continuable/steppable/non-steppable watchpoints.
    	* gdbarch.h, gdbarch.c: Regenerate.

Diff:
---
 gdb/ChangeLog  |  7 +++++++
 gdb/gdbarch.h  |  2 ++
 gdb/gdbarch.sh |  2 ++
 gdb/target.h   | 34 ++++++++++++++++++++++++++++++++++
 4 files changed, 45 insertions(+)

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 30c0c6f..0b8ed31 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,5 +1,12 @@
 2018-08-31  Pedro Alves  <palves@redhat.com>
 
+	* gdbarch.sh (have_nonsteppable_watchpoint): Add comment.
+	* target.h (Hardware watchpoint interfaces): Describe
+	continuable/steppable/non-steppable watchpoints.
+	* gdbarch.h, gdbarch.c: Regenerate.
+
+2018-08-31  Pedro Alves  <palves@redhat.com>
+
 	* nto-procfs.c (nto_procfs_target::have_continuable_watchpoint):
 	Delete.
 	* s390-linux-nat.c
diff --git a/gdb/gdbarch.h b/gdb/gdbarch.h
index b563f8d..8340881 100644
--- a/gdb/gdbarch.h
+++ b/gdb/gdbarch.h
@@ -818,6 +818,8 @@ extern void set_gdbarch_adjust_dwarf2_line (struct gdbarch *gdbarch, gdbarch_adj
 extern int gdbarch_cannot_step_breakpoint (struct gdbarch *gdbarch);
 extern void set_gdbarch_cannot_step_breakpoint (struct gdbarch *gdbarch, int cannot_step_breakpoint);
 
+/* See comment in target.h about continue, steppable and non-steppable watchpoints. */
+
 extern int gdbarch_have_nonsteppable_watchpoint (struct gdbarch *gdbarch);
 extern void set_gdbarch_have_nonsteppable_watchpoint (struct gdbarch *gdbarch, int have_nonsteppable_watchpoint);
 
diff --git a/gdb/gdbarch.sh b/gdb/gdbarch.sh
index 24a553b..670ac30 100755
--- a/gdb/gdbarch.sh
+++ b/gdb/gdbarch.sh
@@ -707,6 +707,8 @@ f;CORE_ADDR;adjust_dwarf2_addr;CORE_ADDR pc;pc;;default_adjust_dwarf2_addr;;0
 # stop PC.
 f;CORE_ADDR;adjust_dwarf2_line;CORE_ADDR addr, int rel;addr, rel;;default_adjust_dwarf2_line;;0
 v;int;cannot_step_breakpoint;;;0;0;;0
+# See comment in target.h about continuable, steppable and
+# non-steppable watchpoints.
 v;int;have_nonsteppable_watchpoint;;;0;0;;0
 F;int;address_class_type_flags;int byte_size, int dwarf2_addr_class;byte_size, dwarf2_addr_class
 M;const char *;address_class_type_flags_to_name;int type_flags;type_flags
diff --git a/gdb/target.h b/gdb/target.h
index b29d34b..229b5d0 100644
--- a/gdb/target.h
+++ b/gdb/target.h
@@ -1905,6 +1905,40 @@ extern struct thread_info *target_thread_handle_to_thread_info
 
 /* Hardware watchpoint interfaces.  */
 
+/* GDB's current model is that there are three "kinds" of watchpoints,
+   with respect to when they trigger and how you can move past them.
+
+   Those are: continuable, steppable, and non-steppable.
+
+   Continuable watchpoints are like x86's -- those trigger after the
+   memory access's side effects are fully committed to memory.  I.e.,
+   they trap with the PC pointing at the next instruction already.
+   Continuing past such a watchpoint is doable by just normally
+   continuing, hence the name.
+
+   Both steppable and non-steppable watchpoints trap before the memory
+   access.  I.e, the PC points at the instruction that is accessing
+   the memory.  So GDB needs to single-step once past the current
+   instruction in order to make the access effective and check whether
+   the instruction's side effects change the watched expression.
+
+   Now, in order to step past that instruction, depending on
+   architecture and target, you can have two situations:
+
+   - steppable watchpoints: you can single-step with the watchpoint
+     still armed, and the watchpoint won't trigger again.
+
+   - non-steppable watchpoints: if you try to single-step with the
+     watchpoint still armed, you'd trap the watchpoint again and the
+     thread wouldn't make any progress.  So GDB needs to temporarily
+     remove the watchpoint in order to step past it.
+
+   If your target/architecture does not signal that it has either
+   steppable or non-steppable watchpoints via either
+   target_have_steppable_watchpoint or
+   gdbarch_have_nonsteppable_watchpoint, GDB assumes continuable
+   watchpoints.  */
+
 /* Returns non-zero if we were stopped by a hardware watchpoint (memory read or
    write).  Only the INFERIOR_PTID task is being queried.  */