updated readme, fix configuration shell invoked twice.

diff --git a/README.md b/README.md
index c4a4ea9579fd3f61f0c310e746abc6bfffa76814..fe73edc437d3c2498af76fa60ec5cb438e0640f3 100644 (file)
--- a/README.md
+++ b/README.md
@@ -10,7 +10,10 @@
 
 The Lunaix kernel (or soon-to-be LunaixOS) is a hobby kernel, written entirely from scratch. Designed to be POSIX-compliance, performance critical and modern, with some independent thoughts being applied in architectural design.
 
 
 The Lunaix kernel (or soon-to-be LunaixOS) is a hobby kernel, written entirely from scratch. Designed to be POSIX-compliance, performance critical and modern, with some independent thoughts being applied in architectural design.
 

-This project is based solely on first principles. Meaning that it does neither copy-pasting nor recycling other os projects/tutorials. However, this doesn't necessarily imply superiority; In fact, Lunaix starts out as a mean to challenge my understanding in OS theory and also a platform for experimenting some advanced (and cool) kernel features. If you are a kernel hobbyist who want some new perspectives or just simply get fatigued on those recycled content, then you have came to the right place!
+
+This project is built entirely from first principles - meaning no code was copy-pasted or recycled from other OS projects or tutorials. Lunaix didn't begin as an attempt to outperform anything; it started as a personal challenge to learn OS theory and explore advanced kernel features through original design and implementation. Everything you see here was developed solo, part-time, with only hardware specs and my beloved **Modern Operating Systems** as guidance.
+
+If you're a kernel hobbyist looking for a fresh take or tired of mass-produced projects, then welcome, you're in the right place!

 
 
 | ![showcase_lunaix-over-serial.png](docs/img/showcase_lunaix-over-serial.png) |
 
 
 | ![showcase_lunaix-over-serial.png](docs/img/showcase_lunaix-over-serial.png) |


@@ -25,81 +28,90 @@ This project is based solely on first principles. Meaning that it does neither c
 
 ## Features
 
 
 ## Features
 

-In a nutshell, Lunaix is a multi-architectural general purpose kernel, and she is:
+Lunaix is a multi-architecture, general-purpose kernel built with performance, modularity, and robustness in mind. Its design emphasizes advanced abstractions, proactive error detection, and subsystem isolation. Lunaix is
+
++ **Fully-preemptive** for responsive multi-tasking
++ **Modular** with compile-time configurable components and extensible subsystems
++ **High-performance**, leveraging modern caching strategies and efficient infrastructures.
++ **Fault-tolerant**, with built-in error handling and stack backtracing
++ **Robust by design**, using mechanisms like proactive deadlock detection and driver isolation

 
 

-+ fully-preemptive
-+ modular design with configurable components at compile-time and extendable subsystems
-+ high-performance by utilising advanced caching techniques and infrastructure.
-+ fault-tolerance with sophisticated builtin error handling and tracing techniques.
-+ robust in nature with techniques such as proactive deadlock detection and driver isolation mechanism.
+A significant amount of effort has gone into crafting clean abstractions, implementing advanced kernel features, and applying performance optimizations throughout the system.

 
 

-The author has put a significant amount of time on devising better abstractions, advance kernel features and various optimisation techniques. To give a better understanding (and appreciation) of the works being done, the following non-exhaust list has been compiled with features that are currently supported in lunaix:
+To better illustrate the scope of work already done, the following non-exhaustive list outlines currently supported features in Lunaix:
+
+<details>
+
+<summary>List of all features implemented</summary>

 
 + Multi-ISA
   + x86_32
   + x86_64
 
 + Multi-ISA
   + x86_32
   + x86_64

-  + Aarch64 (W.I.P)
+  + Aarch64 (WIP)

 + Boot protocol
   + abstraction for different protocol
   + configurable kernel boot-time parameters
 + Platform resource management and definition
 + Boot protocol
   + abstraction for different protocol
   + configurable kernel boot-time parameters
 + Platform resource management and definition

-  + ACPI
-  + Devicetree
+  + read-only ACPI table interpretation
+  + full devicetree implementation

 + Memory management
   + architecture-neutral abstraction
 + Memory management
   + architecture-neutral abstraction

+  + highmem
+  + copy-on-write
+  + page sharing
+  + explicit huge page

   + on-demand paging
   + on-demand paging

-  + copy-on-write and page sharing
-  + compound page support
-  + explicit huge page support (sorry, not THP!)
-  + reverse mapping indexing (rmap)
-  + memory compaction (W.I.P)
-  + slab-alike object allocator
-  + highmem support
-  + remote address space accessing
+  + compound page
+  + reverse mapping (rmap)
+  + memory compaction (WIP)
+  + slab-style object allocator
+  + inter-process address space access

 + Multi-tasking
 + Multi-tasking

