API for Remote Control and JTAG Access TRACE32 Online Help TRACE32 Directory TRACE32 Index TRACE32 Documents ......................................................................................................................  Misc ................................................................................................................................................  API for Remote Control and JTAG Access .............................................................................. 1 Licensing Terms ...................................................................................................................... 5 Introduction ............................................................................................................................. 6 Release Information 6 Compatibility 6 System Configuration Overview 7 Restrictions in Demo Mode 7 Interfaces 8 Operation of API Requests 10 Conventions for Target Memory Access 10 Building an Application with API ........................................................................................... 13 API Files 13 Connecting API and Application 13 Logging the API Calls 14 Communication Setup ............................................................................................................ 15 Preparing TRACE32 Software 15 Configuring the API 15 API Functions .......................................................................................................................... 16 Error Codes 16 Generic API Functions 16 T32_Config Configure Driver 16 T32_Init Initialize driver and connect 17 T32_Exit Close connection 19 T32_Attach Attach TRACE32 device 20 T32_Nop Send Empty Message 21 T32_Ping Send Ping Message 21 T32_Cmd Execute TRACE32 Command 22 T32_Cmd_f Execute PRACTICE Command Formatted 23 T32_CmdWin Execute PRACTICE Command 24 T32_Printf Print Formatted to TRACE32 24 T32_Stop Stop PRACTICE script 25 ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 1 T32_EvalGet Get Evaluation Result 26 T32_EvalGetString Get Evaluation String Result 27 T32_GetMessage Get Message Line Contents 28 T32_Terminate Terminate TRACE32 instance 29 T32_GetPracticeState Check if a PRACTICE script is running 30 T32_SetMode Set Data.List display mode 30 T32_GetWindowContent Get the content of a TRACE32 window 31 T32_GetApiRevision Get revision number or API 32 T32_GetSocketHandle Get the handle of the TRACE32 socket 33 Functions for using the API with Multiple Debuggers 34 T32_GetChannelSize Get size of channel structure 34 T32_GetChannelDefaults Get default channel parameters 35 T32_SetChannel Set active channel 36 ICD/ICE API Functions 37 T32_GetState Get State of ICE/ICD 37 T32_GetCpuInfo Get Information about used CPU 39 T32_GetRam Get Memory Mapping (ICE only) 40 T32_ResetCPU Prepare for Emulation 41 T32_ReadMemory Read Target Memory 42 T32_ReadMemoryObj Read Target Memory Object 44 T32_WriteMemory Write to Target Memory 45 T32_WriteMemoryPipe Write to Target Memory pipelined 47 T32_WriteMemoryObj Write Target Memory Object 48 T32_TransferMemoryBundleObj Read/Write Target Memory Bundles 49 T32_SetMemoryAccessClass Set memory access class 51 T32_ReadRegister Read CPU Registers 52 T32_ReadRegisterByName Read Value of Register 53 T32_ReadRegisterObj Read CPU Register Object 54 T32_ReadRegisterSetObj Read CPU Register Set Object 55 T32_WriteRegister Write CPU Registers 56 T32_WriteRegisterByName Write Value of Register 57 T32_WriteRegisterObj Write CPU Register Object 58 T32_WriteRegisterSetObj Write CPU Register Set Object 59 T32_ReadPP Read Program Pointer 60 T32_ReadBreakpoint Read Breakpoints 61 T32_WriteBreakpoint Write Breakpoints 63 T32_GetBreakpointList Get Breakpoint List 65 T32_WriteBreakpointObj Write breakpoint object 66 T32_ReadBreakpointObj Read breakpoint object by address 67 T32_ReadBreakpointObjByIndex Read breakpoint object by index 68 T32_QueryBreakpointObjCount Query number of breakpoints 69 T32_Step Single Step 70 T32_StepMode Single Step with Mode Control 71 ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 2 T32_Go Start real time 72 T32_Break Stop real time 73 T32_GetTriggerMessage Get Trigger Message Contents 74 T32_GetSymbol Get Symbol Information 75 T32_GetSymbolFromAddress Get symbol name from address 77 T32_QuerySymbolObj Query symbol object information 78 T32_QueryAddressObjMmuTranslation Query MMU address translation 80 T32_QueryAddressObjTargetSizeOfMau Query target MAU size 82 T32_ReadVariableValue Read value of variable 83 T32_WriteVariableValue Write value to variable 84 T32_ReadVariableString Read variable as string 85 T32_GetSource Get Source Filename and Line 86 T32_GetSelectedSource Get Source Filename and Line of Selection 87 T32_AnaStatusGet Get State of State Analyzer 88 T32_AnaRecordGet Get One Record of State Analyzer 89 T32_GetTraceState Get State of Trace 92 T32_ReadTrace Get n Trace Records 94 T32_NotifyStateEnable Register a function to be called at state change 97 T32_NotifyEventEnable Register a function to be called at ON events 98 T32_CheckStateNotify Check message to receive for state notify 99 T32_APILock Lock the Remote API connection 101 T32_APIUnlock Unlock the Remote API connection 102 ICD Direct Access API Functions 103 Bundled Accesses and Exclusive Access 105 T32_BundledAccessAlloc Retrieve a Handle for Bundled Access Mode 106 T32_BundledAccessFree Release Handle for Bundled Access Mode 107 T32_BundledAccessExecute Execute a Bundled Access 108 T32_DirectAccessRelease Unlock Debugger 109 Configuration of instance parameters and independent parameters 110 T32_ParamFromUint32 Set instance parameter 110 T32_DirectAccessSetInfo Set instance parameter 110 T32_DirectAccessGetInfo Set instance parameter 111 Instance independent parameters and functions 113 T32_DirectAccessResetAll Reset configuration data of all instances 115 ICD TAP Access API Functions 116 T32_TAPAccessSetInfo Configure JTAG Interface 123 T32_TAPAccessShiftIR Shift Data to/from Instruction Register 125 T32_TAPAccessShiftDR Shift Data to/from Data Register 126 T32_TAPAccessDirect Direct JTAG Port Access 127 T32_TAPAccessJTAGResetWithTMS Reset JTAG TAP by TMS sequence 130 T32_TAPAccessJTAGResetWithTRST Reset JTAG TAP by TRST signal 131 T32_TAPAccessSetShiftPattern Define automated shift sequences 132 T32_TAPAccessShiftRaw RAW JTAG Shifts 135 ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 3 ICD User Signal API Functions 138 T32_DirectAccessUserSignal User Signal Access 139 DAP Access API Functions 143 T32_DAPAccessScan Access DAP registers 145 T32_DAPAccessInitSWD Initialize SWD Port 147 DAP Bus Access API Functions 148 T32_DAPAPAccessReadWrite Read/Write memory at bus 151 Remote Lua API Functions 154 API Object Handling ................................................................................................................ 159 Buffer Object 160 Address Object 162 Bundle Object 167 Register Object 169 RegisterSet Object 174 Breakpoint Object 176 Symbol Object 180 Document Revision Information ............................................................................................ 182 ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 4 API for Remote Control and JTAG Access Version 16-Nov-2018 Licensing Terms The TRACE32 Application Programming Interface for Remote Control and JTAG Access (“Remote API”) contains source code for the client interface, which is copyright by Lauterbach. These licensing terms and conditions apply to all files referred to in this document. You may: (cid:129) share the original C source code of the TRACE32 Remote API with others (e.g. in a public repository) (cid:129) use the original source code of the Remote API in your own software (commercial and non- commercial) (cid:129) modify the original source code if necessary for compilation or integration into your product or a library used by it (cid:129) port the Remote API source code to other computer languages You may not: (cid:129) sell or sub-license the original source code of the TRACE32 Remote API (cid:129) modify the original source code, or any derived works, in a away that changes or extends the APDUs (Application Protocol Data Units) that it produces (cid:129) distribute any modified source code to others (cid:129) implement the host/server part of the Lauterbach TRACE32 Remote API in your own product (if you think you need this, please contact us to negotiate different licensing terms for this) You have to: (cid:129) include these Licensing Terms in any derived works (cid:129) inform Lauterbach if you use the original source code, or any derived works, in a commercial product Disclaimer: The API source code is designed to remote-control Lauterbach TRACE32 software. We provide this code “as is” without any implicit or explicit warranties, and without taking responsibility for its correctness or for its fitness for a specific purpose. ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 5 Introduction Release Information Release 4.0, shipped from 01-SEP-2004, includes the ability to connect to several debuggers at once (multi- core debugging). Compatibility Lauterbach ensures backward compatibility of the API. Backward compatibility means, that application built with one release of the API will remain working on both, future versions of the API and future versions of the main TRACE32 software. Future releases of the API and/or the TRACE32 software will extend or replace some functionality, but will not break previous functionality. The compatibility applies to: (cid:129) The C function interface. The functions listed in this manual will keep their calling conventions and the functionality described here. (cid:129) The UDP socket stream. The binary data sent over the UDP connection will keep functioning. The compatibility does not apply to: (cid:129) The composition of the API functions in the source files. The coding of the function may change completely, keeping the above compatibilities. (cid:129) API internal data structures and representations. Variables and data structures, that are not exposed in the manual, may be changed without further notice. When accessing data structures of the API, use only the access functions mentioned herein. ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 6 System Configuration Overview The TRACE32/PowerView software contains an external control interface. The TRACE32 Application Programming Interface (further referred to as API) gives external applications the possibility to control the debugger and the program run by the debugger. The API is built as a plain C source library with a C function interface to the controlling application. Alternatively to the C source files, a prebuilt Windows DLL is available that exports the same function set. The API communicates with the TRACE32 application (not with the TRACE32 debug interface itself!) using a socket interface. This is the command chain using TRACE32 API: Application ---> TRACE32 API ---> TRACE32 application --> TRACE32 (C Functions) (sockets) (HW interface) Application TRACE32 API TRACE32 UDP/IP UDP/IP TRACE32 Ethernet localhost/ Hardware Socket Socket display driver USB Ethernet Interface Interface Restrictions in Demo Mode The TRACE32 Remote API is blocked in “demo mode”, i.e. if you do not have a valid TRACE32 license. You will not be able to create successful connections between the API and TRACE32. If you need to evaluate the API without having a full license, contact Lauterbach for an evaluation license of your TRACE32 system. ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 7 Interfaces Application --> TRACE32 API Application TRACE32 API The application uses the API as ordinary C functions. The API is linked to the application at the usual linking stage. The API functions are not thread safe. If the application uses threads, it has to lock the functions against reentrancy. TRACE32 API --> TRACE32 display driver Application TRACE32 API UDP/IP UDP/IP TRACE32 localhost/ Socket Socket display driver Ethernet Interface Interface The communication to the TRACE32 software is implemented as a socket interface. The controlling application (compiled/linked with the API) and the debugger software can reside on two different hosts, using socket connections for communication. But be aware that this connection is not fault tolerant, because no error correction is implemented in the API. Network errors may lead to a break of the connection. It is recommended, that both parties run on the same host. ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 8 TRACE32 display driver --> TRACE32 TRACE32 TCP/IP TRACE32 Ethernet Hardware Socket display driver USB Interface The TRACE32/PowerView debugger software processes and routes the API requests to the TRACE32 hardware. This interface is the one, you chose for your debugger. E.g. it could be Ethernet or USB. The answers for a request go exactly the opposite way, returning information to the application in passed buffers. ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 9 Operation of API Requests The API requests are executed just in parallel with normal TRACE32 operation. You can use both, the TRACE32 user interface and the API simultaneously, although it is not recommended. The application will not be informed about changes that are done via the user interface. Also, unpredictable errors may occur, if e.g. an API request and a running PRACTICE file interfere. Conventions for Target Memory Access When using Remote API functions to read and write target memory (e.g. T32_ReadMemory, T32_WriteMemory), it is necessary to follow the TRACE32 conventions given below. Byte-Addresses If not explicitly changed (see below), the address parameter for reading and writing target memory always is a “byte” (octet) address, independently of the target architecture’s native memory width. This implies that (cid:129) For machines that are byte-addressed (i.e. natively address single bytes like x86) the byte address corresponds to the native address. On these machines incrementing the address by 1 yields the next byte in memory. (cid:129) For machines using word-addresses (i.e. natively address memory words like many DSPs) the byte address for use with the TRACE32 remote API is calculated multiplying the word address with the native memory width (in bytes). On these machines incrementing the native address by 1 yields the next word in memory. (cid:129) Accessing peripheral registers or special purpose registers that are not byte addresses (e.g. ARM CP15 or PowerPC SPR) need an address correction that multiplies the register number by the byte width of the register access class. E.g. if “Data.dump SPR:0x10” shows 32bit for each register number (= SPR address), the corresponding API address is 0x10*4. The address objects may be set to be used with other addressing modes, by setting the MAU (minimum addressable unit) with T32_SetAddressObjSizeOfMau() (see there). ©1989-2018 Lauterbach GmbH API for Remote Control and JTAG Access 10