SEGGER Flash Loader

From SEGGER Wiki
Revision as of 18:07, 27 February 2018 by Erik (talk | contribs) (→‎Extending an Existing Device)
Jump to: navigation, search

Open Flash Loader

Introduction

As the number of devices being available is steadily growing and sometimes in an early stage of the MCU development only a few samples/boards are available that may not be provided to third parties (e.g. SEGGER) to add support for a new device. Also the existence of the device may have confidential status, so it might not be mentioned as being supported in public releases yet. Therefore it might be desirable to be able to add support for new devices on your own, without depending on SEGGER and a new release of the J-Link Software & Documentation package being available.

The J-Link DLL allows customers to add support for new devices on their own. It is also possible to edit / extend existing device support by for example adding new flash banks (e.g. to add support for internal EEPROM programming or SPIFI programming). This article explains how new devices can be added to the DLL and how existing ones can be edited / extended.

General Procedure

By default, the J-Link DLL comes with a build-in device database that defines which device names are known and therefore officially supported by the J-Link DLL and software that uses the J-Link DLL. This list can also be viewed on our website: https://www.segger.com/downloads/supported-devices.php

Additionally, the build-in device database can be extended by specifying devices in an XML file, named JLinkDevices.xml. It is also possible to edit / extend an device from the built-in device database via this XML file. There are different places where the JLinkDevices.xml can be referenced from (see list below). In case of several JLinkDevices.xml files are used, supplement each other as in the order specified below:

  1. In the same directory as the J-Link DLL (JLinkARM.dll)
  2. In the same directory as the J-Link settings file. The location of the settings file depends on the IDE / software being used.
  3. In the directory specified using the J-Link Command String JLinkDevicsXMLPath = <Path>

Extend / Add Device Support

Extending an Existing Device

In order to edit/extend a device that is already in the built-in device database of the J-Link DLL, the following needs to be added to the JLinkDevices.xml: 

<Database>
  <Device>
    <ChipInfo Vendor="..." Name="..." />
    <FlashBankInfo Name="..." BaseAddr="..." MaxSize="..." Loader="..." LoaderType="..." AlwaysPresent="..." />
  </Device>
</Database>

The attribute Name of the tag <ChipInfo> must specify exactly the same name as the device in the built-in device database specifies. In case the value of the attribute BaseAddr specifies an address of an existing flash bank for the existing device, in the built-in device database, the flash bank from the built-in database is replaced by the one from the XML file.

When adding new flash banks or if the device in the built-in database does not specify any flash banks so far, the same attribute requirements as for adding a new device, apply. For more information, please refer to Adding a new device.

In order to add more than one flash bank, just repeat the <FlashBankInfo … />> tag structure from above, inside the same <Device> tag. For more information about the tags and their attributes, please refer to XML Tags and Attributes.

Adding a New Device

Create a Flash Loader

This article describes how to create a flash loader using the template projects (Cortex-M and Cortex-A/R) for SEGGER Embedded Studio.

Debug Configurations

The example project contains two debug configurations:

  • Debug
  • Release

Debug configuration

This configuration allows to debug the flash algorithm in Embedded Studio. The configuration includes a main.c containing the typical function call order, executed by the J-Link DLL during flash programming. The optimization level for this configuration is set to "none".

Release configuration

This configuration does not allow debugging but creates the output elf file which can be referenced from within the JLinkDevices.xml file as "Loader". The optimization level is set to 3 (highest).

Included files

