2.5.17. TAPOp_DefineMacro

Adds a single TAPOp or ARMTAP function call to a macro.

Syntax

#include “tapmacro.h”

extern TAPOp_Error TAPOp_DefineMacro((unsigned8 connectId, unsigned8 macroNo, char *callDetails, unsigned8 nTimes, void *fixedParamValues, int paramSize);

where:

connectId

Connection ID, as returned by TAPOp_OpenConnection.

macroNo

The number of the macro. This is a client selectedinteger that identifies the macro to append to. Macros are not shared between connections.

callDetails

This is a string that is interpreted according to the following rules:

fn-name

Is used if there are no fixed parameters for this invocation.

fn-name:list

Is used if there are fixed parameters.

fn-name must be the name of a TAPOp or ARMTAP function. For example, ARMTAP_AccessDR_W.

The list defines the parameters of the call that are fixed, and their values must be specified in fixedParamValues. Parameters that are not listed in callDetails are variable parameters. These are specified as arguments to the function TAPOp_RunMacro.

A callDetails specification consists of a sequence of digits and uppercase letters in increasing order, digits first. Each digit or letters refers to a structure element in the corresponding MAC_xxx structure defined in macstruct.h, starting at 1.

nTimes

The number of times the line of this macro is executed. Each time it is executed, the same fixed parameters are used, but a new set of variable parameters is used, and results are added to the result block.

fixedParamValues

A block of data holding the fixed parameters for this invocation of this macro.

paramSize

The size of the block of fixed parameter data. This is required so the data can be sent easily over RPC.

Returns

The function returns:

TAPOp_NoError

No error.

TAPOp_UnableToSelect

Connection could not be made.

TAPOp_NoSuchConnection

The connectId was not recognized.

TAPOp_InBadTAPState

TAP controller is not in Run-Test/Idle.

TAPOp_BadParameter

Unrecognized fn-name in callDetails.

TAPOp_RPC_Connection_Fail

The RPC connection was lost while processing this request.

TAPOp_TooManyMacros

Maximum number of macros exceeded. The maximum is 250.

TAPOp_TooManyMacroLines

Too many lines in the macro. The maximum is 1000.

TAPOp_BadFixedParamNo

A bad parameter number was specified.

TAPOp_UnknownProcedureName

Unknown procedure name in TAPOp_DefineMacro call.

TAPOp_CantUseProcInMacro

Procedure specified in TAPOp_DefineMacro call cannot be run in a macro.

Usage

TAPOp_DefineMacro adds a line (one TAPOp or ARMTAP function call) to a TAPOp macro definition, creating the macro as required. Macro definitions are stored in the Multi-ICE server and are private to each connection. Using macros instead of direct calls enables you to speed up the execution of clients, because the overhead of communicating with the server is reduced significantly.

This function must be called for each line of a macro. If a macro with the same ID number is already defined for this connection, the new line is added to the existing macro. If there is no current definition, a new macro is created with this line. You can display a summary of the contents of a macro by calling TAPOp_DisplayMacro.

You can specify that a line added by TAPOp_DefineMacro is executed a number of times, and a parameter to TAPOp_RunMacro enables you to specify that the whole macro is run a number of times. This allows the server to optimize some operations further, providing better performance.

If you run a macro or a macro line more than once by using the nTimes argument of TAPOp_DefineMacro or TAPOp_RunMacro, the same set of fixed parameter data is used each time the line is executed. However, each time a macro line is executed, a new set of variable data (passed in at runtime) is used and new results are output.

Example

This example demonstrates defining a macro to select a scan chain on an ARM processor.

There are three TAPOp calls in this macro. The fixed parameters are defined using the InitParams and NREnterParamUx C macros, described in TAPOp constant and macro definitions. There is one variable parameter, TDIbits1 of the second API call, that enables the scan chain to be specified when the macro is run.

See also the examples in Using TAPOp macros.

#define SELCHAIN   1   /* macro number for select scanchain macro */
{
    ... declarations
    InitParams;
    NREnterParamU16(SCAN_N);    //TDIbits
    NREnterParamU8(0);          //TDIrev
    NREnterParamU8(0);          //nClks
    TAPCheck(TAPOp_DefineMacro(cId, SELCHAIN, "ARMTAP_AccessIR_nClks:123", 1,
                                            Values, ValPtr));
    InitParams;
    NREnterParamU8(0);          //TDIbits2
    NREnterParamU8(0);          //TDIrev
    NREnterParamU8(TDefs->SCSRlen); //len
    NREnterParamU8(0);          //WRoffset
    NREnterParamU32(TDefs->SCSRMask.low32); //WRmask1
    NREnterParamU8(TDefs->SCSRMask.high8);  //WRmask2
    NREnterParamU8(0);          //nClks
    TAPCheck(TAPOp_DefineMacro(cId, SELCHAIN, "ARMTAP_AccessDR_W:2345678", 1,
                                            Values, ValPtr));
    InitParams;
    NREnterParamU16(INTEST);    //TDIbits
    NREnterParamU8(0);          //TDIrev
    NREnterParamU8(0);          //nClks
    TAPCheck(TAPOp_DefineMacro(cId, SELCHAIN, "ARMTAP_AccessIR_nClks:123", 1,
                                            Values, ValPtr));

See also

These TAPOp API functions provide similar or related functionality:

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