J-Link script files

From SEGGER Knowledge Base
Revision as of 14:09, 11 July 2024 by Nino (talk | contribs)
Jump to navigation Jump to search

Customizable actions

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

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


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

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

ConfigTargetSettings()

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

Prototype

int ConfigTargetSettings(void);

Notes and Limitations

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

  • Should only set some global DLL variables

InitTarget()

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

Prototype

int InitTarget(void);

Notes and Limitations

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

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

SetupTarget()

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

Prototype

int SetupTarget(void);

Notes and Limitations

Does not replace any DLL functionality but extends it.

  • May use MEM_ API functions

ResetTarget()

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

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

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

Prototype

int ResetTarget(void);

Notes and Limitations

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

InitEMU()

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

Allowed J-Link Command Strings

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.

StartNTRACETE()

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

Prototype

int StartNTRACETE(void);

Notes and Limitations

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

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

StopNTRACETE()

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

Prototype

int StopNTRACETE(void);

Notes and Limitations

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

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

StartNTRACETF()

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

Prototype

int StartNTRACETF(void);

Notes and Limitations

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

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

StopNTRACETF()

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

Prototype

int StopNTRACETF(void);

Notes and Limitations

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

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

StartNTRACEPIB()

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

Prototype

int StartNTRACEPIB(void);

Notes and Limitations

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

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

StopNTRACEPIB()

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

Prototype

int StopNTRACEPIB(void);

Notes and Limitations

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

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

StartNTRACESRAM()

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

Prototype

int StartNTRACESRAM(void);

Notes and Limitations

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

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

StopNTRACESRAM()

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

Prototype

int StopNTRACESRAM(void);

Notes and Limitations

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

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

StartNTRACEATB()

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

Prototype

int StartNTRACEATB(void);

Notes and Limitations

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

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

StopNTRACEATB()

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

Prototype

int StopNTRACEATB(void);

Notes and Limitations

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

  • May use high-level API functions like JLINK_MEM_ etc.
  • Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function.
Retrieved from "https://kb.segger.com/index.php?title=J-Link_script_files&oldid=20511"