Programming eCOG1X Internal Flash Memory in CyanIDE 2

AN106 – Programming eCOG1X Internal Flash Memory in CyanIDE 2 Version 1.0

This application note describes Read, Write and Erase operations for the internal flash memory in the eCOG1X microcontrollers, and their implementation in CyanIDE 2. It also describes a simple example application project that copies data from one sector to another.

05 September 2008 Cyan Technology Ltd.

AN106 Programming eCOG1X Internal Flash Memory in CyanIDE 2 Version 1.0

Confidential and Proprietary Information ©Cyan Technology Ltd, 2008

This document contains confidential and proprietary information of Cyan Technology Ltd and is protected by copyright laws. Its receipt or possession does not convey any rights to reproduce, manufacture, use or sell anything based on information contained within this document.

Cyan TechnologyTM, the Cyan Technology logo and Max-eICETM are trademarks of Cyan Holdings Ltd. CyanIDE® and eCOG® are registered trademarks of Cyan Holdings Ltd. Cyan Technology Ltd recognises other brand and product names as trademarks or registered trademarks of their respective holders.

Any product described in this document is subject to continuous developments and improvements. All particulars of the product and its use contained in this document are given by Cyan Technology Ltd in good faith. However, all warranties implied or expressed, including but not limited to implied warranties of merchantability, or fitness for purpose, are excluded.

This document is intended only to assist the reader in the use of the product. Cyan Technology Ltd shall not be liable for any loss or damage arising from the use of any information in this guide, any error or omission in such information, or any incorrect use of the product.

This product is not designed or intended to be used for on-line control of aircraft, aircraft navigation or communications systems or in air traffic control applications or in the design, construction, operation or maintenance of any nuclear facility, or for any medical use related to either life support equipment or any other life-critical application. Cyan Technology Ltd specifically disclaims any express or implied warranty of fitness for any or all of such uses. Ask your sales representative for details.

05 September 2008 Cyan Technology Ltd. of 15



Revision History Version Date Notes

V1.0 05/10/2008 First release.



Contents 1 Introduction.......................................................................................... 5

2 Glossary .............................................................................................. 5

3 Internal Flash Operations .................................................................... 6 3.1 Memory Configuration ............................................................................... 6

3.1.1 Flash Data Mapping ........................................................................... 6 3.1.2 RAM Code Mapping ........................................................................... 6

3.2 Execution from RAM.................................................................................. 6 3.2.1 Initialisation......................................................................................... 6 3.2.2 Execution............................................................................................ 8

3.3 Flash Operations ....................................................................................... 8 3.3.1 Erase Sector....................................................................................... 8 3.3.2 FLASH_write ...................................................................................... 9 3.3.3 FLASH_read....................................................................................... 9 3.3.4 Operation Status............................................................................... 10

4 Example............................................................................................. 11 4.1 Overview.................................................................................................. 11 4.2 Program Flow .......................................................................................... 11 4.3 Using the Application Software................................................................ 11

4.3.1 Importing the Project into CyanIDE 2 ............................................... 11 4.3.2 Running the Project .......................................................................... 12

Appendix A Flash APIs.......................................................................... 13 A.1 Data Structures........................................................................................ 13 A.2 Functions................................................................................................. 14


1 Introduction

This application note describes the READ, WRITE and ERASE operations for the internal flash memory of the eCOG1X. These flash processes are provided as API functions in a CyanIDE 2 project archive. A simple example demonstrates a procedure for copying data from one flash sector to another.

2 Glossary

A table of abbreviations used in this document.

API Application Programming Interface eCOG1X Cyan target 16-bit microcontroller CyanIDE Cyan’s integrated development environment IRAM Internal Random Access Memory MMU eCOG1X Memory Management Unit SA Flash sector address



3 Internal Flash Operations

The eCOG1X contains a total of 528KB of on-chip flash memory for program and data storage, organised as three blocks: one main block of 512KB divided into 11 sectors, and 2 smaller blocks of 8KB each, BOOT and TROM. More details on the organisation and sector sizes of the embedded flash can be found in the eCOG1X User Manual.

