Metadata-Version: 2.4
Name: kimdos
Version: 0.2.0
Summary: Commodore serial bus disk library and shell for the KIM-1 and its replicas
Author: anarkiwi
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/anarkiwi/kimdos
Keywords: kim-1,6502,iec,1541,sd2iec,pal-ii,retrocomputing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kimtape>=0.1.1
Requires-Dist: py65
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Dynamic: license-file

# kimdos

Commodore serial bus (IEC) disk access for the KIM-1, PAL-1/PAL-II and other
replicas: a 6502 library, and a shell built on it, that load and save CBM DOS
files on a 1541, an SD2IEC/uIEC or anything else that speaks the bus, with
JiffyDOS for devices that have it. Written from the protocol, not from
Commodore's code.

The library uses no zero page, preserves the user port's spare bits, and links
anywhere with ld65; an llvm-mos C version comes with a KIM-1 platform for that
compiler. The shell runs over the monitor's TTY:

```
KIMDOS
>S PROG,2000,290D
00, OK,00,00
>L PROG,4000
$4000-$490D
>$
1 "                " 32 2A
10   "PROG"             PRG
65535 BLOCKS FREE.
>S PROG,2000,2001
63,FILE EXISTS,00,00
```

## Install

```sh
pip install kimdos
kimtape load --port /dev/ttyUSB0 https://github.com/anarkiwi/kimdos/releases/latest/download/kimdos-2000.ptp --go 2000
```

Each release has the shell at $0400, $2000 and $C000 (`kimdos-<org>.ptp`,
`.bin`, `.lbl`), also in the package (`kimdos.build.packaged`); it needs
about 2.5K of RAM there. The package ships the llvm-mos C library:
`python -m kimdos.clib` prints its directory.

To build, with cc65: `make ORG=2000` writes `build/kimdos-2000.{bin,ptp,lbl,map}`
and `build/kimdos.lib`; `make clib` builds `build/c/libkimdos.a` with llvm-mos
in docker.

## Shell

| Command | |
| --- | --- |
| `$[pattern]` | directory, e.g. `$`, `$0:A*` |
| `@` | drive status |
| `@command` | DOS command, e.g. `@S:OLD`, `@R:NEW=OLD`, `@CD:GAMES` |
| `L name[,addr]` | load, to the file's own address or to `addr` |
| `V name[,addr]` | verify against memory |
| `S name,start,end` | save `start`-`end` inclusive; `@0:name` replaces |
| `#[device]` | show or set the device number (decimal, default 8) |
| `J[0\|1]` | show, or turn off or on, JiffyDOS (default on) |
| `Q` | return to the monitor; `G` then runs what was loaded |

Names may be quoted. From the keypad, put the KIM tape ID in $17F9 and run
`ORG+3` to load the file named by its two hex digits, or set $17F5-$17F8 as
for a tape save and run `ORG+6` to save.

## Simulator

```sh
kimdos sim --dir ./disk           # the shell against .prg files in ./disk
kimdos sim --no-jiffy             # against a drive without JiffyDOS
kimdos bench                      # cycles per byte and JiffyDOS margins
kimdos board --port /dev/ttyUSB0 --install '$' '@'
```

## Documentation

- [docs/hardware.md](docs/hardware.md) — the adapter and its wiring
- [docs/library.md](docs/library.md) — linking the library into a program, the API
- [docs/clibrary.md](docs/clibrary.md) — the llvm-mos C library and KIM-1 platform
- [docs/protocol.md](docs/protocol.md) — the bus protocol as implemented
- [docs/development.md](docs/development.md) — tests, the simulator, releases
