Namespaces
	Error

	FWFS

	Gdb

	Host

	HYFS

	SPIFFS

Classes
struct	ACL

struct	Compression
	A compression descriptor. More...

class	Directory
	Wrapper class for enumerating a directory. More...

class	DirectoryTemplate
	Directory stream class. More...

class	File
	Wraps up all file access methods. More...

struct	FileNameBuffer
	a quick'n'dirty name buffer with maximum path allocation More...

class	FileStream
	File stream class. More...

class	FileSystem
	Installable File System base class. More...

class	FsBase

struct	FWObjDesc
	FWFS Object Descriptor. More...

class	HtmlDirectoryTemplate
	Read-only stream access to directory listing with HTML output. More...

class	IFileSystem
	Installable File System base class. More...

class	IObjectStore

class	JsonDirectoryTemplate
	Read-only stream providing directory listing in JSON format. More...

struct	NameBuffer
	defines a 'safe' name buffer More...

struct	NameStat
	version of Stat with integrated name buffer More...

struct	Object
	Object structure. More...

struct	ObjRef
	gives the identity and location of an FWFS object More...

struct	Stat
	File Status structure. More...

struct	TimeStamp
	Manage IFS timestamps stored as an unsigned 32-bit value. More...

Typedefs
using	ErrorCode = int

using	FileAttributes = BitSet< uint8_t, FileAttribute, size_t(FileAttribute::MAX)>
	File attributes are stored as a bitmask. More...

using	DirHandle = struct FileDir *

using	OpenFlags = BitSet< uint8_t, OpenFlag, size_t(OpenFlag::MAX)>

using	FileHandle = int16_t
	File handle. More...

using	FileID = uint32_t
	File identifier. More...

Enumerations
enum	ControlCode : uint16_t { FCNTL_GET_MD5_HASH = 1, FCNTL_USER_BASE = 0x8000 }
	See `IFS::IFileSystem::fcontrol` More...

enum	FileAttribute { FileAttribute::XX, FileAttribute::MAX }

enum	OpenFlag { OpenFlag::XX, OpenFlag::MAX }

enum	UserRole : uint8_t { UserRole::XX, UserRole::MAX }

Functions

String getAclString (const IFS::ACL &acl)

Return a brief textual representation for an ACL Suitable for inclusion in a file listing. More...

String getFileAttributeString (FileAttributes attr)

Get the string representation for the given set of file attributes suitable for inclusion in a file listing. More...

IFileSystem * createSpiffsFilesystem (Storage::Partition partition)

Create a SPIFFS filesystem. More...

IFileSystem * createFirmwareFilesystem (Storage::Partition partition)

Create a firmware filesystem. More...

IFileSystem * createHybridFilesystem (Storage::Partition fwfsPartition, Storage::Partition spiffsPartition)

Create a hybrid filesystem. More...

time_t fsGetTimeUTC ()

Get current timestamp in UTC. More...

template<typename T >

static T at_offset (const void *current, int offset)

template<typename T >

static T at_offset (void *current, int offset)

constexpr OpenFlags operator| (OpenFlag a, OpenFlag b)

char getChar (UserRole role)

UserRole getUserRole (char code, UserRole defaultRole)

Return compression corresponding to given string

Parameters

str

Return values

Compression::Type

Compression::Type getCompressionType (const char *str, Compression::Type defaultValue=Compression::Type::None)

Compression::Type getCompressionType (const String &str, Compression::Type defaultValue=Compression::Type::None)

Return the access type value for the given string.

Parameters

str
defaultRole	Returned if string isn't recognsed

Return values

UserRole

UserRole getUserRole (const char *str, UserRole defaultRole)

UserRole getUserRole (const String &str, UserRole defaultRole)

Variables
constexpr ErrorCode	FS_OK = Error::Success

Detailed Description

Access.h Access control definitions

Created on: 6 Jun 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Compression.h

Created on: 31 Aug 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Control.h

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Directory.h

Created: May 2019

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

File.h

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FileAttributes.h

