STMicroelectronics C55 User Manual

UM2636

User manual

Standard Software Driver for C55 Flash module embedded

on SPC58 B, C, E, H, G and N lines microcontroller

Introduction

The standard software driver (SSD) is a set of APIs that enable user applications to operate on the Flash module embedded on a microcontroller. The C55 SSD contains a set of functions which allow to program/erase a single C55 Flash module.

The C55 standard software driver provides the following APIs:

• FlashInit

• FlashErase

• FlashEraseAlternate

• BlankCheck

• FlashProgram

• ProgramVerify

• CheckSum

• FlashCheckStatus

• FlashSuspend

• FlashResume

• GetLock

• SetLock

• OverPgmProtGetStatus

• FlashArrayIntegrityCheck

• FlashArrayIntegritySuspend

• FlashArrayIntegrityResume

• UserMarginReadCheck

UM2636 - Rev 1 - May 2020 For further information contact your local STMicroelectronics sales office.

www.st.com

1 Overview

This document is the user manual for the standard software driver (SSD) for single C55 Flash module. The roadmap for the document is the following.

Section 1.1 Features lists the features of the driver.

Section 2 API specifications describes the API specifications. This section includes many sub-sections which

describe the different aspects of the driver.

• Section 2.1 General overview provides a general overview of the driver.

• Section 2.2 General type definitions provides the type definitions used for the driver.

• Section 2.3 SSD configuration parameters reports the driver configuration parameters.

• Section 2.4 Context data structure and Section 2.5 Other data structures describe the data context structure and provide some other data structures used in this driver.

• Section 2.6 Return codes provides return code information.

• Section 2.7 Normal mode functions and Section 2.8 User Test Mode Functions provide the detailed description of the standard software Flash driver APIs for the normal mode and the user's test mode respectively.

Section A.1 System requirements details the system requirements for the driver development. Section B.1 Acronyms lists the acronyms used in the present document. Section C.1 Document reference lists the

reference documents.

UM2636

Overview

1.1 Features

The C55 SSD provides the following features:

• Driver binary built with Variable-Length-Encoding (VLE) instruction set.

• Driver released in binary c-array format to provide compiler-independent support for non-debug-mode embedded applications.

• Driver released in s-record format to provide compiler-independent support for debug-mode/JTAG programming tools.

• Each driver function is independent of each other so the end user can choose the function subset to meet their particular needs.

• Support from word-wise to quad-page-wise programming according to specific hardware feature for fast programming.

• Position-independent and ROM-able

• Ready-to-use demos illustrating the usage of the driver

• Concurrency support via asynchronous design.

UM2636 - Rev 1

page 2/45

2 API specifications

2.1 General overview

The C55 SSD has APIs to handle the erase, program, erase verify and program verify operations on the Flash. Apart from these, it also provides the feature for locking specific blocks and calculating check sum. This SSD also provides four User Test APIs to check the array integrity, perform the user margin read check as well as to suspend/resume these operations. All functions work as an asynchronous model for concurrency event support by invoking the 'FlashCheckStatus' function to track the on-going status of the targeted operation.

2.2 General type definitions

Derived type Size C language type description

BOOL 8-bit unsigned char

INT8 8-bit signed char

VINT8 8-bit volatile signed char

UINT8 8-bit unsigned char

VUINT8 8-bit volatile unsigned char

INT16 16-bit signed short

VINT16 16-bit volatile signed short

UINT16 16-bit unsigned short

VUINT16 16-bit volatile unsigned short

INT32 32-bit signed long

VINT32 32-bit volatile signed long

UINT32 32-bit unsigned long

VUINT32 32-bit volatile unsigned long

UM2636

API specifications

Table 1. Type definitions

UM2636 - Rev 1

page 3/45

2.3 SSD configuration parameters

This section explains the configuration parameters used for the SSD operation. The configuration parameters are handled as structure. The user should correctly initialize the fields including c55RegBase, mainArrayBase, uTestArrayBase, mainInterfaceFlag, programmableSize and BDMEnable before passing the structure to SSD functions. The rest of parameters such as lowBlockInfo, midBlockInfo, highBlockInfo and nLargeBlockNum, are initialized by ‘FlashInit’ automatically and can be used for other purposes of the user’s application.

Table 2. SSD configuration structure field definition

Parameter name Type Parameter description

c55RegBase UINT32 The base address of C55 control registers.

mainArrayBase UINT32 The base address of Flash main array.

lowBlockInfo BLOCK_INFO

midBlockInfo BLOCK_INFO

highBlockInfo BLOCK_INFO

nLargeBlockNum UINT32 Number of blocks of the 256 K address space.

uTestArrayBase UINT32 The base address of the UTest block.

mainInterfaceFlag BOOL The flag to select the main interface or not.

