2.11 Flash Driver

2.11.1 Introduction

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.

2.11.2 Module Documentation

2.11.2.1 Flash Driver

FLASH Driver using dsPIC MCUs.

2.11.2.1.1 Module description

FLASH Driver using dsPIC MCUs.

2.11.2.1.1.1 Data structures

struct FLASH_INTERFACE

Structure containing the function pointers of FLASH driver.

2.11.2.1.1.2 Definitions

#define FLASH_PC_UNIT_SIZE 2U

Defines FLASH Flash PC unit size.
#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key value.
#define FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS 128U

Defines FLASH write row size in instruction counts.
#define FLASH_WRITE_ROW_SIZE_IN_PC_UNITS (FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH write row size in PC counts.
#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 1024U

Defines FLASH erase page size in instruction counts.
#define FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS (FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH erase page size in PC counts.
#define FLASH_HAS_ECC 1

Defines if FLASH has ECC.
#define FLASH_ERASE_PAGE_MASK (~(FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS - 1U))

Defines FLASH erase page mask value.
#define FLASH_ODD_ADDRESS_MASK 1U

Defines FLASH odd address mask value.
#define FLASH_PC_UNIT_SIZE 2U

Defines FLASH Flash PC unit size.
#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key value.
#define FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS 128U

Defines FLASH write row size in instruction counts.
#define FLASH_WRITE_ROW_SIZE_IN_PC_UNITS (FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH write row size in PC counts.
#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 1024U

Defines FLASH erase page size in instruction counts.
#define FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS (FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH erase page size in PC counts.
#define FLASH_HAS_ECC 1

Defines if FLASH has ECC.
#define FLASH_ERASE_PAGE_MASK (~(FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS - 1U))

Defines FLASH erase page mask value.
#define FLASH_ODD_ADDRESS_MASK 1U

Defines FLASH odd address mask value.
#define FLASH_ERROR_MASK 0x2100

Defines FLASH flash error mask value.

2.11.2.1.1.3 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 }

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

