Introduction

The flash file system shall be a light-weight single-use implementation for embedded targets that have flash device access either as part of the processing chip itself or externally with a dedicated flash memory chip on the board. The flash file system component’s main purpose is to load a saved signal processing layout or to load module coefficients. It is not intended to be a general purpose file system but rather is a limited subset of a full featured file system designed exclusively for use on a flash memory device for the specific purpose of loading pre-saved layouts and coefficient sets. There is no limitation and any file types, like wav file for sound design modules, can be stored in the flash file system.

Flash Memory Details

The flash memory reserved for this file system may be part of the processor chip itself, an external part or simulated in the target file system. It should be noted that flash memory starts out fully erased which means all bits are set to 1. Most non-volatile storage for file systems sets all bits to 0 for the fully erased state but most flash memory devices can only change a single bit from a 1 to a 0 so the erased state is considered to be all 1’s. A block of bits can be reset to all 1’s (this is called sector or block erase) but a single bit cannot be changed from a 0 to a 1.

System Context

The flash file system shall publish an API for the basic file operations. The low level interface to read, write and erase the flash memory device shall be implemented by the firmware author and shall be accessed by the flash file system using callbacks.

The flash file system is part of the AWECore library. Its use is optional, but if used the AWECore instance structure must include a Flash File System instance structure.

AWE Server has a flash file system manager which uses tuning commands to maintain files on the flash file system. The AWE Server flash file system manager provides the ability to list files, write new files, delete files, and mark file attributes. It also can reformat the target file system.

Design Assumptions, Constraints and Dependencies

The flash file system requires AWE Server to manage the file system and firmware to implement the low level interaction with the flash memory device.

Fault Tolerant

The flash file system shall be fault tolerant. If power is removed or some part of the system crashes while the flash file system is being updated the file system shall remain consistent when the target is stable again. If a file write operation is not completed successfully that file may be lost but the rest of the file system shall remain stable.

No Garbage Collection

When a file is deleted it shall be marked as such but no attempt to reassign its allocated blocks as available shall be performed until the flash file system is re-formatted.

One File Open at a Time

Only one file may be operated on at a time. A complete file operation consists of file open, file read/write, file close. There shall be no mechanism to support concurrent file I/O.

Component Design

Component Structure

The flash file system shall be able to be located at a specific starting address in flash memory and shall have a defined size in units of 32-bit words. The memory footprint shall consist of the following elements:

• File Header Info (including identifying signature word)

• Allocation table bitmap

• File Directory

• File Data

File Allocation Blocks

In order to determine how big a file is, the data is broken into allocation blocks and a bitmap is used to determine which allocation blocks are in use. The allocation block size is a tradeoff between read/write performance and wasted space since the minimum allocated space must be in units of the allocation size and an allocation table entry for each allocation block in use. The smaller the block allocation size the worse performance and the larger the file allocation table but less wasted space for lots of small files.

File Allocation Block Size

The file allocation block size shall be 16 32-bit words or 64 bytes. This is currently a hard-coded #define in the C code.

#define ALLOCATION_BLOCKSIZE_DWORDS 16

File Header Info

Information about the current file system needs to be persisted as part of the flash file system. The following information shall appear at the start of the flash memory area devoted to the flash file system.

This header information is written at the start of the flash file system when the flash file system is initialized. 

The Version Number is “AW” followed by a 16-bit binary version number. The ASCII “AW” can be used as an identifying signature to determine if the flash memory area has already been set up as a flash file system.

Allocation Table Bitmap

There shall be a file allocation bitmap table. All bits of this table start out as a 1. When a segment of ALLOCATION_BLOCKSIZE_DWORDS is allocated a single bit is changed from a 1 to a 0. The allocation table shall account for all allocation blocks used including blocks for the flash file system header and for the file allocation table itself.

ALLOCATION_BLOCKSIZE_DWORDS is currently set to 16 32-bit words

File Directory

A file directory entry is limited to one allocation block size. A directory entry has an attribute 32-bit word followed by a file data length 32-bit word followed by the file name as 14 32-bit words. 

Directory Entry Definition

#define MAX_FILENAME_LENGTH_IN_DWORDS 14

