tinyfs

README

TinyFS

TinyFS contains Go implementations of embedded filesystems. The packages in this module require CGo support and are TinyGo compatible.

Supported hardware

You can use TinyFS with the following embedded hardware configurations:

Onboard Flash memory

You can use TinyFS on processors that have onboard Flash memory in the area above where the compiled TinyGo program is running.

External Flash memory

You can use TinyFS on an external Flash memory chip connected via SPI/QSPI hardware interface.

See https://github.com/tinygo-org/drivers/tree/release/flash

SD card connected via SPI/QPI

You can use TinyFS on an SD card connected via SPI/QSPI hardware interface.

See https://github.com/tinygo-org/drivers/tree/release/sdcard

LittleFS

The LittleFS file system is specifically designed for embedded applications.

See https://github.com/littlefs-project/littlefs for more information.

Example

This example runs on the RP2040 using the on-board flash in the available memory above where the program code itself is running:

$ tinygo flash -target pico -monitor ./examples/console/littlefs/machine/
Connected to /dev/ttyACM0. Press Ctrl-C to exit.
SPI Configured. Reading flash info
==> lsblk

-------------------------------------
 Device Information:  
-------------------------------------
 flash data start: 10017000
 flash data end:  10200000
-------------------------------------

==> format
Successfully formatted LittleFS filesystem.

==> mount
Successfully mounted LittleFS filesystem.

==> ls
==> samples
wrote 90 bytes to file0.txt
wrote 90 bytes to file1.txt
wrote 90 bytes to file2.txt
wrote 90 bytes to file3.txt
wrote 90 bytes to file4.txt
==> ls
-rwxrwxrwx    90 file0.txt
-rwxrwxrwx    90 file1.txt
-rwxrwxrwx    90 file2.txt
-rwxrwxrwx    90 file3.txt
-rwxrwxrwx    90 file4.txt
==> cat file3.txt
00000000: 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f     !"#$%&'()*+,-./
00000010: 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f    0123456789:;<=>?
00000020: 40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f    @ABCDEFGHIJKLMNO
00000030: 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f    PQRSTUVWXYZ[\]^_
00000040: 60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f    `abcdefghijklmno
00000050: 70 71 72 73 74 75 76 77 78 79                      pqrstuvwxy

After unplugging and reconnecting the RP2040 device (a hard restart):

$ tinygo monitor
Connected to /dev/ttyACM0. Press Ctrl-C to exit.
SPI Configured. Reading flash info
==> mount
Successfully mounted LittleFS filesystem.

==> ls
-rwxrwxrwx    90 file0.txt
-rwxrwxrwx    90 file1.txt
-rwxrwxrwx    90 file2.txt
-rwxrwxrwx    90 file3.txt
-rwxrwxrwx    90 file4.txt
==> cat file3.txt
00000000: 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f     !"#$%&'()*+,-./
00000010: 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f    0123456789:;<=>?
00000020: 40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f    @ABCDEFGHIJKLMNO
00000030: 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f    PQRSTUVWXYZ[\]^_
00000040: 60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f    `abcdefghijklmno
00000050: 70 71 72 73 74 75 76 77 78 79                      pqrstuvwxy

FAT FS

The FAT file system is not currently working, due to https://github.com/tinygo-org/tinygo/issues/3460.

Documentation

Index

• Constants
• type BlockDevice
• type File
• type FileHandle
• type Filesystem
• type MemBlockDevice
  • func NewMemoryDevice(pageSize, blockSize, blockCount int) *MemBlockDevice
  • func (bd *MemBlockDevice) EraseBlockSize() int64
  • func (bd *MemBlockDevice) EraseBlocks(start int64, len int64) error
  • func (bd *MemBlockDevice) ReadAt(buf []byte, off int64) (n int, err error)
  • func (bd *MemBlockDevice) Size() int64
  • func (bd *MemBlockDevice) Sync() error
  • func (bd *MemBlockDevice) WriteAt(buf []byte, off int64) (n int, err error)
  • func (bd *MemBlockDevice) WriteBlockSize() int64
• type Syncer

Constants

const Version = "0.4.0"

Version returns a user-readable string showing the version of the package for support purposes. Update this value before release of new version of software.

Types

type BlockDevice

type BlockDevice interface {

	// ReadAt reads the given number of bytes from the block device.
	io.ReaderAt

	// WriteAt writes the given number of bytes to the block device.
	io.WriterAt

	// Size returns the number of bytes in this block device.
	Size() int64

	// WriteBlockSize returns the block size in which data can be written to
	// memory. It can be used by a client to optimize writes, non-aligned writes
	// should always work correctly.
	WriteBlockSize() int64

	// EraseBlockSize returns the smallest erasable area on this particular chip
	// in bytes. This is used for the block size in EraseBlocks.
	// It must be a power of two, and may be as small as 1. A typical size is 4096.
	EraseBlockSize() int64

	// EraseBlocks erases the given number of blocks. An implementation may
	// transparently coalesce ranges of blocks into larger bundles if the chip
	// supports this. The start and len parameters are in block numbers, use
	// EraseBlockSize to map addresses to blocks.
	EraseBlocks(start, len int64) error
}

A BlockDevice is the raw device that is meant to store a filesystem.

type File

type File interface {
	FileHandle
	IsDir() bool
	Readdir(n int) (infos []os.FileInfo, err error)
}

File specifies the common behavior of the file abstraction in TinyFS; this interface may be changed or superseded by the TinyGo os.FileHandle interface if/when that is merged and standardized.

type FileHandle

type FileHandle interface {
	// Read reads up to len(b) bytes from the file.
	Read(b []byte) (n int, err error)

	// Write writes up to len(b) bytes to the file.
	Write(b []byte) (n int, err error)

	// Close closes the file, making it unusable for further writes.
	Close() (err error)
}

FileHandle is a copy of the experimental os.FileHandle interface in TinyGo

type Filesystem

type Filesystem interface {
	Format() error
	Mkdir(path string, _ os.FileMode) error
	Mount() error
	Open(path string) (File, error)
	OpenFile(path string, flags int) (File, error)
	Remove(path string) error
	Rename(oldPath string, newPath string) error
	Stat(path string) (os.FileInfo, error)
	Unmount() error
}

type MemBlockDevice

type MemBlockDevice struct {
	// contains filtered or unexported fields
}

MemBlockDevice is a block device implementation backed by a byte slice

func NewMemoryDevice

func NewMemoryDevice(pageSize, blockSize, blockCount int) *MemBlockDevice

func (*MemBlockDevice) EraseBlockSize

func (bd *MemBlockDevice) EraseBlockSize() int64

func (*MemBlockDevice) EraseBlocks

func (bd *MemBlockDevice) EraseBlocks(start int64, len int64) error

func (*MemBlockDevice) ReadAt

func (bd *MemBlockDevice) ReadAt(buf []byte, off int64) (n int, err error)

func (*MemBlockDevice) Size

func (bd *MemBlockDevice) Size() int64

func (*MemBlockDevice) Sync

func (bd *MemBlockDevice) Sync() error

func (*MemBlockDevice) WriteAt

func (bd *MemBlockDevice) WriteAt(buf []byte, off int64) (n int, err error)

func (*MemBlockDevice) WriteBlockSize

func (bd *MemBlockDevice) WriteBlockSize() int64

type Syncer

type Syncer interface {
	// Sync triggers the devices to commit any pending or cached operations
	Sync() error
}