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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{geometry}
\usepackage{longtable}
\usepackage{listings}
\geometry{margin=1in}
\title{HeFS Filesystem Specification (v1.3)}
\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{kHeFSMagicLen} & 8 \\
\texttt{kHeFSBlockLen} & 512 bytes \\
\texttt{kHeFSFileNameLen} & 256 characters \\
\texttt{kHeFSPartNameLen} & 128 characters \\
\texttt{kHeFSMinimumDiskSize} & 8 GiB \\
\texttt{kHeFSDefaultVolumeName} & "HeFS Volume" \\
\texttt{kHeFSINDStartOffset} & Offset after boot node \\
\texttt{kHeFSSearchAllStr} & "\*" (wildcard string) \\
\hline
\end{longtable}
\section{Disk and File Metadata Enums}\label{sec:disk-and-file-metadata-enums}
\subsection{Drive Kind (\texttt{UInt8})}\label{subsec: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})}\label{subsec: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})}\label{subsec:encoding-flags-(texttt{uint16})}
\begin{itemize}
\item UTF-8
\item UTF-16
\item UTF-32
\item UTF-16BE
\item UTF-16LE
\item UTF-32BE
\item UTF-32LE
\item UTF-8BE
\item UTF-8LE
\item Binary
\end{itemize}
\subsection{File Kinds (\texttt{UInt16})}\label{subsec: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})}\label{subsec:file-flags-(texttt{uint32})}
\begin{itemize}
\item 0x000: None
\item 0x100: ReadOnly
\item 0x101: Hidden
\item 0x102: System
\item 0x103: Archive
\item 0x104: Device
\end{itemize}
\section{Structures}\label{sec:structures}
\subsection{HEFS\_BOOT\_NODE}\label{subsec: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{fStartBlock}, \texttt{fEndBlock}
\end{itemize}
\subsection{HEFS\_INDEX\_NODE}\label{subsec:hefs_index_node}
Contains file metadata and block layout.
\begin{itemize}
\item \texttt{fHashPath}, \texttt{fFlags}, \texttt{fKind}, \texttt{fSize}, \texttt{fChecksum}
\item \texttt{fSymLink} - if set, \texttt{fHashPath} represents the symlink target
\item Time: \texttt{fCreated}, \texttt{fAccessed}, \texttt{fModified}, \texttt{fDeleted}
\item Ownership: \texttt{fUID}, \texttt{fGID}, \texttt{fMode}
\item Block data: \texttt{fOffsetSliceLow}, \texttt{fOffsetSliceHigh}
\end{itemize}
\subsection{HEFS\_INDEX\_NODE\_DIRECTORY}\label{subsec: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 inode links
\item RB-Tree Fields:
\begin{itemize}
\item \texttt{fColor}: Red or Black
\item \texttt{fNext}/\texttt{fPrev}: Sibling pointers
\item \texttt{fChild}: Left or right child (implementation-defined)
\item \texttt{fParent}: Parent node
\end{itemize}
\end{itemize}
\section{Timestamp Layout (ATime)}\label{sec:timestamp-layout-(atime)}
\texttt{ATime} is a 64-bit timestamp and allocation status tracker 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}\label{sec: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, kind)}
\item \texttt{DeleteINode(drive, flags, dir, name, kind)}
\item \texttt{INodeManip(drive, block, size, dir, kind, name, in)}
\end{itemize}
Internal helpers:
\begin{itemize}
\item \texttt{INodeCtlManip}, \texttt{INodeDirectoryCtlManip}
\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}
|
