VxWorks NAND Flash and TrueFFS Architecture Guide

VxWorks NAND Flash and TrueFFS Architecture Guide

VxWorks provides flash storage support through TrueFFS (True Flash File System), which abstracts raw flash devices through a layered architecture involving Memory Technology Drivers (MTDs) and Translation Layers (TLs).

For NAND flash, this abstraction is more complicated than a conventional block-device interface because NAND requires page-oriented access, spare-area management, bad-block handling, and error detection and correction (ECC). The translation layer must convert these physical characteristics into a logical sector interface that higher-level VxWorks storage components can consume.

A simplified architecture is:

                 VxWorks File System
                         |
                         v
                  Block Device Layer
                         |
                         v
                      TrueFFS
                         |
              +----------+----------+
              |                     |
              v                     v
      Translation Layer          MTD
       SSFDC / NFTL          NAND Hardware
              |                     |
              +----------+----------+
                         |
                         v
                  Raw NAND Flash

The most important engineering constraint is that TrueFFS NAND support is tightly coupled to the flash geometry and translation-layer format. A driver that can physically access a larger NAND device does not automatically mean that the native translation layer can address and manage its entire capacity.

🧱 NOR vs. NAND Flash Architecture

#

NOR and NAND are both non-volatile flash technologies, but their electrical interfaces, access granularity, endurance characteristics, and software requirements differ substantially.

Exact density, endurance, page size, erase-block geometry, and timing vary significantly between generations and NAND types. Therefore, NAND driver logic should derive geometry from the actual device rather than assuming fixed values.

💾 TrueFFS NAND Support Model

#

TrueFFS separates flash support into two major layers.

Memory Technology Driver

#

The MTD provides the hardware-specific interface to the flash device.

For NAND, the MTD typically handles:

• Command sequencing
• Address cycles
• Page reads
• Page programming
• Block erasure
• Spare-area access
• Bad-block detection
• ECC operations
• Device status handling

The MTD therefore understands the physical NAND geometry.

Translation Layer

#

The Translation Layer (TL) converts the physical flash organization into a logical block-device model.

Conceptually:

Logical Sector
      |
      v
Translation Layer
      |
      +--> Logical-to-physical mapping
      +--> Block management
      +--> Metadata
      +--> Wear / replacement handling
      |
      v
      MTD
      |
      v
Physical NAND Page / Block

This separation is important because modifying an MTD can increase the range of physical addresses accessible to the system without necessarily increasing the addressable capacity of the translation layer.

📐 SSFDC and Small-Page NAND

#

The native VxWorks TrueFFS NAND implementation described by the SSFDC path is based around the small-page NAND model.

The traditional geometry is:

Main Area:     512 bytes
Spare Area:     16 bytes
-----------------------
Total Page:    528 bytes

The spare area is not simply unused storage. It can contain metadata required by the translation layer, including information used for:

• Bad-block identification
• Logical block mapping
• Write-status markers
• ECC-related information

This architecture creates an important compatibility boundary: a translation layer designed around 512-byte pages and 16-byte spare areas cannot automatically manage newer large-page NAND devices with different physical geometries.

⚠️ Large-Page NAND Limitation

#

Modern NAND devices commonly use larger page sizes, such as:

512-byte page + 16-byte spare
        |
        v
Traditional SSFDC geometry

2 KiB page + larger spare
4 KiB page + larger spare
8 KiB page + larger spare
        |
        v
Modern large-page NAND

A Linux NAND stack can use file systems and translation layers designed for these larger geometries, while a legacy TrueFFS SSFDC implementation may require substantial changes to support them.

The key issue is not merely page size. Metadata layouts, logical-block addressing, ECC placement, bad-block management, and erase-block geometry all become part of the compatibility problem.

📦 TrueFFS Capacity and Unit Management

#

A particularly important limitation in the legacy SSFDC implementation is the number of managed units.

The implementation can restrict the number of units to fewer than approximately 1,000, which can impose a practical capacity limit around the 16 MB range for the supported geometry.

The relationship can be represented as:

NAND Capacity
     |
     v
Number of Physical Units
     |
     v
SSFDC Address Representation
     |
     v
Translation-Layer Unit Limit
     |
     v
Maximum Addressable Capacity

Increasing the physical NAND density alone does not solve this problem. The translation layer must also be capable of representing and managing the additional units.

🔧 Extending SSFDC Capacity

#

One approach to extending the capacity is to revisit how formatSSFDC() and mountSSFDC() calculate the virtual-sector range.

A representative calculation may look like:

vol.virtualSectors = vol.sectorsPerUnit;

if (vol.noOfUnits < 500)
    vol.virtualSectors *= 250;