typedef struct _DIRECTORY_ENTRY
{
    UINT32 nFileInfo;
    UINT32 nDataDWordCnt;
    UINT32 nFilename [ MAX_FILENAME_LENGTH_IN_DWORDS ];
}   DIRECTORY_ENTRY,  *PDIRECTORY_ENTRY;

Directory Entry File Info Word

Each entry in the directory table starts with a file info word.

Attribute Bit Definition

Files on the flash file system may be of different types defined by the file attribute byte

Attributes:

• LOAD_IMAGE — unused

• STARTUP_FILE — to be loaded on target start

• DATA_FILE — coefficients

• COMPILED_SCRIPT — command script is binary

• COMMAND_SCRIPT — commands

• PRESET_SCRIPT — unused

• COMPILED_PRESET_SCRIPT — unused

• LOADER_FILE — unused

• FILE_DELETED — marks a file as deleted

Flash File System Memory layout

The memory layout starts with the file system header fields followed by the file allocation bitmap table. The file directory entries start at the end of the space dedicated to the flash file system and grow down. As files are added the file data area grows up.

When the data needed to create a file exceeds the data space between the first available word in the file data area and the bottom of the file directory area the file system is considered full.

Data Structures

AWEFlashFSInstance Structure

The AWEFlashFSInstance structure is part of the firmware code and is used by the AWECore library code to define required features of the flash file system.

typedef struct _AWEFlashFSInstance
{
    /** Size of flash memory - if non-zero, next two values must also be non-zero. */
    UINT32 flashSizeInBytes;

    /** Size of flash erase block. */
    UINT32 flashErasableBlocksizeInBytes;

    /** Offset into start of flash used for file system. */
    UINT32 flashStartOffsetInBytes;

    /** Flash erase time in milliseconds */
    UINT32 flashEraseTimeInMs;

    /** User function to initialize flash file system, */
    BOOL (*cbInit)(void);

    /** User function to erase one or more sectors. */
    BOOL (*cbEraseSector)(UINT32 nStartingAddress, UINT32   nNumberOfSectors);

    /** User function to write to flash. */
    BOOL (*cbFlashWrite)(UINT32 nFlashAddress, UINT32 * pBuffer, UINT32 nDWordsToWrite);

    /** User function to read from flash. */
    BOOL (*cbFlashRead)(UINT32 nFlashAddress, UINT32 * pBuffer, UINT32 nDWordsToRead);

    /** Optional user callback function pointer for instance packet process. */
    INT32 (*cbFlashProcessCmd)(struct _AWEInstance *pAWE);

    FSAttributes flashAttributes;

}   AWEFlashFSInstance;

DIRECTORY_ENTRY Structure

The DIRECTORY_ENTRY structure is written to flash memory to identify each file added to the flash file system.

typedef struct _DIRECTORY_ENTRY
{
       UINT32 nFileInfo;
       UINT32 nDataDWordCnt;
       UINT32 nFilename[MAX_FILENAME_LENGTH_IN_DWORDS];

}   DIRECTORY_ENTRY, *PDIRECTORY_ENTRY;

FileSystemInfo Structure

The FileSystemInfo structure is used by the AWECore library code to maintain state for the current flash file system.

/** This structure defines the file system info. */
typedef struct _FileSystemInfo
{
     UINT32 m_FileSystemType; /* 0 */
     UINT32 m_FlashDeviceDWords; /* 4 */
     UINT32 m_FileSystemDWords; /* 8 */
     UINT32 m_DataStructOverheadDWords; /* 12 */
     UINT32 m_DeletedOrCorruptedDWords; /* 16 */
     UINT32 m_DWordsInUse; /* 20 */
     UINT32 m_DWordsAvailable; /* 24 */
     UINT32 m_BlkSize_MaxFilename_Len; /* 28 */
}   FileSystemInfo;

FSAttributes Structure

The FSAttributes structure is used by the AWECore library code to maintain information about the current flash file system.

