NetBurner EFFS Programming Guide

Overview

This guide covers the NetBurner implementation of the HCC Embedded Flash File System (EFFS) and NetBurner flash card hardware interface. EFFS provides file system capabilities for both external flash cards (EFFS-FAT) and on-chip flash memory (EFFS-STD).

Topics Covered

Example programs and supported platforms
EFFS-FAT file system for external flash cards
EFFS-STD file system for on-chip flash memory
Hardware interface design for external flash cards
Debug port configuration

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    NetBurner Platform                       │
│                                                             │
│  ┌────────────────────┐         ┌────────────────────────┐  │
│  │   EFFS-FAT         │         │   EFFS-STD             │  │
│  │   (External)       │         │   (On-chip)            │  │
│  │                    │         │                        │  │
│  │  External Flash    │         │  Internal Flash        │  │
│  │  Card (SD/MMC)     │         │  Memory                │  │
│  │                    │         │                        │  │
│  │  FAT32 Format      │         │  Custom Format         │  │
│  │  Up to 32GB        │         │  Platform Dependent    │  │
│  └────────┬───────────┘         └──────────┬─────────────┘  │
│           │                                │                │
│           v                                v                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │            Application Layer (User Code)               │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Supported Platforms

Platform Capabilities Matrix

┌──────────────┬─────────────────┬─────────────────┐
│   Platform   │    External     │    On-board     │
│              │  Flash Card     │   Flash Card    │
├──────────────┼─────────────────┼─────────────────┤
│ MODM7AE70    │  SPI            │  N/A            │
├──────────────┼─────────────────┼─────────────────┤
│ MOD54415     │  SPI            │  SPI            │
├──────────────┼─────────────────┼─────────────────┤
│ MOD54417     │  SPI            │  SPI            │
├──────────────┼─────────────────┼─────────────────┤
│ SB800EX      │  SDIO           │  -              │
├──────────────┼─────────────────┼─────────────────┤
│ NANO54415    │  SPI            │  SDIO           │
└──────────────┴─────────────────┴─────────────────┘
 
Note: All platforms support EFFS-STD on-chip flash file system

Interface Types

SPI Mode**: Serial Peripheral Interface

Single data channel operation
Lower data transfer rates
Simpler hardware implementation

SDIO Mode**: Secure Digital Input/Output
Four parallel data channels
Higher data transfer rates
More complex hardware design

Example Programs

EFFS-FAT Examples

Located at: \nburn\examples\EFFS\Fat

Available examples demonstrate:

Simple file storage operations
FTP server integration
HTTP server with file system
HTTP with variable tags
Multi-task file system access
RAM drive implementation
Application updates from flash

EFFS-FAT Security Examples

Advanced security implementations:

HttpsDualCert**

Dual certificate support (compiled-in and SD card-based)
Dynamic certificate loading from EFFS-FAT
Web server SSL/TLS configuration

SSL_pop3**
Secure email retrieval via SSL
Email storage to SD/MMC flash card
POP3 protocol implementation

SendMailAttach**
File attachment from EFFS-FAT
Secure email transmission with SSL/TLS
SMTP integration

EFFS-STD Examples

Located at: \nburn\examples\EFFS\Std

HTTP Example**

Web page serving from STD file system
Application-level page serving
File system override capability

Security Examples** (\nburn\examples\SSL)

HttpsUploadCert**
Certificate and key upload via web interface
SSL/TLS credential storage in EFFS-STD

SslVerifyPeerEffs**
CA List upload and storage
Peer verification support
Certificate authority management

Flash Card Hardware Interface

SD/MMC Hardware Connection Diagram

        NetBurner Module
