cc65/doc/cx16.sgml

<!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 &dollar;0800 - &dollar;9EFF and &dollar;A000 -
&dollar;BFFF.

Special locations:

<descrip>
  <tag/Stack/
  The C run-time stack is located at &dollar;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 &dollar;A000 - &dollar;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 &dollar;C000 - &dollar;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 &lt;configfile&gt;/.


<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 &dollar;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 &dollar;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 &dollar;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>