J-Link script files

In some situations, it is necessary to customize some actions performed by J-Link. In most cases, it is the connection sequence and/or the way in which a reset is performed by J-Link, since some custom hardware needs some special handling which cannot be integrated into the generic part of the J-Link software. J-Link script files are written in C-like syntax in order to have an easy start to learning how to write J-Link script files. The script file syntax supports most statements (if-else, while, declaration of variables, ...) which are allowed in C, but not all of them. Moreover, there are some statements that are script file specific. The script file allows maximum flexibility, so almost any target initialization necessary can be supported.

Customizable actions

The script file support allows customizing of different actions performed by J-Link. Depending on whether the corresponding function is present in the script file or not, a generically implemented action is replaced by an action defined in a script file. In the following all J-Link actions which can be customized using a script file are listed and explained.

Action	Prototype
ConfigTargetSettings()	int ConfigTargetSettings (void);
InitTarget()	int InitTarget (void);
SetupTarget()	int SetupTarget (void);
ResetTarget()	int ResetTarget (void);
InitEMU()	int InitEMU (void);
OnDisconnectTarget()	int OnDisconnectTarget (void);
OnTraceStop()	int OnTraceStop (void);
OnTraceStart()	int OnTraceStart (void);
AfterResetTarget()	int AfterResetTarget (void);
SWO_EnableTarget()	int SWO_EnableTarget (void);
SWO_GetSWOBaseClock()	U32 SWO_GetSWOBaseClock (U32 CPUclock);
HandleBeforeFlashProg()	int HandleBeforeFlashProg (void);
HandleAfterFlashProg()	int HandleAfterFlashProg (void);
HandleBeforeMemAccessWrite()	int HandleBeforeMemAccessWrite (U32 Addr, U32 NumBytes, U32 Flags);
HandleAfterMemAccessWrite()	int HandleAfterMemAccessWrite (U32 Addr, U32 NumBytes, U32 Flags);
HandleBeforeMemAccessRead()	int HandleBeforeMemAccessRead (U32 Addr, U32 NumBytes, U32 Flags);
HandleAfterMemAccessRead()	int HandleAfterMemAccessRead (U32 Addr, U32 NumBytes, U32 Flags);
StartETM()	int StartETM (void);
StopETM()	int StopETM (void);
StartTPIU()	int StartTPIU (void);
StopTPIU()	int StopTPIU (void);
StartTMC()	int StartTMC (void);
StopTMC()	int StopTMC (void);
StartPTM()	int StartPTM (void);
StopPTM()	int StopPTM (void);
StartTF()	int StartTF (void);
StopTF()	int StopTF (void);
StartETB()	int StartETB (void);
StopETB()	int StopETB (void);
StartSTM()	int StartSTM (void);
StopSTM()	int StopSTM (void);
StartNTRACETE()	int StartNTRACETE (void);
StopNTRACETE()	int StopNTRACETE (void);
StartNTRACETF()	int StartNTRACETF (void);
StopNTRACETF()	int StopNTRACETF (void);
StartNTRACEPIB()	int StartNTRACEPIB (void);
StopNTRACEPIB()	int StopNTRACEPIB (void);
StartNTRACESRAM()	int StartNTRACESRAM (void);
StopNTRACESRAM()	int StopNTRACESRAM (void);
StartNTRACEATB()	int StartNTRACEATB (void);
StopNTRACEATB()	int StopNTRACEATB (void);

Note:
The default return values for all listed functions above are:

Return value	Meaning
>= 0	O.K.
< 0	Error

ConfigTargetSettings()

Called before InitTarget(). Mainly used to set some global DLL variables to customize the normal connect procedure. For ARM CoreSight devices this may be specifying the base address of some CoreSight components (ETM, CTI, ...) that cannot be auto-detected by J-Link due to erroneous ROM tables etc. May also be used to specify the device name in case debugger does not pass it to the DLL.

Prototype

int ConfigTargetSettings(void);

Notes and Limitations

May not, under absolutely NO circumstances, call any API functions that perform target communication.

• Should only set some global DLL variables

InitTarget()

This function has "extending nature" meaning if it is in a script file, it is called before the JTAG/SWD/... and CPU auto-detection mechanisms take place.
This gives the user a chance to do chip-specific init that needs to be done before the core itself is available for debug.
Example devices are MCUs from TI which have a so-called ICEPick JTAG unit on them that needs to be configured, before the actual core is accessible (or even visible) via JTAG.
If this function is not in a script file or empty (simply returns 0), this has no effect on the connect sequence of J-Link.

Prototype

int InitTarget(void);

Notes and Limitations

If target interface JTAG is used: JTAG chain has to be specified manually before leaving this function (meaning all devices and their TAP IDs have to be specified by the user). Also appropriate JTAG TAP number to communicate with during the debug session has to be manually specified in this function.

• MUST NOT use any MEM_ API functions
• Global DLL variable "CPU" MUST be set when implementing this function, so the DLL knows which CPU module to use internally.

SetupTarget()

If present, called after InitTarget() and after general debug connect sequence has been performed by J-Link. Usually used for more high-level CPU debug setup like writing certain memory locations, initializing PLL for faster download etc.

Prototype

int SetupTarget(void);

Notes and Limitations

Does not replace any DLL functionality but extends it.

• May use MEM_ API functions

ResetTarget()

This function has "replacing nature" meaning if it is in a script file, it is called instead of the standard target reset sequence if the debugger issues a target reset request to J-Link.
This gives the user a chance to override the reset sequence performed by J-Link.
Example cases:

• Target is Cortex-M based and J-Link will issue a reset via the AIRCR.SYSRESETREQ bit but the signal triggered by this bit is not correctly wired inside the MCU. The reset pin is also not connected. In such a case, this function may implement a chip-specific reset that uses the chip-specific reset controller peripheral to reset all peripherals manually or uses a watchdog etc. to trigger a proper self-reset of the chip.
• Target has a ROM bootloader that must run after reset and before passing control to the user application code but the standard debugger triggered reset halts the core before the ROM bootloader has been executed. In such a case, the user may implement a reset function that manually restarts the core to execute the ROM BTL but halts immediately before executing the first instruction of the user code.

If this function is present in a script file but empty, effectively no reset is issued to the target.

Prototype

int ResetTarget(void);

Notes and Limitations

• DLL expects target CPU to be halted / in debug mode, when leaving this function
• May use MEM_ API functions
• No matter what reset type is selected in the DLL, if this function is present, it will be called instead of the DLL internal reset.

InitEMU()

This function can be used to initialize the emulator settings like for example the host interface (e.g. in case of it cannot be selected in the IDE). This function should be used thoughtful and only if you know exactly what you are doing as there are many things which needs to be taken into account. Currently this function is only used to set the J-Link Command Strings listed in below. It will be called right before the connection to the emulator is opened.

Allowed J-Link Command Strings

• SetHostIf
• JLinkDevicesXMLPath

Prototype

int InitEMU(void);

Notes and Limitations

• May only use JLINK_ExecCommand() and only for the J-Link Command Strings listed above.

OnDisconnectTarget()

This function is called right before the generic debug deinitialization. It is usually used to reset any device specific debug registers that were set for device specific connect.

Prototype

int OnDisconnectTarget(void);

Notes and Limitations

• May use MEM_ API functions

OnTraceStop()

Called right before capturing of trace data is stopped on the J-Link / J-Trace. On some target, an explicit flush of the trace FIFOs is necessary to get the latest trace data. If such a flush is not performed, the latest trace data may not be output by the target

Prototype

int OnTraceStop(void);

Notes and Limitations

• May use MEM_ API functions

OnTraceStart()

If present, called right before trace is started. Used to initialize MCU specific trace related things like configuring the trace pins for alternate function.

Prototype

int OnTraceStart(void);

Notes and Limitations

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt().
• Can rely on target being halted when entering this function.

AfterResetTarget()

If present, called after ResetTarget(). Usually used to initialize peripheries which have been reset during reset, disable watchdogs which may be active after reset, etc... Apart from this, for some cores it is necessary to perform some special operations after reset to guarantee proper device functionality after reset. This is mainly the case on devices which have some bugs that occur at the time of a system reset (not power on reset).

Prototype

int AfterResetTarget(void);

Notes and Limitations

DLL expects target CPU to be halted / in debug mode, when leaving this function

• May use MEM_ API functions

SWO_EnableTarget()

If present, called before SWO_GetSWOBaseClock(). Used for target device that need additional init steps to enable SWO. For example if there are none CoreSight registers that need to be enabled or more than one pin can be configured to be the SWO pin.

Prototype

int SWO_EnableTarget(void);

Notes and Limitations

• This function should only be called if the target device needs extra initialization of SWO registers that are not generic.

SWO_GetSWOBaseClock()

Determines the actual SWO base clock that is supplied by the device to the SWO CoreSight logic. On most devices it is CPUClock / 1 but there are exceptions for which this function can be used for.

Prototype

U32 SWO_GetSWOBaseClock(U32 CPUClock);

Parameter	Description
CPUClock	Measured CPU clock speed in Hz

Return value

The return value is the actual SWO base clock speed.

Notes and Limitations

• This function should only be called if the target device has some other SWO base clock than CPUClock / 1.

HandleBeforeFlashProg()

If present, called right before flash programming is performed Usually used to initialize peripherals which are used during the flash download like for example clocks or port pins (e.g. QSPI alternate function)

Prototype

int HandleBeforeFlashProg(void);

Notes and Limitations

DLL expects target CPU to be halted / in debug mode, when leaving this function

• May use MEM_ API functions

HandleAfterFlashProg()

If present, called right after flash programming Usually used to restore initialized peripherals which have been used during the flash download like for example clocks or port pins (e.g. QSPI alternate function)

Prototype

int HandleAfterFlashProg(void);

Notes and Limitations

DLL expects target CPU to be halted / in debug mode, when leaving this function

• May use MEM_ API functions

HandleBeforeMemAccessWrite()

If present, called right before a memory write access is performed. Usually used to clean and invalidate device specific caches, if necessary.

Prototype

int HandleBeforeMemAccessWrite(U32 Addr, U32 NumBytes, U32 Flags);

Notes and Limitations

DLL expects target CPU to be halted / in debug mode, when leaving this function

• MUST NOT use any MEM_ API functions

HandleAfterMemAccessWrite()

If present, called right after a memory write access.

Prototype

int HandleAfterMemAccessWrite(U32 Addr, U32 NumBytes, U32 Flags);

Notes and Limitations

DLL expects target CPU to be halted / in debug mode, when leaving this function

• MUST NOT use any MEM_ API functions

HandleBeforeMemAccessRead()

If present, called right before a memory read access is performed. Usually used to clean and invalidate device specific caches, if necessary.

Prototype

int HandleBeforeMemAccessRead(U32 Addr, U32 NumBytes, U32 Flags);

Notes and Limitations

DLL expects target CPU to be halted / in debug mode, when leaving this function

• MUST NOT use any MEM_ API functions

HandleAfterMemAccessRead()

If present, called right after a memory read access.

Prototype

int HandleAfterMemAccessRead(U32 Addr, U32 NumBytes, U32 Flags);

