NetBurner 3.1
EFFS-STD File System with On-chip Flash

Using the EFFS-STD File System with On-chip Flash

EFFS-FAT vs. EFFS-STD

The previoius sections of this guide have focused on the EFFS-FAT file system, which is a FAT32 file system used for external flash cards. The EFFS-STD file system uses the on-chip flash memory of your NetBurner device. It has a different set of libraries and functions than the EFFS-FAT file system. In most cases the differences between the EFFS-STD and EFFS-FAT are simply a change in functioncall prefix from f_ to fs_. For example, the EFFS-FAT function call f_open() is fs_open() for EFFS-STD. A list of the documented functions can be found at STD File System.

Overview

When using the on-chip flash you need to be aware that the flash will be shared between your application and the file system. You will need to specify the amount of space to be used by the file system, while making sure you leave enough room for your application. The amount of flash used by your application is displayed each time you compile. You want to use the compressed number, not the uncompressed. You certainly want to leave enough additional space so your application can grow.

The flash memory chip will be divided into sectors, typically 4k or 64k bytes in size. The EFFS-STD file system requires that you allocate a number of these sectors to be used by the file system. Please review the data sheet for the flash memory used on your NetBurner device so you are familiar with the architecture. The configuration settings are dependant on the specific flash chip you are using.

Warning: Incorrect settings can erase the NetBurner boot monitor!

Examples

The following is a short reference for the different example applications that utlize EFFS-STD, and what their primary function is.

Standard STD EFFS Usage

pageExamples-EFFS-Std - This program sets up HTTP access to the STD file system, and shows how web pages can be served from the file system, and override compiled in versions.

EFFS STD With NetBurner's Security Library

SSL Https Upload Cert - This program will demonstrate how to upload certificates and keys to support SSL/TLS web page access and store them in the EFFS-STD file system.
SSL Verify Peer EFFS-STD - This program will demonstrate how to upload CA Lists to use in support of verify peer, and store them in the EFFS-STD file system.

Project Settings

To create a project that uses the EFFS-STD file system, you will need to complete a few extra steps in addition to your normal project setup.
For NBEclipse users:

  • Modify the COMPCODEFLAGS to match the new memory space of the application. The remaining space will be used for the file system. The format of the COMPCODEFLAGS setting is: COMPCODEFLAGS <start address> <end address>.
  • Add the EFFS-STD library to the linker path:
    <nburn_install>/platform/<platform>/original/lib/libStdFFile.a
  • Import the source files found here into your project:
    <nburn_install>examples\_common\EFFS\STD

    For projects that use the command line tools:
  • Add the following lines to your makefile:
    XTRALIB = c:/platform/SB72EX/original/lib/libStdFFile.a
    include c:/examples/_common/EFFS/STD/common.mak

Flash Memory Addresses

The flash memory on your NetBurner device is used for the Boot Monitor, System Parameter Storage, User Parameter Storage, Application, and now the EFFS-STD file system. A table of memory sizes for NetBurner platforms at the time of this writing is shown below. The example column illustrates one possible configuration. You can modify the parameters to suit your requirements. The COMPCODE flag starting address specifies the starting memory location of your application. The end address specifies the end location of the application. You should not modify the starting address! The Boot Monitor, Configuration Record and User Parameters occupy the space between the start of flash memory address and the start of the application memory address. You will only need to modify the end address to represent the amount of memory allocated for the flash file system.

Platform Total Size in Bytes Start Address End Address Configuration Definition Example
MODM7AE70 2MB 0x00400000 0x005FFFFF Example for 512K flash file system
Application must begin at 0x0040600
COMPCODEFLAGS = 0x00406004 0x005A0000
#define FLASH_SIZE ( 2*1024*1024 ) // Total flash size
#define FS_SIZE ( 256*512 ) // Size of filesystem

Configuration File for SAME70Q21

The configuration section of the file SAME70Q21.h is shown below. The file system will the specified number of physical flash sectors for file storage and management.

