MEMORY functions

Collaboration diagram for MEMORY functions:

Macros
#define	mem_getDataAddr(u16Addr)   *(((uint8*)&u16Addr)) = *((uint8 volatile xdata *) SWI_ADDR); *(((uint8*)&u16Addr + 1)) = 0x00;
#define	mem_getPrgSize(u8PrgSize)   *(((uint8*)&u8PrgSize)) = *((uint8 volatile xdata *) SWI_ADDR);
#define	mem_backupFlashPage(u16SrcAddr, u16DstAddr, pu8Buffer)   mem_readFlash(pu8Buffer,u16SrcAddr, 512); mem_writeFlash(pu8Buffer, u16DstAddr, 512)
#define	mem_restoreFlashPage(u16SrcAddr, u16DstAddr, pu8Buffer)   mem_backupFlashPage(u16SrcAddr, u16DstAddr, pu8Buffer)
#define	mem_checkBackup(u16SrcAddr, u16DstAddr)   memcmp((uint8 code *)(u16SrcAddr), (uint8 code *)(u16DstAddr), 512)

Functions
RETURN_TYPE	mem_writeFlash (uint8 xdata *pu8SrcAddr, uint16 u16DstAddr, uint16 u16NumBytes)
RETURN_TYPE	mem_writeFlashNoErase (uint8 xdata *pu8SrcAddr, uint16 u16DstAddr, uint16 u16NumBytes)
RETURN_TYPE	mem_writeRAM0 (uint8 *pu8SrcAddr, uint8 u8DstAddr, uint8 u8NumBytes)
RETURN_TYPE	mem_readFlash (uint8 xdata *pu8DstAddr, uint16 u16SrcAddr, uint16 u16NumBytes)
RETURN_TYPE	mem_readRAM0 (uint8 *pu8DstAddr, uint8 u8SrcAddr, uint8 u8NumBytes)
RETURN_TYPE	mem_flashBist ()
RETURN_TYPE	mem_readEEPROM (uint8 xdata *pu8DstAddr, uint16 u16SrcAddr, uint8 u8NumBytes)
RETURN_TYPE	mem_writeEEPROM (uint8 xdata *pu8SrcAddr, uint16 u16DstAddr, uint8 u8NumBytes)

---

Detailed Description

The MEM module offers access interface to the following memories:

• flash area (which includes the program area, the configuration area, the software information area, the module and chip information areas)
• RAM0 (Address range: 0x00 - 0x1F, Size: 32 byte)

Using the MEM module it is possible to verify flash program area consistancy using Built In Self test routine. Be sure to read flash_arch, Configuration area (CFG).

---

Macro Definition Documentation

#define mem_getDataAddr

(

u16Addr

)

*(((uint8*)&u16Addr)) = *((uint8 volatile xdata *) SWI_ADDR); *(((uint8*)&u16Addr + 1)) = 0x00;

This macro returns the address in the FLASH program area from which the application can store it's data. It is the first free page in the FLASH after the program pages.

Parameters:

[out]

u16Addr

Address of the first free FLASH page

Returns:

-

See also:

mem_writeFlash, mem_getPrgSize

#define mem_getPrgSize

(

u8PrgSize

)

*(((uint8*)&u8PrgSize)) = *((uint8 volatile xdata *) SWI_ADDR);

This macro returns the program size stored in the flash in FLASH pages

Parameters:

[out]

u8PrgSize

Program area size in FLASH pages

Returns:

-

See also:

mem_writeFlash, mem_getDataAddr

#define mem_backupFlashPage	(		u16SrcAddr,
			u16DstAddr,
			pu8Buffer
	)		mem_readFlash(pu8Buffer,u16SrcAddr, 512); mem_writeFlash(pu8Buffer, u16DstAddr, 512)

This macro performs a backup of one FLASH page (512 bytes)

Parameters:

[in]	u16SrcAddr	Source memory address of data to backup in PRG_AREA: 0x0000 - 0xFF00
[in]	u16DstAddr	Destination memory address of the backup area in PRG_DATA: 0x0000-0xFF00
[in]	pu8Buffer	Pointer to a buffer of 512 byte xdata memory for temporary storing of the FLASH page to backup

Returns:

ADDR_OUT_OF_MEM If the u16DstAddr + 512 is in SWI area

FLASH_HW_ERROR If there was an error during writing

OK if the process was succesfull

Note:

Be sure not to use addresses in your program memory, use mem_getDataAddr to get the next free page after your program

Do not use SWI area

