3.9 Flash Driver

Overview

The Flash Driver helps the users to generate the Flash driver code. It provides the users easy to use Flash read, write and erase API's along with the required helper functions.

Note: Non-Blocking flash driver is applicable to devices with dual flash panels. CPU does not stall when programming the inactive partition, Non blocking drivers takes the advantage of this.

3.9.1 Module Documentation

3.9.1.1 Flash Driver

FLASH Driver using dsPIC MCUs.

3.9.1.1.1 Module description

FLASH Driver using dsPIC MCUs.

Data structures

struct FLASH_INTERFACE

Structure containing the function pointers of FLASH driver.

Definitions

#define FLASH_ADDRESS_MASK 4U

Defines FLASH odd address mask value.
#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key.
#define FLASH_PAGE_ERASE_OPCODE 0x4003

Defines FLASH page erase opcode.
#define FLASH_WORD_WRITE_OPCODE 0x4001

Defines FLASH word write opcode.
#define FLASH_ROW_WRITE_OPCODE 0x4002

Defines FLASH word write opcode.
#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 512U

Defines FLASH flash page size.
#define FLASH_ERASE_PAGE_MASK (~(FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS - 1U))

Defines FLASH erase page mask.

Enumerations

enum FLASH_PANEL { FLASH_PANEL_1 = 0, FLASH_PANEL_2 = 1, FLASH_PANEL_MAX_PANELS }

This enum is be used for the flash panel numbers and maximum flash panels.
enum FLASH_RETURN_STATUS { FLASH_NO_ERROR, FLASH_INVALID_ADDRESS, FLASH_INVALID_DATA, FLASH_WRITE_ERROR, FLASH_READ_ERROR, FLASH_ERASE_ERROR, FLASH_INVALID_CALLBACK_HANDLER, FLASH_OP_BUSY, FLASH_OP_IN_PROGRESS, FLASH_INVALID_KEY, FLASH_INVALID_OEPRATION, FLASH_SECURITY_ACCESS_CONTROL_ERROR, FLASH_PANEL_CONTROL_LOGIC_ERROR, FLASH_ROW_OP_SYSTEM_BUS_ERROR, FLASH_ROW_OP_WARM_RESET_ERROR }

This enum is be used to return the status of write, read and erase operation.

Functions

enum FLASH_RETURN_STATUS FLASH_PageErase (flash_adr_t flashAddress, flash_key_t unlockKey)

This function erases a page.
enum FLASH_RETURN_STATUS FLASH_WordWrite (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey)

This function writes the specified data to the specified address.
enum FLASH_RETURN_STATUS FLASH_RowWrite (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey)

This function writes the specified data to the specified address.
enum FLASH_RETURN_STATUS FLASH_Read (flash_adr_t flashAddress, size_t count, flash_data_t *data)

This function reads the data from the specified address.
uint16_t FLASH_ErasePageOffsetGet (flash_adr_t flashAddress)

This function returns the offest from page start.
uint32_t FLASH_ErasePageAddressGet (flash_adr_t flashAddress)

This function returns the offest from page start.

Variables

const struct FLASH_INTERFACE flash

Structure object of type FLASH_INTERFACE assigned with name displayed in the Melody Driver User interface. A structure pointer can be used to achieve portability across the FLASH having same interface structure.

3.9.1.1.2 Definition Documentation

FLASH_ADDRESS_MASK

#define FLASH_ADDRESS_MASK 4U

Defines FLASH odd address mask value.

FLASH_ERASE_PAGE_MASK

#define FLASH_ERASE_PAGE_MASK (~(FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS - 1U))

Defines FLASH erase page mask.

FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS

#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 512U

Defines FLASH flash page size.

FLASH_PAGE_ERASE_OPCODE

#define FLASH_PAGE_ERASE_OPCODE 0x4003

Defines FLASH page erase opcode.

FLASH_ROW_WRITE_OPCODE