Created on: 31 Aug 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FsBase.h Common base for file system classes

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FileSystem.h FWFS - Firmware File System

Created on: 19 Jul 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

ObjectStore.h

Created on: 1 Sep 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

ObjRefCache.h

Created on: 1 Sep 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FileSystem.h IFS wrapper for GDB syscall file access

Created on: 1 December 2020

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Helpers.h Helper functions to assist with standard filesystem creation

Created on: 27 Jan 2019

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

NameBuffer.h

Created on: 31 Aug 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Object.h Basic definitions for FW file system structure.

Created on: 7 Aug 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

A filesystem image is basically:

uint32_t START_MARKER;
Object Objects[];
Object EndObject;
uint32_t END_MARKER;

An FWFS Object is a variable-length structure which can be read as either 1 or 2 words, depending on the type. Objects always start on a word boundary. File and directory objects are both emitted as 'named' objects which contain a list of zero or more child objects. When the image is built the child objects are emitted first, followed by the parent. This puts the root directory at the end of the image. This arrangement means an image can be generated without having to back-track and rewrite headers.

Child objects can be of any type. A directory object will mostly contain other file and directory objects. File data is stored in a data object, not in the file object itself. This is usually found following the file object, but it doesn't have to be. Any object may be referenced by zero or more named object(s). For example, file links/aliases can contain references to the same file data. A file object may contain multiple data objects. These are treated as a contiguous block for file operations. This would potentially allow a file system builder to place common file blocks into shared data objects.

Object names are from 0 to 255 characters, inclusive. The root directory has a zero-length name. Paths lengths are unlimited. '/' is used as the path separator. It informs the filesystem of the parent/child relationship between one directory object and a sub-ordinate. ':' is used as the file stream separator. It performs the equivalent of the path separator for non-directory named objects. For exaample, file object may contain named objects accessible thus: index.html:info opens a handle to a named object called 'info' belonging to index.html.

OK, I admit it; this is pinched from NTFS; but it's such a cool idea. Applications can use it to attach custom data to their files without limitation.

As a side note, of course FWFS is read-only. More precisely, it only supports random reading of files, not random writing. Serial writing is supported in the form of image creation.

For SPIFFS, IFS is a wrapper. The metadata features are supported using SPIFFS metadata. An alternative approach is to implement every named object as a SPIFFS file. We'd then get all the features of FWFS in a rewritable system, with all the benefits of SPIFFS wear-levelling.

Objects are identified by their index, but it's not stored in the image. Instead, it's tracked via internal object descriptor.

To optimise lookups, an object table can be stored at the end of the image. This is just an array of 32-bit image offsets so that an object can be located instantly on large volumes. This will be optional as it can consume significant space.

OpenFlags.h

Created on: 31 Aug 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Error.h SPIFFS error codes

Created on: 31 Aug 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FileMeta.h

Created on: 21 Jul 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Stat.h

Created: August 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

TimeStamp.h

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

UserRole.h

Created on: 6 Jun 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Util.h Various bits for file system implementations to use

Created on: 10 Sep 2018

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Typedef Documentation

◆ DirHandle

using IFS::DirHandle = typedef struct FileDir*

◆ FileAttributes

using IFS::FileAttributes = typedef BitSet<uint8_t, FileAttribute, size_t(FileAttribute::MAX)>

File attributes are stored as a bitmask.

◆ FileHandle

using IFS::FileHandle = typedef int16_t

File handle.

References an open file

◆ FileID

using IFS::FileID = typedef uint32_t

File identifier.

Contained within Stat, uniquely identifies any file on the file system.

◆ OpenFlags

using IFS::OpenFlags = typedef BitSet<uint8_t, OpenFlag, size_t(OpenFlag::MAX)>

Enumeration Type Documentation

◆ ControlCode

enum IFS::ControlCode : uint16_t

See IFS::IFileSystem::fcontrol

These are weakly typed as values may be defined elsewhere.

Enumerator

FCNTL_GET_MD5_HASH

Get stored MD5 hash for file.