┌───────────────────────────────┐
│                               │
│  QSPI Interface               │
│  ┌─────────────────────┐      │
│  │                     │      │
│  │  CLK >──────────────┼──────┼─> Pin 5 (CLK)
│  │  DOUT >─────────────┼──────┼─> Pin 2 (DI)
│  │  DIN <──────────────┼──────┼─< Pin 7 (DO)
│  │                     │      │
│  └─────────────────────┘      │
│                               │
│  GPIO Pins                    │
│  ┌─────────────────────┐      │
│  │                     │      │
│  │  J2-35 >────10k─────┼──────┼─> Pin 1 (/CS)
│  │  J2-47 <────10k─────┼──────┼─< Pin D (CD)
│  │  J2-40 <────10k─────┼──────┼─< Pin W (WP)
│  │                     │      │
│  └─────────────────────┘      │
│                               │
│  Power                        │
│  VCC 3.3V >─────────────────────> Pin 4 (VCC)
│  GND >──────────────────────────> Pin 3,6 (GND)
│                               │
└───────────────────────────────┘
                                      SD/MMC Card

Signal Connection Table

┌───────────┬────────────────────┬──────────────────────────────┐
│  SD/MMC   │   Signal Name      │   NetBurner Connection       │
│   Pin     │                    │                              │
├───────────┼────────────────────┼──────────────────────────────┤
│     1     │  /CS (Chip Select) │  J2-35 (10k pull-up)         │
├───────────┼────────────────────┼──────────────────────────────┤
│     2     │  DI (Data In)      │  J2-28 (QSPI DOUT)           │
├───────────┼────────────────────┼──────────────────────────────┤
│     3     │  GND               │  Ground                      │
├───────────┼────────────────────┼──────────────────────────────┤
│     4     │  VCC               │  VCC 3.3V                    │
├───────────┼────────────────────┼──────────────────────────────┤
│     5     │  CLK               │  J2-J5 (QSPI CLK)            │
├───────────┼────────────────────┼──────────────────────────────┤
│     6     │  GND               │  Ground                      │
├───────────┼────────────────────┼──────────────────────────────┤
│     7     │  DO (Data Out)     │  J2-J7 (QSPI DIN)            │
├───────────┼────────────────────┼──────────────────────────────┤
│     8     │  NC                │  No Connection               │
├───────────┼────────────────────┼──────────────────────────────┤
│     9     │  NC                │  No Connection               │
├───────────┼────────────────────┼──────────────────────────────┤
│     D     │  CD (Card Detect)  │  J2-47 (10k pull-up)         │
├───────────┼────────────────────┼──────────────────────────────┤
│     W     │  WP (Write Protect)│  J2-40 (10k pull-up)         │
├───────────┼────────────────────┼──────────────────────────────┤
│    Com    │  Common            │  Ground                      │
└───────────┴────────────────────┴──────────────────────────────┘
 
Note: GPIO pins (CS, CD, WP) are configurable in mmc_m7.cpp 
      or mmc_mcf.cpp depending on platform

Hardware Specifications

SD/MMC Connector**: Mouser Electronics Part # 688-SCDA1A0901

Card Compatibility**:

Must support native SPI mode transfers
Standard SD/MMC: Up to 2GB
SDHC: Up to 32GB

SPI Interface Requirements**:
EFFS normally requires exclusive use of SPI interface
Sharing SPI with other peripherals is not officially supported
Exclusive use recommended for optimal performance

GPIO Pin Configuration

Configure interface control pins in platform-specific files:

MODM7AE70**: \nburn\platform\<platform>\mmc_m7.cpp Other Platforms**: \nburn\platform\<platform>\mmc_mcf.cpp

Key functions to modify:

void MMC_BaseInit(int CurrentDrive)  // Configure SD/MMC interface pins
int get_cd(int currentDrive)         // Get Card Detect state
int get_wp(void)                     // Get Write Protect state
void spi_cs_lo(void)                 // Set SPI chip select low
void spi_cs_hi(void)                 // Set SPI chip select high

Interrupt-Driven SPI (ColdFire Platforms Only)

For MOD5441X, SB800EX, and NANO54415 platforms:

Enable interrupt-driven SPI for improved system performance at the cost of slightly lower SD/MMC performance. This is beneficial when network or user tasks need priority during file system access.

Configuration**: Uncomment in \nburn\platform\<platform>\mmc_mcf.cpp:

