Skip to content

Commit 4eee203

Browse files
CPScriptCPScript
authored
Update README.md
1 parent d4611d4 commit 4eee203

File tree

1 file changed

+167
-5
lines changed

1 file changed

+167
-5
lines changed

‎README.md‎

Lines changed: 167 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,167 @@
1-
<img width="488" height="366" alt="491976349-fb7e5b1e-c90e-494c-afa4-c238eef3e86d" src="https://github.com/user-attachments/assets/73b65df8-2564-4e3e-a26a-1f377a2293e4" />
2-
<img width="487" height="401" alt="491976361-8c378fbe-461f-4580-b94d-247fefe88f2b" src="https://github.com/user-attachments/assets/640b4d5d-8913-4dd4-b1ba-a7b7ea5f283b" />
3-
<img width="630" height="402" alt="491976426-57325cc4-dd78-47cf-8827-804cf53cb185" src="https://github.com/user-attachments/assets/03bc584a-1734-40be-b99d-690d16a2c35f" />
4-
<img width="308" height="163" alt="491976413-0b86062a-a32c-4c5f-a6fc-20f09e9b77b4" src="https://github.com/user-attachments/assets/61e00811-6436-4969-9935-cdb40b677370" />
5-
<img width="474" height="359" alt="491976385-63fb8d22-9909-4921-8cd1-293cf9314de8" src="https://github.com/user-attachments/assets/dc470698-29e2-429c-bd99-0b18790c3e25" />
1+
# Apollo Kernel - x86_64 Operating System
2+
3+
A x86_64 operating system kernel with a cool architecture, improved input handling, and modular design. This implementation maintains visual compatibility with previous versions while featuring an entirely new codebase built from the ground up. **From Scratch** (This wouldn't exist if someone didn't treatin a DMCA takedown)
4+
5+
<img width="488" height="366" alt="491976349-fb7e5b1e-c90e-494c-afa4-c238eef3e86d" src="https://github.com/user-attachments/assets/f334aa19-5c7e-4ce7-b293-c8573310ba28" />
6+
7+
8+
## Architecture Overview
9+
10+
### Core Design Principles
11+
- **Modular Component Architecture**: Cleanly separated subsystems with well-defined interfaces
12+
- **Enhanced Memory Management**: Heap allocator with block coalescing and alignment
13+
- **Robust Input Handling**: PS/2 keyboard driver with proper interrupt management
14+
- **Layered System Design**: Clear separation between hardware abstraction and kernel logic
15+
16+
### System Components
17+
- **Terminal Subsystem**: Hardware-abstracted VGA text mode with advanced color management
18+
- **Input Manager**: Buffered keyboard input with state tracking and scan code conversion
19+
- **Command Processor**: Interactive shell with history management and command parsing
20+
- **Memory Allocator**: Dynamic heap management with fragmentation prevention
21+
- **Time Keeper**: Real-time clock interface with date/time functionality
22+
23+
## Features
24+
25+
### Updated Functionality
26+
- **Improved Keyboard Input**: Fixed input handling with proper buffering and state management
27+
- **Advanced Shell System**: Command history, tab completion, and enhanced user interaction
28+
- **Better Memory Management**: Efficient allocation strategies with automatic defragmentation
29+
- **Robust Error Handling**: Input validation and graceful error recovery
30+
- **Hardware Abstraction**: Clean separation between hardware-specific and generic code
31+
32+
### Technical Improvements
33+
- **64-bit Native Design**: Full x86_64 long mode implementation
34+
- **Multiboot2 Compliance**: Enhanced bootloader compatibility
35+
- **Modular Build System**: Organized source tree with logical component separation
36+
- **Enhanced Documentation**: Inline documentation and API specifications
37+
38+
## Building the Kernel
39+
40+
### Prerequisites
41+
```bash
42+
# Ubuntu/Debian
43+
sudo apt update
44+
sudo apt install build-essential nasm qemu-system-x86 grub-pc-bin grub-common xorriso
45+
46+
# Cross-compiler setup
47+
wget https://github.com/lordmilko/i686-elf-tools/releases/download/7.1.0/x86_64-elf-tools-linux.zip
48+
unzip x86_64-elf-tools-linux.zip
49+
export PATH=$PATH:$(pwd)/bin
50+
```
51+
52+
### Compilation
53+
```bash
54+
# Build complete kernel
55+
make all
56+
57+
# Run in QEMU emulator
58+
make run
59+
60+
# Debug with GDB
61+
make debug
62+
63+
# Clean build artifacts
64+
make clean
65+
66+
# Show build information
67+
make info
68+
69+
# Validate
70+
make verify
71+
```
72+
73+
## System Architecture
74+
75+
### Boot Sequence
76+
1. **Multiboot2 Header**: GRUB bootloader integration
77+
2. **32-bit Bootstrap**: Initial CPU setup and verification
78+
3. **Long Mode Transition**: Switch to 64-bit execution
79+
4. **Subsystem Initialization**: Component startup sequence
80+
5. **Shell Activation**: Interactive user environment
81+
82+
### Memory Layout
83+
- **Kernel Space**: 1MB+ physical address mapping
84+
- **Heap Region**: 16MB dynamic allocation area
85+
- **Stack Space**: 64KB kernel execution stack
86+
- **Page Tables**: Identity-mapped 1GB address space
87+
88+
### Input/Output Architecture
89+
- **VGA Text Mode**: 80x25 character display with full color support
90+
- **PS/2 Keyboard**: Enhanced driver with proper interrupt handling
91+
- **Serial Interface**: Debug output capability for development
92+
93+
## Commands Reference
94+
95+
| Command | Description | Example Usage |
96+
|-----------|--------------------------------|----------------------|
97+
| `help` | Display available commands | `help` |
98+
| `shell` | Enter advanced shell mode | `shell` |
99+
| `clear` | Clear screen | `clear` |
100+
| `echo` | Display text | `echo Hello World` |
101+
| `date` | Show current date/time | `date` |
102+
| `calc` | Basic arithmetic calculator | `calc 15 + 25` |
103+
| `meminfo` | Memory usage statistics | `meminfo` |
104+
| `sysinfo` | System information | `sysinfo` |
105+
| `history` | Show command history | `history` |
106+
| `palette` | Color palette demonstration | `palette` |
107+
| `uptime` | System uptime | `uptime` |
108+
| `reboot` | Restart system | `reboot` |
109+
| `shutdown`| Halt system | `shutdown` |
110+
111+
### Example images
112+
113+
<img width="630" height="402" alt="491976426-57325cc4-dd78-47cf-8827-804cf53cb185" src="https://github.com/user-attachments/assets/2725aafa-2fe1-4201-8857-c048301d74d0" />
114+
115+
<img width="308" height="163" alt="491976413-0b86062a-a32c-4c5f-a6fc-20f09e9b77b4" src="https://github.com/user-attachments/assets/e0312457-23eb-4f6a-a022-7deeeb1fb674" />
116+
117+
<img width="474" height="359" alt="491976385-63fb8d22-9909-4921-8cd1-293cf9314de8" src="https://github.com/user-attachments/assets/e04c7c31-51d4-40f3-a218-8c3dcc20716b" />
118+
119+
<img width="487" height="401" alt="491976361-8c378fbe-461f-4580-b94d-247fefe88f2b" src="https://github.com/user-attachments/assets/c395609b-5be9-4acd-afb7-4f60c306e9cb" />
120+
121+
122+
### Calculator Examples
123+
```bash
124+
apollo> calc 100 + 50
125+
Result: 100 + 50 = 150
126+
127+
apollo> calc 256 / 8
128+
Result: 256 / 8 = 32
129+
130+
apollo> calc 25 * 4
131+
Result: 25 * 4 = 100
132+
```
133+
134+
## Development and Debugging
135+
136+
### Running on Real Hardware
137+
```bash
138+
# Create bootable USB drive
139+
sudo dd if=distribution/apollo.iso of=/dev/sdX bs=4M status=progress conv=fsync
140+
# Replace /dev/sdX with your USB device
141+
```
142+
143+
### Debug Information
144+
```bash
145+
# Boot with debugging symbols
146+
qemu-system-x86_64 -cdrom apollo.iso -s -S -monitor stdio
147+
148+
# In another terminal, connect GDB
149+
gdb distribution/apollo.bin
150+
(gdb) target remote localhost:1234
151+
(gdb) continue
152+
```
153+
154+
## Technical Specifications
155+
156+
- **Architecture**: x86_64 (AMD64/Intel 64)
157+
- **Boot Protocol**: Multiboot2
158+
- **Memory Model**: 64-bit flat memory with paging
159+
- **Graphics**: VGA text mode 80x25 with 16-color palette
160+
- **Input**: PS/2 keyboard with full modifier support
161+
- **Build System**: GNU Make with cross-compilation
162+
- **Languages**: C99, x86_64 Assembly
163+
- **Toolchain**: GCC cross-compiler, NASM assembler
164+
165+
---
166+
167+
**Apollo Kernel** - x86_64 Operating System Technology

0 commit comments

Comments
 (0)