diff options
| author | Amlal El Mahrouss <amlal@nekernel.org> | 2025-12-28 09:23:05 +0100 |
|---|---|---|
| committer | Amlal El Mahrouss <amlal@nekernel.org> | 2025-12-28 09:24:36 +0100 |
| commit | 9012c6fb7c040be92aa8f950bad4f49c5be264d8 (patch) | |
| tree | 581b9aaf6f372bf62c81d9626c63e835ea65736c /doc | |
| parent | 42d321d36c8922de043bb65693fd427c51f89f14 (diff) | |
feat! rename docs to doc.
Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/drawio/AHCI_DESIGN.drawio | 40 | ||||
| -rw-r--r-- | doc/drawio/LAUNCH_DESIGN.drawio | 22 | ||||
| -rw-r--r-- | doc/drawio/MBCI_DESIGN.drawio | 70 | ||||
| -rw-r--r-- | doc/drawio/SCHED_DESIGN.drawio | 34 | ||||
| -rw-r--r-- | doc/drawio/SOFT_SCHED_DESIGN.drawio | 25 | ||||
| -rw-r--r-- | doc/drawio/SYSTEM_DESIGN.drawio | 46 | ||||
| -rw-r--r-- | doc/drawio/TIMER_DESIGN.drawio | 49 | ||||
| -rw-r--r-- | doc/drawio/ZXD_DESIGN.drawio | 31 | ||||
| -rw-r--r-- | doc/specs/SPECIFICATION_FWRK.md | 302 | ||||
| -rw-r--r-- | doc/specs/SPECIFICATION_MBCI.md | 34 | ||||
| -rw-r--r-- | doc/specs/SPECIFICATION_OS.md | 82 | ||||
| -rw-r--r-- | doc/svg/OS_DESIGN.png | bin | 0 -> 22504 bytes | |||
| -rw-r--r-- | doc/tex/NOTICE.md | 10 | ||||
| -rw-r--r-- | doc/tex/binary_mutex.tex | 77 | ||||
| -rw-r--r-- | doc/tex/mini_bus_controller_interface.tex | 117 | ||||
| -rw-r--r-- | doc/tex/nefs.tex | 125 | ||||
| -rw-r--r-- | doc/tex/nekernel_smp_subsystem.tex | 32 | ||||
| -rw-r--r-- | doc/tex/openhefs.tex | 174 |
18 files changed, 1270 insertions, 0 deletions
diff --git a/doc/drawio/AHCI_DESIGN.drawio b/doc/drawio/AHCI_DESIGN.drawio new file mode 100644 index 00000000..73029de7 --- /dev/null +++ b/doc/drawio/AHCI_DESIGN.drawio @@ -0,0 +1,40 @@ +<mxfile host="65bd71144e"> + <diagram id="n4yoMa775TB45TuBg3XL" 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="4" style="edgeStyle=none;html=1;" parent="1" source="2" target="3" edge="1"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="8" style="edgeStyle=none;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="2" target="6"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="2" value="DRIVER I/O" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="490" y="310" width="120" height="170" as="geometry"/> + </mxCell> + <mxCell id="5" style="edgeStyle=none;html=1;exitX=1;exitY=0.25;exitDx=0;exitDy=0;entryX=0;entryY=0.25;entryDx=0;entryDy=0;" parent="1" source="3" target="2" edge="1"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="3" value="AHCI CTRL" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="170" y="310" width="120" height="170" as="geometry"/> + </mxCell> + <mxCell id="7" style="edgeStyle=none;html=1;exitX=0;exitY=0.25;exitDx=0;exitDy=0;entryX=1;entryY=0.25;entryDx=0;entryDy=0;" edge="1" parent="1" source="6" target="2"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="6" value="SK + AHCI FUNCTIONS" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="630" y="310" width="100" height="170" as="geometry"/> + </mxCell> + <mxCell id="10" style="edgeStyle=none;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="9" target="2"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="9" value="MAIN AHCI<br>DRIVER" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="630" y="490" width="100" height="170" as="geometry"/> + </mxCell> + <mxCell id="11" style="edgeStyle=none;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.03;entryY=0.841;entryDx=0;entryDy=0;entryPerimeter=0;" edge="1" parent="1" source="2" target="9"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile>
\ No newline at end of file diff --git a/doc/drawio/LAUNCH_DESIGN.drawio b/doc/drawio/LAUNCH_DESIGN.drawio new file mode 100644 index 00000000..32fe8eda --- /dev/null +++ b/doc/drawio/LAUNCH_DESIGN.drawio @@ -0,0 +1,22 @@ +<mxfile host="65bd71144e"> + <diagram id="WN9xM0SvnG1OFdIgUV1P" name="Page-1"> + <mxGraphModel dx="1149" dy="361" 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="LaunchHelpers" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="250" y="100" width="255" height="60" as="geometry"/> + </mxCell> + <mxCell id="3" value="ne_launch" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="250" y="170" width="255" height="60" as="geometry"/> + </mxCell> + <mxCell id="4" value="ne_kernel" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="250" y="240" width="540" height="60" as="geometry"/> + </mxCell> + <mxCell id="5" value="libSystem" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="520" y="170" width="270" height="60" as="geometry"/> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile>
\ No newline at end of file diff --git a/doc/drawio/MBCI_DESIGN.drawio b/doc/drawio/MBCI_DESIGN.drawio new file mode 100644 index 00000000..38aa8b92 --- /dev/null +++ b/doc/drawio/MBCI_DESIGN.drawio @@ -0,0 +1,70 @@ +<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36" version="26.0.14"> + <diagram name="Page-1" id="hkk8yLV24Qf0g4vqRryx"> + <mxGraphModel dx="1368" dy="751" 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="lO14xRhUFe0yug9pa5VE-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-1" target="lO14xRhUFe0yug9pa5VE-2"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-1" value="Reset" style="whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="120" y="700" width="140" height="60" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-5" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-2" target="lO14xRhUFe0yug9pa5VE-4"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-7" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-2" target="lO14xRhUFe0yug9pa5VE-6"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-2" value="Start" style="whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="420" y="700" width="120" height="60" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-8" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-4" target="lO14xRhUFe0yug9pa5VE-1"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-4" value="Failed" style="whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="420" y="880" width="120" height="60" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-10" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-6" target="lO14xRhUFe0yug9pa5VE-9"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-6" value="Success, Wait" style="whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="650" y="700" width="120" height="60" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-12" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-9" target="lO14xRhUFe0yug9pa5VE-4"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-14" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-9" target="lO14xRhUFe0yug9pa5VE-13"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-9" value="Transfer CMD" style="whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="840" y="700" width="120" height="60" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-16" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-13" target="lO14xRhUFe0yug9pa5VE-15"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-13" value="Read CMD" style="whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="1070" y="700" width="120" height="60" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-17" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-15" target="lO14xRhUFe0yug9pa5VE-4"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-19" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-15" target="lO14xRhUFe0yug9pa5VE-18"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-15" value="Do Op" style="whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="1070" y="980" width="120" height="60" as="geometry" /> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-20" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.25;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="lO14xRhUFe0yug9pa5VE-18"> + <mxGeometry relative="1" as="geometry"> + <mxPoint x="910" y="1150" as="sourcePoint" /> + <mxPoint x="710" y="760" as="targetPoint" /> + </mxGeometry> + </mxCell> + <mxCell id="lO14xRhUFe0yug9pa5VE-18" value="Send back and ready" style="whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="1070" y="1120" width="120" height="60" as="geometry" /> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile>
\ No newline at end of file diff --git a/doc/drawio/SCHED_DESIGN.drawio b/doc/drawio/SCHED_DESIGN.drawio new file mode 100644 index 00000000..ab75d000 --- /dev/null +++ b/doc/drawio/SCHED_DESIGN.drawio @@ -0,0 +1,34 @@ +<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36" version="24.7.14"> + <diagram name="Page-1" id="6QVppPX6dMcFLP7eY7Ap"> + <mxGraphModel dx="1368" dy="717" 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="V4mTDnC5FWkVb8QuH4lW-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="V4mTDnC5FWkVb8QuH4lW-1" target="V4mTDnC5FWkVb8QuH4lW-2"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="V4mTDnC5FWkVb8QuH4lW-1" value="ISCHEDOBJECT INTERFACE" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="90" y="70" width="670" height="60" as="geometry" /> + </mxCell> + <mxCell id="V4mTDnC5FWkVb8QuH4lW-11" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="V4mTDnC5FWkVb8QuH4lW-2" target="V4mTDnC5FWkVb8QuH4lW-4"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="V4mTDnC5FWkVb8QuH4lW-2" value="USER SCHEDULER/THREAD SCHEDULER/HW THREAD SCHEDULER" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="90" y="170" width="670" height="50" as="geometry" /> + </mxCell> + <mxCell id="V4mTDnC5FWkVb8QuH4lW-4" value="ANOTHER SCHEDULER OR DIRECT CALL TO DRIVER/HAL." style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="90" y="280" width="670" height="60" as="geometry" /> + </mxCell> + <mxCell id="V4mTDnC5FWkVb8QuH4lW-12" value="PROCESS BANKS CPU 1..N" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;" vertex="1" parent="1"> + <mxGeometry x="338" y="450" width="175" height="80" as="geometry" /> + </mxCell> + <mxCell id="V4mTDnC5FWkVb8QuH4lW-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;entryPerimeter=0;" edge="1" parent="1" source="V4mTDnC5FWkVb8QuH4lW-4" target="V4mTDnC5FWkVb8QuH4lW-12"> + <mxGeometry relative="1" as="geometry" /> + </mxCell> + <mxCell id="V4mTDnC5FWkVb8QuH4lW-15" value="<h1 style="margin-top: 0px;">Raise error checks when:</h1><p>- Kernel level tasks crashes.</p><p>- An assertion fails.</p><p>- System Call isn't returning correctly.</p><p>- Driver is at an uncertain state.</p>" style="text;html=1;whiteSpace=wrap;overflow=hidden;rounded=0;" vertex="1" parent="1"> + <mxGeometry x="580" y="390" width="180" height="210" as="geometry" /> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile> diff --git a/doc/drawio/SOFT_SCHED_DESIGN.drawio b/doc/drawio/SOFT_SCHED_DESIGN.drawio new file mode 100644 index 00000000..27d4e2b0 --- /dev/null +++ b/doc/drawio/SOFT_SCHED_DESIGN.drawio @@ -0,0 +1,25 @@ +<mxfile host="65bd71144e"> + <diagram name="Page-1" id="lDkK2i6CeL2VbSOVDvrP"> + <mxGraphModel dx="764" dy="289" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0"> + <root> + <mxCell id="0"/> + <mxCell id="1" parent="0"/> + <mxCell id="ifhO3zQZNW-sXvZMTmu8-2" value="libsci Dylib inside code (RING 3)" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="235.5" y="340" width="360" height="30" as="geometry"/> + </mxCell> + <mxCell id="ifhO3zQZNW-sXvZMTmu8-3" value="Running code (RING 3)" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="235.5" y="295" width="360" height="35" as="geometry"/> + </mxCell> + <mxCell id="ifhO3zQZNW-sXvZMTmu8-8" value="<h1 style="margin-top: 0px;"><span style="background-color: initial;">NeKernel Scheduler</span></h1><h1 style="margin-top: 0px;"><span style="font-size: 12px; font-weight: 400; background-color: initial;">This describes how NeKernel is structued to schedule tasks.</span><br></h1><div>A Process may be attached to another one (thread)</div><div>Otherwise it's a process within a team.</div>" style="text;html=1;whiteSpace=wrap;overflow=hidden;rounded=0;" parent="1" vertex="1"> + <mxGeometry x="620" y="290" width="180" height="200" as="geometry"/> + </mxCell> + <mxCell id="ifhO3zQZNW-sXvZMTmu8-13" value="Process structure (RING 0)" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="235.5" y="380" width="360" height="60" as="geometry"/> + </mxCell> + <mxCell id="4" value="HardwareThread, HardwareThreadScheduler and UserProcessScheduler (RING 0)" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="234" y="450" width="360" height="60" as="geometry"/> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile>
\ No newline at end of file diff --git a/doc/drawio/SYSTEM_DESIGN.drawio b/doc/drawio/SYSTEM_DESIGN.drawio new file mode 100644 index 00000000..ffc625d4 --- /dev/null +++ b/doc/drawio/SYSTEM_DESIGN.drawio @@ -0,0 +1,46 @@ +<mxfile host="65bd71144e"> + <diagram name="Page-1" id="lDkK2i6CeL2VbSOVDvrP"> + <mxGraphModel dx="960" dy="709" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0"> + <root> + <mxCell id="0"/> + <mxCell id="1" parent="0"/> + <mxCell id="ifhO3zQZNW-sXvZMTmu8-2" value="<p class="p1"><b>System API (libSystem.dll</b><b style="background-color: transparent;">) – User-Space Interface (Ring 3, EL0)</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="240" y="340" width="360" height="30" as="geometry"/> + </mxCell> + <mxCell id="ifhO3zQZNW-sXvZMTmu8-3" value="<p class="p1"><b>Applications &amp; Dynamically Linked Libraries (Ring 3, EL0)</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="240" y="240" width="180" height="35" as="geometry"/> + </mxCell> + <mxCell id="ifhO3zQZNW-sXvZMTmu8-13" value="<p class="p1"><b>NeKernel MP Kernel, DDK, and Drivers (Ring 0, EL1)</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="240" y="450" width="360" height="60" as="geometry"/> + </mxCell> + <mxCell id="4" value="<p class="p1"><b>SCI and DDK calls (Ring 0 / Ring 2, EL0 to EL1 Transitions)</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="240" y="380" width="360" height="60" as="geometry"/> + </mxCell> + <mxCell id="5" value="<p class="p1"><b>HAL</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="404.5" y="525" width="195.5" height="60" as="geometry"/> + </mxCell> + <mxCell id="6" value="<p class="p1"><b>NeKernel</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="140" y="525" width="250" height="60" as="geometry"/> + </mxCell> + <mxCell id="7" value="<p class="p1"><b>BootZ Bootloader and Handover Protocol</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="140" y="600" width="460" height="60" as="geometry"/> + </mxCell> + <mxCell id="9" value="<p class="p1"><b>Firmware (EFI, NeKernel.org's FW)</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="140" y="670" width="460" height="60" as="geometry"/> + </mxCell> + <mxCell id="13" value="<p class="p1"><b>System SDK Stable API</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="238.88" y="290" width="360" height="40" as="geometry"/> + </mxCell> + <mxCell id="15" value="<p class="p1"><b>Services (Ring 3, EL0)</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="430" y="240" width="170" height="35" as="geometry"/> + </mxCell> + <mxCell id="16" value="<p class="p1"><b>Hypr86</b></p><p class="p1"><b>Virtual Machine</b></p>" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="140" y="240" width="90" height="270" as="geometry"/> + </mxCell> + <mxCell id="19" value="<h1 style="margin-top: 0px;">NeKernel</h1><p>This shows how NeKernel is</p><p>designed, some parts here are</p><p>not present yet, such as Hypr86.</p><p>This diagram was made for the</p><p>developers to understand NeKernel better.</p>" style="text;html=1;whiteSpace=wrap;overflow=hidden;rounded=0;" vertex="1" parent="1"> + <mxGeometry x="630" y="240" width="180" height="190" as="geometry"/> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile>
\ No newline at end of file diff --git a/doc/drawio/TIMER_DESIGN.drawio b/doc/drawio/TIMER_DESIGN.drawio new file mode 100644 index 00000000..ca081fd3 --- /dev/null +++ b/doc/drawio/TIMER_DESIGN.drawio @@ -0,0 +1,49 @@ +<mxfile host="65bd71144e"> + <diagram name="Page-1" id="SMmOiZGLec9H7ruN5qyQ"> + <mxGraphModel dx="764" dy="289" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0"> + <root> + <mxCell id="0"/> + <mxCell id="1" parent="0"/> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="c-_7pHU60HQ0aR4bwu-4-1" target="c-_7pHU60HQ0aR4bwu-4-2" edge="1"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-5" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="c-_7pHU60HQ0aR4bwu-4-1" target="c-_7pHU60HQ0aR4bwu-4-4" edge="1"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-7" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="c-_7pHU60HQ0aR4bwu-4-1" target="c-_7pHU60HQ0aR4bwu-4-6" edge="1"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-1" value="TIME_INFO" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="340" y="230" width="120" height="60" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-2" value="APIC/PIC/IOAPIC" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="340" y="400" width="120" height="60" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-4" value="GT" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="530" y="400" width="120" height="60" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-6" value="CLINT" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="150" y="400" width="120" height="60" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-9" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="c-_7pHU60HQ0aR4bwu-4-8" target="c-_7pHU60HQ0aR4bwu-4-1" edge="1"> + <mxGeometry relative="1" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-8" value="Scheduler context switch (on non MT mode),<br>Also SoftwareTimer gets implemented." style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="130" y="75" width="120" height="90" as="geometry"/> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-11" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=1;entryY=0;entryDx=0;entryDy=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;" parent="1" source="c-_7pHU60HQ0aR4bwu-4-10" edge="1"> + <mxGeometry relative="1" as="geometry"> + <mxPoint x="530" y="120" as="sourcePoint"/> + <mxPoint x="430" y="230" as="targetPoint"/> + </mxGeometry> + </mxCell> + <mxCell id="c-_7pHU60HQ0aR4bwu-4-10" value="Hook 2 system calls for timing purposes.<br>(Wait, WaitUntil)" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="560" y="90" width="120" height="60" as="geometry"/> + </mxCell> + <mxCell id="2" value="It is either abstracted like this, or has a direct interface to it." style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1"> + <mxGeometry x="490" y="235" width="200" height="55" as="geometry"/> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile>
\ No newline at end of file diff --git a/doc/drawio/ZXD_DESIGN.drawio b/doc/drawio/ZXD_DESIGN.drawio new file mode 100644 index 00000000..19fadabd --- /dev/null +++ b/doc/drawio/ZXD_DESIGN.drawio @@ -0,0 +1,31 @@ +<mxfile host="65bd71144e"> + <diagram name="Page-1" id="PApGwmLcT2JRCILoETeI"> + <mxGraphModel dx="960" dy="709" 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="5xbXWvOdvmnQnRAweQaM-1" value="<h1 style="margin-top: 0px;">ZXD</h1><p>NeKernel eXtended Driver Format.</p><p>An Extended PE32+</p><p>With additional headers and such.</p>" style="text;html=1;whiteSpace=wrap;overflow=hidden;rounded=0;" parent="1" vertex="1"> + <mxGeometry x="40" y="40" width="210" height="130" as="geometry"/> + </mxCell> + <mxCell id="5xbXWvOdvmnQnRAweQaM-2" value="ZXD HEADER" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="40" y="180" width="310" height="60" as="geometry"/> + </mxCell> + <mxCell id="5xbXWvOdvmnQnRAweQaM-3" value="PE32+ ZONE" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="40" y="260" width="310" height="60" as="geometry"/> + </mxCell> + <mxCell id="5xbXWvOdvmnQnRAweQaM-4" value="ZXD STUB [1..N]" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1"> + <mxGeometry x="40" y="340" width="310" height="60" as="geometry"/> + </mxCell> + <mxCell id="FgewEam9b60nFajCTQDb-1" value="StubHeapSz, StubStackSz, StubPageFlags..." style="text;html=1;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1"> + <mxGeometry x="380" y="355" width="290" height="30" as="geometry"/> + </mxCell> + <mxCell id="FgewEam9b60nFajCTQDb-2" value="Executable image of type PE32+&nbsp;" style="text;html=1;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1"> + <mxGeometry x="380" y="274" width="290" height="30" as="geometry"/> + </mxCell> + <mxCell id="FgewEam9b60nFajCTQDb-5" value="ZXD header, contains issuer and assignee signature, checked at runtime." style="text;html=1;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1"> + <mxGeometry x="380" y="194" width="290" height="30" as="geometry"/> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile>
\ No newline at end of file diff --git a/doc/specs/SPECIFICATION_FWRK.md b/doc/specs/SPECIFICATION_FWRK.md new file mode 100644 index 00000000..8d95abc7 --- /dev/null +++ b/doc/specs/SPECIFICATION_FWRK.md @@ -0,0 +1,302 @@ +=================================== + +# 0: General Information + +=================================== + +- ABI and Format: PEF/PE32+. +- Target: NeKernel. + +=================================== + +# 1: The specification: + +=================================== + +The NeKernel framework system (`.fwrk`) provides a standardized structure for creating modular, reusable libraries and components. Frameworks are self-contained packages that include headers, source code, metadata, and configuration for compilation and deployment within the NeKernel ecosystem. + +================================== + +# 2: Framework Directory Structure: + +================================== + +Each framework follows the standardized directory layout below: + +``` +<FrameworkName>.fwrk/ +├── <FrameworkName>.json # Framework manifest and build configuration +├── headers/ # Public API headers +│ ├── *.h # Public header files (C++ headers) +│ └── ... +├── src/ # Implementation source files +│ ├── *.cc # C++ implementation files +│ ├── DylibMain.cc # Dynamic library entry point (optional) +│ └── ... +├── xml/ # Framework metadata and properties +│ └── app.xml # Framework property list +├── dist/ # Build output directory +│ └── lib<FrameworkName>.fwrk.dylib # Compiled dynamic library +└── .keep # Placeholder file +``` + +================================ + +# 3: Component Specifications + +================================ + +### 1. Framework Manifest (`<FrameworkName>.json`) + +The JSON manifest file defines the build configuration, compilation flags, and metadata for the framework. + +**Required Fields:** + +- **`compiler_path`** (string): Path to the C++ compiler executable + - Example: `"clang++"`, `"x86_64-w64-mingw32-g++"` + +- **`compiler_std`** (string): C++ standard version + - Example: `"c++20"`, `"c++17"` + +- **`headers_path`** (array): Array of header search paths (relative to framework) + - Include paths for finding dependencies and kernel interfaces + - Example: `["./", "../../../src/kernel", "../../../public/frameworks/", "../../../src/"]` + +- **`sources_path`** (array): Array of source file globs to compile + - Example: `["src/*.cc"]` + +- **`output_name`** (string): Path and filename for compiled library output + - Example: `"./dist/libCoreFoundation.fwrk.dylib"` + +**Optional Fields:** + +- **`compiler_flags`** (array): Custom compilation flags + - Example: `["-ffreestanding", "-shared", "-fno-rtti", "-fno-exceptions"]` + +- **`cpp_macros`** (array): C++ preprocessor macro definitions + - Example: `["kCFVersion=0x0100", "__NE_AMD64__", "__CF_64BIT__"]` + +**Example Manifest:** +```json +{ + "compiler_path": "x86_64-w64-mingw32-g++", + "compiler_std": "c++20", + "headers_path": ["../", "./", "../../../dev", "../../../src/kernel"], + "sources_path": ["src/*.cc"], + "output_name": "./dist/libCoreFoundation.fwrk.dylib", + "compiler_flags": [ + "-ffreestanding", + "-shared", + "-fno-rtti", + "-fno-exceptions", + "-Wl,--subsystem=17" + ], + "cpp_macros": [ + "kCFVersion=0x0100", + "kCFVersionHighest=0x0100", + "kCFVersionLowest=0x0100", + "__NE_AMD64__", + "__CF_64BIT__" + ] +} +``` + +### 2. Public Headers Directory (`headers/`) + +Contains all public-facing C++ header files that define the framework's API. + +**Conventions:** +- File extension: `.h` (not `.hpp`) +- Namespace: Typically matches framework name (e.g., `CF::` for CoreFoundation) +- Include guards: Use `#pragma once` for header protection +- Copyright headers: Include NeKernel copyright notice at the top + +**Typical Headers:** +- Main header providing overall framework interface +- Specialized headers for different components +- Type definitions and class declarations +- Exception/error definitions + +### 3. Source Implementation Directory (`src/`) + +Contains C++ implementation files for the framework. + +**Key Files:** + +- **`DylibMain.cc`** (Optional): + - Entry point for dynamic library initialization + - Contains `_DylibAttach(SInt32 argc, Char* argv[])` function + - Returns status code (0 for success, EXIT_FAILURE otherwise) + + **Example:** + ```cpp + #include <libSystem/SystemKit/System.h> + + SInt32 _DylibAttach(SInt32 argc, Char* argv[]) { + // Initialization code here + return EXIT_FAILURE; // Change based on initialization result + } + ``` + +- **Implementation Files** (`*.cc`): + - Correspond to public headers + - Contain class definitions and function implementations + - Include necessary system and framework headers + +### 4. Metadata Directory (`xml/`) + +Contains XML-based property list files for framework metadata. + +**`app.xml` Structure:** +- PropertyList format for framework configuration +- Typically includes: + - `LibraryName`: Framework name (string) + - `CacheLibs`: Whether to cache library (boolean) + - Other framework-specific properties + +**Example:** +```xml +<PropertyList/> +<PLEntry Type="CFString" Name="LibraryName" Len="255" Value="CoreFoundation" /> +<PLEntry Type="BOOL" Name="CacheLibs" Value="YES" /> +``` + +### 5. Build Output Directory (`dist/`) + +Auto-generated directory containing compiled framework binaries. + +- **Output file**: `lib<FrameworkName>.fwrk.dylib` +- Created during build process via `mk_fwrk.py` +- Not committed to version control + +## Built-in Frameworks + +The NeKernel project includes the following standard frameworks: + +### CoreFoundation.fwrk +**Purpose:** Core data structures and utilities foundation +**Provides:** +- Reference types (CFRef) +- String handling (CFString) +- Collections (Arrays, Dictionaries) +- Geometric types (CFPoint, CFRect, CFColor) +- Object system (CFObject, CFProperty) + +### DiskImage.fwrk +**Purpose:** Disk image management and handling + +### KernelTest.fwrk +**Purpose:** Testing framework for kernel components + +### LaunchHelpers.fwrk +**Purpose:** Helper functions for system launch and initialization + +## Framework Creation + +### Using mk_fwrk.py + +The `mk_fwrk.py` tool automates framework creation: + +```bash +python3 tools/mk_fwrk.py <framework_name> +``` + +This generates: +1. Complete directory structure +2. Template `<framework_name>.json` manifest +3. Skeleton `DylibMain.cc` entry point +4. Template `xml/app.xml` metadata + +**Generated Structure:** +``` +<framework_name>.fwrk/ +├── <framework_name>.json +├── headers/ +│ └── .keep +├── src/ +│ ├── .keep +│ └── DylibMain.cc +├── xml/ +│ └── app.xml +└── .keep +``` + +## Compilation and Linking + +### Build Process + +1. **Configuration Phase**: Read and parse `<framework_name>.json` +2. **Compilation Phase**: Compile source files with specified compiler and flags +3. **Linking Phase**: Link object files into dynamic library +4. **Output Phase**: Place compiled binary in `dist/` directory + +### Dependencies + +- Frameworks can depend on: + - System libraries (via SystemKit) + - Other frameworks (via headers_path) + - Kernel components (via kernel paths in headers_path) + +### Linking Order + +When building applications that use frameworks: +1. Frameworks are linked in dependency order +2. CoreFoundation is typically a base dependency +3. Framework paths and library names must match manifest output names + +## Naming Conventions + +- **Framework directories**: `<Name>.fwrk` (PascalCase + .fwrk suffix) +- **JSON manifest**: `<Name>.json` (matches framework directory name) +- **Output library**: `lib<Name>.fwrk.dylib` +- **Namespaces**: Two-letter abbreviations (e.g., `CF`, `DI`, `KT`, `LH`) +- **Macros**: `k<ComponentName>` prefix (e.g., `kCFVersion`) + +## Version Specification + +Frameworks should include version information via preprocessor macros: + +- **`k<Framework>Version`**: Current framework version (e.g., `0x0100` for v1.0) +- **`k<Framework>VersionHighest`**: Highest compatible version +- **`k<Framework>VersionLowest`**: Lowest compatible version + +**Version Format**: Hexadecimal (e.g., `0x0100` = 1.0, `0x0201` = 2.1) + +## Architecture Support + +Frameworks can be compiled for multiple architectures: + +- **x86_64** (amd64): 64-bit x86/AMD64 architecture +- **ARM64**: 64-bit ARM architecture +- **RISC-V 64**: RISC-V 64-bit architecture +- **PowerPC 64**: PowerPC 64-bit architecture + +Architecture is typically controlled via: +- Compiler selection in manifest +- C++ macros (`__NE_AMD64__`, `__NE_ARM64__`, etc.) + +## Best Practices + +1. **Header Organization**: Keep headers minimal; place implementation in `.cc` files +2. **Namespace Usage**: Encapsulate all public APIs in framework namespace +3. **Dependencies**: Minimize external dependencies; prefer kernel APIs +4. **Configuration**: Use `.json` manifest for all build-time configuration +5. **Documentation**: Include copyright headers and documentation comments in code +6. **Error Handling**: Define framework-specific error codes and status returns +7. **Testing**: Provide test cases using KernelTest.fwrk when applicable + +## Integration with Applications + +Applications that use frameworks: + +1. **Include Headers**: `#include <Framework/Header.h>` +2. **Link Framework**: Add framework library to linker flags +3. **Initialize**: Call framework initialization if provided +4. **Handle Errors**: Check return codes and handle framework exceptions + +## File Permissions + +- Framework files: Standard text (`.h`, `.cc`, `.json`, `.xml`) +- Build artifacts: Auto-generated and read-only during runtime +- Framework package: Should be distributable as single `.fwrk` directory + diff --git a/doc/specs/SPECIFICATION_MBCI.md b/doc/specs/SPECIFICATION_MBCI.md new file mode 100644 index 00000000..648529cf --- /dev/null +++ b/doc/specs/SPECIFICATION_MBCI.md @@ -0,0 +1,34 @@ +=================================== + +# 0: General Information: + +=================================== + +- High Speed Bus Format. +- Designed for keyboards, mouses, interfaces. +- A open and cheap alternative to other HCIs. + +=================================== + +# 1: Concepts: + +=================================== + +- MBCI Host +- MBCI Authentication key (24-bit number) +- MBCI Host Kind and Flags. + +=================================== + +# 2: Pinout: + +=================================== + +- VCC (IN) (OUT for MCU) +- CLK (IN) (OUT for MCU) +- ACK (BI) (Contains an Acknowledge Packet Frame) +- D0- (IN) (Starts with the Host Interface Packet Frame) +- D1- (IN) (Starts with the Host Interface Packet Frame) +- D0+ (OUT) (Starts with the Host Interface Packet Frame) +- D1+ (OUT) (Starts with the Host Interface Packet Frame) +- GND (IN) (OUT for MCU)
\ No newline at end of file diff --git a/doc/specs/SPECIFICATION_OS.md b/doc/specs/SPECIFICATION_OS.md new file mode 100644 index 00000000..08c2b326 --- /dev/null +++ b/doc/specs/SPECIFICATION_OS.md @@ -0,0 +1,82 @@ +=================================== + +# 0: General Information: + +=================================== + +- ABI and Format: PEF/PE32+. +- Kernel architecture: Portable hybrid Kernel. +- Used Languages: C++, and Assembly Assembly (AMD64, X64000, X86S, ARM64, POWER, RISCV) +- 32-bit is not supported as of 12/25/2025. + +=================================== + +# 1: The Kernel (NeKernel) + +=================================== + +- Drive/Device Abstraction. +- SMP, Preemptive Multi Threading. +- Separation of Files/Devices. +- Networking Support. +- Hardware Abstraction Layer. +- Native Filesystem support (NeFS, FAT32 and ffs2). +- Program Loaders interfaces. +- TLS (Thread Local Storage) support. +- BinaryMutex, Locks, Timers. +- Canary mechanisms. +- Dynamic Loader. +- Cross Platform. +- Permission Selectors. +- Modular and Security focused. + +=================================== + +# 2: The Filesystem (NeFS, or OpenHeFS) + +=================================== + +- Catalog object with associated forks. +- Large storage support. +- Long file names. +- UNIX path style. +- Can be formated under 8mb. + +================================== + +# 3: Common conventions: + +================================== + +- Kernel -> ke_init_x +- RunTime -> rt_copy_mem +- Hal -> hal_foo_bar +- Class methods -> Class::FooBar +- Internals function shall be formated as such: (hali, rtli, rti...) + +=================================== + +# 4: The Bootloader (BootZ) + +=================================== + +- Capable of booting from a network drive. +- Loads a PE file which is the Kernel, or any modules. +- Sanity checks, based on the number of sections. +- Handover compliant. +- Does check for a valid partition (useful in the case of recovering) +- Modular, and Security focused. + +=================================== + +# 5: The IFS + +================================== + +- Filesystem to mountpoint interface abstraction. +- VFS-like subsystem inspired by NT/OS2 IFS. +- Multi-drive support (A, B, C, D indices). +- Ext2 support via IFS layer. +- Packet-based I/O operations. +- Separation of read/write operations per drive. + diff --git a/doc/svg/OS_DESIGN.png b/doc/svg/OS_DESIGN.png Binary files differnew file mode 100644 index 00000000..05fbee16 --- /dev/null +++ b/doc/svg/OS_DESIGN.png diff --git a/doc/tex/NOTICE.md b/doc/tex/NOTICE.md new file mode 100644 index 00000000..23417d2a --- /dev/null +++ b/doc/tex/NOTICE.md @@ -0,0 +1,10 @@ +# Notice: NeKernel specifications. + +## Notice: CoreProcessScheduler paper. + +The CPS has been moved to WG02,for more information, clone the following repository: [https://github.com/nekernel-org/draft](https://github.com/nekernel-org/draft). + +## Recommended: + +- `pdflatex` is recommended for this matter. +- You can use `overleaf` to edit the LaTeX files too. diff --git a/doc/tex/binary_mutex.tex b/doc/tex/binary_mutex.tex new file mode 100644 index 00000000..548f440f --- /dev/null +++ b/doc/tex/binary_mutex.tex @@ -0,0 +1,77 @@ +\documentclass{article} +\usepackage{graphicx} +\usepackage{hyperref} + +\title{BinaryMutex: Technical Documentation} +\author{Amlal El Mahrouss} +\date{\today} + +\begin{document} + +\maketitle + +\section{Abstract} + +{The BinaryMutex is a core component of NeKernel (NeKernel/Legacy VMKernel) based systems. The pattern excludes other acquirers to own the USER\_PROCESS that is currently being hold. Thus the acquiree is the USER\_PROCESS itself} + +\section{Overview} + +{The BinaryMutex comes from the need to make sure that no race conditions occurs in kernel code. Most of those race conditions happens in process handling code. Thus the design of the BinaryMutex (which holds a process handle to it)} + +\begin{verbatim} +BinaryMutex mux; +mux.Lock(process); + +// Say we want to interact with the process itself on this thread, +we can then make sure that no race condition happens by using: +constexpr auto kSecondsMax = 5; +while (mux.WaitForProcess(kSecondsMax)); + +// finally do our task now. + +process.DoFoo(); +\end{verbatim} + +\section{Implementation} + +The source implementation consists of this simple C++ class: + +\begin{verbatim} +class BinaryMutex final { + public: + explicit BinaryMutex() = default; + ~BinaryMutex() = default; + + public: + bool IsLocked() const; + bool Unlock(); + + public: + BOOL WaitForProcess(const UInt32& sec); + + public: + bool Lock(UserProcess* process); + bool LockAndWait(UserProcess* process, ITimer* timer); + + public: + NE_COPY_DEFAULT(BinaryMutex) + + private: + UserProcess* fLockingProcess; +}; +\end{verbatim} + +\section{Conclusion} + +{This design pattern is useful for systems that need to make sure that a process isn't tampered by concurrent usages. +Thus its existence in Legacy VMKernel and NeKernel.} + +\section{References} + +{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel} + +{Legacy VMKernel}: \href{https://snu.systems/specs/vmkernel}{Legacy VMKernel} + +{BinaryMutex}: \href{https://github.com/nekernel-org/nekernel/blob/src/src/kernel/KernelKit/BinaryMutex.h}{BinaryMutex} + +\end{document} diff --git a/doc/tex/mini_bus_controller_interface.tex b/doc/tex/mini_bus_controller_interface.tex new file mode 100644 index 00000000..ba2381b7 --- /dev/null +++ b/doc/tex/mini_bus_controller_interface.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{\today} + +\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} diff --git a/doc/tex/nefs.tex b/doc/tex/nefs.tex new file mode 100644 index 00000000..37e43d13 --- /dev/null +++ b/doc/tex/nefs.tex @@ -0,0 +1,125 @@ +\documentclass{article} +\usepackage[a4paper,margin=1in]{geometry} +\usepackage{listings} +\usepackage{xcolor} +\usepackage{amsmath} +\usepackage{hyperref} +\usepackage{longtable} +\usepackage{titlesec} +\usepackage{fancyhdr} +\usepackage{caption} +\usepackage{graphicx} + +\definecolor{codegray}{gray}{0.95} +\lstset{ + backgroundcolor=\color{codegray}, + basicstyle=\ttfamily\small, + breaklines=true, + frame=single, + tabsize=4, + language=C++, + showstringspaces=false +} + +\title{NeFS: New Extended File System Specification} +\author{Amlal El Mahrouss} +\date{2025} + +\begin{document} + +\maketitle + +\section{Overview} +NeFS (New Extended File System) is am embedded file system designed to operate over low-level block storage (AHCI/ATA) with a modular architecture. It supports catalogs (like files or directories), forks (similar to macOS data/resource forks), and a formatting mechanism using EPM (Extended Partition Map). + +\section{Key Components} + +\subsection*{Mountpoint and Drive Access} +\begin{itemize} + \item `kMountpoint`: Global mountpoint interface to access drives. + \item `DriveTrait`: Interface used to abstract block-level access. +\end{itemize} + +\subsection*{Core Structures} +\begin{longtable}{|l|p{11cm}|} +\hline +\textbf{Structure} & \textbf{Purpose} \\ +\hline +NEFS\_FORK\_STRUCT & Represents a data fork (stream of bytes attached to a catalog). \\ +\hline +NEFS\_CATALOG\_STRUCT & Represents metadata of a file or directory, including fork pointers. \\ +\hline +NEFS\_ROOT\_PARTITION\_BLOCK & Metadata describing a NeFS partition. \\ +\hline +EPM\_PART\_BLOCK & EPM descriptor for bootable partition support. \\ +\hline +\end{longtable} + +\subsection*{Key Functions} + +\begin{itemize} + \item \texttt{CreateCatalog()} — Creates a file or directory catalog. + \item \texttt{CreateFork()} — Adds a fork to a catalog, with LBA linking. + \item \texttt{FindCatalog()} — Finds a catalog by traversing sibling links. + \item \texttt{FindFork()} — Locates a fork by name under a catalog. + \item \texttt{WriteCatalog()} — Writes a fork's data to the correct offset. + \item \texttt{Format()} — Initializes a NeFS + EPM partition on a drive. + \item \texttt{ReadCatalog()} — Reads back a fork's data. + \item \texttt{RemoveCatalog()} — Marks a catalog as deleted and updates partition metadata. +\end{itemize} + +\section{Design Overview} + +\subsection*{Fork Management} +Forks are chained using `NextSibling` pointers and are scanned linearly to find unallocated entries. Forks contain: +\begin{itemize} + \item Fork name + \item Catalog name + \item Flags (e.g., created/deleted) + \item Data size and offset + \item Sibling pointers (Next, Previous) +\end{itemize} + +\subsection*{Catalog Management} +Catalogs act like files or directories. Each has: +\begin{itemize} + \item Name and type (file/dir) + \item Data and resource forks + \item Status flags + \item Chaining via sibling pointers +\end{itemize} +Catalog creation attempts to find a parent first, then finds a free block to allocate the new catalog structure. + +\subsection*{Partition Formatting} +The `Format()` function sets up the NeFS partition and optionally writes an EPM descriptor if bootable. It: +\begin{enumerate} + \item Verifies the drive + \item Initializes partition metadata (sector size, catalog start, etc.) + \item Writes the root directory +\end{enumerate} + +\section{Error Handling} +Errors are written to a global error register using `err\_global\_get()`. Common codes include: +\begin{itemize} + \item \texttt{kErrorDiskIsCorrupted} + \item \texttt{kErrorFileExists} + \item \texttt{kErrorFileNotFound} + \item \texttt{kErrorUnimplemented} +\end{itemize} + +\section{Limitations and Notes} +\begin{itemize} + \item No read/write locking or access concurrency. + \item Assumes in-memory buffers for fork writing. + \item Seek/Tell operations are not implemented — only bulk read/write. + \item Supports one mountpoint at a time. +\end{itemize} + +\section{Future Work} +\begin{itemize} + \item Implement streaming I/O with Seek/Tell. + \item Support multiple mountpoints or drives. + \item Improve metadata journaling and recovery features. +\end{itemize} + +\end{document} diff --git a/doc/tex/nekernel_smp_subsystem.tex b/doc/tex/nekernel_smp_subsystem.tex new file mode 100644 index 00000000..cb30f3cb --- /dev/null +++ b/doc/tex/nekernel_smp_subsystem.tex @@ -0,0 +1,32 @@ +\documentclass{article} +\usepackage{graphicx} + +\title{NeKernel: The SMP Subsystem} +\author{Amlal El Mahrouss} +\date{\today} + +\begin{document} + + \maketitle + + \section{Abstract} + + {NeKernel is a hybrid based operating system kernel written in modern C++ (C++17/C++20). It features a bootloader, kernel, tools, libraries, and frameworks. This document is about the SMP subsystem of the kernel.} + + \section{Design Overview} + + {NeKernel is designed with SMP by default. Although it may fallback under classic preemptive round-robin scheduling when unavailable - NeKernel runs best on a SMP based machine. The subsystem goes from the HardwareThreadScheduler to the Hardware Abstraction Layer's Application Processor API.} + + \section{The SMP Subsystem} + + {The SMP subsystem consist of the HTS (HardwareThreadScheduler) and AP (Application Processor) APIs. Those systems are made to handle SMP tasks inside NeKernel.} + + \subsection{Higher Level: HardwareThreadScheduler (HTS)} + + {HTS's main purpose is to make cores all busy with a StackFrame object. That object contains program registers such as the stack pointer and instruction pointer. Each task is fairly assigned to then be run by the AP's mp\_register\_task function.} + + \subsection{Lower Level: Application Processor (AP) API} + + {Application Processors (now referred as AP) is the API taking care of multi-core scheduling, very platform dependent (thus its presence on the HAL) it is designed to run tasks passed from the HTS.} + +\end{document} diff --git a/doc/tex/openhefs.tex b/doc/tex/openhefs.tex new file mode 100644 index 00000000..136d651c --- /dev/null +++ b/doc/tex/openhefs.tex @@ -0,0 +1,174 @@ +\documentclass{article} +\usepackage[utf8]{inputenc} +\usepackage{geometry} +\usepackage{longtable} +\usepackage{listings} +\geometry{margin=1in} +\title{OpenHeFS: Hight-throughput extended File System} +\author{Amlal El Mahrouss} +\date{\today} + +\begin{document} + +\maketitle + +\section{Overview} +The High-throughput Extended File System (OpenHeFS) 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{kOpenHeFSVersion} & 0x0103 \\ +\texttt{kOpenHeFSMagic} & "OpenHeFS" (9-byte magic identifier) \\ +\texttt{kOpenHeFSMagicLen} & 9 \\ +\texttt{kOpenHeFSBlockLen} & 512 bytes \\ +\texttt{kOpenHeFSFileNameLen} & 256 characters \\ +\texttt{kOpenHeFSPartNameLen} & 128 characters \\ +\texttt{kOpenHeFSMinimumDiskSize} & 128 GiB \\ +\texttt{kOpenHeFSDefaultVolumeName} & "OpenHeFS Volume" \\ +\texttt{kOpenHeFSINDStartOffset} & Offset after boot node \\ +\texttt{kOpenHeFSSearchAllStr} & "*" (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 of the filesystem, provides necessary information about the disk and the filesystem itself. + +\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[kOpenHeFSSliceCount]} 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{kOpenHeFSTimeInvalid = 0x0} + \item \texttt{kOpenHeFSTimeMax = 0xFFFFFFFFFFFFFFFF - 1} +\end{itemize} + +\section{Filesystem API}\label{sec:filesystem-api} + +Provided by \texttt{Kernel::OpenHeFS::HeFileSystemParser}. + +\begin{itemize} + \item \texttt{Format(drive, flags, name)} - Format drive with OpenHeFS + \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} +OpenHeFS 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} |