#define SD_IRQ_SPI

Then rebuild the platform system directory.

EFFS-FAT File System Operation

Typical Operation Flow

    Start
      |
      v
┌─────────────┐
│ f_enterFS() │  Create working directory for task
└──────┬──────┘
       |
       v
┌──────────────────┐
│ f_mountfat()     │  Mount flash card
└────────┬─────────┘
         |
         v
    ┌────────────────┐
    │ File Operations│
    └────────┬───────┘
             |
    ┌────────┴────────────────────────────┐
    |                                     |
    v                                     v
┌─────────┐                          ┌─────────┐
│ f_open()│                          │Directory│
└────┬────┘                          │Operations│
     |                               └────┬────┘
     v                                    |
┌──────────┐                              v
│ f_read() │                      ┌──────────────┐
│ f_write()│                      │ f_findfirst()│
│ f_seek() │                      │ f_findnext() │
└────┬─────┘                      │ f_chdir()    │
     |                            │ f_mkdir()    │
     v                            └──────────────┘
┌─────────┐
│f_close()│
└────┬────┘
     |
     v
┌───────────────┐
│ f_delvolume() │  Dismount flash card
└───────┬───────┘
        |
        v
┌──────────────┐
│ f_releaseFS()│  Release working directory
└──────────────┘
        |
        v
      End

Common EFFS-FAT Function Calls

Working Directory Management

int f_enterFS(void); // Create working directory for current task

void f_releaseFS(void); // Release working directory

Mount/Dismount Operations

int f_mountfat(MMC_DRV_NUM, mmc_initfunc, F_MMC_DRIVE0); // Mount flash card

int f_delvolume(int drivenum); // Dismount flash card

File Operations

F_FILE *f_open(const char *filename, const char *mode); // Open file

int f_close(F_FILE *filehandle); // Close file

f_close

#define f_close(filehandle)

Closes an opened file.

Definition api_f.h:487

Read/Write Operations

int f_getfreespace(int drivenum, F_SPACE *pspace);
long f_write(const void *buf, long size, long size_st, F_FILE *filehandle);
long f_read(void *buf, long size, long size_st, F_FILE *filehandle);
long f_seek(F_FILE *filehandle, long offset, long whence);
int f_eof(F_FILE *filehandle);
int f_rewind(F_FILE *filehandle);
int f_delete(const char *filename);

Directory Operations

int f_findfirst(const char *filename, F_FIND *find);
int f_findnext(F_FIND *find);
int f_chdir(const char *dirname);
int f_mkdir(const char *dirname);

Time/Date Functions

int f_settimedate(const char *filename, unsigned short ctime, unsigned short cdate);

int f_gettimedate(const char *filename, unsigned short *pctime, unsigned short *pcdate);

f_settimedate

#define f_settimedate(filename, ctime, cdate)

Set the time and date of a file or directory.

Definition api_f.h:601

f_gettimedate

#define f_gettimedate(filename, pctime, pcdate)

Get the time and date of a file or directory.

Definition api_f.h:589

File Time and Date Stamps

EFFS supports file time and date stamps obtained through:

Network Time Protocol (NTP) server
Real-Time Clock (RTC)
Manual configuration

Note**: If no time/date is set, files will be stamped with January 1, 1980.

File System Utilities

All NetBurner EFFS examples include FileSystemUtils.cpp providing:

Easy-to-use initialization interface
Status checking functions
Testing utilities
Read/write helpers

Location**:
FAT utilities: <nburn_install>\examples\_common\EFFS\FAT
STD utilities: <nburn_install>\examples\_common\EFFS\STD

Card Type Selection**: Edit cardtype.h to select between CF or SD/MMC cards.

EFFS-FAT Project Configuration

NBEclipse Project Setup

Step 1: Add EFFS-FAT Library

Right-click project in Project Explorer
Navigate to: C/C++ Build > Settings > GNU C/C++ Linker > Libraries
Add "FatFile" to Libraries (-l) list

Step 2: Import Source Files

Import files from: <nburn_install>\examples\_common\EFFS\FAT