typedef struct _FSAttributes
{
    /** Byte Address in flash memory of start of file allocation table */
    UINT32 nAllocTableBitMapFlashAddr;

    /** Block size for the file system 16 words/block */
    UINT32 nAllocBlockSizeInDWords;

    /** Block size for the file system 64 bytes/block */
    UINT32 nAllocBlockSizeInBytes;

    /** Byte Address in flash memory of the first entry of the file directory */
    UINT32 nFileDirectoryFlashAddr;

    /** Total flash memory size in bytes */
    UINT32 nFlashMemorySizeBytes;

    /** Size of flash memory erasable block size in bytes */
    UINT32 nEraseableBlockSize;

    /** Count of active files saved in the flash file system */
    INT32  nFileCnt;

    /** Byte Address in flash memory of the start of file data */
    UINT32 nStartOfFileDataFlashAddr;

    /** Count of the number of file allocation blocks in use */
    UINT32 nDataBlocksInUse;

    /** Current directory entry when navigating through the file system */
    DIRECTORY_ENTRY CurrentDirEntry;

    /** Address of first free block for file allocation */
    UINT32 nFirstFreeBlockFlashAddr;

    /** File is open state */
    BOOL   bFileOpen;

    /** Number of DWords read so far */
    INT32  nDWordsRead;

    /** Number of DWords written so far */
    INT32  nDWordsWritten;

    /** Current file position byte offset */
    UINT32 nFileCurrentPosByteOffset;

    /** Offset to start of file content area in flash */
    UINT32 nFileContentReadOffset;

    /** File attribute byte */
    UINT32 nNewFileAttributeByte;

    /** Current directory entry when navigating */
    UINT32 CurrentDirEntryFlashAddr;

    /** Start of chain of deleted files */
    UINT32 nFileDirectoryFlashAddr_toDel;

    /** Residue DWords */
    UINT32 ResidueDWords[ALLOCATION_BLOCKSIZE_DWORDS];

    /** Number of DWords remaining to write */
    UINT32 nRemainingDWordsToWrite;

    /** Flash file system information */
    FileSystemInfo filesystem_info;

}  FSAttributes;

Flash File System Low Level Driver

The flash file system shall use callbacks that must be implemented by the firmware author to read, write, and erase flash memory. The firmware author must also define the location and size of the flash file system in flash memory.

Low Level Callbacks

There are four basic callbacks to interact with the flash memory device that must be implemented by the firmware author. When executed, these callbacks must run at a lower priority than the signal processing layout since these are blocking calls.

BOOL cbInit(void)

The  cbInit() callback is used to perform any initialization of the flash memory device needed.

BOOL cbInit(void);

BOOL cbEraseSector(UINT32 nStartingAddress, UINT32 nNumberOfSectors)

The cbEraseSector() callback is used to erase a flash memory block.

BOOL cbFlashWrite(UINT32 nFlashAddress, UINT32 * pBuffer, UINT32 nDWordsToWrite)

The cbFlashWrite callback writes starting at the flash address from pBuffer the specified number of 32-bit words.

BOOL cbFlashRead(UINT32 nFlashAddress, UINT32 * pBuffer, UINT32 nDWordsToRead)

The cbFlashRead callback reads from the flash address into pBuffer the specified number of 32-bit words.

INT32 cbFlashProcessCmd(AWEInstance *pAWE)

The optional cbFlashProcessCmd callback to return the next command from an awb in flash. Only required for multi-instance BSPs.

If not defined, awb commands are processed internally in the associated AWEInstance.
The command to be processed is in pAWE->pPacketBuffer. Parse the instanceID/opcode with AWECoreUtils, and route/process it on the desired instance.

Software Functions (or units)

File Location

Flash File System (AweFlashFileSystem.c) API Description

The following API is called by the AWECore library to interact with the flash file system.

awe_fwInitFlashFileSystem

Prototype:

BOOL awe_fwInitFlashFileSystem(AWEFlashFSInstance * pAWEFlashFSInstance)

1. Verify callbacks are defined in the AWEFlashFSInstance structure.

2. Initialize the flashAttributes member of AWEFlashFSInstance structure with default values.

3. Read from the beginning of the dedicated file system flash memory and look for signature bytes “AW”.

4. If the signature bytes are found update the flashAttributes with the values found in flash.

5. Read through the file directory updating the count of non-deleted files as well as the count of data words in use.

6. Read through the file allocation table to determine the first block available for new use.

If the signature bytes were not found at the start of the flash file system memory area then initialize by writing a valid header to the beginning of this memory. Then determine the size of file system memory and create the file allocation table with bits set for the file header and the file allocation table itself.

Returns:

