Created a target and a library for the Commander X16 prototype computer.
This commit is contained in:
Greg King
311
doc/cx16.sgml
Normal file
311
doc/cx16.sgml
Normal file
@@ -0,0 +1,311 @@
|
||||
<!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 on
|
||||
the ROMs in Commodore's VIC-20 and 64C. It has a couple of the I/O chips that
|
||||
are in the VIC-20.
|
||||
|
||||
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 are
|
||||
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 with 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 start-up file and linker config.
|
||||
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65-generated programs with the default setup run with the I/O area and the
|
||||
Kernal ROM visible. That means that Kernal entry points can be called directly.
|
||||
The usable memory ranges are $0800 - $9EFF 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 Mibibyte or two Mibibytes 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>/.
|
||||
|
||||
|
||||
<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>waitvsync()
|
||||
</itemize>
|
||||
|
||||
|
||||
<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_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()
|
||||
</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/VERA/</tag>
|
||||
The <tt/VERA/ structure allows access
|
||||
to the Video Enhanced Retro Adapter chip.
|
||||
|
||||
<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/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.
|
||||
|
||||
|
||||
<sect1>Graphics drivers<p>
|
||||
|
||||
No graphics drivers are available currently for the CX16.
|
||||
|
||||
|
||||
<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-stdjoy.joy (cx16_stdjoy_joy)/.
|
||||
|
||||
<descrip>
|
||||
<tag><tt/cX16-stdjoy.joy (cX16_stdjoy_joy)/</tag>
|
||||
Supports up to two NES and SNES controllers connected to the joystick ports
|
||||
of the CX16. It reads the four directions, and the A, B, Select, and Start
|
||||
buttons. Button A is the primary fire button.
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are available currently for the CX16.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
No serial drivers are available currently for the CX16.
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
The Commander X16 still is being designed. It's configuration can change at
|
||||
any time. Some changes could make old programs fail to work.
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
|
||||
<sect1>Escape code<p>
|
||||
|
||||
For an Esc, press <tt/Ctrl/ and the <tt/[/ key.
|
||||
|
||||
|
||||
<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 use of the
|
||||
<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>
|
||||
Reference in New Issue
Block a user