Filename Content
FlashDev.c Flash device description for the ST STM32F205RC
FlashOS.h Function prototypes, definitions and structures
FlashPrg.c Flash algorithm itself (e.g. ProgramPage(), EraseSector()
main.c Flash algorithm debug code (used by debug configuration, only)
Cortex_M_Startup.s
ARM_Startup.s		 Cortex-M startup code (used by debug configuration, only)
Cortex-A/R startup code (used by debug configuration, only)
MemoryMap.xml Memory map of the ST STM32F205RC
Placement_debug.xml Debug configuration section placement file.
Placement_release.xml Release configuration section placement file.
thumb_crt0.s
crt0.s		 Initialization file for Cortex-M (used by debug configuration, only)
Initialization file for Cortex-A/R(used by debug configuration, only)

Embedded Studio Template Projects

The template projects below have been tested with SEGGER Embedded Studio V3.10.

Step-By-Step Instruction

This step-by-step instruction explains how to create your own flash loader using the template projects for Embedded Studio and how to use add a new flash bank for an existing or new device to the J-Link DLL, so that it can be used from within any application using the DLL.

  1. Adapt the template project
    1. FlashDev.c: Modify the FlashDevice structure according to your device
    2. FlashPrg.c: Implement the flash routines Init(), UnInit(), EraseSector() and ProgramPage()
    3. MemoryMap.xml: Enter RAM base address and RAM size
    4. main.c: Make sure that the define _FLASH_BASE_ADDR defines the correct flash base address
  2. Test the debug configuration
    1. Connect the target to the J-Link and the J-Link to the PC
    2. Switch to the Debug configuration in Embedded Studio (Build -> Set Active Build Configuration -> Debug)
    3. Build the project by pressing F7
    4. Start the debug session by pressing F5
    5. PC should be halted at main. Now debug the flash algorithm and make sure that it behaves as expected.
  3. Build the flash loader using the release configuration
    1. Switch to the Release configuration in Embedded Studio (Build -> Set Active Build Configuration -> Release)
    2. Build the project by pressing F7 --> The flash loader file can be found here: $PROJ_DIR$\Output\Release\Exe\*.elf
  4. JLinkDevices.xml
    1. Create or adapt the JLinkDevices.xml (described in the J-Link User Manual (UM08001)).
    2. Place the JLinkDevices.xml file at the correct location (described in the J-Link User Manual (UM08001)).

Now you can select and use the created or adapted device which uses the new flash bank in any J-Link DLL based application (e.g. J-Link Commander / IDE / ...).

Frequently Asked Questions

In which order does the J-Link DLL call the function during flash programming?

  1. Compare
    1. Init()
    2. Compare()
      Memory is accessed so it has to be initialized during Init() so that it can be memory mapped accessed here. If it is not initialized correctly, the read access may results in confusing the MCU.
    3. UnInit()
  2. Erase
    1. Init()
    2. Erase()
    3. UnInit()
  3. Program
    1. Init()
    2. Program()
    3. UnInit()

Troubleshoot

This section provides assistance in case of issues pops up when using custom added flash bank. The section assumes that the functionality has been verified using the debug configuration in Embedded Studio.

  1. Get the latest version of the template project
  2. Follow the Step-By-Step instructions expect of 2.1 FlashPrg.c --> Functions should not contain any code that accesses any SFRs
  3. Build the flash loader using the release configuration
  4. Perform a flash download using J-Link Commander. Flash download should report an error during verify
  5. Implement EraseSector() and retry the flash download test. J-Link Commander should still report verify failed but effected flash memory region should be empty. If not, check EraseSector().
  6. Implement ProgramPage() and retry the flash download test. Expected result: Test reports O.K. --> Programmed successfully. If not, check ProgramPage() code.

Frequently Problems

PC has unexpected value after flash download

This error may have different root causes:

  • Watchdog is enabled but not fed in the flash loader functions. This may result in a watchdog timeout pops up during RAMCode execution. The behavior is different but usually a reset will be triggered.
  • Accessing not enabled / clocked special function registers / peripherals
  • Accessing invalid memory regions (reserved)

(Q)SPI flashes

  • The Init() code has to make sure that the (Q)SPI pins as well as the (Q)SPI controller are configured so that the flash can be memory mapped (read) accessed. This is necessary as the J-Link DLL reads the data before programming to check if flash content does already match. This can be validated by setting the compare method in J-Link Commander to "skip" (exec SetCompareMode 0). Now start flash download. J-Link Commander should report a verify error but the flash should be memmory mapped accessible from now. If not, check the Init() code.
Retrieved from "https://wiki.segger.com/index.php?title=SEGGER_Flash_Loader&oldid=2297"