• SUCCESS (TRUE)

• FAILURE (FALSE)

awe_fwGetFirstFile

Prototype:

INT32 awe_fwGetFirstFile(AWEFlashFSInstance *   pAWEFlashFSInstance,
            PDIRECTORY_ENTRY * pDirEntry)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

pDirEntry - Pointer to return file directory information, if found.

This function returns the first file exists in the Flash File System.

Returns:

• E_SUCCESS

• E_NO_MORE_FILES

• E_ERROR_READING_FLASH_MEMORY

awe_fwGetNextFile

Prototype:

INT32 awe_fwGetNextFile(AWEFlashFSInstance *   pAWEFlashFSInstance, 
            PDIRECTORY_ENTRY * pDirEntry)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

pDirEntry - Pointer to return file directory information, if found.

This function returns the next file information, after the first file, if exists in the Flash File System. If called again in sequence, next file information is returned or NULL if no more files exists.

Returns:

• E_SUCCESS

• E_NO_MORE_FILES

• E_ERROR_READING_FLASH_MEMORY

awe_fwOpenFile

Prototype:

INT32 awe_fwOpenFile(AWEFlashFSInstance * pAWEFlashFSInstance,
            UINT32 nFileAttribute, 
            UINT32 * pFileNameInDWords,
            UINT32 * nFileLenInDWords)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

nFileAttribute - Attribute of the file to be opened. Compiled Script, AudioWeaver Script, Other etc to open the file to write. Attribute 0 to open the file for reading.

pFileNameInDWords - File name packed into 32-bit unsigned words.

nFileLenInDWords - If the file is opened for reading, length of the file is returned through this pointer. In write mode, this is ignored, and the returned value is unknown.

If the file is opened for reading, this function allocates a block in the Flash File System with a directory entry. If the file is opened for reading, it returns E_SUCCESS and the length of the file through nFileLenInDWords argument, if exists.

Returns:

• E_SUCCESS

• E_FILE_ALREADY_OPEN

• E_FILE_NOT_FOUND

• E_ILLEGAL_FILE_ATTRIBUTE

• E_OUT_OF_SPACE

• E_ERROR_WRITING_FLASH_MEMORY

awe_fwCloseFile

Prototype:

INT32 awe_fwCloseFile(AWEFlashFSInstance * pAWEFlashFSInstance)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

If the file is opened before for writing, this function writes remaining data in the file which is less than the block size (16 words) in prior awe_fwWriteFile. Then the file is marked as closed.

Returns:

• E_SUCCESS

• E_NO_OPEN_FILE

• E_OUT_OF_SPACE

• E_ERROR_WRITING_FLASH_MEMORY

awe_fwWriteFile

Prototype:

INT32 awe_fwWriteFile(AWEFlashFSInstance * pAWEFlashFSInstance, 
            UINT32 nWordsToWrite, 
            UINT32 * pBuffer, 
            UINT32 * pDWordsWritten)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

nWordsToWrite - Number of 32-bit words to write.

pBuffer - Pointer to data to be written on to flash file system.

pDWordsWritten - Actual number of words written. Caller can use this information to check if the correct data is written.

This function writes a block of data onto the Flash File System for the file opened before. If this function called without prior file open, then it returns failure.

Returns:

• E_SUCCESS

• E_OUT_OF_SPACE

• E_ERROR_WRITING_FLASH_MEMORY

• E_NO_OPEN_FILE

awe_fwReadFile

Prototype:

INT32 awe_fwReadFile(AWEFlashFSInstance * pAWEFlashFSInstance, 
            UINT32 nWordsToRead, 
            UINT32 * pBuffer, 
            UINT32 * pDWordsRead)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

nWordsToRead - Number of 32-bit words to read.

pBuffer - Pointer to copy data from the flash file system.

pDWordsRead - Actual number of words fetched. Caller can use this information to check if the correct data is fetched.

If the file is opened for reading before, then this function copies specified number of words from the Flash File System into the buffer. Otherwise, error code is returned.

Returns: 

• E_SUCCESS

• E_ERROR_READING_FLASH_MEMORY

• E_NO_OPEN_FILE

awe_fwDeleteFile

Prototype:

INT32 awe_fwDeleteFile(AWEFlashFSInstance * pAWEFlashFSInstance, 
            UINT32 * pFileNameInDWords)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