Example:

    #define ORIGINAL_DATA 0x7000
    #define BACKUP_DATA   0x7200
    uint8 xdata buf[256] _at_ 0x600;
    mem_backupFlashPage(ORIGINAL_DATA, BACKUP_DATA, &buf);

See also:

mem_restoreFlashPage, mem_checkBackup, mem_writeFlash, mem_readFlash, mem_getDataAddr

#define mem_restoreFlashPage	(		u16SrcAddr,
			u16DstAddr,
			pu8Buffer
	)		mem_backupFlashPage(u16SrcAddr, u16DstAddr, pu8Buffer)

This macro performs a restore of one FLASH page (512 bytes)

Parameters:

[in]	u16SrcAddr	Source memory address of the backup area in PRG_DATA: 0x0000-0xFE00
[in]	u16DstAddr	Destination memory address of your original data in PRG_AREA: 0x0000 - 0xFE00
[out]	pu8Buffer	Pointer to a buffer of 512 byte xdata memory for temporary storing of the FLASH page to restore

Returns:

FLASH_HW_ERROR If there was an error during writing

OK if the process was successful

Note:

Be sure not to use addresses in your program memory, use mem_getDataAddr to get the next free page after your program

Do not use CFG area

Example:

    #define ORIGINAL_DATA 0x7000
    #define BACKUP_DATA   0x7200
    uint8 xdata buf[256] _at_ 0x600;
    mem_restoreFlashPage(BACKUP_DATA, RESTORE_DATA, &buf);

See also:

mem_backupFlashPage, mem_checkBackup, mem_writeFlash, mem_readFlash, mem_getDataAddr

#define mem_checkBackup	(		u16SrcAddr,
			u16DstAddr
	)		memcmp((uint8 code *)(u16SrcAddr), (uint8 code *)(u16DstAddr), 512)

This macro checks the contents of one FLASH page (512 bytes) for equal data

Parameters:

[in]	u16SrcAddr	Source memory address of the original data in PRG_DATA: 0x0000-0xFE00
[in]	u16DstAddr	Destination memory address of backuped data in PRG_AREA: 0x0000 - 0xFE00

Returns:

0 Both FLASH pages contain the same data

!= 0 The FLASH pages are different

Example:

    #define ORIGINAL_DATA 0x7000
    #define BACKUP_DATA   0x7200
    uint8 xdata buf[256] _at_ 0x600;
    if (mem_checkBackup(ORIGINAL_DATA, BACKUP_DATA) != 0)
        mem_restoreFlashPage(BACKUP_DATA, RESTORE_DATA, &buf);

See also:

mem_backupFlashPage, mem_restoreFlashPage, mem_writeFlash, mem_readFlash, mem_getDataAddr

---

Function Documentation

RETURN_TYPE mem_writeFlash	(	uint8 xdata *	pu8SrcAddr,
		uint16	u16DstAddr,
		uint16	u16NumBytes
	)

Takes the u16NumBytes bytes from the XDATA address pointing to by pu8SrcAddr and copies them to flash memory. Before writing to the FLASH all accessed FLASH pages are erased (1 page is 512 byte).

Parameters:

[in]	*pu8SrcAddr	Pointer to the bytes source, (only XDATA allowed)
[in]	u16DstAddr	Destination memory address, PRG_AREA: 0x0000 - 0xFDFF, 4-Byte-alligned (Bit0 and Bit1 have to be 0)
[in]	u16NumBytes	Number of bytes to copy (1..4096 because this is the max XDATA size)

Returns:

ADDR_OUT_OF_MEM If the u16DstAddr + u16NumBytes is in SWI area or u16DstAddr is not 4-Byte-alligned

FLASH_HW_ERROR If there was an error during erase operation

OK if the process was succesfull

Note:

When writing to FLASH the bootloader is called. The *pu8SrcAddr must reside in the XDATA!

Minimum amount of writing is 4 bytes. The destination address has to be 4 byte aligned.

Be sure XTAL is running when calling this function. When running with CRCO the duration of the flash write can take longer. Every time you write in a page even if only 4 bytes the page will be erased. Therefore be sure to keep a shadow register for the area you will to write in the XDATA.

Keep in mind that when writing to the FLASH all the interrupts are disabled. Therefore it is not possible to receive telegrams from radio or uart.

Note when writing to FLASH let's say 512 bytes it takes about 25 ms time. The system schedule has 1 ms takt but the interrupts are switched off during flash write and with them also the schedule timer. Therfore all the SW timer and also the system timer will be not precise. This has also influence on subtelegram timing and ARIB limitations!

