Difference between revisions of "Adding Support for New Devices"
(→Information for Silicon Vendors) |
(Redirected page to "Open Flashloader") |
||
| Line 1: | Line 1: | ||
| + | #REDIRECT [["Open Flashloader"]] |
||
| − | __TOC__ |
||
| − | 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...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 '''Open Flashloader''' chapter in the J-Link User Manual (UM08001). 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 (can be evaluated without license; Supports Cortex-M and Cortex-A/R)<br>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. |
||
| − | = Creating a flash algorithm using SEGGER Embedded Studio = |
||
| − | 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 == |
||
| − | {| class="wikitable" |
||
| − | |- |
||
| − | ! 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'''<br>'''ARM_Startup.s''' || Cortex-M startup code (used by debug configuration, only) <br> 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'''<br>'''crt0.s''' || Initialization file for Cortex-M (used by debug configuration, only)<br>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. |
||
| − | *[[File:OpenFlashLoader_CortexM_Template_EmbeddedStudio.zip]] |
||
| − | *[[File:OpenFlashLoader_CortexAR_Template_EmbeddedStudio.zip]] |
||
| − | |||
| − | == 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. |
||
| − | #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 |
||
| − | ##'''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 / ...). |
||
| − | |||
| − | === 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 flash loader 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. |
||
| − | }; |
||
| − | |||
| − | == Frequently Asked Questions == |
||
| − | In which order does the J-Link DLL call the function during flash programming? |
||
| − | #Compare |
||
| − | ##Init() |
||
| − | ##Compare()<br>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. |
||
| − | ##UnInit() |
||
| − | # Erase |
||
| − | ## Init() |
||
| − | ## Erase() |
||
| − | ## UnInit() |
||
| − | # Program |
||
| − | ## Init() |
||
| − | ## Program() |
||
| − | ## 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. |
||
| − | #Get the latest version of the template project |
||
| − | #Follow the Step-By-Step instructions expect of 2.1 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. |
||
| − | === 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 Flash Loader 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. |
||
| − | |||
| − | = Using a Precompiled Flashloader = |
||
| − | <ul> |
||
| − | <ol> |
||
| − | <li>Make sure that J-Link software V6.16f or later is installed:<br>https://www.segger.com/downloads/jlink/</li> |
||
| − | <li>Browse to the installation of the J-Link software package.<br>You should now see JFlash.exe, JLinkDevices.xml, ...</li> |
||
| − | <li>Open JLinkDevices.xml in a text editor and add the device entry at the beginning, right after the <Database> opening tag.<br>Example:</li> |
||
| − | <!-- 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> |
||
| − | <li>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).</li> |
||
| − | <li>Start JFlash.exe (or any other application which supports J-Link) and select the device</li> |
||
| − | </ol> |
||
| − | </ul> |
||
| − | |||
| − | = 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. |
||
Revision as of 15:26, 4 April 2019
Redirect to:
