any ideas?

Given that the Chameleon uses flash memory, would it be possible to store save data directly on the cart instead of relying on a SaveKey?

Run make from the source directory with an env var to specify the location of the preferred emulator and tv setting.

ElfTemplate20251023\source> make EMU_PATH=../../../Gopher2600/gopher2600.exe

The bin folder will contain 3 files.

ElfTemplate-dbg.bin - Includes all the symbols needed for Gopher2600 to profile and debug the code.
ElfTemplate.bin - Optimized bin to be distributed to others for playing in emulators and on plus/uno cart.
ElfTemplateChameleon128KB.elf - Linked with Chameleon Cart firmware. Use this to program the Chameleon Cart.

arm-none-eabi-gcc and python3 are required.

When programming the Chameleon Cart the st-link should be connected to the adapter on pins SWCLK, SWDIO, and GND. I like to leave the board inserted into the console, and the st-link attached so I can simply flash the cart, power cycle, test, repeat. The 5V from st-link should never be connected when the board is in the console.

ElfTemplate20251023.zip

Note: If you're looking for PXE (the ELF-based batari Basic kernel) please see PXE Kernel Templates, Tutorials and Documentation.

ELF-VCS is a C-level API (defined in vcsLib.h) for developing Atari 2600 games that run on several flash cartridges (UnoCart, PlusCart, Chameleon Cart) as well as in popular emulators like Stella and Gopher2600.

Beyond simply running your game logic, the ELF-VCS runtime provides a set of helper features, including:

• Detecting NTSC vs PAL

• Detecting 2600 vs 7800 hardware

• Bus Stuffing support (see here)

• Reading/writing flash memory for high scores and save data

• A built-in byte-reverse lookup table (handy for PF0/PF2 use and for reflecting sprites in software)

• Indicating whether your game is running on a Multi-Cart or Chameleon Cart

You can write your ELF-VCS game entirely in C using the ARM GNU toolchain, or in Rust using the Rust toolchain. In fact, any language can be used, as long as the output is a partially linked ELF file containing relocatable machine code and unresolved references to the vcsLib library. The runtime environment then provides its own vcsLib implementation at load time. 

On some hardware, such as the Chameleon Cart (a retail-ready flash cart), the ELF is eventually fully linked against a vcsLib implementation that uses the SoC’s GPIOs, along with a small CRT and bootstrap code. This final linked binary is then flashed onto the cart.

For maximum compatibility, most ELF-VCS titles target the ARM Cortex-M0+, which is the CPU used in the Chameleon Cart. This core executes 16-bit Thumb-1 instructions (plus a small subset of Thumb-2), which are also supported by the UnoCart and PlusCart, making Cortex-M0+ the safest common target across all devices.

Follow the steps below to set up your environment and build your first C program using ELF-VCS:

1. Install the ARM GNU Toolchain

Download the Arm GNU Toolchain for your operating system:

👉 Arm GNU Toolchain Downloads → pick the arm-none-eabi version for your OS, which targets AArch32 bare-metal.

After installation, check to see if the toolchain binaries (e.g. arm-none-eabi-gcc) are available in your system’s PATH.

To test, run:

arm-none-eabi-gcc --version

2. Download the ELF-VCS Library Header

Download the latest vcsLib.h header file, which provides the interface for Atari ELF-VCS development.

Place it in the same directory where you’ll write your code.

3. Write Your First Program

Create a file named main.c and paste a simple example into it. For instance:

#include "vcsLib.h"

