SEGGER Flash Loader
Contents
- 1 Open Flashloader
- 1.1 Introduction
- 1.2 Supported CPU architectures
- 1.3 General Procedure
- 1.4 Extending an Existing Device
- 1.5 Adding a New Device
- 1.6 Adding a New Flash Bank
- 1.7 JLinkDevices folder
- 1.8 JLinkDevices.xml Tags and Attributes
- 1.9 Example JLinkDevices.xml file
- 1.10 Add. Information / Considerations / Limitations
- 2 Create a Flash Loader
- 2.1 Build Configurations
- 2.2 Included files
- 2.3 ARM Cortex-A and Cortex-R template projects
- 2.4 ARM Cortex-M template projects
- 2.5 ARM7/9 template projects
- 2.6 RISC-V template projects
- 2.7 Reference algorithms
- 2.8 Step-By-Step Instruction
- 2.9 FAQ
- 2.10 Troubleshoot
- 2.11 Frequently Problems
- 2.12 Example projects
- 3 Algorithm Functions
- 4 Function Overview
- 5 FlashDevice struct
- 6 Using a Precompiled Flashloader
Open Flashloader
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 and Documentation Pack 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.
Supported CPU architectures
The open flash loader is available for the following architectures:
- ARMv4 (ARM7)
- ARMv5 (ARM9)
- ARMv6-M (Cortex-M0, Cortex-M1, ...)
- ARMv7-M (Cortex-M3, Cortex-M4, ...)
- ARMv8-M (Cortex-M23, Cortex-M33, ...)
- ARMv7-A (Cortex-A8, Cortex-A9, ...)
- ARMv7-R (Cortex-R4, Cortex-R5, ...)
- RISC-V RV32
Architectures not listed here must be assumed as being not supported.
While they may work by chance, no support is provided for problems in regards to getting open flash loaders running on non-listed architectures.
In case of doubt, please feel free to contact SEGGER.
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 a XML file. It is also possible to edit / extend an device from the built-in device database via this XML file. There is a standard location where the J-Link DLL will look for *.xml files.
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, a *.xml with the following content has to be created or extended in the JLinkDevices folder:
<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
In order to add support for a new device to the J-Link DLL, the following needs to be added to a *.xml file in the JLinkDevices folder:
<Database> <Device> <ChipInfo Vendor="..." Name="..." WorkRAMAddr="..." WorkRAMSize="..." Core="..." /> <FlashBankInfo Name="..." BaseAddr="..." MaxSize="..." Loader="..." LoaderType="..." AlwaysPresent="..." /> </Device> </Database>
When adding a new device, the following attributes for the <ChipInfo> tag are mandatory:
- Vendor
- Name
- Core
In case a <FlashBankInfo> tag is also added, the following attributes in addition to the ones mentioned before, become mandatory: ChipInfo-Tag
- WorkRAMAddr
- WorkRAMSize
- FlashBankInfo
FlashBankInfo-Tag
- Name
- BaseAddr
- MaxSize
- Loader
- LoaderType
- AlwaysPresent
For more information about the tags and their attributes, please refer to XML Tags and Attributes . In order to add more than one device to the device database, just repeat the <Device> … </Device> tag structure from above for each device or create a separate *.xml file in the JLinkDevices folder.
Adding a New Flash Bank
In general, there are two possibilities to add a new flash bank for a new or existing device:
- Use a pre-compiled flash loader
- Compile / create the flash loader on your own
- Using Keil uVision (a license is required, no trial available; Supports Cortex-M, only)
- SEGGER Embedded Studio (can be evaluated without license; Supports Cortex-M, Cortex-A/R and RISC-V)
How to create a flash loader on your own using Embedded Studio is described below.
Note: The Open Flashloader concept replaces the previous RAMCode SDK.
JLinkDevices folder
Customers and silicon vendors may add support for their own devices or extend support for already existing devices by passing a *.xml file to the J-Link DLL. Those *.xml files need to be located in the central SEGGER/JLinkDevices folder. If the folder does not exist, it may be created.
Location
- Windows: C:\Users\<USER>\AppData\Roaming\SEGGER\JLinkDevices
- Linux: $HOME/.config/SEGGER/JLinkDevices
- macOS: $HOME/Library/Application Support/SEGGER/JLinkDevices
Usage
The J-Link DLL will recursively look through the JLinkDevices folder for any *.xml files and evaluate them as JLinkDevices.xml files. Customers may freely structure the folder into subfolders with a maximum depth of four.
This feature has been introduced with V7.62.
JLinkDevices.xml Tags and Attributes
XML Tags and Attributes In the following, the valid XML tags and their possible attributes are explained. General rules • Attributes may only occur inside an opening tag • Attribute values must be enclosed by quotation marks Tag Description
Tag | Description |
---|---|
<Database> | Opens the XML file top-level tag. |
<Device> | Opens the description for a new device. |
<ChipInfo> | Specifies basic information about the device to be added, like the core it incorporates etc. |
<FlashBankInfo> | Specifies a flash bank for the device. |
<Database>
Opens the XML file top-level tag. Only present once per XML file. Valid attributes This tag has no attributes Notes
- Must only occur once per XML file
- Must be closed via </Database>
<Device>
Opens the description for a new device. Valid attributes
Parameter | Meaning |
---|---|
InheritFrom | String that specifies the name of a parent device which the DLL already knows. The new child device will inherit all properties from the parent to use as a base. If the child inherits from a parent that was defined through *.XML, the parent and child must be defined in the same *.XML file and the parent must be defined before the child. Other configurations may lead to unspecified behavior. This attribute is optional. E.g. InheritFrom=“STM32F767NI”. |
Notes
- Must be closed via </Device> .
- May occur multiple times in an XML file
<ChipInfo>
Specifies basic information about the device to be added, like the core it incorporates etc. Valid attributes
Parameter | Meaning |
---|---|
Vendor | String that specifies the name of the vendor of the device. This attribute is mandatory. E.g. Vendor=“ST”. |
Name | Name of the device. This attribute is mandatory. E.g. Name=“STM32F407IE” |
WorkRAMAddr | Hexadecimal value that specifies the address of a RAM area that can be used by J-Link during flash programming etc. Should not be used by any DMAs on the device. Cannot exist without also specifying WorkRAMSize. If no flash banks are added for the new device, this attribute is optional. E.g. WorkRAMAddr=“ 0x20000000 ” |
WorkRAMSize | Hexadecimal value that specifies the size of the RAM area that can be used by J-Link during flash programming etc. Cannot exist without also specifying WorkRAMAddr. If no flash banks are added for the new device, this attribute is optional. E.g. WorkRAMSize=“ 0x10000 ” |
Core | Specifies the core that the device incorporates. If a new device added, this attribute is mandatory. E.g. Core=“ JLINK_CORE_CORTEX_M0 ”For a list of valid attribute values, please refer to Attribute values - Core. |
JLinkScriptFile | String that specifies the path to a J-Link script file if required for the device. Path can be relative or absolute. If path is
relative, it is relative to the location of the JLinkDevices.xml file. This attribute is optional. E.g. JLinkScriptFile=“ST/Example.jlinkscript” |
Notes
- No separate closing tag.
Directly closed after attributes have been specified: <ChipInfo … />
- Must not occur outside a <Device> tag.
Attribute values - Core
For a list of all available values for the Core attribute, please expand the following list:
JLINK_CORE_CORTEX_M1 |
JLINK_CORE_CORTEX_M3 |
JLINK_CORE_CORTEX_M3_R1P0 |
JLINK_CORE_CORTEX_M3_R1P1 |
JLINK_CORE_CORTEX_M3_R2P0 |
JLINK_CORE_CORTEX_M3_R2P1 |
JLINK_CORE_CORTEX_M0 |
JLINK_CORE_CORTEX_M_V8BASEL |
JLINK_CORE_ARM7 |
JLINK_CORE_ARM7TDMI |
JLINK_CORE_ARM7TDMI_R3 |
JLINK_CORE_ARM7TDMI_R4 |
JLINK_CORE_ARM7TDMI_S |
JLINK_CORE_ARM7TDMI_S_R3 |
JLINK_CORE_ARM7TDMI_S_R4 |
JLINK_CORE_CORTEX_A8 |
JLINK_CORE_CORTEX_A7 |
JLINK_CORE_CORTEX_A9 |
JLINK_CORE_CORTEX_A12 |
JLINK_CORE_CORTEX_A15 |
JLINK_CORE_CORTEX_A17 |
JLINK_CORE_ARM9 |
JLINK_CORE_ARM9TDMI_S |
JLINK_CORE_ARM920T |
JLINK_CORE_ARM922T |
JLINK_CORE_ARM926EJ_S |
JLINK_CORE_ARM946E_S |
JLINK_CORE_ARM966E_S |
JLINK_CORE_ARM968E_S |
JLINK_CORE_ARM11 |
JLINK_CORE_ARM1136 |
JLINK_CORE_ARM1136J |
JLINK_CORE_ARM1136J_S |
JLINK_CORE_ARM1136JF |
JLINK_CORE_ARM1136JF_S |
JLINK_CORE_ARM1156 |
JLINK_CORE_ARM1176 |
JLINK_CORE_ARM1176J |
JLINK_CORE_ARM1176J_S |
JLINK_CORE_ARM1176JF |
JLINK_CORE_ARM1176JF_S |
JLINK_CORE_CORTEX_R4 |
JLINK_CORE_CORTEX_R5 |
JLINK_CORE_RX |
JLINK_CORE_RX62N |
JLINK_CORE_RX62T |
JLINK_CORE_RX63N |
JLINK_CORE_RX630 |
JLINK_CORE_RX63T |
JLINK_CORE_RX621 |
JLINK_CORE_RX62G |
JLINK_CORE_RX631 |
JLINK_CORE_RX65N |
JLINK_CORE_RX21A |
JLINK_CORE_RX220 |
JLINK_CORE_RX230 |
JLINK_CORE_RX231 |
JLINK_CORE_RX23T |
JLINK_CORE_RX24T |
JLINK_CORE_RX110 |
JLINK_CORE_RX113 |
JLINK_CORE_RX130 |
JLINK_CORE_RX71M |
JLINK_CORE_CORTEX_M4 |
JLINK_CORE_CORTEX_M7 |
JLINK_CORE_CORTEX_M_V8MAINL |
JLINK_CORE_CORTEX_A5 |
JLINK_CORE_POWER_PC |
JLINK_CORE_POWER_PC_N1 |
JLINK_CORE_POWER_PC_N2 |
JLINK_CORE_MIPS |
JLINK_CORE_MIPS_M4K |
JLINK_CORE_MIPS_MICROAPTIV |
JLINK_CORE_EFM8_UNSPEC |
JLINK_CORE_CIP51 |
<FlashBankInfo>
Specifies a flash bank for the device. This allows to use the J-Link flash download functionality with IDEs, debuggers and other software that uses the J-Link DLL (e.g. J-Link Commander) for this device. The flash bank can then be programmed via the normal flash download functionality of the J-Link DLL. For more information about flash download, please refer to Flash download . For possible limitations etc. regarding newly added flash banks, please refer to Add. Info / Considerations / Limitations . Valid attributes
Parameter | Meaning |
---|---|
Name | String that specifies the name of the flash bank. Only used for visualization. Can be freely chosen. This attribute is mandatory. E.g. Name=“SPIFI flash” |
BaseAddr | Hexadecimal value that specifies the start address of the flash bank. The J-Link DLL uses this attribute together with MaxSize to determine which memory write accesses performed by the debugger, shall be redirected to the flash loader instead of being written directly to the target as normal memory access. This attribute is mandatory. E.g. BaseAddr=“ 0x08000000 ” |
MaxSize | Hexadecimal value that specifies the max. size of the flash bank in bytes. For many flash loader types the real bank size may depend on the actual flash being connected (e.g. SPIFI flash where the loader can handle different SPIFI flashes so size may differ from hardware to hardware). Also, for some flash loaders the sectorization is extracted from the flash loader at runtime. The real size of the flash bank may be smaller than MaxSize but must never be bigger. The J-Link DLL uses this attribute together with BaseAddr to determine which memory write accesses performed by the debugger, shall be redirected to the flash loader instead of being written directly to the target as normal memory access. This attribute is mandatory. E.g. MaxSize=“ 0x80000 ” |
Loader | String that specifies path to the ELF file that holds the flash loader. Path can be relative or absolute. If path is relative, it
is relative to the location of the JLinkDevices.xml file. This attribute is mandatory. E.g. Loader=“ST/MyFlashLoader.elf” For CMSIS flash loaders the file extension is usually FLM, however any extension is accepted by the J-Link DLL. |
LoaderType | Specifies the type of the loader specified by Loader. This attribute is mandatory. E.g. LoaderType=“ FLASH_ALGO_TYPE_OPEN ” For a list of valid attribute values, please refer to Attribute values LoaderType. |
AlwaysPresent | Specifies if a flash bank is always present (e.g. internal flash). If this element is set to one, this flash bank will be affected by the “erase” command. This attribute is optional. E.g. AlwaysPresent=“1”. |
Notes
- No separate closing tag. Directly closed after attributes have been specified:
<FlashBankInfo … />
- Must not occur outside a <Device> tag
Attribute values - LoaderType
The following values are valid for the LoaderType attribute:
- FLASH_ALGO_TYPE_OPEN
Describes that the used algorithm is an Open Flashloader algorithm. CMSIS based algorithms are also supported via the Open Flashloader concept. For additional information, see Add. Info / Considerations / Limitations .
Example JLinkDevices.xml file
Add. Information / Considerations / Limitations
Create a Flash Loader
This article describes how to add support for new devices / flash banks to the J-Link DLL so that they can be used with any J-Link DLL based application like for example J-Flash, J-Link Commander, IDEs, etc...The description is based on the template projects (Cortex-M, Cortex-A/R, ARM7/9 and RISC-V) for SEGGER Embedded Studio. This article assumes that there is already a basic understanding of the method of adding new devices using the Open Flashloader concept. If this is not the case, we recommend to read the article above. In general, there are two possibilities to add support for a new device:
- Use a pre-compiled flash loader
- Compile / create the flash loader on your own
- Using Keil uVision (a license is required, no trial available; Supports Cortex-M, only)
- SEGGER Embedded Studio (Supports Cortex-M, Cortex-A/R and RISC-V)
Basically, any usage of ES in a commercial scope requires a valid license.
However, the Open Flashloader is an exception. The evaluation license can be used to debug & create a flashloader; a valid license is not required.
How to create a flash loader on your own using Embedded Studio is described below.
Supported cores:
- Cortex-M
- Cortex-A/R
- ARM7/9
- RISC-V
Note: The Open Flashloader concept replaces the previous RAMCode SDK.
Build Configurations
The example project contains two build configurations:
- Debug: 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.
- Release: Creates elf file which can be referenced from within the JLinkDevices.xml file as "Loader".
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) |
ARM Cortex-A and Cortex-R template projects
The template projects below have been tested with SEGGER Embedded Studio for ARM V5.34.
ARM Cortex-M template projects
The template projects below have been tested with SEGGER Embedded Studio for ARM V5.34.
ARM7/9 template projects
The template projects below have been tested with SEGGER Embedded Studio for ARM V5.34.
RISC-V template projects
The template projects below have been tested with SEGGER Embedded Studio for RISC-V V5.34.
Note: The template project is configured for "Enable Linker Relaxation = no". Linker relaxation is not supported for open flash loaders.
Reference algorithms
Step-By-Step Instruction
This step-by-step instruction explains how to create your own flash loader using the template projects for Embedded Studio.
- Adapt the template project
- FlashDev.c: Modify the FlashDevice structure according to your device
- FlashPrg.c: Implement the flash routines Init(), UnInit(), EraseSector() and ProgramPage()
- MemoryMap.xml: Enter RAM base address and RAM size
- Placement_debug.xml: Enter RAM address in the program section element.
- main.c: Make sure that the define _FLASH_BASE_ADDR defines the correct flash base address
- Test the debug configuration
- Connect the target to the J-Link and the J-Link to the PC
- Switch to the Debug configuration in Embedded Studio (Build -> Set Active Build Configuration -> Debug)
- Build the project by pressing F7
- Start the debug session by pressing F5
- PC should be halted at main. Now debug the flash algorithm and make sure that it behaves as expected.
- Build the flash loader using the release configuration
- Switch to the Release configuration in Embedded Studio (Build -> Set Active Build Configuration -> Release)
- Build the project by pressing F7 --> The flash loader file can be found here: $PROJ_DIR$\Output\Release\Exe\*.elf
- JLinkDevices.xml
- Create or adapt the JLinkDevices.xml (described in the J-Link User Manual (UM08001)).
- 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 / ...).
FAQ
- Q: Do I need a valid Embedded Studio license when using the Open Flashloader in a commercial scope?
A: Basically, any usage of ES in a commercial scope requires a valid license. However, the Open Flashloader is an exception. The evaluation license suffice; a valid license is not required.
TBD
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.
- Get the latest version of the template project
- Follow the Step-By-Step instructions except of 1.2 FlashPrg.c --> Functions should not contain any code that accesses any SFRs
- Build the flash loader using the release configuration
- Perform a flash download using J-Link Commander. Flash download should report an error during verify
- 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().
- 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.
I get build errors in Release build config
If you get build errors when switching from Debug to Release build in the template project the main cause is that third party libraries are used. The Open Flashloader interface expects all program parts to be linked to sections PrgCode and PrgData. Third party libraries often use statically linked program parts which will not be put in the aforementioned sections which will cause a build or linker error. Generally we recommend not using any third party libraries when creating Flash loaders as they will increase the Flash loader size drastically while usually slowing down the maximum possible Flash loader speed. If you happen to have to use an external library in your project it is user responsibility to make sure this external library is linked to the aforementioned sections for all application parts.
Example projects
The projects below are based on the template projects (see links above). They can be used as reference when creating your own flashloader using the Open Flashloader.
Algorithm Functions
The following tables provide an overview of all available functions. The tables are split into mandatory and optional functions.
Following functions are mandatory. Note: The functions EraseSector and ProgramPage have been extended by new functions optimized for speed. Either of these func
Function Name | Description |
---|---|
Init | Handles the initialization of the flash module. |
UnInit | Handles the de-initialization of the flash module. |
SEGGER_OPEN_Erase |
Erases one or more flash sector(s). Alternatively, the deprecated function EraseSector can be used which does support single sector erase, only. |
SEGGER_OPEN_Program | Programs one or multiple flash page(s). Alternatively, the deprecated function ProgramPage can be used which does support single page program, only. We highly recommend to use the SEGGER_OPEN_Program() because a much higher throughput can be achieved compared to the legacy one. |
Note: In order to stay backward compatible, the DLL accepts both program / erase functions. In this case, the SEGGER_OPEN_XXX variant will be used. In general, users have to make sure that at least one program / erase function is implemented in the flashloader.
Following functions are optional:
Function Name | Description |
---|---|
BlankCheck | Checks if a memory region is blank |
EraseChip | Erases the entire chip (flash bank) |
Verify | Compares a specified number of bytes of a provided data buffer with the content of the device |
SEGGER_OPEN_Read | Reads the target memory (e.g. can be used to read data from non-memory mapped flashes) |
Flash Erase Procedure
This procedure is executed to erase the flash before programming it.
Flash Program Procedure
This procedure is executed to program the flash. The DLL makes sure that the effected sectors are erased.
Flash Verify Procedure
This procedure verifies that the programmed data have been programmed successfully.
TBD
Flash Read Procedure
This procedure reads back the flash content. Please note that this sequence is executed in case of SEGGER_OPEN_Read() has been implemented. If this function is not available, the read back is done using memory mapped read accesses to the specified address.
TBD
Function Overview
Init
Prototype
1 int Init(U32 Addr, U32 Freq, U32 Func);
Function description
Handles the initialization of the flash module. This function will be called prior any flash action (read, program, erase, etc...).
Parameters
- Addr: Specifies the base address of the flash.
- Freq: Specifies the CPU clock frequency.
- Func: Specifies the action followed by Init() (e.g.: 1 - Erase, 2 - Program, 3 - Verify / Read)
Return values
- 0: O.K.
- 1: Error
Code Example
1 int Init(U32 Addr, U32 Freq, U32 Func) {
2 (void)Addr;
3 (void)Freq;
4 (void)Func;
5 //
6 // Init code
7 //
8 FLASH->ACR = 7; // Disable all caches and set wait-states to 7
9 do {
10 v = FLASH->ACR;
11 if ((v & 0x00001F07) == 7) { // Wait until write has completely succeeded
12 break;
13 }
14 } while (1);
15 FLASH->ACR = (1 << 11) | (1 << 12) | 7; // Reset data and instruction cache
16 FLASH->ACR = 7; // Invalidate reset of data and instruction cache
17 return 0;
18 }
UnInit
Prototype
1 int UnInit(U32 Func);
Function description
Handles the de-initialization of the flash module.
Parameters
- Func: Specifies the previous flash action before the call of UniInit() (e.g.: 1 - Erase, 2 - Program, 3 - Verify / Read)
Return values
- 0: O.K.
- 1: Error
Code Example
1 int UnInit(U32 Func) {
2 (void)Func;
3 //
4 // Uninit code
5 //
6 return 0;
7 }
SEGGER_OPEN_Erase
Prototype
1 int SEGGER_OPEN_Erase(U32 SectorAddr, U32 SectorIndex, U32 NumSectors)
Function description
Erases one or more flash sector(s).
Parameters
- SectorAddr: Address of the start sector to be erased
- SectorIndex: Index of the start sector to be erased
- NumSectors: Number of sectors to be erased
Return values
- 0: O.K.
- 1: Error
Code Example
1 int SEGGER_OPEN_Erase(U32 SectorAddr, U32 SectorIndex, U32 NumSectors) {
2 do {
3 //
4 // Erase sector code
5 //
6 _FeedWatchdog();
7 SectorAddr += SECTOR_SIZE;
8 SectorIndex++;
9 } while (--NumSectors);
10 return 0;
11 }
EraseSector
Prototype
1 int EraseSector(U32 SectorAddr)
Function description
Erases one flash sector.
Parameters
- Addr: Address of the sector to be erased
Return values
- 0: O.K.
- 1: Error
Code Example
1 int EraseSector(U32 SectorAddr) {
2 //
3 // Erase sector code
4 //
5 _FeedWatchdog();
6 return 0;
7 }
SEGGER_OPEN_Program
Prototype
1 int SEGGER_OPEN_Program(U32 DestAddr, U32 NumBytes, U8 *pSrcBuff)
Function description
Programs one or more flash pages.
Parameters
- DestAddr: Destination address
- NumBytes: Number of bytes to be programmed (always a multiple of program page size, defined in FlashDev.c)
- pSrcBuff: Point to the source buffer
Return values
- 0: O.K.
- 1: Error
Code Example
1 int SEGGER_OPEN_Program(U32 DestAddr, U32 NumBytes, U8 *pSrcBuff) {
2 volatile U8 * pSrc;
3 volatile U8 * pDest;
4 U8 AccessWidth;
5 U32 Status;
6 U32 NumPages;
7 U32 NumBytesAtOnce;
8 int r;
9
10 r = -1;
11 pSrc = (volatile U8*)pSrcBuff;
12 pDest = (volatile U8*)DestAddr;
13 //
14 // RAMCode is able to program multiple pages
15 //
16 NumPages = NumBytes >> PAGE_SIZE_SHIFT;
17 //
18 // Program page-wise
19 //
20 if (NumPages) {
21 r = 0;
22 do {
23 NumBytesAtOnce = (1 << PAGE_SIZE_SHIFT);
24 _FeedWatchdog();
25 //
26 // Program one page
27 //
28 do {
29 //
30 // Program page code
31 //
32 *pDest++ = *pSrc++;
33 } while(--NumBytesAtOnce);
34 } while (--NumPages);
35 }
36 return r;
37 }
ProgramPage
Prototype
1 int ProgramPage(U32 DestAddr, U32 NumBytes, U8 *pSrcBuff)
Function description
Programs one flash page.
Parameters
- DestAddr: Destination address
- NumBytes: Number of bytes to be programmed (Program page size, defined in FlashDev.c; The J-Link DLL is not allowed to pass multiple pages at once. We recommend to use SEGGER_OPEN_Program() instead.)
- pSrcBuff: Point to the source buffer
Return values
- 0: O.K.
- 1: Error
Code Example
1 int ProgramPage(U32 DestAddr, U32 NumBytes, U8 *pSrcBuff) {
2 volatile U8 * pSrc;
3 volatile U8 * pDest;
4 U8 AccessWidth;
5 U32 Status;
6 U32 NumBytesAtOnce;
7 int r;
8
9 r = -1;
10 pSrc = (volatile U8*)pSrcBuff;
11 pDest = (volatile U8*)DestAddr;
12 //
13 // Program page-wise
14 //
15 r = 0;
16 do {
17 NumBytesAtOnce = (1 << PAGE_SIZE_SHIFT);
18 _FeedWatchdog();
19 //
20 // Program one page
21 //
22 do {
23 //
24 // Program page code
25 //
26 *pDest++ = *pSrc++;
27 } while(--NumBytesAtOnce);
28 } while (--NumPages);
29 return r;
30 }
BlankCheck
Prototype
1 int BlankCheck(U32 Addr, U32 NumBytes, U8 BlankData)
Function description
Checks if a memory region is blank
Parameters
- Addr: Blank check start address
- NumBytes: Number of bytes to be checked
- BlankData: Pointer to the destination data
Return values
- 0: O.K., blank
- 1: O.K., *not* blank
- < 0: Error
Code Example
1 int BlankCheck(U32 Addr, U32 NumBytes, U8 BlankData) {
2 U8* pData;
3
4 pData = (U8 *)Addr;
5 do {
6 if (*pData++ != BlankData) {
7 return 1;
8 }
9 } while (--NumBytes);
10 return 0;
11 }
EraseChip
Prototype
1 int EraseChip(void)
Function description
Erases the entire flash
Return values
- 0: O.K.
- 1: Error
Code Example
1 int EraseChip(void) {
2 //
3 // Erase chip code
4 //
5 *(volatile U32*)(0x000000) = SectorAddr; // Dummy code, needs to be replaced with erase chip code
6 _FeedWatchdog();
7 return 0;
8 }
Verify
Prototype
1 U32 Verify(U32 Addr, U32 NumBytes, U8 *pBuff)
Function description
Compares a specified number of bytes of a provided data buffer with the content of the device
Parameters
- Addr: Start address in memory which should be compared
- NumBytes: Number of bytes to be compared
- pBuff: Pointer to the data to be compared
Return values
- == (Addr + NumBytes): O.K.
- != (Addr + NumBytes): *not* O.K. (ideally the fail address is returned)
Code Example
1 U32 Verify(U32 Addr, U32 NumBytes, U8 *pBuff) {
2 unsigned char *pFlash;
3 unsigned long r;
4
5 pFlash = (unsigned char *)Addr;
6 r = Addr + NumBytes;
7 do {
8 if (*pFlash != *pBuff) {
9 r = (unsigned long)pFlash;
10 break;
11 }
12 pFlash++;
13 pBuff++;
14 } while (--NumBytes);
15 return r;
16 }
SEGGER_OPEN_Read
Prototype
1 int SEGGER_OPEN_Read(U32 Addr, U32 NumBytes, U8 *pDestBuff)
Function description
Reads a specified number of bytes into the provided buffer
Parameters
- Addr: Start read address
- NumBytes: Number of bytes to be read
- pBuff: Pointer to the destination data
Return values
- >= 0: O.K., NumBytes read
- < 0: Error
Code Example
1 int SEGGER_OPEN_Read(U32 Addr, U32 NumBytes, U8 *pDestBuff) {
2 //
3 // Read function
4 // Add your code here...
5 //
6 return NumBytes;
7 }
FlashDevice struct
The FlashDevice structure variable contains all the static information about the flash algorithm like sectorization of the flash, programming chunk size, ... In the following, the structure elements are explained in detail to give a good idea about what needs to be filled in for a new flash loader.
struct FlashDevice { U16 AlgoVer; U8 Name[128]; U16 Type; U32 BaseAddr; U32 TotalSize; U32 PageSize; U32 Reserved; U8 ErasedVal; U32 TimeoutProg; U32 TimeoutErase; struct SECTOR_INFO SectorInfo[MAX_NUM_SECTORS]; };
AlgoVer
Set to <ALGO_VERSION>. Do not set to anything else!
Name
Name of the flash bank this flash loader handles. (E.g. "internal flash", "QSPI", ...). Must not exceed 127 characters (last character reserved for string termination)
Type
Currently ignored. Set to <ONCHIP> to get max. compatibility.
BaseAddr
This element describes the base address of the flash. It is recommended to always use the real address of the flash here, even if the flash is also available at other addresses, depending on the current settings of the device.
TotalSize
This describes the total size of the flash that is achieved when summing up all sector info from <SectorInfo>. If the flash is 512 KiB in size, <TotalSize> must be 0x80000 (524,288 => 512 KiB)
PageSize
This field describes in what chunks J-Link feeds the flash loader. The SEGGER_OPEN_Program() function will be called with a data chunk of multiple of <PageSize> bytes. For example if the flash requires to be programmed in multiple of 128 bytes, <PageSize> should be set to 128. If the flash can be programmed 4 byte wise, <PageSize> should be set to 4.
Reserved
Set this element to 0
ErasedVal
Most flashes have an erased value of 0xFF (set this element to 0xFF in such cases). However, some flashes have different erased value like for example 0x00 (set element to 0x00 for such cases)
TimeoutProg
Timeout in miliseconds (ms) to program one chunk of <PageSize>
TimeoutErase
Timeout in miliseconds (ms) to erase one sector
SectorInfo
This element is actually a list of different sector sizes present on target flash. The define MAX_NUM_SECTORS does not describe the max. number of sectors the algorithm can handle, it describes how many blocks of sectors of different sizes can be handled. The MAX_NUM_SECTORS define must not be changed! This spec. comes from the original Keil MDK-ARM flash loaders the Open Flashloader is compatible to and is not really well explained.
Example
The algorithm handles a flash with the following sectorization:
256 KiB divided into: 4 * 16 KiB 1 * 64 KiB 1 * 128 KiB <SectorInfo>: // SectSize StartAddr of block (absolute) 0x00004000, 0x00000000, // 4 * 16 KiB = 64 KiB 0x00010000, 0x00010000, // 1 * 64 KiB = 64 KiB 0x00020000, 0x00020000, // 1 * 128 KiB = 128 KiB 0xFFFFFFFF, 0xFFFFFFFF // Indicates the end of the flash sector layout. Must be present.
256 KiB divided into: 256 * 1 KiB <SectorInfo>: // SectSize StartAddr of block (absolute) 0x00000800, 0x00000000, // 256 * 1 KiB = 256 KiB 0xFFFFFFFF, 0xFFFFFFFF // Indicates the end of the flash sector layout. Must be present.
256 KiB divided into: 4 * 64 KiB <SectorInfo>: // SectSize StartAddr of block (absolute) 0x00010000, 0x00000000, // 4 * 64 KiB = 256 KiB 0xFFFFFFFF, 0xFFFFFFFF // Indicates the end of the flash sector layout. Must be present.
Example for STM32F401VC (256 KiB internal flash):
struct FlashDevice const FlashDevice __attribute__ ((section ("DevDscr"))) = { ALGO_VERSION, // Algo version "Template internal flash", // Flash device name ONCHIP, // Flash device type 0x00000000, // Flash base address 0x00040000, // Total flash device size in Bytes (256 KiB) 128, // Page Size (Flash needs to be programmed 128 byte aligned, in 128 byte chunks) 0, // Reserved, should be 0 0xFF, // Flash erased value 100, // Program page timeout in ms 6000, // Erase sector timeout in ms // // Flash sector layout definition // 0x00004000, 0x00000000, // 4 * 16 KiB = 64 KiB 0x00010000, 0x00010000, // 1 * 64 KiB = 64 KiB 0x00020000, 0x00020000, // 1 * 128 KiB = 128 KiB 0xFFFFFFFF, 0xFFFFFFFF // Indicates the end of the flash sector layout. Must be present. };
Using a Precompiled Flashloader
- Make sure that J-Link software V6.16f or later is installed:
https://www.segger.com/downloads/jlink/ - Browse to the location of the JLinkDevices folder. If it does not exist, create it.
- Create a new *.xml file in a text editor and add the device entry.
Example: - Copy the flashloader file, referenced in the JLinkDevices.xml entry, into the same directory where also the JLinkDevices.xml is located (in this example ST_STM32F7xxxx_2MB_DualBank.elf).
- Start JFlash.exe (or any other application which supports J-Link) and select the device
<Database> <Device> <!-- This entry will overwrite the existing device entry in the J-Link software, so that a custom flash algorithm is used for the internal flash --> <ChipInfo Vendor="ST" Name="STM32F767ZI" Core="JLINK_CORE_CORTEX_M7" /> <FlashBankInfo Name="Internal flash" BaseAddr="0x08000000" MaxSize="0x00200000 " Loader="ST_STM32F7xxxx_2MB_DualBank.elf" LoaderType="FLASH_ALGO_TYPE_OPEN" /> </Device> </Database>