else if (vol.noOfUnits < 1000)
    vol.virtualSectors *= 500;
else if (vol.noOfUnits < 2000)
    vol.virtualSectors *= 2000;

This type of modification should not be treated as a standalone capacity fix.

Increasing virtualSectors without reviewing the underlying logical-to-physical address representation can produce mappings that appear valid at the block-device layer but cannot be represented correctly in the spare-area metadata.

A robust extension therefore requires auditing:

1. Unit-number representation.
2. Spare-area metadata layout.
3. Logical-to-physical translation.
4. Zone boundaries.
5. Bad-block replacement.
6. Formatting behavior.
7. Mount-time metadata validation.
8. Maximum sector addressing.
9. ECC and OOB handling.

🧮 Physical-to-Virtual Address Translation

#

The physical2Virtual() translation routine is another critical part of the SSFDC implementation.

The function converts physical unit information into the representation stored or consumed by the translation layer.

A representative implementation is:

static UnitNo physical2Virtual(SSFDC vol,
                               UnitNo unitNo,
                               int addressAreaNo)
{
    ...
    virtualUnitNo <<= 4;
    virtualUnitNo >>= 5;

    return virtualUnitNo;
}

The shift operations are significant because they determine how many bits participate in the resulting virtual-unit representation.

If the intended representation uses a 10-bit unit field, the implementation must be reviewed carefully to ensure that the shift and mask operations actually preserve the required bit range.

A safer engineering approach is to document the bit layout explicitly rather than relying on implicit assumptions:

Physical Unit Number
        |
        v
+-----------------------+
| zone | virtual unit   |
+-----------------------+
        |
        v
Spare Area Metadata

Any change to the bit allocation must be coordinated with both formatting and mounting code.

🔄 Zone Management for Larger NAND

#

When the available logical-unit address space becomes insufficient, zone management is one architectural approach.

Instead of attempting to represent the entire NAND device in a single address space:

Entire NAND
+---------------------------------------------+
| Unit 0 ... Unit N                           |
+---------------------------------------------+

the device can be divided into independently addressable regions:

NAND Device
+----------------+----------------+----------------+
|    Zone 0      |    Zone 1      |    Zone 2      |
| Unit 0..1023   | Unit 0..1023   | Unit 0..1023   |
+----------------+----------------+----------------+

Each zone can then maintain its own logical-unit range while a higher-level mechanism identifies the active zone.

However, introducing zones changes the translation-layer architecture and requires coordinated changes to formatting, mounting, metadata validation, and logical-sector calculations.

🧬 NFTL Support and Porting

#

Another approach is to use the NAND Flash Translation Layer (NFTL) implementation associated with older VxWorks releases.

The legacy VxWorks 5.4 environment included NFTL support that was subsequently absent from later VxWorks releases such as the VxWorks 6.x generation described here.

Porting NFTL therefore requires restoring both the implementation and its integration with the TrueFFS configuration.

A conceptual porting path is:

VxWorks 5.4 NFTL Source
          |
          v
      nftllite.c
          |
          v
Adapt APIs / Build Environment
          |
          v
       tffsConfig.c
          |
          v
       tlTable[]
          |
          v
      TrueFFS Mount

🛠️ Registering NFTL in TrueFFS

#

The NFTL translation-layer functions must be registered with the TrueFFS translation-layer table.

A representative configuration is:

#ifdef INCLUDE_TL_NFTL

#ifdef FORMAT_VOLUME
    { mountNFTL, formatNFTL },
#else
    mountNFTL,
#endif

#endif

This allows the TrueFFS configuration to associate NFTL mounting and formatting operations with the corresponding volume.

The exact registration structure depends on the VxWorks release and the local tffsConfig.c implementation.

⚙️ NAND MTD Operational Modes

#

A NAND MTD driver must distinguish between accesses to the main page data and accesses to the spare/OOB region.

The relevant modes can be represented as:

             NAND Page
        +-------------------+
        |                   |
        |    Main Area      |
        |                   |
        +-------------------+
        |                   |
        |   Spare / OOB     |
        |                   |
        +-------------------+

Mode 0: Main Area

#

Mode 0 represents normal access to the primary NAND page data.

For traditional small-page NAND:

Main Area = 512 bytes

The driver performs normal read or write operations against this payload region.

EXTRA: Spare Area

#

The EXTRA mode targets the spare/OOB region.

For the SSFDC geometry:

Spare Area = 16 bytes

The spare area can contain metadata required for:

• Bad-block markers
• Logical block addresses
• Translation-layer state
• Write markers
• ECC-related information

The MTD must preserve this metadata when performing operations that depend on the translation layer.

EDC: ECC-Aware Access

