J-Link script files

From SEGGER Wiki
Jump to: navigation, search

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.

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


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

Prototype

int InitEMU(void);

Notes and Limitations

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.

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

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

TBD

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

Return Value

TBD

Example

TBD

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

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

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.

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

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

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

  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.

JTAG initialization

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

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+):
The special handling includes setting the core base address as well as the CTI base address.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.