diff options
author | David Brownell <dbrownell@users.sourceforge.net> | 2010-03-02 15:45:12 -0800 |
---|---|---|
committer | David Brownell <dbrownell@users.sourceforge.net> | 2010-03-02 15:45:12 -0800 |
commit | d72e90ae4b070cc08799e800c111dd422ac6b1a4 (patch) | |
tree | e3be291c9a89e74b6bf0a9ec31b8b2fe8f205912 | |
parent | 53b3d4dd53eebbf03f481dc59e4bc0259911864a (diff) | |
download | openocd+libswd-d72e90ae4b070cc08799e800c111dd422ac6b1a4.tar.gz openocd+libswd-d72e90ae4b070cc08799e800c111dd422ac6b1a4.tar.bz2 openocd+libswd-d72e90ae4b070cc08799e800c111dd422ac6b1a4.tar.xz openocd+libswd-d72e90ae4b070cc08799e800c111dd422ac6b1a4.zip |
target_resume() doxygen
Add doxygen for target_resume() ... referencing the still-unresolved
confusion about what the "debug_execution" parameter means (not all
CPU support code acts the same).
The 'handle_breakpoints" param seems to have resolved the main issue
with its semantics, but it wasn't part of the function spec before.
Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
-rw-r--r-- | src/target/target.c | 36 |
1 files changed, 33 insertions, 3 deletions
diff --git a/src/target/target.c b/src/target/target.c index 25224083..9596302d 100644 --- a/src/target/target.c +++ b/src/target/target.c @@ -424,6 +424,36 @@ int target_halt(struct target *target) return ERROR_OK; } +/** + * Make the target (re)start executing using its saved execution + * context (possibly with some modifications). + * + * @param target Which target should start executing. + * @param current True to use the target's saved program counter instead + * of the address parameter + * @param address Optionally used as the program counter. + * @param handle_breakpoints True iff breakpoints at the resumption PC + * should be skipped. (For example, maybe execution was stopped by + * such a breakpoint, in which case it would be counterprodutive to + * let it re-trigger. + * @param debug_execution False if all working areas allocated by OpenOCD + * should be released and/or restored to their original contents. + * (This would for example be true to run some downloaded "helper" + * algorithm code, which resides in one such working buffer and uses + * another for data storage.) + * + * @todo Resolve the ambiguity about what the "debug_execution" flag + * signifies. For example, Target implementations don't agree on how + * it relates to invalidation of the register cache, or to whether + * breakpoints and watchpoints should be enabled. (It would seem wrong + * to enable breakpoints when running downloaded "helper" algorithms + * (debug_execution true), since the breakpoints would be set to match + * target firmware being debugged, not the helper algorithm.... and + * enabling them could cause such helpers to malfunction (for example, + * by overwriting data with a breakpoint instruction. On the other + * hand the infrastructure for running such helpers might use this + * procedure but rely on hardware breakpoint to detect termination.) + */ int target_resume(struct target *target, int current, uint32_t address, int handle_breakpoints, int debug_execution) { int retval; @@ -435,9 +465,9 @@ int target_resume(struct target *target, int current, uint32_t address, int hand return ERROR_FAIL; } - /* note that resume *must* be asynchronous. The CPU can halt before we poll. The CPU can - * even halt at the current PC as a result of a software breakpoint being inserted by (a bug?) - * the application. + /* note that resume *must* be asynchronous. The CPU can halt before + * we poll. The CPU can even halt at the current PC as a result of + * a software breakpoint being inserted by (a bug?) the application. */ if ((retval = target->type->resume(target, current, address, handle_breakpoints, debug_execution)) != ERROR_OK) return retval; |