2.5.37. TAPOp_SetControlMacros

Define the macro numbers that the Multi-ICE server uses to recognize device events and perform synchronized starting or stopping of processors.


#include “tapop.h”

extern TAPOp_Error TAPOp_SetControlMacros(unsigned8 connectId, unsigned8 flags, unsigned8 eventMacroNo, unsigned8 preExecMacroNo, unsigned8 executeMacroNo, unsigned8 postExecMacroNo, unsigned8 stopMacroNo, ScanData40 *eventMask, ScanData40 *eventXOR);



Connection ID, as returned by TAPOp_OpenConnection.


Various flags (defined in TAPOp inter-client communication flags).


The number of the macro to use as eventMacro.


The number of the macro to use as preExecMacro.


The number of the macro to use as executeMacro.


The number of the macro to use as postExecMacro.


The number of the macro to use as stopMacro.


The mask for detecting an event (see the descriptionof eventMacro in Usage).


XOR for detecting an event (see the description of eventMacro in Usage).


The function returns:


No error.


Connection could not be made.


The connectId was not recognized.


The RPC connection was lost while processing this request.


A macro number specified has not been defined.


Before calling this function, the client must define macros that perform the following functions:


This macro is periodically run by the server while the processor is running, indicated by the state of the private flags set by the debugger. The last line of this macro must be TAPOp_AccessDR_RW or ARMTAP_AccessDR_RW. The result of the data read from this function is ANDed with eventMask and XORed with eventXOR. If the result is zero, an event is recognized. When the server recognizes an event, it runs the stopMacros for other processors if marked for synchronized stopping on the server.

The typical use of eventMacro is to recognize a breakpoint condition. However, this is not the only possible use. Any event that can be recognized using a scan chain read and mask can be set up as a trigger for stopMacro (and stopMacro does not have to be written to stop the processor).


If the TAPOp_PreExecMacroRequired flag is set, this macro is run before the executeMacro because it is used to set up the processor state before actually starting it. The server runs the supplied macros in the following order:

  1. All the preExec macros are run one by one for each processor.

  2. All the execute macros that can be merged are run in one pass of Run-Test/Idle.

  3. Any other execute macros are run.

  4. All the postExec macros are run one by one for each processor.

All of these steps are completed in one block. No other TAPOp operations take place during these steps. The sequence commences when all the processors are ready to start. This happens when the debuggers for all the processors that require sync start have set TAPOp_ProcStartREQ.


This macro is run by the server to start execution of the processor. If the last line of the macro is an IR write and the operation causes the TAP state machine to pass through Run-Test/Idle (as is the case on an ARM processor), the IR writes from all the processors are merged. The whole set of IR registers in the scan chain is written in one operation, and the resulting pass through Run-Test/Idle starts all the processors on the same TCK.


If the TAPOp_PostExecMacroRequired flag is set, this macro is run by the server immediately after the executeMacro because it must be used to tidy up after executeMacro. Because the last line of executeMacro has some constraints (as described in the text for executeMacro), this extra macro can be used to sort out any loose ends. For example, reselecting scan chains and putting INTEST in the IR.


This macro is run to stop the processor. See the description of eventMacro in Usage.


The event, stop, and combined execute macros must all start and stop in a known state, because they can be run in any order by the server.

Any TAPOp operations that a client makes while the processor is running with synchronous stopping enabled must also start and stop in this same state, and must also not deselect until these have finished (to ensure that running one of these macros cannot get in at an inappropriate point).


This example gives an outline of the steps you must take to use the TAPOp_SetControlMacros function.

#define ARM9_EVENTMAC  21
#define ARM9_PREEXECMAC  22
#define ARM9_EXECMAC  23
#define ARM9_POSTEXECMAC  24
#define ARM9_STOPMAC  25
TAPOp_Error defineMacros(void)
    ... define ARM9_EVENTMAC
    ... define ARM9_PREEXECMAC
    ... define ARM9_EXECMAC
    ... define ARM9_POSTEXECMAC
    ... define ARM9_STOPMAC
    ... define any other macros for this device
TAPOp_Error initialiseTarget(void)
    ... make a connection to the target
    if (defineMacros() == TAPOp_NoError) {
        TAPCheck(TAPOp_SetControlMacros(connectId, flags,
                 ARM9_POSTEXECMAC, ARM9_STOPMAC, andMask, xorMask));
        ... other initializations

See also

These TAPOp API functions provide similar or related functionality:

Copyright © 1998-2002 ARM Limited. All rights reserved.ARM DUI 0154B