summaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/STANDARD_FWRK.md283
-rw-r--r--docs/drawio/GUI_DESIGN.drawio6
-rw-r--r--docs/drawio/LAUNCH_DESIGN.drawio22
-rw-r--r--docs/tex/binary_mutex.tex6
-rw-r--r--docs/tex/core_process_scheduler.tex2
5 files changed, 312 insertions, 7 deletions
diff --git a/docs/STANDARD_FWRK.md b/docs/STANDARD_FWRK.md
new file mode 100644
index 00000000..1411fe5e
--- /dev/null
+++ b/docs/STANDARD_FWRK.md
@@ -0,0 +1,283 @@
+# STANDARD NEKERNEL FRAMEWORK SPECIFICATION
+
+## Overview
+
+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.
+
+## 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
+```
+
+## 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: `["./", "../../../dev/kernel", "../../../public/frameworks/", "../../../dev/"]`
+
+- **`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", "../../../dev/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/docs/drawio/GUI_DESIGN.drawio b/docs/drawio/GUI_DESIGN.drawio
index 31fc11cf..bdf977af 100644
--- a/docs/drawio/GUI_DESIGN.drawio
+++ b/docs/drawio/GUI_DESIGN.drawio
@@ -1,16 +1,16 @@
<mxfile host="65bd71144e">
<diagram name="Page-1" id="yf45V2V4Ppj0j8o4dQoi">
- <mxGraphModel dx="1144" dy="442" 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">
+ <mxGraphModel dx="1149" dy="361" 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="mspNsT0Gx7HsNPX6GqQO-2" value="libsci" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxCell id="mspNsT0Gx7HsNPX6GqQO-2" value="libSystem" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="50" y="500" width="450" height="140" as="geometry"/>
</mxCell>
<mxCell id="2" style="edgeStyle=none;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" parent="1" source="mspNsT0Gx7HsNPX6GqQO-3" target="mspNsT0Gx7HsNPX6GqQO-13" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
- <mxCell id="mspNsT0Gx7HsNPX6GqQO-3" value="LibGUI" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxCell id="mspNsT0Gx7HsNPX6GqQO-3" value="libGUI" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="250" y="210" width="270" height="160" as="geometry"/>
</mxCell>
<mxCell id="mspNsT0Gx7HsNPX6GqQO-11" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.093;entryY=1.019;entryDx=0;entryDy=0;entryPerimeter=0;" parent="1" source="mspNsT0Gx7HsNPX6GqQO-2" target="mspNsT0Gx7HsNPX6GqQO-3" edge="1">
diff --git a/docs/drawio/LAUNCH_DESIGN.drawio b/docs/drawio/LAUNCH_DESIGN.drawio
index e69de29b..32fe8eda 100644
--- a/docs/drawio/LAUNCH_DESIGN.drawio
+++ b/docs/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/docs/tex/binary_mutex.tex b/docs/tex/binary_mutex.tex
index 1b5a59c2..0f6a6663 100644
--- a/docs/tex/binary_mutex.tex
+++ b/docs/tex/binary_mutex.tex
@@ -12,7 +12,7 @@
\section{Abstract}
-{The BinaryMutex is a core component of NeKernel (NeKernel/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}
+{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}
@@ -64,13 +64,13 @@ class BinaryMutex final {
\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 VMKernel and NeKernel.}
+Thus its existence in Legacy VMKernel and NeKernel.}
\section{References}
{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel}
-{VMKernel}: \href{https://snu.systems/specs/vmkernel}{VMKernel}
+{Legacy VMKernel}: \href{https://snu.systems/specs/vmkernel}{Legacy VMKernel}
{BinaryMutex}: \href{https://github.com/nekernel-org/nekernel/blob/dev/dev/kernel/KernelKit/BinaryMutex.h}{BinaryMutex}
diff --git a/docs/tex/core_process_scheduler.tex b/docs/tex/core_process_scheduler.tex
index ab5636f6..41bad465 100644
--- a/docs/tex/core_process_scheduler.tex
+++ b/docs/tex/core_process_scheduler.tex
@@ -123,7 +123,7 @@ struct ProcessImage final {
{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel}
-{VMKernel}: \href{https://snu.systems/specs/vmkernel}{VMKernel}
+{Legacy VMKernel}: \href{https://snu.systems/specs/vmkernel}{Legacy VMKernel}
{CoreProcessScheduler C++ Header}: \href{https://github.com/nekernel-org/nekernel/blob/dev/dev/kernel/KernelKit/CoreProcessScheduler.h}{CoreProcessScheduler}
generated by cgit v1.2.3 (git 2.39.1) at 2026-03-13 17:57:04 +0000