Merge pull request #2 from amlel-el-mahrouss/dev

embdfs: add filesystem structure + tex files.

4 files changed, 167 insertions, 16 deletions

diff --git a/.gitignore b/.gitignore
index 9d7ef2e..5d0bfd2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,4 +32,6 @@
 *.app
 
 # CMake build output
-*/build/
\ No newline at end of file
+*/build/
+
+*.pdf
\ No newline at end of file
diff --git a/lib/astdx/embdfs.hpp b/lib/astdx/embdfs.hpp
index 6b018cf..dbb0042 100644
--- a/lib/astdx/embdfs.hpp
+++ b/lib/astdx/embdfs.hpp
@@ -15,7 +15,7 @@
 /// @brief A Filesystem designed for tiny storage medias.
 /// @author Amlal EL Mahrouss (amlal@nekernel.org)
 
-namespace astdx::freestanding
+namespace astdx::embdfs
 {
 	namespace details
 	{
@@ -24,6 +24,9 @@ namespace astdx::freestanding
 
 		inline constexpr const size_t _superblock_name_len	  = 16;
 		inline constexpr const size_t _superblock_reserve_len = 462;
+		inline constexpr const size_t _inode_name_len		  = 128;
+		inline constexpr const size_t _inode_arr_len		  = 12;
+		inline constexpr const size_t _inode_lookup_len		  = 8;
 
 #ifdef EMBDFS_28BIT_LBA
 		typedef std::uint32_t lba_t;
@@ -50,21 +53,26 @@ namespace astdx::freestanding
 			utf8_char_t s_name[_superblock_name_len];
 			utf8_char_t s_reserved[_superblock_reserve_len];
 		};
-	} // namespace details
 
-	/// @brief Creates the library context.
-	/// @return Whether it suceeded or not.
-	inline int32_t embdfs_create_context()
-	{
-		return 0;
-	}
+		/// @brief Indexed node structure.
+		/// @brief i_name file name
+		/// @brief i_size_virt, i_size_phys: virtual and physical (sector count) size.
+		/// @brief i_offset direct block pointer.
+		/// @brief i_checksum crc32 checksum.
+		/// @brief i_flags_perms flags and permissions
+		/// @brief i_acl_* ACL to keep track of inode allocation status.
+		struct embdfs_inode
+		{
+			utf8_char_t i_name[_inode_name_len];
+			sword_t		i_size_virt, i_size_phys;
+			lba_t		i_offset[_inode_lookup_len];
+			sword_t		i_checksum, i_flags_perms;
+			lba_t		i_acl_creat, i_acl_edit, i_acl_delet;
+		};
 
-	/// @brief Destroys the library context.
-	/// @return Whether it suceeded or not.
-	inline int32_t embdfs_destroy_context()
-	{
-		return 0;
-	}
-} // namespace astdx::freestanding
+		/// @brief Indexed node linear array.
+		typedef embdfs_inode embdfs_inode_arr_t[_inode_arr_len];
+	} // namespace details
+} // namespace astdx::embdfs
 
 #endif // ifndef _STDX_EMBDFS_HPP
