1 files changed, 174 insertions, 0 deletions
diff --git a/docs/tex/openhefs.tex b/docs/tex/openhefs.tex
new file mode 100644
index 00000000..ea618196
--- /dev/null
+++ b/docs/tex/openhefs.tex
@@ -0,0 +1,174 @@
+\documentclass{article}
+\usepackage[utf8]{inputenc}
+\usepackage{geometry}
+\usepackage{longtable}
+\usepackage{listings}
+\geometry{margin=1in}
+\title{OpenHeFS: Hight-throughput extended File System}
+\author{Amlal El Mahrouss}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{Overview}
+The High-throughput Extended File System (OpenHeFS) 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{kOpenHeFSVersion} & 0x0103 \\
+\texttt{kOpenHeFSMagic} & "OpenHeFS" (8-byte magic identifier) \\
+\texttt{kOpenHeFSMagicLen} & 9 \\
+\texttt{kOpenHeFSBlockLen} & 512 bytes \\
+\texttt{kOpenHeFSFileNameLen} & 256 characters \\
+\texttt{kOpenHeFSPartNameLen} & 128 characters \\
+\texttt{kOpenHeFSMinimumDiskSize} & 128 GiB \\
+\texttt{kOpenHeFSDefaultVolumeName} & "OpenHeFS Volume" \\
+\texttt{kOpenHeFSINDStartOffset} & Offset after boot node \\
+\texttt{kOpenHeFSSearchAllStr} & "*" (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 of the filesystem, provides necessary information about the disk and the filesystem itself.
+
+\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[kOpenHeFSSliceCount]} 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{kOpenHeFSTimeInvalid = 0x0}
+  \item \texttt{kOpenHeFSTimeMax = 0xFFFFFFFFFFFFFFFF - 1}
+\end{itemize}
+
+\section{Filesystem API}\label{sec:filesystem-api}
+
+Provided by \texttt{Kernel::OpenHeFS::HeFileSystemParser}.
+
+\begin{itemize}
+  \item \texttt{Format(drive, flags, name)} - Format drive with OpenHeFS
+  \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}
+OpenHeFS 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 performance-sensitive use cases.
+
+\end{document}