The first 128 bytes of the TROM sector are used in many Cyan application examples for the storage of system information, such as the serial number, software version and EMAC address.

The example described here executes from the internal flash memory. Note that code cannot be executed from any sector of the flash memory while any part of the flash is being erased or programmed, therefore the erase and write routines are copied to and executed from internal RAM. Also note that because the code is stored in the main block of the flash, the read routines also need to be executed from IRAM when reading data from the TROM or BOOT sector.

3.1 Memory Configuration

3.1.1 Flash Data Mapping To program the flash, the application maps a 4KB page of flash into data space at logical address 0x0000, using the flash_data1 translator in the MMU. It disables the flash_data0, usb and emac data space translators as these have higher precedence than flash_data1. However, the internal RAM data blocks 0 and 1 are not disabled since they are likely to be used for the stacks and heap, so care must be taken that their mappings do not overlap with the flash_data1 mapping.

The flash data mapping is done by the following macros:

MAP_FLASH_PAGE_INIT()

MAP_FLASH_PAGE()

END_MAP_FLASH_PAGE()

3.1.2 RAM Code Mapping When programming the flash, the code is executed from IRAM through the ram_code code space translator, at logical address 0x80000 (size = 32K bytes).

3.2 Execution from RAM

3.2.1 Initialisation In order to make the use of the flash routines easier, an initialisation function takes care of copying them into the IRAM and retrieving their addresses (as pointers) in the different memory spaces.

Since the function pointers are 16-bit addresses, they cannot directly address the entire program memory map and are implemented as addresses into a jump table. For normal use with static code this is transparent to the user. However, for this example where it is necessary to relocate functions at run-time, some extra work is required to be able to retrieve function pointers and use them effectively to assign a new address for a function copied to RAM.

The solution chosen in this example consists of locating the required functions in a specific code section and finding their absolute addresses at compile time using the linker script. Similarly, the function size can be found at compile time by introducing a dummy function label after the required function and calculating the difference between the function start and end addresses.



The steps are:

1. Attribute a section to the function unsigned long flash_sector_erase(va_list args_in) __attribute__ ((section (".text.flash_sector_erase"))); unsigned long flash_sector_erase(va_list args_in) { … } void flash_sector_erase_end(void){}

2. Modify the linker script to find the address .ecog1.text : { *(.text) start_flash_sector_erase = .; *(.text.flash_sector_erase) end_flash_sector_erase = .; *(.text.*) . = ALIGN(0x2); } >code AT>CodeFlash flash_sector_erase_size = end_flash_sector_erase - start_flash_sector_erase;

3. Retrieve the address in the program using some assembly code. The following macros can be used:

#define GET_FUNC_START(x) ({ unsigned long __addr; asm ("ld\t%%AH, %%hwrd(" #x ")\n\tld\t%%AL, %%lwrd(" #x ")\n\tlsl\t1" : "=a" (__addr)); __addr; })

#define GET_FUNC_SIZE(x) ({ unsigned int __size; asm ("ld\t%0, " #x "_size" : "=h" (__size)); __size; })

unsigned long flash_sector_erase_addr = GET_FUNC_START(flash_sector_erase);

The address retrieved in this way is actually the logical address in code space, so before copying the function, the physical address must be inferred from the MMU code settings.

Similarly, when the functions are copied to the heap, their pointer values refer to the MMU IRAM data space, but they are required for use in the MMU IRAM code space. The initialization function calculates all the required pointers, which are defined as global variables.

function_name_irom_ptr refers to the function pointer in the flash_data1 space.

function_name_iram_cmd_ptr is the function pointer in the heap (ram_data1 space).

function_name_cmd is the function pointer in the ram_code space.

Depending on which block of the flash is accessed and which operations are used, only the required routines are copied into IRAM. Four cyan_flash_mode values are defined:

