LLFS

Project Title

Created by: Sergey Sanders

Company: Sesa Design Inc

The Linked-List File System (LLFS) is a compact file system designed for storage media with a capacity of up to 64KB, utilizing a 256-byte block size. This system is particularly suitable for environments with limited storage requirements, such as embedded systems.

Key Features of LLFS:

Block Partitioning:

Uses a 256-byte block size. The first sector is designated as the "index sector," serving as the file allocation table.

Index Sector:

Can contain up to 15 file descriptors. Supports multiple index sectors for scalability within the volume.

File Descriptor Structure:

Defined by the lf_record_t structure, which is packed and aligned for efficiency:

Field	Size (bytes)	Description
fptr	1	Sector pointer.
attr	1	File attribute.
rptr	2	Reference pointer, 0 for root.
name	12	File name.

Sector Management:

Designed for small volumes with a sector count up to 254. Sectors 0 and 255 are reserved for index sectors, optimizing file descriptor storage and retrieval.

LLFS provides a streamlined way to manage files on small-volume media, leveraging a linked-list structure for efficient file indexing and retrieval.

Offset	Size (bytes)	Description
0	16	lf_phy_t structure containing volume metadata.
16-31	16	lf_record_t - file descriptor (1st block).
32-47	16	lf_record_t - file descriptor (2nd block).
...	...	...
224-239	16	lf_record_t - file descriptor (15th block).
240-255	16	last lf_record_t descriptor with attr set to LLFS_ATTR_INDEX and last byte set to LLFS_MARK_INDEX_BYTE

The first record in the first index sector is a physical media description:

Field	Size (bytes)	Description
fsType	1	File system type, value 0xdb.
fsTypeN	1	Complement of fsType.
devID	2	Device identifier.
secCount	2	Number of sectors in the volume.
compress	1	Compression type, LLFS_COMPRESS_NONE.
ecc	1	ECC base size, LLFS_ECC_NONE.
name	8	Volume name.

LLFS API Documentation

Overview

LLFS (Linked List File System) is a file system designed for small volumes with limited sector counts. This documentation provides an overview of the LLFS API, including data structures, constants, and functions.

Constants

• Filename and Volume Lengths

  • LLFS_FILENAME_LEN: 12
  • LLFS_VOLNAME_LEN: 8

• Sector and Volume Settings

  • LLFS_SECTOR_SIZE: 256
  • LLFS_MAX_SECTOR_COUNT: 256
  • LLFS_MAX_VOLUME_COUNT: 4

• Volume and Compression Types

  • LLFS_VOLUME_VALID: 0xdb
  • LLFS_COMPRESS_NONE: 0x00
  • LLFS_ECC_NONE: 0x00

Attributes

• User Accessible

  • LLFS_ATTR_EXEC: 0x04
  • LLFS_ATTR_WRITE: 0x02
  • LLFS_ATTR_READ: 0x01
  • LLFS_ATTR_LOCK: 0x08

• System Only

  • LLFS_ATTR_DIR: 0x10
  • LLFS_ATTR_LINK: 0x20
  • LLFS_ATTR_INDEX: 0x40
  • LLFS_ATTR_FVALID: 0x80

Modes

• MODE_EXEC: 0x01
• MODE_WRITE: 0x02
• MODE_READ: 0x04
• MODE_CREATE: 0x08
• MODE_APPEND: 0x10

Data Structures

lf_err_t

Enumeration for error codes:

• LF_ERR_NONE
• LF_ERR_VOLUME
• LF_ERR_READ
• LF_ERR_WRITE
• LF_ERR_FULL
• LF_ERR_MEM
• LF_ERR_NOTOPEN
• LF_ERR_NOTFOUND
• LF_ERR_FNAME

lf_phy_t

Represents the physical layer of the file system:

• uint8_t fsType
• uint8_t fsTypeN
• uint16_t devID
• uint16_t secCount
• uint8_t compress
• uint8_t ecc
• uint8_t name[LLFS_VOLNAME_LEN]

volume_t

Manages volume operations:

• const lf_phy_t *phy
• Function pointers for sector operations
• uint8_t sData[LLFS_SECTOR_SIZE]

lf_record_t

File descriptor for small volumes:

• uint8_t fptr
• uint8_t attr
• uint16_t rptr
• char name[LLFS_FILENAME_LEN]

lfile_t

Represents an open file:

• uint16_t index
• uint16_t pos
• uint8_t *sData
• uint8_t dataSect
• uint16_t upIndex
• char name[LLFS_FILENAME_LEN+1]
• uint8_t mode
• uint8_t changed
• uint8_t volume

Functions

• void lf_init(void)
• lf_err_t lf_format(uint32_t size, uint16_t devID, char *name)
• void lf_delete(char *name)
• uint32_t lf_get_free(uint8_t volIndex)
• uint32_t lf_get_fsize(char* name, uint16_t fPtr)
• uint16_t lf_find_record(char *name, lf_record_t *record, uint8_t next)
• char *lf_rname_tostr(char *destStr, char *name)
• void lf_close(lfile_t *file)
• lfile_t *lf_open(char *name, uint8_t mode)
• uint16_t lf_write(lfile_t *file, void *data, uint16_t size)
• uint16_t lf_read(lfile_t *file, void *data, uint16_t size)
• char *lf_gets(char *str, uint16_t size, lfile_t *file)

LLFS Implementation Details

Overview

This document provides an in-depth look into the implementation of the LLFS (Linked List File System) functions.

Functions

void lf_init(void)

Initializes the file system. This function is weakly defined and can be overridden.

lf_err_t lf_format(uint32_t size, uint16_t devID, char* name)

Formats the volume with the specified size and device ID.

uint32_t lf_get_free(uint8_t volIndex)

Returns the amount of free space available on the specified volume index.

uint16_t lf_get_free_sector(void)

Finds the next available free sector.

uint16_t lf_add_record(lf_record_t* newRecord, char* name, uint8_t attr)

Adds a new file record with the specified name and attributes.

void lf_del_record(uint16_t pos)

Deletes a file record at the specified position.

bool lf_match(char* fname, char* exp)

Checks if a filename matches a given expression, supporting wildcard *.

uint16_t lf_find_record(char* name, lf_record_t* record, uint8_t next)

Finds a file record by name, returning its position.

char* lf_rname_tostr(char* destStr, char* name)

Converts a raw file name into a string.

void lf_clean_data(uint8_t fPtr)

Clears data starting from the specified sector pointer.

uint16_t lf_find_eof(uint16_t fPtr)

Finds the end of a file, starting from the given file pointer.

uint32_t lf_get_fsize(char* name, uint16_t fPtr)

Calculates the size of a file, identified by name or file pointer.

void lf_delete(char* name)

Deletes a file by name, regardless of type.

void lf_flush(lfile_t* file)

Writes any buffered data to the volume.

void lf_close(lfile_t* file)

Closes an open file, freeing associated resources.

lfile_t* lf_open(char* name, uint8_t mode)

Opens a file with the given name and mode, returning a file handle.

uint16_t lf_write(lfile_t* file, void* data, uint16_t size)

Writes data to a file, returning the number of bytes written.

uint16_t lf_read(lfile_t* file, void* data, uint16_t size)

Reads data from a file, returning the number of bytes read.

char* lf_gets(char* str, uint16_t size, lfile_t* file)

Reads a line from a file into a string.

Licensing

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. See license details.

Disclaimer

This work is provided "as is" without any guarantees. Use at your own risk.