\ No newline at end of file
diff --git a/meta/pdf/.keep b/meta/pdf/.keep
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/meta/pdf/.keep
diff --git a/meta/tex/embdfs.tex b/meta/tex/embdfs.tex
new file mode 100644
index 0000000..1c63b7a
--- /dev/null
+++ b/meta/tex/embdfs.tex
@@ -0,0 +1,141 @@
+\documentclass{article}
+\usepackage[a4paper,margin=1in]{geometry}
+\usepackage{listings}
+\usepackage{xcolor}
+\usepackage{amsmath}
+\usepackage{hyperref}
+\usepackage{longtable}
+\usepackage{graphicx}
+\usepackage{fancyhdr}
+\usepackage{titlesec}
+\usepackage{caption}
+
+\titleformat{\section}{\normalfont\Large\bfseries}{\thesection}{1em}{}
+
+\definecolor{codegray}{gray}{0.95}
+\lstset{
+  backgroundcolor=\color{codegray},
+  basicstyle=\ttfamily\small,
+  breaklines=true,
+  frame=single,
+  tabsize=4,
+  language=C++,
+  showstringspaces=false
+}
+
+\title{Embedded File System (EMBFS) Specification}
+\author{Amlal El Mahrouss}
+\date{2025}
+
+\begin{document}
+
+\maketitle
+
+\section{Overview}
+The \textbf{Embedded File System (EMBFS)} is a compact and minimal filesystem designed for use in embedded environments with limited storage media. This specification describes its key data structures, constants, and layout.
+
+\section{Namespace}
+The EMBFS implementation resides under:
+\begin{lstlisting}
+namespace astdx::embdfs
+\end{lstlisting}
+
+\section{Supported Logical Block Addressing (LBA) Modes}
+Two LBA addressing modes are supported via macro definitions:
+\begin{itemize}
+    \item \texttt{EMBDFS\_28BIT\_LBA} — Uses \texttt{uint32\_t}.
+    \item \texttt{EMBDFS\_48BIT\_LBA} — Uses \texttt{uint64\_t}.
+\end{itemize}
+
+\section{Fundamental Types}
+\begin{longtable}{|l|l|}
+\hline
+\textbf{Type} & \textbf{Definition} \\
+\hline
+\texttt{lba\_t} & 28-bit or 48-bit logical block address \\
+\texttt{sword\_t} & \texttt{int16\_t} \\
+\texttt{sdword\_t} & \texttt{int32\_t} \\
+\texttt{utf8\_char\_t} & \texttt{uint8\_t}, used for file names and labels \\
+\hline
+\end{longtable}
+
+\section{Constants}
+\begin{longtable}{|l|l|}
+\hline
+\textbf{Constant} & \textbf{Description} \\
+\hline
+\texttt{\_superblock\_name\_len} & Length of superblock name (16 bytes) \\
+\texttt{\_superblock\_reserve\_len} & Reserved bytes in superblock (462 bytes) \\
+\texttt{\_inode\_name\_len} & Length of inode file name (128 bytes) \\
+\texttt{\_inode\_arr\_len} & Number of inodes per partition (12) \\
+\texttt{\_inode\_lookup\_len} & Number of direct LBA pointers in inode (8) \\
+\hline
+\end{longtable}
+
+\section{Superblock Structure}
+\textbf{Structure:} \texttt{embdfs\_superblock}
+\begin{lstlisting}
+struct embdfs_superblock {
+    sword_t     s_block_mag;
+    sdword_t    s_num_inodes;
+    sdword_t    s_part_size;
+    sdword_t    s_part_used;
+    sdword_t    s_version;
+    sword_t     s_sector_sz;
+    lba_t       s_inode_start;
+    lba_t       s_inode_end;
+    utf8_char_t s_name[16];
+    utf8_char_t s_reserved[462];
+};
+\end{lstlisting}
+
+\textbf{Description:}
+\begin{itemize}
+    \item \texttt{s\_block\_mag} — Magic number identifying the filesystem
+    \item \texttt{s\_num\_inodes} — Total number of inodes
+    \item \texttt{s\_part\_size} — Total size of the partition (in sectors)
+    \item \texttt{s\_part\_used} — Used size of the partition
+    \item \texttt{s\_version} — Filesystem version
+    \item \texttt{s\_sector\_sz} — Sector size (in bytes)
+    \item \texttt{s\_inode\_start}, \texttt{s\_inode\_end} — LBA range where inodes are stored
+    \item \texttt{s\_name} — Filesystem label
+    \item \texttt{s\_reserved} — Reserved for future use
+\end{itemize}
+
+\section{Inode Structure}
+\textbf{Structure:} \texttt{embdfs\_inode}
+\begin{lstlisting}
+struct embdfs_inode {
+    utf8_char_t i_name[128];
+    sword_t     i_size_virt, i_size_phys;
+    lba_t       i_offset[8];
+    sword_t     i_checksum, i_flags_perms;
+    lba_t       i_acl_creat, i_acl_edit, i_acl_delet;
+};
+\end{lstlisting}
+
+\textbf{Description:}
+\begin{itemize}
+    \item \texttt{i\_name} — UTF-8 encoded file name
+    \item \texttt{i\_size\_virt} — Virtual file size (logical size)
+    \item \texttt{i\_size\_phys} — Physical size in sectors
+    \item \texttt{i\_offset} — Array of direct LBA pointers
+    \item \texttt{i\_checksum} — CRC32 checksum of file contents
+    \item \texttt{i\_flags\_perms} — Flags and permissions field
+    \item \texttt{i\_acl\_creat}, \texttt{i\_acl\_edit}, \texttt{i\_acl\_delet} — ACLs for access control
+\end{itemize}
+
+\section{Inode Array Type}
+\begin{lstlisting}
+typedef embdfs_inode embdfs_inode_arr_t[12];
+\end{lstlisting}
+Represents a fixed-size array of 12 inodes within a given partition.
+
+\section{License}
+\begin{itemize}
+    \item Copyright © 2025 Amlal El Mahrouss
+    \item All rights reserved.
+    \item For questions or licensing requests, contact: \texttt{amlal@nekernel.org}
+\end{itemize}
+
+\end{document}
\ No newline at end of file