CMSIS-Pack: Algorithm Functions

| CMSIS-Pack Version 1.6.0 Delivery Mechanism for Software Packs

- Main Page
- Usage and Description

All Pages
Algorithm Functions

Blank Check

The following functions are available for creating new Flash programming algorithms:

Function Name | Indication | Description
--- | --- | ---
BlankCheck | optional | Check and compare patterns.
EraseChip | optional | Delete entire Flash memory content.
EraseSector | mandatory | Delete Flash memory content of a specific sector.
Init | mandatory | Initialize and prepare device for Flash programming.
ProgramPage | mandatory | Write the application into the Flash memory.
UnInit | mandatory | De-initialize the microcontroller after one of the Flash programming steps.
Verify | optional | Compare Flash memory content with the program code.

The following diagrams show how the functions of the Flash Programming Algorithms are executed by a development tool.

The Flash Erase sequence is executed to erase the Flash content.

Flash Erase

The Flash Program sequence is executed to program the Flash memory.

Flash Program

The Flash Verify sequence is executed to verify the content after flash programming.

Flash Verify

# BlankCheck

int BlankCheck (unsigned long adr, unsigned long sz, unsigned char pat);

Parameters

  adr | Block start address
  sz | Block size in bytes
  pat | Pattern to compare

Returns
  status information:
  - 0 when the block content is equal to the pattern pat.
  - 1 when the block content differs from the pattern pat.

The function BlankCheck can be used to check whether the specified block is empty, or whether the content is equal to a specific pattern defined in the argument pat.

The argument adr specifies the start address of the block that is to be verified.

The argument sz specifies the size of the block that is to be verified.

Code Example

int BlankCheck (unsigned long adr, unsigned long sz, unsigned char pat) {
unsigned long i, j, k;
// Recalculate address for External SDRAM addresses
if (adr >= SDRAM_START)
adr = adr - SDRAM_START + USER_OFFSET;
for (i = 0; i < sz; i += 256) {
// Read 256 bytes
ReadPage_HW (adr+i, 256, &rd_buf[0]);
// Determine size to compare
if ((sz-i) >= 256) k = 256;
else k = (sz-i);
// Check up to 256 bytes if equal to pattern "pat"
for (j = 0; j < k; j++)
if (rd_buf[j] != pat) return (1); // Memory is not blank
}
return (0); // Memory is blank
}

# EraseChip

int EraseChip (void);

Returns
  status information:
  - 0 on success.
  - 1 on failure.

The function EraseChip deletes the content of the entire Flash memory. It is invoked whenever the uVision menu Flash - Erase is used, or whenever an attempt is made to download the program to Flash and the option Erase Full Chip has been set in the Flash Download Setup dialog. If this function is missing in the Flash Programming Algorithm, the EraseSector function is executed until the entire content of the Flash memory area has been deleted.

Code Example

int EraseChip (void) {
FLASH->CR |= FLASH_MER; // Mass Erase Enabled
FLASH->CR |= FLASH_STRT; // Start Erase
while (FLASH->SR & FLASH_BSY) {
IWDG->KR = 0xAAAA; // Reload IWDG
}
FLASH->CR &= ~FLASH_MER; // Mass Erase Disabled
return (0); // Done
}

# EraseSector

int EraseSector (unsigned long adr);

Parameters

  adr | Sector address

Returns
  status information:
  - 0 on success.
  - 1 on failure.

The function EraseSector deletes the content of the sector starting at the address specified by the argument adr. The function is invoked whenever the uVision menu Flash - Erase is used, or whenever an attempt is made to download the program to Flash and the option Erase Sectors has been set in the Flash Download Setup dialog.

Code Example

int EraseSector (unsigned long adr) {
FLASH->CR |= FLASH_PER; // Page Erase Enabled
FLASH->AR = adr; // Page Address
FLASH->CR |= FLASH_STRT; // Start Erase
while (FLASH->SR & FLASH_BSY) {
IWDG->KR = 0xAAAA; // Reload IWDG
}
FLASH->CR &= ~FLASH_PER; // Page Erase Disabled
return (0); // Done
}

# Init

int Init (unsigned long adr, unsigned long clk, unsigned long fnc);

Parameters

  adr | Device base address
  clk | Clock frequency (Hz)
  fnc | Function code

Returns
  status information:
  - 0 on success.
  - 1 on failure.

The function Init initializes the microcontroller for Flash programming. It is invoked whenever an attempt is made to download the program to Flash.