pFileNameInDWords - File name packed into 32-bit unsigned words.

Specified file, if exists, will be marked as deleted in the Flash File System.

Returns:

• E_SUCCESS

• E_FILE_ALREADY_OPEN

• E_FILE_NOT_FOUND

• E_ERROR_READING_FLASH_MEMORY

• E_ERROR_WRITING_FLASH_MEMORY

awe_fwFindFile

Prototype:

PDIRECTORY_ENTRY awe_fwFindFile(AWEFlashFSInstance * pAWEFlashFSInstance, 
            UINT32 * pFileNameInDWords)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

pFileNameInDWords - File name packed into 32-bit unsigned words.

This function looks through the Flash File System and returns the file directory pointer, if exists. otherwise, NULL pointer is returned.

Returns:

• Valid PDIRECTORY_ENTRY

• NULL

awe_fwEraseFlash

Prototype:

INT32 awe_fwEraseFlash(AWEFlashFSInstance * pAWEFlashFSInstance)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

Entire Flash File System will be erased and reinitializes with default state.

Returns:

• E_SUCCESS

• E_ERROR_ERASING_FLASH_MEMORY

awe_fwExecuteFile

Prototype:

INT32 awe_fwExecuteFile(AWEInstance * pAWE, 
            AWEFlashFSInstance * pAWEFlashFSInstance,
            UINT32 * pFileNameInDWords)

Arguments:

pAWE - AWE Instance pointer.

pAWEFlashFSInstance - Flash File System instance pointer.

pFileNameInDWords - File name packed into 32-bit unsigned words.

This function just calls awe_loadAWBfromFlash with the provided file name to execute it. Generally, this is called from awe_fwExecuteFlashFiles, to load any compiled script marked as bootable.

Returns:

• Error returned from awe_loadAWBfromFlash

awe_fwExecuteFlashFiles

Prototype:

INT32 awe_fwExecuteFlashFiles(AWEInstance * pAWE, 
            AWEFlashFSInstance * pAWEFlashFSInstance)

Arguments:

pAWE - AWE Instance pointer.

pAWEFlashFSInstance - Flash File System instance pointer.

This function walkthrough the Flash File System and if any compiled script marked as bootable then awe_fwExecuteFile is called with that file name.

Returns:

• E_SUCCESS

• E_ERROR_READING_FLASH_MEMORY

• E_NO_MORE_FILES

• Error returned from awe_loadAWBfromFlash

awe_fwReadFileMem

Prototype:

INT32 awe_fwReadFileMem(AWEFlashFSInstance * pAWEFlashFSInstance,
            UINT32 nStartingAddress, 
            UINT32 nOffsetInDWords, 
            UINT32 nWordsToRead, 
            UINT32 * pBuffer)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

nStartingAddress - Start address into the Flash File System to read data

nOffsetInDWords - Offset from the start address, in 32-bit words

nWordsToRead - Number of 32-bit words to read

pBuffer - Buffer pointer to copy data

This is an alternative function to awe_fwReadFile, to read file data based on the address in the flash file system.

Returns:

• E_SUCCESS

• E_ERROR_READING_FLASH_MEMORY

awe_fwGetFileMemStartingAddress

Prototype:

INT32 awe_fwGetFileMemStartingAddress(AWEFlashFSInstance * pAWEFlashFSInstance, 
            UINT32 * nStartingAddress, 
            UINT32 * nFileLenInDWords)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

pFileNameInDWords - File name packed into 32-bit words

nStartingAddress - Start address into the Flash File System of the file specified

nFileLenInDWords - File length in 32-bit words

This is a supporting function to alternate Flash File System read method awe_fwReadFileMem, to get the start address and the length of a file in the Flash File System.
Returns:

• E_SUCCESS

• E_FILE_NOT_FOUND

awe_fwGetFileAttribute

Prototype:

UINT8 awe_fwGetFileAttribute(PDIRECTORY_ENTRY pDirectoryEntry)

Arguments:

pDirectoryEntry - Pointer to a file directory entry.

This function extracts and returns the file attribute information from the provided file directory entry.

Returns:

• File attribute byte

awe_initFlashFS

Prototype:

