recarted 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- recarted-0.2.0/LICENSE +21 -0
- recarted-0.2.0/Makefile +8 -0
- recarted-0.2.0/PKG-INFO +91 -0
- recarted-0.2.0/README.md +74 -0
- recarted-0.2.0/asm/disk.s +177 -0
- recarted-0.2.0/asm/loader.cfg +2 -0
- recarted-0.2.0/asm/memory.s +69 -0
- recarted-0.2.0/docs/TECHNICAL.md +43 -0
- recarted-0.2.0/pyproject.toml +52 -0
- recarted-0.2.0/pyproject.toml.orig +41 -0
- recarted-0.2.0/src/recarted/__init__.py +1 -0
- recarted-0.2.0/src/recarted/atx.py +125 -0
- recarted-0.2.0/src/recarted/capture.py +127 -0
- recarted-0.2.0/src/recarted/cli.py +99 -0
- recarted-0.2.0/src/recarted/convert.py +85 -0
- recarted-0.2.0/src/recarted/example.py +42 -0
- recarted-0.2.0/src/recarted/images.py +219 -0
- recarted-0.2.0/src/recarted/loaders/disk.bin +0 -0
- recarted-0.2.0/src/recarted/loaders/memory.bin +0 -0
- recarted-0.2.0/tests/test_atx.py +152 -0
- recarted-0.2.0/tests/test_loaders.py +82 -0
- recarted-0.2.0/tests/test_media.py +120 -0
recarted-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Christopher Patti
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
recarted-0.2.0/Makefile
ADDED
recarted-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: recarted
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Turn recognized Atari 8-bit cassette and floppy images into A8PicoCart cartridges
|
|
5
|
+
Author: Christopher Patti
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Classifier: Environment :: Console
|
|
9
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
10
|
+
Classifier: Topic :: System :: Emulators
|
|
11
|
+
Requires-Dist: cyclopts>=4,<5
|
|
12
|
+
Requires-Python: >=3.11
|
|
13
|
+
Project-URL: Homepage, https://github.com/feoh/recarted
|
|
14
|
+
Project-URL: Repository, https://github.com/feoh/recarted
|
|
15
|
+
Project-URL: Issues, https://github.com/feoh/recarted/issues
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
# ReCarted!
|
|
19
|
+
|
|
20
|
+