#

The EDC mode provides data access with error-detection/correction handling.

Conceptually:

Read
 |
 v
NAND Main Area
 |
 v
ECC Calculation / Verification
 |
 +---- Correctable error ---> Correct data
 |
 +---- Uncorrectable error -> Report failure

On writes, the driver can generate the required ECC information and associated spare-area metadata.

In the implementation described, a successful write also commits:

0x5555

to spare-area bytes 5 and 6 as a valid-write marker.

That marker is part of the specific translation-layer metadata convention and should therefore be treated as an implementation detail rather than a universal NAND requirement.

🧮 ECC and Bad-Block Management

#

NAND reliability depends heavily on ECC and bad-block handling.

A typical write sequence is:

Logical Sector
      |
      v
Translation Layer
      |
      v
Physical NAND Page
      |
      +---- Main Data
      |
      +---- ECC
      |
      +---- Translation Metadata
      |
      v
NAND Program Operation

A read reverses this process:

NAND Page
   |
   +---- Main Data
   |
   +---- Spare / ECC
   |
   v
ECC Verification
   |
   +---- Correctable ---> Return corrected data
   |
   +---- Uncorrectable -> Report I/O error

Bad-block management is equally important. The translation layer must avoid factory-marked bad blocks and handle blocks that become unusable during the device’s lifetime.

🔍 Formatting vs. Mounting

#

Extending TrueFFS NAND support requires distinguishing between format-time and mount-time behavior.

Formatting

#

Formatting establishes the metadata structures required by the translation layer.

Typical responsibilities include:

• Detecting NAND geometry
• Identifying bad blocks
• Creating logical mappings
• Initializing spare-area metadata
• Establishing virtual-sector counts
• Writing translation-layer metadata

Mounting

#

Mounting reconstructs the logical view from existing NAND metadata.

Typical responsibilities include:

• Scanning translation metadata
• Validating logical mappings
• Detecting incomplete writes
• Reconstructing physical-to-logical relationships
• Validating bad-block information
• Establishing the logical block-device interface

Therefore, changing only formatSSFDC() is insufficient if mountSSFDC() still assumes the original address-space constraints.

🧪 Practical Validation Strategy

#

A modified NAND translation layer should be tested incrementally.

A useful test hierarchy is:

1. Device Identification
          |
          v
2. Raw Page Read
          |
          v
3. Raw Page Program
          |
          v
4. Spare/OOB Access
          |
          v
5. ECC Verification
          |
          v
6. Bad-Block Detection
          |
          v
7. Translation-Layer Format
          |
          v
8. Mount / Remount
          |
          v
9. Logical Read / Write
          |
          v
10. Reboot / Power-Cycle Recovery

Testing only sequential reads and writes is not sufficient. Translation-layer modifications should also be validated against power interruption, bad blocks, remounting, and metadata corruption scenarios.

🧩 Common Failure Modes

#

📊 Architecture Comparison

#

🏁 Conclusion

#

VxWorks NAND support through TrueFFS is fundamentally a layered translation problem. The MTD understands the physical NAND device, while the translation layer converts that physical geometry into a logical storage model suitable for the operating system.

The most important architectural constraint is that physical NAND capacity and translation-layer addressability are separate limits. Increasing the size of the NAND device does not automatically expand the number of logical units that an SSFDC implementation can represent.

For larger devices, the engineering options include:

• Extending SSFDC unit and sector calculations.
• Correcting or redesigning logical-unit bit allocation.
• Introducing zone management.
• Porting an older NFTL implementation.
• Replacing the legacy translation layer with an architecture designed for modern large-page NAND.

In every case, modifications must remain consistent across the MTD, spare-area metadata, translation layer, formatter, mount logic, ECC handling, and bad-block management.

The complete storage path can therefore be viewed as:

                VxWorks File System
                         |
                         v
                  Logical Sectors
                         |
                         v
                    TrueFFS
                         |
              +----------+----------+
              |                     |
              v                     v
        Translation Layer          MTD
        SSFDC / NFTL          NAND Controller
              |                     |
              |              +------+------+
              |              |             |
              |              v             v
              |            Main          Spare
              |             Area           Area
              |              |             |
              +--------------+-------------+
                             |
                             v
                        ECC / EDC
                             |
                             v
                       Raw NAND Flash

For legacy VxWorks systems, the safest approach is to treat the existing TrueFFS implementation as a coherent storage protocol rather than a collection of independent functions. Changes to unit addressing, page geometry, or spare-area metadata can affect formatting, mounting, ECC, and recovery behavior simultaneously. That is why large-NAND support should be implemented and validated as an end-to-end translation-layer change rather than as a simple capacity-limit patch.