mirror of
https://github.com/cc65/cc65.git
synced 2024-08-16 12:29:03 +00:00
365 lines
11 KiB
Plaintext
365 lines
11 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
<title>Commander X16-specific information for cc65
|
|
<author><url url="mailto:greg.king5@verizon.net" name="Greg King">
|
|
|
|
<abstract>
|
|
An overview over the CX16 run-time system as it's implemented for the cc65 C
|
|
compiler.
|
|
</abstract>
|
|
|
|
<!-- Table of contents -->
|
|
<toc>
|
|
|
|
<!-- Begin the document -->
|
|
|
|
<sect>Overview<p>
|
|
|
|
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 <url url="funcref.html" name="function
|
|
reference">. Even functions marked as "platform dependent" may be available on
|
|
more than one platform. Please see the function reference for more
|
|
information.
|
|
|
|
|
|
|
|
<sect>Binary format<p>
|
|
|
|
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.
|
|
|
|
|
|
|
|
<sect>Memory layout<p>
|
|
|
|
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:
|
|
|
|
<descrip>
|
|
<tag/Stack/
|
|
The C run-time stack is located at $9EFF, and grows downward.
|
|
|
|
<tag/Heap/
|
|
The C heap is located at the end of the program, and grows toward the C
|
|
run-time stack.
|
|
|
|
<tag/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.
|
|
|
|
<tag/Bank ROM/
|
|
Bank ROM is located at $C000 - $FFFF. It's a sixteen-Kibibyte
|
|
window into 128 Kibibytes of banked ROM.
|
|
</descrip><p>
|
|
|
|
|
|
|
|
<sect>Linker configurations<p>
|
|
|
|
The ld65 linker comes with a default config. file for the Commander X16, which
|
|
is used via <tt/-t cx16/. The cx16 package comes with additional secondary
|
|
linker config. files which are used via <tt/-t cx16 -C <configfile>/.
|
|
|
|
Those files use 94 bytes in the zero page. (The rest of page zero is reserved
|
|
for Kernal and BASIC.)
|
|
|
|
|
|
<sect1>Default config. file (<tt/cx16.cfg/)<p>
|
|
|
|
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.
|
|
|
|
|
|
<sect1><tt/cx16-asm.cfg/<p>
|
|
|
|
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 <tt/--start-addr/ or <tt/-S/. All standard segments,
|
|
with the exception of <tt/ZEROPAGE/, are written to the output file;
|
|
and, a two-byte load address is prepended.
|
|
|
|
To use that config. file, assemble with <tt/-t cx16/, and link with <tt/-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 <tt/cl65/, use both command-line options.
|
|
|
|
Sample command line for <tt/cl65/:
|
|
<tscreen><verb>
|
|
cl65 -o file.prg -t cx16 -C cx16-asm.cfg source.s
|
|
</verb></tscreen>
|
|
|
|
To generate code that loads to $A000:
|
|
<tscreen><verb>
|
|
cl65 -o file.prg -Wl -S,$A000 -t cx16 -C cx16-asm.cfg source.s
|
|
</verb></tscreen>
|
|
|
|
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
|
|
<tscreen><verb>
|
|
cl65 -o file.prg -u __EXEHDR__ -t cx16 -C cx16-asm.cfg source.s
|
|
</verb></tscreen>
|
|
|
|
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.
|
|
|
|
|
|
|
|
<sect>Platform-specific header files<p>
|
|
|
|
Programs containing CX16-specific code may use the <tt/cx16.h/ or <tt/cbm.h/
|
|
header files. Using the later may be an option when writing code for more than
|
|
one CBM-like platform, because it includes <tt/cx16.h/, and declares several
|
|
functions common to all CBM-like platforms.
|
|
|
|
|
|
<sect1>CX16-specific functions<p>
|
|
|
|
The functions listed below are special for the CX16. See the <url
|
|
url="funcref.html" name="function reference"> for declarations and usage.
|
|
|
|
<itemize>
|
|
<item>get_ostype()
|
|
<item>set_tv()
|
|
<item>videomode()
|
|
<item>vpeek()
|
|
<item>vpoke()
|
|
</itemize>
|
|
|
|
<tt/cpeekcolor()/ works differently on the Commander X16 than it does on other
|
|
platforms. Each character has two colors: background and text (foreground).
|
|
<tt/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.
|
|
|
|
|
|
<sect1>CBM-specific functions<p>
|
|
|
|
Some functions are available for all (or, at least most) of the Commodore-like
|
|
machines. See the <url url="funcref.html" name="function reference"> for
|
|
declarations and usage.
|
|
|
|
<itemize>
|
|
<item>cbm_close()
|
|
<item>cbm_closedir()
|
|
<item>cbm_k_basin()
|
|
<item>cbm_k_bsout()
|
|
<item>cbm_k_chkin()
|
|
<item>cbm_k_ckout()
|
|
<item>cbm_k_close()
|
|
<item>cbm_k_clrch()
|
|
<item>cbm_k_getin()
|
|
<item>cbm_k_load()
|
|
<item>cbm_k_open()
|
|
<item>cbm_k_readst()
|
|
<item>cbm_k_save()
|
|
<item>cbm_k_second()
|
|
<item>cbm_k_setlfs()
|
|
<item>cbm_k_setnam()
|
|
<item>cbm_k_tksa()
|
|
<item>cbm_load()
|
|
<item>cbm_open()
|
|
<item>cbm_opendir()
|
|
<item>cbm_read()
|
|
<item>cbm_readdir()
|
|
<item>cbm_save()
|
|
<item>cbm_write()
|
|
<item>get_tv()
|
|
<item>waitvsync()
|
|
</itemize>
|
|
|
|
|
|
<sect1>Hardware access<p>
|
|
|
|
The following pseudo variables declared in the <tt/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.
|
|
|
|
<descrip>
|
|
|
|
<tag><tt/RAM_BANK/</tag>
|
|
A register that controls which bank of high RAM is visible in the
|
|
<tt/BANK_RAM/ window.
|
|
|
|
<tag><tt/ROM_BANK/</tag>
|
|
A register that controls which bank of ROM is active at the moment.
|
|
|
|
<tag><tt/VIA1, VIA2/</tag>
|
|
Access to the two VIA (Versatile Interface Adapter) chips is available via
|
|
the <tt/VIA1/ and <tt/VIA2/ variables. The structure behind those variables
|
|
is explained in <tt/_6522.h/.
|
|
|
|
<tag><tt/VERA/</tag>
|
|
The <tt/VERA/ structure allows access
|
|
to the Video Enhanced Retro Adapter chip.
|
|
|
|
<tag><tt/BANK_RAM/</tag>
|
|
A character array that mirrors the eight-Kibibyte window, at $A000,
|
|
into banked RAM.
|
|
</descrip><p>
|
|
|
|
|
|
|
|
<sect>Loadable drivers<p>
|
|
|
|
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.
|
|
|
|
|
|
<sect1>Graphics drivers<p>
|
|
|
|
The default drivers, <tt/tgi_stddrv (tgi_static_stddrv)/,
|
|
point to <tt/cx320p1.tgi (cx320p1_tgi)/.
|
|
|
|
<descrip>
|
|
<tag><tt/cx320p1.tgi (cx320p1_tgi)/</tag>
|
|
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).
|
|
</descrip><p>
|
|
|
|
|
|
<sect1>Extended memory drivers<p>
|
|
|
|
No extended memory drivers are available currently for the CX16.
|
|
|
|
|
|
<sect1>Joystick drivers<p>
|
|
|
|
The default drivers, <tt/joy_stddrv (joy_static_stddrv)/,
|
|
point to <tt/cx16-std.joy (cx16_std_joy)/.
|
|
|
|
<descrip>
|
|
<tag><tt/cx16-std.joy (cx16_std_joy)/</tag>
|
|
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 <bf/A/, <bf/B/, <bf/Select/, and <bf/Start/ buttons.
|
|
Buttons <bf/A/ and <bf/B/ are the first and second fire buttons.
|
|
</descrip><p>
|
|
|
|
|
|
<sect1>Mouse drivers<p>
|
|
|
|
The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/,
|
|
point to <tt/cx16-std.mou (cx16_std_mou)/.
|
|
|
|
<descrip>
|
|
<tag><tt/cx16-std.mou (cx16_std_mou)/</tag>
|
|
Supports a standard 3-button mouse connected to the PS/2 mouse port of the
|
|
Commander X16.
|
|
|
|
Currently, this driver doesn't support <tt/mouse_move()/ and
|
|
<tt/mouse_setbox()/.
|
|
</descrip><p>
|
|
|
|
|
|
<sect1>RS232 device drivers<p>
|
|
|
|
No serial drivers are available currently for the CX16.
|
|
|
|
|
|
|
|
<sect>Limitations<p>
|
|
|
|
The Commander X16 still is being designed. Its configuration can change at
|
|
any time. Some changes could make old programs fail to work.
|
|
|
|
|
|
|
|
<sect>Other hints<p>
|
|
|
|
|
|
<sect1>STOP and RUN codes<p>
|
|
|
|
The <tt/Esc/ key acts as Commodore's <tt/STOP/ key -- or, you can press the
|
|
<tt/Ctrl/ key and the <tt/C/ key together. Pressing the <tt/Shift/ and the
|
|
<tt/Esc/ keys together will type Commodore's <tt/RUN/ key.
|
|
|
|
|
|
<sect1>Escape code<p>
|
|
|
|
For an <tt/Esc/, press the <tt/Ctrl/ key and the <tt/[/ key together.
|
|
|
|
|
|
<sect1>Passing arguments to the program<p>
|
|
|
|
Command-line arguments can be passed to <tt/main()/. Because that is not
|
|
supported directly by BASIC, the following syntax was chosen:
|
|
<tscreen><verb>
|
|
RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
|
|
</verb></tscreen>
|
|
|
|
<enum>
|
|
<item>Arguments are separated by spaces.
|
|
<item>Arguments may be quoted.
|
|
<item>Leading and trailing spaces around an argument are ignored. Spaces within
|
|
a quoted argument are allowed.
|
|
<item>The first argument passed to <tt/main()/ is the program name.
|
|
<item>A maximum number of 10 arguments (including the program name) are
|
|
supported.
|
|
</enum>
|
|
|
|
|
|
<sect1>Program return code<p>
|
|
|
|
The program return code (low byte) is passed back to BASIC by the use of its
|
|
<tt/ST/ variable.
|
|
|
|
|
|
<sect1>Interrupts<p>
|
|
|
|
The run-time for the CX16 uses routines marked as <tt/.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 <tt/.CONDES/
|
|
feature in the <url url="ca65.html" name="assembler manual">.
|
|
|
|
|
|
|
|
<sect>License<p>
|
|
|
|
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:
|
|
<enum>
|
|
<item> 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.
|
|
<item> Altered source versions must be plainly marked as such, and must not
|
|
be misrepresented as being the original software.
|
|
<item> This notice may not be removed or altered from any source
|
|
distribution.
|
|
</enum>
|
|
|
|
</article>
|