Notes and Limitations

DLL expects target CPU to be halted / in debug mode, when leaving this function

• MUST NOT use any MEM_ API functions

StartETM()

If present, replaces generic initialization of Embedded Trace Macrocell (ETM) trace settings. Used for target devices that need different init steps for ETM which are not set automatically by J-Link/J-Trace.

Prototype

int StartETM(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopETM()

If present, replaces generic deinitialization of Embedded Trace Macrocell (ETM) trace settings. Used for target devices that need different deinit steps for ETM which are not set automatically by J-Link/J-Trace.

Prototype

int StopETM(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartETB()

If present, replaces generic initialization of Embedded Trace Buffer (ETB) trace settings. Used for target devices that need different init steps for ETB which are not set automatically by J-Link/J-Trace.

Prototype

int StartETB(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopETB()

If present, replaces generic deinitialization of Embedded Trace Buffer (ETB) trace settings. Used for target devices that need different deinit steps for ETB which are not set automatically by J-Link/J-Trace.

Prototype

int StopETB(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartTPIU()

If present, replaces generic initialization of Trace Port Interface Unit (TPIU) trace settings. Used for target devices that need different init steps for TPIU which are not set automatically by J-Link/J-Trace.

Prototype

int StartTPIU(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopTPIU()

If present, replaces generic deinitialization of Trace Port Interface Unit (TPIU) trace settings. Used for target devices that need different deinit steps for TPIU which are not set automatically by J-Link/J-Trace.

Prototype

int StopTPIU(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartTMC()

If present, replaces generic initialization of Trace Memory Controller (TMC) trace settings. Used for target devices that need different init steps for TMC which are not set automatically by J-Link/J-Trace.

Prototype

int StartTMC(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopTMC()

If present, replaces generic deinitialization of Trace Memory Controller (TMC) trace settings. Used for target devices that need different deinit steps for TMC which are not set automatically by J-Link/J-Trace.

Prototype

int StopTMC(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartTF()

If present, replaces generic initialization of Trace Funnel (TF) trace settings. Used for target devices that need different init steps for TF which are not set automatically by J-Link/J-Trace.

Prototype

int StartTF(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopTF()

If present, replaces generic deinitialization of Trace Funnel (TF) trace settings. Used for target devices that need different deinit steps for TF which are not set automatically by J-Link/J-Trace.

Prototype

int StopTF(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartPTM()

If present, replaces generic initialization of Program Flow Trace (PTM) trace settings. Used for target devices that need different init steps for PTM which are not set automatically by J-Link/J-Trace.

Prototype

int StartPTM(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopPTM()

If present, replaces generic deinitialization of Program Flow Trace (PTM) trace settings. Used for target devices that need different init steps for PTM which are not set automatically by J-Link/J-Trace.

Prototype

int StopPTM(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartSTM()

If present, replaces generic initialization of System Trace Macrocell (STM) trace settings. Used for target devices that need different init steps for STM which are not set automatically by J-Link/J-Trace.

Prototype

int StartSTM(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopSTM()

If present, replaces generic deinitialization of System Trace Macrocell (STM) trace settings. Used for target devices that need different deinit steps for STM which are not set automatically by J-Link/J-Trace.

Prototype

int StopSTM(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic deinitialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartNTRACETE()

If present, replaces generic initialization of RISC-V N-Trace trace encoder (TE) trace settings. Used for target devices that need different init steps for TE which are not set automatically by J-Link/J-Trace.

Prototype

int StartNTRACETE(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopNTRACETE()

If present, replaces generic deinitialization of RISC-V N-Trace trace encoder (TE) trace settings. Used for target devices that need different init steps for TE which are not set automatically by J-Link/J-Trace.

Prototype

int StopNTRACETE(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartNTRACETF()

If present, replaces generic initialization of RISC-V N-Trace trace funnel (TF) trace settings. Used for target devices that need different init steps for TF which are not set automatically by J-Link/J-Trace.

Prototype

int StartNTRACETF(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopNTRACETF()

If present, replaces generic deinitialization of RISC-V N-Trace trace funnel (TF) trace settings. Used for target devices that need different init steps for TF which are not set automatically by J-Link/J-Trace.

Prototype

int StopNTRACETF(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartNTRACEPIB()

If present, replaces generic initialization of RISC-V N-Trace pin sink (PIB) trace settings. Used for target devices that need different init steps for PIB which are not set automatically by J-Link/J-Trace.

Prototype

int StartNTRACEPIB(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopNTRACEPIB()

If present, replaces generic deinitialization of RISC-V N-Trace pin sink (PIB) trace settings. Used for target devices that need different init steps for PIB which are not set automatically by J-Link/J-Trace.

Prototype

int StopNTRACEPIB(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartNTRACESRAM()

If present, replaces generic initialization of RISC-V N-Trace SRAM sink (SRAM) trace settings. Used for target devices that need different init steps for SRAM which are not set automatically by J-Link/J-Trace.

Prototype

int StartNTRACESRAM(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopNTRACESRAM()

If present, replaces generic deinitialization of RISC-V N-Trace SRAM sink (SRAM) trace settings. Used for target devices that need different init steps for SRAM which are not set automatically by J-Link/J-Trace.

Prototype

int StopNTRACESRAM(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StartNTRACEATB()

If present, replaces generic initialization of RISC-V N-Trace advanced trace bus sink (ATB) trace settings. Used for target devices that need different init steps for ATB which are not set automatically by J-Link/J-Trace.

Prototype

int StartNTRACEATB(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

StopNTRACEATB()

If present, replaces generic deinitialization of RISC-V N-Trace advanced trace bus sink (ATB) trace settings. Used for target devices that need different init steps for ATB which are not set automatically by J-Link/J-Trace.

Prototype

int StopNTRACEATB(void);

Notes and Limitations

Only to be used if you are familiar with trace initializations. If the generic initialization from J-Link software produces a trace output, do not use this function!

• May use high-level API functions like JLINK_MEM_ etc.
• Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.

Script file API functions

In the following, the API functions which can be used in a script file to communicate with the DLL are explained.

Return value	Function	Parameters
int	JLINK_C2_ReadAddr()	(U32* pAddr)
int	JLINK_C2_WriteAddr()	(U32 Addr)
int	JLINK_C2_ReadData()	(U8* pData, int NumItems)
int	JLINK_C2_WriteData()	(const U8* pData, int NumItems)
int	JLINK_CORESIGHT_AddAP()	(int Index, U32 Type)
int	JLINK_CORESIGHT_Configure()	(const char* sConfig)
int	JLINK_CORESIGHT_ReadAP()	(int RegIndex)
int	JLINK_CORESIGHT_ReadDP()	(int RegIndex)
int	JLINK_CORESIGHT_ReadDAP()	(int RegIndex, int APnDP, U32* Data)
int	JLINK_CORESIGHT_WriteAP()	(int RegIndex, U32 Data)
int	JLINK_CORESIGHT_WriteDP()	(int RegIndex, U32 Data)
int	JLINK_CORESIGHT_WriteDAP()	(int RegIndex, int APnDP, U32 Data)
int	JLINK_ExecCommand()	(const char* sMsg)
int	JLINK_FILE_Read()	(const U8* pFilename, U8* pBuf, U32 Offset, U32 Length, U32* pCRC)
int	JLINK_FILE_GetSize()	(const U8* pFilename)
int	JLINK_GetTime()	(void)
int	JLINK_GetPinState()	(U8 iPin)
int	JLINK_JTAG_GetDeviceId()	(int DeviceIndex)
int	JLINK_JTAG_GetU32()	(int BitPos)
int	JLINK_JTAG_ReadWriteBits()	(const U8 * pTDI, U8 * pTMS, U8 * pTDO, unsigned NumBits)
int	JLINK_JTAG_Reset()	(void)
int	JLINK_JTAG_SetDeviceId()	(int DeviceIndex, U32 Id)
int	JLINK_JTAG_StartDR()	(void)
int	JLINK_JTAG_Store()	(U32 tms, U32 tdi, U32 NumBits)
int	JLINK_JTAG_StoreClocks()	(int NumClocks)
int	JLINK_JTAG_StoreDR()	(U32 tdi, int NumBits)
int	JLINK_JTAG_StoreIR()	(U32 Cmd)
int	JLINK_JTAG_Write()	(U32 tms, U32 tdi, U32 NumBits)
int	JLINK_JTAG_WriteClocks()	(int NumClocks)
int	JLINK_JTAG_WriteDR()	(U32 tdi, int NumBits)
int	JLINK_JTAG_WriteDRCont()	(U32 Data, int NumBits)
int	JLINK_JTAG_WriteDREnd()	(U32 Data, int NumBits)
int	JLINK_JTAG_WriteIR()	(U32 Cmd)
int	JLINK_PIN_Override()	(const U32* paMode, U32* paState)
int	JLINK_MemRegion()	(const char* sConfig)
int	JLINK_MEM_WriteU8()	(U32 Addr, U32 Data)
int	JLINK_MEM_WriteU16()	(U32 Addr, U32 Data)
int	JLINK_MEM_WriteU32()	(U32 Addr, U32 Data)
U8	JLINK_MEM_ReadU8()	(U32 Addr)
U16	JLINK_MEM_ReadU16()	(U32 Addr)
U32	JLINK_MEM_ReadU32()	(U32 Addr)
int	JLINK_MEM_Preserve()	(U32 Addr, U32 NumBytes)
int	JLINK_MEM_Restore()	(int Handle)
int	JLINK_MEM_Fill()	(U32 Addr, U32 NumBytes, U32 FillVal)
int	JLINK_RISCV_DMI_AutodetectDMISettings()	(void)
int	JLINK_RISCV_DMI_ClearState()	(unsigned AbortPendingDMIAcc)
int	JLINK_RISCV_DMI_ReadReg()	(U32 RegAddr, U32* pData)
int	JLINK_RISCV_DMI_ReadRegMultiple()	(U32 RegAddr, U32* paData, U32 NumItems)
int	JLINK_RISCV_DMI_SetDMISettings()	(U32 NumAddrBits, U32 NumIdleClocks, U32 AccTimeout)
int	JLINK_RISCV_DMI_WriteReg()	(U32 RegAddr, U32 Data)
int	JLINK_RISCV_DMI_WriteRegMultiple()	(U32 RegAddr, const U32 * paData, U32 NumItems)
void	JLINK_SelectTIF()	(U32 tif)
int	JLINK_SetDevice()	(const char* sDevice)
int	JLINK_SWD_ReadWriteBits()	(const U8* pDataIn, const U8* pDirection, U8* pDataOut, int NumBits)
int	JLINK_SYS_MessageBox()	(const char* sMsg)
int	JLINK_SYS_MessageBox1()	(const char* sMsg, int v)
int	JLINK_SYS_Report()	(const char* sMsg)
int	JLINK_SYS_Report1()	(const char* sMsg, int v)
int	JLINK_SYS_Sleep()	(int Delayms)
int	JLINK_SYS_UnsecureDialog()	(const char* sText, const char* sQuestion, const char* sIdent, int DefaultAnswer, U32 Flags)
int	JLINK_TARGET_IsHalted()	(void)
int	JLINK_TARGET_Halt()	(void)
void	JLINK_TIF_ActivateTargetReset()	(void)
void	JLINK_TIF_ReleaseTargetReset()	(void)
void	JLINK_TIF_SetClrTCK()	(int OnOff)
void	JLINK_TIF_SetClrTMS()	(int OnOff)
void	JLINK_TIF_SetClrTDI()	(int OnOff)
void	JLINK_TIF_SetSpeed()	(U32 Speed)
int	JLINK_GetConfigData()	(const char* sKey, U8* pDest, U32 MaxSize)
int	JLINK_GetConfigDataEx()	(const char* sKey, U8* pBuf, U32 BufSize, U32 Flags)
int	JLINK_GetConfigValue()	(const char* sKey, int* pValue)

JLINK_C2_ReadAddr()

Reads the address register of the C2 interface.

Prototype

int JLINK_C2_ReadAddr(U32* pAddr);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_C2_WriteAddr()

Writes the address register of the C2 interface.

Prototype

int JLINK_C2_WriteAddr(U32 Addr);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_C2_ReadData()

Reads the data register of the C2 interface.

Prototype

int JLINK_C2_ReadData(U8* pData, int NumItems);

Parameter	Description
pData	Pointer to buffer to read to
NumItems	NumBytes to read

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_C2_WriteData()

Writes the data register of the C2 interface.

Prototype

int JLINK_C2_WriteData(const U8* pData, int NumItems);

Parameter	Description
pData	Pointer to data to write
NumItems	NumBytes to write

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_CORESIGHT_AddAP()

Note:

This function is deprecated because it cannot handle CoreSight SoC-600 and nested APs.

It is recommended to use JLINK_ExecCommand() instead, using the command string "CORESIGHT_AddAP".

Allows the user to manually configure the AP-layout of the device J-Link is connected to. This makes sense on targets on which J-Link can not perform a auto-detection of the APs which are present on the target system. Type can only be a known global J-Link DLL AP constant. For a list of all available constants, please refer to Global DLL constants.

Prototype

int JLINK_CORESIGHT_AddAP(int Index, U32 Type);

Parameter	Description
Index	AP Index
Type	AP Type

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

Example

JLINK_CORESIGHT_AddAP(0, CORESIGHT_AHB_AP);  // First  AP is a AHB-AP
JLINK_CORESIGHT_AddAP(1, CORESIGHT_APB_AP);  // Second AP is a APB-AP
JLINK_CORESIGHT_AddAP(2, CORESIGHT_JTAG_AP); // Third  AP is a JTAG-AP

JLINK_CORESIGHT_Configure()

Has to be called once, before using any other _CORESIGHT_ function that accesses the DAP. Takes a configuration string to prepare target and J-Link for CoreSight function usage. Configuration string may contain multiple setup parameters that are set. Setup parameters are separated by a semicolon.
At the end of the JLINK_CORESIGHT_Configure(), the appropriate target interface switching sequence for the currently active target interface is output, if not disabled via setup parameter.
This function has to be called again, each time the JTAG chain changes (for dynamically changing JTAG chains like those which include a TI ICEPick), in order to setup the JTAG chain again.

For JTAG

The SWD -> JTAG switching sequence is output. This also triggers a TAP reset on the target (TAP controller goes through -> Reset -> Idle state) The IRPre, DRPre, IRPost, DRPost parameters describe which device inside the JTAG chain is currently selected for communication.

For SWD

The JTAG -> SWD switching sequence is output. It is also made sure that the "overrun mode enable" bit in the SW-DP CTRL/STAT register is cleared, as in SWD mode J-Link always assumes that overrun detection mode is disabled.
Make sure that this bit is NOT set by accident when writing the SW-DP CTRL/STAT register via the _CORESIGHT_ functions.

Prototype

int JLINK_CORESIGHT_Configure(const char* sConfig);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
= -2	Not supported by the current CPU + target interface combination

Example

if (JLINK_ActiveTIF == JLINK_TIF_JTAG) {
  // Simple setup where we have TDI -> Cortex-M (4-bits IRLen) -> TDO
  JLINK_CORESIGHT_Configure("IRPre=0;DRPre=0;IRPost=0;DRPost=0;IRLenDevice=4");
} else {
  // For SWD, no special setup is needed, just output the switching sequence
  JLINK_CORESIGHT_Configure("");
}
v = JLINK_CORESIGHT_ReadDP(JLINK_CORESIGHT_DP_REG_CTRL_STAT);
JLINK_SYS_Report1("DAP-CtrlStat: " v);
// Complex setup where we have
// TDI -> ICEPick (6-bits IRLen) -> Cortex-M (4-bits IRLen) -> TDO
JLINK_CORESIGHT_Configure("IRPre=0;DRPre=0;IRPost=6;DRPost=1;IRLenDevice=4;");
v = JLINK_CORESIGHT_ReadDP(JLINK_CORESIGHT_DP_REG_CTRL_STAT);
JLINK_SYS_Report1("DAP-CtrlStat: " v)

Known setup parameters

Parameter	Type	Explanation
IRPre	DecValue	Sum of IRLen of all JTAG devices in the JTAG chain, closer to TDO than the actual one J-Link shall communicate with.
DRPre	DecValue	Number of JTAG devices in the JTAG chain, closer to TDO than the actual one, J-Link shall communicate with.
IRPost	DecValue	Sum of IRLen of all JTAG devices in the JTAG chain, following the actual one, J-Link shall communicate with.
DRPost	DecValue	Number of JTAG devices in the JTAG chain, following the actual one, J-Link shall communicate with.
IRLenDevice	DecValue	IRLen of the actual device, J-Link shall communicate with.
PerformTIFInit	DecValue	0: Do not output switching sequence etc. once JLINK_CORESIGHT_Configure() completes.

JLINK_CORESIGHT_ReadAP()

Reads a specific AP register. For JTAG, makes sure that AP is selected automatically. Makes sure that actual data is returned, meaning for register read-accesses which usually only return data on the second access, this function performs this automatically, so the user will always see valid data.

Prototype

int JLINK_CORESIGHT_ReadAP(int RegIndex);

Parameter	Description
RegIndex	Specifies the index of the AP register to read.

Return value	Description
!= -1	Data read
= -1	Error

Example

v = JLINK_CORESIGHT_ReadAP(JLINK_CORESIGHT_AP_REG_DATA);
JLINK_SYS_Report1("DATA: " v);

JLINK_CORESIGHT_ReadDP()

Reads a specific DP register. For JTAG, makes sure that DP is selected automatically. Makes sure that actual data is returned, meaning for register read-accesses which usually only return data on the second access, this function performs this automatically, so the user will always see valid data.

Prototype

int JLINK_CORESIGHT_ReadDP(int RegIndex);

Parameter	Description
RegIndex	Specifies the index of the DP register to read.

Return value	Description
!= -1	Data read
= -1	Error

Example

v = JLINK_CORESIGHT_ReadDP(JLINK_CORESIGHT_DP_REG_IDCODE);
JLINK_SYS_Report1("DAP-IDCODE: ", v);

JLINK_CORESIGHT_ReadDAP()

Reads a specific AP/DP register. For JTAG, makes sure that AP/DP is selected automatically. Makes sure that actual data is returned, meaning for register read-accesses which usually only return data on the second access, this function performs this automatically, so the user will always see valid data.

Prototype

int JLINK_CORESIGHT_ReadDAP(int RegIndex, int APnDP, U32* Data);

Parameter	Description
RegIndex	Specifies the index of the AP/DP register to read.
APnDP	0: DP register 1: AP register
Data	Pointer to buffer for data read

Return Value

Return value	Description
>= 0	O.K. (Number of repetitions needed before read was accepted / returned valid data)
< 0	Error

Example

JLINK_CORESIGHT_ReadDAP(JLINK_CORESIGHT_DP_REG_IDCODE, 0, v);
JLINK_SYS_Report1("DAP-IDCODE: " v);

JLINK_CORESIGHT_WriteAP()

Writes a specific AP register. For JTAG, makes sure that AP is selected automatically.

Prototype

int JLINK_CORESIGHT_WriteAP(int RegIndex, U32 Data);

Parameter	Description
RegIndex	Specifies the index of the AP register to write.
Data	Data to be written

Return Value

Return value	Description
>= 0	O.K. (Number of repetitions needed before write was accepted)
< 0	Error
= -2	Not supported by the current CPU + target interface combination

Example

JLINK_CORESIGHT_WriteAP(JLINK_CORESIGHT_AP_REG_BD1, 0x1E);

JLINK_CORESIGHT_WriteDP()

Writes a specific DP register. For JTAG, makes sure that DP is selected automatically.

Prototype

int JLINK_CORESIGHT_WriteDP(int RegIndex, U32 Data);

Parameter	Description
RegIndex	Specifies the index of the DP register to write.
Data	Data to be written

Return Value

Return value	Description
>= 0	O.K. (Number of repetitions needed before write was accepted)
< 0	Error
= -2	Not supported by the current CPU + target interface combination

Example

JLINK_CORESIGHT_WriteDP(JLINK_CORESIGHT_DP_REG_ABORT, 0x1E);

JLINK_CORESIGHT_WriteDAP()

Writes to a CoreSight AP/DP register. This function performs a full-qualified write which means that it tries to write until the write has been accepted or too many WAIT responses have been received.

Prototype

int JLINK_CORESIGHT_WriteDAP(int RegIndex, int APnDP, U32 Data);

Parameter	Description
RegIndex	Specifies the index of the AP/DP register to write.
APnDP	0: DP register 1: AP register
Data	Data to be written

Return Value

Return value	Description
>= 0	O.K. (Number of repetitions needed before write was accepted)
< 0	Error
= -2	Not supported by the current CPU + target interface combination

Example

JLINK_CORESIGHT_WriteDAP(JLINK_CORESIGHT_DP_REG_ABORT, 0, 0x1E);

JLINK_ExecCommand()

Gives the option to use J-Link Command Strings in the J-Link script file.

Prototype

int JLINK_ExecCommand(const char* sMsg);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

Example

JLINK_ExecCommand("TraceSampleAdjust TD=2000");

Note:
Has no effect when executed in Flasher stand-alone mode or when calling this function from a function that implements the __probe attribute.

JLINK_FILE_Read()

Supported since V7.96 of the J-Link software.

Prototype

int JLINK_FILE_Read(const U8* pFilename, U8* pBuf, U32 Offset, U32 Length, U32* pCRC);

Parameter

Parameter	Description
pFilename	Pointer to file name
pBuf	Pointer to data buffer
Offset	Offset into file
Length	Number of bytes to be read

Return Value

Return value	Description
>= 0	OK, number of bytes read from file (may be smaller than <Length>)
< 0	Error

Example

/*********************************************************************
*
*       SetupTarget
*/
int SetupTarget(void) {
  int r;
  U32 i;
  U32 NumBytesKeyFile;
  U8 abKeys[32];
  //
  // Output test values for <Keyfile>
  //
  NumBytesKeyFile = 32;
  r = JLINK_FILE_Read("C:\\Temp\\Keyfile.bin", &abKeys[0], 0, NumBytesKeyFile, 0);
  if (r < 0) {
    JLINK_SYS_Report("Failed to read from keyfile.");
    return -1;
  }
  JLINK_SYS_Report1("NumBytes read from keyfile: ", r);
  if (r < NumBytesKeyFile) {
    JLINK_SYS_Report1("Keyfile smaller than expected. <NumBytes> reduced to: ", r);
    NumBytesKeyFile = r;
  }
  JLINK_SYS_Report("Keyfile data:");
  i = 0;
  do {
    JLINK_SYS_Report1("", abKeys[i]);
    i += 1;
  } while (i < NumBytesKeyFile);
  return 0;
}

Used file: File:JLinkScriptFile Example Keyfile.zip

JLINK_FILE_GetSize()

Supported since V8.10a of the J-Link software.

Prototype

int JLINK_FILE_GetSize(const U8* pFilename);

Parameter

Parameter	Description
pFilename	Pointer to file name

Return Value

Return value	Description
>= 0	OK, size of the file in bytes
< 0	Error

Example

/*********************************************************************
*
*       SetupTarget
*/
int SetupTarget(void) {
  U32 FileSize;
  //
  // Get the size of the specified file
  //
  FileSize = JLINK_FILE_GetSize(C:\\Temp\\Keyfile.bin);
  if (FileSize < 0) {
    JLINK_SYS_Report("Error! Could not get the size of the specified file.");
    return -1;
  }
  JLINK_SYS_Report1("FileSize: ", FileSize);
  return 0;
}

Used file: File:JLinkScriptFile Example Keyfile.zip

JLINK_GetTime()

Returns J-Link (DLL) uptime in milliseconds.
Intended usage: timeouts and time measurements.

Prototype

int JLINK_GetTime(void);

JLINK_GetPinState()

Gets the state of a specific pin.

Prototype

int JLINK_GetPinState(U8 iPin);

Parameter	Description
iPin	Specifies the pin to get the state from

Parameter iPin

Value	Description
0	Pin 3
1	Pin 5
2	Pin 7
3	Pin 9
4	Pin 11
5	Pin 13
6	Pin 15
7	Pin 17

Return Value

Return value	Description
= 1	Pin state is HIGH
= 0	Pin state is LOW
< 0	Getting state for this pin is not supported by this J-Link

JLINK_JTAG_GetDeviceId()

Retrieves the JTAG ID of a specified device, in the JTAG chain. The index of the device depends on its position in the JTAG chain. The device closest to TDO has index 0.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_GetDeviceId(int DeviceIndex);

Return Value

Return value	Description
> 0	Device ID
= 0	No JTAG device found at Index

Example

/*********************************************************************
*
*       SetupTarget
*/
int SetupTarget(void) {
  int r;
  r = JLINK_JTAG_GetDeviceId(0);
  JLINK_SYS_Report1("Device 0: ", r);
  r = JLINK_JTAG_GetDeviceId(1);
  JLINK_SYS_Report1("Device 1: ", r);

  return 0;
}

Example output on STM32F103ZG:

Device 0: 0x3BA00477
Device 1: 0x06430041

JLINK_JTAG_GetU32()

Gets 32 bits JTAG data, starting at given bit position.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_GetU32(int BitPos);

JLINK_JTAG_ReadWriteBits()

This function stores the specified number of bits in the output buffers, transfers the whole content of the output buffers to the JTAG device(s) and stores the received data in the input buffer.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_ReadWriteBits(const U8* pTDI, U8* pTMS, U8* pTDO, unsigned NumBits);

Parameter	Description
pTDI	Pointer to input buffer
pTMS	Pointer to mode select buffer
pTDO	Pointer to output buffer
NumBits	Number of bits to read and write

Note:
Buffers are used as 8-bits/clocks per U8.

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_JTAG_Reset()

Performs a TAP reset and tries to auto-detect the JTAG chain (Total IRLen, Number of devices). If auto-detection was successful, the global DLL variables which determine the JTAG chain configuration, are set to the correct values. For more information about the known global DLL variables, please refer to Global DLL variables.

Note:
This will not work for devices which need some special init (for example to add the core to the JTAG chain), which is lost at a TAP reset.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_Reset(void);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_JTAG_SetDeviceId()

Sets the JTAG ID of a specified device, in the JTAG chain. The index of the device depends on its position in the JTAG chain. The device closest to TDO has index 0. The Id is used by the DLL to recognize the device. Before calling this function, please make sure that the JTAG chain has been configured correctly by setting the appropriate global DLL variables. For more information about the known global DLL variables, please refer to Global DLL variables.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_SetDeviceId(int DeviceIndex, U32 Id);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_JTAG_StartDR()

Brings the state machine of the selected device in the JTAG-chain in SHIFT-DR state.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_StartDR(void);

Return Value

Return value	Description
>= 1	Bit position in JTAG buffer
= 0	Error

JLINK_JTAG_Store()

Stores a JTAG sequence (max. 64 bits per pin) in the DLL JTAG buffer.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_Store(U32 tms, U32 tdi, U32 NumBits);

Parameter	Description
tms	Bitmask to output on TMS
tdi	Bitmask to output on TDI
NumBits	NumBits to store for each pin. Maximum 32.

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_JTAG_StoreClocks()

Stores a given number of clocks in the DLL JTAG buffer.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_StoreClocks(int NumClocks);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_JTAG_StoreDR()

Stores JTAG data in the DLL JTAG buffer.
Before calling this function, please make sure that the JTAG chain has been configured correctly by setting the appropriate global DLL variables. For more information about the known global DLL variables, please refer to Global DLL variables.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_StoreDR(U32 tdi, int NumBits);

Parameter	Description
tdi	Bitmask to output on TDI
NumBits	NumBits to store

Return Value

Returns the bit position.

JLINK_JTAG_StoreIR()

Stores a JTAG instruction in the DLL JTAG buffer.
Before calling this function, please make sure that the JTAG chain has been configured correctly by setting the appropriate global DLL variables. For more information about the known global DLL variables, please refer to Global DLL variables.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_StoreIR(U32 Cmd);

Return Value

Returns the bit position.

JLINK_JTAG_Write()

Writes a JTAG sequence (max. 64 bits per pin).

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_Write(U32 tms, U32 tdi, U32 NumBits);

Parameter	Description
tms	Bitmask to output on TMS
tdi	Bitmask to output on TDI
NumBits	NumBits to write

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_JTAG_WriteClocks()

Writes a given number of clocks.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_WriteClocks(int NumClocks);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_JTAG_WriteDR()

Writes JTAG data. Before calling this function, please make sure that the JTAG chain has been configured correctly by setting the appropriate global DLL variables. For more information about the known global DLL variables, please refer to Global DLL variables.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_WriteDR(U32 tdi, int NumBits);

Parameter	Description
tdi	Bitmask to output on TDI
NumBits	NumBits to store

Return Value

Returns the bit position.

JLINK_JTAG_WriteDRCont()

Writes data of variable length. This function expects to be in Shift-DR state and remains there. This function expects that the JTAG chain has already be configured before. It does not try to perform any JTAG identification before sending the DR-data.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_WriteDRCont(U32 Data, int NumBits);

Return Value

Returns the bit position.

Example

//
// Write a 67-bit register on DR path of JTAG
//
JLINK_JTAG_StartDR();                 // Get TAP state machine into Shift-DR state
JLINK_JTAG_WriteDRCont(Data_31to0, 32);  // Write [31:0] and remain state machine in Shift-DR state
JLINK_JTAG_WriteDRCont(Data_63to32, 32); // Write [63:32] and remain state machine in Shift-DR state
JLINK_JTAG_WriteDREnd(Data_66to64, 3);   // Write [66:64] Shift in last bits and move state machine to Update-DR

JLINK_JTAG_WriteDREnd()

Writes data of variable length and remains in UPDATE-DR state. This function expects that the JTAG chain has already be configured before. It does not try to perform any JTAG identification before sending the DR-data.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_WriteDREnd(U32 Data, int NumBits);

Return Value

Returns the bit position.

JLINK_JTAG_WriteIR()

Writes a JTAG instruction.

Before calling this function, please make sure that the JTAG chain has been configured correctly by setting the appropriate global DLL variables. For more information about the known global DLL variables, please refer to Global DLL variables.

Note:
Can be used with both JTAG and cJTAG interface.

Prototype

int JLINK_JTAG_WriteIR(U32 Cmd);

Return Value

Returns the bit position.

JLINK_PIN_Override()

This function allows to override some of the J-Link pins and assign a special functionality to them (GPIO, UART, ...). For example setting the functionality to GPIO allows to implement almost any protocol on these pins which can give some extra flexibility in some cases.

Prototype

int JLINK_PIN_Override(const U32* paMode, U32* paState);

Parameter	Description
paMode	Pointer to JLINK_PIN_MAX_NUM_PINS-element array that holds the configuration to be assigned to the pins. Each element of the array describes a pin that can be overridden, resulting in a total of JLINK_PIN_MAX_NUM_PINS pins that can be overridden.
paState	Pointer to JLINK_PIN_MAX_NUM_PINS-element array that is used to store the state of each pin. This for example can be used to read the current data on the pin, if it is configured as JLINK_PIN_OVERRIDE_MODE_PIO_IN. State may be == 0 for LOW or == 1 for HIGH.

Array offset of paMode / paState to Pin No mapping

Array element	Description
0	Pin 3
1	Pin 5
2	Pin 7
3	Pin 9
4	Pin 11
5	Pin 13
6	Pin 15
7	Pin 17

Possible values passed via paMode

Value	Description
JLINK_PIN_OVERRIDE_MODE_RELEASE	Releases the override on this pin. It returns to its original functionality.
JLINK_PIN_OVERRIDE_MODE_PIO_IN	Configures the pin as GPIO input.
JLINK_PIN_OVERRIDE_MODE_PIO_OUT_LOW	Configures the pin as GPIO output state LOW.
JLINK_PIN_OVERRIDE_MODE_PIO_OUT_HIGH	Configures the pin as GPIO output state HIGH.
JLINK_PIN_OVERRIDE_MODE_UART_TX	Configures the pin as UART Tx pin.
JLINK_PIN_OVERRIDE_MODE_UART_RX	Configures the pin as UART rx pin.
JLINK_PIN_OVERRIDE_MODE_UART_RXTX	Configures pin for half-duplex UART functionality which means this pin in Tx and Rx. Cannot be used together with other UART defines.

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

Example

The following example shows how to output a default->low->(wait 2500ms)->high->(wait 2500ms)->default signal on pin 15 (= nRESET) after InitTarget()

U32 _aPINMode[8];    // JLINK_PIN_MAX_NUM_PINS
U32 _aPINState[8];   // JLINK_PIN_MAX_NUM_PINS

/*********************************************************************
*
*       SetupTarget
*/
int SetupTarget(void) {
  int i;
  int r;

  i = 0;
  do {
    _aPINMode[i] = JLINK_PIN_OVERRIDE_MODE_RELEASE;      // Do not override any pin by default
    i += 1;
  } while(i < JLINK_PIN_MAX_NUM_PINS);
  //
  // Initially, we check if pin override is supported
  //
  r = JLINK_PIN_Override(&_aPINMode[0], &_aPINState[0]);
  if (r < 0) {
    JLINK_SYS_Report("ERROR: Pin override is not supported by the connected J-Link");
    return r;
  }
  _aPINMode[6] = JLINK_PIN_OVERRIDE_MODE_PIO_OUT_LOW;
  r = JLINK_PIN_Override(&_aPINMode[0], &_aPINState[0]);
  JLINK_SYS_Sleep(2500);
  _aPINMode[6] = JLINK_PIN_OVERRIDE_MODE_PIO_OUT_HIGH;
  r = JLINK_PIN_Override(&_aPINMode[0], &_aPINState[0]);
  JLINK_SYS_Sleep(2500);
  //
  // Restore pin configuration of J-Link
  //
  i = 0;
  do {
    _aPINMode[i] = JLINK_PIN_OVERRIDE_MODE_RELEASE;      // Do not override any pin by default
    i += 1;
  } while(i < JLINK_PIN_MAX_NUM_PINS);
  JLINK_PIN_Override(&_aPINMode[0], &_aPINState[0]);
  return 0;
}

JLINK_MemRegion()

This command is used to specify memory areas with various region types.

Prototype

int JLINK_MemRegion(const char* sConfig);

Syntax of sConfig

<StartAddressOfArea>-<EndAddressOfArea> <RegionType>

Parameter RegionType

Region type	Description
N	Normal
C	Cacheable
X	Excluded
XI	Excluded & Illegal
I	Indirect access
A	Alias (static, e.g. RAM/flash that is aliased multiple times in one area. Does not change during the debug session.)
AD	Alias (dynamic, e.g. memory areas where different memories can be mapped to.)

Return value	Description
>= 0	O.K.
< 0	Error

Example

JLINK_MemRegion("0x100000-0x1FFFFF C")

Note:
Has no effect when executed in Flasher stand-alone mode or when calling this function from a function that implements the __probe attribute.

JLINK_MEM_WriteU8()

Writes a byte to the specified address.

Prototype

int JLINK_MEM_WriteU8(U32 Addr, U32 Data);

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_MEM_WriteU16()

Writes a halfword to the specified address.

Prototype

int JLINK_MEM_WriteU16(U32 Addr, U32 Data);

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_MEM_WriteU32()

Writes a word to the specified address.

Prototype

int JLINK_MEM_WriteU32(U32 Addr, U32 Data);

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_MEM_ReadU8()

Reads a byte from the specified address.

Prototype

U8 JLINK_MEM_ReadU8 (U32 Addr);

JLINK_MEM_ReadU16()

Reads a halfword from the specified address.

Prototype

U16 JLINK_MEM_ReadU16(U32 Addr);

JLINK_MEM_ReadU32()

Reads a word from the specified address.

Prototype

U32 JLINK_MEM_ReadU32(U32 Addr);

JLINK_MEM_Preserve()

Preserves selected memory area in amount of set size.

Prototype

int  JLINK_MEM_Preserve(U32 Addr, U32 NumBytes);

Parameter	Description
Addr	Specifies the address starting point which to preserve
NumBytes	Number of bytes to preserve

Return Value

Return value	Description
>= 0	O.K., handle to preserved area (may be used by JLINK_MEM_Restore())
< 0	Error
-1	Unspecified error
-2	Failed to read memory to preserve

JLINK_MEM_Restore()

Restore memory that has been previously preserved via JLINK_MEM_Preserve(). Returned handle is used to identify the restore region.

Prototype

int  JLINK_MEM_Restore(int Handle);

Parameter	Description
Handle	Specifies handle to identify the restore region

Return Value

Return value	Description
O.K.
Error
Unspecified error
Failed to write memory to restore

JLINK_MEM_Fill()

Fill memory with given value. Only the lowest byte of <FillVal> is taken into account.

Prototype

int  JLINK_MEM_Fill(U32 Addr, U32 NumBytes, U32 FillVal);

Parameter	Description
Specifies the address starting point which to preserve
Number of bytes to preserve
Value used for filling

Return Value

Return value	Description
O.K., handle to preserved area (may be used by JLINK_MEM_Restore())
Error
Unspecified error
Failed to read memory to fill

JLINK_RISCV_DMI_AutodetectDMISettings()

Available for RISC-V cores only.

Determines DMI settings by reading the DTMCS register (accessible via its own JTAG instruction).

Prototype

int JLINK_RISCV_DMI_AutodetectDMISettings(void);

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error

Note:

1. DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
2. DMI accesses are not available if the RISC-V core is behind a CoreSight DAP. Then the regular CORESIGHT_WriteDP / CORESIGHT_WriteAP() API should be used.

JLINK_RISCV_DMI_ClearState()

Available for RISC-V cores only.

Clears the sticky DMI state by setting DTMCS[DMIRESET].

Optionally also sets DTMCS[DMIHARDRESET] to abort any pending DMI accesses. (If <AbortPendingDMIAcc> == 1).

Prototype

int JLINK_RISCV_DMI_ClearState(unsigned AbortPendingDMIAcc);

Parameter	Description
AbortPendingDMIAcc	Optional. Sets DTMCS[DMIHARDRESET]

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error

Note:

1. DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
2. DMI accesses are not available if the RISC-V core is behind a CoreSight DAP. Then the regular CORESIGHT_WriteDP / CORESIGHT_WriteAP() API should be used.
3. Automatically selects DMI for JTAG DR-Scan afterwards.be used.

JLINK_RISCV_DMI_ReadReg()

Available for RISC-V cores only.

Reads a DMI register.

Triggers a read to a DMI register and triggers a final NOP operation to get the data of the triggered read. If triggering the read or NOP causes a busy response of the DMI, the dtmcs.dmistat (sticky error state) will be cleared and the access is re-triggered. So this function performs auto-repeat logic in case of a slow DMI which avoids having the repeat logic in the caller level at all places.

Prototype

int JLINK_RISCV_DMI_ReadReg(U32 RegAddr, U32* pData);

Parameter	Description
RegAddr	Register address
pData	Pointer to data

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error
== -2	Timeout (DMI operation never finished)
== -3	DMI reported exception / abort

Note:

1. DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
2. DMI accesses are not available if the RISC-V core is behind a CoreSight DAP. Then the regular CORESIGHT_WriteDP / CORESIGHT_WriteAP() API should be used.

JLINK_RISCV_DMI_ReadRegMultiple()

Available for RISC-V cores only.

Reads the same DMI register multiple times.

Triggers a series of read accesses to a DMI register and a final NOP operation to get the data of the last triggered read. If triggering a read or NOP causes a busy response of the DMI, the dtmcs.dmistat (sticky error state) will be cleared and the access is re-triggered. So this function performs auto-repeat logic in case of a slow DMI which avoids having the repeat logic in the caller level at all places.

Prototype

int JLINK_RISCV_DMI_ReadRegMultiple(U32 RegAddr, U32* paData, U32 NumItems);

Parameter	Description
RegAddr	Register address
paData	Pointer to data array
NumItems	Number of items to read

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error
== -2	Timeout (DMI operation never finished)
== -3	DMI reported exception / abort

Note:

1. DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
2. DMI accesses are not available if the RISC-V core is behind a CoreSight DAP. Then the regular CORESIGHT_WriteDP / CORESIGHT_WriteAP() API should be used.

JLINK_RISCV_DMI_SetDMISettings()

Available for RISC-V cores only.

Manually sets the DMI settings and ignores whatever is reported by the DTMCS register.

Prototype

int JLINK_RISCV_DMI_SetDMISettings(U32 NumAddrBits, U32 NumIdleClocks, U32 AccTimeout);

Parameter	Description
NumAddrBits	Number of address bits
NumIdleClocks	Number of idle clocks
AccTimeout	Access timeout for a single DMI access in [ms]

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error

Note:

1. DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
2. DMI accesses are not available if the RISC-V core is behind a CoreSight DAP. Then the regular CORESIGHT_WriteDP / CORESIGHT_WriteAP() API should be used.

JLINK_RISCV_DMI_WriteReg()

Available for RISC-V cores only.

Writes a DMI register.

Triggers a write to a DMI register and triggers a final NOP operation to make sure that the triggered DMI write completed. If triggering the write or NOP causes a busy response of the DMI, the dtmcs.dmistat (sticky error state) will be cleared and the access is re-triggered. So this function performs auto-repeat logic in case of a slow DMI which avoids having the repeat logic in the caller level at all places.

Prototype

int JLINK_RISCV_DMI_WriteReg(U32 RegAddr, U32 Data);

Parameter	Description
RegAddr	Register address
Data	Data to write

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error
== -2	Timeout (DMI operation never finished)
== -3	DMI reported exception / abort

Note:

1. DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
2. DMI accesses are not available if the RISC-V core is behind a CoreSight DAP. Then the regular CORESIGHT_WriteDP / CORESIGHT_WriteAP() API should be used.

JLINK_RISCV_DMI_WriteRegMultiple()

Available for RISC-V cores only.

Writes the same DMI register multiple times.

Triggers a series of write accesses to a DMI register and a final NOP operation to make sure that the last triggered write is complete. If triggering a write or NOP causes a busy response of the DMI, the dtmcs.dmistat (sticky error state) will be cleared and the access is re-triggered. So this function performs auto-repeat logic in case of a slow DMI which avoids having the repeat logic in the caller level at all places.

Prototype

int JLINK_RISCV_DMI_WriteRegMultiple(U32 RegAddr, const U32* paData, U32 NumItems);

Parameter	Description
RegAddr	Register address
paData	Pointer to data array
NumItems	Number of items to write

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error
== -2	Timeout (DMI operation never finished)
== -3	DMI reported exception / abort

Note:

1. DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
2. DMI accesses are not available if the RISC-V core is behind a CoreSight DAP. Then the regular CORESIGHT_WriteDP / CORESIGHT_WriteAP() API should be used.

JLINK_RISCV_WriteCSR()

Writes the CSR with the given index.
Available for RISC-V cores only.
Supported since V7.94c

Prototype

int JLINK_RISCV_WriteCSR(U32 RegIndex, U32 DataL, U32 DataH, U32 RegSize);

Parameter	Description
RegAddr	Register index. Indexes may be taken from RISC-V spec. where e.g. mstatus = 0x300, mtvec = 0x305, ...
DataL	Data low-word to write.
DataH	Data high-word to write.
RegSize	CSR size in bytes. Mainly needed where CSR size is not equal to XLEN of core, e.g. writing a 32-bit CSR on a 64-bit (RV64) target. May be 0 which causes XLEN to be assumed as CSR size.

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error

Limitations

• May only be used after a connection to the target has already been established, e.g. in SetupTarget() NOT in InitTarget()!
• May only be called while the target is halted.

JLINK_RISCV_ReadCSR()

Reads the CSR with the given index.
Available for RISC-V cores only.
Supported since V7.94c

Prototype

int JLINK_RISCV_ReadCSR(U32 RegIndex, U32* pDataL, U32* pDataH, U32 RegSize);

Parameter	Description
RegAddr	Register index. Indexes may be taken from RISC-V spec. where e.g. mstatus = 0x300, mtvec = 0x305, ...
pDataL	Pointer to data low-word to be read from CSR.
pDataH	Pointer to data high-word to be read from CSR.
RegSize	CSR size in bytes. Mainly needed where CSR size is not equal to XLEN of core, e.g. writing a 32-bit CSR on a 64-bit (RV64) target. May be 0 which causes XLEN to be assumed as CSR size.

Return Value

Return value	Description
>= 0	O.K.
< 0	Error
== -1	Unspecified error

Limitations

• May only be used after a connection to the target has already been established, e.g. in SetupTarget() NOT in InitTarget()!
• May only be called while the target is halted.

Example

int AfterResetTarget(void) {
  U32 v_L;
  U32 v_H;

  JLINK_RISCV_ReadCSR(0xF11, &v_L, &v_H, 0);  // mvendorid
  JLINK_SYS_Report1("mvendorid_L:", v_L);
  JLINK_SYS_Report1("mvendorid_H:", v_H);
  JLINK_RISCV_ReadCSR(0xF12, &v_L, &v_H, 0);  // marchid
  JLINK_SYS_Report1("marchid_L:", v_L);
  JLINK_SYS_Report1("marchid_H:", v_H);
  return 0;
}

JLINK_SelectTIF()

Selects a target interface. For a list of all available constants, please refer to Constants for global variable "JLINK_ActiveTIF"

Prototype

void JLINK_SelectTIF(U32 tif);

JLINK_SetDevice()

Selects / specifies the target device.

Prototype

int JLINK_SetDevice(const char* sDevice);

sDevice has to be a valid device identifier. For a list of all available device identifiers, please refer to the SEGGER homepage.

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

Example

JLINK_SetDevice("AT91SAM7S256");

JLINK_SWD_ReadWriteBits()

This function stores the specified number of bits in the output buffers, transfers the whole content of the output buffers to the SWD device and stores the received data in the input buffer.

Prototype

int JLINK_SWD_ReadWriteBits(const U8 * pDataIn, const U8 * pDirection, U8 * pDataOut, int NumBits);

Parameter	Description
pDataIn	Pointer to data to be send to the target
pDirection	Pointer to direction buffer
pDataOut	Pointer to buffer for receiving data from target
NumBits	Number of bits to read / write

Note:
Data and direction buffers are used as 8-bits / clocks per U8.

Return Value

Return value	Description
>= 0	O.K.
< 0	Error

Example

See: Sending data via SWD manually

JLINK_SYS_MessageBox()

Outputs a string in a message box.

Prototype

int JLINK_SYS_MessageBox(const char * sMsg);

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_SYS_MessageBox1()

Outputs a constant character string in a message box. In addition to that, a given value (can be a constant value, the return value of a function or a variable) is added, right behind the string.

Prototype

int JLINK_SYS_MessageBox1(const char * sMsg, int v);

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_SYS_Report()

Outputs a constant character string on stdio.

Prototype

int JLINK_SYS_Report(const char * sMsg);

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_SYS_Report1()

Outputs a constant character string on stdio. In addition to that, a given value (can be a constant value, the return value of a function or a variable) is added, right behind the string.

Prototype

int JLINK_SYS_Report1(const char * sMsg, int v);

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_SYS_Sleep()

Waits for a given number of milliseconds. During this time, J-Link does not communicate with the target.

Prototype

int JLINK_SYS_Sleep(int Delayms);

Return value	Description
>= 0	O.K.
< 0	Error

JLINK_SYS_UnsecureDialog()

Informs the user that the device needs to be unsecured for further debugging. This is usually done via a message box where possible (except on Linux & Mac).

Prototype

int JLINK_SYS_UnsecureDialog (const char* sText, const char* sQuestion, const char* sIdent, int DefaultAnswer, U32 Flags);

Parameter	Description
sText	Text printed to the logfile or presented in a message box
sQuestion	Question printed in the message box after sText
sIdent	Unique ID for the request. User settings like "Do not show again" are saved per Unique ID.
DefaultAnswer	Default answer for messages with timeout or non-GUI versions. Only used if not setting is saved for the Unique ID.
Flags	Please consult the table below for valid values. Specifying a valid JLINK_DLG_TYPE flag is mandatory.

Parameter Flags

Value	Description
JLINK_DLG_TYPE_PROT_READ	Read protection dialog
JLINK_DLG_TYPE_PROT_WRITE	Write protection dialog

Return Value

Return value	Description
= 1	User selected to unsecure the device
= 0	User selected to NOT unsecure the device

Note:
If executed in Flasher stand-alone mode or when calling this function from a function that implements the __probe attribute, no dialog is shown but the default answer is used

JLINK_TARGET_IsHalted()

Checks if the target device is halted.

Prototype

int JLINK_TARGET_IsHalted(void);

Return Value

Return value	Description
= 1	O.K. CPU is halted
= 0	O.K. CPU is not halted
< 0	Error

Example

/*********************************************************************
*
*       SetupTarget
*/
int SetupTarget(void) {
  int r;

  r = JLINK_TARGET_IsHalted();
  if (r == 0) {
    JLINK_SYS_Report("Target is not halted!");
  } else if (r == 1) {
    JLINK_SYS_Report("Target is halted!");
  } else {
    JLINK_SYS_Report("Error occurred!");
  }
  return 0;
}

JLINK_TARGET_Halt()

Halt the target device. Returns O.K. if the target is already halted.

Prototype

int JLINK_TARGET_Halt(void);

Return Value

Return value	Description
=> 1	Error
= 0	O.K.

Example

/*********************************************************************
*
*       SetupTarget
*/
int SetupTarget(void) {
  int r;

  r = JLINK_TARGET_Halt();
  if (r == 0) {
    JLINK_SYS_Report("Target is halted!");
  } else {
    JLINK_SYS_Report("Error occurred!");
  }
  return 0;
}

JLINK_TIF_ActivateTargetReset()

Sets nReset LOW.

Prototype

void JLINK_TIF_ActivateTargetReset(void);

JLINK_TIF_ReleaseTargetReset()

Sets nReset HIGH.

Prototype

void JLINK_TIF_ReleaseTargetReset(void);

JLINK_TIF_SetClrTCK()

Sets or clears the TCK pin.

Prototype

void JLINK_TIF_SetClrTCK(int OnOff);

Parameter	Description
OnOff	Desired state of TCK

Parameter OnOff

Value	Description
>= 1	Set pin to HIGH
= 0	Set pin to LOW

JLINK_TIF_SetClrTMS()

Sets or clears the TMS pin.

Prototype

void JLINK_TIF_SetClrTMS(int OnOff);

Parameter	Description
OnOff	Desired state of TMS

Parameter OnOff

Value	Description
>= 1	Set pin to HIGH
= 0	Set pin to LOW

JLINK_TIF_SetClrTDI()

Sets or clears the TCK pin.

Prototype

void JLINK_TIF_SetClrTDI(int OnOff);

Description
Desired state of TDI

Parameter OnOff

Value	Description
>= 1	Set pin to HIGH
= 0	Set pin to LOW

JLINK_TIF_SetSpeed()

Sets the target interface speed.

Prototype

void JLINK_TIF_SetSpeed(U32 Speed);

Parameter	Description
Speed	Speed in kHz.

JLINK_GetConfigData()

Gets the config data to a given key.

Prototype

int JLINK_GetConfigData(const char* sKey, U8* pBuf, U32 BufSize);

Parameter	Description
sKey	The key for which the data should be returned.
pBuf	Pointer to data buffer.
BufSize	Buffer size.

Return Value

Return value	Description
< 0	Error
>= 0	O.K., number of bytes written to <pBuf> (May be smaller than <BufSize>)

JLINK_GetConfigDataEx()

Gets the config data to a given key.

Prototype

int JLINK_GetConfigDataEx(const char* sKey, U8* pBuf, U32 BufSize, U32 Flags);

Parameter	Description
sKey	The key for which the data should be returned.
pBuf	Pointer to data buffer.
BufSize	Buffer size.
Flags	Valid flags: JLINK_GET_CONFIG_DATA_FLAG_HEX_DECODE

Return Value

Return value	Description
< 0	Error
>= 0	O.K., number of bytes written to <pBuf> (May be smaller than <BufSize>)

JLINK_GetConfigValue()

Gets the config value to a given key.

Prototype

int JLINK_GetConfigValue(const char* sKey, int* pValue);

Parameter	Description
sKey	The key for which the value should be returned.
pValue	Pointer to the value.

Return Value

Return value	Description
!= 0	Error
= 0	O.K.

Global DLL variables

The script file feature also provides some global variables which are used for DLL configuration. Some of these variables can only be set to some specific values, others can be set to the whole data type with. In the following all global variables and their value ranges are listed and described.
Note:
All global variables are treated as unsigned 32-bit values and are zero-initialized.

Legend

Abbreviation	Description
RO:	Variable is read-only
WO:	Variable is write-only
R/W:	Variable is read-write

Variable	Description	Example	R/W
CPU	Pre-selects target CPU J-Link is communicating with. Used in InitTarget() to skip the core auto-detection of J-Link. This variable can only be set to a known global J-Link DLL constant. For a list of all valid values, please refer to Global DLL constants	CPU = ARM926EJS;	WO
JTAG_IRPre	Used for JTAG chain configuration. Sets the number of IR-bits of all devices which are closer to TDO than the one we want to communicate with.	JTAG_IRPre = 6;	R/W
JTAG_DRPre	Used for JTAG chain configuration. Sets the number of devices which are closer to TDO than the one we want to communicate with.	JTAG_DRPre = 2;	RO
JTAG_IRPost	Used for JTAG chain configuration. Sets the number of IR-bits of all devices which are closer to TDI than the one we want to communicate with.	JTAG_IRPost = 6;	RO
JTAG_DRPost	Used for JTAG chain configuration. Sets the number of devices which are closer to TDI than the one we want to communicate with.	JTAG_DRPost = 0;	RO
JTAG_IRLen	IR-Len (in bits) of the device we want to communicate with.	JTAG_IRLen = 4	RO
JTAG_TotalIRLen	Computed automatically, based on the values of JTAG_IRPre, JTAG_DRPre, JTAG_IRPost and JTAG_DRPost.	v = JTAG_TotalIRLen;	RO
JTAG_AllowTAPReset	En-/Disables auto-JTAG-detection of J-Link. Has to be disabled for devices which need some special init (for example to add the core to the JTAG chain), which is lost at a TAP reset.	Allowed values: 0 Auto-detection is enabled. 1 Auto-detection is disabled.	WO
JTAG_Speed	Sets the JTAG interface speed. Speed is given in kHz.	JTAG_Speed = 2000; // 2MHz JTAG speed	R/W
JTAG_ResetPin	Pulls reset pin low / Releases nRST pin. Used to issue a reset of the CPU. Value assigned to reset pin reflects the state. 0 = Low, 1 = high.	JTAG_ResetPin = 0; SYS_Sleep(5);// Give pin some time to get low JTAG_ResetPin = 1;	WO
JTAG_TRSTPin	Pulls reset pin low / Releases nTRST pin. Used to issue a reset of the debug logic of the CPU. Value assigned to reset pin reflects the state. 0 = Low, 1 = high.	JTAG_TRSTPin = 0; SYS_Sleep(5); // Give pin some time to get low JTAG_TRSTPin = 1;	WO
JTAG_TCKPin	Pulls TCK pin LOW / HIGH. Value assigned to reset pin reflects the state. 0 = LOW, 1 = HIGH.	JTAG_TCKPin = 0;	R/W
JTAG_TDIPin	Pulls TDI pin LOW / HIGH. Value assigned to reset pin reflects the state. 0 = LOW, 1 = HIGH.	JTAG_TDIPin = 0;	R/W
JTAG_TMSPin	Pulls TMS pin LOW / HIGH. Value assigned to reset pin reflects the state. 0 = LOW, 1 = HIGH.	JTAG_TMSPin = 0;	R/W
JLINK_TRACE_Portwidth	Sets or reads Trace Port width. Possible values: 1,2, 4. Default value is 4.	JLINK_TRACE_Portwidth = 4;	R/W
EMU_ETB_IsPresent	If the connected device has an ETB and you want to use it with J-Link, this variable should be set to 1. Setting this variable in another function as InitEmu() does not have any effect.	void InitEmu(void) { EMU_ETB_IsPresent = 1; }	WO
EMU_ETB_UseETB	ETB instead of RAWTRACE capability of the emulator. Setting this variable in another function as InitEmu() does not have any effect.	EMU_ETB_UseETB = 0;	RO
EMU_ETM_IsPresent	Selects whether an ETM is present on the target or not. Setting this variable in another function as InitEmu() does not have any effect.	EMU_ETM_IsPresent= 0;	R/W
EMU_ETM_UseETM	Uses ETM as trace source. Setting this variable in another function as InitEmu() does not have any effect.	EMU_ETM_UseETM = 1;	WO
EMU_JTAG_DisableHWTransmissions	Disables use of hardware units for JTAG transmissions since this can cause problems on some hardware designs.	EMU_JTAG_DisableHWTransmissions = 1;	WO
CORESIGHT_CoreBaseAddr	Sets base address of core debug component for CoreSight compliant devices. Setting this variable disables the J-Link auto-detection of the core debug component base address. Used on devices where auto-detection of the core debug component base address is not possible due to incorrect CoreSight information.	CORESIGHT_CoreBaseAddr = 0x80030000;	R/W
CORESIGHT_IndexAHBAPToUse	Pre-selects an AP as an AHB-AP that J-Link uses for debug communication (Cortex-M). Setting this variable is necessary for example when debugging multi-core devices where multiple AHB-APs are present (one for each device). This function can only be used if a AP-layout has been configured via JLINK_CORESIGHT_AddAP()	JLINK_CORESIGHT_AddAP(0, CORESIGHT_AHB_AP); JLINK_CORESIGHT_AddAP(1, CORESIGHT_AHB_AP); JLINK_CORESIGHT_AddAP(2, CORESIGHT_APB_AP); // // Use second AP as AHB-AP // for target communication // CORESIGHT_IndexAHBAPToUse = 1;	WO
CORESIGHT_IndexAPBAPToUse	Pre-selects an AP as an APB-AP that J-Link uses for debug communication (Cortex-A/R). Setting this variable is necessary for example when debugging multi-core devices where multiple APB-APs are present (one for each device). This function can only be used if an AP-layout has been configured via JLINK_CORESIGHT_AddAP().	JLINK_CORESIGHT_AddAP(0, CORESIGHT_AHB_AP); JLINK_CORESIGHT_AddAP(1, CORESIGHT_APB_AP); JLINK_CORESIGHT_AddAP(2, CORESIGHT_APB_AP); // // Use third AP as APB-AP // for target communication // CORESIGHT_IndexAPBAPToUse = 2;	WO
CORESIGHT_AHBAPCSWDefaultSettings	Overrides the default settings to be used by the DLL when configuring the AHB-AP CSW register. By default, the J-Link DLL will use the following settings for the CSW: Cortex-M0, M0+, M3, M4 [30] == 0 [28] == 0 [27] == 0 [26] == 0 [25] == 1 [24] == 1 Configurable settings [30] == SPROT: 0 == secure transfer request [28] == HRPOT[4]: Always 0 [27] == HRPOT[3]: 0 == uncachable [26] == HRPOT[2]: 0 == unbufferable [25] == HRPOT[1]: 0 == unprivileged [24] == HRPOT[0]: 1 == Data access	---	WO
MAIN_ResetType	Used to determine what reset type is currently selected by the debugger. This is useful, if the script has to behave differently in case a specific reset type is selected by the debugger and the script file has a ResetTarget() function which overrides the J-Link reset strategies.	if (MAIN_ResetType == 2) { [...] } else { [...] }	RO
JLINK_ActiveTIF	Returns the currently used target interface used by the DLL to communicate with the target. Useful in cases where some special setup only needs to be done for a certain target interface, e.g. JTAG. For a list of possible values this variable may hold, please refer to Constants for global variable "JLINK_ActiveTIF".	---	RO
MAIN_IsFirstIdentify	Used to check if this is the first time we are running into InitTarget(). Useful if some init steps only need to be executed once per debug session.	if (MAIN_IsFirstIdentify == 1) { [...] } else { [...] }	RO
JLINK_TargetEndianness	Sets the target data and instruction endianness. For a list of possible values this variable may hold, please refer to Constants for global variable "JLINK_TargetEndianness"	JLINK_TargetEndianness = JLINK_TARGET_ENDIANNESS_I_LITTLE_D_LITTLE	RW
JLINK_SkipInitECCRAMOnConnect	Used to disable ECC RAM init on connect, e.g. in case only a attach to a running CPU shall be performed. Allowed values are 0 (do not skip) or 1 (skip).	SetSkipInitECCRAMOnConnect = 1	RW

Global DLL constants

Currently there are only global DLL constants to set the global DLL variable CPU. If necessary, more constants will be implemented in the future.

Constants for global variable: CPU

The following constants can be used to set the global DLL variable CPU:

• ARM7
• ARM7TDMI
• ARM7TDMIR3
• ARM7TDMIR4
• ARM7TDMIS
• ARM7TDMISR3
• ARM7TDMISR4
• ARM9
• ARM9TDMIS
• ARM920T
• ARM922T
• ARM926EJS
• ARM946EJS
• ARM966ES
• ARM968ES
• ARM11
• ARM1136
• ARM1136J
• ARM1136JS
• ARM1136JF
• ARM1136JFS
• ARM1156
• ARM1176
• ARM1176J
• ARM1176JS
• ARM1176IF
• ARM1176JFS
• CORTEX_M0
• CORTEX_M1
• CORTEX_M3
• CORTEX_M3R1P0
• CORTEX_M3R1P1
• CORTEX_M3R2P0
• CORTEX_M33
• CORTEX_M4
• CORTEX_M7
• CORTEX_A5
• CORTEX_A7
• CORTEX_A8
• CORTEX_A9
• CORTEX_A12
• CORTEX_A15
• CORTEX_A17
• CORTEX_R4
• CORTEX_R5

Constants for "JLINK_CORESIGHT_xxx" functions

APs

• CORESIGHT_AHB_AP
• CORESIGHT_APB_AP
• CORESIGHT_JTAG_AP
• CORESIGHT_CUSTOM_AP
• CORESIGHT_AXI_AP (Since V7.86e)

DP/AP register indexes

• JLINK_CORESIGHT_DP_REG_IDCODE
• JLINK_CORESIGHT_DP_REG_ABORT
• JLINK_CORESIGHT_DP_REG_CTRL_STAT
• JLINK_CORESIGHT_DP_REG_SELECT
• JLINK_CORESIGHT_DP_REG_RDBUF
• JLINK_CORESIGHT_AP_REG_CTRL
• JLINK_CORESIGHT_AP_REG_ADDR
• JLINK_CORESIGHT_AP_REG_DATA
• JLINK_CORESIGHT_AP_REG_BD0
• JLINK_CORESIGHT_AP_REG_BD1
• JLINK_CORESIGHT_AP_REG_BD2
• JLINK_CORESIGHT_AP_REG_BD3
• JLINK_CORESIGHT_AP_REG_ROM
• JLINK_CORESIGHT_AP_REG_IDR

Constants for global variable "JLINK_ActiveTIF"

• JLINK_TIF_JTAG
• JLINK_TIF_SWD

Constants for global variable "JLINK_TargetEndianness"

• JLINK_TARGET_ENDIANNESS_I_LITTLE_D_LITTLE
• JLINK_TARGET_ENDIANNESS_I_LITTLE_D_BIG
• JLINK_TARGET_ENDIANNESS_I_BIG_D_LITTLE
• JLINK_TARGET_ENDIANNESS_I_BIG_D_BIG

Script file language

The syntax of the J-Link script file language follows the conventions of the C-language, but it does not support all expressions and operators which are supported by the C-language. In the following, the supported operators and expressions are listed.

Supported Operators

The following operators are supported by the J-Link script file language:

• Multiplicative operators: *
• Additive operators: +, -
• Bitwise shift operators: <<, >>
• Relational operators: <, >, <=, >=
• Equality operators: ==, !=
• Bitwise operators: &, |, ^, ~
• Logical operators: &&, ||
• Assignment operators: =, *=, +=, -=, <<=, >>=, &=, ^=, |=

Supported basic type specifiers

The following basic type specifiers are supported by the J-Link script file language:

Name	Size (Bit)	Signed
void	N/A	N/A
char	8	signed
short	16	signed
int	32	signed
long	32	signed
U8	8	unsigned
U16	16	unsigned
U32	32	unsigned
I8	8	signed
I16	16	signed
I32	32	signed

Supported type qualifiers

The following type qualifiers are supported by the J-Link script file language:

• const
• signed
• unsigned

Supported declarators

The following declarators are supported by the J-Link script file language:

• Array declarators

Supported selection statements

The following selection statements are supported by the J-Link script file language:

• if-statements
• if-else-statements

Supported iteration statements

The following iteration statements are supported by the J-Link script file language:

• while
• do-while

Jump statements

The following jump statements are supported by the J-Link script file language:

• return

Sample script files

The J-Link Software and Documentation Pack comes with sample script files for different devices. The sample script files can be found at $JLINK_INST_DIR$\Samples\JLink\Scripts .

Script file limitations

• J-Link script file functions support max. 7 function parameters.
• J-Link script file functions do not support an array value as return value. If an array value needs to be returned, we recommend using a temporary variable for it:
  

  int SomeFunction (void) {
    int Array[2];
  
    Array[0] = 0x1234;
    Array[1] = 0x5678;
    return Array[0];  // <= Not supported
  }
  

  
  

  int SomeFunction (void) {
    int Array[2];
    int v;
  
    Array[0] = 0x1234;
    Array[1] = 0x5678;
    v = Array[0];
    return v;  // <= Supported
  }
  

Using J-Link script files

For most SEGGER applications, a J-Link script file can either be specified in the configuration dialog or via command line.

In some IDEs, the J-Link script file can be configured directly (e.g. in the project file). If the IDE does not offer a native J-Link script file configuration option, there are some alternative options which can be used to use J-Link script files anyhow. For further information regarding this, please refer to Using J-Link Script Files#Generic.

Please note that there are two different kind of script files:

• Plaintext script files (*.JLinkScript)
• Pre-compiled script files (*.pex)

Both script file types are accepted by the DLL.

J-Link Commander

To use a .JLinkScript file in J-Link Commander, simply specify the path to the script file via command line:

JLink.exe <Other CLI options> -JLinkScriptFile C:\Work\MyFile.JLinkScript

J-Flash

J-Link script files can be added via the project options in J-Flash.

1. Open project
2. Navigate to Options -> Project settings... -> MCU
3. Tick "Use J-Link script file"
4. Add J-Link script file via the file browser (three dots)

Embedded Studio

To use a .JLinkScript file in Embedded Studio simply go to the project settings Project->Edit Options... and set the J-Link script file path under Debug->J-Link->Script File
The absolute path on the drive must be used. Note that macros can be used (e.g. "$(ProjectDir)/MyScript.JLinkScript").

Ozone

To use a .JLinkScript file in Ozone first an Ozone project needs to be created. For that it is recommended to use the project wizard. At one of the setup steps you will have a field where you can set the .JLinkScript file.

Alternatively you can simply create a new project without setting the file via the wizard and add the script manually as described below. The Project file (.jdebug file), can then be edited to use a .JLinkScript file. The line you need to add would be Project.SetJLinkScript("<PathToScriptFile>");.

The Ozone Project file is in C/C++ similar format. To add the script file, please uncomment the BeforeTargetConnect() function and call the file function Project.SetJLinkScript("<PathToScriptFile>"); from it. <PathToScriptFile> would be the path to the .JLinkScript file.

Either the absolute path on the drive or the relative path in regards to the .jdebug file can be used.
Note:
This function can be called in any of the Ozone project functions but in most cases it is advisable to call it from BeforeTargetConnect(). More information can be found in the Ozone user manual.

Example

void BeforeTargetConnect (void) {
  //
  // Trace pin init is done by J-Link script file as J-Link script files are IDE independent
  //
  Project.SetJLinkScript("./TraceExample.JLinkScript");
}

To add a script file to an already existing Ozone project you can also use the GUI and set the script via Tools->J-Link Settings->J-Link Script.

SystemView

In order to set the J-Link script file to use the following steps are necessary:

1. Start the SystemView application
2. Open up the Recorder Configuration
   • Navigate to Target -> Recorder Configuration in the menu bar
3. Select "J-Link" as recorder
   
   
   
   
4. Switch to the advanced settings of the configuration dialog and select the desired J-Link script file to be used.
   
   
   
   

IAR EWARM

Please refer to: IAR EWARM#Using J-Link script files

Keil MDK

Please refer to: Keil MDK#Using J-Link Script Files

Eclipse

Please refer to: Eclipse#Using J-Link script files

Generic

1. If no J-Link settings file is present, "Default.JLinkScript" is loaded if present in the same directory as the J-Link DLL.
2. If a settings file is present (used by IDE), but no script file is specified inside of the settings file:
   1. "<NameOfSettingsFile>.JLinkScript" is loaded if present in the same directory as the settings file.
   2. A J-Link Script file can be set inside the J-Link settings file
   1. Open the J-Link settings file in a text editor
   2. Go to section [CPU]. If not present, add it.
   3. Edit the line ScriptFile="<path to script file>" to contain the script file to be used. If not present, add it. E.g:
      

      [CPU]
      ScriptFile="C:\Some\Path\Example.JLinkScriptFile"

J-Link script file examples

This section lists examples for solutions to different, common scenarios that can be solved using a J-Link Script file.

Generic Template

A generic template that can be used as a starting point for creating custom J-Link script files.

• Generic_Template.JLinkScript

JTAG initialization

J-Link script files support dynamic and static JTAG chain device selection.

• Dynamic JTAG chain device selection: Template_JTAGAutoDetection.JLinkScript
• Static JTAG chain device selection: Template_JTAGSpecificConnect.JLinkScript
• Custom JTAG chain configuration: Template_CustomJTAGChain.JLinkScript

Exclude illegal memory regions

This example shows how to exclude an illegal memory region using the map region J-Link Command String. The J-Link DLL will ignore all read / write accesses to the specified region(s). This can be used if an IDE for example accesses an illegal memory address for some reason.

• Template_ExcludeIllegalRegions.JLinkScript

Connect to a specific core of a multi-core device

By default J-Link auto detects the ROM-table and selects the first core of the target device it finds. If you want to select another core as the by default selected core, you need to setup a J-LinkScript file. Within the JLinkScript file you need to define the AP map of the device, the AP to use for your core and the base address of the debug registers of the core you want to select.

The next example shows how to select the correct AP to connect to the Cortex-M7 core on a STM32H757 series device.

• Example_SwitchAPtoSelectSpecificCore_ST_STM32H753xxx.JLinkScript

This example shows a special handling for NXP S32V234 (Cortex-A53, Cortex-M4, Cortex-M0+):
The special handling includes setting the core base address as well as the CTI base address.

• Template Example_ConfigTargetSettings_NXP_S32V234.JLinkScript

Override J-Link pins

This sample shows how to use the J-Link pin override functionality. This can be for example useful if a special sequence has to be send to the target in order to enable the debug interface.

• Template_PinOverride.JLinkScript

Adding missing ROM table entries

In some cases the target devices ROM table is not complete or broken. However, some components might be required for debug purposes (e.g. trace components). In such a case, these components can be added manually. Keep in mind that there are sometimes multiple memory spaces on one target device so make sure the addresses you are setting are accessible by an external debug probe.

• Template_AddCompMissingInROMTable.JLinkScript

The corresponding command strings are documented here: J-Link_Command_Strings

Init ECC work RAM

Some devices provide the option to activate an ECC RAM mode. In this case the work RAM used for the J-Link RAM Codes is also set to ECC which will result in the RAM Codes to fail, as the RAM is not readable on erased value. The following sample shows how to tell the J-Link that the RAM has to be initialized so that the RAM codes do not fail because of the ECC setting of the RAM.

• Template_SetInitWorkRAMOnConnect.JLinkScript

Init Additional RAM area

Some devices do have additional RAM or TCM areas that are not enabled after reset.
See: J-Link RAM initialization
The following samples for the Renesas RZG3E and RZT2H show how to use J-Link script files to configure additional RAM areas.

• Template_Renesas_RZG3E_EnableSRAM1.JLinkScript
• Template_Renesas_RZT2H_RZN2H_InitTCM.JLinkScript

Cache handling

Some devices require special handling of their Cache.
The following shows how to use J-Link script files to configure caches:

• Example_DisableCacheAtEL2_ARMv8A.JLinkScript

Reset sequences

There are multiple strategies to reset a target device. These strategies can be customized via a J-Link Script file. Following are examples showing different reset strategies.

• ARMv8-M J-Link Reset type 0: Normal (reset via system reset request)
• ARMv7-M J-Link Reset type 0: Normal (reset via system reset request)
• ARMv7-M J-Link Reset type 2: ResetPin (reset via reset pin)
• ARMv8AR J-Link Reset type 0: Normal (reset via system reset request)

Connect sequences

The generic connect sequence depends on the core of the selected device. These sequence can be customized via a J-Link Script file. Following are examples showing the generic connect sequences:

• TBD

Following are examples showing the device specific connect sequences:

• ST STM32U5 - Connect under reset

Sending raw data via JTAG / SWD manually

J-Link Script files allow to transfer raw data via SWD/JTAG manually. This is rarely required but might be needed for some special devices.

• SWD switching sequence and read ID via JLINK_SWD_ReadWriteBits
• JTAG switching sequence and read ID via JLINK_JTAG_ReadWriteBits
• JTAG_Write/Store_*-API read ID sample

Overriding device specific connect

For some devices, a device specific connect was implemented to provide he best debug experience for most debug scenarios. However, in some rare cases this might cause issues with some setups. To override this device specific connect, the following script file can be use.

• J-Link InitTarget() override

Halt after reset

In some scenarios a device may only be accessible for a short period after reset. The device may still be usable by connecting under reset, but not all devices support this reset type. Such cases can sometimes still be saved by quickly halting the target, before the access gets blocked. The following script file issues a pin reset and requests a halt as soon as the ID can be read, which should generally be the earliest possible time.

• Example_ResetAndHalt.JLinkScript
• Example_HaltAfterBTLUsingBP_RaspberryPi_RP2040.JLinkScript

AHB-AP communication

In some cases, data has to be written via (multiple) AHB-AP(s) to establish connection to a target device. To name some examples:

• Core to connect to has to be started via another core.
• Device protection has to be lifted via a device specific AP.

For this purpose, the following template/examples can be used.

• Select/switch, write and read AHB-APs: Template_SelectWriteReadAHBAP.JLinkScript
• Select/switch, write and read APs (SoC-600 based): Template_SelectWriteReadAP_SoC600.JLinkScript

AXI-AP communication

In some cases, data has to be written via (multiple) AXI-AP(s) to establish connection to a target device. To name some examples:

• Core to connect to has to be started via another core.
• Device protection has to be lifted via a device specific AP.

For this purpose, the following template/examples can be used.

• Select/switch, write and read AXI-APs: Template_SelectWriteReadAXIAP.JLinkScript
• Select/switch, write and read APs (SoC-600 based): Template_SelectWriteReadAP_SoC600.JLinkScript

Specify AHB-AP for background access

Some devices (e.g. Cortex-A) are mainly accessed via APB-AP but provide an AHB-AP for background access. This AHB-AP can be used by J-Link to make e.g. RTT work non-intrusively on these devices, but it must be manually specified as the existance of such an AP is not mandatory.

• Select AHB-AP for background access: Example_SetAPForBGAccess.JLinkScript

Skip debug de-init

The J-Link Software will de-init the debug registers on disconnect per default. However, in some cases it might be desirable to skip this step, e.g. when the target application requires the Cycle Counter which will be disabled as part of the DWT unit disable.

• Skip debug de-init on disconnect/close: Example_SkipDebugDeInit.JLinkScript

DAP Multi Acc

A script showcasing how to handle DAP (Debug Access Port) multiple access functionality. The Script shows how to use the JLINK_CORESIGHT_WriteDAPMultiple, JLINK_CORESIGHT_WriteDAPRepeatData, JLINK_CORESIGHT_ReadDAPMultiple and JLINK_CORESIGHT_ReadDAPMultipleCheck function. This can be used to output custom sequences (e.g. if they are required to enable the device).

• Template_DAPMultiAcc.JLinkScript

Attach Mode

This script demonstrates how to set up and utilize the attach mode functionality. For a high-level CPU debug setup to write certain memory locations, initializing PLL for faster download etc.

• Template_AttachMode.JLinkScript

Low Level CPU

This script provides low-level access to a CPU.

• Template_LowLevel_CPU_CortexM.JLinkScript

File I/O

• Template_FileRead.JLinkScript
• Template_FileGetSize.JLinkScript