Add File System

docs/RustPOSIX/Architecture.md

@@ -47,6 +47,72 @@ The following are a breif description of the public methods
 - `insert_next_pipe` - given a pipe, insert it into the pipe table
 - `add_to_fd_table`, `rm_from_fd_table`, and `changedir` are **UNUSED!**
 
+# FILE SYSTEM
+# Inode Structure
+
+An important part of file representation, the Inode structure in SafePOSIX encompasses various formats of files supported by the system. Each file and directory in the filesystem has a different inode number.
+
+## Types of Inodes
+
+- **File**: Represents a standard file that contains data.
+- **CharDev**: Denotes a character device such as `/dev/null` or `/dev/zero`, including random number generators.
+- **Socket**: Represents a Unix domain socket, used for inter-process communication.
+- **Dir**: Represents a directory, organizing files and other directories.
+
+## Metadata within Inodes
+
+Each variant of Inode stores specific metadata:
+
+- **Common Metadata (all Inode types)**:
+  - `size`: Size of the file in bytes.
+  - `uid`, `gid`: User and group identity numbers.
+  - `mode`: Permissions of the file (read, write, execute).
+  - `linkcount`: Number of hard links that point to the inode.
+  - `refcount`: Counts open file descriptors of the file, allowing the system to track the file's lifetime internally.
+  - `atime`, `ctime`, `mtime`: Access, creation, modification timestamps.
+
+- **Directory-specific metadata (DirectoryInode)**:
+  - `filename_to_inode_dict`: A fast HashMap of filenames.
+
+- **Character Device-Specific Metadata (DeviceInode)**:
+  - `dev`: A DevNo struct holding the major and minor device numbers, uniquely identifying the device.
+
+## Ref Counting and File Lifetimes
+
+Refcount is used to manage file lifetimes. When a file is opened, its refcount increases; when closed, it decreases. The file is deleted only if both the link and ref count are 0, ensuring no current process can access the file.
+
+# Metadata
+
+## FilesystemMetadata Data Structure
+
+The FilesystemMetadata struct holds central filesystem-wide data:
+
+- `nextinode`: The next available inode number, ensuring uniqueness for new files and directories.
+- `dev_id`: The device ID where the filesystem resides.
+- `Inodetable`: HashMap mapping inode numbering to InodeEnum for quick lookups of file and directory metadata.
+
+# Logging for Correctness and Recovery
+
+## Write Ahead Logging
+
+- **Log File**: Modifications to filesystem metadata are initially recorded in the "lind.md.log" file before being committed to actual metadata structures.
+- **Crash Recovery**: Upon reboot, the log file is scanned. If any inconsistencies are found, it will replay the logged changes, restoring the filesystem to a consistent state.
+
+## Logging Functionality
+
+- `log_metadata`: Adds a log entry (inode number and potentially some inode data) to a log file, enabling crash recovery or the ability to undo certain changes.
+- `persist_metadata`: Serializes the entire FilesystemMetadata object and writes its data onto disk, allowing the system to remember the state of the filesystem.
+
+# Path Traversal
+
+Translation from paths to inode numbers, and vice versa, is aided by the following functions:
+
+- `metawalkandparent`: Given a path, Returns the inode number of the last element in it, and the inode number of its parent directory.
+- `metawalk`: Similar to metawalkandparent, but returns only inode number of the last element in it.
+- `pathnamefrominodenum`: Given an inode number, performs the opposite of the above operation.
+- `filenamefrominode`: Given a directory inode and a target inode number that belongs to any file within the directory, it returns the filename of the given inode from the directory’s files.
+
+
 ## FS Metadata
 
 Our metadata table (in the code, this is `FilesystemMetadata` struct) is similar to how the metadatatable from SafePOSIX-Repy operated.