int elf_main(uint32_t* args)
{
	// Always reset PC first, cause it's going to be close to the end of the 6507 address space
	vcsJmp3();
	
	// Init TIA and RIOT RAM
	vcsLda2(0);
	for (int i = 0; i < 256; i++) {
		vcsSta3(i);
	}

	while (1)
	{
		// 3 lines of VSYNC
		vcsLda2(2);
		vcsSta3(VSYNC);
		for (int i = 0; i < 3; i++) {
			vcsSta3(WSYNC);
		}
		vcsLda2(0);
		vcsSta3(VSYNC);

		// 37 lines of VBLANK
		for (int i = 0; i < 37; i++) {
			vcsSta3(WSYNC);
		}
		vcsSta3(VBLANK); // disable blanking

		// 192 lines of COLUBK
		for (int i = 0; i < 192; i++) {
			vcsLdx2(i);
			vcsStx3(COLUBK);
			vcsJmp3();
			vcsSta3(WSYNC);
		}
	
		vcsWrite5(VBLANK, 2); // enter blanking

		// 30 lines of Overscan
		for (int i = 0; i < 30; i++) {
			vcsSta3(WSYNC);
		}
	}
}

4. Compile Your Program

Use the Arm GNU Toolchain to build the program into a .bin file:

arm-none-eabi-gcc -r -mlong-calls -fno-exceptions -march=armv6-m main.c -o main.bin -O3 -Wall -lgcc

If compilation succeeds, you’ll get main.bin, which is a playable ROM.

5. Run in an Emulator

Open main.bin in an Atari 2600/7800 emulator such as:

• Stella

• Gopher2600

Or load them into your UnoCart or PlusCart (note: you'll need to have a recent firmware installed on these carts).

6. Explore More Examples

To see more advanced programs, clone the ELF-VCS examples repository:

git clone https://github.com/dionoid/ELF-VCS-examples

This repo includes:

• Multiple example programs

• A DevContainer for Docker Desktop, preconfigured with the ARM GNU Toolchain.
  → This means you can build projects without installing the toolchain locally.

✅ You’re ready to start making Atari 2600/7800 homebrew with ELF-VCS!

Since the board has exposed SMCs, it can get damaged if something drops onto it. To prevent that, I reused a standard cartridge shell (one of the later types with holes under the front label) and modified it to fit the PXE adapter.

Using a Dremel, I cut a small square opening in the side of the shell so the adapter can plug in cleanly while keeping the rest of the cart protected.

It's a simple mod, but it gives the cart a much sturdier feel when inserting into my 2600 and adds peace of mind during storage.

Here are a couple of pictures showing the result:

Hopefully this helps others who want to keep their dev kits safe

I’m now looking for a good label design to finish it off, probably something inspired by the rainbow-striped Chameleon Cart logo (see below). I think that style would fit perfectly on this shell. Maybe @8bitPoet has some ideas or suggestions? 

I'd like to start a discussion about adding networking to Atari 2600 ELF games using the PlusCart’s WiFi. Currently the ELF format support (via UCA firmware) only provides basic functions (VCSLib) for running on hardware. I'm wondering if we could also tap into the PlusCart's ESP8266 library (esp8266.h/.c in the firmware) to give ELF games online features.

The goal is to provide ELF game developers with easy network APIs (highscores, online modes, etc.), similar to PlusROM functions.

At first this would only work on real PlusCart hardware, but emulators like Stella and Gopher2600 already emulate PlusROM, so they should be able to handle these calls too

The current esp8266 library was designed mostly for the PlusStore communication, but I believe it can be generalized. I'd love to hear thoughts or advice: Has anyone tried hooking network routines into ELF before? Do you think we can simply reuse the existing ESP8266 lib, or are there pitfalls I'm missing? Any feedback or suggestions would be greatly appreciated!

Thanks, and looking forward to the discussion.

The resulting binary runs in Stella, but I’m not sure if this is the best way to set up a Rust build for ELF-VCS.

I’d love to hear if anyone has suggestions for improvements or more idiomatic approaches.

Here’s the command I used to build:

rustc --target=thumbv6m-none-eabi \
   -C panic=abort \
   -C opt-level=3 \
   -C relocation-model=pic \
   -C target-feature=+long-calls \
   -C link-arg=-r \
   -C link-arg=-u \
   -C link-arg=elf_main \
   -C link-arg=--discard-all \
   --emit=link \
   main.rs -o main.bin