|
|
21
|
+
|
|
22
|
+
Give an Atari cassette or floppy a second life in the cartridge slot. ReCarted is a **Linux command-line converter for the Atari 8-bit XL/XE and A8PicoCart**. Give it a supported `.cas` cassette, `.atr` floppy, or `.atx` track image and it writes a new cartridge file. It never overwrites your original.
|
|
23
|
+
|
|
24
|
+
## Try it in a minute (no game images needed)
|
|
25
|
+
|
|
26
|
+
Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git on Linux, then:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
uv tool install recarted
|
|
30
|
+
recarted example rainbow.cas
|
|
31
|
+
recarted inspect rainbow.cas
|
|
32
|
+
recarted convert rainbow.cas
|
|
33
|
+
recarted inspect rainbow.car
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
To update later, run `uv tool upgrade recarted`. If the shell can't find `recarted`, run `uv tool update-shell` and open a new terminal. Python 3.11 or newer is required; uv can supply it. No assembler is needed. Only the two emulator-assisted ATX recipes require Atari800 and an Atari OS ROM.
|
|
37
|
+
|
|
38
|
+
The example is an original Atari program that displays colour bars. Try `recarted example rainbow-disk.atr` for the floppy equivalent, or `recarted example rainbow-track.atx` to try the ATX workflow without an emulator or ROM. Use distinct names: both `rainbow.cas` and `rainbow.atr` would otherwise want to write `rainbow.car`.
|
|
39
|
+
|
|
40
|
+
## Convert your own image
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
recarted recipes
|
|
44
|
+
recarted inspect 'Gridrunner.cas'
|
|
45
|
+
recarted convert 'Gridrunner.cas'
|
|
46
|
+
recarted convert 'Bruce Lee.atr' --output 'Bruce Lee.xex'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`inspect` reads the contents, not the filename. `convert` writes a `.car` beside the source unless you choose `--output`. If the output already exists, choose a new name. For one-load games you can request `.xex` instead: the A8PicoCart loads that directly into RAM. For games that still need disk sectors, use `.car`.
|
|
50
|
+
|
|
51
|
+
| Source | Recognized games in 0.2 | Output |
|
|
52
|
+
| --- | --- | --- |
|
|
53
|
+
| Cassette (`.cas`) | Attack of the Mutant Camels, Gridrunner, Hover Bovver | CAR or XEX |
|
|
54
|
+
| Disk (`.atr`) | Bruce Lee (Datasoft, US a2) | CAR or XEX |
|
|
55
|
+
| Disk (`.atr`) | Jumpman (Epyx, US), Pinball Construction Set | CAR with a **read-only** virtual disk |
|
|
56
|
+
| Track disk (`.atx`) | Jumpman (Epyx, US) | CAR with a **read-only** virtual disk |
|
|
57
|
+
| Track disk (`.atx`) | The Tail of Beta Lyrae (Datamost), Bruce Lee | CAR; Atari800 + stock XL/XE OS revision 2 required |
|
|
58
|
+
|
|
59
|
+
These are **specific releases**, not every dump of each title. If `inspect` says “No matching recipe,” changing the name won't help. No commercial games, game data, or Atari OS ROMs are distributed with ReCarted. Use images you have the right to convert.
|
|
60
|
+
|
|
61
|
+
## Convert an ATX disk
|
|
62
|
+
|
|
63
|
+
Run `recarted inspect` first. If the disk is the recognized Jumpman release, `recarted convert 'Jumpman (1983)(Epyx)(US)[!].atx'` works directly. For *The Tail of Beta Lyrae* and *Bruce Lee*, install Atari800 with its text monitor (tested with 5.2.0) and supply your own stock 16 KiB XL/XE OS revision 2 ROM. For example, from the directory containing the game and `ATARIXL.ROM`:
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
recarted inspect 'Tail of Beta Lyrae (The) _ Datamost.atx'
|
|
67
|
+
recarted convert 'Tail of Beta Lyrae (The) _ Datamost.atx' --os-rom ATARIXL.ROM
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
ReCarted boots a temporary copy of the original track image in the background. The resulting `.car` needs neither the disk nor that ROM file on the cartridge. An unknown dump isn't flattened into an ATR; it may need the disk's duplicate sectors, timing or error status. If you're upgrading the Git-based install, run `uv tool upgrade recarted`.
|
|
71
|
+
|
|
72
|
+
## Play it
|
|
73
|
+
|
|
74
|
+
- **A8PicoCart:** With the cartridge **removed from the Atari**, connect it to the computer over USB. Copy the resulting `.car` or `.xex` to it, eject it, and **disconnect USB before inserting it into the powered-off Atari**. Power on, select the file normally, and it boots straight into the program. No DiskCart menu or disk in D1: is needed.
|
|
75
|
+
- **Linux emulator:** Install `atari800` separately and run `recarted test rainbow.car`. For the disk-reader games, use a stock XL/XE OS: `recarted test 'Jumpman.car' --os-rom ATARIXL.ROM` (supply the path to your own ROM). The command opens Atari800 so **you** can check the screen and controls; it does not claim the game passed just because the emulator started. For XEX, use `atari800 -xl -nobasic -run 'Bruce Lee.xex'`.
|
|
76
|
+
|
|
77
|
+
**Can I save a pinball table?** Not to the embedded cartridge disk. Use your original ATR in a writable disk setup for authoring and saving.
|
|
78
|
+
|
|
79
|
+
**“Unsupported Cartridge Type”?** Run `recarted inspect` on the file you actually copied. ReCarted generates **type 41, 128 KiB** (Atarimax **1 Mbit**). The older type 42 is **1 MiB / 8 Mbit** and is not supported by stock A8PicoCart. Renaming a ROM or editing that header byte doesn't fix it. If type 41 is rejected, tell us your cartridge model and firmware version.
|
|
80
|
+
|
|
81
|
+
## What's next?
|
|
82
|
+
|
|
83
|
+
More **cassette** recipes are a priority, especially multi-stage tapes such as Preppie! and the two sides of International Karate. Additional ATX releases, more floppy layouts, and tested **macOS and Windows** installations are also on the roadmap. WAV recordings, raw ROMs, and arbitrary disk/tape ports are not supported.
|
|
84
|
+
|
|
85
|
+
## Contribute a recipe
|
|
86
|
+
|
|
87
|
+
Got another Atari disk or tape running from a cartridge? [Send a pull request](https://github.com/feoh/recarted/compare) with your recipe. ATX, ATR, and CAS recipes are all welcome, including ones for a different release of a game we already support. Tell us which release you converted and what you saw when you booted it in Atari800 or on hardware. Share the recipe and the image’s SHA-256, not the commercial image or OS ROM. See [how to add and verify a recipe](docs/TECHNICAL.md#verification-and-adding-recipes) for the testing details.
|
|
88
|
+
|
|
89
|
+
[Request a recipe or report a hardware result](https://github.com/feoh/recarted/issues): include the title and release, `recarted inspect` output, the source's `sha256sum`, your Atari/cart model and firmware, and what you saw. Please **don't attach commercial images or OS ROMs**.
|
|
90
|
+
|
|
91
|
+
For how recognition works, emulator evidence, limitations, or building and testing the loaders, see [Technical notes](docs/TECHNICAL.md). [MIT license](LICENSE).
|
recarted-0.2.0/README.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# ReCarted!
|
|
2
|
+
|
|
3
|
+

|
|
4
|
+
|
|
5
|
+
Give an Atari cassette or floppy a second life in the cartridge slot. ReCarted is a **Linux command-line converter for the Atari 8-bit XL/XE and A8PicoCart**. Give it a supported `.cas` cassette, `.atr` floppy, or `.atx` track image and it writes a new cartridge file. It never overwrites your original.
|
|
6
|
+
|
|
7
|
+
## Try it in a minute (no game images needed)
|
|
8
|
+
|
|
9
|
+
Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git on Linux, then:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
uv tool install recarted
|
|
13
|
+
recarted example rainbow.cas
|
|
14
|
+
recarted inspect rainbow.cas
|
|
15
|
+
recarted convert rainbow.cas
|
|
16
|
+
recarted inspect rainbow.car
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
To update later, run `uv tool upgrade recarted`. If the shell can't find `recarted`, run `uv tool update-shell` and open a new terminal. Python 3.11 or newer is required; uv can supply it. No assembler is needed. Only the two emulator-assisted ATX recipes require Atari800 and an Atari OS ROM.
|
|
20
|
+
|
|
21
|
+
The example is an original Atari program that displays colour bars. Try `recarted example rainbow-disk.atr` for the floppy equivalent, or `recarted example rainbow-track.atx` to try the ATX workflow without an emulator or ROM. Use distinct names: both `rainbow.cas` and `rainbow.atr` would otherwise want to write `rainbow.car`.
|
|
22
|
+
|
|
23
|
+
## Convert your own image
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
recarted recipes
|
|
27
|
+
recarted inspect 'Gridrunner.cas'
|
|
28
|
+
recarted convert 'Gridrunner.cas'
|
|
29
|
+
recarted convert 'Bruce Lee.atr' --output 'Bruce Lee.xex'
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`inspect` reads the contents, not the filename. `convert` writes a `.car` beside the source unless you choose `--output`. If the output already exists, choose a new name. For one-load games you can request `.xex` instead: the A8PicoCart loads that directly into RAM. For games that still need disk sectors, use `.car`.
|
|
33
|
+
|
|
34
|
+
| Source | Recognized games in 0.2 | Output |
|
|
35
|
+
| --- | --- | --- |
|
|
36
|
+
| Cassette (`.cas`) | Attack of the Mutant Camels, Gridrunner, Hover Bovver | CAR or XEX |
|
|
37
|
+
| Disk (`.atr`) | Bruce Lee (Datasoft, US a2) | CAR or XEX |
|
|
38
|
+
| Disk (`.atr`) | Jumpman (Epyx, US), Pinball Construction Set | CAR with a **read-only** virtual disk |
|
|
39
|
+
| Track disk (`.atx`) | Jumpman (Epyx, US) | CAR with a **read-only** virtual disk |
|
|
40
|
+
| Track disk (`.atx`) | The Tail of Beta Lyrae (Datamost), Bruce Lee | CAR; Atari800 + stock XL/XE OS revision 2 required |
|
|
41
|
+
|
|
42
|
+
These are **specific releases**, not every dump of each title. If `inspect` says “No matching recipe,” changing the name won't help. No commercial games, game data, or Atari OS ROMs are distributed with ReCarted. Use images you have the right to convert.
|
|
43
|
+
|
|
44
|
+
## Convert an ATX disk
|
|
45
|
+
|
|
46
|
+
Run `recarted inspect` first. If the disk is the recognized Jumpman release, `recarted convert 'Jumpman (1983)(Epyx)(US)[!].atx'` works directly. For *The Tail of Beta Lyrae* and *Bruce Lee*, install Atari800 with its text monitor (tested with 5.2.0) and supply your own stock 16 KiB XL/XE OS revision 2 ROM. For example, from the directory containing the game and `ATARIXL.ROM`:
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
recarted inspect 'Tail of Beta Lyrae (The) _ Datamost.atx'
|
|
50
|
+
recarted convert 'Tail of Beta Lyrae (The) _ Datamost.atx' --os-rom ATARIXL.ROM
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
ReCarted boots a temporary copy of the original track image in the background. The resulting `.car` needs neither the disk nor that ROM file on the cartridge. An unknown dump isn't flattened into an ATR; it may need the disk's duplicate sectors, timing or error status. If you're upgrading the Git-based install, run `uv tool upgrade recarted`.
|
|
54
|
+
|
|
55
|
+
## Play it
|
|
56
|
+
|
|
57
|
+
- **A8PicoCart:** With the cartridge **removed from the Atari**, connect it to the computer over USB. Copy the resulting `.car` or `.xex` to it, eject it, and **disconnect USB before inserting it into the powered-off Atari**. Power on, select the file normally, and it boots straight into the program. No DiskCart menu or disk in D1: is needed.
|
|
58
|
+
- **Linux emulator:** Install `atari800` separately and run `recarted test rainbow.car`. For the disk-reader games, use a stock XL/XE OS: `recarted test 'Jumpman.car' --os-rom ATARIXL.ROM` (supply the path to your own ROM). The command opens Atari800 so **you** can check the screen and controls; it does not claim the game passed just because the emulator started. For XEX, use `atari800 -xl -nobasic -run 'Bruce Lee.xex'`.
|
|
59
|
+
|
|
60
|
+
**Can I save a pinball table?** Not to the embedded cartridge disk. Use your original ATR in a writable disk setup for authoring and saving.
|
|
61
|
+
|
|
62
|
+
**“Unsupported Cartridge Type”?** Run `recarted inspect` on the file you actually copied. ReCarted generates **type 41, 128 KiB** (Atarimax **1 Mbit**). The older type 42 is **1 MiB / 8 Mbit** and is not supported by stock A8PicoCart. Renaming a ROM or editing that header byte doesn't fix it. If type 41 is rejected, tell us your cartridge model and firmware version.
|
|
63
|
+
|
|
64
|
+
## What's next?
|
|
65
|
+
|
|
66
|
+
More **cassette** recipes are a priority, especially multi-stage tapes such as Preppie! and the two sides of International Karate. Additional ATX releases, more floppy layouts, and tested **macOS and Windows** installations are also on the roadmap. WAV recordings, raw ROMs, and arbitrary disk/tape ports are not supported.
|
|
67
|
+
|
|
68
|
+
## Contribute a recipe
|
|
69
|
+
|
|
70
|
+
Got another Atari disk or tape running from a cartridge? [Send a pull request](https://github.com/feoh/recarted/compare) with your recipe. ATX, ATR, and CAS recipes are all welcome, including ones for a different release of a game we already support. Tell us which release you converted and what you saw when you booted it in Atari800 or on hardware. Share the recipe and the image’s SHA-256, not the commercial image or OS ROM. See [how to add and verify a recipe](docs/TECHNICAL.md#verification-and-adding-recipes) for the testing details.
|
|
71
|
+
|
|
72
|
+
[Request a recipe or report a hardware result](https://github.com/feoh/recarted/issues): include the title and release, `recarted inspect` output, the source's `sha256sum`, your Atari/cart model and firmware, and what you saw. Please **don't attach commercial images or OS ROMs**.
|
|
73
|
+
|
|
74
|
+
For how recognition works, emulator evidence, limitations, or building and testing the loaders, see [Technical notes](docs/TECHNICAL.md). [MIT license](LICENSE).
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
; Read-only D1: driver for two specifically recognized 90 KiB boot disks.
|
|
2
|
+
; Copy the XL/XE's own OS to the RAM underneath it, then redirect DSKINV.
|
|
3
|
+
; The OS itself is neither part of ReCarted nor stored in the .car.
|
|
4
|
+
.segment "CODE"
|
|
5
|
+
.org $a000
|
|
6
|
+
params = $bf00
|
|
7
|
+
start:
|
|
8
|
+
sei
|
|
9
|
+
cld
|
|
10
|
+
lda #0
|
|
11
|
+
sta $d40e
|
|
12
|
+
sta $d400
|
|
13
|
+
lda $d301
|
|
14
|
+
ora #3
|
|
15
|
+
sta $d301
|
|
16
|
+
; Relocate the OS copy loop to RAM so its absolute operands are writable.
|
|
17
|
+
ldx #r_end-reloc
|
|
18
|
+
move: lda source-1,x
|
|
19
|
+
sta reloc-1,x
|
|
20
|
+
dex
|
|
21
|
+
bne move
|
|
22
|
+
jsr reloc
|
|
23
|
+
; Now executing with RAM OS selected, cartridge bank 0 still visible.
|
|
24
|
+
ldx #handler_end-driver
|
|
25
|
+
put: lda handler_src-1,x
|
|
26
|
+
sta driver-1,x
|
|
27
|
+
dex
|
|
28
|
+
bne put
|
|
29
|
+
lda #$4c
|
|
30
|
+
sta $e453
|
|
31
|
+
lda #<driver
|
|
32
|
+
sta $e454
|
|
33
|
+
lda #>driver
|
|
34
|
+
sta $e455
|
|
35
|
+
lda params
|
|
36
|
+
sta $0304
|
|
37
|
+
clc
|
|
38
|
+
adc #6
|
|
39
|
+
sta enter+1
|
|
40
|
+
lda params+1
|
|
41
|
+
sta $0305
|
|
42
|
+
adc #0
|
|
43
|
+
sta enter+2
|
|
44
|
+
lda params+2
|
|
45
|
+
sta nboot
|
|
46
|
+
lda #$31
|
|
47
|
+
sta $0300
|
|
48
|
+
lda #1
|
|
49
|
+
sta $0301
|
|
50
|
+
sta $030a
|
|
51
|
+
sta $09
|
|
52
|
+
lda #0
|
|
53
|
+
sta $030b
|
|
54
|
+
sta $0244
|
|
55
|
+
lda #$52
|
|
56
|
+
sta $0302
|
|
57
|
+
jmp load_boot
|
|
58
|
+
source:
|
|
59
|
+
.org $0400
|
|
60
|
+
reloc:
|
|
61
|
+
ldy #0
|
|
62
|
+
os_page:
|
|
63
|
+
lda $d301
|
|
64
|
+
ora #1
|
|
65
|
+
sta $d301
|
|
66
|
+
os_read: ldx $c000,y
|
|
67
|
+
and #$fe
|
|
68
|
+
sta $d301
|
|
69
|
+
txa
|
|
70
|
+
os_write: sta $c000,y
|
|
71
|
+
iny
|
|
72
|
+
bne os_page
|
|
73
|
+
inc os_read+2
|
|
74
|
+
inc os_write+2
|
|
75
|
+
lda os_read+2
|
|
76
|
+
cmp #$d0
|
|
77
|
+
bne check
|
|
78
|
+
lda #$d8
|
|
79
|
+
sta os_read+2
|
|
80
|
+
sta os_write+2
|
|
81
|
+
check: lda os_read+2
|
|
82
|
+
bne os_page
|
|
83
|
+
rts
|
|
84
|
+
load_boot:
|
|
85
|
+
sta $d510
|
|
86
|
+
lda $d013
|
|
87
|
+
sta $03fa
|
|
88
|
+
lda #$c0
|
|
89
|
+
sta $6a
|
|
90
|
+
lda #$40
|
|
91
|
+
sta $d40e
|
|
92
|
+
cli
|
|
93
|
+
read_boot:
|
|
94
|
+
jsr driver
|
|
95
|
+
clc
|
|
96
|
+
lda $0304
|
|
97
|
+
adc #128
|
|
98
|
+
sta $0304
|
|
99
|
+
bcc skip
|
|
100
|
+
inc $0305
|
|
101
|
+
skip: inc $030a
|
|
102
|
+
dec nboot
|
|
103
|
+
bne read_boot
|
|
104
|
+
enter: jmp $ffff
|
|
105
|
+
nboot: .byte 0
|
|
106
|
+
r_end:
|
|
107
|
+
.assert r_end < $0600, error, "boot code overlaps boot sectors"
|
|
108
|
+
; Continue emitting bytes in bank 0, with run addresses in shadow OS RAM.
|
|
109
|
+
.org $a000+(source-start)+(r_end-reloc)
|
|
110
|
+
handler_src:
|
|
111
|
+
.org $cc00 ; international font, unused by these recipes
|
|
112
|
+
driver:
|
|
113
|
+
lda $0302
|
|
114
|
+
cmp #$52
|
|
115
|
+
bne fail
|
|
116
|
+
lda $0301
|
|
117
|
+
cmp #1
|
|
118
|
+
bne fail
|
|
119
|
+
; One-based sector, 64 sectors per 8 KiB bank; max 720 sectors ($2d0).
|
|
120
|
+
sec
|
|
121
|
+
lda $030a
|
|
122
|
+
sbc #1
|
|
123
|
+
sta low
|
|
124
|
+
lda $030b
|
|
125
|
+
sbc #0
|
|
126
|
+
cmp #3
|
|
127
|
+
bcs fail
|
|
128
|
+
cmp #2
|
|
129
|
+
bne in_range
|
|
130
|
+
ldy low
|
|
131
|
+
cpy #$d0
|
|
132
|
+
bcs fail
|
|
133
|
+
in_range:
|
|
134
|
+
asl
|
|
135
|
+
asl
|
|
136
|
+
sta high
|
|
137
|
+
lda low
|
|
138
|
+
lsr
|
|
139
|
+
lsr
|
|
140
|
+
lsr
|
|
141
|
+
lsr
|
|
142
|
+
lsr
|
|
143
|
+
lsr
|
|
144
|
+
ora high
|
|
145
|
+
tax
|
|
146
|
+
inx
|
|
147
|
+
lda low
|
|
148
|
+
lsr
|
|
149
|
+
and #$1f
|
|
150
|
+
ora #$a0
|
|
151
|
+
sta fetch+2
|
|
152
|
+
lda #0
|
|
153
|
+
ror ; carry = sector offset bit 0
|
|
154
|
+
sta fetch+1
|
|
155
|
+
lda $0304
|
|
156
|
+
sta store+1
|
|
157
|
+
lda $0305
|
|
158
|
+
sta store+2
|
|
159
|
+
inc $42 ; suppress deferred OS VBI during bank changes
|
|
160
|
+
ldy #0
|
|
161
|
+
loop: sta $d500,x
|
|
162
|
+
fetch: lda $a000,y
|
|
163
|
+
sta $d510
|
|
164
|
+
store: sta $ffff,y
|
|
165
|
+
iny
|
|
166
|
+
bpl loop
|
|
167
|
+
dec $42
|
|
168
|
+
ldy #1
|
|
169
|
+
bne finish
|
|
170
|
+
fail: ldy #$8b ; unsupported (including writes)
|
|
171
|
+
finish: sty $0303
|
|
172
|
+
tya
|
|
173
|
+
rts
|
|
174
|
+
low: .byte 0
|
|
175
|
+
high: .byte 0
|
|
176
|
+
handler_end:
|
|
177
|
+
.assert handler_end-driver < 256, error, "handler too big"
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
; ReCarted! type-41 RAM loader. Bank 0 holds this program; banks 1..15
|
|
2
|
+
; contain a page-aligned payload. The Atari OS calls start via CARTAD.
|
|
3
|
+
.segment "CODE"
|
|
4
|
+
.org $a000
|
|
5
|
+
params = $bf00
|
|
6
|
+
start:
|
|
7
|
+
sei
|
|
8
|
+
cld
|
|
9
|
+
lda #0
|
|
10
|
+
sta $d40e ; keep ANTIC NMIs out of the copy loop
|
|
11
|
+
sta $d400
|
|
12
|
+
lda $d301
|
|
13
|
+
ora #2 ; RAM, not BASIC, under the cartridge
|
|
14
|
+
sta $d301
|
|
15
|
+
ldx #ram_end-copy
|
|
16
|
+
move: lda source-1,x
|
|
17
|
+
sta copy-1,x
|
|
18
|
+
dex
|
|
19
|
+
bne move
|
|
20
|
+
lda params
|
|
21
|
+
sta dest+2
|
|
22
|
+
lda params+1
|
|
23
|
+
sta remaining
|
|
24
|
+
lda params+2
|
|
25
|
+
sta go+1
|
|
26
|
+
lda params+3
|
|
27
|
+
sta go+2
|
|
28
|
+
lda params+4
|
|
29
|
+
sta $0c ; cassette init vector
|
|
30
|
+
lda params+5
|
|
31
|
+
sta $0d
|
|
32
|
+
jmp copy
|
|
33
|
+
source:
|
|
34
|
+
.org $0100 ; bottom of stack page (no JSRs while here)
|
|
35
|
+
copy:
|
|
36
|
+
ldx #1
|
|
37
|
+
ldy #0
|
|
38
|
+
byte:
|
|
39
|
+
sta $d500,x ; select 8 KiB bank X
|
|
40
|
+
src: lda $a000,y
|
|
41
|
+
sta $d510 ; release cartridge before writing to RAM
|
|
42
|
+
dest: sta $1000,y
|
|
43
|
+
iny
|
|
44
|
+
bne byte
|
|
45
|
+
inc dest+2
|
|
46
|
+
inc src+2
|
|
47
|
+
lda src+2
|
|
48
|
+
cmp #$c0
|
|
49
|
+
bne next
|
|
50
|
+
lda #$a0
|
|
51
|
+
sta src+2
|
|
52
|
+
inx
|
|
53
|
+
next: dec remaining
|
|
54
|
+
bne byte
|
|
55
|
+
lda $d013
|
|
56
|
+
sta $03fa ; sync XL cartridge interlock with new state
|
|
57
|
+
lda #$c0
|
|
58
|
+
sta $6a
|
|
59
|
+
lda #2
|
|
60
|
+
sta $09 ; cassette boot flag (also used by Bruce Lee)
|
|
61
|
+
lda #0
|
|
62
|
+
sta $0244
|
|
63
|
+
lda #$40
|
|
64
|
+
sta $d40e
|
|
65
|
+
cli
|
|
66
|
+
go: jmp $ffff
|
|
67
|
+
remaining: .byte 0
|
|
68
|
+
ram_end:
|
|
69
|
+
.assert ram_end < $01c0, error, "loader exceeds stack reservation"
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# ReCarted technical notes
|
|
2
|
+
|
|
3
|
+
## Boundaries
|
|
4
|
+
|
|
5
|
+
This is a recipe converter, not an Atari CPU emulator, a tape decoder for audio, or a general filesystem-to-ROM converter. `images.py` sniffs container magic and parses bounded input (4 MiB maximum). It matches SHA-256 of the **program the tape boot header requests** the **entire ATR sector payload**, or the **whole ATX file**. A structurally valid unknown image can be inspected but not converted. Recognition does not depend on a filename or network lookup. No commercial input, captured memory, or proprietary OS is shipped.
|
|
6
|
+
|
|
7
|
+
- **CAS:** Walk little-endian FUJI chunks, allow the FUJI description, 600-baud declarations and standard 132-byte data records. Verify the two sync bytes, record framing and the Atari end-around-carry checksum. The recognized games are one-stage boot tapes; some dumps have one extra full block beyond the requested count. Timing gaps, descriptions and that unused block are not part of the game fingerprint. FSK, custom loaders, partial records and additional stages aren't interchangeable with this format. Don't discard a second stage to make the first stage match.
|
|
8
|
+
- **ATR:** Validate the paragraph count against file size and account for short boot sectors when inspecting double-density media. Only exact, single-density images in the catalog convert. Bruce Lee's boot sector and relocation stage describe a contiguous RAM program. Jumpman and Pinball Construction Set still read sectors after startup, so a bare RAM dump is not a substitute for a disk reader.
|
|
9
|
+
- **ATX v1:** Walk bounded track records and their length-prefixed chunks. Read each physical sector header without deduplicating it; report repeated IDs and controller error flags. Recognition hashes the original bytes, not a normalized sector map. Exact Jumpman maps cleanly to 40 single-density tracks of 18 unique sectors: reject exceptional geometry, extension chunks and flagged/missing sectors, order by logical sector, then require the existing ATR payload digest as a second check. The generated colour-bar ATX exercises a one-track variant. Other unrecognized images are never linearized for conversion.
|
|
10
|
+
- **Emulator-assisted ATX:** `capture.py` boots the two catalogued protected disks unmodified, from a read-only temporary copy. Atari800 must support ATX, headless SDL and the text monitor. We use a private config and NTSC 800XL, no BASIC or OS patches. The caller supplies stock XL/XE OS rev. 2 (SHA-256 `a77050b2d81db2d11eaa3dbafd8ec2531b478abcc3bcc4b0d846b634e885edb1`). No shell or caller-supplied paths enter the monitor commands. The game's own loader handles timing and error checks before handing off at `$4E8D` (Lyrae) or `$0418` (Bruce Lee). Require the breakpoint transcript, a complete `$0400–$BFFF` RAM dump and a matching fingerprint of 128 bytes at the entry point. Package only the game RAM with the memory loader, **not** a CPU snapshot or the OS ROM. Abort on timeout, emulator errors or signature mismatch; remove temporary media and RAM on exit. The output does not emulate the original disk drive or persist disk writes.
|
|
11
|
+
- **CAR:** Check the `CART` signature and big-endian additive payload checksum. Verify length for types 41 and 42. Inspection does not imply every other mapper is supported or that the contents are executable. [A8PicoCart firmware mapper table](https://github.com/robinhedwards/A8PicoCart/blob/fb0b36137a969a71b9258841c46676701125699d/source/Pico%20VSCode%20Project/a8_pico_cart/atari_cart.c#L418-L451).
|
|
12
|
+
|
|
13
|
+
## Output and 6502 boot code
|
|
14
|
+
|
|
15
|
+
`convert.py` writes a 16-byte CAR header followed by sixteen 8 KiB banks. Bank zero has ReCarted's original boot code, parameters at `$BF00`, and cartridge vectors. Payload starts in bank one. Access `$D500 + bank` to select a bank, `$D510` to release the cartridge. The loader synchronizes the XL cartridge interlock after release. This is **not** a resized type-42 DiskCart image. No DiskCart code or third-party boot binary is included.
|
|
16
|
+
|
|
17
|
+
- **Memory loader (`asm/memory.s`):** Relocates a small transfer loop to the low stack page, copies the program to its original address in RAM, disables the cart and enters the program with the boot variables it expects. An XEX output instead uses load segments, sets boot variables and supplies RUNAD. Payload data is taken from the user's input at conversion time.
|
|
18
|
+
- **Disk reader (`asm/disk.s`):** For the two 720-sector recipes, copies the host machine's XL/XE OS to RAM underneath ROM, skipping the I/O hole. Patches **DSKINV**, not all of SIO, to a small D1: read-only handler in shadow RAM in the international character set area. Copies the requested boot sectors, then enters the disk program. Each subsequent 128-byte sector is addressed as `(sector-1) / 64` banks past bank one and `(sector-1) % 64` sectors into that bank. Writes, other units and invalid sector numbers fail. Programs that bank the ROM OS back in, need the international font, use RAM underneath the OS, bypass DSKINV, or depend on write/status/timing semantics cannot assume this works. Do not enable this path just because an unknown disk is 90 KiB.
|
|
19
|
+
|
|
20
|
+
Both loaders are shipped **preassembled** as package resources. Users don't need a compiler. To change them, install cc65 (`ca65` and `ld65` on PATH), edit the corresponding `.s` file and `make -B loaders`. Commit both source and regenerated blobs. Linux CI checks byte-for-byte reproducibility.
|
|
21
|
+
|
|
22
|
+
## Local development
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
git clone https://github.com/feoh/recarted.git
|
|
26
|
+
cd recarted
|
|
27
|
+
uv sync --locked --python 3.11
|
|
28
|
+
uv run recarted --help
|
|
29
|
+
uv run prek run --all-files
|
|
30
|
+
uv run mypy src
|
|
31
|
+
uv run pytest
|
|
32
|
+
uv build
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Unit tests generate their own tapes/disks. Nothing in `tests` requires commercial media. A small 6502 harness exercises the mapper and the assembled code with synthetic RAM, ROM and input sectors. It isn't a substitute for Atari800 or hardware tests.
|
|
36
|
+
|
|
37
|
+
## Verification and adding recipes
|
|
38
|
+
|
|
39
|
+
Linux Atari800 5.2.0, PAL 800XL, stock XL OS, no attached tape or disk: startup checked for the six game CAR recipes. Observed the Minter titles/attract screens, Bruce Lee title, Jumpman start/attract screen and Pinball Construction Set editor. The cassette regression inputs for this pass were standard CAS streams reconstructed from the known boot payloads, not fresh reads of the historical tape containers. Jumpman was also checked against its archived original ATR. In separate Atari800 runs, all four game XEX outputs reached an identifiable game screen and the built-in CAS example displayed colour bars. These are startup checks, **not** full playthroughs, save tests or physical A8PicoCart certification. Test a real supported device before claiming hardware verification. The project's synthetic colour-bar tape and disks can be freely shared for reproductions.
|
|
40
|
+
|
|
41
|
+
ATX checks in 0.2: all three commercial ATX inputs were converted locally. Booting only the new CARs under Atari800 5.2.0 (NTSC 800XL) reached the Cadet Mission after pressing START in The Tail of Beta Lyrae, Bruce Lee's title and first playfield, and Jumpman's Epyx title sequence. These are separate tests from booting the disks during conversion; later levels and physical hardware were not tested.
|
|
42
|
+
|
|
43
|
+
For a new release, inspect the actual loading path and what it does *after* startup. Confirm any extra reads, writes, bank switching and later stages; add a digest only after validating the conversion. Add a generated regression case for the new behavior. Test with no source media mounted, check an identifiable title/editor, and launch a game if possible. Record exactly which features, machine, OS and mapper were tested. Keep emulator screenshots of commercial games and all third-party media out of this repository.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "recarted"
|
|
3
|
+
version = "0.2.0"
|
|
4
|
+
description = "Turn recognized Atari 8-bit cassette and floppy images into A8PicoCart cartridges"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
requires-python = ">=3.11"
|
|
9
|
+
dependencies = ["cyclopts>=4,<5"]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"Environment :: Console",
|
|
12
|
+
"Operating System :: POSIX :: Linux",
|
|
13
|
+
"Topic :: System :: Emulators",
|
|
14
|
+
]
|
|
15
|
+
|
|
16
|
+
[[project.authors]]
|
|
17
|
+
name = "Christopher Patti"
|
|
18
|
+
|
|
19
|
+
[project.urls]
|
|
20
|
+
Homepage = "https://github.com/feoh/recarted"
|
|
21
|
+
Repository = "https://github.com/feoh/recarted"
|
|
22
|
+
Issues = "https://github.com/feoh/recarted/issues"
|
|
23
|
+
|
|
24
|
+
[project.scripts]
|
|
25
|
+
recarted = "recarted.cli:main"
|
|
26
|
+
|
|
27
|
+
[build-system]
|
|
28
|
+
requires = ["uv_build>=0.9,<0.12"]
|
|
29
|
+
build-backend = "uv_build"
|
|
30
|
+
|
|
31
|
+
[tool.uv.build-backend]
|
|
32
|
+
source-include = [
|
|
33
|
+
"asm/**",
|
|
34
|
+
"Makefile",
|
|
35
|
+
"docs/**",
|
|
36
|
+
"tests/**",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[tool.mypy]
|
|
40
|
+
strict = true
|
|
41
|
+
|
|
42
|
+
[tool.pytest.ini_options]
|
|
43
|
+
testpaths = ["tests"]
|
|
44
|
+
|
|
45
|
+
[dependency-groups]
|
|
46
|
+
dev = [
|
|
47
|
+
"mypy",
|
|
48
|
+
"prek",
|
|
49
|
+
"py65>=1.2.0",
|
|
50
|
+
"pytest",
|
|
51
|
+
"ruff",
|
|
52
|
+
]
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "recarted"
|
|
3
|
+
version = "0.2.0"
|
|
4
|
+
description = "Turn recognized Atari 8-bit cassette and floppy images into A8PicoCart cartridges"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{name = "Christopher Patti"}]
|
|
9
|
+
requires-python = ">=3.11"
|
|
10
|
+
dependencies = ["cyclopts>=4,<5"]
|
|
11
|
+
classifiers = ["Environment :: Console", "Operating System :: POSIX :: Linux", "Topic :: System :: Emulators"]
|
|
12
|
+
|
|
13
|
+
[project.urls]
|
|
14
|
+
Homepage = "https://github.com/feoh/recarted"
|
|
15
|
+
Repository = "https://github.com/feoh/recarted"
|
|
16
|
+
Issues = "https://github.com/feoh/recarted/issues"
|
|
17
|
+
|
|
18
|
+
[project.scripts]
|
|
19
|
+
recarted = "recarted.cli:main"
|
|
20
|
+
|
|
21
|
+
[build-system]
|
|
22
|
+
requires = ["uv_build>=0.9,<0.12"]
|
|
23
|
+
build-backend = "uv_build"
|
|
24
|
+
|
|
25
|
+
[tool.uv.build-backend]
|
|
26
|
+
source-include = ["asm/**", "Makefile", "docs/**", "tests/**"]
|
|
27
|
+
|
|
28
|
+
[dependency-groups]
|
|
29
|
+
dev = [
|
|
30
|
+
"mypy",
|
|
31
|
+
"prek",
|
|
32
|
+
"py65>=1.2.0",
|
|
33
|
+
"pytest",
|
|
34
|
+
"ruff",
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
[tool.mypy]
|
|
38
|
+
strict = true
|
|
39
|
+
|
|
40
|
+
[tool.pytest.ini_options]
|
|
41
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""ReCarted! Atari 8-bit image inspection and conversion."""
|