programmableSize UINT32 The maximum programmable size of the C55 Flash according to specific interface.

BDMEnable BOOL

Block info of the low address space. It includes information of this block space based on different block sizes.

Block info of the mid address space. It includes information of this block space based on different block sizes.

Block info of the high address space. It includes information of this block space based on different block sizes.

The debug mode selection. User can enable/disable the debug mode via this input argument.

UM2636

SSD configuration parameters

2.4

The type definition for the structure is given below:

typedef struct _c55_ssd_config { UINT32 c55RegBase; UINT32 mainArrayBase; BLOCK_INFO lowBlockInfo; BLOCK_INFO midBlockInfo; BLOCK_INFO highBlockInfo; UINT32 nLargeBlockNum; UINT32 uTestArrayBase; BOOL mainInterfaceFlag; UINT32 programmableSize; BOOL BDMEnable; } SSD_CONFIG, *PSSD_CONFIG;

Context data structure

The Context data structure is used for storing the context variable values while an operation is in progress. The operations that support asynchronous model may require caching the context data including ‘FlashProgram’, ‘ProgramVerify’, ‘BlankCheck’, ‘CheckSum’, ‘FlashArrayIntegrityCheck’, and ‘UserMarginReadCheck’. The user needs to declare and initialize a context data structure before passing it to the SSD functions mentioned above. Refer to ‘FlashCheckStatus’ to have a quick view of how to initialize the context data. The context data structure contents can be reviewed at anytime during the operation progress (these information may be useful in some cases), but they must not be changed for any reason in order to make the operation complete correctly.

UM2636 - Rev 1

page 4/45

Table 3. Context data structure field definitions

Name Description

dest The context destination address of an operation

size The context size of an operation

source The context source of an operation

pFailedAddress The context failed address of an operation

pFailedData The context failed data of an operation

pFailedSource The context failed source of an operation

pSum The context sum of an operation

pMisr The context MISR values of an operation

pReqCompletionFn Function pointer to the Flash function being checked for status

The type definition for the structure is given below:

typedef struct _c55_context_data { UINT32 dest; UINT32 size; UINT32 source; UINT32 *pFailedAddress; UINT32 *pFailedData; UINT32 *pFailedSource; UINT32 *pSum; MISR *pMisr; void* pReqCompletionFn; } CONTEXT_DATA, *PCONTEXT_DATA;

UM2636

Other data structures

2.5

Other data structures

This section reports some other data structures used for the SSD operation. These are the structures used for variables' declaration in SSD configuration and context data structures or input arguments' declaration in some APIs.

Table 4. Block information structure field definitions

Name Type Definition

n16KBlockNum UINT32 Number of 16K block

n32KBlockNum UINT32 Number of 32K block

n64KBlockNum UINT32 Number of 64K block

n128KBlockNum UINT32 Number of 128K block

The type definition for the structure is given below:

typedef struct _c55_block_info { UINT32 n16KBlockNum; UINT32 n32KBlockNum; UINT32 n64KBlockNum; UINT32 n128KBlockNum; } BLOCK_INFO, *PBLOCK_INFO;

UM2636 - Rev 1

page 5/45

Table 5. 256K block select structure field definitions

Name Type Definition

firstLargeBlockSelect UINT32

secondLargeBlockSelect UINT32

Bit map for the first 32-bit block select (from bit 0 to bit 31) in 256K block space; bit 0 corresponds to the least significant bit and bit 31 corresponds to the most significant bit.

Bit map for the second 32-bit block select (from bit 32 to upper bits) in 256K block space; bit 32 corresponds to the least significant bit and bit 63 corresponds to the most significant bit.

The type definition for the structure is given below:

typedef struct _c55_nLarge_block_sel { UINT32 firstLargeBlockSelect; UINT32 secondLargeBlockSelect; } NLARGE_BLOCK_SEL,*PNLARGE_BLOCK_SEL;

Table 6. MISR structure field definitions

UM2636

Other data structures

Name Type Definition

n = 0, 1, …9

UINT32

Each Wn corresponds to each MISR value provided by the user. The user must provide ten MISR values in total via this structure to perform the user’s test mode functions.

The type definition for the structure is given below:

typedef struct _c55_misr { UINT32 w0; UINT32 w1; UINT32 w2; UINT32 w3; UINT32 w4; UINT32 w5; UINT32 w6; UINT32 w7; UINT32 w8; UINT32 w9; } MISR, *PMISR;

UM2636 - Rev 1

page 6/45

2.6 Return codes

The return code returned to the caller function notifies the success or the errors of the API execution. These are the possible values of the return code:

Name Value Description

C55_OK 0x00000000 The requested operation is successful.

