Commander X16-specific information for cc65

Greg King


An overview over the CX16 run-time system as it's implemented for the cc65 C compiler.

1. Overview

2. Binary format

3. Memory layout

4. Linker configurations

5. Platform-specific header files

6. Loadable drivers

7. Limitations

8. Other hints

9. License


1. Overview

The Commander X16 is a modern small computer with firmware that is based partly on the ROMs in Commodore's VIC-20 and 64C. It has a couple of I/O chips (WDC65C22 VIA) that are like the ones in the VIC-20. It supports file storage on Secure Digital cards. It allows two joysticks and a mouse. It has three sound devices. Its VGA screen has twice the range of the C64 (similar to the C128's 80-column screen), with 256 colors.

This file contains an overview of the CX16 run-time system as it comes with the cc65 C compiler. It describes the memory layout, CX16-specific header files, available drivers, and any pitfalls specific to that platform.

Please note that CX16-specific functions just are mentioned here; they might be described in detail in the separate function reference. Even functions marked as "platform dependent" may be available on more than one platform. Please see the function reference for more information.

2. Binary format

The standard binary output format generated by the linker for the CX16 target is a machine language program that's prepended with a 16-bit load address and a one-line BASIC stub which calls the machine language part via SYS. That means that a program can be loaded as a BASIC program, and started with RUN. It is, of course, possible to change that behaviour by using a modified program-header file and linker config.

3. Memory layout

cc65-generated programs with the default setup run with the I/O area, RAM bank one, and the Kernal ROM being visible. That means that Kernal entry points can be called directly. The usable memory ranges are $0800 - $9EFF, $0400 - $07FF, and $A000 - $BFFF.

Special locations:

Stack

The C run-time stack is located at $9EFF, and grows downward.

Heap

The C heap is located at the end of the program, and grows toward the C run-time stack.

Bank RAM

Bank RAM is located at $A000 - $BFFF. It's an eight-Kibibyte window into a half Mebibyte or two Mebibytes of banked RAM.

Bank ROM

Bank ROM is located at $C000 - $FFFF. It's a sixteen-Kibibyte window into 128 Kibibytes of banked ROM.

4. Linker configurations

The ld65 linker comes with a default config. file for the Commander X16, which is used via -t cx16. The cx16 package comes with additional secondary linker config. files which are used via -t cx16 -C <configfile>.

Those files use 94 bytes in the zero page. (The rest of page zero is reserved for Kernal and BASIC.)

4.1 Default config. file (cx16.cfg)

The default configuration is tailored to C programs. It supplies the load address and a small BASIC stub that starts the compiled program using a SYS command.

4.2 cx16-asm.cfg

This configuration is made for Assembly programmers who don't need a special setup. The default start address is $0801. It can be changed with the linker command-line option --start-addr or -S. All standard segments, with the exception of ZEROPAGE, are written to the output file; and, a two-byte load address is prepended.

To use that config. file, assemble with -t cx16, and link with -C cx16-asm.cfg. The former will make sure that the correct character translations are in effect, while the latter supplies the actual config. When using cl65, use both command-line options.

Sample command line for cl65:

cl65 -o file.prg -t cx16 -C cx16-asm.cfg source.s

To generate code that loads to $A000:

cl65 -o file.prg -Wl -S,$A000 -t cx16 -C cx16-asm.cfg source.s

It also is possible to add a small BASIC header to the program, that uses SYS to jump to the program entry point (which is the start of the code segment). The advantage is that the program can be started using RUN.

To generate a program with a BASIC SYS header, use

cl65 -o file.prg -u __EXEHDR__ -t cx16 -C cx16-asm.cfg source.s

Please note that, in this case, a changed start address doesn't make sense, because the program must be loaded to BASIC's start address.

5. Platform-specific header files

Programs containing CX16-specific code may use the cx16.h or cbm.h header files. Using the later may be an option when writing code for more than one CBM-like platform, because it includes cx16.h, and declares several functions common to all CBM-like platforms.

5.1 CX16-specific functions

The functions listed below are special for the CX16. See the function reference for declarations and usage.

