Difference between revisions of "J-Link script files"
(→JLINK_RISCV_DMI_ReadRegMultiple()) |
(→JLINK_RISCV_DMI_SetDMISettings()) |
||
Line 1,614: | Line 1,614: | ||
== JLINK_RISCV_DMI_SetDMISettings() == |
== 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 === |
=== Prototype === |
||
<source lang="c">int JLINK_RISCV_DMI_SetDMISettings(U32 NumAddrBits, U32 NumIdleClocks, U32 AccTimeout);</source> |
<source lang="c">int JLINK_RISCV_DMI_SetDMISettings(U32 NumAddrBits, U32 NumIdleClocks, U32 AccTimeout);</source> |
||
+ | |||
+ | === Return Value === |
||
+ | {| class="wikitable" |
||
+ | |- |
||
+ | ! Return value !! Description |
||
+ | |- |
||
+ | | >= 0 || O.K. |
||
+ | |- |
||
+ | | < 0 || Error |
||
+ | |- |
||
+ | | == -1 || Unspecified error |
||
+ | |- |
||
+ | |} |
||
+ | |||
+ | {{Note| |
||
+ | #DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG |
||
+ | #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() == |
== JLINK_RISCV_DMI_WriteReg() == |
Revision as of 18:12, 17 November 2022
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
- 1 Customizable actions
- 1.1 ConfigTargetSettings()
- 1.2 InitTarget()
- 1.3 SetupTarget()
- 1.4 ResetTarget()
- 1.5 InitEMU()
- 1.6 OnDisconnectTarget()
- 1.7 OnTraceStop()
- 1.8 OnTraceStart()
- 1.9 AfterResetTarget()
- 1.10 SWO_EnableTarget()
- 1.11 SWO_GetSWOBaseClock()
- 1.12 HandleBeforeFlashProg()
- 1.13 HandleAfterFlashProg()
- 1.14 HandleBeforeMemAccessWrite()
- 1.15 HandleAfterMemAccessWrite()
- 1.16 HandleBeforeMemAccessRead()
- 1.17 HandleAfterMemAccessRead()
- 1.18 StartETM()
- 1.19 StopETM()
- 1.20 StartETB()
- 1.21 StopETB()
- 1.22 StartTPIU()
- 1.23 StopTPIU()
- 1.24 StartTMC()
- 1.25 StopTMC()
- 1.26 StartTF()
- 1.27 StopTF()
- 1.28 StartPTM()
- 1.29 StopPTM()
- 2 Script file API functions
- 2.1 JLINK_C2_ReadAddr()
- 2.2 JLINK_C2_WriteAddr()
- 2.3 JLINK_C2_ReadData()
- 2.4 JLINK_C2_WriteData()
- 2.5 JLINK_CORESIGHT_AddAP()
- 2.6 JLINK_CORESIGHT_Configure()
- 2.7 JLINK_CORESIGHT_ReadAP()
- 2.8 JLINK_CORESIGHT_ReadDP()
- 2.9 JLINK_CORESIGHT_ReadDAP()
- 2.10 JLINK_CORESIGHT_WriteAP()
- 2.11 JLINK_CORESIGHT_WriteDP()
- 2.12 JLINK_CORESIGHT_WriteDAP()
- 2.13 JLINK_ExecCommand()
- 2.14 JLINK_GetTime()
- 2.15 JLINK_GetPinState()
- 2.16 JLINK_JTAG_GetDeviceId()
- 2.17 JLINK_JTAG_GetU32()
- 2.18 JLINK_JTAG_ReadWriteBits()
- 2.19 JLINK_JTAG_Reset()
- 2.20 JLINK_JTAG_SetDeviceId()
- 2.21 JLINK_JTAG_StartDR()
- 2.22 JLINK_JTAG_Store()
- 2.23 JLINK_JTAG_StoreClocks()
- 2.24 JLINK_JTAG_StoreDR()
- 2.25 JLINK_JTAG_StoreIR()
- 2.26 JLINK_JTAG_Write()
- 2.27 JLINK_JTAG_WriteClocks()
- 2.28 JLINK_JTAG_WriteDR()
- 2.29 JLINK_JTAG_WriteDRCont()
- 2.30 JLINK_JTAG_WriteDREnd()
- 2.31 JLINK_JTAG_WriteIR()
- 2.32 JLINK_PIN_Override()
- 2.33 JLINK_MemRegion()
- 2.34 JLINK_MEM_WriteU8()
- 2.35 JLINK_MEM_WriteU16()
- 2.36 JLINK_MEM_WriteU32()
- 2.37 JLINK_MEM_ReadU8()
- 2.38 JLINK_MEM_ReadU16()
- 2.39 JLINK_MEM_ReadU32()
- 2.40 JLINK_MEM_Preserve()
- 2.41 JLINK_MEM_Restore()
- 2.42 JLINK_MEM_Fill()
- 2.43 JLINK_RISCV_DMI_AutodetectDMISettings()
- 2.44 JLINK_RISCV_DMI_ClearState()
- 2.45 JLINK_RISCV_DMI_ReadReg()
- 2.46 JLINK_RISCV_DMI_ReadRegMultiple()
- 2.47 JLINK_RISCV_DMI_SetDMISettings()
- 2.48 JLINK_RISCV_DMI_WriteReg()
- 2.49 JLINK_RISCV_DMI_WriteRegMultiple()
- 2.50 JLINK_SelectTIF()
- 2.51 JLINK_SetDevice()
- 2.52 JLINK_SWD_ReadWriteBits()
- 2.53 JLINK_SYS_MessageBox()
- 2.54 JLINK_SYS_MessageBox1()
- 2.55 JLINK_SYS_Report()
- 2.56 JLINK_SYS_Report1()
- 2.57 JLINK_SYS_Sleep()
- 2.58 JLINK_SYS_UnsecureDialog()
- 2.59 JLINK_TARGET_IsHalted()
- 2.60 JLINK_TARGET_Halt()
- 2.61 JLINK_TIF_ActivateTargetReset()
- 2.62 JLINK_TIF_ReleaseTargetReset()
- 2.63 JLINK_TIF_SetClrTCK()
- 2.64 JLINK_TIF_SetClrTMS()
- 2.65 JLINK_TIF_SetClrTDI()
- 2.66 JLINK_TIF_SetSpeed()
- 3 Global DLL variables
- 4 Global DLL constants
- 5 Script file language
- 6 Using J-Link script files
- 7 J-Link script file examples
- 7.1 JTAG initialization
- 7.2 Exclude illegal memory regions
- 7.3 Connect to a specific core of a multi-core device
- 7.4 Override J-Link pins
- 7.5 Adding missing ROM table entries
- 7.6 Init ECC work RAM
- 7.7 Reset sequences
- 7.8 Sending data via SWD manually
- 7.9 Overriding device specific connect
- 7.10 Halt after reset
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); |
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()
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
Prototype
int InitEMU(void);
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 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) |
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()
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 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 |
- DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
- 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);
Return Value
Return value | Description |
---|---|
>= 0 | O.K. |
< 0 | Error |
== -1 | Unspecified error |
- DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
- 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.
- 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);
Return Value
Return value | Description |
---|---|
>= 0 | O.K. |
< 0 | Error |
== -1 | Unspecified error |
== -2 | Timeout (DMI operation never finished) |
== -3 | DMI reported exception / abort |
- DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
- 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);
Return Value
Return value | Description |
---|---|
>= 0 | O.K. |
< 0 | Error |
== -1 | Unspecified error |
== -2 | Timeout (DMI operation never finished) |
== -3 | DMI reported exception / abort |
- DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
- 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);
Return Value
Return value | Description |
---|---|
>= 0 | O.K. |
< 0 | Error |
== -1 | Unspecified error |
- DMI accesses are only available for JTAG-like target interfaces like: JTAG, cJTAG
- 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()
Prototype
int JLINK_RISCV_DMI_WriteReg(U32 RegAddr, U32 Data);
JLINK_RISCV_DMI_WriteRegMultiple()
Prototype
int JLINK_RISCV_DMI_WriteRegMultiple(U32 RegAddr, const U32* paData, U32 NumItems);
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 |
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: |
--- | 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
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.
- Open project
- Navigate to Options -> Project settings... -> MCU
- Tick "Use J-Link script file"
- 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:
- Start the SystemView application
- Open up the Recorder Configuration
- Navigate to Target -> Recorder Configuration in the menu bar
- Select "J-Link" as recorder
- Switch to the advanced settings of the configuration dialog and select the desired J-Link script file to be used.
IAR EWARM
Please refer to: IAR EWARM#Using J-Link script files
Keil MDK
Please refer to: Keil MDK#Using J-Link Script Files
Eclipse
Please refer to: Eclipse#Using J-Link script files
Generic
- 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 settings file is present (used by IDE), but no script file is specified inside of the settings file:
- "<NameOfSettingsFile>.JLinkScript" is loaded if present in the same directory as the settings file.
- A J-Link Script file can be set inside the J-Link settings file
- Open the J-Link settings file in a text editor
- Go to section [CPU]. If not present, add it.
- 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.
- Dynamic JTAG chain device selection: Template_JTAGAutoDetection.JLinkScript
- Static JTAG chain device selection: Template_JTAGSpecificConnect.JLinkScript
Exclude illegal memory regions
This example shows how to exclude an illegal memory region using the map region J-Link Command String. The J-Link DLL will ignore all read / write accesses to the specified region(s). This can be used if an IDE for example accesses an illegal memory address for some reason.
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 data via SWD manually
J-Link Script files allow to transfer raw data via SWD 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.