Student Guide

Open PowerShell as Administrator:

The final artefact is seng21213.img — a raw disk image consisting of the 512-byte boot sector followed immediately by the kernel binary.

QEMU opens a window showing the VGA output. You should see:

Open Makefile and add your file to KERN_SRCS:

For NASM assembly files (e.g., boot/switch.asm) add a separate rule:

Terminal 1 — start QEMU in debug mode (CPU paused):

Terminal 2 — attach GDB (sets breakpoint at kernel_main then continues):

• 512-byte MBR in NASM loads the kernel via INT 0x13
• 3-entry GDT and CR0 Protected Mode switch
• VGA text-mode driver writing directly to physical 0xB8000
• PS/2 keyboard driver (polling mode, Set-1 scancodes)
• Interactive shell with command table dispatch

• Define pcb_t — at minimum: PID, state, stack pointer, entry point
• Implement create_process(entry_fn) — allocates a 4 KB stack
• Program the i8253 PIT to fire IRQ0 at 100 Hz (10 ms tick)
• Write switch.asm — PUSHAD/POPAD context switch stub
• Implement the Round-Robin scheduler in the IRQ0 handler
• Add ps shell command — lists all PCBs and their states

• Kernel threads sharing the process's address space — thread_create(fn, arg)
• mutex_t with mutex_lock() and mutex_unlock() (blocking)
• Counting semaphore_t with sem_wait() and sem_signal()
• Demonstrate the myglobal race condition with and without a mutex
• Bounded-buffer producer-consumer using three semaphores

• Parse the BIOS E820 memory map stored by the bootloader at a known address
• Build a bitmap — 1 bit per 4 KB physical page frame
• pmm_alloc_frame() — first-fit scan, marks frame used, returns physical address
• pmm_free_frame(paddr) — clears the bitmap bit
• meminfo shell command — prints total / used / free MB

• 1 MB RAM disk — a fixed-size byte array in BSS
• Superblock at block 0 — magic number, block/inode counts
• Block bitmap and inode bitmap at fixed offsets
• inode_t — size, direct block pointers (8 × 4 KB = 32 KB max)
• Flat directory — array of (name[28], inode) entries in block 1
• POSIX-style API: fs_open, fs_read, fs_write, fs_close, fs_unlink
• Shell: ls, touch, cat, write, rm

# 1. Create a private repository on your personal GitHub account
                #    Go to https://github.com/new — set visibility to Private
                #    Repository name: seng21213-os
                
                # 2. Clone it and copy the starter kit in
                $ git clone https://github.com/<your-username>/seng21213-os.git
                $ cp -r stage0/* seng21213-os/
                $ cd seng21213-os
                
                # 3. Add a .gitignore to exclude build artefacts
                $ echo "build/
                seng21213.img
                *.o
                *.bin
                *.elf" > .gitignore
                
                # 4. Initial commit and push
                $ git add .
                $ git commit -m "Initial commit: Stage 0 starter kit"
                $ git push origin main
                
                # 5. Add the lecturer as a collaborator so your work can be reviewed
                #    GitHub → Settings → Collaborators → Add: tiroshanm

• make clean && make produces zero errors and zero warnings
• make run boots in QEMU without crashing or rebooting
• All required commands for this stage work correctly
• Code is commented with references to lecture sections (e.g., "L09 §3")
• .gitignore excludes build/ and seng21213.img
• README.md is updated — describes your extensions and how to test them
• Extension(s) documented in README with test instructions (bonus marks)
• Tag pushed to GitLab: git push origin main --tags

Your GCC installation lacks 32-bit multilib support. Install it:

The most common cause is the kernel loading address not matching the linker script. Check:

• KERNEL_LOAD_SEG EQU 0x1000 in boot.asm → physical address 0x1000 × 0x10 = 0x10000
• . = 0x10000 in linker.ld
• Both values must match. Run make debug and step through with GDB from 0x7C00.

You ran make gdb without a running make debug session. Start make debug first in a separate terminal, wait for the message "waiting for GDB on :1234", then run make gdb.

Click inside the QEMU window to capture keyboard focus. To release focus press Ctrl+Alt+G. If running headless (-nographic), type directly in the terminal — the PS/2 driver will still receive scancodes via QEMU's emulated keyboard.

Technically yes, but it is strongly discouraged for bare-metal work at this level. C++ requires additional runtime support (__cxa_atexit, global constructors, vtable infrastructure) that adds complexity without benefit. All lecture examples use C99 — stay with C.