The argument adr specifies the base address of the device.

The argument clk specifies the clock frequency for prgramming the device.

The argument fnc is a number:

- 1 stands for Erase.
- 2 stands for Program.
- 3 stands for Verify.

Thus, different initialization sections can be implemented for each individual Flash programming step.

Code Example

int Init (unsigned long adr, unsigned long clk, unsigned long fnc) {
// Zero Wait State
FLASH->ACR = 0x00000000;
// Unlock Flash
FLASH->KEYR = FLASH_KEY1;
FLASH->KEYR = FLASH_KEY2;
// Test if IWDG is running (IWDG in HW mode)
if ((FLASH->OBR & 0x04) == 0x00) {
// Set IWDG time out to ~32.768 second
IWDG->KR = 0x5555; // Enable write access to IWDG_PR and IWDG_RLR
IWDG->PR = 0x06; // Set prescaler to 256
IWDG->RLR = 4095; // Set reload value to 4095
}
return (0);
}

# ProgramPage

int ProgramPage (unsigned long adr, unsigned long sz, unsigned char *buf);

Parameters

  adr | Page start address
  sz | Page size
  buf | Data to be written

Returns
  status information:
  - 0 on success.
  - 1 on failure.

The function ProgramPage is used to write code into the Flash memory. It is invoked to download a program to Flash. As Flash memory is typically organized in blocks or pages, the parameters to the function ProgramPage must not cross alignment boundaries of these flash pages. The page size is specified in the struct FlashDevice with the value Program Page Size.

The argument adr specifies the start address of the page that is to be programmed. It is aligned by the host programming system to a start address of a flash page.

The argument sz specifies the data size in the data buffer. The host programming system ensures that page boundaries are not crossed.

The argument buf points to the data buffer containing the data to be programmed.

Note
  The host programming system ensures that the argument adr + sz never crosses any page boundary. The function ProgramPage does therefore not require any provisions for that.

Code Example

int ProgramPage (unsigned long adr, unsigned long sz, unsigned char *buf) {
sz = (sz + 1) & ~1; // Adjust size for Half Words
while (sz) {
FLASH->CR |= FLASH_PG; // Programming Enabled
M16(adr) = *((unsigned short *)buf); // Program Half Word
while (FLASH->SR & FLASH_BSY);
FLASH->CR &= ~FLASH_PG; // Programming Disabled
// Check for Errors
if (FLASH->SR & (FLASH_PGERR | FLASH_WRPRTERR)) {
FLASH->SR |= FLASH_PGERR | FLASH_WRPRTERR;
return (1); // Failed
}
// Go to next Half Word
adr += 2;
buf += 2;
sz -= 2;
}
return (0); // Done
}

# UnInit

int UnInit (unsigned long fnc);

Parameters

  fnc | Function code

Returns
  status information:
  - 0 on success.
  - 1 on failure.

The function UnInit de-initializes the microcontroller and is invoked at the end of an erasing, programming, or verifying step.

The argument fnc is a number:

- 1 stands for Erase.
- 2 stands for Program.
- 3 stands for Verify.

Thus, different de-initialization sections can be implemented for each individual Flash programming step.

Code Example

int UnInit (unsigned long fnc) {
// Lock Flash
FLASH->CR |= FLASH_LOCK;
return (0);
}

# Verify

unsigned long Verify (unsigned long adr, unsigned long sz, unsigned char *buf);

Parameters

  adr | Start address
  sz | Size in bytes
  buf | Data to be compared

Returns
  status information:
  - the sum of (adr+sz) - on success.
  - any other number - on failure, and represents the failing address.

The function Verify compares the content of the Flash memory with the program code *buf.

The argument adr specifies the start address for the verification.

The argument sz specifies the size of the verification.

The argument buf points to the buffer containing the data to be verified.

Code Example

unsigned long Verify (unsigned long adr, unsigned long sz, unsigned char *buf) {
unsigned long i, adr_dest, in_page_ofs;
if (adr < block_size) { // Verifying 2-nd level bootloader data
adr_dest = adr + page_usr_size; // skip page 0 of block 0
} else { // Verifying program data
FindBlock(adr, 0);
adr_dest = nand_block_offset + (adr & (block_size-1));
}
in_page_ofs = adr_dest & (page_usr_size-1);
if (ReadPage_HW(adr_dest, page_usr_size, data_buf)) return (1);
for (i=0; i<sz; i++)
if (buf[i] != data_buf[i+in_page_ofs])
break;
return (adr+i);
}