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.

Syntax

#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);

where:

connectId

Connection ID, as returned by TAPOp_OpenConnection.

flags

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

eventMacroNo

The number of the macro to use as eventMacro.

preExecMacroNo

The number of the macro to use as preExecMacro.

executeMacroNo

The number of the macro to use as executeMacro.

postExecMacroNo

The number of the macro to use as postExecMacro.

stopMacroNo

The number of the macro to use as stopMacro.

eventMask

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

eventXOR

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

Return

The function returns:

TAPOp_NoError

No error.

TAPOp_UnableToSelect

Connection could not be made.

TAPOp_NoSuchConnection

The connectId was not recognized.

TAPOp_RPC_Connection_Fail

The RPC connection was lost while processing this request.

TAPOp_UndefinedMacro

A macro number specified has not been defined.

Usage

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

eventMacro

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).

preExecMacro

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.

executeMacro

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.

postExecMacro

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.

stopMacro

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

Note

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).

Example

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_EVENTMAC, ARM9_PREEXECMAC, ARM9_EXECMAC,
                 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
Non-Confidential