\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 performance-sensitive use cases.

\end{document}