NFFS v1.0

NFFS

NFFS is a non-fragmented file system designed to be used with hardware emulators.

By providing a guaranteed non-fragmented file system a hardware device (such as an FPGA computer emulator like FPGABee) can be given a range of disk block numbers that a disk image resides and doesn't need to concern itself with file allocation tables.

NFFS provides:

  • A tiny C library for manipulating the file system
  • Command line tool for creating NFFS files and transfering them to/from SD cards or other storage media
  • Support for large disks and files (up to 2TB)
  • Simple directory structure (one root directory only, files up to 15 characters in length)
  • Designed to be useable from very small processors - compiles and runs just fine with SDCC on a Z-80

Command Line Tool

The nffs command line tool is used to manipulate the contents of an NFFS file system by adding, removing, extracting etc... files to/from file system.

Currently the nffs tool is known to work well on Windows and to compile and run on Linux but is not well tested on other platforms.

For help on using the nffs tool, simply run it with --help switch: 

nffs v1.0 - Non-Fragmented File System Utility
Copyright (C) 2017 Topten Software.  All Rights Reserved

Usage: nffs <fsimage> <command> [args]

    fsimage            image of the nffs file system to work with
    command            see commands below
    args               additional command argument

Commands:

    format                          create a new nffs file system
    ls [<spec>]                     list files in fsimage
    add <file> [newname]            add file to fsimage
    extract <file> [<diskimage>]    extract file from fsimage
    compare <file> [<diskimage>]    compare file to disk image
    cp <oldfile> <newfile>          copy file in fsimage
    mv <oldfile> <newfile>          rename file in fsimage
    rm <file>                       remove file from fsimage
    make <file> <size>[b|k|m|s]     make a file filled with zeros [bytes|kilobytes|megabytes|sectors]
    transfer <newimage> [glob]      ftransfer entire file system to newimage
    repair                          repair file system

Volume Names

The second parameter to the nffs command line tool can be either the name of a file to work with a "file-system-in-a-file", or it can be the name of a physical device, or the the name of a volume.

For example to create an NFFS file system inside a regular file:

> nffs mydata.nffs format

To create a file system on a drive letter mapped volume:

> nffs e: format

You can also use Window's physical drive names (be very careful)

> nffs \\.\PhysicalDrive7 format

And volume names: (Note: the volume must not include a trailing backslash)

> nffs \\?\Volume{d69038b9-cef9-4b6d-a7df-dd5807e96dc2} format

Using volume names without a mapped drive letter is convenient because it prevents Windows prompting to format the drive everytime it's plugged in. It's inconvenient however because typing ugly volume names like that shown above is tedious. For this reason you can create a configuration file at:

C:\Users\<YOURUSERNAME>\.nffs\config.json

with an alias for the volume name:

{
	"Volumes":
	{
		"sdcard": "\\\\?\\Volume{d69038b9-cef9-4b6d-a7df-dd5807e96dc2}",
	}
}

Now you can sdcard as the volume name. eg:

nffs sdcard add myfile.dsk

To help find the name of the volume of an external drive, use the Window mountvol command. Plug and unplug the device between multiple runs to figure out the name of the device.

> mountvol

Will display something like the following. (Don't forget to remove the trailing backslash if you copy/paste)

\\?\Volume{53396b23-3077-11e3-b15c-005056c00008}\
    C:\

\\?\Volume{0b368759-0000-0000-0000-f01f77000000}\
    *** NO MOUNT POINTS ***

Under Linux you can use device names, but you'll probably need sudo:

> sudo nffs /dev/sdg format

Examples

The following examples demonstrate how to use nffs from the command line:

Create a new NFFS file system in a file:

nffs myfs.nffs format

Add a file:

nffs myfs.nffs add fpgabee.sys

Add multiple files:

nffs myfs.nffs add *.ds40

Create a blank file in the file system of specified size:

nffs myfs.nffs make newfile.bin 64k

List the contents of a file system

nffs myfs.nffs ls

Transfer the file system to an external drive (will trash the volume, be careful)

nffs myfs.nffs transfer k:

Add a file directly to an external drive

nffs k: add fpgabee.sys

Extract a file directly from an external drive:

nffs k: extract working.dsk

Rename a file:

nffs k: mv config.dat config.old