Introduction

Flash File System

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.

...

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

...

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.

...

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

Note: Start of Data Address is ignored and the actual start address is derived from the start of the file data in flash address.

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

Code Block
#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

...

Attribute	Value
LOAD_IMAGE	0x01
STARTUP_FILE	0x02
DATA_FILE	0x04
COMPILED_SCRIPT	0x08
COMMAND_SCRIPT	0x10
PRESET_SCRIPT	0x20
COMPILED_PRESET_SCRIPT	0x28
LOADER_FILE	0x40
FILE_DELETED	0x80

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

Code Block
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.

Code Block
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.

Code Block
/** 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.

Code Block
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 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

File Name	Description	Location
AweFlashFileSystem.c	File that contains all of the functions related to Flash File System	\awecore-common\Source\CFramework\AWEInstance\FlashFileSystem
AweFlashFileSystemPacketAPI.c	File that contains all of the Flash File System related PFID’s handling	\awecore-common\Source\CFramework\AWEInstance\FlashFileSystem
fw_FlashFSInstance.h	File that contains all of the function prototypes and definitions related to Flash File System	\awecore-common\Include
TestAweFlashFileSystem.cpp	File that contains unit tests related to each Flash File System function	\awecore-common\Source\CFramework\Test
test_awe_packetProcess.c	File that contains integration tests for Flash File System PFID’s	\awecore-common\Source\Test

Flash File System (AweFlashFileSystem.c) API Description

...

awe_fwInitFlashFileSystem

Prototype:

Code Block
BOOL awe_fwInitFlashFileSystem(AWEFlashFSInstance * pAWEFlashFSInstance)

Verify callbacks are defined in the AWEFlashFSInstance structure.
Initialize the flashAttributes member of AWEFlashFSInstance structure with default values.
Read from the beginning of the dedicated file system flash memory and look for signature bytes “AW”.
If the signature bytes are found update the flashAttributes with the values found in flash.
Read through the file directory updating the count of non-deleted files as well as the count of data words in use.
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:

Code Block
INT32 awe_fwGetFirstFile(AWEFlashFSInstance * pAWEFlashFSInstance,

...


                                                              PDIRECTORY_ENTRY * pDirEntry)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

...

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:

Code Block
INT32 awe_fwGetNextFile(AWEFlashFSInstance *

...

Arguments:

...

 pAWEFlashFSInstance, 
                                                               PDIRECTORY_ENTRY * pDirEntry)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

...

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:

Code Block
INT32 awe_fwOpenFile(AWEFlashFSInstance *

...

 pAWEFlashFSInstance,
                                                          UINT32 nFileAttribute, 
                                                          UINT32 * pFileNameInDWords,
                                                          UINT32 * nFileLenInDWords)

Arguments:

pAWEFlashFSInstance - Flash File System instance pointer.

...

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:

Code Block
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)

...

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,

...

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)

...

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)

...

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)

...

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,

...

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)

...

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,

...

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 * pFileNameInDWords,
UINT32 * nStartingAddress,
UINT32 * nFileLenInDWords)

...

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)

...

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)

...

Initializes internal Flash File System structure to default state.

Returns:
E_SUCCESS

awe_fwAllocateBlock

Prototype: BOOL awe_fwAllocateBlock(AWEFlashFSInstance * pAWEFlashFSInstance, UINT32 nAddress)

...

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)

...

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,

...

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)

...

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)

...

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

...

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.

Command Packet

Command ID

N data words

CRC

Command ID List

PFID_FileSystemReset

PFID_GetFirstFile

PFID_GetNextFile

PFID_OpenFile

PFID_ReadFile

PFID_WriteFile

PFID_CloseFile

PFID_DeleteFile

PFID_ExecuteFile

PFID_EraseFlash

PFID_GetFileSystemInfo

PFID_Get_Flash_Erase_Time

...

Version	Old Version 1	New Version 2
Changes made by	Matthew Mitschang	Matthew Mitschang
Saved on	Jan 10, 2023	Jan 10, 2023

Page Comparison

Versions Compared

Key

Introduction

Flash File System

Design Assumptions, Constraints and Dependencies

File Allocation Blocks

File Header Info

Allocation Table Bitmap

File Directory

Directory Entry Definition

Directory Entry File Info Word

Flash File System Memory layout

DIRECTORY_ENTRY Structure

FileSystemInfo Structure

FSAttributes Structure

Flash File System Low Level Driver

BOOL cbEraseSector(UINT32 nStartingAddress, UINT32 nNumberOfSectors)

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

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

INT32 cbFlashProcessCmd(AWEInstance *pAWE)

Software Functions (or units)

File Location

Flash File System (AweFlashFileSystem.c) API Description

awe_fwInitFlashFileSystem

awe_fwGetFirstFile

awe_fwGetNextFile

awe_fwOpenFile

awe_fwCloseFile

awe_fwWriteFile

awe_fwReadFile

awe_fwDeleteFile

awe_fwFindFile

awe_fwEraseFlash

awe_fwExecuteFile

awe_fwExecuteFlashFiles

awe_fwReadFileMem

awe_fwGetFileMemStartingAddress

awe_fwGetFileAttribute

awe_initFlashFS

awe_fwResetFileSystem

awe_fwAllocateBlock

GetFileNameLengthInDWords

awe_fwGetFileSystemInfo

awe_fwFlashFileSystemCommandHandler

awe_fwInitFFS