Difference between revisions of "SEGGER Flash Loader"

From SEGGER Wiki
Jump to: navigation, search
(SEGGER_OPEN_Erase)
(ProgramPage)
Line 658: Line 658:
 
'''Prototype'''
 
'''Prototype'''
 
<syntaxhighlight lang="c" line='line'>
 
<syntaxhighlight lang="c" line='line'>
  +
int ProgramPage(U32 DestAddr, U32 NumBytes, U8 *pSrcBuff)
int EraseSector(U32 SectorAddr)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
   
Line 712: Line 712:
 
} while (--NumPages);
 
} while (--NumPages);
 
}
 
}
  +
return r;
  +
}
  +
</syntaxhighlight>
  +
  +
==ProgramPage==
  +
'''Prototype'''
  +
<syntaxhighlight lang="c" line='line'>
  +
int ProgramPage(U32 DestAddr, U32 NumBytes, U8 *pSrcBuff)
  +
</syntaxhighlight>
  +
  +
'''Function description'''
  +
  +
Programs one flash page.
  +
  +
'''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'''
  +
  +
<syntaxhighlight lang="c" line='line'>
  +
int ProgramPage(U32 DestAddr, U32 NumBytes, U8 *pSrcBuff) {
  +
volatile U8 * pSrc;
  +
volatile U8 * pDest;
  +
U8 AccessWidth;
  +
U32 Status;
  +
U32 NumBytesAtOnce;
  +
int r;
  +
  +
r = -1;
  +
pSrc = (volatile U8*)pSrcBuff;
  +
pDest = (volatile U8*)DestAddr;
  +
//
  +
// Program page-wise
  +
//
  +
r = 0;
  +
do {
  +
NumBytesAtOnce = (1 << PAGE_SIZE_SHIFT);
  +
_FeedWatchdog();
  +
//
  +
// Program one page
  +
//
  +
do {
  +
//
  +
// Program page code
  +
//
  +
*pDest++ = *pSrc++;
  +
} while(--NumBytesAtOnce);
  +
} while (--NumPages);
 
return r;
 
return r;
 
}
 
}

Revision as of 15:03, 4 April 2019


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

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

In order to add support for a new device to the J-Link DLL, the following needs to be added to the JLinkDevices.xml :

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

Adding a New Flash Bank

In general, there are two possibilities to add a new flash bank for a new or existing device:

  1. Use a pre-compiled flash loader
  2. Compile / create the flash loader on your own
    1. Using Keil uVision (a license is required, no trial available; Supports Cortex-M, only)
    2. SEGGER Embedded Studio (can be evaluated without license; Supports Cortex-M and Cortex-A/R)
      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.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 This tag has no attributes 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, is relative to the location of the JLinkDevices.xml file. This attribute is mandatory. 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:

<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 and Cortex-A/R) 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:

  1. Use a pre-compiled flash loader
  2. Compile / create the flash loader on your own
    1. Using Keil uVision (a license is required, no trial available; Supports Cortex-M, only)
    2. SEGGER Embedded Studio (can be evaluated without license; Supports Cortex-M and Cortex-A/R)
      How to create a flash loader on your own using Embedded Studio is described below.

Supported cores:

  • Cortex-M
  • Cortex-A
  • Cortex-R

Note: The Open Flashloader concept replaces the previous RAMCode SDK.

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.

  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. Placement_debug.xml: Enter RAM address in the program section element.
    5. 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 / ...).

FAQ

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.

  1. Get the latest version of the template project
  2. Follow the Step-By-Step instructions except 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.

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.

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)

// EL xxxxxx Add SEGGER_Open_Program


Flash Erase Procedure

This procedure is executed to erase the flash before programming it.

Flash Erase Procedure.svg

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.

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.

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 }

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 (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 ProgramPage(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 (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 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 KB in size, <TotalSize> must be 0x80000 (524,288 => 512 KB)

PageSize

This field describes in what chunks J-Link feeds the flash loader. The 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 KB divided into:
4 *  16 KB
1 *  64 KB
1 * 128 KB

<SectorInfo>:
  // SectSize StartAddr of block (absolute) 
  0x00004000, 0x00000000,   // 4 *  16 KB =  64 KB
  0x00010000, 0x00010000,   // 1 *  64 KB =  64 KB
  0x00020000, 0x00020000,   // 1 * 128 KB = 128 KB
  0xFFFFFFFF, 0xFFFFFFFF    // Indicates the end of the flash sector layout. Must be present.
256 KB divided into:
256 * 1 KB

<SectorInfo>:
  // SectSize StartAddr of block (absolute) 
  0x00000800, 0x00000000,   // 256 * 1 KB = 256 KB
  0xFFFFFFFF, 0xFFFFFFFF    // Indicates the end of the flash sector layout. Must be present.
256 KB divided into:
4 * 64 KB

<SectorInfo>:
  // SectSize StartAddr of block (absolute) 
  0x00010000, 0x00000000,   // 4 * 64 KB = 256 KB
  0xFFFFFFFF, 0xFFFFFFFF    // Indicates the end of the flash sector layout. Must be present.

Example for STM32F401VC (256 KB 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 KB)
  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 KB =  64 KB
  0x00010000, 0x00010000,   // 1 *  64 KB =  64 KB
  0x00020000, 0x00020000,   // 1 * 128 KB = 128 KB
  0xFFFFFFFF, 0xFFFFFFFF    // Indicates the end of the flash sector layout. Must be present.
};

Using a Precompiled Flashloader

  1. Make sure that J-Link software V6.16f or later is installed:
    https://www.segger.com/downloads/jlink/
  2. Browse to the installation of the J-Link software package.
    You should now see JFlash.exe, JLinkDevices.xml, ...
  3. Open JLinkDevices.xml in a text editor and add the device entry at the beginning, right after the <Database> opening tag.
    Example:
  4.  <!-- 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="Internes Flash" BaseAddr="0x08000000" MaxSize="0x00200000 " Loader="ST_STM32F7xxxx_2MB_DualBank.elf" LoaderType="FLASH_ALGO_TYPE_OPEN" />
     </Device>
    
  5. 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).
  6. Start JFlash.exe (or any other application which supports J-Link) and select the device

Information for Silicon Vendors

SEGGER offers the opportunity to hand in custom created flash algorithms which will then be included in the official J-Link Software and Documentation Package hence distributed to any J-Link customer who is using the latest software package. The following files and hardware need to be provided to SEGGER:

  • All required source files + the project which can be used to rebuild the algorithm of the flashloader
  • JLinkDevices.xml - including the device entry / entries
  • Flash loader file - referenced in the JLinkDevices.xml (which is based on the provided source files)
  • Two hardware samples which can be used to verify the functionality of the compiled flashloader
  • Readme.txt which may includes additional information or at least a contact e-mail address which can be used by customers in case support is needed.

This applies to all new flashloaders which should be shipped with the J-Link package. If a silicon vendor cannot meet the requirements, the alternative option is to deliver the flashloader to the customers manually.