Makefile Configuration

Add the following lines to your project makefile:

XTRALIB = $(NNDK_ROOT)/platform/$(PLATFORM)/original/lib/libFatFFile.a

include $(NNDK_ROOT)/examples/_common/EFFS/FAT/common.mak

EFFS-STD File System (On-Chip Flash)

EFFS-FAT vs EFFS-STD Comparison

┌──────────────┬─────────────────────┬─────────────────────┐
│   Feature    │     EFFS-FAT        │     EFFS-STD        │
├──────────────┼─────────────────────┼─────────────────────┤
│  Storage     │  External Flash     │  On-chip Flash      │
│              │  Card (SD/MMC)      │  Memory             │
├──────────────┼─────────────────────┼─────────────────────┤
│  Format      │  FAT32              │  Custom             │
├──────────────┼─────────────────────┼─────────────────────┤
│  Size        │  Up to 32GB         │  Platform Dependent │
├──────────────┼─────────────────────┼─────────────────────┤
│  Functions   │  f_* prefix         │  fs_* prefix        │
│              │  (e.g., f_open())   │  (e.g., fs_open())  │
├──────────────┼─────────────────────┼─────────────────────┤
│  Library     │  libFatFile.a       │  libStdFFile.a      │
├──────────────┼─────────────────────┼─────────────────────┤
│  Removable   │  Yes                │  No                 │
└──────────────┴─────────────────────┴─────────────────────┘

Flash Memory Layout

Flash Memory Map
┌────────────────────────────────────────────┐ 0x00000000
│                                            │
│           Boot Monitor                     │
│                                            │
├────────────────────────────────────────────┤
│                                            │
│        System Parameters                   │
│                                            │
├────────────────────────────────────────────┤
│                                            │
│         User Parameters                    │
│                                            │
├────────────────────────────────────────────┤ Application Start
│                                            │ (COMPCODE start)
│                                            │
│                                            │
│          Application Code                  │
│                                            │
│                                            │
├────────────────────────────────────────────┤ File System Start
│                                            │ (COMPCODE end)
│                                            │
│       EFFS-STD File System                 │
│                                            │
│                                            │
└────────────────────────────────────────────┘ End of Flash

Memory Allocation Considerations

When using EFFS-STD, you must:

Determine application code size (use compressed size from build output)
Allocate flash sectors for file system
Ensure sufficient room for application growth
Configure COMPCODE flags to define memory boundaries

Flash memory is divided into sectors (typically 4KB or 64KB). The EFFS-STD file system requires allocation of specific sectors. Consult your platform's flash memory datasheet for architecture details.

EFFS-STD Project Configuration

NBEclipse Configuration

Step 1: Import Source Files

Import from: <nburn_install>\examples\_common\EFFS\STD

Step 2: Add EFFS-STD Library

Right-click project
Navigate to: C/C++ Build > Settings > GNU C/C++ Linker > Libraries
Add "StdFFile" to Libraries section (no .a extension)

Step 3: Platform-Specific Configuration

MODM7AE70, SBE70LC Platforms

Enable "Locate Application at Fixed Address in Flash":

Right-click project > Properties
Navigate to: C/C++ Build > Settings > NB Flashpack > General
Check "Locate Application at Fixed Address in Flash"

Purpose**: Disables background flash erase to preserve file system sectors

NANO54415, SB800EX Platforms

Modify CompCode flags to reserve file system space:

Right-click project
Navigate to: C/C++ Build > Settings > NBCompCode > General
Change memory address range:

Original: COMPCODEFLAGS = 0x04000 0x800000

Modified: COMPCODEFLAGS = 0x04000 0x700000

Parameters**:

First address: Application start
Second address: File system start

MOD54415, MOD54417 Platforms

Modify CompCode flags:

Right-click project
Navigate to: C/C++ Build > Settings > NBCompCode > General
Change memory address range:

Original: COMPCODEFLAGS = 0xC0040000 0xC2000000

Modified: COMPCODEFLAGS = 0xC0040000 0xC1F00000