Avoid writing too often to FLASH. The FLASH memories has a limited life cycle and accessing them needs lot of system resources (critical from power or timing point of view)

When writing to FLASH_PRG be sure to store data beyond the program area. You can get the size of your program in number of flash pages by calling mem_getDataAddr, mem_getPrgSize macro

You can also rewrite your own program in the FLASH. The mem_write is executed in the FLASH itself so be sure to avoid rewriting the mem_writeFlash function otherwise your program will crash.

The writing routine does not verify the bytes written in the flash. In a critical application the application should compare the data written to the flash with the data residing in RAM.

When receiving or sending an UART or radio telegram and simultaneously writing in FLASH memory the effect could be:

• corrupt UART telegram receiving
• corrupt radio telegram receiving
• wrong sub telegram timing for radio telegrams

See also:

mem_writeFlashNoErase, mem_writeFlash, mem_readFlash, mem_getDataAddr, mem_getPrgSize, flash_arch

RETURN_TYPE mem_writeFlashNoErase	(	uint8 xdata *	pu8SrcAddr,
		uint16	u16DstAddr,
		uint16	u16NumBytes
	)

Takes the u16NumBytes bytes from the XDATA address pointing to by pu8SrcAddr and copies them to the flash memory. The FLASH page is not erased before writing to the FLASH. The application must ensure that the page is clear (1 page is 512 byte).

Parameters:

[in]	*pu8SrcAddr	Pointer to the bytes source, (only XDATA allowed)
[in]	u16DstAddr	Destination memory address, PRG_AREA: 0x0000 - 0xFDF0, 4-Byte-aligned (Bit0 and Bit1 have to be 0)
[in]	u16NumBytes	Number of bytes to copy (1..4096 because this is the max XDATA size)

Returns:

ADDR_OUT_OF_MEM If the u16DstAddr + u16NumBytes is in SWI area, or u16DstAddr is not 4-Byte-aligned

FLASH_HW_ERROR If there was an error during writing operation

OK if the process was successful

Note:

You can use this function only if you are absolutly sure the location you are writing to was never written before (after an erase)! Otherwise it may happen that flash will be corrupted!

When receiving or sending an UART or radio telegram and simultaneously writing in FLASH memory the effect could be:

• corrupt UART telegram receiving
• corrupt radio telegram receiving
• wrong sub telegram timing for radio telegrams

When writing to FLASH the bootloader is called. The *pu8SrcAddr must reside in the XDATA!

Minimum amount of writing is 4 bytes. The destination address has to be 4 byte alligned.

Be sure XTAL is running when calling this function. When running with CRCO the duration of the flash write can take longer. Therfore be sure to keep a shadow register for the area you will to write in the XDATA.

Keep in mind that when writing to the FLASH all the interrupts are disabled. Therfore it is not possible to receive telegrams from radio or uart.

Note when writing to FLASH let's say 512 bytes it takes more about 25 ms time. The system schedule has 1ms takt but the interrupts are switched off during flash write and with them also the schedule timer. Therfore all the SW timer and also the system timer will be unprecise. This has also influence on subtelegram timing!

Avoid writing too often to FLASH. The FLASH memories has a limited lifecycle and accesing them needs lot of system resources (critical from power or timing point of view)

When writing to FLASH_PRG be sure to store data beyond the program area. You can get the size of your program in number of flash pages by calling mem_getDataAddr, mem_getPrgSize macro

The writing routine does not verify the bytes written in the flash. In a critical application the application should compare the data written to the flash with the data residing in RAM.

See also:

mem_writeFlashNoErase, mem_writeFlash, mem_readFlash, mem_getDataAddr, mem_getPrgSize, flash_arch

RETURN_TYPE mem_writeRAM0	(	uint8 *	pu8SrcAddr,
		uint8	u8DstAddr,
		uint8	u8NumBytes
	)

Takes the u8NumBytes bytes from the address pointing to by pu8SrcAddr and copies them to the RAM0 (PRAM) memory.

Parameters:

[in]	*pu8SrcAddr	Pointer to the bytes source addresses.
[in]	u8DstAddr	Destination memory address (0x00 - 0x1F).
[in]	u6NumBytes	Number of bytes to copy (1..32)

Returns:

ADDR_OUT_OF_MEM If the address is out of memory range

OK If the process was succesfull

See also:

mem_readRAM0