#define FLASH_ROW_WRITE_OPCODE 0x4002

Defines FLASH word write opcode.

FLASH_UNLOCK_KEY

#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key.

FLASH_WORD_WRITE_OPCODE

#define FLASH_WORD_WRITE_OPCODE 0x4001

Defines FLASH word write opcode.

3.9.1.1.3 Function Documentation

FLASH_ErasePageAddressGet()

uint32_t FLASH_ErasePageAddressGet (flash_adr_t flashAddress)

This function returns the offest from page start.

Parameters:
in	flashAddress	: Flash address

Returns:
FLASH_RETURN_STATUS: returns page start address for the given address

FLASH_ErasePageOffsetGet()

uint16_t FLASH_ErasePageOffsetGet (flash_adr_t flashAddress)

This function returns the offest from page start.

Parameters:
in	flashAddress	: Flash address

Returns:
FLASH_RETURN_STATUS: returns the flash offset from page start address

FLASH_PageErase()

enum FLASH_RETURN_STATUS FLASH_PageErase (flash_adr_t flashAddress, flash_key_t unlockKey)

This function erases a page.

Parameters:
in	flashAddress	: Flash address
in	unlockKey	: Pointer of the data to be written

Returns:
FLASH_RETURN_STATUS: returns FLASH_NO_ERROR if operation is successful , else returns errors like FLASH_INVALID_ADDRESS, FLASH_WRITE_ERROR

FLASH_Read()

enum FLASH_RETURN_STATUS FLASH_Read (flash_adr_t flashAddress, size_t count, flash_data_t * data)

This function reads the data from the specified address.

Parameters:
in	flashAddress	: Flash address
out	data	: Pointer to read the data

Returns:
FLASH_RETURN_STATUS: returns FLASH_NO_ERROR if operation is successful , else returns errors like FLASH_INVALID_ADDRESS, FLASH_INVALID_DATA

FLASH_RowWrite()

enum FLASH_RETURN_STATUS FLASH_RowWrite (flash_adr_t flashAddress, flash_data_t * data, flash_key_t unlockKey)

This function writes the specified data to the specified address.

Parameters:
in	flashAddress	: Flash address
in	data	: Pointer of the data to be written

Returns:
FLASH_RETURN_STATUS: returns FLASH_NO_ERROR if operation is successful , else returns errors like FLASH_INVALID_ADDRESS, FLASH_INVALID_DATA, FLASH_WRITE_ERROR

FLASH_WordWrite()

enum FLASH_RETURN_STATUS FLASH_WordWrite (flash_adr_t flashAddress, flash_data_t * data, flash_key_t unlockKey)

This function writes the specified data to the specified address.

Parameters:
in	flashAddress	: Flash address
in	data	: Pointer of the data to be written. This will write the 4 WORDS pointed to by the pointer.

Returns:
FLASH_RETURN_STATUS: returns FLASH_NO_ERROR if operation is successful , else returns errors like FLASH_INVALID_ADDRESS, FLASH_INVALID_DATA, FLASH_WRITE_ERROR

3.9.1.1.4 Enumeration Type Documentation

FLASH_PANEL

enum FLASH_PANEL

This enum is be used for the flash panel numbers and maximum flash panels.


FLASH_PANEL_1
FLASH_PANEL_2
FLASH_PANEL_MAX_PANELS

FLASH_RETURN_STATUS

enum FLASH_RETURN_STATUS

This enum is be used to return the status of write, read and erase operation.


