Components/IFS/src/include/IFS/FWFS/FileSystem.h
Go to the documentation of this file.
1 /****
2  * FileSystem.h
3  * FWFS - Firmware File System
4  *
5  * Created on: 19 Jul 2018
6  *
7  * Copyright 2019 mikee47 <mike@sillyhouse.net>
8  *
9  * This file is part of the IFS Library
10  *
11  * This library is free software: you can redistribute it and/or modify it under the terms of the
12  * GNU General Public License as published by the Free Software Foundation, version 3 or later.
13  *
14  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
15  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License along with this library.
19  * If not, see <https://www.gnu.org/licenses/>.
20  *
21  ****/
22 
23 #pragma once
24 
25 #include "../IFileSystem.h"
26 #include "Object.h"
27 
28 namespace IFS
29 {
30 namespace FWFS
31 {
32 // File handles start at this value
33 #ifndef FWFS_HANDLE_MIN
34 #define FWFS_HANDLE_MIN 100
35 #endif
36 
37 // Maximum number of file descriptors
38 #ifndef FWFS_MAX_FDS
39 #define FWFS_MAX_FDS 8
40 #endif
41 
42 // Maximum number of volumes - 1 is minimum, the rest are mounted in subdirectories
43 #ifndef FWFS_MAX_VOLUMES
44 #define FWFS_MAX_VOLUMES 4
45 #endif
46 
47 // Maximum file handle value
48 #define FWFS_HANDLE_MAX (FWFS_HANDLE_MIN + FWFS_MAX_FDS - 1)
49 
53 struct FWFileDesc {
54  FWObjDesc odFile;
55  union {
56  struct {
57  uint32_t dataSize;
58  uint32_t cursor;
59  };
60  // For MountPoint
61  struct {
62  IFileSystem* fileSystem;
63  union {
65  DirHandle dir;
66  };
67  };
68  };
69 
70  bool isAllocated() const
71  {
72  return odFile.obj.typeData != 0;
73  }
74 
75  bool isMountPoint() const
76  {
77  return odFile.obj.isMountPoint();
78  }
79 
80  void reset()
81  {
82  *this = FWFileDesc{};
83  }
84 };
85 
89 struct FWVolume {
90  std::unique_ptr<IFileSystem> fileSystem;
91 };
92 
96 class FileSystem : public IFileSystem
97 {
98 public:
100  {
101  }
102 
103  // IFileSystem methods
104  int mount() override;
105  int getinfo(Info& info) override;
106  String getErrorString(int err) override;
107  int setVolume(uint8_t index, IFileSystem* fileSystem) override;
108  int opendir(const char* path, DirHandle& dir) override;
109  int readdir(DirHandle dir, Stat& stat) override;
110  int rewinddir(DirHandle dir) override;
111  int closedir(DirHandle dir) override;
112  int mkdir(const char* path) override;
113  int stat(const char* path, Stat* stat) override;
114  int fstat(FileHandle file, Stat* stat) override;
115  int fcontrol(FileHandle file, ControlCode code, void* buffer, size_t bufSize) override;
116  int fsetxattr(FileHandle file, AttributeTag tag, const void* data, size_t size) override;
117  int fgetxattr(FileHandle file, AttributeTag tag, void* buffer, size_t size) override;
118  int fenumxattr(FileHandle file, AttributeEnumCallback callback, void* buffer, size_t bufsize) override;
119  int setxattr(const char* path, AttributeTag tag, const void* data, size_t size) override;
120  int getxattr(const char* path, AttributeTag tag, void* buffer, size_t size) override;
121  FileHandle open(const char* path, OpenFlags flags) override;
122  int close(FileHandle file) override;
123  int read(FileHandle file, void* data, size_t size) override;
124  int write(FileHandle file, const void* data, size_t size) override;
125  file_offset_t lseek(FileHandle file, file_offset_t offset, SeekOrigin origin) override;
126  int eof(FileHandle file) override;
127  file_offset_t tell(FileHandle file) override;
128  int ftruncate(FileHandle file, file_size_t new_size) override;
129  int flush(FileHandle file) override;
130  int fgetextents(FileHandle file, Storage::Partition* part, Extent* list, uint16_t extcount) override;
131  int rename(const char* oldpath, const char* newpath) override;
132  int remove(const char* path) override;
133  int fremove(FileHandle file) override;
134  int format() override
135  {
136  return Error::ReadOnly;
137  }
138  int check() override
139  {
140  /* We could implement this, but since problems would indicate corrupted firmware
141  * there isn't much we can do other than suggest a re-flashing. This sort of issue
142  * is better resolved externally using a hash of the entire firmware image. */
143  return Error::NotImplemented;
144  }
145 
146 private:
147  int getMd5Hash(FWFileDesc& fd, void* buffer, size_t bufSize);
148 
149  bool isMounted()
150  {
151  return flags[Flag::mounted];
152  }
153 
160  int readObjectHeader(FWObjDesc& od);
161 
169  int getChildObject(const FWObjDesc& parent, const FWObjDesc& child, FWObjDesc& od);
170 
179  int readChildObjectHeader(const FWObjDesc& parent, FWObjDesc& child);
180 
189  int readObjectContent(const FWObjDesc& od, uint32_t offset, uint32_t size, void* buffer);
190 
195  int findUnusedDescriptor();
196 
197  int findChildObjectHeader(const FWObjDesc& parent, FWObjDesc& child, Object::Type objId);
198  int findChildObject(const FWObjDesc& parent, FWObjDesc& child, const char* name, unsigned namelen);
199  int findObject(Object::ID objId, FWObjDesc& od);
200 
208  int findObjectByPath(const char*& path, FWObjDesc& od);
209 
216  int resolveMountPoint(const FWObjDesc& odMountPoint, IFileSystem*& fileSystem);
217 
218  /*
219  * @brief Resolve path to mounted volume.
220  * @param path Path to parse, consumes path to mount point
221  * @param fileSystem Located filesystem
222  * @retval int error code
223  *
224  * Used for methods which require write access are read-only unless path corresponds to mounted volume.
225  * If path is within this volume then Error::ReadOnly is returned.
226  */
227  int findLinkedObject(const char*& path, IFileSystem*& fileSystem);
228 
235  int getObjectDataSize(FWObjDesc& od, uint32_t& dataSize);
236 
237  int readObjectName(const FWObjDesc& od, NameBuffer& name);
238  int fillStat(Stat& stat, const FWObjDesc& entry);
239  int readAttribute(FWObjDesc& od, AttributeTag tag, void* buffer, size_t size);
240 
241  void printObject(const FWObjDesc& od, bool isChild);
242 
243 protected:
244  enum class Flag {
245  mounted,
246  };
247 
249  FWVolume volumes[FWFS_MAX_VOLUMES];
250  FWFileDesc fileDescriptors[FWFS_MAX_FDS];
251  FWObjDesc odRoot;
253  ACL rootACL{};
255 };
256 
257 } // namespace FWFS
258 
259 } // namespace IFS
Represents a flash partition.
Definition: Partition.h:85
Object obj
The object structure.
Definition: Components/IFS/src/include/IFS/FWFS/Object.h:590
int ftruncate(FileHandle file, file_size_t new_size) override
Truncate (reduce) the size of an open file.
int fsetxattr(FileHandle file, AttributeTag tag, const void *data, size_t size) override
Set an extended attribute on an open file.
std::unique_ptr< IFileSystem > fileSystem
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:130
int setxattr(const char *path, AttributeTag tag, const void *data, size_t size) override
Set an extended attribute for a file given its path.
int closedir(DirHandle dir) override
close a directory object
int getinfo(Info &info) override
get filing system information
int readdir(DirHandle dir, Stat &stat) override
read a directory entry
void reset()
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:120
int remove(const char *path) override
remove (delete) a file by path
#define FWFS_MAX_FDS
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:79
int fremove(FileHandle file) override
remove (delete) a file by handle
FileSystem(Storage::Partition partition)
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:139
The String class.
Definition: WString.h:136
int stat(const char *path, Stat *stat) override
get file information
Storage::Partition partition
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:288
file_offset_t tell(FileHandle file) override
get current file position
int flush(FileHandle file) override
flush any buffered data to physical media
Installable File System base class.
Definition: IFileSystem.h:99
Defines the location of a contiguous run of file data.
Definition: Extent.h:57
int fgetextents(FileHandle file, Storage::Partition *part, Extent *list, uint16_t extcount) override
Get extents for a file.
uint32_t dataSize
Total size of data.
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:97
bool isMountPoint() const
Definition: Components/IFS/src/include/IFS/FWFS/Object.h:369
bool isMountPoint() const
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:115
uint32_t ID
Object identifier (offset from start of image)
Definition: Components/IFS/src/include/IFS/FWFS/Object.h:290
int16_t FileHandle
File handle.
Definition: Stat.h:59
Definition: DirectoryTemplate.h:36
BitSet< uint8_t, Flag > flags
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:294
int close(FileHandle file) override
close an open file
Flag
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:284
int rename(const char *oldpath, const char *newpath) override
rename a file
ControlCode
See IFS::IFileSystem::fcontrol
Definition: Components/IFS/src/include/IFS/Control.h:48
int mkdir(const char *path) override
Create a directory.
int fenumxattr(FileHandle file, AttributeEnumCallback callback, void *buffer, size_t bufsize) override
Enumerate attributes.
FWVolume volumes[FWFS_MAX_VOLUMES]
Volumes mapped to mountpoints by index.
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:289
String getErrorString(int err) override
get the text for a returned error code
int32_t file_offset_t
Definition: Components/IFS/src/include/IFS/Types.h:51
#define FWFS_MAX_VOLUMES
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:84
File Status structure.
Definition: Stat.h:71
Type
Definition: Components/IFS/src/include/IFS/FWFS/Object.h:292
Manage a set of bit values using enumeration.
Definition: BitSet.h:44
int rewinddir(DirHandle dir) override
Reset directory read position to start.
DirHandle dir
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:105
uint8_t typeData
Stored type plus flag.
Definition: Components/IFS/src/include/IFS/FWFS/Object.h:285
struct ImplFileDir * DirHandle
Definition: IFileSystem.h:72
int write(FileHandle file, const void *data, size_t size) override
write content to a file at current position and advance cursor
FWObjDesc odRoot
Reference to root directory object.
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:291
defines a 'safe' name buffer
Definition: NameBuffer.h:63
int mount() override
Mount file system, performing any required initialisation.
FileHandle open(const char *path, OpenFlags flags) override
open a file (or directory) by path
FWFileDesc fileDescriptors[FWFS_MAX_FDS]
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:290
AttributeTag
Identifies a specific attribute.
Definition: Attribute.h:64
int read(FileHandle file, void *data, size_t size) override
read content from a file and advance cursor
IFS::FileHandle FileHandle
Definition: Core/FileSystem.h:24
ACL rootACL
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:293
FWObjDesc odFile
File object.
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:94
uint32_t cursor
Current read/write offset within file data.
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:98
Object::ID volume
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:292
SeekOrigin
Stream/file seek origins.
Definition: SeekOrigin.h:18
FileHandle file
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:104
int eof(FileHandle file) override
determine if current file position is at end of file
int fgetxattr(FileHandle file, AttributeTag tag, void *buffer, size_t size) override
Get an extended attribute from an open file.
int opendir(const char *path, DirHandle &dir) override
open a directory for reading
file_offset_t lseek(FileHandle file, file_offset_t offset, SeekOrigin origin) override
change file read/write position
int fcontrol(FileHandle file, ControlCode code, void *buffer, size_t bufSize) override
Low-level and non-standard file control operations.
int format() override
format the filing system
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:174
int check() override
Perform a file system consistency check.
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:178
int setVolume(uint8_t index, IFileSystem *fileSystem) override
Set volume for mountpoint.
bool isAllocated() const
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:110
IFS::DirHandle DirHandle
Definition: Core/FileSystem.h:25
FWFS File Descriptor.
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:93
Definition: Delegate.h:20
int getxattr(const char *path, AttributeTag tag, void *buffer, size_t size) override
Get an attribute from a file given its path.
int fstat(FileHandle file, Stat *stat) override
get file information
uint32_t file_size_t
Definition: Components/IFS/src/include/IFS/Types.h:50
IFileSystem * fileSystem
Definition: Components/IFS/src/include/IFS/FWFS/FileSystem.h:102