-  + Protection level and process image isolation
-  + Native threading support (no more lightweight process nonsense)
-  + Signal mechanism
-  + Kernel level multi-tasking (i.e. kernel threads)
-  + Round-robin scheduling (for now)
-  + Preemptive kernel design
+  + fully preemptive
+  + protection levels
+  + process isolation
+  + native threading
+  + signal mechanism
+  + round-robin scheduler (for now)
+  + kernel level multi-tasking (i.e. kernel threads)

   + taskfs: file system interface to process and threads
 + File system
   + taskfs: file system interface to process and threads
 + File system

+  + POSIX-compliant interface

   + virtual file system framework
   + virtual file system framework

-  + ...with POSIX compliant interfaces

   + file system mounting mechanism
   + page cache for file IO
   + file system mounting mechanism
   + page cache for file IO

-  + node cache for vfs structure representation.
+  + inode/dnode caching

   + ext2 (rev.0, rev.1)
   + iso9660 (rock-ridge)
   + ext2 (rev.0, rev.1)
   + iso9660 (rock-ridge)

-  + twifs: file system interface to kernel states.
+  + twifs: kernel state fs interface.

 + Device management and interrupt handling
 + Device management and interrupt handling

-  + architecture-neutral design
-  + generalised driver framework
-  + generalised irq framework
-  + driver modularisation design
-  + support asynchronous device model
-  + devfs: file system interface to device subsystem
+  + unified IRQ framework
+  + unified driver framework for heterogenous devices
+  + modular driver model allow compiled-time toggling
+  + asynchronous operation model supported
+  + devfs: device fs interface.

 + Block I/O (blkio)
 + Block I/O (blkio)

-  + generalised block IO interface and encapsulation
-  + blkio packets caching
-  + asynchronous blkio operation in nature
+  + unified block IO interface
+  + IO request packets caching
+  + asynchronous IO operation

 + Serial I/O
 + Serial I/O

-  + POSIX-compliant serial port model
-  + serial device driver framework (part of driver framework)
+  + POSIX-compliant serial IO model

 + Caching Infrastructure
 + Caching Infrastructure

-  + primitive: generic sparse associative array (spatial data)

   + LRU replacement policy and pooling
   + LRU replacement policy and pooling

-  + kernel daemon for scheduled cache eviction
+  + kernel daemon for dynamic and transparent cache managements

 + Error handling and detection
 + Error handling and detection

-  + stack back-tracing with symbol resolution
-  + nested exception unfolding
+  + stack backtracing with symbol resolution
+  + stack unwinding for nested exception

   + CPU state dumping
   + CPU state dumping

-  + Deadlock/hung-up detection
+  + deadlock/hung-up detection
+
+</details>

 
 

-For the device drivers that are currently support see below:
+<details>

 
 

-+ Arhcitecture Neutral
+<summary>List of currently supported device</summary>
+
++ Architecture Neutral

   + UART 16650-compatible driver
   + Serial ATA AHCI
   + PCI 3.0
   + UART 16650-compatible driver
   + Serial ATA AHCI
   + PCI 3.0


@@ -107,12 +119,13 @@ For the device drivers that are currently support see below:
   + Standard VGA
 + Intel x86
   + RTC (Intel PCH)
   + Standard VGA
 + Intel x86
   + RTC (Intel PCH)

-  + IOAPIC irq controller
+  + IOAPIC IRQ controller

   + APIC Timer
   + Legacy i8042 keyboard controller
 + ARM
   + GICv3
   + APIC Timer
   + Legacy i8042 keyboard controller
 + ARM
   + GICv3

-  + PL011 (W.I.P)
+  + PL011 (WIP)
+</details>

 
 ## Project Structure
 
 
 ## Project Structure
 


@@ -152,7 +165,83 @@ A successful build will give `build/bin/kernel.bin`.
 
 If you are impatient, or just want something to run and don't want to went through tedious process of configuring rootfs and tweak kernel parameters. You can use the `live_debug.sh` provided in the lunaix root directory to quickly bring up the system with default parameters (also used by the author for debugging).
 
 
 If you are impatient, or just want something to run and don't want to went through tedious process of configuring rootfs and tweak kernel parameters. You can use the `live_debug.sh` provided in the lunaix root directory to quickly bring up the system with default parameters (also used by the author for debugging).
 