FWFS calculates this when the filesystem image is built and can be used by applications to verify file integrity.

On success, returns size of the hash itself (16) If the file is zero-length then Error::NotFound will be returned as the hash is not stored for empty files.

FCNTL_USER_BASE

Start of user-defined codes.

Codes before this are reserved for system use

◆ FileAttribute

enum IFS::FileAttribute

strong

Enumerator
XX
MAX

◆ OpenFlag

enum IFS::OpenFlag

strong

Enumerator
XX
MAX

◆ UserRole

enum IFS::UserRole : uint8_t

strong

Enumerator
XX
MAX	Actually maxmimum value + 1...

Function Documentation

◆ at_offset() [1/2]

template<typename T >

static T IFS::at_offset	(	const void *	current,
		int	offset
	)

static

◆ at_offset() [2/2]

template<typename T >

static T IFS::at_offset	(	void *	current,
		int	offset
	)

static

◆ createFirmwareFilesystem()

IFileSystem* IFS::createFirmwareFilesystem ( Storage::Partition partition )

Create a firmware filesystem.

Parameters

partition

Return values

IFileSystem* constructed filesystem object

◆ createHybridFilesystem()

IFileSystem* IFS::createHybridFilesystem	(	Storage::Partition	fwfsPartition,
		Storage::Partition	spiffsPartition
	)

Create a hybrid filesystem.

Parameters

fwfsPartition
spiffsPartition

Return values

IFileSystem* constructed filesystem object

◆ createSpiffsFilesystem()

IFileSystem* IFS::createSpiffsFilesystem ( Storage::Partition partition )

Create a SPIFFS filesystem.

Parameters

partition

Return values

IFileSystem* constructed filesystem object

◆ fsGetTimeUTC()

time_t IFS::fsGetTimeUTC ( )

Get current timestamp in UTC.

Return values

time_t

Note: Filing systems must store timestamps in UTC Use this function; makes porting easier.

◆ getAclString()

String IFS::getAclString ( const IFS::ACL & acl )

Return a brief textual representation for an ACL Suitable for inclusion in a file listing.

Parameters

acl

Return values

String

◆ getChar()

char IFS::getChar ( UserRole role )

◆ getCompressionType() [1/2]

Compression::Type IFS::getCompressionType	(	const char *	str,
		Compression::Type	defaultValue = `Compression::Type::None`
	)

◆ getCompressionType() [2/2]

Compression::Type IFS::getCompressionType	(	const String &	str,
		Compression::Type	defaultValue = `Compression::Type::None`
	)

inline

◆ getFileAttributeString()

String IFS::getFileAttributeString ( FileAttributes attr )

Get the string representation for the given set of file attributes suitable for inclusion in a file listing.

Parameters

attr

Return values

String

◆ getUserRole() [1/3]

UserRole IFS::getUserRole	(	const char *	str,
		UserRole	defaultRole
	)

◆ getUserRole() [2/3]

UserRole IFS::getUserRole	(	const String &	str,
		UserRole	defaultRole
	)

inline

◆ getUserRole() [3/3]

UserRole IFS::getUserRole	(	char	code,
		UserRole	defaultRole
	)

◆ operator|()

constexpr OpenFlags IFS::operator\|	(	OpenFlag	a,
		OpenFlag	b
	)

inline

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ DirHandle

◆ FileAttributes

◆ FileHandle

◆ FileID

◆ OpenFlags

Enumeration Type Documentation

◆ ControlCode

◆ FileAttribute

◆ OpenFlag

◆ UserRole

Function Documentation

◆ at_offset() [1/2]

◆ at_offset() [2/2]

◆ createFirmwareFilesystem()

◆ createHybridFilesystem()

◆ createSpiffsFilesystem()

◆ fsGetTimeUTC()

◆ getAclString()

◆ getChar()

◆ getCompressionType() [1/2]

◆ getCompressionType() [2/2]

◆ getFileAttributeString()

◆ getUserRole() [1/3]

◆ getUserRole() [2/3]

◆ getUserRole() [3/3]

◆ operator|()