1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{geometry}
\usepackage{longtable}
\usepackage{listings}
\geometry{margin=1in}
\title{HeFS Filesystem Specification (v0x0103)}
\author{Amlal El Mahrouss}
\date{2025}
\begin{document}
\maketitle
\section{Overview}
The High-throughput Extended File System (HeFS) is a custom filesystem tailored for performance, structure, and compact representation. It uses red-black trees for directory indexing, sparse block slicing for file layout, and fixed-size metadata structures optimized for 512-byte sector alignment.
\section{Constants and Macros}
\begin{longtable}{|l|l|}
\hline
\textbf{Name} & \textbf{Value / Description} \\
\hline
\texttt{kHeFSVersion} & 0x0103 \\
\texttt{kHeFSMagic} & " HeFS" (8-byte magic identifier) \\
\texttt{kHeFSFileNameLen} & 256 characters \\
\texttt{kHeFSPartNameLen} & 128 characters \\
\texttt{kHeFSMinimumDiskSize} & 16 MiB \\
\texttt{kHeFSDefaultVoluneName} & "HeFS Volume" \\
\texttt{kHeFSINDStartOffset} & Offset after boot + dir nodes \\
\texttt{kHeFSSearchAllStr} & "\*" (wildcard string) \\
\hline
\end{longtable}
\section{Disk and File Metadata Enums}
\subsection{Drive Kind (\texttt{UInt8})}
\begin{itemize}
\item 0xC0: Hard Drive
\item 0xC1: Solid State Drive
\item 0x0C: Optical Drive
\item 0xCC: USB Mass Storage
\item 0xC4: SCSI Drive
\item 0xC6: Flash Drive
\item 0xFF: Unknown
\end{itemize}
\subsection{Disk Status (\texttt{UInt8})}
\begin{itemize}
\item 0x18: Unlocked
\item 0x19: Locked
\item 0x1A: Error
\item 0x1B: Invalid
\end{itemize}
\subsection{Encoding Flags (\texttt{UInt16})}
\begin{itemize}
\item UTF-8, UTF-16, UTF-32, Binary (with endianness variants)
\end{itemize}
\subsection{File Kinds (\texttt{UInt16})}
\begin{itemize}
\item 0x00: Regular File
\item 0x01: Directory
\item 0x02: Block Device
\item 0x03: Character Device
\item 0x04: FIFO
\item 0x05: Socket
\item 0x06: Symbolic Link
\item 0x07: Unknown
\end{itemize}
\subsection{File Flags (\texttt{UInt32})}
\begin{itemize}
\item ReadOnly, Hidden, System, Archive, Device
\end{itemize}
\section{Structures}
\subsection{HEFS\_BOOT\_NODE}
Acts as the superblock.
\begin{itemize}
\item \texttt{fMagic}, \texttt{fVolName}, \texttt{fVersion}, \texttt{fChecksum}
\item Sector and disk geometry: \texttt{fSectorCount}, \texttt{fSectorSize}, \texttt{fBadSectors}
\item Drive info: \texttt{fDiskKind}, \texttt{fEncoding}, \texttt{fDiskStatus}, \texttt{fDiskFlags}, \texttt{fVID}
\item Tree layout: \texttt{fStartIND}, \texttt{fEndIND}, \texttt{fINDCount}
\item Reserved: \texttt{fStartIN}, \texttt{fEndIN}, \texttt{fReserved}, \texttt{fReserved1}
\end{itemize}
\subsection{HEFS\_INDEX\_NODE}
Contains file metadata and block layout.
\begin{itemize}
\item \texttt{fHashPath}, \texttt{fFlags}, \texttt{fKind}, \texttt{fSize}, \texttt{fChecksum}
\item Symbolic link: \texttt{fSymLink}
\item Time: \texttt{fCreated}, \texttt{fAccessed}, \texttt{fModified}, \texttt{fDeleted}
\item Ownership: \texttt{fUID}, \texttt{fGID}, \texttt{fMode}
\item Block data: \texttt{fOffsetSlices}, \texttt{fSlices[kHeFSSliceCount]} as (base, length) pairs
\end{itemize}
\subsection{HEFS\_INDEX\_NODE\_DIRECTORY}
Red-black tree based directory node.
\begin{itemize}
\item \texttt{fHashPath}, \texttt{fFlags}, \texttt{fKind}, \texttt{fEntryCount}, \texttt{fChecksum}
\item Time and ownership same as inode
\item \texttt{fINSlices[kHeFSSliceCount]} for storing child inodes
\item Tree links: \texttt{fColor}, \texttt{fNext}, \texttt{fPrev}, \texttt{fChild}, \texttt{fParent}
\end{itemize}
\section{Timestamp Layout (ATime)}
\texttt{ATime} is a 64-bit timestamp with the following structure:
\begin{itemize}
\item Bits 63-32: Year
\item Bits 31-24: Month
\item Bits 23-16: Day
\item Bits 15-8: Hour
\item Bits 7-0: Minute
\end{itemize}
Constants:
\begin{itemize}
\item \texttt{kHeFSTimeInvalid = 0x0}
\item \texttt{kHeFSTimeMax = 0xFFFFFFFFFFFFFFFF - 1}
\end{itemize}
\section{Filesystem API}
Provided by \texttt{Kernel::HeFS::HeFileSystemParser}.
\begin{itemize}
\item \texttt{Format(drive, flags, name)} - Format drive with HeFS
\item \texttt{CreateINodeDirectory(drive, flags, dir)}
\item \texttt{RemoveINodeDirectory(drive, flags, dir)}
\item \texttt{CreateINode(drive, flags, dir, name)}
\item \texttt{DeleteINode(drive, flags, dir, name)}
\item \texttt{WriteINode(drive, block, size, dir, name)}
\item \texttt{ReadINode(drive, block, size, dir, name)}
\end{itemize}
Internal helpers:
\begin{itemize}
\item \texttt{INodeCtl\_}, \texttt{INodeDirectoryCtl\_}
\end{itemize}
\section{Conclusion}
HeFS provides a modern and compact approach to high-performance file storage. Its use of red-black trees, fixed-size metadata, slice-based sparse files, and minimal overhead makes it a strong candidate for embedded and performance-sensitive use cases.
\end{document}
|