void awe_initFlashFS(AWEInstance * pAWE, AWEFlashFSInstance * pAWEFlashFSInstance)

Firmware (BSP) has to call this public API to initialize internal flash file system states when flash file system is implemented.

awe_fwResetFileSystem

Prototype:

INT32 awe_fwResetFileSystem(AWEFlashFSInstance * pAWEFlashFSInstance)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

Initializes internal Flash File System structure to default state.

Returns:

• E_SUCCESS

awe_fwAllocateBlock

Prototype:

BOOL awe_fwAllocateBlock(AWEFlashFSInstance * pAWEFlashFSInstance, UINT32 nAddress)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

nAddress - Address at which to allocate a block of 16 words

This is an internal function which allocate a block in the Flash File System. Generally, this function is called during file open to write data.

Returns:

• SUCCESS

• FAILURE

GetFileNameLengthInDWords

Prototype:

UINT32 GetFileNameLengthInDWords(UINT32 * pFileNameInDWords)

Arguments:

pFileNameInDWords - File name packed into 32-bit words.

This is an internal method to find the length of the null terminated file name and returns the file name in 32-bit words. If the file name is not exact multiple of 4 bytes, then the last remaining bytes are expected to be filled with 0’s in the provided file name.

Returns:

• Word count

awe_fwGetFileSystemInfo

Prototype:

INT32 awe_fwGetFileSystemInfo(AWEFlashFSInstance * pAWEFlashFSInstance,
            FileSystemInfo *pFileSystemInfo)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

pFileSystemInfo - Pointer to return file system information.

This function returns the current file system information like file system type (Flash), allocation table size (16 words), max file name length etc.

Returns:

• E_SUCCESS

• E_PARAMETER_ERROR

awe_fwFlashFileSystemCommandHandler

Prototype:

INT32 awe_fwFlashFileSystemCommandHandler(AWEInstance * pAWE)

Arguments:

pAWE - AWE instance pointer.

This is the main function handler to process all the Flash File System related PFID commands.

Returns:

• E_SUCCESS

• E_COMMAND_NOT_IMPLEMENTED

awe_fwInitFFS

Prototype:

INT32 awe_fwInitFFS(AWEInstance * pAWE)

Arguments:

pAWE - AWE instance pointer.

Just a wrapper function to Flash File System initialization and making a call to user callback cbInit.

Returns:

• E_SUCCESS

• E_NOT_OBJECT

• E_EXCEPTION

Internal Callback to Process Command

An internal callback is implemented to enable AWECore to process commands that are read from the flash file system to instantiate a signal processing layout. This callback is invoked as part of the process called by awe_pltExecuteFlashFiles. awe_pltExecuteFlashFiles calls awe_pltExecutFile for each file marked for boot which calls an internal method awe_loadAWBfromFlash. This method calls the callback cbFlashProcessCmd, if defined, which must point to a BSP method with the following prototype:

INT32 cbFlashProcessCmd(AWEInstance * pAWE);

If not defined by the BSP, the internal packet processing method is used.

AWE Core Flash File System Message IDs

AWE_Server sends packets with a command ID 32-bit word followed by any argument 32-bit words and ending with a CRC 32-bit word. Also, the flash file system reserves 14 32-bit words for a file name.

PFID_FileSystemReset

It is a two-word packet with command header and CRC only. Flash file manager make a call to awe_fwResetFileSystem upon receiving this command.

Reply packet is 3 32-bit words

PFID_GetFirstFile

It is a two-word packet with command header and CRC only. Flash file manager make a call to awe_fwGetFirstFile upon receiving this command.

Reply packet is 19 32-bit words

PFID_GetNextFile

It is a two-word packet with command header and CRC only. Flash file manager make a call to awe_fwGetNextFile upon receiving this command.

Reply packet is 19 32-bit words

PFID_OpenFile

File name to open starts at the third command word in the received packet. Second word contains file attribute. Flash file manager make a call to awe_fwOpenFile upon receiving this command.

If the file is opened for reading (attribute as 0) then the file length in the reply packet represents the actual length of the file opened.

When the file is opened for writing, then file length field in the reply packet is 0.

Reply packet is 4 32-bit words

PFID_ReadFile

It is three words packet with command header, number of words to read and CRC. Flash file manager make a call to awe_fwReadFile upon receiving this command.