FLASH_READ_WRITE_ONLY Copy erase and write functions into IRAM FLASH_READ_WRITE_TROM_BOOT_MAIN Copy erase, write and read into IRAM FLASH_R_MAIN_ONLY No functions copied FLASH_R_TROM_BOOT_MAIN Copy read function into IRAM



3.2.2 Execution Once the function has been copied into RAM and mapped into code space (at address 0x80000), it can be called from the application code. However, it cannot be called directly due to the way in which CyanIDE 2 implements function pointers. Instead, a function is called that is located in the lower 64KB of code memory, which then "trampolines" to the required function wherever it is located. Note that this call to the relocated flash programming function can take place only after mapping the right part of RAM into code space, and disabling all interrupts and the cache. /** * @brief FLASH function RAM execution trampoline. * @param start_addr Function start address. * @param args Variable argument list. * * @return @ref FLASH_SUCCESS if the FLASH is read successfully; otherwise * an @ref flash_ret_t "error code". */ extern unsigned long flash_function_ram_execute_trampoline (unsigned long start_addr, va_list args);

3.3 Flash Operations

3.3.1 Erase Sector Flash memory bits can be programmed only from a ‘1’ to a ‘0’. Changing bits back from a ‘0’ to a ‘1’ requires an erase operation, either a sector erase or a chip erase.

The FLASH_erase_sector function allows one selected flash sector to be erased in a single operation. Single word erase operation is not available in the eCOG1X internal flash.

If erasing the TROM sector, the function saves and restores the system information stored in the first 128 bytes.

FLASH_erase_sector is seamlessly executed from RAM with the interrupts and cache disabled.

The following table shows the command sequence for the SECTOR ERASE operation, consisting of six write cycles.

Address Data FLASH_LOGICAL_ADDRESS + 0x555 0xAA

FLASH_LOGICAL_ADDRESS + 0x2AA 0x55

FLASH_LOGICAL_ADDRESS + 0x555 0x80

FLASH_LOGICAL_ADDRESS + 0x555 0xAA


FLASH_LOGICAL_ADDRESS + offset 0x30

Table 1. Sector erase operation

FLASH_LOGICAL_ADDRESS: The logical base address in data space for the internal flash_data1 memory mapping.

Offset: Any valid address within the selected flash sector.



3.3.2 FLASH_write The FLASH_write function programs a given number of bytes of data (void *) at the specified target address in the given flash block.

Note that flash memory bits can be programmed only from a ‘1’ to a ‘0’. Changing bits back from a ‘0’ to a ‘1’ requires an erase operation, either a sector erase or a chip erase.

FLASH_write is seamlessly executed from RAM with the interrupts and cache disabled.

After setting the write enable bits for the required sectors, the command sequence for the WRITE BUFFER operation is executed, consisting of six or more write cycles.

Address Data FLASH_LOGICAL_ADDRESS + 0x555 0xAA


FLASH_LOGICAL_ADDRESS + sectaddr 0x25

FLASH_LOGICAL_ADDRESS + sectaddr i-1

FLASH_LOGICAL_ADDRESS + offset + 0 data[0]

FLASH_LOGICAL_ADDRESS + offset + 1 data[1]

: :

FLASH_LOGICAL_ADDRESS + offset + (i-2) data[i-2]

FLASH_LOGICAL_ADDRESS + offset + (i-1) data[i-1]

FLASH_LOGICAL_ADDRESS + sectaddr 0x29

Table 2. Write Buffer Operation

sectaddr: Any valid address within the target flash sector.

offset: Any valid offset address within the selected flash sector.

FLASH_LOGICAL_ADDRESS: the logical base address in data space for the internal flash_data1 mapping.

data[ ]: An array of 16-bit data words containing the data to be written to internal flash.

i: The number of data words to be programmed.

3.3.3 FLASH_read The FLASH_read operation reads a buffer of data at the specified target address in the given block of flash.

The C code statements corresponding to the Read operation are: for (i=0; i<size; i++) { ((unsigned char*)data_ptr)[end_page_data + i] = Flash_Page_Block[offset+i]; }