EFFS-STD Makefile Configuration

Step 1: Add EFFS-STD Library

XTRALIB = $(NNDK_ROOT)/platform/$(PLATFORM)/original/lib/libStdFFile.a

DBXTRALIB = $(NNDK_ROOT)/platform/$(PLATFORM)/original/lib/libStdFFile.a

Step 2: Platform-Specific Configuration

MODM7AE70, SBE70LC

Enable fixed application address:

EXTRAPACKARGS += -cflag C:3

NANO54415, SB800EX

Modify memory address range:

# Original
COMPCODEFLAGS = 0x04000 0x800000
 
# Modified for file system
COMPCODEFLAGS = 0x04000 0x700000

MOD54415, MOD54417

Modify memory address range:

# Original
COMPCODEFLAGS = 0xC0040000 0xC2000000
 
# Modified for file system
COMPCODEFLAGS = 0xC0040000 0xC1F00000

Flash Memory Address Configuration

Platform Memory Map

┌──────────────┬─────────────┬──────────────┬─────────────┬───────────────────────────────┐
│   Platform   │  Total Size │Start Address │ End Address │   Configuration Example       │
├──────────────┼─────────────┼──────────────┼─────────────┼───────────────────────────────┤
│  MODM7AE70   │    2MB      │  0x00400000  │ 0x005FFFFF  │  512K Flash File System:      │
│              │             │              │             │                               │
│              │             │              │             │  Application: 0x00406004      │
│              │             │              │             │  File System: 0x005A0000      │
│              │             │              │             │                               │
│              │             │              │             │  COMPCODEFLAGS =              │
│              │             │              │             │    0x00406004 0x005A0000      │
│              │             │              │             │                               │
│              │             │              │             │  #define FLASH_SIZE           │
│              │             │              │             │    (2*1024*1024)              │
│              │             │              │             │  #define FS_SIZE (256*512)    │
└──────────────┴─────────────┴──────────────┴─────────────┴───────────────────────────────┘

Memory Region Diagram

MODM7AE70 Flash Memory (2MB Total)
┌────────────────────────────────┐ 0x00400000
│      Boot/System (24KB)        │
├────────────────────────────────┤ 0x00406004
│                                │
│                                │
│   Application Code Space       │
│                                │
│                                │
├────────────────────────────────┤ 0x005A0000
│                                │
│   EFFS-STD File System         │
│         (512KB)                │
│                                │
└────────────────────────────────┘ 0x005FFFFF

Configuration File Reference

For SAME70Q21 platform configuration details, refer to: \nburn\examples\_common\EFFS\STD\src\flashChip\SAME70Q21.h

Debug Port Configuration

Overview

The debug port is an RS-232 serial port used for interactive communication with your NetBurner device during development and testing.

Default Configuration

By default, the debug port has the following mappings:

┌──────────────────────────────────────────┐
│        Standard I/O Mappings             │
│                                          │
│  stdout  >  Debug Port (console output)  │
│  stdin   >  Debug Port (console input)   │
│  stderr  >  Debug Port (error output)    │
│                                          │
└──────────────────────────────────────────┘

Supported Functions

Standard C/C++ I/O functions work with the debug port:

printf()   // Formatted output to debug port
scanf()    // Formatted input from debug port
gets()     // Read string from debug port
puts()     // Write string to debug port
getchar()  // Read single character
putchar()  // Write single character

Custom Configuration

The debug port is fully configurable:

Option 1**: Disable and use as general-purpose UART

Frees port for custom communication protocols
Suitable for production deployments

Option 2**: Reassign stdio descriptors
Route stdout/stdin/stderr to network interfaces
Use telnet or SSH for remote debugging
Implement custom logging mechanisms

Option 3**: Multiple debug interfaces
Combine serial and network debug output
Create redundant logging paths
Support simultaneous local and remote debugging

API Reference Documentation

EFFS-FAT API Reference

Complete function documentation located at: \nburn\docs\NetBurner\EFFS

EFFS-STD API Reference

