From ac07c23e376fd5b3de67d96e937d65622da2d17a Mon Sep 17 00:00:00 2001 From: Alexey Gerenkov Date: Thu, 16 Aug 2018 21:33:23 +0300 Subject: [PATCH] docs: Adds description of OpenOCD command to configure custom app image location --- docs/en/api-guides/jtag-debugging/index.rst | 1 + .../jtag-debugging/tips-and-quirks.rst | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index 16ab37d78a..c74609fdf3 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -281,6 +281,7 @@ This section provides collection of links to all tips and quirks referred to fro * :ref:`jtag-debugging-tip-breakpoints` * :ref:`jtag-debugging-tip-where-breakpoints` +* :ref:`jtag-debugging-tip-flash-mappings` * :ref:`jtag-debugging-tip-why-next-works-as-step` * :ref:`jtag-debugging-tip-code-options` * :ref:`jtag-debugging-tip-freertos-support` diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index e104ff0ff4..e473873f35 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -20,6 +20,25 @@ What else should I know about breakpoints? Emulating part of hardware breakpoints using software flash ones means that the GDB command ``hb myFunction`` which is invoked for function in flash will use pure hardware breakpoint if it is avalable otherwise one of the 32 software flash breakpoints is used. The same rule applies to ``b myFunction``-like commands. In this case GDB will decide what type of breakpoint to set itself. If ``myFunction`` is resided in writable region (IRAM) software IRAM breakpoint will be used otherwise hardware or software flash breakpoint is used as it is done for ``hb`` command. +.. _jtag-debugging-tip-flash-mappings: + +Flash Mappings vs SW Flash Breakpoints +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the ESP32 address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format: + +``esp32 appimage_offset `` + +Offset should be in hex format. To reset to the default behaviour you can specify ``-1`` as offset. + +.. note:: + + Since GDB requests memory map from OpenOCD only once when connecting to it, this command should be specified in one of the TCL configuration files, or passed to OpenOCD via its command line. In the latter case command line should look like below: + + ``bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg -c "init; halt; esp32 appimage_offset 0x210000"`` + + Another option is to execute that command via OpenOCD telnet session and then connect GDB, but it seems to be less handy. + .. _jtag-debugging-tip-why-next-works-as-step: Why stepping with "next" does not bypass subroutine calls?