If reading from the main block of the flash, FLASH_read is executed directly. If reading from either the TROM or BOOT sector, FLASH_read is executed seamlessly from IRAM.



3.3.4 Operation Status The status of the above flash operations can be accessed during the operation by reading the contents of the flash at the data base address:

status = *(unsigned int *)(FLASH_LOGICAL_ADDRESS);

FLASH_LOGICAL_ADDRESS: The logical base address in data space for the internal flash mapping. The flash sector to be read should be mapped to this region.

The least significant byte indicates the status of the operation.

Here is the summary of the status bits:

Bit Bit Name Description DB7 Data Polling Bit Inverse of data bit if operation is in progress or fails.

Outputs actual data bit when the operation succeeds.

DB6 Toggle Bit 1 Continues to toggle on successive reads if an operation is in progress or fails. Outputs actual data bit when operation succeeds.

DB5 Internal Timeout Set if internal timeout occurs during a Program or Erase operation.

DB4 Erase Phase Indicator

Additional information to DB5 = 1 when the Erase operation fails. DB4 = 1 indicates the Erase Phase of the Erase operation failed. DB4 = 0 indicates the Program Phase of the Erase operation failed.

DB3 Sector Erase Timer

Set when the Sector Erase operation starts. Clear when the Erase Hold Timer is triggered and counting down.

DB2 Toggle Bit 2 Toggles on successive read cycles during the Erase operation. Outputs actual data bit when the Erase operation succeeds.

DB1 Write to Buffer Abort

Set when a Write Buffer operation has been aborted.

DB0 Not used -



4 Example

4.1 Overview The software example demonstrates these operations on the internal flash with CyanIDE 2. The target device is an eCOG1X14Z5, which contains 512KB of embedded flash. The software example defines flash sector 0 (SA0) as the code area. Flash sector 10 (SA10) is assigned as the application data area, as in the default CyanIDE 2 memory configuration. Flash sector 9 (SA9), which has the same size as sector 10, is used as a temporary storage area when SA10 is being erased and reprogrammed.

The purpose of the example is to modify the application data content in SA10. In order to modify the data in SA10, it is necessary to first erase this flash sector area and then to program it with new contents.

4.2 Program Flow The following steps describe the operation of the software example.

• Erase flash sector 9. • Copy flash sector 10 to flash sector 9.

• Read 128 bytes from flash sector 10 in data buffer.

• Write data buffer into flash sector 9.

• Repeat these 2 steps until the whole sector is copied.

• Map flash_data0 space to sector 9 via MMU. • Erase flash sector 10. • Restore data content to flash sector 10.

• Read 128 bytes from flash sector 9 into data buffer.

• Write data buffer into flash sector 10.

• Repeat these 2 steps until the whole sector is copied.

• Restore MMU flash_data0 space to sector 10. • Free IRAM from the flash routines.

4.3 Using the Application Software

4.3.1 Importing the Project into CyanIDE 2 - Create a new Cyan Executable project from the file menu

o Enter a project name.

o Choose the board type: DEVKIT1X - eCOG1X Dev Board rev. B.

o Choose chip type: cCOG1X14Z5.

o Select blank project.

- In the Project Explorer: right-click on the project and select Import...

- In the new window, select General->Archive File, click Next.

- Find the project archive in the file system and click “Finish”.

- The system prompts whether you want to overwrite the .cproject and .project files: click on “Yes to All”.

- Compile the project and run it (using Debug As).



4.3.2 Running the Project The application uses serial port UART1A to output basic information about the application.

In order to check what the program is doing, the CyanIDE 2 debug environment can be used to set breakpoints after the erase and write operations and look at the memory monitor window. Meaningful program data are mapped at address 0x0 and can be seen there throughout the program.

However, to check that the program data are actually written and erased in the flash, we can use the fact that the flash_code0 space maps the entire flash memory. Code space in the CyanIDE debugger is viewed at memory addresses 0x80000000 and above. Thus data in sector 10 can be seen at address 0x8078000, and the copied data can be seen in sector 9 at address 0x8068000.

