[PATCH 2/2] Add comment describing continuable/steppable/non-steppable watchpoints

Pedro Alves
2018-08-31T15:12:06Z

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.
---
gdb/gdbarch.h | 2 ++
gdb/gdbarch.sh | 1 +
gdb/target.h | 34 ++++++++++++++++++++++++++++++++++
3 files changed, 37 insertions(+)

diff --git a/gdb/gdbarch.h b/gdb/gdbarch.h
index b563f8d165a..83408812b2a 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 24a553b73c3..941c11b430e 100755
--- a/gdb/gdbarch.sh
+++ b/gdb/gdbarch.sh
@@ -707,6 +707,7 @@ 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 continue, 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 b29d34b8a65..229b5d0551a 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. */

--
2.14.4