summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorDavid Brownell <dbrownell@users.sourceforge.net>2010-03-02 15:45:12 -0800
committerDavid Brownell <dbrownell@users.sourceforge.net>2010-03-02 15:45:12 -0800
commitd72e90ae4b070cc08799e800c111dd422ac6b1a4 (patch)
treee3be291c9a89e74b6bf0a9ec31b8b2fe8f205912 /src
parent53b3d4dd53eebbf03f481dc59e4bc0259911864a (diff)
downloadopenocd_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>
Diffstat (limited to 'src')
-rw-r--r--src/target/target.c36
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;