diff options
Diffstat (limited to 'docs/tex')
| -rw-r--r-- | docs/tex/hefs.tex | 83 | ||||
| -rw-r--r-- | docs/tex/mbci.tex | 117 |
2 files changed, 170 insertions, 30 deletions
diff --git a/docs/tex/hefs.tex b/docs/tex/hefs.tex index afafc472..6d7c1c53 100644 --- a/docs/tex/hefs.tex +++ b/docs/tex/hefs.tex @@ -4,7 +4,7 @@ \usepackage{longtable} \usepackage{listings} \geometry{margin=1in} -\title{HeFS Filesystem Specification (v0x0103)} +\title{HeFS Filesystem Specification (v1.3)} \author{Amlal El Mahrouss} \date{2025} @@ -22,18 +22,20 @@ The High-throughput Extended File System (HeFS) is a custom filesystem tailored \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} & 16 MiB \\ -\texttt{kHeFSDefaultVoluneName} & "HeFS Volume" \\ -\texttt{kHeFSINDStartOffset} & Offset after boot + dir nodes \\ +\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} +\section{Disk and File Metadata Enums}\label{sec:disk-and-file-metadata-enums} -\subsection{Drive Kind (\texttt{UInt8})} +\subsection{Drive Kind (\texttt{UInt8})}\label{subsec:drive-kind-(texttt{uint8})} \begin{itemize} \item 0xC0: Hard Drive \item 0xC1: Solid State Drive @@ -44,7 +46,7 @@ The High-throughput Extended File System (HeFS) is a custom filesystem tailored \item 0xFF: Unknown \end{itemize} -\subsection{Disk Status (\texttt{UInt8})} +\subsection{Disk Status (\texttt{UInt8})}\label{subsec:disk-status-(texttt{uint8})} \begin{itemize} \item 0x18: Unlocked \item 0x19: Locked @@ -52,12 +54,21 @@ The High-throughput Extended File System (HeFS) is a custom filesystem tailored \item 0x1B: Invalid \end{itemize} -\subsection{Encoding Flags (\texttt{UInt16})} +\subsection{Encoding Flags (\texttt{UInt16})}\label{subsec:encoding-flags-(texttt{uint16})} \begin{itemize} -\item UTF-8, UTF-16, UTF-32, Binary (with endianness variants) +\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})} +\subsection{File Kinds (\texttt{UInt16})}\label{subsec:file-kinds-(texttt{uint16})} \begin{itemize} \item 0x00: Regular File \item 0x01: Directory @@ -69,14 +80,19 @@ The High-throughput Extended File System (HeFS) is a custom filesystem tailored \item 0x07: Unknown \end{itemize} -\subsection{File Flags (\texttt{UInt32})} +\subsection{File Flags (\texttt{UInt32})}\label{subsec:file-flags-(texttt{uint32})} \begin{itemize} -\item ReadOnly, Hidden, System, Archive, Device +\item 0x000: None +\item 0x100: ReadOnly +\item 0x101: Hidden +\item 0x102: System +\item 0x103: Archive +\item 0x104: Device \end{itemize} -\section{Structures} +\section{Structures}\label{sec:structures} -\subsection{HEFS\_BOOT\_NODE} +\subsection{HEFS\_BOOT\_NODE}\label{subsec:hefs_boot_node} Acts as the superblock. \begin{itemize} @@ -84,33 +100,40 @@ Acts as the superblock. \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} + \item Reserved: \texttt{fStartIN}, \texttt{fEndIN}, \texttt{fStartBlock}, \texttt{fEndBlock} \end{itemize} -\subsection{HEFS\_INDEX\_NODE} +\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 Symbolic link: \texttt{fSymLink} + \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{fOffsetSlices}, \texttt{fSlices[kHeFSSliceCount]} as (base, length) pairs + \item Block data: \texttt{fOffsetSliceLow}, \texttt{fOffsetSliceHigh} \end{itemize} -\subsection{HEFS\_INDEX\_NODE\_DIRECTORY} +\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 inodes - \item Tree links: \texttt{fColor}, \texttt{fNext}, \texttt{fPrev}, \texttt{fChild}, \texttt{fParent} + \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)} +\section{Timestamp Layout (ATime)}\label{sec:timestamp-layout-(atime)} -\texttt{ATime} is a 64-bit timestamp with the following structure: +\texttt{ATime} is a 64-bit timestamp and allocation status tracker with the following structure: \begin{itemize} \item Bits 63-32: Year @@ -126,7 +149,7 @@ Constants: \item \texttt{kHeFSTimeMax = 0xFFFFFFFFFFFFFFFF - 1} \end{itemize} -\section{Filesystem API} +\section{Filesystem API}\label{sec:filesystem-api} Provided by \texttt{Kernel::HeFS::HeFileSystemParser}. @@ -134,18 +157,18 @@ Provided by \texttt{Kernel::HeFS::HeFileSystemParser}. \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)} + \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{INodeCtl\_}, \texttt{INodeDirectoryCtl\_} + \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. +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} diff --git a/docs/tex/mbci.tex b/docs/tex/mbci.tex new file mode 100644 index 00000000..71907376 --- /dev/null +++ b/docs/tex/mbci.tex @@ -0,0 +1,117 @@ + +\documentclass{article} +\usepackage{geometry} +\usepackage{longtable} +\usepackage{listings} +\usepackage{xcolor} +\geometry{margin=1in} +\title{MBCI: Mini Bus Controller Interface Specification} +\author{Amlal El Mahrouss} +\date{2025} + +\begin{document} + +\maketitle + +\section{Overview} +The Mini Bus Controller Interface (MBCI) is a standardized memory-mapped I/O bus specification designed for use in embedded systems and operating system kernels. It provides an extensible framework for managing hardware devices via a shared bus using memory-mapped registers. It is designed to remain abstract and platform-agnostic, leaving platform-specific interrupt and address logic to the HAL. + +\section{Signal Lines} +The MBCI bus interface includes the following signal lines: + +\begin{itemize} + \item \textbf{VCC} (IN) – Power supply (OUT for MCU) + \item \textbf{CLK} (IN) – Clock line (OUT for MCU) + \item \textbf{ACK} (BI) – Acknowledge line containing packet frame + \item \textbf{D0-, D1-} (IN) – Host interface packet input + \item \textbf{D0+, D1+} (OUT) – Host interface packet output + \item \textbf{GND} (IN) – Ground line (OUT for MCU) +\end{itemize} + +\section{Host Structure} + +\subsection*{IMBCIHost Structure} + +\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] +volatile struct IMBCIHost { + UInt32 Magic; + UInt32 HostId; + UInt16 VendorId; + UInt16 DeviceId; + UInt8 MemoryType; + UInt16 HostType; + UInt16 HostFlags; + UInt8 Error; + UInt32 MMIOTest; + UInt16 State; + UInt8 Status; + UInt8 InterruptEnable; + UInt64 BaseAddressRegister; + UInt64 BaseAddressRegisterSize; + UInt32 CommandIssue; + UInt8 Esb[64]; // Extended Signature Block + UInt8 Zero[8]; +}; +\end{lstlisting} + +\section{Enumerations} + +\subsection*{Device Speeds} +\begin{itemize} + \item \texttt{kMBCISpeedDeviceInvalid} + \item \texttt{kMBCILowSpeedDevice} + \item \texttt{kMBCIHighSpeedDevice} +\end{itemize} + +\subsection*{Host Flags} +\begin{itemize} + \item \texttt{kMBCIHostFlagsSupportsNothing} + \item \texttt{kMBCIHostFlagsSupportsAPM} + \item \texttt{kMBCIHostFlagsSupportsDaisyChain} + \item \texttt{kMBCIHostFlagsSupportsHWInterrupts} + \item \texttt{kMBCIHostFlagsSupportsDMA} + \item \texttt{kMBCIHostFlagsExtended} +\end{itemize} + +\subsection*{Host Types} +\begin{itemize} + \item \texttt{kMBCIHostKindHardDisk} + \item \texttt{kMBCIHostKindOpticalDisk} + \item \texttt{kMBCIHostKindKeyboardLow} + \item \texttt{kMBCIHostKindMouseLow} + \item \texttt{kMBCIHostKindMouseHigh} + \item \texttt{kMBCIHostKindKeyboardHigh} + \item \texttt{kMBCIHostKindNetworkInterface} + \item \texttt{kMBCIHostKindDaisyChain} + \item \texttt{kMBCIHostKindStartExtended} +\end{itemize} + +\subsection*{Host State} +\begin{itemize} + \item \texttt{kMBCIHostStateInvalid} + \item \texttt{kMBCIHostStateReset} + \item \texttt{kMBCIHostStateSuccess} + \item \texttt{kMBCIHostStateReady} + \item \texttt{kMBCIHostStateDmaStart} + \item \texttt{kMBCIHostStateDmaEnd} + \item \texttt{kMBCIHostStateFail} + \item \texttt{kMBCIHostStateCount} +\end{itemize} + +\section{Functions} + +\subsection*{MMIO Test} +Tests if MMIO is accessible by writing and checking a challenge value. Times out if the bus does not respond. + +\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] +inline BOOL busi_test_mmio(struct IMBCIHost* host, const UInt32 test); +\end{lstlisting} + +\subsection*{Auth Key Reader} +Reads the 24-bit auth key encoded in the last three bytes of the Extended Signature Block after verifying MMIO test success: + +\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] +inline MBCIAuthKeyType mbci_read_auth_key(struct IMBCIHost* host); +\end{lstlisting} + +\end{document} |