RETURN_TYPE mem_readFlash	(	uint8 xdata *	pu8DstAddr,
		uint16	u16SrcAddr,
		uint16	u16NumBytes
	)

Reads values from a FLASH memory and places them to an XDATA buffer defined by u8DstAddr.
Note: The destination buffer must be located in XDATA.

Parameters:

[out]	*pu8DstAddr	Pointer to the byte where the information is to be stored
[in]	u16SrcAddr	Source memory address PRG_AREA: 0x0000 - 0xFDFF
[in]	u8NumBytes	Number of bytes to read

Returns:

OK always

Note:

It is not possible to read the MOD area with this function. To read it use the MOD_AREA union.

You can't use this function in the callback functions. To read from flash in a callback use CBYTE or CWORD macro from Keil

See also:

mem_writeFlash, mem_readFlash, mem_getDataAddr, mem_getPrgSize, flash_arch

RETURN_TYPE mem_readRAM0	(	uint8 *	pu8DstAddr,
		uint8	u8SrcAddr,
		uint8	u8NumBytes
	)

Reads values from a RAM0 (PRAM) memory and places them to a buffer defined by u16DstAddr.

Parameters:

[out]	*pu8DstAddr	Pointer to the byte where the information is to be stored
[in]	u8SrcAddr	Source memory address (0x00 - 0x1F)
[in]	u6NumBytes	Number of bytes to copy (1..32)

Returns:

ADDR_OUT_OF_MEM If the address is out of memory range

OK If the process was succesfull

Note:

After power-up or if the VDD drops below VOFF the RAM0 contents is undefined!

See also:

mem_writeRAM0

RETURN_TYPE mem_flashBist

(

)

Performs a built in self test (BIST) on the flash program area. The test calculates a CRC value on the program using the program size byte in the CFG_AREA. The result is compared with the CRC stored in the last byte of the last page of the program = PrgArea[u8PrgSize*256-1]. With the help of this BIST the corruption of the flash can be detected.

Parameters:

-

Returns:

OK BIST was succesfull

BIST_FAILED BIST has failed

Note:

The CRC is calculated only on the flash pages where the program is stored not on the data following the program flash pages. The information how big is the program is stored in the CFG_AREA u8PrgSize variable and can be read out using the macro mem_getPrgSize.

The BIST CRC is stored in the last page and last byte of the program. To calculate the BIST for your program you must yous the EOPX postbuild tool. See DolphinV4 API Configurator manual for more information.

See also:

flash_arch

RETURN_TYPE mem_readEEPROM	(	uint8 xdata *	pu8DstAddr,
		uint16	u16SrcAddr,
		uint8	u8NumBytes
	)

Reads values from an external EEPROM memory and places them to an XDATA buffer defined by pu8DstAddr.
Note: The destination buffer must be located in XDATA.

Parameters:

[out]	*pu8DstAddr	Pointer to the byte where the information is to be stored
[in]	u16SrcAddr	Source memory address inside EEPROM
[in]	u8NumBytes	Number of bytes to read

Returns:

OK Read successful

ADDR_OUT_OF_MEM Address out of memory of EEPROM

NOT_POSSIBLE EEPROM does not response

Note:

This function does only support EEPROM type 24AA08 from Microchip or compatible

Use SCLKDIO_1 for SCL and SCSEDIO_0 for SDA. Be sure both pins are configured as input pull up.

You can't use this function in the callback functions.

See also:

mem_writeEEPROM

RETURN_TYPE mem_writeEEPROM	(	uint8 xdata *	pu8SrcAddr,
		uint16	u16DstAddr,
		uint8	u8NumBytes
	)

Takes the u8NumBytes bytes from the XDATA address pointing to by pu8SrcAddr and copies them to an external EEPROM memory.

Parameters:

[in]	*pu8SrcAddr	Pointer to the bytes source, (only XDATA allowed)
[in]	u16DstAddr	Destination memory address inside EEPROM
[in]	u8NumBytes	Number of bytes to copy

Returns:

OK Writing successfull

ADDR_OUT_OF_MEM Address out of memory of EEPROM

NOT_POSSIBLE EEPROM does not response

Note:

This function does only support EEPROM type 24AA08 from Microchip or compatible

Use SCLKDIO_1 for SCL and SCSEDIO_0 for SDA. Be sure both pins are configured as input pull up.

You can't use this function in the callback functions.

The writing routine does not verify the bytes written in the EEPROM. In a critical application the application should compare the data written to the EEPROM with the data residing in RAM.

Function will not write for security reasons if Vdd<Von

See also:

mem_readEEPROM