feat! firmware breaking changes on the API.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>

6 files changed, 370 insertions, 0 deletions

diff --git a/doc/.gitkeep b/doc/.gitkeep
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/.gitkeep
diff --git a/doc/drawio/FIRMWARE.drawio b/doc/drawio/FIRMWARE.drawio
new file mode 100644
index 0000000..7cfc174
--- /dev/null
+++ b/doc/drawio/FIRMWARE.drawio
@@ -0,0 +1,43 @@
+<mxfile host="65bd71144e">
+    <diagram id="Y4IiTM2VAUaSzFU077Gh" name="Page-1">
+        <mxGraphModel dx="1144" dy="698" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+            <root>
+                <mxCell id="0"/>
+                <mxCell id="1" parent="0"/>
+                <mxCell id="2" value="EMBDFS (LAST BYTES TO BE LOADED BY BFL)" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+                    <mxGeometry x="305" y="180" width="240" height="70" as="geometry"/>
+                </mxCell>
+                <mxCell id="5" style="edgeStyle=none;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="3" target="4">
+                    <mxGeometry relative="1" as="geometry"/>
+                </mxCell>
+                <mxCell id="6" value="Loads Stage2 from" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="5">
+                    <mxGeometry x="-0.1733" relative="1" as="geometry">
+                        <mxPoint as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="7" style="edgeStyle=none;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;" edge="1" parent="1" source="3" target="2">
+                    <mxGeometry relative="1" as="geometry"/>
+                </mxCell>
+                <mxCell id="8" value="Loads Driver from" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="7">
+                    <mxGeometry x="0.15" y="-2" relative="1" as="geometry">
+                        <mxPoint as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="3" value="BASE FIRMWARE LAYER (FIRST BYTES&lt;div&gt;TO BE LOADED)&lt;/div&gt;" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+                    <mxGeometry x="305" y="370" width="240" height="60" as="geometry"/>
+                </mxCell>
+                <mxCell id="9" style="edgeStyle=none;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="4" target="3">
+                    <mxGeometry relative="1" as="geometry"/>
+                </mxCell>
+                <mxCell id="10" value="If Stage2 part, load it and replace current context&lt;div&gt;with Stage2&lt;/div&gt;" style="edgeLabel;html=1;align=left;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="9">
+                    <mxGeometry x="0.414" y="-2" relative="1" as="geometry">
+                        <mxPoint as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="4" value="EPM Partition" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;" vertex="1" parent="1">
+                    <mxGeometry x="30" y="540" width="190" height="70" as="geometry"/>
+                </mxCell>
+            </root>
+        </mxGraphModel>
+    </diagram>
+</mxfile>
\ No newline at end of file
diff --git a/doc/md/SPECIFICATION_FIRMWARE.md b/doc/md/SPECIFICATION_FIRMWARE.md
new file mode 100644
index 0000000..bfb3134
--- /dev/null
+++ b/doc/md/SPECIFICATION_FIRMWARE.md
@@ -0,0 +1,39 @@
+==================================================================
+
+                     Multi Platform Firmware
+
+==================================================================
+
+==================================================================
+0. Objective:
+==================================================================
+
+- Optimized for each target.
+- EPM/GPT compilant.
+- AMD64, PowerPC, RISC-V, 64x0, 32x0 support.
+- SMP support.
+
+==================================================================
+1. Solutions:
+==================================================================
+
+- Abstract Memory and I/O. (pci-tree)
+- Platform Independent Device Tree. (pci-tree)
+- Common Starting point for each core (smp)
+
+==================================================================
+2. Memory Layout:
+==================================================================
+
+- 0x80000000/0x00FF/0x0000: Firmware Startup Code
+- 0x90000000/0x7c00: Linear Header or EPM partition.
+
+==================================================================
+3. Error Codes:
+==================================================================
+
+- CB0001: Not bootable to Stage2 (or bootloader).
+- CB0003: Bad arch.
+- CB0002: Context returned early.
+
+
diff --git a/doc/tex/30pin.tex b/doc/tex/30pin.tex
new file mode 100644
index 0000000..386ddbe
--- /dev/null
+++ b/doc/tex/30pin.tex
@@ -0,0 +1,73 @@
+
+\documentclass{article}
+\usepackage{listings}
+\usepackage{xcolor}
+\usepackage{geometry}
+\usepackage{titlesec}
+\usepackage{fancyhdr}
+\usepackage{amsmath}
+\usepackage{amsfonts}
+\usepackage{graphicx}
+\usepackage{enumitem}
+\geometry{margin=1in}
+
+\titleformat{\section}{\large\bfseries}{\thesection}{1em}{}
+\titleformat{\subsection}{\normalsize\bfseries}{\thesubsection}{1em}{}
+
+\title{\texttt{30Pin} Technical Specification}
+\author{Amlal El Mahrouss}
+\date{\today}
+
+\lstset{
+    basicstyle=\ttfamily\footnotesize,
+    keywordstyle=\color{blue},
+    commentstyle=\color{gray},
+    stringstyle=\color{red},
+    showstringspaces=false,
+    breaklines=true
+}
+
+\begin{document}
+
+\maketitle
+
+\section*{File Description}
+\textbf{File:} \texttt{30pin.h} \\
+\textbf{Description:} This header defines the 30pin recovery protocol structures, constants, and packet kinds.
+
+\section{Constants}
+\begin{itemize}[leftmargin=2em]
+    \item \texttt{NB\_30PIN\_MAG} - Magic number identifier for a 30pin packet. Defined as \texttt{"TP"}.
+    \item \texttt{NB\_30PIN\_MAG\_LEN} - Length of the magic number (\texttt{2} bytes).
+    \item \texttt{NB\_30PIN\_BUFFER\_LEN} - Length of the data buffer in the packet (\texttt{498} bytes).
+    \item \texttt{NB\_30PIN\_EOP\_LEN} - Length of the end-of-packet data (\texttt{11} bytes).
+\end{itemize}
+
+\section{Data Structures}
+\subsection{\texttt{nb\_tpin\_recovery\_packet}}
+\begin{lstlisting}[language=C]
+struct _nb_tpin_recovery_packet
+{
+    uint8_t mag[NB_30PIN_MAG_LEN];     // Magic number
+    uint8_t kind;                      // Packet kind identifier
+    uint8_t buffer[NB_30PIN_BUFFER_LEN]; // Packet data buffer
+    uint8_t eop[NB_30PIN_EOP_LEN];     // End-of-packet data
+};
+\end{lstlisting}
+
+\textbf{Typedef:} \texttt{nb\_tpin\_recovery\_packet\_t}
+
+\section{Enumerations}
+\subsection{Packet Kinds}
+Defines the kinds of packets used in the 30pin recovery protocol:
+
+\begin{itemize}[leftmargin=2em]
+    \item \texttt{TPIN\_RECOVERY\_PACKET\_KIND\_UNKNOWN = 0}
+    \item \texttt{TPIN\_RECOVERY\_PACKET\_KIND\_BOOT = 1}
+    \item \texttt{TPIN\_RECOVERY\_PACKET\_KIND\_DATA = 2}
+    \item \texttt{TPIN\_RECOVERY\_PACKET\_KIND\_EOP = 3}
+    \item \texttt{TPIN\_RECOVERY\_PACKET\_KIND\_EOP\_ACK = 4}
+    \item \texttt{TPIN\_RECOVERY\_PACKET\_KIND\_EOP\_NACK = 5}
+\end{itemize}
+
+\end{document}
diff --git a/doc/tex/epm.tex b/doc/tex/epm.tex
new file mode 100644
index 0000000..c8b1d7a
--- /dev/null
+++ b/doc/tex/epm.tex
@@ -0,0 +1,143 @@
+\documentclass[12pt]{article}
+\usepackage[utf8]{inputenc}
+\usepackage[margin=1in]{geometry}
+\usepackage{titlesec}
+\usepackage{listings}
+\usepackage{xcolor}
+\usepackage{amsmath}
+\usepackage{caption}
+\usepackage{longtable}
+
+\titleformat{\section}{\large\bfseries}{\thesection}{1em}{}
+\titleformat{\subsection}{\normalsize\bfseries}{\thesubsection}{1em}{}
+
+\definecolor{codegray}{gray}{0.95}
+
+\lstdefinestyle{customc}{
+  backgroundcolor=\color{codegray},
+  basicstyle=\ttfamily\footnotesize,
+  keywordstyle=\color{blue},
+  commentstyle=\color{gray},
+  stringstyle=\color{red},
+  breaklines=true,
+  showstringspaces=false,
+  frame=single,
+  language=C
+}
+
+\title{EPM Partition Map: Technical Specification}
+\author{Amlal El Mahrouss}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{Overview}
+This document specifies the Explicit Partition Map (EPM) data structures and constants as defined in \texttt{partition\_map.h}. The EPM is designed to store partition information in a platform-independent manner with architecture-specific magic identifiers.
+
+\section{Constants and Macros}
+
+\subsection{Magic Strings}
+\begin{longtable}{|l|l|}
+\hline
+\textbf{Macro} & \textbf{Description} \\
+\hline
+\texttt{EPM\_MAGIC\_X86} & "EPMAM", used on AMD64 \\
+\texttt{EPM\_MAGIC\_RV} & "EPMRV", used on RISC-V \\
+\texttt{EPM\_MAGIC\_ARM} & "EPMAR", used on ARM \\
+\texttt{EPM\_MAGIC\_64X0} & "EPM64", for custom 64x0 architecture \\
+\texttt{EPM\_MAGIC\_32X0} & "EPM32", for custom 32x0 architecture \\
+\texttt{EPM\_MAGIC\_PPC} & "EPMPC", used on POWER \\
+\texttt{EPM\_MAGIC} & Defaults based on architecture \\
+\hline
+\end{longtable}
+
+\subsection{Layout Macros}
+\begin{itemize}
+  \item \texttt{EPM\_MAX\_BLKS = 128} \\
+  Maximum number of blocks in the partition table (first 128 LBAs).
+  \item \texttt{EPM\_PART\_BLK\_SZ} \\
+  Size of the \texttt{part\_block} structure.
+  \item \texttt{EPM\_PART\_BLK\_START = 0} \\
+  Start LBA of EPM partition headers.
+  \item \texttt{EPM\_REVISION = 2} \\
+  Current revision of the EPM format.
+\end{itemize}
+
+\section{Data Structures}
+
+\subsection{boot\_guid\_t}
+\begin{lstlisting}[style=customc]
+typedef struct boot_guid {
+  uint32_t data1;
+  uint16_t data2;
+  uint16_t data3;
+  uint8_t  data4[8];
+} __attribute__((packed)) boot_guid_t;
+\end{lstlisting}
+A GUID structure used for identifying partitions.
+
+\subsection{part\_block}
+\begin{lstlisting}[style=customc]
+struct __attribute__((packed)) part_block {
+  ascii_char_t magic[5];        // Magic string
+  ascii_char_t name[32];        // Human-readable name
+  boot_guid_t  uuid;            // Partition UUID
+  int32_t      version;         // Partition version
+  int32_t      num_blocks;      // Number of blocks
+  int64_t      lba_start;       // Starting LBA
+  int64_t      sector_sz;       // Sector size
+  int64_t      lba_end;         // Ending LBA
+  int16_t      type;            // Partition type
+  int32_t      fs_version;      // Filesystem version
+  ascii_char_t fs[16];          // Filesystem name
+  ascii_char_t reserved[401];   // Reserved for future use
+};
+\end{lstlisting}
+
+\subsection*{Filesystem Type Values}
+\begin{longtable}{|l|l|}
+\hline
+\textbf{Enum Value} & \textbf{Meaning} \\
+\hline
+\texttt{EPM\_INVALID} & \texttt{0x00} - Invalid/undefined \\
+\texttt{EPM\_GENERIC\_OS} & \texttt{0xcf} - Generic OS partition \\
+\texttt{EPM\_LINUX} & \texttt{0x8f} - Linux partition \\
+\texttt{EPM\_BSD} & \texttt{0x9f} - BSD partition \\
+\texttt{EPM\_NEKERNEL\_OS} & \texttt{0x1f} - NeKernel-specific \\
+\texttt{EPM\_SNU\_OS} & \texttt{0x1f} - SNU-specific \\
+\hline
+\end{longtable}
+
+\section{Functions}
+
+\subsection{\texttt{cb\_filesystem\_exists}}
+\begin{lstlisting}[style=customc]
+boolean cb_filesystem_exists(caddr_t fs, size_t len);
+\end{lstlisting}
+Checks if a filesystem name is supported.
+
+\subsection{\texttt{cb\_parse\_partition\_block\_data\_at}}
+\begin{lstlisting}[style=customc]
+bool cb_parse_partition_block_data_at(
+  voidptr_t blob,
+  size_t blob_sz,
+  size_t index,
+  size_t* end_lba,
+  size_t* start_lba,
+  size_t* sector_sz);
+\end{lstlisting}
+Parses an EPM partition block from a blob at the specified index and returns LBA information.
+
+\subsection{\texttt{cb\_parse\_partition\_block\_at}}
+\begin{lstlisting}[style=customc]
+part_block_t* cb_parse_partition_block_at(
+  voidptr_t blob,
+  size_t blob_sz,
+  size_t index);
+\end{lstlisting}
+Returns a pointer to a parsed EPM partition block at the specified index.
+
+\end{document}
+
diff --git a/doc/tex/pci-tree.tex b/doc/tex/pci-tree.tex
new file mode 100644
index 0000000..5ca6dfd
--- /dev/null
+++ b/doc/tex/pci-tree.tex
@@ -0,0 +1,72 @@
+\documentclass{article}
+\usepackage{graphicx} % Required for inserting images
+
+\title{The PCI Tree System}
+\author{Amlal El Mahrouss}
+\date{\today}
+
+\usepackage{listings}
+
+\lstset { %
+    language=C++,
+}
+
+\begin{document}
+
+\maketitle
+
+\section{Abstract}
+
+The PCI tree is an architecture designed to abstract away device specific data. One leaf might for instance hold an AHCI's HBA (Host Bus Adapter) into a '/pci-tree/@ahci' for instance. The advantage of this approach is the ability to quickly lookup and recognize a device from a tree given by a firmware at handoff.
+
+\section{The Protocol}
+
+Each leaf has a identification number of '0xfeedd00d', then followed by the version in a binary encoded format (0x1000). The offset and size of the offset and then given by the firmware. A PCI-Tree is assembled by the firmware itself. As the structures are not packed, thus multi-platform portability isn't possible.
+
+\section{Trade-offs}
+
+The trade-offs (portability, complexity) are largely justified by the need of a better and more straightforward way to recognize devices at the firmware level, the PCI tree approach helps us do exactly that.
+
+\subsection{Implementation of a PCI-Tree Leaf}
+
+Language of implementation is the C programming language
+
+\begin{lstlisting}
+struct hw_nb_pci_tree {
+  cb_pci_num_t d_magic;
+  cb_pci_num_t d_version;
+  cb_pci_num_t d_off_props;
+  cb_pci_num_t d_off_struct;
+  cb_pci_num_t d_sz_props;
+  cb_pci_num_t d_sz_struct;
+
+  cb_pci_num_t d_first_node;
+  cb_pci_num_t d_next_sibling;
+
+  cb_pci_char_t d_name[NB_PCI_NAME_LEN];
+};
+
+\end{lstlisting}
+
+\section{Official Implementations}
+
+\subsection{ISO C}
+
+\begin{ImplC}
+\item {SNU Trusted Base:} \url(https://snu.systems)
+\item {NeBoot (NeKernel Boot):} \url(https://github.com/nekernel-org/neboot)
+\end{ImplC}
+
+\subsection{ISO C++}
+
+\begin{ImplCxx}
+\item {No Implementation yet}
+\end{ImplCxx}
+
+\subsection{Forth}
+
+\begin{ImplForth}
+\item {No Implementation yet}
+\end{ImplForth}
+
+\end{document}