FLASH_NO_ERROR	No error occurred
FLASH_INVALID_ADDRESS	Invalid address
FLASH_INVALID_DATA	Invalid data
FLASH_WRITE_ERROR	Write error has occurred
FLASH_READ_ERROR	Read error has occurred
FLASH_ERASE_ERROR	Flash erase error occurred
FLASH_INVALID_CALLBACK_HANDLER	Invalid parameter to operation
FLASH_OP_BUSY	Flash is physically busy
FLASH_OP_IN_PROGRESS	Flash operation is in progress
FLASH_INVALID_KEY	Invalid NVM unlock Key
FLASH_INVALID_OEPRATION	Invalid program/erase operation (PROGOP)
FLASH_SECURITY_ACCESS_CONTROL_ERROR	Flash Security access control violation
FLASH_PANEL_CONTROL_LOGIC_ERROR	Error reported by flash panel control logic
FLASH_ROW_OP_SYSTEM_BUS_ERROR	Flash System bus error during row operation
FLASH_ROW_OP_WARM_RESET_ERROR	Row programming operation not completed due to warm reset

3.9.1.1.5 Variable Documentation

flash

const struct FLASH_INTERFACE flash

Structure object of type FLASH_INTERFACE assigned with name displayed in the Melody Driver User interface. A structure pointer can be used to achieve portability across the FLASH having same interface structure.

3.9.2 Data Structure Documentation

3.9.2.1 FLASH_INTERFACE Struct Reference

Structure containing the function pointers of FLASH driver.

3.9.2.1.1 Detailed Description

Structure containing the function pointers of FLASH driver.

#include <flash_interface.h>

Data Fields

enum FLASH_RETURN_STATUS(* PageErase )(flash_adr_t address, flash_key_t unlockKey)

Pointer to FLASH_PageErase e.g. FLASH_PageErase.
enum FLASH_RETURN_STATUS(* Write )(flash_adr_t address, flash_data_t *data, flash_key_t unlockKey)

Pointer to FLASH_WordWrite e.g. FLASH_WordWrite.
enum FLASH_RETURN_STATUS(* RowWrite )(flash_adr_t address, flash_data_t *data, flash_key_t unlockKey)

Pointer to FLASH_RowWrite e.g. FLASH_RowWrite.
enum FLASH_RETURN_STATUS(* Read )(flash_adr_t address, size_t count, uint32_t *data)

Pointer to FLASH_Read e.g. FLASH_Read.
uint32_t(* PageAddressGet )(flash_adr_t address)

Pointer to FLASH_ErasePageAddressGet e.g. FLASH_ErasePageAddressGet.
uint16_t(* PageOffsetGet )(flash_adr_t address)

Pointer to FLASH_ErasePageOffsetGet e.g. FLASH_ErasePageOffsetGet.
enum FLASH_RETURN_STATUS(* OperationStatusGet )(void)

