Namespaces

 Error
 
 FWFS
 
 Gdb
 
 Host
 
 HYFS
 

Classes

struct  ACL
 
struct  AttributeEnum
 Attribute information passed to enumeration callback. 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
 
class  HtmlDirectoryTemplate
 Read-only stream access to directory listing with HTML output. More...
 
class  IFileSystem
 Installable File System base class. More...
 
class  IProfiler
 Filesystems may optionally provide performance statistics. More...
 
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...
 
class  Profiler
 
struct  Stat
 File Status structure. More...
 
struct  TimeStamp
 Manage IFS timestamps stored as an unsigned 32-bit value. More...
 

Typedefs

using AttributeEnumCallback = Delegate< bool(AttributeEnum &e)>
 Return true to continue enumeration, false to stop. More...
 
using ErrorCode = int
 
using FileAttributes = BitSet< uint8_t, FileAttribute, size_t(FileAttribute::MAX)>
 File attributes are stored as a bitmask. More...
 
using DirHandle = struct ImplFileDir *
 
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  AttributeTag : uint16_t { AttributeTag::XX, AttributeTag::User = 16 }
 Identifies a specific attribute. More...
 
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...
 
AttributeTag getUserAttributeTag (uint8_t value)
 
size_t getAttributeSize (AttributeTag tag)
 
struct __attribute__ ((packed)) Compression
 A compression descriptor. More...
 
String getFileAttributeString (FileAttributes attr)
 Get the string representation for the given set of file attributes suitable for inclusion in a file listing. More...
 
FileSystemcreateFirmwareFilesystem (Storage::Partition partition)
 Create a firmware filesystem. More...
 
FileSystemcreateHybridFilesystem (Storage::Partition fwfsPartition, IFileSystem *flashFileSystem)
 Create a hybrid filesystem. More...
 
constexpr OpenFlags operator| (OpenFlag a, OpenFlag b)
 
time_t fsGetTimeUTC ()
 Get current timestamp in UTC. More...
 
char getChar (UserRole role)
 
UserRole getUserRole (char code, UserRole defaultRole)
 
bool isRootPath (const char *&path)
 Check if path is root directory. More...
 
void checkStat (Stat &stat)
 
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
defaultRoleReturned 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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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/.

Attribute.h

Created: April 2021

Copyright 2021 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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/.

ArchiveStream.h

Copyright 2021 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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.

ObjectBuffer.h

Copyright 2021 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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/.

OpenFlags.h

Created on: 31 Aug 2018

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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/.

IProfiler.h - Abstract interface to implement filesystem profiling

Copyright 2021 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

Copyright 2019 mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

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

◆ AttributeEnumCallback

Return true to continue enumeration, false to stop.

◆ DirHandle

using IFS::DirHandle = typedef struct ImplFileDir*

◆ 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

◆ AttributeTag

enum IFS::AttributeTag : uint16_t
strong

Identifies a specific attribute.

Enumerator
XX 
User 

First user attribute.

◆ ControlCode

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

◆ __attribute__()

struct IFS::__attribute__ ( (packed)  )

A compression descriptor.

< Actually maxmimum value + 1...

◆ checkStat()

void IFS::checkStat ( Stat stat)

◆ createFirmwareFilesystem()

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

Create a firmware filesystem.

Parameters
partition
Return values
FileSystem*constructed filesystem object

◆ createHybridFilesystem()

FileSystem* IFS::createHybridFilesystem ( Storage::Partition  fwfsPartition,
IFileSystem flashFileSystem 
)

Create a hybrid filesystem.

Parameters
fwfsPartitionBase read-only filesystem partition
flashFileSystemThe filesystem to use for writing
Return values
FileSystem*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

◆ getAttributeSize()

size_t IFS::getAttributeSize ( AttributeTag  tag)

◆ 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

◆ getUserAttributeTag()

AttributeTag IFS::getUserAttributeTag ( uint8_t  value)
inline

◆ 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 
)

◆ isRootPath()

bool IFS::isRootPath ( const char *&  path)

Check if path is root directory.

Parameters
Pathto check, set to nullptr if it's the root directory
Return values
booltrue if path is root directory

Paths equal to "/" or "" are empty and considered equivalent to nullptr. Methods or functions can use this macro to resolve these for simpler parsing.

◆ operator|()

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