cpeekcolor() works differently on the Commander X16 than it does on other platforms. Each character has two colors: background and text (foreground). cpeekcolor() returns both colors. The high nybble describes the background color, the low nybble describes the text color. For example, if the function is used on the default screen, then it returns $61, which means white-on-blue.

5.2 CBM-specific functions

Some functions are available for all (or, at least most) of the Commodore-like machines. See the function reference for declarations and usage.

5.3 Hardware access

The following pseudo variables declared in the cx16.h header file do allow access to hardware located in the address space. Some variables are structures, accessing the struct fields will access the chip registers.

RAM_BANK

A register that controls which bank of high RAM is visible in the BANK_RAM window.

ROM_BANK

A register that controls which bank of ROM is active at the moment.

VIA1, VIA2

Access to the two VIA (Versatile Interface Adapter) chips is available via the VIA1 and VIA2 variables. The structure behind those variables is explained in _6522.h.

VERA

The VERA structure allows access to the Video Enhanced Retro Adapter chip.

BANK_RAM

A character array that mirrors the eight-Kibibyte window, at $A000, into banked RAM.

6. Loadable drivers

The names in the parentheses denote the symbols to be used for static linking of the drivers. The names fit into the old 8.3-character limit of the SD-Card's FAT32 file-system.

6.1 Graphics drivers

The default drivers, tgi_stddrv (tgi_static_stddrv), point to cx320p1.tgi (cx320p1_tgi).

cx320p1.tgi (cx320p1_tgi)

This driver features a resolution of 320 across and 240 down with 256 colors, and a slightly adjustable palette (the order of the colors can be changed in a way that's compatible with some of the other color drivers).

cx640p1.tgi (cx640p1_tgi)

This driver features a resolution of 640 across and 480 down with 2 colors, black and white.

6.2 Extended memory drivers

No extended memory drivers are available currently for the CX16.

6.3 Joystick drivers

The default drivers, joy_stddrv (joy_static_stddrv), point to cx16-std.joy (cx16_std_joy).

cx16-std.joy (cx16_std_joy)

Supports the keyboard emulation of a controller and up to four SNES (and NES) controllers connected to the joystick ports of the CX16. It reads the four directions, and the A, B, Select, and Start buttons. Buttons A and B are the first and second fire buttons.

6.4 Mouse drivers

The default drivers, mouse_stddrv (mouse_static_stddrv), point to cx16-std.mou (cx16_std_mou).

cx16-std.mou (cx16_std_mou)

Supports a standard 3-button mouse connected to the PS/2 mouse port of the Commander X16.

Currently, this driver doesn't support mouse_move() and mouse_setbox().

6.5 RS232 device drivers

No serial drivers are available currently for the CX16.

7. Limitations

The Commander X16 still is being designed. Its configuration can change at any time. Some changes could make old programs fail to work.

8. Other hints

8.1 STOP and RUN codes

The Esc key acts as Commodore's STOP key -- or, you can press the Ctrl key and the C key together. Pressing the Shift and the Esc keys together will type Commodore's RUN key.

8.2 Escape code

For an Esc, press the Ctrl key and the [ key together.

8.3 Passing arguments to the program

Command-line arguments can be passed to main(). Because that is not supported directly by BASIC, the following syntax was chosen:

    RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5

  1. Arguments are separated by spaces.
  2. Arguments may be quoted.
  3. Leading and trailing spaces around an argument are ignored. Spaces within a quoted argument are allowed.
  4. The first argument passed to main() is the program name.
  5. A maximum number of 10 arguments (including the program name) are supported.

8.4 Program return code

The program return code (low byte) is passed back to BASIC by the use of its ST variable.

8.5 Interrupts

The run-time for the CX16 uses routines marked as .INTERRUPTOR for interrupt handlers. Such routines must be written as simple machine language subroutines, and will be called automatically by the interrupt handler code if they are linked into a program. See the discussion of the .CONDES feature in the assembler manual.

9. License

This software is provided "as-is", without any expressed or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated, but is not required.
  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.