Pointer to FLASH_OperationStatusGet e.g. FLASH_OperationStatusGet.
enum FLASH_RETURN_STATUS(* NonBlockingPageErase )(flash_adr_t address, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

Pointer to FLASH_NonBlockingPageErase e.g. FLASH_NonBlockingPageErase.
enum FLASH_RETURN_STATUS(* NonBlockingBulkErase )(enum FLASH_PANEL panel, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

Pointer to FLASH_NonBlockingBulkErase e.g. FLASH_NonBlockingBulkErase.
enum FLASH_RETURN_STATUS(* NonBlockingWordWrite )(flash_adr_t address, flash_data_t *data, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

Pointer to FLASH_NonBlockingWordWrite e.g. FLASH_NonBlockingWordWrite.
enum FLASH_RETURN_STATUS(* NonBlockingRowWrite )(flash_adr_t address, flash_data_t *data, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

Pointer to FLASH_NonBlockingRowWrite e.g. FLASH_NonBlockingRowWrite.
enum FLASH_RETURN_STATUS(* NonBlockingRead )(flash_adr_t address, size_t count, uint32_t *data)

Pointer to FLASH_NonBlockingRead e.g. FLASH_NonBlockingRead.
enum FLASH_RETURN_STATUS(* NonBlockingPolledPageErase )(flash_adr_t address, flash_key_t unlockKey)

Pointer to FLASH_NonBlockingPolledPageErase e.g. FLASH_NonBlockingPolledPageErase.
enum FLASH_RETURN_STATUS(* NonBlockingPolledBulkErase )(enum FLASH_PANEL panel, flash_key_t unlockKey)

Pointer to FLASH_NonBlockingPolledBulkErase e.g. FLASH_NonBlockingPolledBulkErase.
enum FLASH_RETURN_STATUS(* NonBlockingPolledWordWrite )(flash_adr_t address, flash_data_t *data, flash_key_t unlockKey)

Pointer to FLASH_NonBlockingPolledWordWrite e.g. FLASH_NonBlockingPolledWordWrite.
enum FLASH_RETURN_STATUS(* NonBlockingPolledRowWrite )(flash_adr_t address, flash_data_t *data, flash_key_t unlockKey)

Pointer to FLASH_NonBlockingPolledRowWrite e.g. FLASH_NonBlockingPolledRowWrite.
enum FLASH_RETURN_STATUS(* NonBlockingPolledRead )(flash_adr_t address, size_t count, uint32_t *data)

Pointer to FLASH_NonBlockingPolledRead e.g. FLASH_NonBlockingPolledRead.

3.9.2.1.2 Field Documentation

The documentation for this struct was generated from the following file:

source/

flash_interface.h

NonBlockingBulkErase

enum FLASH_RETURN_STATUS(* NonBlockingBulkErase) (enum FLASH_PANEL panel, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

Pointer to FLASH_NonBlockingBulkErase e.g. FLASH_NonBlockingBulkErase.

NonBlockingPageErase

enum FLASH_RETURN_STATUS(* NonBlockingPageErase) (flash_adr_t address, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

Pointer to FLASH_NonBlockingPageErase e.g. FLASH_NonBlockingPageErase.

NonBlockingPolledBulkErase

enum FLASH_RETURN_STATUS(* NonBlockingPolledBulkErase) (enum FLASH_PANEL panel, flash_key_t unlockKey)

Pointer to FLASH_NonBlockingPolledBulkErase e.g. FLASH_NonBlockingPolledBulkErase.

NonBlockingPolledPageErase

enum FLASH_RETURN_STATUS(* NonBlockingPolledPageErase) (flash_adr_t address, flash_key_t unlockKey)

Pointer to FLASH_NonBlockingPolledPageErase e.g. FLASH_NonBlockingPolledPageErase.

NonBlockingPolledRead

enum FLASH_RETURN_STATUS(* NonBlockingPolledRead) (flash_adr_t address, size_t count, uint32_t *data)

Pointer to FLASH_NonBlockingPolledRead e.g. FLASH_NonBlockingPolledRead.

NonBlockingPolledRowWrite

enum FLASH_RETURN_STATUS(* NonBlockingPolledRowWrite) (flash_adr_t address, flash_data_t *data, flash_key_t unlockKey)

Pointer to FLASH_NonBlockingPolledRowWrite e.g. FLASH_NonBlockingPolledRowWrite.

NonBlockingPolledWordWrite

enum FLASH_RETURN_STATUS(* NonBlockingPolledWordWrite) (flash_adr_t address, flash_data_t *data, flash_key_t unlockKey)

Pointer to FLASH_NonBlockingPolledWordWrite e.g. FLASH_NonBlockingPolledWordWrite.

NonBlockingRead

enum FLASH_RETURN_STATUS(* NonBlockingRead) (flash_adr_t address, size_t count, uint32_t *data)

Pointer to FLASH_NonBlockingRead e.g. FLASH_NonBlockingRead.

NonBlockingRowWrite

enum FLASH_RETURN_STATUS(* NonBlockingRowWrite) (flash_adr_t address, flash_data_t *data, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

Pointer to FLASH_NonBlockingRowWrite e.g. FLASH_NonBlockingRowWrite.

NonBlockingWordWrite

enum FLASH_RETURN_STATUS(* NonBlockingWordWrite) (flash_adr_t address, flash_data_t *data, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

Pointer to FLASH_NonBlockingWordWrite e.g. FLASH_NonBlockingWordWrite.

OperationStatusGet

enum FLASH_RETURN_STATUS(* OperationStatusGet) (void)

Pointer to FLASH_OperationStatusGet e.g. FLASH_OperationStatusGet.

PageAddressGet

uint32_t(* PageAddressGet) (flash_adr_t address)

Pointer to FLASH_ErasePageAddressGet e.g. FLASH_ErasePageAddressGet.

PageErase

enum FLASH_RETURN_STATUS(* PageErase) (flash_adr_t address, flash_key_t unlockKey)

Pointer to FLASH_PageErase e.g. FLASH_PageErase.

PageOffsetGet

uint16_t(* PageOffsetGet) (flash_adr_t address)

Pointer to FLASH_ErasePageOffsetGet e.g. FLASH_ErasePageOffsetGet.

Read

enum FLASH_RETURN_STATUS(* Read) (flash_adr_t address, size_t count, uint32_t *data)

Pointer to FLASH_Read e.g. FLASH_Read.

RowWrite

enum FLASH_RETURN_STATUS(* RowWrite) (flash_adr_t address, flash_data_t *data, flash_key_t unlockKey)

Pointer to FLASH_RowWrite e.g. FLASH_RowWrite.

Write

enum FLASH_RETURN_STATUS(* Write) (flash_adr_t address, flash_data_t *data, flash_key_t unlockKey)

Pointer to FLASH_WordWrite e.g. FLASH_WordWrite.

3.9.3 File Documentation

3.9.3.1 source/flash.h File Reference

FLASH driver using dsPIC MCUs.

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include "flash_interface.h"

3.9.3.1.1 Functions

enum FLASH_RETURN_STATUS FLASH_PageErase (flash_adr_t flashAddress, flash_key_t unlockKey)

This function erases a page.
enum FLASH_RETURN_STATUS FLASH_WordWrite (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey)

This function writes the specified data to the specified address.
enum FLASH_RETURN_STATUS FLASH_RowWrite (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey)

This function writes the specified data to the specified address.
enum FLASH_RETURN_STATUS FLASH_Read (flash_adr_t flashAddress, size_t count, flash_data_t *data)

This function reads the data from the specified address.
uint16_t FLASH_ErasePageOffsetGet (flash_adr_t flashAddress)

This function returns the offest from page start.
uint32_t FLASH_ErasePageAddressGet (flash_adr_t flashAddress)

This function returns the offest from page start.

3.9.3.1.2 Variables

const struct FLASH_INTERFACE flash

Structure object of type FLASH_INTERFACE assigned with name displayed in the Melody Driver User interface. A structure pointer can be used to achieve portability across the FLASH having same interface structure.

3.9.3.1.3 Detailed Description

FLASH driver using dsPIC MCUs.

FLASH Generated Driver Header File

3.9.3.2 source/flash_interface.h File Reference

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "flash_types.h"

3.9.3.2.1 Data structures

struct FLASH_INTERFACE

Structure containing the function pointers of FLASH driver.

3.9.3.2.2 Detailed Description

flash Generated Driver Interface Header File

3.9.3.3 source/flash_types.h File Reference

FLASH Driver using dsPIC MCUs.

3.9.3.3.1 Macros

#define FLASH_ADDRESS_MASK 4U

Defines FLASH odd address mask value.
#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key.
#define FLASH_PAGE_ERASE_OPCODE 0x4003

Defines FLASH page erase opcode.
#define FLASH_WORD_WRITE_OPCODE 0x4001

Defines FLASH word write opcode.
#define FLASH_ROW_WRITE_OPCODE 0x4002

Defines FLASH word write opcode.
#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 512U

Defines FLASH flash page size.
#define FLASH_ERASE_PAGE_MASK (~(FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS - 1U))

Defines FLASH erase page mask.