C55_ERROR_ALIGNMENT 0x00000001 Alignment error.

C55_ERROR_ENABLE 0x00000002 Fail to enable the operation.

C55_ERROR_BUSY 0x00000004

C55_ERROR_PGOOD 0x00000008 The program operation is unsuccessful.

C55_ERROR_EGOOD 0x00000010 The erase operation is unsuccessful.

C55_ERROR_NOT_BLANK 0x00000020

C55_ERROR_VERIFY 0x00000040

C55_ERROR_BLOCK_INDICATOR 0x00000080 Invalid block space indicator.

C55_ERROR_ALTERNATE 0x00000100

C55_ERROR_FACTORY_OP 0x00000200 Factory erase/program is locked.

C55_ERROR_MISMATCH 0x00000400

C55_ERROR_NO_BLOCK 0x00000800

C55_ERROR_ADDR_SEQ 0x00001000 Invalid address sequence error.

C55_ERROR_MARGIN_LEVEL 0x00002000 Invalid margin level error.

C55_ERROR_ERASE_OPTION 0x00004000 Invalid erase option.

C55_ERROR_MODE_OP 0x00008000 Invalid mode op.

C55_DONE 0x00010000

C55_INPROGRESS 0x00020000

UM2636

Return codes

Table 7. Return codes

New program/erase cannot be performed while a high-voltage operation is already in progress.

New array integrity cannot be performed while an array integrity is going on.

There is a non-blank Flash memory location within the checked Flash memory region.

There is a mismatch between the source data and the content in the checked Flash memory.

The operation does not support an alternate interface for the specified address space.

In ‘FlashArrayIntegrityCheck’ or ‘UserMarginReadCheck’, the MISR values generated by the hardware do not match the values passed by the user.

In ‘FlashArrayIntegrityCheck’ or ‘UserMarginReadCheck’, no block has been enabled for array integrity check.

The operation has been done and this operation is no more requested on FlashCheckStatus function.

The operation is in progress and the user needs to call the FlashCheckStatus more times to finish this operation.

UM2636 - Rev 1

page 7/45

2.7 Normal mode functions

2.7.1 FlashInit

Description

This function initializes an individual Flash module. It accesses the Flash configuration register and read out the number of blocks for each memory space of single Flash module.

Each time this driver is used, the user must provide the chip-dependent parameters such as c55RegBase, mainArrayBase, uTestArrayBase, mainInterfaceFlag, programmableSize and DBMEnable and the rest of parameters initialized via this function. Those are block information including the number of the block based on the block size for each address space.

Prototype

UINT32 FlashInit (PSSD_CONFIG pSSDConfig);

Arguments

UM2636

Normal mode functions

Table 8. FlashInit

Argument Description Range

pSSDConfig

Pointer to the SSD Configuration Structure.

The values in this structure are chip-dependent. Please refer to Section

2.3 SSD configuration parameters for more details.

Return values

Table 9. Return values for FlashInit

Type

UINT32 Indicates successful completion of operation. C55_OK

Description Possible values

Troubleshooting

None.

Comments

In case that the mainInterfaceFlag is the main interface, ‘FlashInit’ checks the C55_MCR_RWE, C55_MCR_EER and C55_MCR_SBC bits, and then clears them if any of them is set.

This function also clears the PGM and ERS bits in the MCR and MCRA registers respectively if any of them is set.

UM2636 - Rev 1

Assumptions

None.

page 8/45

2.7.2 FlashErase

Description

This function is to perform an erase operation for multi-blocks on a single Flash module according to user’s input arguments via the main interface. The target Flash module status is checked in advance to return relevant error code if any. This function only sets the high voltage without waiting for the operation to be finished. Instead, the user must call the ‘FlashCheckStatus’ function to confirm the successful completion of this operation.

Prototype