Reply packet is N+4 32-bit words

PFID_WriteFile

It is three words packet with command header, number of words to write and CRC. Flash file manager make a call to awe_fwWriteFile upon receiving this command.

Reply packet is 3 32-bit words

PFID_CloseFile

It is a two-word packet with command header and CRC only. Flash file manager make a call to awe_fwCloseFile upon receiving this command.

Reply packet is 3 32-bit words

PFID_DeleteFile

FiIe name to delete starts at the third command word in the received packet. Second word is not used and reserved for future use (recommended to set it to 0). Flash file manager make a call to awe_fwDeleteFile upon receiving this command.

Reply 3 32-bit words

PFID_ExecuteFile

FiIe name to execute starts at the third command word in the received packet. Second word is not used and reserved for future use (recommended to set it to 0). Flash file manager make a call to awe_fwExecuteFile upon receiving this command.

Reply 3 32-bit words

PFID_EraseFlash

It is a two-word packet with command header and CRC only. Flash file manager make a call to awe_fwEraseFlash upon receiving this command.

Reply packet is 3 32-bit words

PFID_GetFileSystemInfo

It is a two-word packet with command header and CRC only. Flash file manager make a call to awe_fwGetFileSystemInfo upon receiving this command.

Reply packet is 11 32-bit words

PFID_Get_Flash_Erase_Time

It is a two-word packet with command header and CRC only. Flash file manager constructs reply packet with the actual erase time provided by the system (BSP).

Reply packet is 3 32-bit words

Dynamic Behaviors

Flash File System Life Cycle

Flash file manager initializes flash file system on any physical memory (Flash device or any other local file system) upon called by the system (typically the BSP). The content in the flash file system is persisted until the memory is erased.

Verification and Testing

Unit test for Flash File System can be found at ‘CFramework\Test\TestAweFlashFileSystem.cpp’ and it covers all the units (functions) defined in 'C\Framework\AWEInstance\FlashFileSystem\AweFlashFileSystem.c.

Run TestCFramework GTest suite to trigger automatic unit verification.

Integrating the AWE Flash File System

The following are the steps to integrate or enable AWE Flash File System. Make sure the flash device is fully erased for the first time before enabling AWE Flash File System.

1. Define the following macros corresponding to flash memory size in bytes, erasable block size and the start offset for the Flash File System. Make sure the start offset does not overlap with other applications usage. It is recommended to use the free space in the flash from the end. Following are the example macros of a 64MB flash device:
   

   /* ----------------------------------------------------------------------
   ** Specify flash memory available for flash file system
   ** ------------------------------------------------------------------- */
   #define FLASH_MEMORY_SIZE_IN_BYTES 0x4000000
   #define ERASEABLE_SECTOR_SIZE 0x10000
   #define FILE_SYSTEM_START_OFFSET 0xB0000
   #define SECTOR_ERASE_TIME_MS	400

2. Declare a global AWE Flash File System instance:
   

   /** Flash file system instance */
   AWEFlashFSInstance g_AWEFlashFSInstance;

3. Initialize global AWE Flash File System instance to zero:
   

   // Setup the flash file system */
   memset(&g_AWEFlashFSInstance, 0, sizeof(AWEFlashFSInstance) );

4. Initialize the callbacks for ‘cbInit’, ‘cbEraseSector’, ‘cbFlashWrite’ and ‘cbFlashRead’:
   

   g_AWEFlashFSInstance.cbInit = &usrInitFlashFileSystem;
   g_AWEFlashFSInstance.cbEraseSector = &usrEraseFlashMemorySector;
   g_AWEFlashFSInstance.cbFlashWrite = &usrWriteFlashMemory;
   g_AWEFlashFSInstance.cbFlashRead = &usrReadFlashMemory;

5. Initialize flash memory size, erasable block size, start offset and block erase time:
   

   g_AWEFlashFSInstance.flashSizeInBytes = FLASH_MEMORY_SIZE_IN_BYTES;
   g_AWEFlashFSInstance.flashErasableBlockSizeInBytes = ERASEABLE_SECTOR_SIZE;
   g_AWEFlashFSInstance.flashStartOffsetInBytes = FILE_SYSTEM_START_OFFSET;
   g_AWEFlashFSInstance.flashEraseTimeInMs = (INT32)((FLOAT32)((( (FLASH_MEMORY_SIZE_IN_BYTES - FILE_SYSTEM_START_OFFSET)/ ERASEABLE_SECTOR_SIZE)*SECTOR_ERASE_TIME_MS/1000) + 0.5f) + 5);

