How to Enter Direct Machine Code on the Commodore VIC-20

The Commodore VIC-20 lacks a built-in machine language monitor, so users must rely on BASIC commands or external cartridges to input binary data. This article details the specific steps for entering opcode bytes directly into RAM using immediate mode POKE statements, explains how to calculate memory addresses, and describes the SYS command required to execute the newly entered code safely.

Understanding VIC-20 Memory Layout

To enter machine code effectively, you must know where free RAM is located. On an unexpanded VIC-20, BASIC RAM starts at decimal address 4096. However, the BASIC interpreter itself occupies the lower end of this space. For small machine language routines, it is safest to use the area just above the BASIC program storage or specific reserved areas if you are not running a BASIC program simultaneously. Overwriting the wrong memory section can cause the computer to freeze or crash, requiring a power cycle.

Using POKE Commands in Immediate Mode

The most accessible method for direct entry without additional hardware is using the BASIC POKE command. You can type these commands directly into the command line without line numbers. The syntax is POKE address, value, where both the address and the value must be in decimal format. If you have hexadecimal machine code from a magazine listing, you must convert each byte to decimal before typing. For example, to place the opcode 169 (LDA Immediate) into address 4096, you would type POKE 4096,169 and press Return.

Executing the Machine Code

Once the bytes are stored in memory, you cannot run them like a BASIC program. Instead, you must use the SYS command followed by the decimal starting address of your machine code. Continuing the previous example, if your code starts at address 4096, you would type SYS 4096 and press Return. The processor will jump to that memory location and begin executing the binary instructions immediately. If the code contains an RTS (Return from Subroutine) instruction at the end, control will return to BASIC; otherwise, the system may hang.

Utilizing Machine Code Monitors

For more complex projects, typing individual POKE commands is inefficient. Many users utilized cartridge-based machine code monitors, such as the VIC Monitor cartridge. These tools provide a dedicated interface for entering hexadecimal code directly, viewing memory dumps, and disassembling code. When using a monitor, you typically select a start address and type the hexadecimal bytes sequentially, which eliminates the need for manual decimal conversion and reduces the risk of input errors.

Safety Precautions and Best Practices

Direct machine code entry carries risks because there is no memory protection on the VIC-20. Avoid writing data above address 7680 unless you understand the screen memory map, and never write to addresses above 32767 where the Kernal ROM resides. It is recommended to save your BASIC loader program to tape or disk after typing it in, rather than relying on direct immediate mode entry for permanent storage. Always ensure your machine code routine ends properly to return control to the operating system.