Detailed function documentation available in NetBurner documentation under @ref groupEFFSSTD

Key Function Mapping

┌─────────────────────┬────────────────────┐
│    EFFS-FAT         │    EFFS-STD        │
│   (External)        │   (On-chip)        │
├─────────────────────┼────────────────────┤
│  f_enterFS()        │  fs_enterFS()      │
│  f_releaseFS()      │  fs_releaseFS()    │
│  f_open()           │  fs_open()         │
│  f_close()          │  fs_close()        │
│  f_read()           │  fs_read()         │
│  f_write()          │  fs_write()        │
│  f_seek()           │  fs_seek()         │
│  f_delete()         │  fs_delete()       │
│  f_chdir()          │  fs_chdir()        │
│  f_mkdir()          │  fs_mkdir()        │
└─────────────────────┴────────────────────┘

Best Practices

General Guidelines

Always check return values from file system functions
Close files properly to prevent data loss
Handle card removal gracefully in EFFS-FAT applications
Reserve adequate flash space for EFFS-STD file systems
Test with actual hardware before production deployment

EFFS-FAT Specific

Verify card is inserted before mounting
Implement card detect monitoring in applications
Handle write-protect status appropriately
Use proper file modes for read/write operations
Dismount volumes before card removal when possible

EFFS-STD Specific

Calculate application size carefully
Leave room for application growth
Understand flash sector architecture
Consider wear leveling implications
Don't exceed allocated file system space

Performance Optimization

Use interrupt-driven SPI when system responsiveness is critical
Batch file operations when possible
Minimize file open/close cycles
Use appropriate buffer sizes for read/write operations
Consider RAM drive for frequently accessed temporary files

Troubleshooting

Common EFFS-FAT Issues

Card Not Detected**

Check physical connections
Verify power supply (3.3V)
Confirm card detect pin configuration
Test with known-good card

Mount Failures**
Ensure card is formatted FAT32
Verify card capacity limits (2GB for standard, 32GB for SDHC)
Check SPI interface configuration
Confirm correct initialization sequence

Read/Write Errors**
Check write-protect status
Verify sufficient free space
Ensure proper file handles
Confirm correct file modes

Common EFFS-STD Issues

Insufficient Space**

Recalculate application size
Adjust COMPCODE flags
Reduce file system allocation if needed
Verify compressed vs uncompressed size

Flash Erase Conflicts**
Ensure fixed address mode enabled (MODM7AE70/SBE70LC)
Check memory map configuration
Verify sector boundaries
Confirm no overlap with application space

File System Corruption**
Avoid power interruption during writes
Implement proper shutdown sequences
Check flash wear level
Verify sector allocation

Additional Resources

Documentation References

EFFS API Reference: \nburn\docs\NetBurner\EFFS
Platform Data Sheets: Consult for flash memory specifications
Hardware Schematics: Development board design references
Example Applications: \nburn\examples\EFFS

Support Files

FileSystemUtils.cpp: Common utilities for all examples
cardtype.h: Flash card type selection
Platform-specific mmc_*.cpp: Hardware interface configuration
Flash chip headers: Platform memory configuration

Example Locations

\nburn\examples\
  ├── EFFS\
  │   ├── FAT\        > EFFS-FAT examples
  │   └── STD\        > EFFS-STD examples
  ├── SSL\            > Security examples with EFFS
  └── _common\
      └── EFFS\
          ├── FAT\    > Shared FAT utilities
          └── STD\    > Shared STD utilities

Summary

The NetBurner EFFS provides robust file system capabilities for embedded applications:

EFFS-FAT: External flash card storage with FAT32 compatibility
EFFS-STD: On-chip flash storage with custom format
Easy Integration: Well-documented APIs and extensive examples
Flexible Hardware: Multiple platform support with various interfaces
Security Ready: Integration with NetBurner security libraries

Choose EFFS-FAT for removable storage and large capacity requirements. Choose EFFS-STD for integrated, non-volatile storage in resource-constrained applications.

Both file systems provide reliable, production-ready storage solutions for NetBurner embedded systems.