6. Initialize the Flash File System by calling awe_initFlashFS:
   

   awe_initFlashFS(&g_AWEInstance, &g_AWEFlashFSInstance);

7. Assign pFlashFileSystem in AWE Instance to Flash File System instance:
   

   g_AWEInstance.pFlashFileSystem = &g_AWEFlashFSInstance;

8. Define callback functions for the following:

   1. ‘Init’:
      

      BOOL usrInitFlashFileSystem(void)
      {
      	// Implement any flash specific initializations
      	return 1;
      }   // End usrInitFlashFileSystem

   2. ‘Erase’:
      

      ///-----------------------------------------------------------------------------
      /// @name  BOOL usrEraseFlashSector(UINT32 nStartingAddress, UINT32 nNumberOfSectors)
      /// @brief Erase flash memory starting at address for number of sectors
      ///
      /// @param[in]	UINT32  nStartingAddress - address in flash to start erasing
      /// @param[in]	UINT32  nNumberOfSectors  - number of flash memory sectors to erase
      ///
      /// @retval  	SUCCESS - erase succeeded
      /// @retval 	FAILURE - erase failed
      ///-----------------------------------------------------------------------------
      //AWE_OPTIMIZE_FOR_SPEED
      BOOL usrEraseFlashSector(UINT32 nStartingAddress, UINT32 nNumberOfSectors)
      {
          UINT32 nSectorAddress, index, nSector;
          ERROR_CODE ErrorCode = NO_ERR;
      
      
          nSectorAddress = nStartingAddress;
      
          // Loop through number of sectors and erase each sector
          for (index = 0; index < nNumberOfSectors; index++)
          {
          	// Flash device specific sector erase implementation
      
      	nSectorAddress += ERASEABLE_SECTOR_SIZE;
          }
      
      	return 1;
      
      }	// End usrEraseFlashMemorySector

   3. ‘Write’:
      

      ///-----------------------------------------------------------------------------
      /// @name  BOOL usrWriteFlashMemory(UINT32 nAddress, UINT32 * pBuffer, UINT32 nDWordsToWrite)
      /// @brief Write 4-byte words to flash memory
      ///
      /// @param[in]	UINT32  nAddress - address in flash to start writing
      /// @param[in]	UINT32 * pBuffer  - buffer to write into
      /// @param[in]	UINT32  nDWordsToWrite - number of 4-bytes elements to write
      ///
      /// @retval  	SUCCESS - write succeeded
      /// @retval 	FAILURE - write failed
      ///-----------------------------------------------------------------------------
      BOOL usrWriteFlashMemory(UINT32 nAddress, UINT32 * pBuffer, UINT32 nDWordsToWrite)
      {
      	BOOL bSuccess = 0;
      
      	// Check for the count zero and skip remaining
      	if(nDWordsToWrite == 0)
      		return 1;
      
      	// Flash device write specific implementation
      
      }   // End usrWriteFlashMemory

   4. ‘Read’:
      

      ///-----------------------------------------------------------------------------
      /// @name  BOOL usrReadFlashMemory(UINT32 nAddress, UINT32 * pBuffer, UINT32 nDWordsToRead)
      /// @brief Read 4-byte words from flash memory
      ///
      /// @param[in]	UINT32  nAddress - address in flash to start reading
      /// @param[in]	UINT32 *pBuffer  - buffer to read into
      /// @param[in]	UINT32  nDWordsToRead - number of 4-bytes elements to read
      ///
      /// @retval  	SUCCESS - read succeeded
      /// @retval 	FAILURE - read failed
      ///-----------------------------------------------------------------------------
      BOOL usrReadFlashMemory(UINT32 nAddress, UINT32 * pBuffer, UINT32 nDWordsToRead)
      {
      	BOOL bSuccess = 0;
      
      	// Check for the count zero and skip remaining
      	if(nDWordsToRead == 0)
      		return 1;
      
      	// Flash specific read implementation
      
      }   // End usrReadFlashMemory