2.11.2.1.1.4 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.
bool FLASH_ErasePage (flash_adr_t address, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.
uint32_t FLASH_ReadWord24 (flash_adr_t address)

This routine reads a 24 bit instruction from the indicated address in flash.
uint16_t FLASH_ReadWord16 (flash_adr_t address)

This routine reads a 16 bit instruction from the indicated address in flash.
bool FLASH_WriteDoubleWord24 (flash_adr_t address, flash_data_t Data0, flash_data_t Data1, flash_key_t unlockKey)

This routine writes two 24 bit instructions to the indicated address in flash.
bool FLASH_WriteDoubleWord16 (flash_adr_t flashAddress, uint16_t Data0, uint16_t Data1, flash_key_t unlockKey)

This routine writes two ,16 bit instructions to the indicated address in flash.
bool FLASH_WriteRow24 (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Since the flash is only 24 bits wide all data in the upper 8 bits of the source will be lost.The address in *data must be row aligned.
bool FLASH_WriteRow16 (flash_adr_t address, uint16_t *data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Each 16 bit source data word is stored in the lower 16 bits of each flash entry and the upper 8 bits of the flash is not programmed.The address in *data must be row aligned.
uint16_t FLASH_ErasePageOffsetGet (flash_adr_t address)

This routiner returns the page offset the given flash address.
uint32_t FLASH_ErasePageAddressGet (flash_adr_t address)

This routine returns the page aligned address for a given flash address..
bool FLASH_NonBlockingErasePage (flash_adr_t address, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.
bool FLASH_NonBlockingEraseBulk (uint32_t panel, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.
bool FLASH_NonBlockingWriteDoubleWord24 (flash_adr_t address, flash_data_t Data0, flash_data_t Data1, flash_key_t unlockKey)

This routine writes two 24 bit instructions to the indicated address in flash.
bool FLASH_NonBlockingWriteDoubleWord16 (flash_adr_t flashAddress, uint16_t Data0, uint16_t Data1, flash_key_t unlockKey)

This routine writes two ,16 bit instructions to the indicated address in flash.
bool FLASH_NonBlockingWriteRow24 (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Since the flash is only 24 bits wide all data in the upper 8 bits of the source will be lost.The address in *data must be row aligned.
bool FLASH_NonBlockingWriteRow16 (flash_adr_t address, uint16_t *data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Each 16 bit source data word is stored in the lower 16 bits of each flash entry and the upper 8 bits of the flash is not programmed.The address in *data must be row aligned.
uint32_t FLASH_NonBlockingReadWord24 (flash_adr_t address)

This routine reads a 24 bit instruction from the indicated address in flash.
uint16_t FLASH_NonBlockingReadWord16 (flash_adr_t address)

This routine reads a 16 bit instruction from the indicated address in flash.
void FLASH_Initialize ()

This function initializes the nvm controller.
enum FLASH_RETURN_STATUS FLASH_OperationStatusGet ()

This function gets the status of nvm controller.
enum FLASH_RETURN_STATUS FLASH_NonBlockingPageErase (flash_adr_t flashAddress, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

This function erases a page.
enum FLASH_RETURN_STATUS FLASH_NonBlockingBulkErase (enum FLASH_PANEL panel, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

This function erases a panel.
enum FLASH_RETURN_STATUS FLASH_NonBlockingWordWrite (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void *context)

This function writes the specified data to the specified address.
enum FLASH_RETURN_STATUS FLASH_NonBlockingRowWrite (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey, FLASH_CALLBACK callback, void *context)

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

This function reads the data from the specified address.

2.11.2.1.1.5 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.

2.11.2.1.2 Definition Documentation

2.11.2.1.2.1 FLASH_ERASE_PAGE_MASK[1/2]

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

Defines FLASH erase page mask value.

2.11.2.1.2.2 FLASH_ERASE_PAGE_MASK[1/2]

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

Defines FLASH erase page mask value.

2.11.2.1.2.3 FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS[1/2]

#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 1024U

Defines FLASH erase page size in instruction counts.

2.11.2.1.2.4 FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS[1/2]

#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 1024U

Defines FLASH erase page size in instruction counts.

2.11.2.1.2.5 FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS[1/2]

#define FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS (FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH erase page size in PC counts.

2.11.2.1.2.6 FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS[1/2]

#define FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS (FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH erase page size in PC counts.

2.11.2.1.2.7 FLASH_ERROR_MASK

#define FLASH_ERROR_MASK 0x2100

Defines FLASH flash error mask value.

2.11.2.1.2.8 FLASH_HAS_ECC[1/2]

#define FLASH_HAS_ECC 1

Defines if FLASH has ECC.

2.11.2.1.2.9 FLASH_HAS_ECC[1/2]

#define FLASH_HAS_ECC 1

Defines if FLASH has ECC.

2.11.2.1.2.10 FLASH_ODD_ADDRESS_MASK[1/2]

#define FLASH_ODD_ADDRESS_MASK 1U

Defines FLASH odd address mask value.

2.11.2.1.2.11 FLASH_ODD_ADDRESS_MASK[1/2]

#define FLASH_ODD_ADDRESS_MASK 1U

Defines FLASH odd address mask value.

2.11.2.1.2.12 FLASH_PC_UNIT_SIZE[1/2]

#define FLASH_PC_UNIT_SIZE 2U

Defines FLASH Flash PC unit size.

2.11.2.1.2.13 FLASH_PC_UNIT_SIZE[1/2]

#define FLASH_PC_UNIT_SIZE 2U

Defines FLASH Flash PC unit size.

2.11.2.1.2.14 FLASH_UNLOCK_KEY[1/2]

#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key value.

2.11.2.1.2.15 FLASH_UNLOCK_KEY[1/2]

#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key value.

2.11.2.1.2.16 FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS[1/2]

#define FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS 128U

Defines FLASH write row size in instruction counts.

2.11.2.1.2.17 FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS[1/2]

#define FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS 128U

Defines FLASH write row size in instruction counts.

2.11.2.1.2.18 FLASH_WRITE_ROW_SIZE_IN_PC_UNITS[1/2]

#define FLASH_WRITE_ROW_SIZE_IN_PC_UNITS (FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH write row size in PC counts.

2.11.2.1.2.19 FLASH_WRITE_ROW_SIZE_IN_PC_UNITS[1/2]

#define FLASH_WRITE_ROW_SIZE_IN_PC_UNITS (FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH write row size in PC counts.

2.11.2.1.3 Function Documentation

2.11.2.1.3.1 FLASH_ErasePage()

bool FLASH_ErasePage (flash_adr_t address, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.

Parameters:
in	address	- Flash page aligned address.

Returns:
bool - Returns True if operation successful else returns false.

2.11.2.1.3.2 FLASH_ErasePageAddressGet()

uint32_t FLASH_ErasePageAddressGet (flash_adr_t address)

This routine returns the page aligned address for a given flash address..

Parameters:
in	address	- Flash address.

Returns:
uint32_t - Returns page aligned flash address.

2.11.2.1.3.3 FLASH_ErasePageOffsetGet()

uint16_t FLASH_ErasePageOffsetGet (flash_adr_t address)

This routiner returns the page offset the given flash address.

Parameters:
in	address	- Flash address.

Returns:
uint32_t - returns offset.

2.11.2.1.3.4 FLASH_Initialize()

void FLASH_Initialize ( )

This function initializes the nvm controller.

Returns:

2.11.2.1.3.5 FLASH_NonBlockingBulkErase()

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

This function erases a panel.

Parameters:
in	panel	: Flash panel to erase
in	unlockKey	: Flash unlock key

Returns:
* returns FLASH_NO_ERROR if operation is successful, if the operation is in progress then it returns FLASH_OP_IN_PROGRESS, if there is a previous operation in progress then it returns FLASH_OP_BUSY , in case of any unsuccessful operation it returns errors like FLASH_INVALID_ADDRESS, FLASH_INVALID_CALLBACK_HANDLER, FLASH_WRITE_ERROR

2.11.2.1.3.6 FLASH_NonBlockingEraseBulk()

bool FLASH_NonBlockingEraseBulk (uint32_t panel, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.

Parameters:
in	panel	- Panel to erase.

Returns:
bool - Returns True if operation successful else returns false.

2.11.2.1.3.7 FLASH_NonBlockingErasePage()

bool FLASH_NonBlockingErasePage (flash_adr_t address, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.

Parameters:
in	address	- Flash page aligned address.

Returns:
bool - Returns True if operation successful else returns false.

2.11.2.1.3.8 FLASH_NonBlockingPageErase()

enum FLASH_RETURN_STATUS FLASH_NonBlockingPageErase (flash_adr_t flashAddress, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void * context)

This function erases a page.

Parameters:
in	flashAddress	: Flash address
in	unlockKey	: Flash unlock key
in	callbackHandler	: Pointer to call back handler
in	context	: Optional pointer to context to handle user contexts

Returns:
FLASH_RETURN_STATUS: returns FLASH_NO_ERROR if operation is successful, if the operation is in progress then it returns FLASH_OP_IN_PROGRESS, if there is a previous operation in progress then it returns FLASH_OP_BUSY , in case of any unsuccessful operation it returns errors like FLASH_INVALID_ADDRESS, FLASH_INVALID_CALLBACK_HANDLER, FLASH_WRITE_ERROR

2.11.2.1.3.9 FLASH_NonBlockingRead()

enum FLASH_RETURN_STATUS FLASH_NonBlockingRead (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 of
out	data	: Pointer to read the data

Returns:
FLASH_RETURN_STATUS: returns FLASH_NO_ERROR if operation is successful, if the operation is in progress then it returns FLASH_OP_IN_PROGRESS, if there is a previous operation in progress then it returns FLASH_OP_BUSY , in case of any unsuccessful operation it returns errors like FLASH_INVALID_ADDRESS, FLASH_INVALID_DATA

2.11.2.1.3.10 FLASH_NonBlockingReadWord16()

uint16_t FLASH_NonBlockingReadWord16 (flash_adr_t address)

This routine reads a 16 bit instruction from the indicated address in flash.

Parameters:
in	address	- Flash address.

Returns:
uint16_t - 16 bit data.

2.11.2.1.3.11 FLASH_NonBlockingReadWord24()

uint32_t FLASH_NonBlockingReadWord24 (flash_adr_t address)

This routine reads a 24 bit instruction from the indicated address in flash.

Parameters:
in	address	- Flash address.

Returns:
uint32_t - 24 bit data.

2.11.2.1.3.12 FLASH_NonBlockingRowWrite()

enum FLASH_RETURN_STATUS FLASH_NonBlockingRowWrite (flash_adr_t flashAddress, flash_data_t * data, flash_key_t unlockKey, FLASH_CALLBACK callback, void * context)

This function writes the specified data to the specified address.

Parameters:
in	flashAddress	: Flash address
in	data	: Pointer of the data to be written
in	unlockKey	: Flash unlock Key.
in	callbackHandler	: Pointer to call back handler
in	context	: Optional pointer to context to handle user contexts

Returns:
FLASH_RETURN_STATUS: returns FLASH_NO_ERROR if operation is successful, if the operation is in progress then it returns FLASH_OP_IN_PROGRESS, if there is a previous operation in progress then it returns FLASH_OP_BUSY , in case of any unsuccessful operation it returns errors like FLASH_INVALID_ADDRESS, FLASH_INVALID_CALLBACK_HANDLER, FLASH_WRITE_ERROR

2.11.2.1.3.13 FLASH_NonBlockingWordWrite()

enum FLASH_RETURN_STATUS FLASH_NonBlockingWordWrite (flash_adr_t flashAddress, flash_data_t * data, flash_key_t unlockKey, FLASH_CALLBACK callbackHandler, void * context)

This function writes the specified data to the specified address.

Parameters:
in	flashAddress	: Flash address
in	data	: Pointer of the data to be written.
in	unlockKey	: Flash unlock Key.
in	callbackHandler	: pointer to call back handler
in	context	: Optional pointer to context to handle user contexts This will write the TWO WORDS pointed to by the pointer.

Returns:
FLASH_RETURN_STATUS: returns FLASH_NO_ERROR if operation is successful, if the operation is in progress then it returns FLASH_OP_IN_PROGRESS, if there is a previous operation in progress then it returns FLASH_OP_BUSY , in case of any unsuccessful operation it returns errors like FLASH_INVALID_ADDRESS, FLASH_INVALID_CALLBACK_HANDLER, FLASH_WRITE_ERROR

2.11.2.1.3.14 FLASH_NonBlockingWriteDoubleWord16()

bool FLASH_NonBlockingWriteDoubleWord16 (flash_adr_t flashAddress, uint16_t Data0, uint16_t Data1, flash_key_t unlockKey)

This routine writes two ,16 bit instructions to the indicated address in flash.

Parameters:
in	address	- Flash address.
in	data1	- First 16 bit data to be written(First word).
in	data2	- Second 16 bit data to be written(Second word).

Returns:
bool - Returns true if operation is successful else returns false.

2.11.2.1.3.15 FLASH_NonBlockingWriteDoubleWord24()

bool FLASH_NonBlockingWriteDoubleWord24 (flash_adr_t address, flash_data_t Data0, flash_data_t Data1, flash_key_t unlockKey)

This routine writes two 24 bit instructions to the indicated address in flash.

Parameters:
in	address	- Flash address.
in	data1	- First 24 bit data to be written(First word).
in	data2	- Second 24 bit data to be written(Second word).

Returns:
bool - Returns true if operation is successful else returns false.

2.11.2.1.3.16 FLASH_NonBlockingWriteRow16()

bool FLASH_NonBlockingWriteRow16 (flash_adr_t address, uint16_t * data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Each 16 bit source data word is stored in the lower 16 bits of each flash entry and the upper 8 bits of the flash is not programmed.The address in *data must be row aligned.

Parameters:
in	address	- Flash address.
in	*data	- Address of the data to be written.

Returns:
bool - Returns true if operation is successful else returns false.

2.11.2.1.3.17 FLASH_NonBlockingWriteRow24()

bool FLASH_NonBlockingWriteRow24 (flash_adr_t flashAddress, flash_data_t * data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Since the flash is only 24 bits wide all data in the upper 8 bits of the source will be lost.The address in *data must be row aligned.

Parameters:
in	address	- Flash address.
in	*data	- Address of the data to be written.

Returns:
bool - Returns true if operation is successful else returns false.

2.11.2.1.3.18 FLASH_OperationStatusGet()

enum FLASH_RETURN_STATUS FLASH_OperationStatusGet ( )

This function gets the status of nvm controller.

Returns:

2.11.2.1.3.19 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

2.11.2.1.3.20 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 of
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

2.11.2.1.3.21 FLASH_ReadWord16()

uint16_t FLASH_ReadWord16 (flash_adr_t address)

This routine reads a 16 bit instruction from the indicated address in flash.

Parameters:
in	address	- Flash address.

Returns:
uint16_t - 16 bit data.

2.11.2.1.3.22 FLASH_ReadWord24()

uint32_t FLASH_ReadWord24 (flash_adr_t address)

This routine reads a 24 bit instruction from the indicated address in flash.

Parameters:
in	address	- Flash address.

Returns:
uint32_t - 24 bit data.

2.11.2.1.3.23 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

2.11.2.1.3.24 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 TWO 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

2.11.2.1.3.25 FLASH_WriteDoubleWord16()

bool FLASH_WriteDoubleWord16 (flash_adr_t flashAddress, uint16_t Data0, uint16_t Data1, flash_key_t unlockKey)

This routine writes two ,16 bit instructions to the indicated address in flash.

Parameters:
in	address	- Flash address.
in	data1	- First 16 bit data to be written(First word).
in	data2	- Second 16 bit data to be written(Second word).

Returns:
bool - Returns true if operation is successful else returns false.

2.11.2.1.3.26 FLASH_WriteDoubleWord24()

bool FLASH_WriteDoubleWord24 (flash_adr_t address, flash_data_t Data0, flash_data_t Data1, flash_key_t unlockKey)

This routine writes two 24 bit instructions to the indicated address in flash.

Parameters:
in	address	- Flash address.
in	data1	- First 24 bit data to be written(First word).
in	data2	- Second 24 bit data to be written(Second word).

Returns:
bool - Returns true if operation is successful else returns false.

2.11.2.1.3.27 FLASH_WriteRow16()

bool FLASH_WriteRow16 (flash_adr_t address, uint16_t * data, flash_key_t unlockKey)

Parameters:
in	address	- Flash address.
in	*data	- Address of the data to be written.

Returns:
bool - Returns true if operation is successful else returns false.

2.11.2.1.3.28 FLASH_WriteRow24()

bool FLASH_WriteRow24 (flash_adr_t flashAddress, flash_data_t * data, flash_key_t unlockKey)

Parameters:
in	address	- Flash address.
in	*data	- Address of the data to be written.

Returns:
bool - Returns true if operation is successful else returns false.

2.11.2.1.4 Enumeration Type Documentation

2.11.2.1.4.1 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

2.11.2.1.4.2 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

2.11.2.1.5 Variable Documentation

2.11.2.1.5.1 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.

2.11.3 Class Documentation

2.11.3.1 FLASH_INTERFACE Struct Reference

Structure containing the function pointers of FLASH driver.

2.11.3.1.1 Detailed Description

Structure containing the function pointers of FLASH driver.

#include <flash_interface.h>

2.11.3.1.1.1 Public Attributes

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.

2.11.3.1.2 Member Data Documentation

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

source/

flash_interface.h

2.11.3.1.2.1 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.

2.11.3.1.2.2 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.

2.11.3.1.2.3 NonBlockingPolledBulkErase

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

Pointer to FLASH_NonBlockingPolledBulkErase e.g. FLASH_NonBlockingPolledBulkErase.

2.11.3.1.2.4 NonBlockingPolledPageErase

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

Pointer to FLASH_NonBlockingPolledPageErase e.g. FLASH_NonBlockingPolledPageErase.

2.11.3.1.2.5 NonBlockingPolledRead

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

Pointer to FLASH_NonBlockingPolledRead e.g. FLASH_NonBlockingPolledRead.

2.11.3.1.2.6 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.

2.11.3.1.2.7 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.

2.11.3.1.2.8 NonBlockingRead

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

Pointer to FLASH_NonBlockingRead e.g. FLASH_NonBlockingRead.

2.11.3.1.2.9 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.

2.11.3.1.2.10 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.

2.11.3.1.2.11 OperationStatusGet

enum FLASH_RETURN_STATUS(* OperationStatusGet) (void)

Pointer to FLASH_OperationStatusGet e.g. FLASH_OperationStatusGet.

2.11.3.1.2.12 PageAddressGet

uint32_t(* PageAddressGet) (flash_adr_t address)

Pointer to FLASH_ErasePageAddressGet e.g. FLASH_ErasePageAddressGet.

2.11.3.1.2.13 PageErase

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

Pointer to FLASH_PageErase e.g. FLASH_PageErase.

2.11.3.1.2.14 PageOffsetGet

uint16_t(* PageOffsetGet) (flash_adr_t address)

Pointer to FLASH_ErasePageOffsetGet e.g. FLASH_ErasePageOffsetGet.

2.11.3.1.2.15 Read

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

Pointer to FLASH_Read e.g. FLASH_Read.

2.11.3.1.2.16 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.

2.11.3.1.2.17 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.

2.11.4 File Documentation

2.11.4.1 source/flash.h File Reference

FLASH driver using dsPIC MCUs.

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

2.11.4.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.

2.11.4.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.

2.11.4.1.3 Detailed Description

FLASH driver using dsPIC MCUs.

This is the generated driver header file for the FLASH driver.

FLASH Generated Driver Header File

2.11.4.2 source/flash_hardware.h File Reference

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

2.11.4.2.1 Functions

bool FLASH_ErasePage (flash_adr_t address, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.
uint32_t FLASH_ReadWord24 (flash_adr_t address)

This routine reads a 24 bit instruction from the indicated address in flash.
uint16_t FLASH_ReadWord16 (flash_adr_t address)

This routine reads a 16 bit instruction from the indicated address in flash.
bool FLASH_WriteDoubleWord24 (flash_adr_t address, flash_data_t Data0, flash_data_t Data1, flash_key_t unlockKey)

This routine writes two 24 bit instructions to the indicated address in flash.
bool FLASH_WriteDoubleWord16 (flash_adr_t flashAddress, uint16_t Data0, uint16_t Data1, flash_key_t unlockKey)

This routine writes two ,16 bit instructions to the indicated address in flash.
bool FLASH_WriteRow24 (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Since the flash is only 24 bits wide all data in the upper 8 bits of the source will be lost.The address in *data must be row aligned.
bool FLASH_WriteRow16 (flash_adr_t address, uint16_t *data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Each 16 bit source data word is stored in the lower 16 bits of each flash entry and the upper 8 bits of the flash is not programmed.The address in *data must be row aligned.
uint16_t FLASH_ErasePageOffsetGet (flash_adr_t address)

This routiner returns the page offset the given flash address.
uint32_t FLASH_ErasePageAddressGet (flash_adr_t address)

This routine returns the page aligned address for a given flash address..

2.11.4.2.2 Macros

#define FLASH_PC_UNIT_SIZE 2U

Defines FLASH Flash PC unit size.
#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key value.
#define FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS 128U

Defines FLASH write row size in instruction counts.
#define FLASH_WRITE_ROW_SIZE_IN_PC_UNITS (FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH write row size in PC counts.
#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 1024U

Defines FLASH erase page size in instruction counts.
#define FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS (FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH erase page size in PC counts.
#define FLASH_HAS_ECC 1

Defines if FLASH has ECC.
#define FLASH_ERASE_PAGE_MASK (~(FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS - 1U))

Defines FLASH erase page mask value.
#define FLASH_ODD_ADDRESS_MASK 1U

Defines FLASH odd address mask value.

2.11.4.3 source/flash_hardware_nonblocking.h File Reference

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

2.11.4.3.1 Functions

bool FLASH_NonBlockingErasePage (flash_adr_t address, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.
bool FLASH_NonBlockingEraseBulk (uint32_t panel, flash_key_t unlockKey)

This routine erases a page indicated by the page aligned address.
bool FLASH_NonBlockingWriteDoubleWord24 (flash_adr_t address, flash_data_t Data0, flash_data_t Data1, flash_key_t unlockKey)

This routine writes two 24 bit instructions to the indicated address in flash.
bool FLASH_NonBlockingWriteDoubleWord16 (flash_adr_t flashAddress, uint16_t Data0, uint16_t Data1, flash_key_t unlockKey)

This routine writes two ,16 bit instructions to the indicated address in flash.
bool FLASH_NonBlockingWriteRow24 (flash_adr_t flashAddress, flash_data_t *data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Since the flash is only 24 bits wide all data in the upper 8 bits of the source will be lost.The address in *data must be row aligned.
bool FLASH_NonBlockingWriteRow16 (flash_adr_t address, uint16_t *data, flash_key_t unlockKey)

This routine writes a single row of data from the location given in *data to the flash location in address. Each 16 bit source data word is stored in the lower 16 bits of each flash entry and the upper 8 bits of the flash is not programmed.The address in *data must be row aligned.
uint32_t FLASH_NonBlockingReadWord24 (flash_adr_t address)

This routine reads a 24 bit instruction from the indicated address in flash.
uint16_t FLASH_NonBlockingReadWord16 (flash_adr_t address)

This routine reads a 16 bit instruction from the indicated address in flash.

2.11.4.3.2 Macros

#define FLASH_PC_UNIT_SIZE 2U

Defines FLASH Flash PC unit size.
#define FLASH_UNLOCK_KEY 0x00AA0055

Defines FLASH unlock key value.
#define FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS 128U

Defines FLASH write row size in instruction counts.
#define FLASH_WRITE_ROW_SIZE_IN_PC_UNITS (FLASH_WRITE_ROW_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH write row size in PC counts.
#define FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS 1024U

Defines FLASH erase page size in instruction counts.
#define FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS (FLASH_ERASE_PAGE_SIZE_IN_INSTRUCTIONS * FLASH_PC_UNIT_SIZE)

Defines FLASH erase page size in PC counts.
#define FLASH_HAS_ECC 1

Defines if FLASH has ECC.
#define FLASH_ERASE_PAGE_MASK (~(FLASH_ERASE_PAGE_SIZE_IN_PC_UNITS - 1U))

Defines FLASH erase page mask value.
#define FLASH_ODD_ADDRESS_MASK 1U

Defines FLASH odd address mask value.
#define FLASH_ERROR_MASK 0x2100

Defines FLASH flash error mask value.

2.11.4.4 source/flash_interface.h File Reference

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

2.11.4.4.1 Data structures

struct FLASH_INTERFACE

Structure containing the function pointers of FLASH driver.

2.11.4.4.2 Detailed Description

flash Generated Driver Interface Header File

2.11.4.5 source/flash_nonblocking.h File Reference

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include "xc.h"
#include "flash_interface.h"
#include "flash_hardware_nonblocking.h"
#include "../flash/flash.h"