target: avoid polling during 'resumed' event handler

[openocd.git] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 4b31cbd0f1aaeaa07678b488b5549f1b0edf1af4..a5b94362f584685ef2bb1cadd30148f06a83fa97 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -5035,6 +5035,19 @@ when reset disables PLLs needed to use a fast clock.
 @* After target hardware trace configuration was changed
 @end itemize
 
+@quotation Note
+OpenOCD events are not supposed to be preempt by another event, but this
+is not enforced in current code. Only the target event @b{resumed} is
+executed with polling disabled; this avoids polling to trigger the event
+@b{halted}, reversing the logical order of execution of their handlers.
+Future versions of OpenOCD will prevent the event preemption and will
+disable the schedule of polling during the event execution. Do not rely
+on polling in any event handler; this means, don't expect the status of
+a core to change during the execution of the handler. The event handler
+will have to enable polling or use @command{$target_name arp_poll} to
+check if the core has changed status.
+@end quotation
+
 @node Flash Commands
 @chapter Flash Commands