Note: by default, CyanIDE 2 displays only what it expects for the flash_data0 space at the address 0x0000, because normally this is the constant data area and does not change. To change this behaviour, enter the following text in the gdb console window:

>set trust-readonly-sections off



Appendix A Flash APIs

A.1 Data Structures /** * @brief Flash sector description */ typedef struct { unsigned long start_addr; unsigned long size; } flash_sector_info_s; typedef flash_sector_info_s * flash_sector_info_t; /** * @brief flash blocks */ typedef enum { MAIN_FLASH_BLOCK, BOOT_FLASH_BLOCK, TROM_FLASH_BLOCK } Flash_Block_t; /** * @brief Flash programming modes available. */ typedef enum { FLASH_RW_MAIN_ONLY = 0, FLASH_RW_TROM_BOOT_MAIN, FLASH_R_MAIN_ONLY, FLASH_R_TROM_BOOT_MAIN } cyan_flash_mode; /** * @brief flash initialisation information structure. */ typedef struct { cyan_flash_mode flash_mode; } flash_control_block_t; /** * @brief Persistent data with system information stored in the TROM sector. */ typedef struct { unsigned int Info_Block_Version; unsigned int Hardware_Version; unsigned long Serial_Number; char MAC_Address[6]; } Info_Data_t;



A.2 Functions /** * @brief Allocate space in heap and copy flash routine from internal flash to IRAM. * @return TRUE if the succeeds, FALSE if there is not enough space in heap. */ bool FLASH_init(flash_control_block_t flash_ctrl); /** * @brief Write data to internal flash. * @param block Flash block to be written. * @param address Start address. * @param data Data buffer. * @param size Size in words. * * @return FLASH_SUCCESS if the write succeeds, other failed address. */ unsigned long FLASH_write(Flash_Block_t block, unsigned long address, void *data,unsigned int size); /** * @brief Erase one sector of internal flash. * @param block Flash block to be written. * @param sector_num Flash sector to erase. * * @return FLASH_SUCCESS if the succeeds, otherwise error code. */ int FLASH_erase_sector(Flash_Block_t block, unsigned int sector_num); /** * @brief Read a block of internal flash. * @param block Flash block to be read. * @param address Flash Address to read from. * @param data_ptr Data buffer. * @param size Size in words. * * @return FLASH_SUCCESS if the succeeds, otherwise error code. */ int FLASH_read(Flash_Block_t block, unsigned long address, void *data_ptr, unsigned int size); /** * @brief Free flash routine in heap. * @return TRUE if successful. */ bool FLASH_free_iram(void); /** * @brief Get the information of a given sector * @param block Flash block * @param sector_num Sector whose information are needed * @param sector_infos Structure with the sector information * * @return FLASH_SUCCESS if the succeeds, otherwise error code */ int FLASH_get_sector_info(Flash_Block_t block, unsigned int sector_num, flash_sector_info_t sector_infos); /** * @brief Get the number of sectors in a block of the flash * @param block Flash block * * @return int the number of sector, negativ value if an error occured */ int FLASH_get_number_of_sectors(Flash_Block_t block); /** * @brief Retrieve the MAC address from the Flash TROM sector. * @param addr pointer to store the MAC address. * * @return TRUE if the succeeds, otherwise FALSE. */ bool FLASH_get_MAC_address(char *addr);




/** * @brief Retrieve the serial number. * @param serial_num pointer to store the serial number. * * @return TRUE if the succeeds, otherwise FALSE. */ bool FLASH_get_serial_number(unsigned long *serial_num); /** * @brief Retrieve the Hardware version from the Flash TROM sector. * @param hardware_version pointer to store the HW version. * * @return TRUE if the succeeds, otherwise FALSE. */ bool FLASH_get_hardware_version(unsigned int *hardware_version);

Programming eCOG1X Internal Flash Memory in CyanIDE 2

Documents

Transcript of Programming eCOG1X Internal Flash Memory in CyanIDE 2