# Kernal-Resident C64 OS Skeleton

This sample shows a practical starting memory layout for a Commodore 64 OS that **keeps the KERNAL ROM visible** so you can continue using routines like `CINT`, `BSOUT`, `GETIN`, `LOAD`, and `SAVE`.

## Memory Plan

Use `$0001` with low bits `%110`:

- `LORAM = 0`
- `HIRAM = 1`
- `CHAREN = 1`

That gives you:

- `$A000-$BFFF` = RAM under BASIC ROM
- `$C000-$CFFF` = always-visible RAM for your OS core
- `$D000-$DFFF` = I/O visible
- `$E000-$FFFF` = KERNAL ROM visible

In practice, the commonly seen value is `$36`, but this sample preserves the upper cassette-control bits and only changes the low three banking bits.

## Recommended Layout

- `$0002`, `$00FB-$00FE` = fast zero-page workspace
- `$0200-$03FF` = vectors, buffers, light system workspace
- `$0400-$07E7` = screen RAM
- `$0801-$9FFF` = BASIC area during development, or additional RAM if you fully replace BASIC usage
- `$A000-$BFFF` = banked work RAM, modules, command buffers, filesystem workspace
- `$C000-$CFFF` = OS core and resident code
- `$E000-$FFFF` = KERNAL ROM, still callable through `$FFxx`

## Why This Is a Good First Setup

It lets you:

- keep all normal KERNAL calls available
- avoid writing your own screen, keyboard, and IEC routines on day one
- gain 8 KB of extra RAM at `$A000-$BFFF`
- keep your OS core in safe always-RAM at `$C000`

## What The Sample Does

- loads at `$0801` as a normal BASIC-start PRG
- boots through BASIC line `10 SYS2061`
- switches memory to BASIC-off / KERNAL-on / I/O-on
- writes a live work byte at `$A000` and a small signature starting at `$A001`
- uses a file buffer at `$A100` for simple shell `LOAD`/`SAVE` operations
- uses KERNAL routines for screen output and keyboard input
- lets you inspect the current banking mode and a workspace byte in `$A000`
- restores normal memory mapping before returning to BASIC

## Build

```text
build.bat
```

## Run On A C64 Or In VICE

Because this program now starts in **normal BASIC memory at `$0801`**, load and run it like a standard BASIC program:

```basic
LOAD "KERNAL_OS.PRG",8
RUN
```

If you want to jump into it manually after loading, the BASIC stub runs:

```basic
SYS 2061
```

If you are in VICE:

```text
x64sc -autostart kernal_os.prg
```

Then use these CLI commands:

- `HELP` to show the command list
- `MEM` to show `$0001` and the live work byte at `$A000`
- `INC` to increment the work byte at `$A000`
- `DUMP` to show `$A000-$A00F`
- `ZERO` to clear the first 16 bytes of the workspace
- `SIGN` to rewrite the signature starting at `$A001`
- `SCREEN` to show the current C64 screen dimensions from the KERNAL
- `DIR` to list only the filenames on the current target
- `STATUS` to read and print the drive status channel on the current target
- `INIT` to send the standard `I` initialize command to the current target
- `ECHO text` to print text and load the shell buffer at `$A100`
- `TOUCH filename` to create an empty sequential file
- `TYPE filename` to print a sequential file from the current target
- `LOAD filename` to load a sequential file into the shell buffer at `$A100`
- `SAVE filename` to save the current shell buffer from `$A100`
- `DEVICE n` or `DEV n` to set the current device number, usually `8-15`
- `DRIVE n` to set the current drive number, usually `0` or `1`
- `DEL filename` to scratch a file on the current target
- `ERASE filename` as an alias for `DEL`
- `CLS` to clear the screen
- `ABOUT` to reprint the layout explanation
- `EXIT` to restore normal memory mapping and return to BASIC

## Notes On The New File Commands

- `TYPE`, `LOAD`, and `SAVE` are implemented as **sequential-file shell commands**
- `LOAD filename` in this sample does **not** replace the running OS core with a machine-language PRG
- instead, it reads file data into the buffer at `$A100`
- `SAVE filename` writes the current buffer back out as a sequential file
- `TOUCH filename` creates an empty sequential file by opening it for write and closing it immediately
- `ECHO text` also fills the `$A100` shell buffer so it can be saved

## Simple Pipe Support

The shell now supports a simple redirection pattern for `ECHO`:

```text
ECHO HELLO WORLD > SAVE TESTFILE
```

That:

1. copies `HELLO WORLD` into the shell buffer at `$A100`
2. prints the text
3. rewrites the rest of the command line to `SAVE TESTFILE`
4. runs the save command immediately

This is intentionally small and predictable rather than a full Unix-style pipe system.

That keeps the sample safe and predictable while still showing how a KERNAL-based OS shell can manage files and a current DOS target.