-Following the steps:
+### Quick Start
+
+This will get you up and running real quick. We will use `x86_64` as example.
+
+Assuming a Linux or other Unix-like shell environment.
+
+#### Select your target
+```sh
+$ export ARCH=x86_64
+```
+
+#### Check Python
+```sh
+$ python --version
+```
+
+Ensure at least `3.11`
+
+#### Check compiler
+```sh
+$ gcc -dumpmachine
+```
+
+Ensure `x86_64-linux-gnu` or anything resemble `x86_64`
+
+#### Check QEMU
+```sh
+$ which qemu-system-x86_64
+```
+
+Should display a valid installation path
+
+#### Optional: Setting up Cross-Compiler
+```sh
+$ export CX_PREFIX=x86_64-linux-gnu-
+```
+
+#### Run Configuration
+```sh
+make config
+```
+
+Then hitting `q` in the interactive shell to save and quit
+
+#### Build stock rootfs
+
+```sh
+make rootfs
+```
+
+#### Build & Run
+```sh
+./live_debug.sh
+```
+
+you should see gdb now take control of your shell
+
+#### Connect to serial via telnet
+
+Open up another window or session
+```sh
+telnet localhost 12345
+```
+
+#### Commence simulation
+
+Back to the gdb session and type `c` to countine
+
+
+#### Watch Lunaix booting!
+
+Congrats, enjoy your lunaix! (or submit an issue)
+
+
+### Not so Quick Start
+
+Here is a slower and yet more verbose steps:

 
 1. Select an architecture `<arch>`
 2. Check the compilation prerequisites and presence of `qemu-system-<arch>`
 
 1. Select an architecture `<arch>`
 2. Check the compilation prerequisites and presence of `qemu-system-<arch>`

diff --git a/lunaix-os/makeinc/lunabuild.mkinc b/lunaix-os/makeinc/lunabuild.mkinc
index 2e08b388254948fa93e2519d41cc2fd483086140..0ecd3f0a4a0860d3bc25a630d30d2df79681fb15 100644 (file)
--- a/lunaix-os/makeinc/lunabuild.mkinc
+++ b/lunaix-os/makeinc/lunabuild.mkinc
@@ -15,7 +15,6 @@ define __gen_config
 endef
 
 define __gen_build
 endef
 
 define __gen_build

-       @echo restarting configuration...

        @$(LBUILD) --gen-build $(lbuild_dir)
 endef
 
        @$(LBUILD) --gen-build $(lbuild_dir)
 endef
 


@@ -29,16 +28,21 @@ $(lconfig_save): $(all_lconfigs)
        $(call __gen_config)
 
 export
        $(call __gen_config)
 
 export

-$(lconfig_mkinc): $(all_lconfigs)
+$(lconfig_mkinc): $(lconfig_save)

        $(call __gen_config)
 
 export
        $(call __gen_config)
 
 export

-$(lbuild_config_h): $(all_lbuilds)
+$(lbuild_config_h): $(lconfig_save) $(all_lbuilds)

        $(call __gen_build)
 
 export
        $(call __gen_build)
 
 export

-$(lbuild_mkinc): $(all_lbuilds)
+$(lbuild_mkinc): $(lconfig_save) $(all_lbuilds)

        $(call __gen_build)
 
 config: $(all_lbuilds) $(all_lconfigs)
        $(call __gen_both)
        $(call __gen_build)
 
 config: $(all_lbuilds) $(all_lconfigs)
        $(call __gen_both)

+
+reconfig:
+       @rm -rf $(lbuild_dir)
+       @rm -rf $(lconfig_save)
+       $(call __gen_both)
\ No newline at end of file

diff --git a/lunaix-os/scripts/build-tools/luna_build.py b/lunaix-os/scripts/build-tools/luna_build.py
index 0f96e3e4dfd5901e99bf01e5a0d66b353140aff2..bf610516b1e73120fba59e681f039bc6f7b159ba 100755 (executable)
--- a/lunaix-os/scripts/build-tools/luna_build.py
+++ b/lunaix-os/scripts/build-tools/luna_build.py
@@ -82,9 +82,6 @@ class LunaBuild:
             print("no config file loaded, skipped interactive config")
             return
         
             print("no config file loaded, skipped interactive config")
             return
         

-        if not self.__opt.gen_config:
-            return
-        

         if not shconfig(self.__lconfig):
             print("configuration process aborted")
             exit(1)
         if not shconfig(self.__lconfig):
             print("configuration process aborted")
             exit(1)


@@ -108,10 +105,12 @@ def main():
         print(e)
         exit(1)
     
         print(e)
         exit(1)
     

-    builder.visual_config()
+    if opts.gen_config:
+        builder.visual_config()
+        builder.save()

     
     

-    builder.save()
-    builder.generate()
+    if opts.gen_build:
+        builder.generate()

 
 
 if __name__ == "__main__":
 
 
 if __name__ == "__main__":