J-Link script files

From SEGGER Wiki
Jump to: navigation, search

This article is still under construction. For any missing sections/chapters please refer to the PDF version of the J-Link User Manual (UM08001).

In some situations it it 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 which is necessary can be supported.

Contents

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


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

Replaces the target-CPU-auto-find procedure of the J-Link DLL. Useful for target CPUs that are not accessible by default and need some special steps to be executed before the normal debug probe connect procedure can be executed successfully. Example devices are MCUs from TI which have a so-called ICEPick JTAG unit on them that needs to be configured via JTAG, before the actual CPU core is accessible via JTAG.

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

Replaces reset strategies of DLL. 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.

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

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 override the host interface (USB or IP). It will be called right before the connection to the emulator is opened.

Allowed J-Link Command Strings

SetHostIf

Prototype

int InitEMU(void);

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

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

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_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)
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_SYS_Sleep() (int Delayms)

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

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

Prototype

int JLINK_JTAG_WriteDRCont(U32 Data, int NumBits);

Return Value

Returns the bit position.

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.

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.

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  MEM_ReadU8 (U32 Addr);

JLINK_MEM_ReadU16()

Reads a halfword from the specified address.

Prototype

U16 MEM_ReadU16(U32 Addr);

JLINK_MEM_ReadU32()

Reads a word from the specified address.

Prototype

U32 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_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 and write

Return Value

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

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.

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_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

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.

Using J-Link script files

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 (*.JLinkScriptFile)
  • 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

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.
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");
}

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
    SystemView JLinkScriptFile Recorder.png

  4. Switch to the advanced settings of the configuration dialog and select the desired J-Link script file to be used.
    SystemView JLinkScriptFile.png

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

If no J-Link settings file is present, "Default.JLinkScript" is loaded if present in the same directory as the J-Link DLL.
If a J-Link J-Link settings file is present, but no script file is specified inside of the script file, "<Name of the J-Link settings file>.JLinkScript" is loaded if present in the same directory as the J-Link settings file.
Alternatively, a J-Link script file can be specified by using one of the following ways:

  1. Via J-Link settings file:
    1. Add or edit the line
    2. "ScriptFile="<path to script file>""
      
    3. (e.g. ScriptFile="C:\Work\Test.jlinkscript") to the [CPU] section of the J-Link settings file
  2. Via J-Link command strings
    1. Execute the command string
    2. "ScriptFile = <path>"
      
    3. e.g. ScriptFile = C:\Work\Test.jlinkscript
  3. Via the J-Link control panel
    1. Specify the path to the J-Link script file in the tab Settings of the J-Link control panel
      GenericIDE ScriptFile ControlPanel Marked.png

J-Link script file samples

JTAG initialization

In this example we assume a JTAG chain with two devices on it (Cortex-A8 4 bits IRLen, custom device 5-bits IRLen).

void InitTarget(void) {
  JLINK_SYS_Report("J-Link script example.");
  JTAG_Reset();               // Perform TAP reset and J-Link JTAG auto-detection
  if (JTAG_TotalIRLen != 9) { // Basic check if JTAG chain information matches
    MessageBox("Can not find xxx device");
    return 1;
  }
  JTAG_DRPre  = 0;         // Cortex-A8 is closest to TDO, no no pre devices
  JTAG_DRPost = 1;         // 1 device (custom device) comes after the Cortex-A8
  JTAG_IRPre  = 0;         // Cortex-A8 is closest to TDO, no no pre IR bits
  JTAG_IRPost = 5;         // Custom device after Cortex-A8 has 5 bits IR len
  JTAG_IRLen  = 4;         // We selected the Cortex-A8, it has 4 bits IRLen
  CPU         = CORTEX_A8; // We are connected to a Cortex-A8
  JTAG_AllowTAPReset = 1;         // We are allowed to enter JTAG TAP reset
  //
  // We have a non-CoreSight compliant Cortex-A8 here
  // which does not allow auto-detection of the Core debug components base address.
  // so set it manually to overwrite the DLL auto-detection
  //
  CORESIGHT_CoreBaseAddr = 0x80030000;
}

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.

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.

This example shows a special handling for NXP S32V234 (Cortex-A53, Cortex-M4, Cortex-M0+):

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.