UINT32 FlashErase(PSSD_CONFIG pSSDConfig, UINT8 eraseOption, UINT32 lowBlockSelect, UINT32 midBlockSelect, UINT32 highBlockSelect, NLARGE_BLOCK_SEL nLargeBlockSelect

Arguments

UM2636

Normal mode functions

Table 10. Arguments for FlashErase

Argument Description Range

pSSDConfig

eraseOption

lowBlockSelect

midBlockSelect

highBlockSelect

nLargeBlockSelect

Pointer to the SSD Configuration Structure.

The option is to select user’s expected erase operation.

To select the array blocks in low address space for erasing.

To select the array blocks in mid address space for erasing.

To select the array blocks in high address space for erasing.

To select the array blocks in 256K address space for erasing. It includes two elements to decode the first half of 256K block select and the second half of 256K block select.

The values in this structure are chip-dependent. Please refer to Section

2.3 SSD configuration parameters for more details.

The valid value can be:

C55_ERASE_MAIN (0x0)

C55_ERASE_MAIN_FERS (0x1)

C55_ERASE_UTEST (0x2)

C55_ERASE_UTEST_FERS (0x3)

Bit-mapped value which corresponds to LOWSEL of the block select register in which the least significant bit of this argument corresponds to LOWSEL[0]. Select the block to be erased by setting 1 to the appropriate bit of lowBlockSelect. If there is not any block to be erased in the low address space, lowBlockSelect must be set to 0.

Bit-mapped value which corresponds to 256KSEL of the block select register. The first 256K block select corresponds to the first 32 bits (from 0 to 31) of 256KSEL. The second 256K block select corresponds to the rest of 256KSEL bits. Select the block to be erased by setting 1 to the appropriate bit of nLargeBlockSelect. If there is not any block to be erased in the 256K address space, nLargeBlockSelect must be set to 0.

Bit-mapped value such that the least significant bit is at bit 0 of 16K block region (if available), then 32K block region (if available) and lastly 64K block region (if available). Select the block in the high address space to be erased by setting 1 to the appropriate bit of highBlockSelect. If there is not any block to be erased in the high address space, highBlockSelect must be set to 0.

Bit-mapped value such that the least significant bit is at bit 0 of 256K block region (if available). Select the block in the 256K address space to be erased by setting 1 to the appropriate bit of nLargeBlockSelect. If there is not any block to be erased in the 256K address space, nLargeBlockSelect must be set to 0.

UM2636 - Rev 1

page 9/45

Normal mode functions

Return values

Table 11. Return values for FlashErase

Type Description Possible values

C55_OK

C55_ERROR_ERASE_OPTION

UINT32 Successful completion or error value.

C55_ERROR_BUSY

C55_ERROR_FACTORY_OP

C55_ERROR_ENABLE

Troubleshooting

Table 12. Troubleshooting for FlashErase

Error Codes Possible Causes Solution

C55_ERROR_ERASE_OPTION Invalid erase option. Use one of the valid values for the option.

Wait until all previous program/erase operations on the Flash module finish.

Possible cases that erase cannot start are:

1. erase in progress (MCR-ERS is high);

2. program in progress (MCR-PGM is high);

Factory erase is locked by the system due to the data at the UTest NVM ‘diary’ location.

If UT0[UTE] bit is being set, then the erase operation cannot be started. Thus, make sure that the UT0[UTE] is cleared before any erase operation.

C55_ERROR_BUSY

C55_ERROR_FACTORY_OP

C55_ERROR_ENABLE

New erase operation cannot be performed because there is a program/erase sequence in progress on the Flash module.

The factory erase could not be performed.

ERS bit cannot be set correctly.

UM2636

UM2636 - Rev 1

Comments

'FlashErase' always uses the main interface to complete an erase operation and ignores the value of the ‘mainInterfaceFlag’ in the SSD configuration structure. However, it is recommended that the user explicitly sets this flag value to TRUE before calling 'FlashErase'.

The eraseOption input argument provides an option for the user to select the expected erase operation. If the user wants to set a factory erase, he has to select eraseOption as C55_ERASE_MAIN_FERS or C55_ERASE_UTEST_FERS. If the user wants to perform a normal erase operation on the main array, eraseOption must be C55_ERASE_MAIN and lastly, the user must select C55_ERASE_UTEST to make an erase operation on the UTest block.

The factory erase feature can be used to provide a faster erase. But the feature cannot be performed if the data at “diary” location in the UTest NVM space contains at least one zero at reset. In that case, each try to perform factory erase causes the error C55_ERROR_FACTORY_OP to be returned.

The inputs lowBlockSelect, midBlockSelect, highBlockSelect and nLargeBlockSelect are bit-mapped arguments that are used to select the blocks to be erased in the low/mid/high/256K address spaces of main array. The selection of the blocks of the main array is determined by setting/clearing the corresponding bit in lowBlockSelect, midBlockSelect, highBlockSelect or nLargeBlockSelect.

The bit allocations for low/mid/high/first 256K blocks are: the least significant bit corresponds to the least significant bit of LOWSEL/MIDSEL/HIGHSEL/256KSEL in the relevant block select register. The first 256K block select can specify maximum 32 blocks. If there are more than 32 blocks of 256K, the second 256K block select will be used to specify the remaining ones. In this case the least significant bit of the second 256K block corresponds to 256KSEL[32] and so on.

page 10/45

UM2636

Normal mode functions

Table 13. Bit allocation for low block select argument is an example for block allocation and bit map for specific

Flash modules with two blocks for each block size in low, middle or high address space. The invalid blocks are marked as reserved and the number of valid bits may vary according to specific Flash module.

Table 13. Bit allocation for low block select argument

MSB LSB