From 6ad9bf3b07ecbe8dd34623c8f81db3b7614cffbf Mon Sep 17 00:00:00 2001 From: Lars Kellogg-Stedman Date: Sat, 11 Mar 2023 06:44:50 -0500 Subject: [PATCH] Expand the esp8266 hardware debugging limitations section (#8879) It's trivial to run into a problem caused by the single hardware breakpoint limitation, but the existing documentation doesn't explicitly address this situation (and search results for the error message aren't particularly helpful). This commit updates the documentation with an explicit example of what happens when a breakpoint expression matches multiple locations, along with a possible workaround. --- doc/gdb.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/gdb.rst b/doc/gdb.rst index 53e9f07fbb..79e221e844 100644 --- a/doc/gdb.rst +++ b/doc/gdb.rst @@ -380,4 +380,33 @@ breakpoint) command in GDB while debugging instead of the more common ``break`` command, since ``thb`` will remove the breakpoint once it is reached automatically and save you some trouble. +Because of the single hardware breakpoint limitation, you must pay careful +attention to the output from ``gdb`` when you set a breakpoint. If your +breakpoint expression matches multiple locations, as in this example: +.. code:: bash + + (gdb) break loop + Breakpoint 1 at 0x40202c84: loop. (2 locations) + +Then you will be unable to ``continue``: + +.. code:: bash + + (gdb) cont + Continuing. + Note: automatically using hardware breakpoints for read-only addresses. + Warning: + Cannot insert hardware breakpoint 1. + Could not insert hardware breakpoints: + You may have requested too many hardware breakpoints/watchpoints. + +You can resolve this situation by deleting the previous breakpoint and +using a more specific breakpoint expression: + +.. code:: bash + + (gdb) delete + Delete all breakpoints? (y or n) y + (gdb) break mysketch.ino:loop + Breakpoint 2 at 0x40202c84: file .../mysketch.ino, line 113.