// Start of Flash memory base address
#define FS_FLASHBASE (0x00400000)
/*
* BLOCKSIZE
* This defines the size of the blocks to be used in the file storage area.
* This must be an erasable unit of the flash chip. All blocks in the file
* storage area must be the same size. This maybe different from the DESCSIZE
* where the flash chip has different size erasable units available.
* SECTORSIZE
* This defines the sector size. Each block is divided into a number of sectors.
* This number is the smallest usable unit in the system and thus represents the
* minimum file storage area. For best usage of the flash blocks the sector size
* should always be a power of 2. For more information see sector section below.
* SECTORPERBLOCK
* This defines the number of sectors in a block. It must always be true that:
* SECTORPERBLOCK = BLOCKSIZE/SECTORSIZE
* The memory map below is for a MODM7AE70 with a 2MB bottom boot block flash.
* This example will allocate 1.5MB for the application space, and 512KB for
* the file system.
* Microchip SAME70Q21:
* The memory is organized in sectors. Each sector has a size of 128 Kbytes. The
* first sector is divided into 3 smaller sectors. The three smaller sectors are
* organized in 2 sectors of 8 Kbytes and 1 sector of 112 Kbytes.
* Total number of bytes for storage: 2,097,152. Applicatin space: 1.97MB max.
* Address
* ----------
* ---------------------- 005F FFFF (End of flash space)
* | File System Data |
* | 256KB |
* | 128K x 2 Blocks |
* |--------------------| 005C 0000 (Start of File System Data)
* | DESC BLOCK 0/1 |
* | 128K x 2 Blocks |
* |--------------------| 0058 0000 (Start of File System)
* | |
* | Application |
* | 1.375MB |
* | 128K x 11 Blocks |
* | |
* |--------------------| 0040 6004
* | 8K User Params |
* |--------------------| 0040 4000
* | 10K Configuration |
* |--------------------| 0040 1800
* | 6K Monitor |
* |--------------------| 0040 0000 (Start of Flash space)
* CHANGES TO COMPCODE FLAGS
* In NBEclipse, or your command line makefile, change the following line
* so the application will only occupy the specified application space.
* The first parameter is the start of application space, and the second
* is the address just below the file system space.
* COMPCODEFLAGS = 0x00406004 0x005A0000
* If using NBEclipse:
* - Right-click on the project and select "Properties"
* - Select "NetBurner" in the left side of the dialog box
* - Verify the Platform is set to Mod5234, then check the "Use Custom Platform Settings" checkbox
* - Modify the "Compcode Memory Range" to the above values
* If using NBEclipse, you will also need to tell the linker to include the
* /nburn/platform/<platform>/original/lib/libStdFFile.a library. To do this right-click on your
* project, select properties, GNU Linker, then add the library.
*/
/* WARNING: These settings are for MX29GL256F bottom boot block flash
* components used on the Mod54415
*/
#define BLOCKSIZE ( 16*512 ) // flash physical "sector" size
#define SECTORSIZE ( 512 ) // file system sectors per BLOCK
#define SECTORPERBLOCK (BLOCKSIZE/SECTORSIZE)
/*
* Specify the total amount of flash memory in the system, and the amount
* allocated to be used by the file system (the rest is used by the
* application.
*/
#define FLASH_SIZE ( 2*1024*1024 ) // size of total flash in the system, 32MB
#define FS_SIZE ( 256*512 ) // amount allocated to file system: 2 Desc. plus 1MB for data (8 x 128k)
// note that 1 block of file data will be reserved for the file system
#define FIRST_ADDR (FLASH_SIZE - FS_SIZE) // first file system address to use in the flash
#define BLOCKSTART 2 // first block where file system data starts
// (first 2 blocks are DESCRIPTORS)
/*
* Descriptor Blocks:
* These blocks contain critical information about the file system, block allocation,
* wear information and file/directory information. At least two descriptor blocks
* must be included in the system, which can be erased independently. An optional
* descriptor write cache may be configured which improves the performance of the
* file system. Please refer to the EFFS-STD implementation guide for additional
* information.
*/
#define DESCSIZE ( 16*512 ) // size of one descriptor
#define DESCBLOCKSTART 0 // position of first descriptor
#define DESCBLOCKEND 1 // position of last descriptor
#define DESCCACHE 1024