\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}