[OpenOCD-devel] Target examination: what it was, what it is, and what it should become

[Paul F. <fer...@gm...>]

Hello,

In this mail I'll try to outline my understanding of the concept of
"target examination" as used in the OpenOCD source. Please keep in
mind that when I describe history and motivation behind it, I'm just
writing down my guesses based on reading and using the current code,
so that's not exactly accurate.


* What examination was

Examination is a target-level process, so it shouldn't be confused
with JTAG tap IDCODE checks and the like. The idea is that before
working with a specific target we need to learn (discover) some
specific properties of it, e.g. number of hardware breakpoints it
supports. This was supposed to be non-intrusive and needed to be
performed only once as OpenOCD is not meant to be used with
dynamically attached and detached targets in one session (apart from
taps' enable/disable operation, see below). Before the target
examination no target-specific actions (this includes reset
operations) can be performed.

During the OpenOCD configuration stage one is supposed to define all
the jtag taps that are available on the specific jtag chain and all
the targets that are attached to those taps. A tap might be runtime
enabled or disabled (e.g. TI SoCs embed an ICEPick JTAG router that
attaches or detaches various parts from the chain).

So naturally target examination is done in the following cases:

1. Once on OpenOCD start, during the implicit or explicit "init";
2. After enabling of a tap which has a target connected
3. As part of user-invoked "reset" after "reset-start" event handler
   and before "reset-assert-pre" (to allow working with targets that
   were unavailable for whatever reason);

The target-specific examination code usually checks if the target was
already examined and skips the procedure on subsequent invocations.

The poll routine skips targets that were not examined to avoid errors
but if examination after user issues "reset" succeeds, this target
gets polled regularly from that moment till OpenOCD shutdown.


* What examination is

Implementation of support for various targets proved that examination
can't be just that, examination. Many targets require some specific
operations to init debug access (e.g. bringing up debug power domains
in Cortex-M and Cortex-A). Since there was no better place,
examination was made to also initialise hardware breakpoint units and
the like. The features creeped in but design rationale and
requirements documentation is somewhat lacking and unclear, so
contributors couldn't get a consistent and full picture. See [1].

Some time ago I wanted to get reliable operation with targets that get
disconnected from the debug adapter (and/or fully power-cycled) for
whatever reasons while OpenOCD keeps running. In my specific case it
was an STM32L1 going to deep sleep (and we were measuring current
during that). I noticed that after it's powered on again the polling
succeeds and debug continues to work but the breakpoint unit (DWT) was
in inconsistent state.

The only solution to this problem without extending the current API
was to call examine once again once after polling succeeded for the
first time after failure. This proved to be insufficient for Cortex-A
targets as they can't be polled after reset or power-cycle before
debug regions are properly powered up which was done as part of
examination. So the right thing to do was [2] (every time poll fails,
try to re-examine), but Cortex-A still couldn't be reset properly
because "reset" is calling "arp_examine" which wasn't working without
debug power domains init, so [3] is proposed. It was sort of working
before until [4] was committed which removed an obvious layering
violation.


* What examination should become

This section is a speculation based on my current view, and it's meant
to be discussed.

I propose that:

1. Status quo is documented
2. Target-specific code is reviewed to be consistent and correct to:
   1. Do everything needed to establish initial communication _every_
      time examine is called
   2. Not leak memory and other resources on subsequent invocations
3. Regular testing of existing and future targets includes runtime
   disconnecting (or otherwise disrupting) debug communication and
   physical power-cycling, OpenOCD should handle that gracefully.

[1] http://openocd.org/doc/doxygen/html/structtarget__type.html#a2e87b29bce8308f8eb7a09f56686228f
[2] http://openocd.zylin.com/#/c/2721
[3] http://openocd.zylin.com/#/c/2723
[4] 20a077eadbeea77ed3f4d75fbe23b6f2db891dd8

-- 
Be free, use free (http://www.gnu.org/philosophy/free-sw.html) software!
mailto:fer...@gm...