mirror of
https://github.com/cc65/cc65.git
synced 2025-01-10 19:29:45 +00:00
Merge remote-tracking branch 'upstream/master' into cassette
This commit is contained in:
Christian Groessler
commit
290da8d5ae
1
.gitignore
vendored
1
.gitignore
vendored
@ -1,5 +1,6 @@
|
||||
/bin/
|
||||
/emd/
|
||||
/html/
|
||||
/joy/
|
||||
/lib/
|
||||
/mou/
|
||||
|
||||
12
.travis.yml
12
.travis.yml
@ -1,2 +1,10 @@
|
||||
language: c
|
||||
script: make
|
||||
language:
|
||||
- c
|
||||
install:
|
||||
- sudo apt-get install linuxdoc-tools
|
||||
script:
|
||||
- make
|
||||
- make -C doc gh-pages
|
||||
env:
|
||||
global:
|
||||
- secure: "h+hoQdEHGPLNwaqGKmSaM8NBRDLc2X+W05VsnNG2Feq/wPv/AiBjONNlzN7jRf6D6f3aoPXaQ2Lc3bYWdxGvFRCmwiofdxkJI9n5L8HPHLZ2lf37MQsXmGJzoTFOvjPLj73H6HlbI9Ux0El3zO6hvalxiXj6TfoZ41dbhNyvpYk="
|
||||
|
||||
12
Makefile
12
Makefile
@ -1,6 +1,11 @@
|
||||
.PHONY: all mostlyclean clean install avail unavail bin lib doc
|
||||
|
||||
.SUFFIXES:
|
||||
|
||||
all mostlyclean clean install:
|
||||
@$(MAKE) -C src --no-print-directory $@
|
||||
@$(MAKE) -C libsrc --no-print-directory $@
|
||||
@$(MAKE) -C doc --no-print-directory $@
|
||||
|
||||
avail unavail bin:
|
||||
@$(MAKE) -C src --no-print-directory $@
|
||||
@ -8,12 +13,11 @@ avail unavail bin:
|
||||
lib:
|
||||
@$(MAKE) -C libsrc --no-print-directory $@
|
||||
|
||||
doc:
|
||||
@$(MAKE) -C doc --no-print-directory $@
|
||||
|
||||
%65:
|
||||
@$(MAKE) -C src --no-print-directory $@
|
||||
|
||||
%:
|
||||
@$(MAKE) -C libsrc --no-print-directory $@
|
||||
|
||||
.PHONY: all mostlyclean clean install avail unavail bin lib
|
||||
|
||||
.SUFFIXES:
|
||||
|
||||
32
README
32
README
@ -1,32 +0,0 @@
|
||||
cc65 is a complete cross development package for 65(C)02 systems, including
|
||||
a powerful macro assembler, a C compiler, linker, librarian and several
|
||||
other tools.
|
||||
|
||||
cc65 has C and runtime library support for many of the old 6502 machines,
|
||||
including
|
||||
|
||||
- the following Commodore machines:
|
||||
VIC20
|
||||
C16/C116 and Plus/4
|
||||
C64
|
||||
C128
|
||||
CBM 510 (aka P500)
|
||||
the 600/700 family
|
||||
newer PET machines (not 2001).
|
||||
|
||||
- the Apple ][+ and successors.
|
||||
|
||||
- the Atari 8 bit machines.
|
||||
|
||||
- GEOS for the C64 and C128.
|
||||
|
||||
- the Nintendo Entertainment System (NES).
|
||||
|
||||
- the Supervision console.
|
||||
|
||||
- the Oric Atmos.
|
||||
|
||||
- the Lynx console.
|
||||
|
||||
The libraries are fairly portable, so creating a version for other 6502s
|
||||
shouldn't be too much work.
|
||||
29
README.md
Normal file
29
README.md
Normal file
@ -0,0 +1,29 @@
|
||||
[documentation](http://oliverschmidt.github.io/cc65/doc)
|
||||
|
||||
[](https://travis-ci.org/oliverschmidt/cc65/builds)
|
||||
|
||||
cc65 is a complete cross development package for 65(C)02 systems, including
|
||||
a powerful macro assembler, a C compiler, linker, librarian and several
|
||||
other tools.
|
||||
|
||||
cc65 has C and runtime library support for many of the old 6502 machines,
|
||||
including
|
||||
|
||||
- the following Commodore machines:
|
||||
- VIC20
|
||||
- C16/C116 and Plus/4
|
||||
- C64
|
||||
- C128
|
||||
- CBM 510 (aka P500)
|
||||
- the 600/700 family
|
||||
- newer PET machines (not 2001).
|
||||
- the Apple ][+ and successors.
|
||||
- the Atari 8 bit machines.
|
||||
- GEOS for the C64 and C128.
|
||||
- the Nintendo Entertainment System (NES).
|
||||
- the Supervision console.
|
||||
- the Oric Atmos.
|
||||
- the Lynx console.
|
||||
|
||||
The libraries are fairly portable, so creating a version for other 6502s
|
||||
shouldn't be too much work.
|
||||
@ -1,4 +1,3 @@
|
||||
|
||||
; CPU bitmask constants
|
||||
CPU_ISET_NONE = $0001
|
||||
CPU_ISET_6502 = $0002
|
||||
@ -6,9 +5,8 @@ CPU_ISET_6502X = $0004
|
||||
CPU_ISET_65SC02 = $0008
|
||||
CPU_ISET_65C02 = $0010
|
||||
CPU_ISET_65816 = $0020
|
||||
CPU_ISET_SUNPLUS = $0040
|
||||
CPU_ISET_SWEET16 = $0080
|
||||
CPU_ISET_HUC6280 = $0100
|
||||
CPU_ISET_SWEET16 = $0040
|
||||
CPU_ISET_HUC6280 = $0080
|
||||
|
||||
; CPU capabilities
|
||||
CPU_NONE = CPU_ISET_NONE
|
||||
@ -17,8 +15,5 @@ CPU_6502X = CPU_ISET_6502|CPU_ISET_6502X
|
||||
CPU_65SC02 = CPU_ISET_6502|CPU_ISET_65SC02
|
||||
CPU_65C02 = CPU_ISET_6502|CPU_ISET_65SC02|CPU_ISET_65C02
|
||||
CPU_65816 = CPU_ISET_6502|CPU_ISET_65SC02|CPU_ISET_65816
|
||||
CPU_SUNPLUS = CPU_ISET_SUNPLUS
|
||||
CPU_SWEET16 = CPU_ISET_SWEET16
|
||||
CPU_HUC6280 = CPU_ISET_6502|CPU_ISET_65SC02|CPU_ISET_65C02|CPU_ISET_HUC6280
|
||||
|
||||
|
||||
|
||||
54
doc/Makefile
Normal file
54
doc/Makefile
Normal file
@ -0,0 +1,54 @@
|
||||
.PHONY: all doc html gh-pages mostlyclean clean install
|
||||
|
||||
.SUFFIXES:
|
||||
|
||||
ifeq ($(shell echo),)
|
||||
|
||||
SGMLS := $(wildcard *.sgml)
|
||||
|
||||
../html/coding.html ../html/index.html: \
|
||||
TOC_LEVEL = 0
|
||||
|
||||
TOC_LEVEL = 2
|
||||
|
||||
GH_PAGES = ../../gh-pages
|
||||
|
||||
all:
|
||||
|
||||
doc: html
|
||||
|
||||
html: $(addprefix ../html/,$(SGMLS:.sgml=.html) doc.css doc.png)
|
||||
|
||||
mostlyclean:
|
||||
|
||||
clean:
|
||||
$(RM) -r ../html
|
||||
|
||||
../html:
|
||||
@mkdir $@
|
||||
|
||||
../html/%.html: %.sgml header.html | ../html
|
||||
@cd ../html && linuxdoc -B html -s 0 -T $(TOC_LEVEL) -H ../doc/header.html ../doc/$<
|
||||
|
||||
../html/doc.%: doc.% | ../html
|
||||
cp $< ../html
|
||||
|
||||
gh-pages: html
|
||||
ifdef GH_TOKEN
|
||||
git clone --branch=gh-pages https://$(GH_TOKEN)@github.com/oliverschmidt/cc65.git $(GH_PAGES)
|
||||
git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.name "Oliver Schmidt"
|
||||
git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.email "ol.sc@web.de"
|
||||
git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config push.default simple
|
||||
$(RM) -r $(GH_PAGES)/doc
|
||||
mkdir $(GH_PAGES)/doc
|
||||
cp ../html/* $(GH_PAGES)/doc
|
||||
git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A doc
|
||||
-git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)."
|
||||
git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push
|
||||
endif
|
||||
|
||||
else # cmd.exe
|
||||
|
||||
all doc mostlyclean clean install:
|
||||
|
||||
endif # cmd.exe
|
||||
532
doc/apple2.sgml
Normal file
532
doc/apple2.sgml
Normal file
@ -0,0 +1,532 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Apple ][ specific information for cc65
|
||||
<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de">
|
||||
<date>2009-10-07
|
||||
|
||||
<abstract>
|
||||
An overview over the Apple ][ runtime system as it is
|
||||
implemented for the cc65 C compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the Apple ][ runtime system
|
||||
as it comes with the cc65 C compiler. It describes the memory layout,
|
||||
Apple ][ specific header files, available drivers, and any
|
||||
pitfalls specific to that platform.
|
||||
|
||||
Please note that Apple ][ specific functions are just mentioned
|
||||
here, they are described in detail in the separate <htmlurl 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 file format generated by the linker for the
|
||||
Apple ][ target is a binary program with a 4 byte DOS 3.3 header
|
||||
containing the load address and load length. The default load address is
|
||||
$803.
|
||||
|
||||
<bf/AppleCommander 1.3.5/ or later (available at <url
|
||||
url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/
|
||||
that allows to put binary files with a DOS 3.3 header onto disk images
|
||||
containing DOS 3.3 as well as ProDOS 8.
|
||||
|
||||
For ProDOS 8 system programs the load address is fixed to $2000 so there
|
||||
is no need for a header. Thus the linker configuration
|
||||
<htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> for those programs
|
||||
omits the DOS 3.3 header. The right AppleCommander option to put system files
|
||||
without a header on a ProDOS 8 disk image is <tt/-p/.
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
In the standard setup, cc65 generated programs use the memory from
|
||||
$803 to $95FF, so 35.5 KB of RAM are available.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at HIMEM and grows downwards, regardless of
|
||||
how your linker config file is setup.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
While running <tt/main()/ the Language Card bank 2 is enabled for read access.
|
||||
However while running module constructors/destructors the Language Card is disabled.
|
||||
|
||||
Enabling the Language Card allows to use it as additional memory for cc65
|
||||
generated code. However code is never automatically placed there. Rather code
|
||||
needs to be explicitly placed in the Language Card either per file by compiling
|
||||
with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma
|
||||
code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the
|
||||
cc65 runtime system takes care of actually moving the code into the Language
|
||||
Card.
|
||||
|
||||
The amount of memory available in the Language Card for generated code depends
|
||||
on the chosen <htmlurl url="apple2-4.html" name="linker configuration">.
|
||||
|
||||
|
||||
|
||||
<sect>Linker configurations<p>
|
||||
|
||||
The ld65 linker comes with a default config file for the Apple ][,
|
||||
which is used via <tt/-t apple2/.
|
||||
The apple2 package comes with additional secondary linker config files, which
|
||||
are used via <tt/-t apple2 -C <configfile>/.
|
||||
|
||||
|
||||
<sect1>default config file (<tt/apple2.cfg/)<p>
|
||||
|
||||
Default configuration optimized for a binary program running on ProDOS 8 with
|
||||
BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card
|
||||
bank 2 memory from $D400 to $DFFF.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $803 to $95FF (35.5 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D400 to $DFFF (3 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Variable (default: $803)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
DOS 3.3 header (address and length)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1><tt/apple2-dos33.cfg/<p>
|
||||
|
||||
Configuration optimized for a binary program running on DOS 3.3. A plain
|
||||
vanilla DOS 3.3 doesn't make use of the Language Card at all.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $803 to $95FF (35.5 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D000 to $FFFF (12 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Variable (default: $803)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
DOS 3.3 header (address and length)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1><tt/apple2-system.cfg/<p>
|
||||
|
||||
Configuration for a system program running on ProDOS 8.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $2000 to $BEFF (39.75 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D400 to $DFFF (3 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Fixed ($2000)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
None
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1><tt/apple2-loader.cfg/<p>
|
||||
|
||||
Configuration optimized for a binary program running on ProDOS 8 without
|
||||
BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
|
||||
Apple ][ ProDOS 8 loader for cc65 programs/, which is available
|
||||
in the cc65 User Contributions section.
|
||||
|
||||
A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but
|
||||
isn't tied to the start address $2000. Thus with the default start
|
||||
address $800 the main memory area is increased by 6 KB.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $800 to $BEFF (45.75 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D400 to $DFFF (3 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Variable (default: $800)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
DOS 3.3 header (address and length)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1><tt/apple2-reboot.cfg/<p>
|
||||
|
||||
Configuration optimized for a binary program running on ProDOS 8 without
|
||||
BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
|
||||
Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together
|
||||
with the function <tt/rebootafterexit()/.
|
||||
|
||||
If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather
|
||||
reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of
|
||||
the Language Card bank 2 at all.
|
||||
|
||||
This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine!
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $800 to $BEFF (45.75 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D000 to $DFFF (4 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Variable (default: $800)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
DOS 3.3 header (address and length)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>ProDOS 8 system programs<p>
|
||||
|
||||
ProDOS 8 system programs are always loaded to the start address $2000.
|
||||
For cc65 programs this means that the 6 KB from $800 to $2000 are
|
||||
by default unused. There are however several options to make use of that memory
|
||||
range.
|
||||
|
||||
|
||||
<sect1>LOADER.SYSTEM<p>
|
||||
|
||||
The easiest (and for really large programs in fact the only) way to have a cc65
|
||||
program use the memory from $800 to $2000 is to link it as binary
|
||||
(as opposed to system) program using the linker configuration
|
||||
<htmlurl url="apple2-4.html#ss4.4" name="apple2-loader.cfg"> with start address
|
||||
$800 and load it with <bf/LOADER.SYSTEM - an Apple ][
|
||||
ProDOS 8 loader for cc65 programs/. The program then works like a system program
|
||||
(i.e. quits to the ProDOS dispatcher).
|
||||
|
||||
Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the
|
||||
program to load under name <program>.SYSTEM as a system program. For
|
||||
example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/.
|
||||
|
||||
|
||||
<sect1>Heap<p>
|
||||
|
||||
If the cc65 program can be successfully linked as system program using the linker
|
||||
configuration <htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> but
|
||||
uses the heap either explicitly or implicitly (i.e. by loading a driver) then
|
||||
the memory from $800 to $2000 can be added to the heap by calling
|
||||
<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/.
|
||||
|
||||
|
||||
<sect1>ProDOS 8 I/O buffers<p>
|
||||
|
||||
ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default
|
||||
these buffers are allocated by the cc65 runtime system on the heap using
|
||||
<tt/posix_memalign()/. While this is generally the best solution it means quite
|
||||
some overhead for (especially rather small) cc65 programs which do open files
|
||||
but don't make use of the heap otherwise.
|
||||
|
||||
The apple2 package comes with the alternative ProDOS 8 I/O buffer allocation
|
||||
module <tt/apple2-iobuf-0800.o/ which uses the memory between $800 and
|
||||
the program start address for the 1 KB I/O buffers. For system programs (with
|
||||
start address $2000) this results in up to 6 I/O buffers and thus up to 6
|
||||
concurrently open files.
|
||||
|
||||
While using <tt/_heapadd()/ as described in the section above together with the
|
||||
default I/O buffer allocation basically yields the same placement of I/O buffers
|
||||
in memory the primary benefit of <tt/apple2-iobuf-0800.o/ is a reduction in code
|
||||
size - and thus program file size - of more than 1400 bytes.
|
||||
|
||||
Using <tt/apple2-iobuf-0800.o/ is as simple as placing it on the linker command
|
||||
line like this:
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -t apple2 -C apple2-system.cfg myprog.c apple2-iobuf-0800.o
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing Apple ][ specific code may use the
|
||||
<tt/apple2.h/ header file.
|
||||
|
||||
|
||||
<sect1>Apple ][ specific functions<p>
|
||||
|
||||
The functions listed below are special for the Apple ][. See
|
||||
the <htmlurl url="funcref.html" name="function reference"> for declaration and
|
||||
usage.
|
||||
|
||||
<itemize>
|
||||
<item>_auxtype
|
||||
<item>_dos_type
|
||||
<item>_filetype
|
||||
<item>get_ostype
|
||||
<item>rebootafterexit
|
||||
<item>ser_apple2_slot
|
||||
<item>tgi_apple2_mix
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>Hardware access<p>
|
||||
|
||||
There's currently no support for direct hardware access. This does not mean
|
||||
you cannot do it, it just means that there's no help.
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2.lo.tgi (a2_lo_tgi)/</tag>
|
||||
This driver features a resolution of 40×48 with 16 colors.
|
||||
|
||||
The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
|
||||
function clears the corresponding area at the bottom of the screen.
|
||||
|
||||
<tag><tt/a2.hi.tgi (a2_hi_tgi)/</tag>
|
||||
This driver features a resolution of 280×192 with 8 colors and two
|
||||
hires pages. Note that programs using this driver will have to be linked
|
||||
with <tt/--start-addr $4000/ to reserve the first hires page or with
|
||||
<tt/--start-addr $6000/ to reserve both hires pages.
|
||||
|
||||
The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
|
||||
function doesn't clear the corresponding area at the bottom of the screen.
|
||||
|
||||
In memory constrained situations the memory from $803 to $1FFF
|
||||
can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/
|
||||
at the beginning of <tt/main()/. Doing so is beneficial even if the program
|
||||
doesn't use the the heap explicitly because loading the driver (and in fact
|
||||
already opening the driver file) uses the heap implicitly.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2.auxmem.emd (a2_auxmem_emd)/</tag>
|
||||
Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended
|
||||
80-Column Text Card.
|
||||
|
||||
Note that this driver doesn't check for the actual existence of the memory
|
||||
and that it doesn't check for ProDOS 8 RAM disk content!
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2.stdjoy.joy (a2_stdjoy_joy)/</tag>
|
||||
Supports up to two standard analog joysticks connected to the game port of
|
||||
the Apple ][.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2.stdmou.mou (a2_stdmou_mou)/</tag>
|
||||
Driver for the AppleMouse II Card. Searches all Apple II slots
|
||||
for an AppleMouse II Card compatible firmware. The default bounding
|
||||
box is [0..279,0..191].
|
||||
|
||||
Programs using this driver will have to be linked with <tt/--start-addr $4000/
|
||||
to reserve the first hires page if they are intended to run on an
|
||||
Apple ][ (in contrast to an Apple //e) because the
|
||||
AppleMouse II Card firmware writes to the hires page when initializing
|
||||
on that machine.
|
||||
|
||||
Note that the Apple ][ default mouse callbacks support text
|
||||
mode only.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2.ssc.ser (a2_ssc_ser)/</tag>
|
||||
Driver for the Apple II Super Serial Card. Supports up to 19200 baud,
|
||||
hardware flow control (RTS/CTS) and interrupt driven receives. Note
|
||||
that because of the peculiarities of the 6551 chip transmits are not
|
||||
interrupt driven, and the transceiver blocks if the receiver asserts
|
||||
flow control because of a full buffer.
|
||||
|
||||
The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to
|
||||
<tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/
|
||||
succeeds for all Apple II slots, but <tt/ser_open()/ fails with
|
||||
<tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
<sect1>DOS 3.3<p>
|
||||
|
||||
Although the standard binaries generated by the linker for the Apple ][
|
||||
generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with
|
||||
BASIC.SYSTEM) there are some limitations for DOS 3.3:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag>Disk File I/O</tag>
|
||||
There's no disk file I/O support. Any attempt to use it yields an error with
|
||||
<tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers
|
||||
are in general not functional as they depend on disk file I/O. Therefore the statically
|
||||
linked drivers have to be used instead.
|
||||
|
||||
<tag/Interrupts/
|
||||
There's no <tt/interruptor/ support. Any attempt to use it yields the message
|
||||
'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that
|
||||
<tt/a2.stdmou.mou/ and <tt/a2.ssc.ser/ are not functional as they depend on
|
||||
interrupts.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Direct console I/O<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag/Color/
|
||||
The Apple ][ has no color text mode. Therefore the functions textcolor(),
|
||||
bgcolor() and bordercolor() have no effect.
|
||||
|
||||
<tag/Cursor/
|
||||
The Apple ][ has no hardware cursor. Therefore the function cursor() has
|
||||
no effect.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not
|
||||
supported by BASIC, the following syntax was chosen:
|
||||
|
||||
<tscreen><verb>
|
||||
]CALL2051: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>Interrupts<p>
|
||||
|
||||
The runtime for the Apple ][ uses routines marked as
|
||||
<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be
|
||||
written as simple machine language subroutines and will be called
|
||||
automatically by the interrupt handler code when they are linked into a
|
||||
program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl
|
||||
url="ca65.html" name="assembler manual">.
|
||||
|
||||
|
||||
<sect1>DIO<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag/Drive ID/
|
||||
The function <htmlurl url="dio-1.html" name="dio_open()"> has the single
|
||||
parameter <tt/device/ to identify the device to be opened. Therefore an
|
||||
Apple II slot and drive pair is mapped to that <tt/device/ according
|
||||
to the formula
|
||||
|
||||
<tscreen>
|
||||
device = slot + (drive - 1) * 8
|
||||
</tscreen>
|
||||
|
||||
so that for example slot 6 drive 2 is mapped to <tt/device/ 14.
|
||||
|
||||
<tag/Sector count/
|
||||
The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns
|
||||
the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8
|
||||
disk it simply always returns 280 (which is only correct for a 140 KB disk).
|
||||
This condition is indicated by the <tt/_oserror/ value 82.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
538
doc/apple2enh.sgml
Normal file
538
doc/apple2enh.sgml
Normal file
@ -0,0 +1,538 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Enhanced Apple //e specific information for cc65
|
||||
<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de">
|
||||
<date>2009-10-07
|
||||
|
||||
<abstract>
|
||||
An overview over the enhanced Apple //e runtime system as it is
|
||||
implemented for the cc65 C compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the enhanced Apple //e runtime system
|
||||
as it comes with the cc65 C compiler. It describes the memory layout,
|
||||
enhanced Apple //e specific header files, available drivers, and any
|
||||
pitfalls specific to that platform.
|
||||
|
||||
Please note that enhanced Apple //e specific functions are just mentioned
|
||||
here, they are described in detail in the separate <htmlurl 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 file format generated by the linker for the
|
||||
enhanced Apple //e target is a binary program with a 4 byte DOS 3.3 header
|
||||
containing the load address and load length. The default load address is
|
||||
$803.
|
||||
|
||||
<bf/AppleCommander 1.3.5/ or later (available at <url
|
||||
url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/
|
||||
that allows to put binary files with a DOS 3.3 header onto disk images
|
||||
containing DOS 3.3 as well as ProDOS 8.
|
||||
|
||||
For ProDOS 8 system programs the load address is fixed to $2000 so there
|
||||
is no need for a header. Thus the linker configuration
|
||||
<htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> for those programs
|
||||
omits the DOS 3.3 header. The right AppleCommander option to put system files
|
||||
without a header on a ProDOS 8 disk image is <tt/-p/.
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
In the standard setup, cc65 generated programs use the memory from
|
||||
$803 to $95FF, so 35.5 KB of RAM are available.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at HIMEM and grows downwards, regardless of
|
||||
how your linker config file is setup.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
While running <tt/main()/ the Language Card bank 2 is enabled for read access.
|
||||
However while running module constructors/destructors the Language Card is disabled.
|
||||
|
||||
Enabling the Language Card allows to use it as additional memory for cc65
|
||||
generated code. However code is never automatically placed there. Rather code
|
||||
needs to be explicitly placed in the Language Card either per file by compiling
|
||||
with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma
|
||||
code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the
|
||||
cc65 runtime system takes care of actually moving the code into the Language
|
||||
Card.
|
||||
|
||||
The amount of memory available in the Language Card for generated code depends
|
||||
on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">.
|
||||
|
||||
|
||||
|
||||
<sect>Linker configurations<p>
|
||||
|
||||
The ld65 linker comes with a default config file for the enhanced Apple //e,
|
||||
which is used via <tt/-t apple2enh/.
|
||||
The apple2enh package comes with additional secondary linker config files, which
|
||||
are used via <tt/-t apple2enh -C <configfile>/.
|
||||
|
||||
|
||||
<sect1>default config file (<tt/apple2enh.cfg/)<p>
|
||||
|
||||
Default configuration optimized for a binary program running on ProDOS 8 with
|
||||
BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card
|
||||
bank 2 memory from $D400 to $DFFF.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $803 to $95FF (35.5 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D400 to $DFFF (3 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Variable (default: $803)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
DOS 3.3 header (address and length)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1><tt/apple2enh-dos33.cfg/<p>
|
||||
|
||||
Configuration optimized for a binary program running on DOS 3.3. A plain
|
||||
vanilla DOS 3.3 doesn't make use of the Language Card at all.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $803 to $95FF (35.5 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D000 to $FFFF (12 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Variable (default: $803)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
DOS 3.3 header (address and length)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1><tt/apple2enh-system.cfg/<p>
|
||||
|
||||
Configuration for a system program running on ProDOS 8.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $2000 to $BEFF (39.75 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D400 to $DFFF (3 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Fixed ($2000)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
None
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1><tt/apple2enh-loader.cfg/<p>
|
||||
|
||||
Configuration optimized for a binary program running on ProDOS 8 without
|
||||
BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
|
||||
Apple ][ ProDOS 8 loader for cc65 programs/, which is available
|
||||
in the cc65 User Contributions section.
|
||||
|
||||
A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but
|
||||
isn't tied to the start address $2000. Thus with the default start
|
||||
address $800 the main memory area is increased by 6 KB.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $800 to $BEFF (45.75 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D400 to $DFFF (3 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Variable (default: $800)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
DOS 3.3 header (address and length)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1><tt/apple2enh-reboot.cfg/<p>
|
||||
|
||||
Configuration optimized for a binary program running on ProDOS 8 without
|
||||
BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
|
||||
Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together
|
||||
with the function <tt/rebootafterexit()/.
|
||||
|
||||
If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather
|
||||
reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of
|
||||
the Language Card bank 2 at all.
|
||||
|
||||
This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine!
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/RAM:/ Main memory area</tag>
|
||||
From $800 to $BEFF (45.75 KB)
|
||||
|
||||
<tag><tt/LC:/ Language Card memory area</tag>
|
||||
From $D000 to $DFFF (4 KB)
|
||||
|
||||
<tag><tt/STARTADDRESS:/ Program start address</tag>
|
||||
Variable (default: $800)
|
||||
|
||||
<tag><tt/HEADER:/ Binary file header</tag>
|
||||
DOS 3.3 header (address and length)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>ProDOS 8 system programs<p>
|
||||
|
||||
ProDOS 8 system programs are always loaded to the start address $2000.
|
||||
For cc65 programs this means that the 6 KB from $800 to $2000 are
|
||||
by default unused. There are however several options to make use of that memory
|
||||
range.
|
||||
|
||||
|
||||
<sect1>LOADER.SYSTEM<p>
|
||||
|
||||
The easiest (and for really large programs in fact the only) way to have a cc65
|
||||
program use the memory from $800 to $2000 is to link it as binary
|
||||
(as opposed to system) program using the linker configuration
|
||||
<htmlurl url="apple2enh-4.html#ss4.4" name="apple2enh-loader.cfg"> with start address
|
||||
$800 and load it with <bf/LOADER.SYSTEM - an Apple ][
|
||||
ProDOS 8 loader for cc65 programs/. The program then works like a system program
|
||||
(i.e. quits to the ProDOS dispatcher).
|
||||
|
||||
Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the
|
||||
program to load under name <program>.SYSTEM as a system program. For
|
||||
example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/.
|
||||
|
||||
|
||||
<sect1>Heap<p>
|
||||
|
||||
If the cc65 program can be successfully linked as system program using the linker
|
||||
configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but
|
||||
uses the heap either explicitly or implicitly (i.e. by loading a driver) then
|
||||
the memory from $800 to $2000 can be added to the heap by calling
|
||||
<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/.
|
||||
|
||||
|
||||
<sect1>ProDOS 8 I/O buffers<p>
|
||||
|
||||
ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default
|
||||
these buffers are allocated by the cc65 runtime system on the heap using
|
||||
<tt/posix_memalign()/. While this is generally the best solution it means quite
|
||||
some overhead for (especially rather small) cc65 programs which do open files
|
||||
but don't make use of the heap otherwise.
|
||||
|
||||
The apple2enh package comes with the alternative ProDOS 8 I/O buffer allocation
|
||||
module <tt/apple2enh-iobuf-0800.o/ which uses the memory between $800 and
|
||||
the program start address for the 1 KB I/O buffers. For system programs (with
|
||||
start address $2000) this results in up to 6 I/O buffers and thus up to 6
|
||||
concurrently open files.
|
||||
|
||||
While using <tt/_heapadd()/ as described in the section above together with the
|
||||
default I/O buffer allocation basically yields the same placement of I/O buffers
|
||||
in memory the primary benefit of <tt/apple2enh-iobuf-0800.o/ is a reduction in code
|
||||
size - and thus program file size - of more than 1400 bytes.
|
||||
|
||||
Using <tt/apple2enh-iobuf-0800.o/ is as simple as placing it on the linker command
|
||||
line like this:
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -t apple2enh -C apple2enh-system.cfg myprog.c apple2enh-iobuf-0800.o
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing enhanced Apple //e specific code may use the
|
||||
<tt/apple2enh.h/ header file.
|
||||
|
||||
|
||||
<sect1>Enhanced Apple //e specific functions<p>
|
||||
|
||||
The functions listed below are special for the enhanced Apple //e. See
|
||||
the <htmlurl url="funcref.html" name="function reference"> for declaration and
|
||||
usage.
|
||||
|
||||
<itemize>
|
||||
<item>_auxtype
|
||||
<item>_dos_type
|
||||
<item>_filetype
|
||||
<item>get_ostype
|
||||
<item>rebootafterexit
|
||||
<item>ser_apple2_slot
|
||||
<item>textframe
|
||||
<item>textframexy
|
||||
<item>tgi_apple2_mix
|
||||
<item>videomode
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>Hardware access<p>
|
||||
|
||||
There's currently no support for direct hardware access. This does not mean
|
||||
you cannot do it, it just means that there's no help.
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2e.lo.tgi (a2e_lo_tgi)/</tag>
|
||||
This driver features a resolution of 40×48 with 16 colors.
|
||||
|
||||
The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
|
||||
function clears the corresponding area at the bottom of the screen.
|
||||
|
||||
<tag><tt/a2e.hi.tgi (a2e_hi_tgi)/</tag>
|
||||
This driver features a resolution of 280×192 with 8 colors and two
|
||||
hires pages. Note that programs using this driver will have to be linked
|
||||
with <tt/--start-addr $4000/ to reserve the first hires page or with
|
||||
<tt/--start-addr $6000/ to reserve both hires pages.
|
||||
|
||||
Note that the second hires page is only available if the text display is not in
|
||||
80 column mode. This can be asserted by calling <tt/videomode (VIDEOMODE_40COL);/
|
||||
before installing the driver.
|
||||
|
||||
The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
|
||||
function doesn't clear the corresponding area at the bottom of the screen.
|
||||
|
||||
In memory constrained situations the memory from $803 to $1FFF
|
||||
can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/
|
||||
at the beginning of <tt/main()/. Doing so is beneficial even if the program
|
||||
doesn't use the the heap explicitly because loading the driver (and in fact
|
||||
already opening the driver file) uses the heap implicitly.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2e.auxmem.emd (a2e_auxmem_emd)/</tag>
|
||||
Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended
|
||||
80-Column Text Card.
|
||||
|
||||
Note that this driver doesn't check for the actual existence of the memory
|
||||
and that it doesn't check for ProDOS 8 RAM disk content!
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2e.stdjoy.joy (a2e_stdjoy_joy)/</tag>
|
||||
Supports up to two standard analog joysticks connected to the game port of
|
||||
the enhanced Apple //e.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2e.stdmou.mou (a2e_stdmou_mou)/</tag>
|
||||
Driver for the AppleMouse II Card. Searches all Apple II slots
|
||||
for an AppleMouse II Card compatible firmware. The default bounding
|
||||
box is [0..279,0..191].
|
||||
|
||||
Note that the enhanced Apple //e default mouse callbacks support
|
||||
text mode only.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/a2e.ssc.ser (a2e_ssc_ser)/</tag>
|
||||
Driver for the Apple II Super Serial Card. Supports up to 19200 baud,
|
||||
hardware flow control (RTS/CTS) and interrupt driven receives. Note
|
||||
that because of the peculiarities of the 6551 chip transmits are not
|
||||
interrupt driven, and the transceiver blocks if the receiver asserts
|
||||
flow control because of a full buffer.
|
||||
|
||||
The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to
|
||||
<tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/
|
||||
succeeds for all Apple II slots, but <tt/ser_open()/ fails with
|
||||
<tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
<sect1>DOS 3.3<p>
|
||||
|
||||
Although the standard binaries generated by the linker for the enhanced Apple //e
|
||||
generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with
|
||||
BASIC.SYSTEM) there are some limitations for DOS 3.3:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag>Disk File I/O</tag>
|
||||
There's no disk file I/O support. Any attempt to use it yields an error with
|
||||
<tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers
|
||||
are in general not functional as they depend on disk file I/O. Therefore the statically
|
||||
linked drivers have to be used instead.
|
||||
|
||||
<tag/Interrupts/
|
||||
There's no <tt/interruptor/ support. Any attempt to use it yields the message
|
||||
'Failed to alloc interrupt' on program startup. This implicitly means that
|
||||
<tt/a2e.stdmou.mou/ and <tt/a2e.ssc.ser/ are not functional as they depend on
|
||||
interrupts.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Direct console I/O<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag/Color/
|
||||
The enhanced Apple //e has no color text mode. Therefore the functions
|
||||
textcolor(), bgcolor() and bordercolor() have no effect.
|
||||
|
||||
<tag/Cursor/
|
||||
The enhanced Apple //e has no hardware cursor. Therefore the function
|
||||
cursor() has no effect.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not
|
||||
supported by BASIC, the following syntax was chosen:
|
||||
|
||||
<tscreen><verb>
|
||||
]CALL2051: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>Function keys<p>
|
||||
|
||||
These are defined to be OpenApple + number key.
|
||||
|
||||
|
||||
<sect1>Interrupts<p>
|
||||
|
||||
The runtime for the enhanced Apple //e uses routines marked as
|
||||
<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be
|
||||
written as simple machine language subroutines and will be called
|
||||
automatically by the interrupt handler code when they are linked into a
|
||||
program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl
|
||||
url="ca65.html" name="assembler manual">.
|
||||
|
||||
|
||||
<sect1>DIO<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag/Drive ID/
|
||||
The function <htmlurl url="dio-1.html" name="dio_open()"> has the single
|
||||
parameter <tt/device/ to identify the device to be opened. Therefore an
|
||||
Apple II slot and drive pair is mapped to that <tt/drive_id/ according
|
||||
to the formula
|
||||
|
||||
<tscreen>
|
||||
device = slot + (drive - 1) * 8
|
||||
</tscreen>
|
||||
|
||||
so that for example slot 6 drive 2 is mapped to <tt/device/ 14.
|
||||
|
||||
<tag/Sector count/
|
||||
The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns
|
||||
the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8
|
||||
disk it simply always returns 280 (which is only correct for a 140 KB disk).
|
||||
This condition is indicated by the <tt/_oserror/ value 82.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
148
doc/ar65.sgml
Normal file
148
doc/ar65.sgml
Normal file
@ -0,0 +1,148 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>ar65 Users Guide
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>19.07.2000
|
||||
|
||||
<abstract>
|
||||
ar65 is an archiver for object files generated by ca65. It allows to create
|
||||
archives, add or remove modules from archives, and to extract modules from
|
||||
existing archives.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
|
||||
ar65 is a replacement for the libr65 archiver that was part of the cc65 C
|
||||
compiler suite developed by John R. Dunning. libr65 had some problems and
|
||||
the copyright does not permit some things which I wanted to be possible,
|
||||
so I decided to write a completely new assembler/linker/archiver suite
|
||||
for the cc65 compiler. ar65 is part of this suite.
|
||||
|
||||
<sect>Usage<p>
|
||||
|
||||
|
||||
The archiver is called as follows:
|
||||
|
||||
<tscreen><verb>
|
||||
Usage: ar65 <operation> lib file|module ...
|
||||
Operation is one of:
|
||||
a Add modules
|
||||
d Delete modules
|
||||
l List library contents
|
||||
x Extract modules
|
||||
V Print the archiver version
|
||||
</verb></tscreen>
|
||||
|
||||
You may add modules to a library using the `a' command. If the library
|
||||
does not exist, it is created (and a warning message is printed which you
|
||||
may ignore if creation of the library was your intention). You may
|
||||
specify any number of modules on the command line following the library.
|
||||
|
||||
If a module with the same name exists in the library, it is replaced by
|
||||
the new one. The archiver prints a warning, if the module in the library
|
||||
has a newer timestamp than the one to add.
|
||||
|
||||
Here's an example:
|
||||
|
||||
<tscreen><verb>
|
||||
ar65 a mysubs.lib sub1.o sub2.o
|
||||
</verb></tscreen>
|
||||
|
||||
This will add two modules to the library `mysubs.lib' creating the
|
||||
library if necessary. If the library contains modules named sub1.o or
|
||||
sub2.o, they are replaced by the new ones.
|
||||
|
||||
Modules names in the library are stored without the path, so, using
|
||||
|
||||
<tscreen><verb>
|
||||
ar65 a mysubs.lib ofiles/sub1.o ofiles/sub2.o
|
||||
</verb></tscreen>
|
||||
|
||||
will add two modules named `sub1.o' and `sub2.o' to the library.
|
||||
|
||||
Deleting modules from a library is done with the `d' command. You may not
|
||||
give a path when naming the modules.
|
||||
|
||||
Example:
|
||||
|
||||
<tscreen><verb>
|
||||
ar65 d mysubs.lib sub1.o
|
||||
</verb></tscreen>
|
||||
|
||||
This will delete the module named `sub1.o' from the library, printing an
|
||||
error if the library does not contain that module.
|
||||
|
||||
|
||||
The `l' command prints a list of all modules in the library. Any module
|
||||
names on the command line are ignored.
|
||||
|
||||
Example:
|
||||
|
||||
<tscreen><verb>
|
||||
ar65 l mysubs.lib
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
Using the `x' command, you may extract modules from the library. The
|
||||
modules named on the command line are extracted from the library and put
|
||||
into the current directory.
|
||||
|
||||
Note: Because of the indexing done by the archiver, the modules may have
|
||||
a changed binary layout, that is, a binary compare with the old module
|
||||
(before importing it into the library) may yield differences. The
|
||||
extracted modules are accepted by the linker and archiver, however, so
|
||||
this is not a problem.
|
||||
|
||||
Example for extracting a module from the library:
|
||||
|
||||
<tscreen><verb>
|
||||
ar65 x mysubs.lib sub1.o
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
The `V' command prints the version number of the assembler. If you send
|
||||
any suggestions or bugfixes, please include your version number.
|
||||
|
||||
In addition to these operations, the archiver will check for, and warn
|
||||
about duplicate external symbols in the library, every time when an
|
||||
operation does update the library. This is only a warning, the linker
|
||||
will ignore one of the duplicate symbols (which one is unspecified).
|
||||
|
||||
|
||||
<sect>Copyright<p>
|
||||
|
||||
ar65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
|
||||
Bassewitz. For usage of the binaries and/or sources the following conditions
|
||||
do apply:
|
||||
|
||||
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>
|
||||
|
||||
|
||||
|
||||
958
doc/atari.sgml
Normal file
958
doc/atari.sgml
Normal file
@ -0,0 +1,958 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Atari specific information for cc65
|
||||
<author>Shawn Jefferson, <htmlurl
|
||||
url="mailto:shawnjefferson@24fightingchickens.com"
|
||||
name="shawnjefferson@24fightingchickens.com"> and
|
||||
Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org">
|
||||
<date>03-Jan-2006
|
||||
|
||||
<abstract>
|
||||
An overview over the Atari runtime system as it is implemented for the cc65 C
|
||||
compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the Atari runtime system as it comes
|
||||
with the cc65 C compiler. It describes the memory layout, Atari specific
|
||||
header files, available drivers, and any pitfalls specific to that
|
||||
platform.
|
||||
|
||||
The Atari runtime support comes in two flavors: <tt/atari/ and <tt/atarixl/.
|
||||
The <tt/atari/ target supports all Atari 8-bit computers, the <tt/atarixl/ only
|
||||
supports XL type or newer machines (excluding the 600XL).
|
||||
|
||||
The <tt/atarixl/ runtime makes the whole 64K of memory available, with the
|
||||
exception of the I/O area at $D000 - $D7FFF. Since the
|
||||
<tt/atarixl/ runtime has some <ref name="limitations" id="limitations">, it is
|
||||
recommended to use the <tt/atari/ target unless lack of memory dictates the
|
||||
use of the <tt/atarixl/ target.
|
||||
|
||||
Please note that Atari specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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 Atari DOS executable file format supports more than one load block (<it/chunk/).
|
||||
|
||||
The default binary output format generated by the linker for the
|
||||
Atari target is a machine language program with a standard executable
|
||||
header (FF FF <load chunk #1> ... <load chunk #n>).
|
||||
A load chunk has the format [<2 byte start address> <2 bytes end address>
|
||||
<chunk data>].
|
||||
A run vector is added to the end of the
|
||||
file ($02E0 $02E1 <run vector>) and is calculated using
|
||||
the <tt/start/ label in crt0.s. (Technically the run vector is also a load chunk,
|
||||
but is not regarded as such here.)
|
||||
|
||||
An <tt/atari/ program has two load chunks, an <tt/atarixl/ program has three load
|
||||
chunks. The load chunks are defined in the linker configuration files. For more
|
||||
detailed information about the load chunks see the chapter
|
||||
<ref name="Technical details" id="techdetail">. For the discussion here it's
|
||||
sufficient to know that the first load chunk(s) do preparation work and the
|
||||
main part of the program is in the last load chunk.
|
||||
|
||||
The values determining the size of the main part of the program (the only load
|
||||
chunk for <tt/atari/, the third load chunk for <tt/atarixl/) are calculated in
|
||||
the crt0.s file from the __STARTUP_LOAD__ and __BSS_LOAD__ values.
|
||||
Be aware of that if you create a custom linker config file and start moving segments around (see section
|
||||
<ref name="Reserving a memory area inside the program" id="memhole">).
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
<sect1><tt/atari/ target<p>
|
||||
|
||||
The default linker config file assumes that the BASIC ROM is disabled (or
|
||||
the BASIC cartridge unplugged). This gives a usable memory range of
|
||||
[$2000-$BC1F]. The library startup code examines the
|
||||
current memory configuration, which depends on the size of the
|
||||
installed memory and cartridges. It does so by using the value in
|
||||
the MEMTOP ($2E5) variable as highest memory address the program
|
||||
can use. The initial stack pointer, which is the upper bound of
|
||||
memory used by the program, is set to this value, minus an optionally
|
||||
defined __RESERVED_MEMORY__ value.
|
||||
|
||||
The default load address of $2000 can be changed by creating a custom
|
||||
linker config file or by using the "--start-addr" cl65 command line
|
||||
argument or the "--start-addr" or "-S" ld65 command line arguments.
|
||||
|
||||
Please note that the first load chunk (which checks the available memory)
|
||||
will always be loaded at $2E00, regardless of the specified start
|
||||
address. This address can only be changed by a custom linker config file.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen depends on the installed memory size and cartridges
|
||||
and can be obtained from the SAVMSC variable ($58).
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at MEMTOP and grows downwards,
|
||||
regardless of how your linker config file is setup. This
|
||||
accommodates the different memory configurations of the Atari
|
||||
machines, as well as having a cartridge installed. You can override
|
||||
this behaviour by writing your own crt0.s file and linking it to
|
||||
your program (see also <ref name="Final note"
|
||||
id="memhole_final_note">).
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
<sect1><tt/atarixl/ target<p>
|
||||
|
||||
The startup code rearranges the memory as follows:
|
||||
|
||||
<enum>
|
||||
<item>Sceen memory and display list are moved below the program start address.
|
||||
<item>The ROM is disabled, making the memory in the areas [$C000-$CFFF]
|
||||
and [$D800-$FFF9] available.
|
||||
<item>Character generator data is copied from ROM to the CHARGEN location specified in the
|
||||
linker config file. This is (in the default <tt/atarixl.cfg/ file) at the same address as
|
||||
where it is in ROM ($E000, it can be changed, see <ref name="atarixl chargen location"
|
||||
id="chargenloc">). With the character generator at $E000, there are two upper memory
|
||||
areas available, [$D800-$DFFF] and [$E400-$FFF9].
|
||||
</enum>
|
||||
|
||||
With the default load address of $2400 this gives a usable memory range of
|
||||
[$2400-$CFFF]. Note that the default load address for <tt/atarixl/ is
|
||||
different (and lower) that the default load address for <tt/atari/. This is no problem since
|
||||
on the <tt/atarixl/ target the first load chunk makes sure that the loaded prgram won't overwrite
|
||||
memory below MEMLO. See <ref name="atarixl load chunks" id="xlchunks">.
|
||||
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen depends on the selected load address ($2400
|
||||
by default), and resides directly before that address, rounded to the next
|
||||
lower page boundary.
|
||||
The screen memory's start address can be obtained from the SAVMSC variable
|
||||
($58).
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at end of the RAM memory area ($CFFF)
|
||||
and grows downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program (end of BSS segment) and
|
||||
grows towards the C runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
<sect>Linker configurations<p>
|
||||
|
||||
The ld65 linker comes with default config files for the Atari. There
|
||||
are two targets for the Atari, <tt/atari/ and <tt/atarixl/.
|
||||
The default config file for <tt/atari/ is selected with
|
||||
<tt/-t atari/, and the default config file for <tt/atarixl/ is selected with
|
||||
<tt/-t atarixl/.
|
||||
The Atari package comes with additional secondary linker config files which
|
||||
can be used via <tt/-t atari -C <configfile>/ (for <tt/atari/ target) or
|
||||
<tt/-t atarixl -C <configfile>/ (for <tt/atarixl/ target).
|
||||
|
||||
<sect1><tt/atari/ config files<p>
|
||||
|
||||
<sect2>default config file (<tt/atari.cfg/)<p>
|
||||
|
||||
The default configuration is tailored to C programs. It creates files
|
||||
which have a default load address of $2000.
|
||||
|
||||
The files generated by this config file include the
|
||||
<ref name="&dquot;system check&dquot;" id="syschk"> load chunk. It can
|
||||
optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
|
||||
|
||||
<sect2><tt/atari-asm.cfg/<p>
|
||||
|
||||
This config file aims to give the assembler programmer maximum
|
||||
flexibility. All program segments (<tt/CODE/, <tt/DATA/, etc.) are
|
||||
optional.
|
||||
|
||||
By default it creates regular DOS executable files, which have a default
|
||||
load address of $2E00. It's also possible to generate an image of
|
||||
just the program data without EXE header, load address, or (auto-)start address.
|
||||
To you so, you have to define the symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
|
||||
when linking the program. Therefore, to generate a "plain" binary file, pass the
|
||||
options "<tt/-D__AUTOSTART__=1 -D__EXEHDR__=1/" to the linker.
|
||||
It's also possible to create a non auto-starting program file, by defining
|
||||
only the <tt/__AUTOSTART__/ symbol. Such a program has to be run manually
|
||||
after being loaded by DOS (for example by using the "M" option of DOS 2.5).
|
||||
Defining only the <tt/__EXEHDR__/ symbol will create a (useless) file which
|
||||
doesn't conform to the DOS executable file format (like a "plain" binary file)
|
||||
but still has the "autostart" load chunk appended.
|
||||
|
||||
The sections of the file which the defines refer to (<tt/__AUTOSTART__/ for
|
||||
the autostart trailer, <tt/__EXEHDR__/ for the EXE header and load address)
|
||||
is <it/left out/, keep this in mind.
|
||||
|
||||
The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
|
||||
don't matter.
|
||||
|
||||
<sect2><tt/atari-cart.cfg/<p>
|
||||
|
||||
This config file can be used to create 8K or 16K cartridges. It's suited both
|
||||
for C and assembly language programs.
|
||||
|
||||
By default, an 8K cartridge is generated. To create a 16K cartridge, pass the
|
||||
size of the cartridge to the linker, like "<tt/-D__CARTSIZE__=0x4000/".
|
||||
The only valid values for <tt/__CARTSIZE__/ are 0x2000 and 0x4000.
|
||||
|
||||
The option byte of the cartridge can be set with the <tt/__CARTFLAGS__/
|
||||
value, passed to the linker. The default value is $01, which means
|
||||
that the cartridge doesn't prevent the booting of DOS.
|
||||
|
||||
The option byte will be located at address $BFFD. For more information
|
||||
about its use, see e.g. "Mapping the Atari".
|
||||
|
||||
|
||||
<sect1><tt/atarixl/ config files<p>
|
||||
|
||||
<sect2>default config file (<tt/atarixl.cfg/)<p>
|
||||
|
||||
The default configuration is tailored to C programs. It creates files
|
||||
which have a default load address of $2400.
|
||||
|
||||
The files generated by this config file include the
|
||||
<ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can
|
||||
optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
|
||||
|
||||
<sect2><tt/atarixl-largehimem.cfg/<p>
|
||||
|
||||
This is the same as the default config file, but it rearranges the
|
||||
high memory beneath the ROM into one large block. In order for this
|
||||
config file to work, the runtime library has to be recompiled with a
|
||||
special define. See the file <tt/libsrc/atari/Makefile.inc/ in the
|
||||
source distribution.
|
||||
|
||||
The files generated by this config file include the
|
||||
<ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can
|
||||
optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">.
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing Atari specific code may use the <tt/atari.h/
|
||||
header file.
|
||||
|
||||
|
||||
<sect1>Atari specific functions<p>
|
||||
|
||||
The functions and global variable listed below are special for the Atari.
|
||||
See the <htmlurl url="funcref.html" name="function reference"> for declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>get_ostype
|
||||
<item>get_tv
|
||||
<item>_dos_type
|
||||
<item>_gtia_mkcolor
|
||||
<item>_getcolor
|
||||
<item>_getdefdev
|
||||
<item>_graphics
|
||||
<item>_rest_vecs
|
||||
<item>_save_vecs
|
||||
<item>_scroll
|
||||
<item>_setcolor
|
||||
<item>_setcolor_low
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>Hardware access<p>
|
||||
|
||||
The following pseudo variables declared in the <tt/atari.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/GTIA_READ/ and <tt/GTIA_WRITE/</tag>
|
||||
The <tt/GTIA_READ/ structure allows read access to the GTIA. The
|
||||
<tt/GTIA_WRITE/ structure allows write access to the GTIA.
|
||||
See the <tt/_gtia.h/ header file located in the include directory
|
||||
for the declaration of the structure.
|
||||
|
||||
<tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag>
|
||||
The <tt/POKEY_READ/ structure allows read access to the POKEY. The
|
||||
<tt/POKEY_WRITE/ structure allows write access to the POKEY.
|
||||
See the <tt/_pokey.h/ header file located in the include directory
|
||||
for the declaration of the structure.
|
||||
|
||||
<tag><tt/ANTIC/</tag>
|
||||
The <tt/ANTIC/ structure allows read access to the ANTIC.
|
||||
See the <tt/_antic.h/ header file located in the include directory
|
||||
for the declaration of the structure.
|
||||
|
||||
<tag><tt/PIA/</tag>
|
||||
The <tt/PIA/ structure allows read access to the PIA 6520.
|
||||
See the <tt/_pia.h/ header file located in the include directory
|
||||
for the declaration of the structure.
|
||||
|
||||
</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>
|
||||
|
||||
<table><tabular ca="rrrr">
|
||||
<tt/atari/|<tt/atarixl/|screen resolution|display pages@<hline>
|
||||
<tt/atr3.tgi (atr3_tgi)/|<tt/atrx3.tgi (atrx3_tgi)/|40x24x4 (CIO mode 3, ANTIC mode 8)|1@
|
||||
<tt/atr4.tgi (atr4_tgi)/|<tt/atrx4.tgi (atrx4_tgi)/|80x48x2 (CIO mode 4, ANTIC mode 9)|1@
|
||||
<tt/atr5.tgi (atr5_tgi)/|<tt/atrx5.tgi (atrx5_tgi)/|80x48x4 (CIO mode 5, ANTIC mode A)|1@
|
||||
<tt/atr6.tgi (atr6_tgi)/|<tt/atrx6.tgi (atrx6_tgi)/|160x96x2 (CIO mode 6, ANTIC mode B)|1@
|
||||
<tt/atr7.tgi (atr7_tgi)/|<tt/atrx7.tgi (atrx7_tgi)/|160x96x4 (CIO mode 7, ANTIC mode D)|1@
|
||||
<tt/atr8.tgi (atr8_tgi)/|<tt/atrx8.tgi (atrx8_tgi)/|320x192x2 (CIO mode 8, ANTIC mode F)|1@
|
||||
<tt/atr8p2.tgi (atr8p2_tgi)/|<tt/atrx8p2.tgi (atrx8p2_tgi)/|320x192x2 (CIO mode 8, ANTIC mode F)|2@
|
||||
<tt/atr9.tgi (atr9_tgi)/|<tt/atrx9.tgi (atrx9_tgi)/|80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)|1@
|
||||
<tt/atr9p2.tgi (atr9p2_tgi)/|<tt/atrx9p2.tgi (atrx9p2_tgi)/|80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)|2@
|
||||
<tt/atr10.tgi (atr10_tgi)/|<tt/atrx10.tgi (atrx10_tgi)/|80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)|1@
|
||||
<tt/atr10p2.tgi (atr10p2_tgi)/|<tt/atrx10p2.tgi (atrx10p2_tgi)/|80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)|2@
|
||||
<tt/atr11.tgi (atr11_tgi)/|<tt/atrx11.tgi (atrx11_tgi)/|80x192x16h (CIO mode 11, ANTIC mode F, GTIA mode $C0)|1@
|
||||
<tt/atr14.tgi (atr14_tgi)/|<tt/atrx14.tgi (atrx14_tgi)/|160x192x2 (CIO mode 14, ANTIC mode C)|1@
|
||||
<tt/atr15.tgi (atr15_tgi)/|<tt/atrx15.tgi (atrx15_tgi)/|160x192x4 (CIO mode 15, ANTIC mode E)|1@
|
||||
<tt/atr15p2.tgi (atr15p2_tgi)/|<tt/atrx15p2.tgi (atrx15p2_tgi)/|160x192x4 (CIO mode 15, ANTIC mode E)|2
|
||||
</tabular>
|
||||
<!-- <caption>bla bla -->
|
||||
</table>
|
||||
|
||||
|
||||
Many graphics modes require more memory than the text screen which is
|
||||
in effect when the program starts up. Therefore the programmer has to
|
||||
tell the program beforehand the memory requirements of the graphics
|
||||
modes the program intends to use.
|
||||
|
||||
On the <tt/atari/ target his can be done by using the __RESERVED_MEMORY__
|
||||
linker config variable. The number specified there describes the number
|
||||
of bytes to subtract from the top of available memory as seen from the
|
||||
runtime library. This memory is then used by the screen buffer.
|
||||
|
||||
On the <tt/atarixl/ target the screen memory resides below the program
|
||||
load address. In order to reserve memory for a graphics mode, one
|
||||
simply uses a higher program load address. There are restrictions on
|
||||
selectable load addresses,
|
||||
see <ref name="Selecting a good program load address" id="loadaddr">.
|
||||
|
||||
The numbers for the different graphics modes presented below should
|
||||
only be seen as a rule of thumb. Since the screen buffer memory needs
|
||||
to start at specific boundaries, the numbers depend on the current top
|
||||
of available memory.
|
||||
The following numbers were determined by a BASIC program.
|
||||
|
||||
<table>
|
||||
<tabular ca="rr">
|
||||
graphics mode|reserved memory@<hline>
|
||||
0|1@
|
||||
1|1@
|
||||
2|1@
|
||||
3|1@
|
||||
4|1@
|
||||
5|182@
|
||||
6|1182@
|
||||
7|3198@
|
||||
8|7120@
|
||||
9|7146@
|
||||
10|7146@
|
||||
11|7146@
|
||||
12|162@
|
||||
13|1@
|
||||
14|3278@
|
||||
15|7120@
|
||||
16|1@
|
||||
17|1@
|
||||
18|1@
|
||||
19|1@
|
||||
20|1@
|
||||
21|184@
|
||||
22|1192@
|
||||
23|3208@
|
||||
24|7146@
|
||||
25|7146@
|
||||
26|7146@
|
||||
27|7146@
|
||||
28|162@
|
||||
29|1@
|
||||
30|3304@
|
||||
31|7146
|
||||
</tabular>
|
||||
<caption>reserved memory required for different graphics modes
|
||||
</table>
|
||||
|
||||
The values of "1" are needed because the graphics command crashes if
|
||||
it doesn't have at least one byte available. This seems to be a bug of
|
||||
the Atari ROM code.
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
Currently there is only one extended memory driver. It manages the second 64K of a 130XE.
|
||||
|
||||
<table>
|
||||
<tabular ca="rr">
|
||||
<tt/atari/|<tt/atarixl/@<hline>
|
||||
<tt/atr130.emd (atr130_emd)/|<tt/atrx130.emd (atrx130_emd)/
|
||||
</tabular>
|
||||
</table>
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
Currently there are two joystick drivers available:
|
||||
|
||||
<table>
|
||||
<tabular ca="rrr">
|
||||
<tt/atari/|<tt/atarixl/|description@<hline>
|
||||
<tt/atrstd.joy (atrstd_joy)/|<tt/atrxstd.joy (atrxstd_joy)/|Supports up to two/four standard joysticks connected to the joystick ports of the Atari. (Four on the pre-XL systems, two on XL or newer.)@
|
||||
<tt/atrmj8.joy (atrmj8_joy)/|<tt/atrxmj8.joy (atrxmj8_joy)/|Supports up to eight standard joysticks connected to a MultiJoy adapter.
|
||||
</tabular>
|
||||
<caption>
|
||||
</table>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
Currently there are five mouse drivers available:
|
||||
|
||||
<table>
|
||||
<tabular ca="rrr">
|
||||
<tt/atari/|<tt/atarixl/|description@<hline>
|
||||
<tt/atrjoy.mou (atrjoy_mou)/|<tt/atrxjoy.mou (atrxjoy_mou)/|Supports a mouse emulated by a standard joystick.@
|
||||
<tt/atrst.mou (atrst_mou)/|<tt/atrxst.mou (atrxst_mou)/|Supports an Atari ST mouse.@
|
||||
<tt/atrami.mou (atrami_mou)/|<tt/atrxami.mou (atrxami_mou)/|Supports an Amiga mouse.@
|
||||
<tt/atrtrk.mou (atrtrk_mou)/|<tt/atrxtrk.mou (atrxtrk_mou)/|Supports an Atari trakball.@
|
||||
<tt/atrtt.mou (atrtt_mou)/|<tt/atrxtt.mou (atrxtt_mou)/|Supports an Atari touch tablet.
|
||||
</tabular>
|
||||
<caption>
|
||||
</table>
|
||||
|
||||
All mouse devices connect to joystick port #0.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
Currently there is one RS232 driver. It uses the R: device (therefore
|
||||
an R: driver needs to be installed) and was tested with the 850
|
||||
interface module.
|
||||
|
||||
<table>
|
||||
<tabular ca="rr">
|
||||
<tt/atari/|<tt/atarixl/@<hline>
|
||||
<tt/atrrdev.ser (atrrdev_ser)/|<tt/atrxrdev.ser (atrxrdev_ser)/
|
||||
</tabular>
|
||||
</table>
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
<sect1><tt/atarixl/<label id="limitations"<p>
|
||||
|
||||
<itemize>
|
||||
<item>The display is cleared at program start and at program termination. This is a side
|
||||
effect of relocating the display memory below the program start address.
|
||||
<item>Not all possible CIO and SIO functions are handled by the runtime stub code which banks
|
||||
the ROM in and out. All functions used by the runtime library are handled, though.
|
||||
<item>The <tt/_sys()/ function is not supported.
|
||||
<item>It is not compatible with DOSes or other programs using the memory below the ROM.
|
||||
</itemize>
|
||||
|
||||
<sect>DIO implementation<label id="dio"><p>
|
||||
|
||||
The Atari supports disk drives with either 128 or 256 byte sectors.
|
||||
The first three sectors of any disk are always 128 bytes long though. This is
|
||||
because the system can only boot from 128 bytes sectors.
|
||||
|
||||
Therefore the DIO read and write functions transfer only 128 bytes
|
||||
for sectors 1 to 3, regardless of the type of diskette.
|
||||
|
||||
|
||||
<sect>CONIO implementation<label id="conio"><p>
|
||||
|
||||
The console I/O is speed optimized therefore support for XEP80 hardware
|
||||
or f80.com software is missing. Of course you may use stdio.h functions.
|
||||
|
||||
|
||||
<sect>Technical details<label id="techdetail"><p>
|
||||
|
||||
<sect1><tt/atari/<p>
|
||||
|
||||
<sect2>Load chunks<p>
|
||||
|
||||
An <tt/atari/ program contains two load chunks.
|
||||
|
||||
<enum>
|
||||
<item>"system check"<label id="syschk">&nl;
|
||||
This load chunk is always loaded at address $2E00, and checks if the system has
|
||||
enough memory to run the program. It also checks if the program start address is not
|
||||
below MEMLO. If any of the checks return false, the loading of the program is aborted.&nl;
|
||||
The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file.
|
||||
<item>main program&nl;
|
||||
This load chunk is loaded at the selected program start address (default $2000) and
|
||||
contains all of the code and data of the program.&nl;
|
||||
The contents of this chunk come from the RAM memory area of the linker config file.
|
||||
</enum>
|
||||
|
||||
|
||||
<sect1><tt/atarixl/<p>
|
||||
|
||||
<sect2>General operation<p>
|
||||
|
||||
The <tt/atarixl/ target banks out the ROM while the program is running in
|
||||
order to make more memory available to the program.
|
||||
|
||||
The screen memory is by default located at the top of available memory,
|
||||
$BFFF if BASIC is not enabled, $9FFF if BASIC is enabled.
|
||||
Therefore, in order to create a largest possible continuous memory area,
|
||||
the screen memory is moved below the program load address. This gives
|
||||
a memory area from <program load addr> to $CFFF.
|
||||
|
||||
The startup code installs wrappers for interrupt handlers and ROM routines.
|
||||
When an interrupt or call to a ROM routine happens, the wrappers enable the
|
||||
ROM, call the handler or routine, and disable the ROM again.
|
||||
|
||||
The "wrapping" of the ROM routines is done by changing the ROM entry
|
||||
point symbols in <tt/atari.inc/ to point to the wrapper functions.
|
||||
|
||||
For ROM functions which require input or output buffers, the wrappers
|
||||
copy the data as required to buffers in low memory.
|
||||
|
||||
<sect2>Load chunks<label id="xlchunks"><p>
|
||||
|
||||
An <tt/atarixl/ program contains three load chunks.
|
||||
|
||||
<enum>
|
||||
<item>"system check"<label id="syschkxl">&nl;
|
||||
This load chunk is always loaded at address $2E00, and checks if the system is
|
||||
suitable for running the program. It also checks if there is enough room between MEMLO
|
||||
and the program start address to move the text mode screen buffer there. If any of the
|
||||
checks return false, the loading of the program is aborted.&nl;
|
||||
The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file.
|
||||
<item>"shadow RAM prepare"&nl;
|
||||
The second load chunk gets loaded to the selected program load address (default $2400).
|
||||
It moves the screen memory below the program load address, copies the character generator
|
||||
from ROM to its new place in RAM, and copies the parts of the program which reside in
|
||||
high memory below the ROM to their place. The high memory parts are included in this load chunk.&nl;
|
||||
At the beginning of this load chunk there is a .bss area, which is not part of the
|
||||
EXE file. Therefore the on-disk start address of this load chunk will be higher than the
|
||||
selected start address. This .bss area (segment LOWBSS) contains the buffers for the
|
||||
double buffering of ROM input and output data. If you add contents to this segment be aware
|
||||
that the contents won't be zero initialized by the startup code.&nl;
|
||||
The contents of this chunk come from the SRPREPCHNK memory area of the linker config file.
|
||||
<item>main program&nl;
|
||||
This load chunk is loaded just above the LOWBSS segment, replacing the code of
|
||||
the previous load chunk. It contains all remaining code and data sections of the program,
|
||||
including the startup code.&nl;
|
||||
The contents of this chunk come from the RAM memory area of the linker config file.
|
||||
</enum>
|
||||
|
||||
<sect2>Moving screen memory below the program start address<p>
|
||||
|
||||
When setting a graphics mode, the ROM looks at the RAMTOP location. RAMTOP
|
||||
describes the amount of installed memory in pages (RAMTOP is only one byte).
|
||||
The screen memory and display list are placed immediately below RAMTOP.
|
||||
|
||||
Now in order to relocate the screen memory to lower memory, the startup code
|
||||
puts a value into RAMTOP which causes the ROM routines to allocate the display
|
||||
memory below the program start address and then it issues a ROM call to setup
|
||||
the regular text mode.
|
||||
|
||||
<sect2>Selecting a good program load address<label id="loadaddr"><p>
|
||||
|
||||
Due to the movement of the screen memory below the program start, there are some
|
||||
load addresses which are sub-optimal because they waste memory or prevent a
|
||||
higher resolution graphics mode from being enabled.
|
||||
|
||||
There are restrictions at which addresses screen memory (display buffer and display
|
||||
list) can be placed. The display buffer cannot cross a 4K boundary and a display
|
||||
list cannot cross a 1K boundary.
|
||||
|
||||
The startup code takes this into account when moving the screen memory down.
|
||||
If the program start address (aligned to the next lower page boundary) minus
|
||||
the screen buffer size would result in a screen buffer which spans a 4K
|
||||
boundary, the startup code lowers RAMTOP to this 4K boundary.&nl;
|
||||
The size of the screen buffer in text mode is 960 ($3C0) bytes. So, for
|
||||
example, a selected start address of $2300 would span the 4K boundary
|
||||
at $2000. The startup code would adjust the RAMTOP value in such way that
|
||||
the screen memory would be located just below this boundary (at $1C40).
|
||||
This results in the area [$2000-$22FF] being wasted.
|
||||
Additionally, the program might fail to load since the lowest address used
|
||||
by the screen memory could be below MEMLO. (The lowest address used in this
|
||||
example would be at $1C20, where the display list would allocated.)
|
||||
|
||||
These calculations are performed by the startup code (in the first two
|
||||
load chunks), but the startup code only takes the default 40x24 text mode
|
||||
into account. If the program later wants to load TGI drivers which set
|
||||
a more memory consuming graphics mode, the user has to pick a higher
|
||||
load address.
|
||||
Using higher resolution modes there is a restriction in the ROM that it
|
||||
doesn't expect RAMTOP to be at arbitrary values. The Atari memory modules
|
||||
came only in 8K or 16K sizes, so the ROM expects RAMTOP to only have
|
||||
values in 8K steps. Therefore, when using the highest resolution modes
|
||||
the program start address must be at an 8K boundary.
|
||||
|
||||
|
||||
<sect2>Character generator location<label id="chargenloc"><p>
|
||||
|
||||
The default <tt/atarixl/ linker config file (<tt/atarixl.cfg/) leaves the
|
||||
character generator location at the same address where it is in ROM
|
||||
($E000). This has the disadvatage to split the upper memory into
|
||||
two parts ([$D800-$DFFF] and
|
||||
[$E400-$FFF9]). For applications which
|
||||
require a large continuous upper memory area, an alternative linker
|
||||
config file (<tt/atarixl-largehimem.cfg/) is provided. It relocates the
|
||||
character generator to $D800, providing a single big upper
|
||||
memory area at [$DC00-$FFF9].
|
||||
|
||||
With the character generator at a different address than in ROM, the routines
|
||||
which enable and disable the ROM also have to update the chargen pointer.
|
||||
This code is not enabled by default. In order to enable it,
|
||||
uncomment the line which sets CHARGEN_RELOC in <tt/libsrc/atari/Makefile.inc/
|
||||
and recompile the <tt/atarixl/ runtime library.
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
|
||||
<sect1>Function keys<p>
|
||||
|
||||
Function keys are mapped to Atari + number key.
|
||||
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/ when DOS supports it.
|
||||
|
||||
<enum>
|
||||
<item>Arguments are separated by spaces.
|
||||
<item>Leading and trailing spaces around an argument are ignored.
|
||||
<item>The first argument passed to <tt/main/ is the program name.
|
||||
<item>A maximum number of 16 arguments (including the program name) are
|
||||
supported.
|
||||
</enum>
|
||||
|
||||
|
||||
<sect1>Interrupts<p>
|
||||
|
||||
The runtime for the Atari 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 VBI handler code
|
||||
when they are linked into a program. See the discussion of the <tt/.CONDES/
|
||||
feature in the <htmlurl url="ca65.html" name="assembler manual">.
|
||||
|
||||
|
||||
<sect1>Reserving a memory area inside a program<label id="memhole"><p>
|
||||
|
||||
(This section is primarily applicable to the <tt/atari/ target, but the
|
||||
principles apply to <tt/atatixl/ as well.)
|
||||
|
||||
The Atari 130XE maps its additional memory into CPU memory in 16K
|
||||
chunks at address $4000 to $7FFF. One might want to
|
||||
prevent this memory area from being used by cc65. Other reasons to
|
||||
prevent the use of some memory area could be to reserve space for the
|
||||
buffers for display lists and screen memory.
|
||||
<p>
|
||||
The Atari executable format allows holes inside a program, e.g. one
|
||||
part loads into $2E00 to $3FFF, going below the reserved
|
||||
memory area (assuming a reserved area from $4000 to
|
||||
$7FFF), and another part loads into $8000 to
|
||||
$BC1F.
|
||||
<p>
|
||||
Each load chunk of the executable starts with a 4 byte header which
|
||||
defines its load address and size. In the following linker config files
|
||||
these headers are named HEADER and SECHDR (for the MEMORY layout), and
|
||||
accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout).
|
||||
<p>
|
||||
<sect2>Low code and high data example<p>
|
||||
Goal: Create an executable with 2 load chunks which doesn't use the
|
||||
memory area from $4000 to $7FFF. The CODE segment of
|
||||
the program should go below $4000 and the DATA and RODATA
|
||||
segments should go above $7FFF.
|
||||
<p>
|
||||
The main problem is that the EXE header generated by the cc65 runtime
|
||||
lib is wrong. It defines a single load chunk with the sizes/addresses
|
||||
of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments, in
|
||||
fact, the whole user program (we're disregarding the "system check"
|
||||
load chunk here).
|
||||
<p>
|
||||
The contents of the EXE header come from the EXEHDR and MAINHDR segments.
|
||||
The EXEHDR segment just contains the $FFFF value which is required
|
||||
to be the first bytes of the EXE file.&nl;
|
||||
The MAINHDR are defined in in crt0.s. This cannot be changed without
|
||||
modifying and recompiling the cc65 atari runtime library. Therefore
|
||||
the original contents of this segment must be discarded and be
|
||||
replaced by a user created one. This discarding is done by assigning the
|
||||
MAINHDR segment to the (new introduced) DISCARD memory area. The DISCARD memory area is
|
||||
thrown away in the new linker config file (written to file "").
|
||||
We add a new FSTHDR segment for the chunk header of the first chunk.
|
||||
<p>
|
||||
The user needs to create a customized linker config file which adds
|
||||
new memory areas and segments to hold the new header data for the first load
|
||||
chunk and the header data for the second load chunk. Also an assembly source file
|
||||
needs to be created which defines the contents of the new header data
|
||||
for the two load chunks.
|
||||
<p>
|
||||
<p>
|
||||
This is an example of a modified cc65 Atari linker configuration file
|
||||
(split.cfg):
|
||||
<tscreen><verb>
|
||||
SYMBOLS {
|
||||
__STACKSIZE__: value = $800 type = weak; # 2K stack
|
||||
__RESERVED_MEMORY__: value = $0000, type = weak;
|
||||
}
|
||||
FEATURES {
|
||||
STARTADDRESS: default = $2E00;
|
||||
}
|
||||
MEMORY {
|
||||
ZP: start = $82, size = $7E, type = rw, define = yes;
|
||||
|
||||
HEADER: start = $0000, size = $2, file = %O; # first load chunk
|
||||
|
||||
FSTHDR: start = $0000, size = $4, file = %O; # second load chunk
|
||||
RAMLO: start = %S, size = $4000 - %S, file = %O;
|
||||
|
||||
DISCARD: start = $4000, size = $4000, file = "";
|
||||
|
||||
SECHDR: start = $0000, size = $4, file = %O; # second load chunk
|
||||
RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
|
||||
}
|
||||
SEGMENTS {
|
||||
EXEHDR: load = HEADER, type = ro;
|
||||
|
||||
MAINHDR: load = DISCARD, type = ro;
|
||||
|
||||
NEXEHDR: load = FSTHDR, type = ro; # first load chunk
|
||||
STARTUP: load = RAMLO, type = ro, define = yes;
|
||||
LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes;
|
||||
INIT: load = RAMLO, type = ro, optional = yes;
|
||||
CODE: load = RAMLO, type = ro, define = yes;
|
||||
|
||||
CHKHDR: load = SECHDR, type = ro; # second load chunk
|
||||
RODATA: load = RAM, type = ro, define = yes;
|
||||
DATA: load = RAM, type = rw, define = yes;
|
||||
BSS: load = RAM, type = bss, define = yes;
|
||||
|
||||
ZEROPAGE: load = ZP, type = zp;
|
||||
AUTOSTRT: load = RAM, type = ro; # defines program entry point
|
||||
}
|
||||
FEATURES {
|
||||
CONDES: segment = RODATA,
|
||||
type = constructor,
|
||||
label = __CONSTRUCTOR_TABLE__,
|
||||
count = __CONSTRUCTOR_COUNT__;
|
||||
CONDES: segment = RODATA,
|
||||
type = destructor,
|
||||
label = __DESTRUCTOR_TABLE__,
|
||||
count = __DESTRUCTOR_COUNT__;
|
||||
}
|
||||
</verb></tscreen>
|
||||
<p>
|
||||
|
||||
A new memory area DISCARD was added.
|
||||
It gets loaded with the contents of the (now unused) MAINHDR segment. But the
|
||||
memory area isn't written to the output file. This way the contents of
|
||||
the MAINHDR segment get discarded.
|
||||
<p>
|
||||
The newly added NEXEHDR segment defines the correct chunk header for the
|
||||
first intended load chunk. It
|
||||
puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the
|
||||
segments containing only code, into load chunk #1 (RAMLO memory area).
|
||||
<p>
|
||||
The header for the second load chunk comes from the new CHKHDR
|
||||
segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load
|
||||
chunk #2 (RAM memory area).
|
||||
<p>
|
||||
<p>
|
||||
The contents of the new NEXEHDR and CHKHDR segments come from this
|
||||
file (split.s):
|
||||
<tscreen><verb>
|
||||
.import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
|
||||
.import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
|
||||
|
||||
.segment "NEXEHDR"
|
||||
.word __STARTUP_LOAD__
|
||||
.word __CODE_LOAD__ + __CODE_SIZE__ - 1
|
||||
|
||||
.segment "CHKHDR"
|
||||
.word __RODATA_LOAD__
|
||||
.word __BSS_LOAD__ - 1
|
||||
</verb></tscreen>
|
||||
<p>
|
||||
Compile with
|
||||
<tscreen><verb>
|
||||
cl65 -t atari -C split.cfg -o prog.com prog.c split.s
|
||||
</verb></tscreen>
|
||||
|
||||
<sect2>Low data and high code example<p>
|
||||
|
||||
|
||||
Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT,
|
||||
CODE, BSS, ZPSAVE into high memory (split2.cfg):
|
||||
|
||||
<tscreen><verb>
|
||||
SYMBOLS {
|
||||
__STACKSIZE__: value = $800 type = weak; # 2K stack
|
||||
__RESERVED_MEMORY__: value = $0000, type = weak;
|
||||
}
|
||||
FEATURES {
|
||||
STARTADDRESS: default = $2E00;
|
||||
}
|
||||
MEMORY {
|
||||
ZP: start = $82, size = $7E, type = rw, define = yes;
|
||||
|
||||
HEADER: start = $0000, size = $2, file = %O; # first load chunk
|
||||
|
||||
FSTHDR: start = $0000, size = $4, file = %O; # second load chunk
|
||||
RAMLO: start = %S, size = $4000 - %S, file = %O;
|
||||
|
||||
DISCARD: start = $4000, size = $4000, file = "";
|
||||
|
||||
SECHDR: start = $0000, size = $4, file = %O; # second load chunk
|
||||
RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
|
||||
}
|
||||
SEGMENTS {
|
||||
EXEHDR: load = HEADER, type = ro; # discarded old EXE header
|
||||
|
||||
MAINHDR: load = DISCARD, type = ro;
|
||||
|
||||
NEXEHDR: load = FSTHDR, type = ro; # first load chunk
|
||||
RODATA: load = RAMLO, type = ro, define = yes;
|
||||
DATA: load = RAMLO, type = rw, define = yes;
|
||||
|
||||
CHKHDR: load = SECHDR, type = ro; # second load chunk
|
||||
STARTUP: load = RAM, type = ro, define = yes;
|
||||
INIT: load = RAM, type = ro, optional = yes;
|
||||
CODE: load = RAM, type = ro, define = yes;
|
||||
BSS: load = RAM, type = bss, define = yes;
|
||||
|
||||
ZEROPAGE: load = ZP, type = zp;
|
||||
AUTOSTRT: load = RAM, type = ro; # defines program entry point
|
||||
}
|
||||
FEATURES {
|
||||
CONDES: segment = RODATA,
|
||||
type = constructor,
|
||||
label = __CONSTRUCTOR_TABLE__,
|
||||
count = __CONSTRUCTOR_COUNT__;
|
||||
CONDES: segment = RODATA,
|
||||
type = destructor,
|
||||
label = __DESTRUCTOR_TABLE__,
|
||||
count = __DESTRUCTOR_COUNT__;
|
||||
}
|
||||
</verb></tscreen>
|
||||
|
||||
New contents for NEXEHDR and CHKHDR are needed (split2.s):
|
||||
<tscreen><verb>
|
||||
.import __STARTUP_LOAD__, __BSS_LOAD__, __DATA_SIZE__
|
||||
.import __DATA_LOAD__, __RODATA_LOAD__
|
||||
|
||||
.segment "NEXEHDR"
|
||||
.word __RODATA_LOAD__
|
||||
.word __DATA_LOAD__ + __DATA_SIZE__ - 1
|
||||
|
||||
.segment "CHKHDR"
|
||||
.word __STARTUP_LOAD__
|
||||
.word __BSS_LOAD__ - 1
|
||||
</verb></tscreen>
|
||||
|
||||
Compile with
|
||||
<tscreen><verb>
|
||||
cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s
|
||||
</verb></tscreen>
|
||||
|
||||
<sect2>Final note<label id="memhole_final_note"><p>
|
||||
|
||||
There are two other memory areas which don't appear directly in the
|
||||
linker config file. They are the stack and the heap.
|
||||
|
||||
The cc65 runtime lib places the stack location at the end of available
|
||||
memory. This is dynamically set from the MEMTOP system variable at
|
||||
startup. The heap is located in the area between the end of the BSS
|
||||
segment and the top of the stack as defined by __STACKSIZE__.
|
||||
|
||||
If BSS and/or the stack shouldn't stay at the end of the program,
|
||||
some parts of the cc65 runtime lib need to be replaced/modified.
|
||||
|
||||
common/_heap.s defines the location of the heap and atari/crt0.s
|
||||
defines the location of the stack by initializing sp.
|
||||
|
||||
|
||||
<sect1>Upgrading from an older cc65 version<p>
|
||||
|
||||
If you are using a customized linker config file you might get some errors
|
||||
regarding the MAINHDR segment. Like this:
|
||||
|
||||
<tscreen><verb>
|
||||
ld65: Error: Missing memory area assignment for segment `MAINHDR'
|
||||
</verb></tscreen>
|
||||
|
||||
The old "HEADER" memory description contained six bytes: $FFFF
|
||||
and the first and last memory addess of the program. For the "system
|
||||
check" load chunk this had to be split into two memory assigments. The
|
||||
"HEADER" now only contains the $FFFF. The main program's first
|
||||
and last memory address were moved to a new segment, called "MAINHDR",
|
||||
which in the new linker config file goes into its own memory area (also
|
||||
called "MAINHDR").&nl;&nl;
|
||||
A simple way to adapt your old linker config file is to add the
|
||||
following line to the "SEGMENTS" section:
|
||||
|
||||
<tscreen><verb>
|
||||
MAINHDR: load = HEADER, type = ro;
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
|
||||
<sect1>Getting rid of the "system check" load chunk<label id="nosyschk"><p>
|
||||
|
||||
If, for some reason, you don't want to include the "system check" load
|
||||
chunk, you can do so by defining the symbol <tt/__SYSTEM_CHECK__/ when linking the
|
||||
program. The "system check" chunk doesn't include vital parts of the
|
||||
program. So if you don't want the system checks, it is save to leave them out.
|
||||
This is probably mostly interesting for debugging.
|
||||
|
||||
When using cl65, you can leave it out with this command line:
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -Wl -D__SYSTEM_CHECK__=1 <arguments>
|
||||
</verb></tscreen>
|
||||
|
||||
The value you assign to <tt/__SYSTEM_CHECK_/ doesn't matter. If the
|
||||
<tt/__SYSTEM_CHECK__/ symbol is defined, the load chunk won't be included.
|
||||
|
||||
|
||||
<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>
|
||||
251
doc/atmos.sgml
Normal file
251
doc/atmos.sgml
Normal file
@ -0,0 +1,251 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Oric Atmos specific information for cc65
|
||||
<author>Ullrich von Bassewitz <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"><newline>
|
||||
Stefan A. Haubenthal <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"><newline>
|
||||
<url url="mailto:greg.king5@verizon.net" name="Greg King">
|
||||
<date>2013-01-08
|
||||
|
||||
<abstract>
|
||||
An overview over the Atmos runtime system as it is implemented for the cc65 C
|
||||
compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the Atmos runtime system as it comes with the
|
||||
cc65 C compiler. It describes the memory layout, Atmos specific header files,
|
||||
available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that Atmos specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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 Atmos target
|
||||
is a machine language program with a 17 byte tape header including a cc65 tag.
|
||||
The standard load and autostart address is $500.
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
In the standard setup, cc65 generated programs use the memory from
|
||||
$500 to $9800, so nearly 37K of memory (including the stack) is
|
||||
available. ROM calls are possible without further precautions.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $97FF and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing Atmos specific code may use the <tt/atmos.h/ header file.
|
||||
|
||||
|
||||
<sect1>Atmos specific functions<p>
|
||||
|
||||
The functions listed below are special for the Atmos. See the <htmlurl
|
||||
url="funcref.html" name="function reference"> for declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>atmos_load
|
||||
<item>atmos_save
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>Hardware access<p>
|
||||
|
||||
The following pseudo variables declared in the <tt/atmos.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/VIA/</tag>
|
||||
Access to the VIA (versatile interface adapter) chip is available via the
|
||||
<tt/VIA/ variable. The structure behind this variable is explained in <tt/_6522.h/.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Loadable drivers<p>
|
||||
|
||||
<em>Note:</em> Since the Atmos doesn't have working disk I/O
|
||||
(see <ref id="limitations" name="section "Limitations"">), the
|
||||
available drivers cannot be loaded at runtime (so the term "loadable drivers"
|
||||
is somewhat misleading). Instead, the drivers have to be statically linked. While
|
||||
this may seem overhead, it has two advantages:
|
||||
|
||||
<enum>
|
||||
<item>The interface is identical to the one used for other platforms
|
||||
and to the one for the Atmos once it has disk I/O.
|
||||
<item>Once disk I/O is available, existing code can be changed to load drivers
|
||||
at runtime with almost no effort.
|
||||
</enum>
|
||||
|
||||
The names in the parentheses denote the symbols to be used for static linking of the drivers.
|
||||
|
||||
|
||||
<sect1>Graphics drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/atmos-228-200-3.tgi (atmos_228_200_3_tgi)/</tag>
|
||||
This driver was written by Greg King and Stefan Haubenthal.
|
||||
It features a resolution of 228×200 with a palette of two colors that
|
||||
can be chosen from the Atmos's eight colors. The driver supports a third
|
||||
palette-"color" that actually "flips" the pixel (it becomes the other color)
|
||||
that is on the screen under the graphics cursor.
|
||||
|
||||
<tag><tt/atmos-240-200-2.tgi (atmos_240_200_2_tgi)/</tag>
|
||||
This driver was written by Stefan Haubenthal and Greg King.
|
||||
It features a resolution of 240×200 with black and white colors.
|
||||
It is the default graphics driver for the Atmos.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
No extended memory drivers are currently available for the Atmos.
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/atmos-pase.joy (atmos_pase_joy)/</tag>
|
||||
Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the Atmos.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/atmos-acia.ser (atmos_acia_ser)/</tag>
|
||||
Driver for the Telestrat integrated serial controller and the Atmos with a
|
||||
serial add-on.
|
||||
Note that because of the peculiarities of the 6551 chip together with the
|
||||
use of the NMI, transmits are not interrupt driven, and the transceiver
|
||||
blocks if the receiver asserts flow control because of a full buffer.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<label id="limitations"><p>
|
||||
|
||||
<sect1>Disk I/O<p>
|
||||
|
||||
The existing library for the Atmos doesn't implement C file
|
||||
I/O. There is one hack for the <tt/write()/ routine in
|
||||
place, which will make functions work that write to <tt/stdout/
|
||||
(like <tt/printf()/). However, this function has some shortcomings which
|
||||
won't be fixed, because it's going to be replaced anyway.
|
||||
|
||||
To be more concrete, this limitation means that you cannot use any of the
|
||||
following functions (and a few others):
|
||||
|
||||
<itemize>
|
||||
<item>fclose
|
||||
<item>fopen
|
||||
<item>fread
|
||||
<item>fprintf
|
||||
<item>fputc
|
||||
<item>fscanf
|
||||
<item>fwrite
|
||||
<item>...
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Function keys<p>
|
||||
|
||||
These are defined to be FUNCT + number key.
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/. Since this is not
|
||||
supported by BASIC, the following syntax was chosen:
|
||||
|
||||
<tscreen><verb>
|
||||
CALL#500: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>Interrupts<p>
|
||||
|
||||
The runtime for the Atmos 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
|
||||
when they are linked into a program. See the discussion of the <tt/.CONDES/
|
||||
feature in the <htmlurl 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>
|
||||
|
||||
|
||||
|
||||
353
doc/c128.sgml
Normal file
353
doc/c128.sgml
Normal file
@ -0,0 +1,353 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Commodore 128 specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2003-12-14
|
||||
|
||||
<abstract>
|
||||
An overview over the C128 runtime system as it is implemented for the cc65 C
|
||||
compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the C128 runtime system as it comes with the
|
||||
cc65 C compiler. It describes the memory layout, C128 specific header files,
|
||||
available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that C128 specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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 C128 target
|
||||
is a machine language program with a one line BASIC stub, which calls the
|
||||
machine language part via SYS. This means that a program can be loaded as
|
||||
BASIC program and started with RUN. It is of course possible to change this
|
||||
behaviour by using a modified startup 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 enabled. Note that this is a non standard memory layout, and that
|
||||
there is no "memory configuration index" for this layout. This means that
|
||||
special care has to be taken when changing the configuration, or calling any
|
||||
code that does this. The memory configuration register at $FF00 should
|
||||
be saved and restored instead of relying on the memory configuration index
|
||||
stored in the zero page.
|
||||
|
||||
The setup gives a usable memory range of $1C00 - $BFFF. Having
|
||||
just the kernal ROM mapped in means, that kernal entry points may be called
|
||||
directly, but using the BASIC ROM is not possible without additional code.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen is located at $400 (as in the standard setup).
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $BFFF and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing C128 specific code may use the <tt/c128.h/ or <tt/cbm.h/
|
||||
header files. Using the later may be an option when writing code for more than
|
||||
one CBM platform, since it includes <tt/c128.h/ and declares several functions
|
||||
common to all CBM platforms.
|
||||
|
||||
|
||||
<sect1>C128 specific functions<p>
|
||||
|
||||
The functions listed below are special for the C128. See the <htmlurl
|
||||
url="funcref.html" name="function reference"> for declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>videomode
|
||||
<item>c64mode
|
||||
<item>fast
|
||||
<item>slow
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>CBM specific functions<p>
|
||||
|
||||
Some functions are available for all (or at least most) of the Commodore
|
||||
machines. See the <htmlurl url="funcref.html" name="function reference"> for
|
||||
declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>cbm_close
|
||||
<item>cbm_closedir
|
||||
<item>cbm_k_setlfs
|
||||
<item>cbm_k_setnam
|
||||
<item>cbm_k_load
|
||||
<item>cbm_k_save
|
||||
<item>cbm_k_open
|
||||
<item>cbm_k_close
|
||||
<item>cbm_k_readst
|
||||
<item>cbm_k_chkin
|
||||
<item>cbm_k_ckout
|
||||
<item>cbm_k_basin
|
||||
<item>cbm_k_bsout
|
||||
<item>cbm_k_clrch
|
||||
<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/c128.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/VIC/</tag>
|
||||
The <tt/VIC/ structure allows access to the VIC II (the graphics
|
||||
controller). See the <tt/_vic2.h/ header file located in the include
|
||||
directory for the declaration of the structure.
|
||||
|
||||
<tag><tt/SID/</tag>
|
||||
The <tt/SID/ structure allows access to the SID (the sound interface
|
||||
device). See the <tt/_sid.h/ header file located in the include directory
|
||||
for the declaration of the structure.
|
||||
|
||||
<tag><tt/VDC/</tag>
|
||||
The <tt/VDC/ structure allows access to the VDC (the video display
|
||||
controller). See the <tt/_vdc.h/ header file located in the include
|
||||
directory for the declaration of the structure.
|
||||
|
||||
<tag><tt/CIA1, CIA2/</tag>
|
||||
Access to the two CIA (complex interface adapter) chips is available via
|
||||
the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables
|
||||
is explained in <tt/_6526.h/.
|
||||
|
||||
<tag><tt/COLOR_RAM/</tag>
|
||||
A character array that mirrors the color RAM of the C128 at $D800.
|
||||
|
||||
</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>
|
||||
|
||||
Note: The graphics drivers for the VDC are incompatible with the extended
|
||||
memory drivers using the VDC memory!
|
||||
|
||||
<descrip>
|
||||
<tag><tt/c128-vdc.tgi (c128_vdc_tgi)/</tag>
|
||||
This driver was written by Maciej Witkowiak. It uses the 80 column display
|
||||
and features a resolution of 640*200 with two colors and an adjustable
|
||||
palette (that means that the two colors can be chosen out of the 16 VDC
|
||||
colors).
|
||||
|
||||
<tag><tt/c128-vdc2.tgi (c128_vdc2_tgi)/</tag>
|
||||
This driver was written by Maciej Witkowiak. This driver uses the 80 column
|
||||
display and features a resolution of 640*480 with two colors and an
|
||||
adjustable palette (that means that the two colors can be chosen out of the
|
||||
16 VDC colors). The driver requires 64KB VDC RAM.
|
||||
</descrip><p>
|
||||
|
||||
Note: The colors are translated from definitions in headers to correct VDC values
|
||||
so please use definitions or VIC color numbers only. Colors <tt/GRAY3/ and <tt/BROWN/ are
|
||||
missing on VDC and are translated to the two colors missing from VIC palette.
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c128-georam.emd (c128_georam_emd)/</tag>
|
||||
A driver for the GeoRam cartridge. The driver will always assume 2048 pages
|
||||
of 256 bytes each. There are no checks, so if your program knows better,
|
||||
just go ahead.
|
||||
|
||||
<tag><tt/c128-ram.emd (c128_ram_emd)/</tag>
|
||||
An extended memory driver for the RAM in page 1. The common memory area is
|
||||
excluded, so this driver supports 251 pages of 256 bytes each.
|
||||
|
||||
<tag><tt/c128-ram2.emd (c128_ram2_emd)/</tag>
|
||||
An extended memory driver for the RAM in pages 1-3. The common memory area
|
||||
is excluded, so this driver supports up to 731 pages of 256 bytes each. The
|
||||
driver can be used as a full replacement for <tt/c128-ram.emd/, because RAM
|
||||
in pages 2+3 is autodetected, but it's larger and there are not many
|
||||
machines with RAM in banks 2+3, so it has been made a separate driver. The
|
||||
additional code was contributed by Marco van den Heuvel.
|
||||
|
||||
<tag><tt/c128-ramcart.emd (c128_ramcart_emd)/</tag>
|
||||
A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak.
|
||||
Will test the hardware for the available RAM.
|
||||
|
||||
<tag><tt/c128-reu.emd (c128_reu_emd)/</tag>
|
||||
A driver for the CBM REUs. The driver will determine from the connected REU
|
||||
if it supports 128KB of RAM or more. In the latter case, 256KB are assumed,
|
||||
but since there are no range checks, the application can use more memory if
|
||||
it has better knowledge about the hardware than the driver.
|
||||
|
||||
<tag><tt/c128-vdc.emd (c128_vdc_emd)/</tag>
|
||||
A driver for the VDC memory of the C128 written and contributed by Maciej
|
||||
Witkowiak. Autodetects the amount of memory available (16 or 64K) and offers
|
||||
64 or 256 pages of 256 bytes each. Note: This driver is incompatible with
|
||||
any of the graphics drivers using the VDC!
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c128-ptvjoy.joy (c128_ptvjoy_joy)/</tag>
|
||||
Driver for the Protovision 4-player adapter originally written by Groepaz
|
||||
for the C64 and converted for the C128 by me. See <htmlurl
|
||||
url="http://www.protovision-online.de/hardw/hardwstart.htm"
|
||||
name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
|
||||
building instructions. Up to four joysticks are supported.
|
||||
|
||||
<tag><tt/c128-stdjoy.joy (c128_stdjoy_joy)/</tag>
|
||||
Supports up to two joysticks connected to the standard joysticks port of
|
||||
the C128.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c128-1351.mou (c128_1351_mou)/</tag>
|
||||
Supports a standard mouse connected to port #0 of the C128.
|
||||
|
||||
<tag><tt/c128-inkwell.mou (c128_inkwell_mou)/</tag>
|
||||
Supports the Inkwell Systems lightpens, connected to port #0 of the
|
||||
C128. It can read both the one-button 170-C and the two-button 184-C pens.
|
||||
(It can read other lightpens and light-guns that send their button signal to
|
||||
the joystick left-button pin or the paddle Y [up/down] pin.) It works on
|
||||
only the 40-column screen.
|
||||
|
||||
<tag><tt/c128-joy.mou (c128_joy_mou)/</tag>
|
||||
Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
|
||||
#1 of the C128.
|
||||
|
||||
<tag><tt/c128-pot.mou (c128_pot_mou)/</tag>
|
||||
Supports a potentiometer device e.g. Koala Pad connected to port #1 of
|
||||
the C128.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c128-swlink.ser (c128_swlink_ser)/</tag>
|
||||
Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow
|
||||
control (RTS/CTS) and interrupt driven receives. Note that because of the
|
||||
peculiarities of the 6551 chip together with the use of the NMI, transmits
|
||||
are not interrupt driven, and the transceiver blocks if the receiver asserts
|
||||
flow control because of a full buffer.
|
||||
|
||||
The driver uses the RS232 variables and buffers of the kernal (buffers at
|
||||
$C00 and $D00).
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/. Since this is not
|
||||
supported 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 runtime for the C128 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
|
||||
when they are linked into a program. See the discussion of the <tt/.CONDES/
|
||||
feature in the <htmlurl 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>
|
||||
264
doc/c16.sgml
Normal file
264
doc/c16.sgml
Normal file
@ -0,0 +1,264 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Commodore 16/116 specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2003-12-15
|
||||
|
||||
<abstract>
|
||||
An overview over the C16 runtime system as it is implemented for the cc65 C
|
||||
compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the C16 runtime system as it comes with the
|
||||
cc65 C compiler. It describes the memory layout, C16/116 specific header
|
||||
files, available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that C16 specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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.
|
||||
|
||||
Since the C16/C116 and the Commodore Plus/4 are almost identical (the former
|
||||
don't have the 6551 ACIA and only 16KB of memory), the <htmlurl
|
||||
url="plus4.html" name="Plus/4 documentation"> is also worth a look. The
|
||||
difference between both cc65 targets is that the Plus/4 runtime uses banking
|
||||
to support full 64K RAM, while the C16 does not use banking and supports up to
|
||||
32K RAM. Because banking is not needed, most C16 programs will be somewhat
|
||||
smaller than the same program compiled for the Plus/4. However, programs C16
|
||||
will always run on the Plus/4, while the reverse is not necessarily true.
|
||||
|
||||
|
||||
<sect>Binary format<p>
|
||||
|
||||
The standard binary output format generated by the linker for the C16/116
|
||||
target is a machine language program with a one line BASIC stub which, calls
|
||||
the machine language part via SYS. This means that a program can be loaded as
|
||||
BASIC program and started with RUN. It is of course possible to change this
|
||||
behaviour by using a modified startup file and linker config.
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs with the default setup run with the kernal and basic
|
||||
banked in. This gives a usable memory range of $1000 - $4000
|
||||
(or $8000 if the machine is equipped with 32K RAM or more). Having the
|
||||
kernal and basic ROMs banked in means, that ROM entry points may be called
|
||||
directly from user code.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen is located at $C00 (as in the standard setup).
|
||||
|
||||
<tag/Color RAM/
|
||||
The color RAM is located at $800 (standard location).
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $3FFF ($7FFF in case of a
|
||||
machine with 32K of memory or more) and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing C16 specific code may use the <tt/c16.h/ or <tt/cbm.h/
|
||||
header files. Using the later may be an option when writing code for more than
|
||||
one CBM platform, since it includes <tt/c16.h/ and declares several functions
|
||||
common to all CBM platforms.
|
||||
|
||||
Please note that most of the header file declarations from the <tt/c16.h/
|
||||
header file are shared between the C16 and Plus/4 configurations. For this
|
||||
reason, most of it is located in a common header file named <tt/cbm264.h/.
|
||||
|
||||
|
||||
|
||||
<sect1>C16/C116 specific functions<p>
|
||||
|
||||
There are currently no special C16/C116 functions.
|
||||
|
||||
|
||||
<sect1>CBM specific functions<p>
|
||||
|
||||
Some functions are available for all (or at least most) of the Commodore
|
||||
machines. See the <htmlurl url="funcref.html" name="function reference"> for
|
||||
declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>cbm_close
|
||||
<item>cbm_closedir
|
||||
<item>cbm_k_setlfs
|
||||
<item>cbm_k_setnam
|
||||
<item>cbm_k_load
|
||||
<item>cbm_k_save
|
||||
<item>cbm_k_open
|
||||
<item>cbm_k_close
|
||||
<item>cbm_k_readst
|
||||
<item>cbm_k_chkin
|
||||
<item>cbm_k_ckout
|
||||
<item>cbm_k_basin
|
||||
<item>cbm_k_bsout
|
||||
<item>cbm_k_clrch
|
||||
<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/c16.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/TED/</tag>
|
||||
The <tt/TED/ structure allows access to the TED chip. See the
|
||||
<tt/_ted.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
<tag><tt/COLOR_RAM/</tag>
|
||||
A character array that mirrors the color RAM of the C16 at $0800.
|
||||
|
||||
</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 currently available for the C16/C116.
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c16-ram.emd (c16_ram_emd)/</tag>
|
||||
A driver for the hidden RAM below the BASIC and KERNAL ROMs. Supports 125
|
||||
pages with 256 bytes each if the machine is equipped with 64K of memory
|
||||
(a Plus/4 or a memory extended C16/116).
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c16-stdjoy.joy (c16_stdjoy_joy)/</tag>
|
||||
Supports up to two joysticks connected to the standard joysticks port of
|
||||
the Commodore 16/116.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the C16/C116.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
The Commodore 16 does not have a builtin ACIA and no RS232 extensions are
|
||||
known. For this reason, there are no RS232 drivers available. Please note that
|
||||
the standard Plus/4 driver will <em>not</em> run together with the C16
|
||||
library, because the latter does not support interrupts needed by the driver.
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/. Since this is not
|
||||
supported 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 runtime for the C16 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
|
||||
when they are linked into a program. See the discussion of the <tt/.CONDES/
|
||||
feature in the <htmlurl 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>
|
||||
|
||||
|
||||
|
||||
|
||||
402
doc/c64.sgml
Normal file
402
doc/c64.sgml
Normal file
@ -0,0 +1,402 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Commodore 64 specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2003-09-23
|
||||
|
||||
<abstract>
|
||||
An overview over the C64 runtime system as it is implemented for the cc65 C
|
||||
compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the C64 runtime system as it comes with the
|
||||
cc65 C compiler. It describes the memory layout, C64 specific header files,
|
||||
available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that C64 specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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 C64 target
|
||||
is a machine language program with a one line BASIC stub, which calls the
|
||||
machine language part via SYS. This means that a program can be loaded as
|
||||
BASIC program and started with RUN. It is of course possible to change this
|
||||
behaviour by using a modified startup 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 enabled (memory under the kernal may be used for graphics or as
|
||||
extended memory - see the sections about graphics and extended memory
|
||||
drivers). The BASIC ROM is disabled, which gives a usable memory range of
|
||||
$0800 - $CFFF. This means that kernal entry points may be called
|
||||
directly, but using the BASIC ROM is not possible without additional code.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen is located at $400 (as in the standard setup).
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $CFFF and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect>Linker configurations<p>
|
||||
|
||||
The ld65 linker comes with a default config file for the Commodore 64,
|
||||
which is used via <tt/-t c64/. The
|
||||
c64 package comes with additional secondary linker config files, which are
|
||||
used via <tt/-t c64 -C <configfile>/.
|
||||
|
||||
|
||||
<sect1>default config file (<tt/c64.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/c64-asm.cfg/<p>
|
||||
|
||||
This configuration is made for assembler programmers who don't need a special
|
||||
setup. The default start address is $801. It can be changed with the
|
||||
linker command line option <tt/--start-addr/. 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 this config file, assemble with <tt/-t c64/ and link with <tt/-C
|
||||
c64-asm.cfg/. The former will make sure that correct character translation is
|
||||
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 c64 -C c64-asm.cfg source.s
|
||||
</verb></tscreen>
|
||||
|
||||
To generate code that loads to $C000:
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -o file.prg --start-addr $C000 -t c64 -C c64-asm.cfg source.s
|
||||
</verb></tscreen>
|
||||
|
||||
It is also 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 c64 -C c64-asm.cfg source.s
|
||||
</verb></tscreen>
|
||||
|
||||
Please note that in this case a changed start address doesn't make sense,
|
||||
since the program must be loaded to the BASIC start address.
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/
|
||||
header files. Using the later may be an option when writing code for more than
|
||||
one CBM platform, since it includes <tt/c64.h/ and declares several functions
|
||||
common to all CBM platforms.
|
||||
|
||||
|
||||
<sect1>C64 specific functions<p>
|
||||
|
||||
The functions listed below are special for the C64. See the <htmlurl
|
||||
url="funcref.html" name="function reference"> for declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>get_ostype
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>CBM specific functions<p>
|
||||
|
||||
Some functions are available for all (or at least most) of the Commodore
|
||||
machines. See the <htmlurl url="funcref.html" name="function reference"> for
|
||||
declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>cbm_close
|
||||
<item>cbm_closedir
|
||||
<item>cbm_k_setlfs
|
||||
<item>cbm_k_setnam
|
||||
<item>cbm_k_load
|
||||
<item>cbm_k_save
|
||||
<item>cbm_k_open
|
||||
<item>cbm_k_close
|
||||
<item>cbm_k_readst
|
||||
<item>cbm_k_chkin
|
||||
<item>cbm_k_ckout
|
||||
<item>cbm_k_basin
|
||||
<item>cbm_k_bsout
|
||||
<item>cbm_k_clrch
|
||||
<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/c64.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/VIC/</tag>
|
||||
The <tt/VIC/ structure allows access to the VIC II (the graphics
|
||||
controller). See the <tt/_vic2.h/ header file located in the include
|
||||
directory for the declaration of the structure.
|
||||
|
||||
<tag><tt/SID/</tag>
|
||||
The <tt/SID/ structure allows access to the SID (the sound interface
|
||||
device). See the <tt/_sid.h/ header file located in the include directory
|
||||
for the declaration of the structure.
|
||||
|
||||
<tag><tt/CIA1, CIA2/</tag>
|
||||
Access to the two CIA (complex interface adapter) chips is available via
|
||||
the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables
|
||||
is explained in <tt/_6526.h/.
|
||||
|
||||
<tag><tt/COLOR_RAM/</tag>
|
||||
A character array that mirrors the color RAM of the C64 at $D800.
|
||||
|
||||
</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>
|
||||
|
||||
<em>Note:</em> All available graphics drivers for the TGI interface will use
|
||||
the space below the I/O area and kernal ROM, so you can have hires graphics in
|
||||
the standard setup without any memory loss or need for a changed
|
||||
configuration.
|
||||
|
||||
<descrip>
|
||||
<tag><tt/c64-hi.tgi (c64_hi_tgi)/</tag>
|
||||
This driver features a resolution of 320*200 with two colors and an
|
||||
adjustable palette (that means that the two colors can be chosen out of a
|
||||
palette of the 16 C64 colors).
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c64-c256k.emd (c64_c256k_emd)/</tag>
|
||||
A driver for the C64 256K memory expansion. This driver offers 768 pages of
|
||||
256 bytes each. Written and contributed by Marco van den Heuvel.
|
||||
|
||||
<tag><tt/c64-dqbb.emd (c64_dqbb_emd)/</tag>
|
||||
A driver for the Double Quick Brown Box cartridge. This driver offers
|
||||
64 pages of 256 bytes each. Written and contributed by Marco van den Heuvel.
|
||||
|
||||
<tag><tt/c64-georam.emd (c64_georam_emd)/</tag>
|
||||
A driver for the Berkeley Softworks GeoRam cartridge. The driver will
|
||||
determine the available RAM from the connected cartridge. It supports 64KB
|
||||
up to 2048KB of RAM.
|
||||
|
||||
<tag><tt/c64-isepic.emd (c64_isepic_emd)/</tag>
|
||||
A driver for the ISEPIC cartridge. This driver offers just 8 pages of 256
|
||||
bytes each. Written and contributed by Marco van den Heuvel.
|
||||
|
||||
<tag><tt/c64-ram.emd (c64_ram_emd)/</tag>
|
||||
A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48
|
||||
256 byte pages. Please note that this driver is incompatible with any of the
|
||||
graphics drivers!
|
||||
|
||||
<tag><tt/c64-ramcart.emd (c64_ramcart_emd)/</tag>
|
||||
A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak.
|
||||
Will test the hardware for the available RAM.
|
||||
|
||||
<tag><tt/c64-reu.emd (c64_reu_emd)/</tag>
|
||||
A driver for the CBM REUs. The driver will determine from the connected REU
|
||||
if it supports 128KB of RAM or more. In the latter case, 256KB are assumed,
|
||||
but since there are no range checks, the application can use more memory if
|
||||
it has better knowledge about the hardware than the driver.
|
||||
|
||||
<tag><tt/c64-vdc.emd (c64_vdc_emd)/</tag>
|
||||
A driver for the VDC memory of the C128. Written and contributed by Maciej
|
||||
Witkowiak. Can be used if the program is running in C64 mode of the C128.
|
||||
Autodetects the amount of memory available (16 or 64K) and offers 64 or 256
|
||||
pages of 256 bytes each.
|
||||
|
||||
<tag><tt/dtv-himem.emd (dtv_himem_emd)/</tag>
|
||||
A driver for the C64 D2TV (the second or PAL version). This driver offers
|
||||
indeed 7680 pages of 256 bytes each.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c64-hitjoy.joy (c64_hitjoy_joy)/</tag>
|
||||
Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See
|
||||
<htmlurl url="http://www.digitalexcess.de/downloads/productions.php"
|
||||
name="http://www.digitalexcess.de/downloads/productions.php"> on
|
||||
instructions how to build one. Up to four joysticks are supported.
|
||||
|
||||
<tag><tt/c64-ptvjoy.joy (c64_ptvjoy_joy)/</tag>
|
||||
Driver for the Protovision 4-player adapter contributed by Groepaz. See
|
||||
<htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
|
||||
name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
|
||||
building instructions. Up to four joysticks are supported.
|
||||
|
||||
<tag><tt/c64-stdjoy.joy (c64_stdjoy_joy)/</tag>
|
||||
Supports up to two standard joysticks connected to the joysticks port of
|
||||
the C64.
|
||||
|
||||
<tag><tt/c64-numpad.joy (c64_numpad_joy)/</tag>
|
||||
Supports one joystick emulated by the numberpad of the C128 in C64 mode,
|
||||
the firebutton is labeled &dquot;5&dquot; and ENTER.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c64-1351.mou (c64_1351_mou)/</tag>
|
||||
Supports a standard mouse connected to port #0 of the C64.
|
||||
|
||||
<tag><tt/c64-inkwell.mou (c64_inkwell_mou)/</tag>
|
||||
Supports the Inkwell Systems lightpens, connected to port #0 of the C64.
|
||||
It can read both the one-button 170-C and the two-button 184-C pens. (It can
|
||||
read other lightpens and light-guns that send their button signal to the
|
||||
joystick left-button pin or the paddle Y [up/down] pin.)
|
||||
|
||||
<tag><tt/c64-joy.mou (c64_joy_mou)/</tag>
|
||||
Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
|
||||
#1 of the C64.
|
||||
|
||||
<tag><tt/c64-pot.mou (c64_pot_mou)/</tag>
|
||||
Supports a potentiometer device e.g. Koala Pad connected to port #1 of
|
||||
the C64.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/c64-swlink.ser (c64_swlink_ser)/</tag>
|
||||
Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow
|
||||
control (RTS/CTS) and interrupt driven receives. Note that because of the
|
||||
peculiarities of the 6551 chip together with the use of the NMI, transmits
|
||||
are not interrupt driven, and the transceiver blocks if the receiver asserts
|
||||
flow control because of a full buffer.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Escape code<p>
|
||||
|
||||
For an Esc press CTRL and [ key.
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/. Since this is not
|
||||
supported 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 runtime for the C64 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
|
||||
when they are linked into a program. See the discussion of the <tt/.CONDES/
|
||||
feature in the <htmlurl 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>
|
||||
4749
doc/ca65.sgml
Normal file
4749
doc/ca65.sgml
Normal file
File diff suppressed because it is too large
Load Diff
306
doc/cbm510.sgml
Normal file
306
doc/cbm510.sgml
Normal file
@ -0,0 +1,306 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Commodore 510 (aka P500) specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">&nl;
|
||||
Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">&nl;
|
||||
<htmlurl url="mailto:greg.king5@verizon.net" name="Greg King">
|
||||
<date>2013-08-23
|
||||
|
||||
<abstract>
|
||||
An overview over the Commodore 510 runtime system as it is implemented for the
|
||||
cc65 C compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the CBM 510 runtime system as it comes with
|
||||
the cc65 C compiler. It describes the memory layout, CBM 510 specific header
|
||||
files, available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that CBM 510 specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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.
|
||||
|
||||
In addition to the Commodore 510 (named P128 in the U.S.), no other
|
||||
machines are supported by this cc65 target.
|
||||
|
||||
|
||||
|
||||
<sect>Binary format<p>
|
||||
|
||||
The standard binary output format generated by the linker for the Commodore
|
||||
510 target is a machine language program with a one line BASIC stub, which
|
||||
transfers control to the machine language running in bank 0. This means that a
|
||||
program can be loaded as BASIC program and started with RUN. It is of course
|
||||
possible to change this behaviour by using a modified startup file and linker
|
||||
config.
|
||||
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs for the Commodore 510 run in bank 0, the memory bank
|
||||
reserved for BASIC programs. Since there are no ROMs in this memory bank,
|
||||
kernal subroutines are either emulated or called by bank switching, which has
|
||||
the disadvantage of being slow compared to a direct call.
|
||||
|
||||
The default memory configuration for the CBM 510 allocates all memory between
|
||||
$0002 and $FFF0 in bank 0 for the compiled program. Some space
|
||||
in low memory is lost, because a separate hardware stack is set up in page 1,
|
||||
and the kernal replacement functions need some more memory locations. A few
|
||||
more pages are lost in high memory, because the runtime sets up a copy of the
|
||||
character ROM, a text screen and a CBM compatible jump table at $FF81.
|
||||
The main startup code is located at $0400, so about 54K of the complete
|
||||
bank are actually usable for applications.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $FF81 and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing CBM 510 specific code may use the <tt/cbm510.h/ or
|
||||
<tt/cbm.h/ header files. Using the later may be an option when writing code
|
||||
for more than one CBM platform, since it includes <tt/cbm510.h/ and declares
|
||||
several functions common to all CBM platforms.
|
||||
|
||||
<sect1>CBM 510 specific functions<p>
|
||||
|
||||
The functions listed below are special for the CBM 510. See the <htmlurl
|
||||
url="funcref.html" name="function reference"> for declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>peekbsys
|
||||
<item>peekwsys
|
||||
<item>pokebsys
|
||||
<item>pokewsys
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>CBM specific functions<p>
|
||||
|
||||
Some functions are available for all (or at least most) of the Commodore
|
||||
machines. See the <htmlurl url="funcref.html" name="function reference"> for
|
||||
declaration and usage.
|
||||
|
||||
|
||||
<itemize>
|
||||
<item>cbm_close
|
||||
<item>cbm_closedir
|
||||
<item>cbm_k_setlfs
|
||||
<item>cbm_k_setnam
|
||||
<item>cbm_k_load
|
||||
<item>cbm_k_save
|
||||
<item>cbm_k_open
|
||||
<item>cbm_k_close
|
||||
<item>cbm_k_readst
|
||||
<item>cbm_k_chkin
|
||||
<item>cbm_k_ckout
|
||||
<item>cbm_k_basin
|
||||
<item>cbm_k_bsout
|
||||
<item>cbm_k_clrch
|
||||
<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/cbm510.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.
|
||||
|
||||
<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can
|
||||
therefore not be accessed like on other platforms. Please use one of the
|
||||
<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to
|
||||
access the I/O chips. Direct reads and writes to the structures named below
|
||||
will <em>not</em> work!
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/VIC/</tag>
|
||||
The <tt/VIC/ structure allows access to the VIC II (the graphics
|
||||
controller). See the <tt/_vic2.h/ header file located in the include
|
||||
directory for the declaration of the structure.
|
||||
|
||||
<tag><tt/SID/</tag>
|
||||
The <tt/SID/ structure allows access to the SID (the sound interface
|
||||
device). See the <tt/_sid.h/ header file located in the include directory
|
||||
for the declaration of the structure.
|
||||
|
||||
<tag><tt/ACIA/</tag>
|
||||
Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable.
|
||||
See the <tt/_6551.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
<tag><tt/CIA/</tag>
|
||||
Access to the CIA chip is available via the <tt/CIA/ variable. See the
|
||||
<tt/_6526.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
<tag><tt/TPI1, TPI2/</tag>
|
||||
The two 6525 triport chips may be accessed by using this variable. See the
|
||||
<tt/_6525.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
</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 currently available for the Commodore 510.
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
<descrip>
|
||||
<tag><tt/cbm510-ram.emd (cbm510_ram_emd)/</tag>
|
||||
A driver for the RAM in bank 1. Supports up to 255 pages with 256 bytes
|
||||
each.
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/cbm510-std.joy (cbm510_std_joy)/</tag>
|
||||
Supports up to two standard joysticks connected to the joysticks port of
|
||||
the Commodore 510.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/cbm510-joy.mou (cbm510_joy_mou)/</tag>
|
||||
Supports a mouse that is emulated by a standard joystick, e.g. 1350
|
||||
mouse, in joystick port #2 of the CBM510. That stick's fire button acts as
|
||||
the left mouse button. The fire button of a stick in joystick port #1 can
|
||||
act as the right mouse button.
|
||||
|
||||
<tag><tt/cbm510-inkwl.mou (cbm510_inkwl_mou)/</tag>
|
||||
Supports the Inkwell Systems lightpens, connected to port #1 of the CBM510.
|
||||
It can read both the 170-C and one button of the 184-C pens. (It can
|
||||
read other lightpens and light-guns that send their button signal to the
|
||||
joystick left-button pin.)
|
||||
|
||||
</descrip><p>
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/cbm510-std.ser (cbm510_std_ser)/</tag>
|
||||
Driver for the 6551 ACIA chip built into the Commodore 510. Supports up to
|
||||
19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives.
|
||||
Note that because of the peculiarities of the 6551 chip transmits are not
|
||||
interrupt driven, and the transceiver blocks if the receiver asserts flow
|
||||
control because of a full buffer.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect>Limitations<label id="limitations"><p>
|
||||
|
||||
|
||||
<sect1>Kernal and hardware access<p>
|
||||
|
||||
Since the program runs in bank 0, and the kernal and all I/O chips are located
|
||||
in bank 15, calling ROM routines or accessing hardware needs special code. The
|
||||
cc65 runtime implements wrappers for all functions in the kernal jump table.
|
||||
While this simplifies things, it should be noted that the wrappers do have
|
||||
quite an impact on performance: A cross bank call has an extra 300µs
|
||||
penalty added by the wrapper.
|
||||
|
||||
<sect1>Interrupts<p>
|
||||
|
||||
Compiled programs contain an interrupt handler that runs in the program bank.
|
||||
This has several advantages, one of them being performance (see cross bank
|
||||
call overhead mentioned above). However, this introduces one problem:
|
||||
Interrupts are lost while the CPU executes code in the kernal bank. As a
|
||||
result, the clock may go wrong and (worse) serial interrupts may get lost.
|
||||
|
||||
Since the cc65 runtime does only call the kernal for disk I/O, this means that
|
||||
a program should not do file I/O while it depends on interrupts.
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line argument passing is currently not supported for the Commodore
|
||||
510.
|
||||
|
||||
|
||||
<sect1>Program return code<p>
|
||||
|
||||
The program return code (signed char) is passed back to BASIC by use of the
|
||||
<tt/ST/ variable.
|
||||
|
||||
|
||||
<sect1>Interrupt handlers<p>
|
||||
|
||||
The runtime for the Commodore 510 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 when they are linked into a program. See the discussion of the
|
||||
<tt/.CONDES/ feature in the <htmlurl 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>
|
||||
290
doc/cbm610.sgml
Normal file
290
doc/cbm610.sgml
Normal file
@ -0,0 +1,290 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Commodore 610 specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2003-12-16
|
||||
|
||||
<abstract>
|
||||
An overview over the Commodore 610 runtime system as it is implemented for the
|
||||
cc65 C compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the CBM 610 runtime system as it comes with
|
||||
the cc65 C compiler. It describes the memory layout, CBM 610 specific header
|
||||
files, available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that CBM 610 specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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.
|
||||
|
||||
In addition to the Commodore 610 (named B40 in the U.S.), several other
|
||||
machines are supported by this cc65 target, since they have identical
|
||||
hardware: The Commodore 620 and 630 (more memory, additional coprocessor
|
||||
card), and the Commodore 710, 720 and 730 (same hardware in another case with
|
||||
a builtin monitor).
|
||||
|
||||
|
||||
|
||||
<sect>Binary format<p>
|
||||
|
||||
The standard binary output format generated by the linker for the Commodore
|
||||
610 target is a machine language program with a one line BASIC stub, which
|
||||
transfers control to the machine language running in bank 1. This means that a
|
||||
program can be loaded as BASIC program and started with RUN. It is of course
|
||||
possible to change this behaviour by using a modified startup file and linker
|
||||
config.
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs for the Commodore 610 run in bank 1, the memory bank
|
||||
reserved for BASIC programs. Since there are no ROMs in this memory bank,
|
||||
kernal subroutines are either emulated or called by bank switching, which has
|
||||
the disadvantage of being slow compared to a direct call.
|
||||
|
||||
The default memory configuration for the CBM 610 allocates all memory between
|
||||
$0002 and $FFF0 in bank 1 for the compiled program. Some space
|
||||
in low memory is lost, because a separate hardware stack is set up in page 1,
|
||||
and the kernal replacement functions need some more memory locations. A few
|
||||
more bytes are lost in high memory, because the runtime sets up a CBM
|
||||
compatible jump table at $FF81. The main startup code is located at
|
||||
$0400, so about 63K of the complete bank are actually usable for
|
||||
applications.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $FF81 and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing CBM 610 specific code may use the <tt/cbm610.h/ or
|
||||
<tt/cbm.h/ header files. Using the later may be an option when writing code
|
||||
for more than one CBM platform, since it includes <tt/cbm610.h/ and declares
|
||||
several functions common to all CBM platforms.
|
||||
|
||||
<sect1>CBM 610 specific functions<p>
|
||||
|
||||
The functions listed below are special for the CBM 610. See the <htmlurl
|
||||
url="funcref.html" name="function reference"> for declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>peekbsys
|
||||
<item>peekwsys
|
||||
<item>pokebsys
|
||||
<item>pokewsys
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>CBM specific functions<p>
|
||||
|
||||
Some functions are available for all (or at least most) of the Commodore
|
||||
machines. See the <htmlurl url="funcref.html" name="function reference"> for
|
||||
declaration and usage.
|
||||
|
||||
|
||||
<itemize>
|
||||
<item>cbm_close
|
||||
<item>cbm_closedir
|
||||
<item>cbm_k_setlfs
|
||||
<item>cbm_k_setnam
|
||||
<item>cbm_k_load
|
||||
<item>cbm_k_save
|
||||
<item>cbm_k_open
|
||||
<item>cbm_k_close
|
||||
<item>cbm_k_readst
|
||||
<item>cbm_k_chkin
|
||||
<item>cbm_k_ckout
|
||||
<item>cbm_k_basin
|
||||
<item>cbm_k_bsout
|
||||
<item>cbm_k_clrch
|
||||
<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/cbm610.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.
|
||||
|
||||
<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can
|
||||
therefore not be accessed like on other platforms. Please use one of the
|
||||
<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to
|
||||
access the I/O chips. Direct reads and writes to the structures named below
|
||||
will <em>not</em> work!
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/CRTC/</tag>
|
||||
The <tt/CRTC/ structure allows access to the CRTC (the video controller).
|
||||
See the <tt/_6545.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
<tag><tt/SID/</tag> The <tt/SID/ structure allows access to the SID (the
|
||||
sound interface device). See the <tt/_sid.h/ header file located in the
|
||||
include directory for the declaration of the structure.
|
||||
|
||||
<tag><tt/ACIA/</tag>
|
||||
Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable.
|
||||
See the <tt/_6551.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
<tag><tt/CIA/</tag>
|
||||
Access to the CIA chip is available via the <tt/CIA/ variable. See the
|
||||
<tt/_6526.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
<tag><tt/TPI1, TPI2/</tag>
|
||||
The two 6525 triport chips may be accessed by using this variable. See the
|
||||
<tt/_6525.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
</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 currently available for the Commodore 610 (and since
|
||||
the machine has no graphics capabilities, chances for a graphics driver aren't
|
||||
really good:-).
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
<descrip>
|
||||
<tag><tt/cbm610-ram.emd (cbm610_ram_emd)/</tag>
|
||||
A driver for the RAM in bank 2. Supports up to 255 pages with 256 bytes
|
||||
each.
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
The Commodore 610 is a business machine and doesn't have joystick ports. There
|
||||
are no drivers for the non existing ports available.
|
||||
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the Commodore 610.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/cbm610-std.ser (cbm610_std_ser)/</tag>
|
||||
Driver for the 6551 ACIA chip built into the Commodore 610. Supports up to
|
||||
19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives.
|
||||
Note that because of the peculiarities of the 6551 chip transmits are not
|
||||
interrupt driven, and the transceiver blocks if the receiver asserts flow
|
||||
control because of a full buffer.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect>Limitations<label id="limitations"><p>
|
||||
|
||||
|
||||
<sect1>Kernal and hardware access<p>
|
||||
|
||||
Since the program runs in bank 1, and the kernal and all I/O chips are located
|
||||
in bank 15, calling ROM routines or accessing hardware needs special code. The
|
||||
cc65 runtime implements wrappers for all functions in the kernal jump table.
|
||||
While this simplifies things, it should be noted that the wrappers do have
|
||||
quite an impact on performance: A cross bank call has an extra 300µs
|
||||
penalty added by the wrapper.
|
||||
|
||||
<sect1>Interrupts<p>
|
||||
|
||||
Compiled programs contain an interrupt handler that runs in the program bank.
|
||||
This has several advantages, one of them being performance (see cross bank
|
||||
call overhead mentioned above). However, this introduces one problem:
|
||||
Interrupts are lost while the CPU executes code in the kernal bank. As a
|
||||
result, the clock may go wrong and (worse) serial interrupts may get lost.
|
||||
|
||||
Since the cc65 runtime does only call the kernal for disk I/O, this means that
|
||||
a program should not do file I/O while it depends on interrupts.
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line argument passing is currently not supported for the Commodore
|
||||
610.
|
||||
|
||||
|
||||
<sect1>Program return code<p>
|
||||
|
||||
The program return code (low byte) is passed back to BASIC by use of the
|
||||
<tt/ST/ variable.
|
||||
|
||||
|
||||
<sect1>Interrupt handlers<p>
|
||||
|
||||
The runtime for the Commodore 610 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 when they are linked into a program. See the discussion of the
|
||||
<tt/.CONDES/ feature in the <htmlurl 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>
|
||||
1389
doc/cc65.sgml
Normal file
1389
doc/cc65.sgml
Normal file
File diff suppressed because it is too large
Load Diff
307
doc/cl65.sgml
Normal file
307
doc/cl65.sgml
Normal file
@ -0,0 +1,307 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>cl65 Users Guide
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>01.08.2000, 27.11.2000, 02.10.2001
|
||||
|
||||
<abstract>
|
||||
cl65 is the compile & link utility for cc65, the 6502 C compiler. It was
|
||||
designed as a smart frontend for the C compiler (cc65), the assembler (ca65),
|
||||
the object file converter (co65), and the linker (ld65).
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
cl65 is a frontend for cc65, ca65, co65 and ld65. While you may not use the
|
||||
full power of the tools when calling them through cl65, most features are
|
||||
available, and the use of cl65 is much simpler.
|
||||
|
||||
|
||||
<sect>Basic Usage<p>
|
||||
|
||||
The cl65 compile and link utility may be used to convert, compile, assemble
|
||||
and link files. While the separate tools do just one step, cl65 knows how to
|
||||
build object files from C files (by calling the compiler, then the assembler)
|
||||
and other things.
|
||||
|
||||
<tscreen><verb>
|
||||
---------------------------------------------------------------------------
|
||||
Usage: cl65 [options] file [...]
|
||||
Short options:
|
||||
-c Compile and assemble but don't link
|
||||
-d Debug mode
|
||||
-g Add debug info
|
||||
-h Help (this text)
|
||||
-l name Create an assembler listing file
|
||||
-m name Create a map file
|
||||
-mm model Set the memory model
|
||||
-o name Name the output file
|
||||
-r Enable register variables
|
||||
-t sys Set the target system
|
||||
-u sym Force an import of symbol `sym'
|
||||
-v Verbose mode
|
||||
-vm Verbose map file
|
||||
-C name Use linker config file
|
||||
-Cl Make local variables static
|
||||
-D sym[=defn] Define a preprocessor symbol
|
||||
-I dir Set a compiler include directory path
|
||||
-L path Specify a library search path
|
||||
-Ln name Create a VICE label file
|
||||
-O Optimize code
|
||||
-Oi Optimize code, inline functions
|
||||
-Or Optimize code, honour the register keyword
|
||||
-Os Optimize code, inline known C funtions
|
||||
-S Compile but don't assemble and link
|
||||
-T Include source as comment
|
||||
-V Print the version number
|
||||
-W name[,...] Supress compiler warnings
|
||||
-Wa options Pass options to the assembler
|
||||
-Wl options Pass options to the linker
|
||||
|
||||
Long options:
|
||||
--add-source Include source as comment
|
||||
--asm-args options Pass options to the assembler
|
||||
--asm-define sym[=v] Define an assembler symbol
|
||||
--asm-include-dir dir Set an assembler include directory
|
||||
--bin-include-dir dir Set an assembler binary include directory
|
||||
--bss-label name Define and export a BSS segment label
|
||||
--bss-name seg Set the name of the BSS segment
|
||||
--cc-args options Pass options to the compiler
|
||||
--cfg-path path Specify a config file search path
|
||||
--check-stack Generate stack overflow checks
|
||||
--code-label name Define and export a CODE segment label
|
||||
--code-name seg Set the name of the CODE segment
|
||||
--codesize x Accept larger code by factor x
|
||||
--config name Use linker config file
|
||||
--cpu type Set cpu type
|
||||
--create-dep name Create a make dependency file
|
||||
--create-full-dep name Create a full make dependency file
|
||||
--data-label name Define and export a DATA segment label
|
||||
--data-name seg Set the name of the DATA segment
|
||||
--debug Debug mode
|
||||
--debug-info Add debug info
|
||||
--feature name Set an emulation feature
|
||||
--force-import sym Force an import of symbol `sym'
|
||||
--help Help (this text)
|
||||
--include-dir dir Set a compiler include directory path
|
||||
--ld-args options Pass options to the linker
|
||||
--lib file Link this library
|
||||
--lib-path path Specify a library search path
|
||||
--list-targets List all available targets
|
||||
--listing name Create an assembler listing file
|
||||
--list-bytes n Number of bytes per assembler listing line
|
||||
--mapfile name Create a map file
|
||||
--memory-model model Set the memory model
|
||||
--module Link as a module
|
||||
--module-id id Specify a module id for the linker
|
||||
--o65-model model Override the o65 model
|
||||
--obj file Link this object file
|
||||
--obj-path path Specify an object file search path
|
||||
--register-space b Set space available for register variables
|
||||
--register-vars Enable register variables
|
||||
--rodata-name seg Set the name of the RODATA segment
|
||||
--signed-chars Default characters are signed
|
||||
--standard std Language standard (c89, c99, cc65)
|
||||
--start-addr addr Set the default start address
|
||||
--static-locals Make local variables static
|
||||
--target sys Set the target system
|
||||
--version Print the version number
|
||||
--verbose Verbose mode
|
||||
--zeropage-label name Define and export a ZEROPAGE segment label
|
||||
--zeropage-name seg Set the name of the ZEROPAGE segment
|
||||
---------------------------------------------------------------------------
|
||||
</verb></tscreen>
|
||||
|
||||
Most of the options have the same meaning than the corresponding compiler,
|
||||
assembler or linker option. See the documentation for these tools for an
|
||||
explanation. If an option is available for more than one of the tools, it
|
||||
is set for all tools, where it is available. One example for this is <tt/-v/:
|
||||
The compiler, the assembler and the linker are all called with the <tt/-v/
|
||||
switch.
|
||||
|
||||
There are a few remaining options that control the behaviour of cl65:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt>-S</tt></tag>
|
||||
|
||||
This option forces cl65 to stop after the assembly step. This means that
|
||||
C files are translated into assembler files, but nothing more is done.
|
||||
Assembler files, object files and libraries given on the command line
|
||||
are ignored.
|
||||
|
||||
|
||||
<tag><tt>-c</tt></tag>
|
||||
|
||||
This options forces cl65 to stop after the assembly step. This means
|
||||
that C and assembler files given on the command line are translated into
|
||||
object files, but there is no link step, and object files and libraries
|
||||
given on the command line are ignored.
|
||||
|
||||
|
||||
<tag><tt>-o name</tt></tag>
|
||||
|
||||
The -o option is used for the target name in the final step. This causes
|
||||
problems, if the linker will not be called, and there are several input
|
||||
files on the command line. In this case, the name given with -o will be
|
||||
used for all of them, which makes the option pretty useless. You
|
||||
shouldn't use -o when more than one output file is created.
|
||||
|
||||
|
||||
<tag><tt>-t sys, --target sys</tt></tag>
|
||||
|
||||
The default for this option is different from the compiler and linker in the
|
||||
case that the option is missing: While the other tools (compiler, assembler
|
||||
and linker) will use the "none" system settings by default, cl65 will use
|
||||
the C64 as a target system by default. This was chosen since most people
|
||||
seem to use cc65 to develop for the C64.
|
||||
|
||||
<tag><tt>-Wa options, --asm-args options</tt></tag>
|
||||
|
||||
Pass options directly to the assembler. This may be used to pass options
|
||||
that aren't directly supported by cl65. Several options may be separated by
|
||||
commas, the commas are replaced by spaces when passing them to the
|
||||
assembler. Beware: Passing arguments directly to the assembler may interfere
|
||||
with some of the defaults, because cl65 doesn't parse the options passed. So
|
||||
if cl65 supports an option by itself, do not pass this option to the
|
||||
assembler by means of the <tt/-Wa/ switch.
|
||||
|
||||
<tag><tt>-Wc options, --cc-args options</tt></tag>
|
||||
|
||||
Pass options directly to the compiler. This may be used to pass options
|
||||
that aren't directly supported by cl65. Several options may be separated by
|
||||
commas, the commas are replaced by spaces when passing them to the
|
||||
compiler. Beware: Passing arguments directly to the compiler may interfere
|
||||
with some of the defaults, because cl65 doesn't parse the options passed. So
|
||||
if cl65 supports an option by itself, do not pass this option to the
|
||||
compiler by means of the <tt/-Wc/ switch.
|
||||
|
||||
<tag><tt>-Wl options, --ld-args options</tt></tag>
|
||||
|
||||
Pass options directly to the linker. This may be used to pass options that
|
||||
aren't directly supported by cl65. Several options may be separated by
|
||||
commas, the commas are replaced by spaces when passing them to the linker.
|
||||
Beware: Passing arguments directly to the linker may interfere with some of
|
||||
the defaults, because cl65 doesn't parse the options passed. So if cl65
|
||||
supports an option by itself, do not pass this option to the linker by means
|
||||
of the <tt/-Wl/ switch.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
|
||||
<sect>More usage<p>
|
||||
|
||||
Since cl65 was created to simplify the use of the cc65 development
|
||||
package, it tries to be smart about several things.
|
||||
|
||||
<itemize>
|
||||
|
||||
<item> If you don't give a target system on the command line, cl65
|
||||
defaults to the C64.
|
||||
|
||||
<item> When linking, cl65 will supply the names of the startup file and
|
||||
library for the target system to the linker, so you don't have to do
|
||||
that.
|
||||
|
||||
<item> If the final step is the linker, and the name of the output file was
|
||||
not explicitly given, cl65 will use the name of the first input file
|
||||
without the extension, provided that the name of this file has an
|
||||
extension. So you don't need to name the executable name in most
|
||||
cases, just give the name of your "main" file as first input file.
|
||||
</itemize>
|
||||
|
||||
The command line is parsed from left to right, and the actual processing tool
|
||||
(compiler, assembler, ...) is invoked whenever a file name is encountered.
|
||||
This means that only the options to the left of a file name are in effect when
|
||||
this file is processed. It does also mean that you're able to specify
|
||||
different options for different files on the command line. As an example.
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -Oirs main.c -O -g module.c
|
||||
</verb></tscreen>
|
||||
|
||||
translates main.c with full optimization and module.c with less optimization
|
||||
and debug info enabled.
|
||||
|
||||
The type of an input file is derived from its extension:
|
||||
|
||||
<itemize>
|
||||
<item>C files: <tt/.c/
|
||||
<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/
|
||||
<item>Object files: <tt/.o/ <tt/.obj/
|
||||
<item>Libraries: <tt/.a/, <tt/.lib/
|
||||
<item>GEOS resource files: <tt/.grc/
|
||||
<item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/
|
||||
</itemize>
|
||||
|
||||
Please note that the program cannot handle input files with unknown file
|
||||
extensions.
|
||||
|
||||
|
||||
<sect>Examples<p>
|
||||
|
||||
The morse trainer software, which consists of one C file (morse.c) and one
|
||||
assembler file (irq.s) will need the following separate steps to compile
|
||||
into an executable named morse:
|
||||
|
||||
<tscreen><verb>
|
||||
cc65 -g -Oi -t c64 morse.c
|
||||
ca65 -g morse.s
|
||||
ca65 -g irq.s
|
||||
ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib
|
||||
</verb></tscreen>
|
||||
|
||||
When using cl65, this is simplified to
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -g -Oi morse.c irq.s
|
||||
</verb></tscreen>
|
||||
|
||||
As a general rule, you may use cl65 instead of cc65 at most times,
|
||||
especially in makefiles to build object files directly from C files. Use
|
||||
|
||||
<tscreen><verb>
|
||||
.c.o:
|
||||
cl65 -g -Oi $<
|
||||
</verb></tscreen>
|
||||
|
||||
to do this.
|
||||
|
||||
|
||||
|
||||
<sect>Copyright<p>
|
||||
|
||||
cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von
|
||||
Bassewitz. For usage of the binaries and/or sources the following
|
||||
conditions do apply:
|
||||
|
||||
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>
|
||||
|
||||
344
doc/co65.sgml
Normal file
344
doc/co65.sgml
Normal file
@ -0,0 +1,344 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>co65 Users Guide
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>12.02.2003
|
||||
|
||||
<abstract>
|
||||
co65 is an object file conversion utility. It converts o65 object files into
|
||||
the native object file format used by the cc65 tool chain. Since o65 is the
|
||||
file format used by cc65 for loadable drivers, the co65 utility allows (among
|
||||
other things) to link drivers statically to the generated executables instead
|
||||
of loading them from disk.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
co65 is an object file conversion utility. It converts o65 object files into
|
||||
assembler files, which may be translated by ca65 to generate object files in
|
||||
the native object file format used by the cc65 tool chain.
|
||||
|
||||
Since loadable drivers used by the library that comes with cc65 use the o65
|
||||
relocatable object code format, using the co65 utility allows to link these
|
||||
drivers statically. This enables the use of these drivers without loading
|
||||
additional files from a disk or other secondary storage.
|
||||
|
||||
Another use would be to link object files generated by other development tools
|
||||
to projects using the cc65 tool chain, but this has not been tested until now,
|
||||
since such tools are currently rare.
|
||||
|
||||
|
||||
|
||||
<sect>Usage<p>
|
||||
|
||||
The co65 utility converts one o65 file per run into one assembler files in
|
||||
ca65 format. The utility tries to autodetect the type of the o65 input file
|
||||
using the operating system identifier contained in the o65 option list.
|
||||
|
||||
|
||||
<sect1>Command line option overview<p>
|
||||
|
||||
The converter may be called as follows:
|
||||
|
||||
<tscreen><verb>
|
||||
---------------------------------------------------------------------------
|
||||
Usage: co65 [options] file
|
||||
Short options:
|
||||
-V Print the version number
|
||||
-g Add debug info to object file
|
||||
-h Help (this text)
|
||||
-m model Override the o65 model
|
||||
-n Don't generate an output file
|
||||
-o name Name the output file
|
||||
-v Increase verbosity
|
||||
|
||||
Long options:
|
||||
--bss-label name Define and export a BSS segment label
|
||||
--bss-name seg Set the name of the BSS segment
|
||||
--code-label name Define and export a CODE segment label
|
||||
--code-name seg Set the name of the CODE segment
|
||||
--data-label name Define and export a DATA segment label
|
||||
--data-name seg Set the name of the DATA segment
|
||||
--debug-info Add debug info to object file
|
||||
--help Help (this text)
|
||||
--no-output Don't generate an output file
|
||||
--o65-model model Override the o65 model
|
||||
--verbose Increase verbosity
|
||||
--version Print the version number
|
||||
--zeropage-label name Define and export a ZEROPAGE segment label
|
||||
--zeropage-name seg Set the name of the ZEROPAGE segment
|
||||
---------------------------------------------------------------------------
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<sect1>Command line options in detail<p>
|
||||
|
||||
Here is a description of all the command line options:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt>--bss-label name</tt></tag>
|
||||
|
||||
Set the label used to mark the start of the bss segment. When this option is
|
||||
given, the label is also exported and may be accessed from other code. When
|
||||
accessing such a label from C code, be sure to include the leading
|
||||
underscore. If you don't need to access the bss segment, there's no need to
|
||||
use this option.
|
||||
|
||||
|
||||
<tag><tt>--bss-name seg</tt></tag>
|
||||
|
||||
Set the name of the bss segment. The default name is "BSS" which is
|
||||
compatible with the standard ld65 linker configurations.
|
||||
|
||||
|
||||
<tag><tt>--code-label name</tt></tag>
|
||||
|
||||
Set the label used to mark the start of the code segment. When this option
|
||||
is given, the label is also exported and may be accessed from other code.
|
||||
When accessing such a label from C code, be sure to include the leading
|
||||
underscore. If you don't need to access the code segment, there's no need to
|
||||
use this option.
|
||||
|
||||
|
||||
<tag><tt>--code-name seg</tt></tag>
|
||||
|
||||
Set the name of the code segment. The default name is "CODE" which is
|
||||
compatible with the standard ld65 linker configurations.
|
||||
|
||||
|
||||
<tag><tt>--data-label name</tt></tag>
|
||||
|
||||
Set the label used to mark the start of the data segment. When this option
|
||||
is given, the label is also exported and may be accessed from other code.
|
||||
When accessing such a label from C code, be sure to include the leading
|
||||
underscore. If you don't need to access the data segment, there's no need to
|
||||
use this option.
|
||||
|
||||
|
||||
<tag><tt>--data-name seg</tt></tag>
|
||||
|
||||
Set the name of the data segment. The default name is "DATA" which is
|
||||
compatible with the standard ld65 linker configurations.
|
||||
|
||||
|
||||
<tag><tt>-d, --debug</tt></tag>
|
||||
|
||||
Enables debug mode, something that should not be needed for mere mortals.
|
||||
Currently the converter does only accept cc65 loadable modules generated by
|
||||
ld65 when not in debug mode. Please note that correct conversion has never
|
||||
been tested for o65 files from other sources, so be careful when using
|
||||
<tt/-d/.
|
||||
|
||||
|
||||
<tag><tt>-g, --debug-info</tt></tag>
|
||||
|
||||
This will cause the converter to insert a <tt/.DEBUGINFO/ command into the
|
||||
generated assembler code. This will cause the assembler to include all
|
||||
symbols in a special section in the object file.
|
||||
|
||||
|
||||
<tag><tt>-h, --help</tt></tag>
|
||||
|
||||
Print the short option summary shown above.
|
||||
|
||||
|
||||
<tag><tt>-m model, --o65-model model</tt></tag>
|
||||
|
||||
Set an o65 model. This option changes the way, output is generated for the
|
||||
given o65 file. For example, cc65 loadable drivers have a zero page segment,
|
||||
but this segment must not be defined in the file itself, because the
|
||||
standard module loader will overlay it with the zeropage space used by the
|
||||
application that loads this module. So instead of allocating space in the
|
||||
zero page segment, the converter will reference the start of the zero page
|
||||
area used by the application.
|
||||
|
||||
Currently, the following models are defined:
|
||||
|
||||
<itemize>
|
||||
<item>lunix
|
||||
<item>os/a65
|
||||
<item>cc65-module
|
||||
</itemize>
|
||||
|
||||
The default is to autodetect the model to use from the input file, so
|
||||
there's rarely a need to use this option.
|
||||
|
||||
|
||||
<tag><tt>-n, --no-output</tt></tag>
|
||||
|
||||
Don't do the actual conversion, just read in the o65 file checking for
|
||||
problems. This option may be used in conjunction with <tt/--verbose/ to
|
||||
view some information about the input file.
|
||||
|
||||
|
||||
<tag><tt>-o name</tt></tag>
|
||||
|
||||
Specify the name of the output file. If you don't specify a name, the
|
||||
name of the o65 input file is used, with the extension replaced by ".s".
|
||||
|
||||
|
||||
<tag><tt>-v, --verbose</tt></tag>
|
||||
|
||||
Using this option, the converter will be somewhat more verbose and print
|
||||
some information about the o65 input file (among other things). You may use
|
||||
this option together with <tt/--no-output/ to just get the o65 info.
|
||||
|
||||
|
||||
<tag><tt>-V, --version</tt></tag>
|
||||
|
||||
Print the version number of the compiler. When submitting a bug report,
|
||||
please include the operating system you're using, and the compiler
|
||||
version.
|
||||
|
||||
|
||||
<tag><tt>--zeropage-label name</tt></tag>
|
||||
|
||||
Set the label used to mark the start of the zeropage segment. When this
|
||||
option is given, the label is also exported and may be accessed from other
|
||||
code. When accessing such a label from C code, be sure to include the
|
||||
leading underscore. If you don't need to access the zeropage segment,
|
||||
there's no need to use this option.
|
||||
|
||||
|
||||
<tag><tt>--zeropage-name seg</tt></tag>
|
||||
|
||||
Set the name of the zeropage segment. The default name is "ZEROPAGE" which is
|
||||
compatible with the standard ld65 linker configurations.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect>Input and output<p>
|
||||
|
||||
The converter will accept one o65 file per invocation and create a file with
|
||||
the same base name, but with the extension replaced by ".s". The output
|
||||
file contains assembler code suitable for the use with the ca65 macro
|
||||
assembler.
|
||||
|
||||
|
||||
<sect>Converting loadable drivers<p>
|
||||
|
||||
<sect1>Differences between static linking and runtime loading<p>
|
||||
|
||||
One main use of the utility is conversion of loadable drivers, so they may be
|
||||
linked statically to an application. Statically linking will cause a few
|
||||
things to be different from runtime loading:
|
||||
|
||||
<itemize>
|
||||
|
||||
<item> Without changing the segment names, all segments take the default
|
||||
names used by the standard linker configurations. This means that the
|
||||
driver code is no longer contingous in memory, instead the code
|
||||
segment is placed somewhere in between all other code segments, the
|
||||
data segment is placed with all other data segments and so on. If the
|
||||
driver doesn't do strange things this shouldn't be a problem.
|
||||
|
||||
<item> With statically linked code, data and bss segments will get intialized
|
||||
once (when the application is loaded), while a loadable driver will
|
||||
get its initialization each time the driver is loaded into memory
|
||||
(which may be more than once in the lifetime of a program). It depends
|
||||
on the driver if this is a problem. Currently, most drivers supplied
|
||||
with cc65 behave correctly when linked statically.
|
||||
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect1>Additional requirements<p>
|
||||
|
||||
All loadable drivers used by cc65 have a header and a jump table at the start
|
||||
of the code segment. The header is needed to detect the driver (it may also
|
||||
contain some data that is necessary to access the driver). The jump table is
|
||||
used to access the functions in the driver code.
|
||||
|
||||
When loading a driver at runtime, the load address of the driver is also the
|
||||
address of the code segment, so the locations of the header and jump table are
|
||||
known. However, when linking the driver statically, it is up to the programmer
|
||||
to provide this information to the driver API.
|
||||
|
||||
For this purpose, it is necessary to define a code segment label that can be
|
||||
accessed from the outside later. Please note that the converter does currently
|
||||
<em/not/ create such a label without being ordered to do so, even if the input
|
||||
file is a cc65 module.
|
||||
|
||||
To create such a label, use the <tt/--code-label/ option when calling the
|
||||
converter. Be sure to begin the label with a leading underscore when accessing
|
||||
it from C code. In your code, define an arbitrary variable with this name. Use
|
||||
the address of this variable as the address of the code segment of the driver.
|
||||
Be sure to never modify the variable which is in reality the start of your
|
||||
driver!
|
||||
|
||||
|
||||
<sect1>Example - Convert and link a graphics driver<p>
|
||||
|
||||
As an example, here are some instructions to convert and use the c64-hi.tgi
|
||||
graphics driver:
|
||||
|
||||
First, convert the driver, generating a label named "_c64_hi" for the code
|
||||
segment. Use the assembler to generate an object file from the assembler
|
||||
output.
|
||||
|
||||
<tscreen><verb>
|
||||
co65 --code-label _c64_hi c64-hi.tgi
|
||||
ca65 c64-hi.s
|
||||
</verb></tscreen>
|
||||
|
||||
Next, change your C code to declare a variable that is actually the address
|
||||
of the driver:
|
||||
|
||||
<tscreen><verb>
|
||||
extern void c64_hi[];
|
||||
</verb></tscreen>
|
||||
|
||||
Instead of loading and unloading the driver, change the code to install and
|
||||
uninstall the driver, which will be already in memory after linking:
|
||||
|
||||
<tscreen><verb>
|
||||
/* Install the driver */
|
||||
tgi_install (c64_hi);
|
||||
|
||||
...
|
||||
|
||||
/* Uninstall the driver */
|
||||
tgi_uninstall ();
|
||||
</verb></tscreen>
|
||||
|
||||
Don't forget to link the driver object file to your application, otherwise you
|
||||
will get an "undefined external" error for the _c64_hi symbol.
|
||||
|
||||
|
||||
|
||||
|
||||
<sect>Copyright<p>
|
||||
|
||||
co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries
|
||||
and/or sources the following conditions apply:
|
||||
|
||||
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>
|
||||
|
||||
308
doc/coding.sgml
Normal file
308
doc/coding.sgml
Normal file
@ -0,0 +1,308 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>cc65 coding hints
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2000-12-03, 2009-09-01
|
||||
|
||||
<abstract>
|
||||
How to generate the most effective code with cc65.
|
||||
</abstract>
|
||||
|
||||
|
||||
|
||||
<sect>Use prototypes<p>
|
||||
|
||||
This will not only help to find errors between separate modules, it will also
|
||||
generate better code, since the compiler must not assume that a variable sized
|
||||
parameter list is in place and must not pass the argument count to the called
|
||||
function. This will lead to shorter and faster code.
|
||||
|
||||
|
||||
|
||||
<sect>Don't declare auto variables in nested function blocks<p>
|
||||
|
||||
Variable declarations in nested blocks are usually a good thing. But with
|
||||
cc65, there is a drawback: Since the compiler generates code in one pass, it
|
||||
must create the variables on the stack each time the block is entered and
|
||||
destroy them when the block is left. This causes a speed penalty and larger
|
||||
code.
|
||||
|
||||
|
||||
|
||||
<sect>Remember that the compiler does no high level optimizations<p>
|
||||
|
||||
The compiler needs hints from you about the code to generate. It will try to
|
||||
optimize the generated code, but follow the outline you gave in your C
|
||||
program. So for example, when accessing indexed data structures, get a pointer
|
||||
to the element and use this pointer instead of calculating the index again and
|
||||
again. If you want to have your loops unrolled, or loop invariant code moved
|
||||
outside the loop, you have to do that yourself.
|
||||
|
||||
|
||||
|
||||
<sect>Longs are slow!<p>
|
||||
|
||||
While long support is necessary for some things, it's really, really slow on
|
||||
the 6502. Remember that any long variable will use 4 bytes of memory, and any
|
||||
operation works on double the data compared to an int.
|
||||
|
||||
|
||||
|
||||
<sect>Use unsigned types wherever possible<p>
|
||||
|
||||
The 6502 CPU has no opcodes to handle signed values greater than 8 bit. So
|
||||
sign extension, test of signedness etc. has to be done with extra code. As a
|
||||
consequence, the code to handle signed operations is usually a bit larger and
|
||||
slower than the same code for unsigned types.
|
||||
|
||||
|
||||
|
||||
<sect>Use chars instead of ints if possible<p>
|
||||
|
||||
While in arithmetic operations, chars are immidiately promoted to ints, they
|
||||
are passed as chars in parameter lists and are accessed as chars in variables.
|
||||
The code generated is usually not much smaller, but it is faster, since
|
||||
accessing chars is faster. For several operations, the generated code may be
|
||||
better if intermediate results that are known not to be larger than 8 bit are
|
||||
casted to chars.
|
||||
|
||||
You should especially use unsigned chars for loop control variables if the
|
||||
loop is known not to execute more than 255 times.
|
||||
|
||||
|
||||
|
||||
<sect>Make the size of your array elements one of 1, 2, 4, 8<p>
|
||||
|
||||
When indexing into an array, the compiler has to calculate the byte offset
|
||||
into the array, which is the index multiplied by the size of one element. When
|
||||
doing the multiplication, the compiler will do a strength reduction, that is,
|
||||
replace the multiplication by a shift if possible. For the values 2, 4 and 8,
|
||||
there are even more specialized subroutines available. So, array access is
|
||||
fastest when using one of these sizes.
|
||||
|
||||
|
||||
|
||||
<sect>Expressions are evaluated from left to right<p>
|
||||
|
||||
Since cc65 is not building an explicit expression tree when parsing an
|
||||
expression, constant subexpressions may not be detected and optimized properly
|
||||
if you don't help. Look at this example:
|
||||
|
||||
<tscreen><verb>
|
||||
#define OFFS 4
|
||||
int i;
|
||||
i = i + OFFS + 3;
|
||||
</verb></tscreen>
|
||||
|
||||
The expression is parsed from left to right, that means, the compiler sees 'i',
|
||||
and puts it contents into the secondary register. Next is OFFS, which is
|
||||
constant. The compiler emits code to add a constant to the secondary register.
|
||||
Same thing again for the constant 3. So the code produced contains a fetch
|
||||
of 'i', two additions of constants, and a store (into 'i'). Unfortunately, the
|
||||
compiler does not see, that "OFFS + 3" is a constant for itself, since it does
|
||||
its evaluation from left to right. There are some ways to help the compiler
|
||||
to recognize expression like this:
|
||||
|
||||
<enum>
|
||||
|
||||
<item>Write "i = OFFS + 3 + i;". Since the first and second operand are
|
||||
constant, the compiler will evaluate them at compile time reducing the code to
|
||||
a fetch, one addition (secondary + constant) and one store.
|
||||
|
||||
<item>Write "i = i + (OFFS + 3)". When seeing the opening parenthesis, the
|
||||
compiler will start a new expression evaluation for the stuff in the braces,
|
||||
and since all operands in the subexpression are constant, it will detect this
|
||||
and reduce the code to one fetch, one addition and one store.
|
||||
|
||||
</enum>
|
||||
|
||||
|
||||
<sect>Use the preincrement and predecrement operators<p>
|
||||
|
||||
The compiler is not always smart enough to figure out, if the rvalue of an
|
||||
increment is used or not. So it has to save and restore that value when
|
||||
producing code for the postincrement and postdecrement operators, even if this
|
||||
value is never used. To avoid the additional overhead, use the preincrement
|
||||
and predecrement operators if you don't need the resulting value. That means,
|
||||
use
|
||||
|
||||
<tscreen><verb>
|
||||
...
|
||||
++i;
|
||||
...
|
||||
</verb></tscreen>
|
||||
|
||||
instead of
|
||||
|
||||
<tscreen><verb>
|
||||
...
|
||||
i++;
|
||||
...
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
|
||||
<sect>Use constants to access absolute memory locations<p>
|
||||
|
||||
The compiler produces optimized code, if the value of a pointer is a constant.
|
||||
So, to access direct memory locations, use
|
||||
|
||||
<tscreen><verb>
|
||||
#define VDC_STATUS 0xD601
|
||||
*(char*)VDC_STATUS = 0x01;
|
||||
</verb></tscreen>
|
||||
|
||||
That will be translated to
|
||||
|
||||
<tscreen><verb>
|
||||
lda #$01
|
||||
sta $D601
|
||||
</verb></tscreen>
|
||||
|
||||
The constant value detection works also for struct pointers and arrays, if the
|
||||
subscript is a constant. So
|
||||
|
||||
<tscreen><verb>
|
||||
#define VDC ((unsigned char*)0xD600)
|
||||
#define STATUS 0x01
|
||||
VDC[STATUS] = 0x01;
|
||||
</verb></tscreen>
|
||||
|
||||
will also work.
|
||||
|
||||
If you first load the constant into a variable and use that variable to access
|
||||
an absolute memory location, the generated code will be much slower, since the
|
||||
compiler does not know anything about the contents of the variable.
|
||||
|
||||
|
||||
|
||||
<sect>Use initialized local variables<p>
|
||||
|
||||
Initialization of local variables when declaring them gives shorter and faster
|
||||
code. So, use
|
||||
|
||||
<tscreen><verb>
|
||||
int i = 1;
|
||||
</verb></tscreen>
|
||||
|
||||
instead of
|
||||
|
||||
<tscreen><verb>
|
||||
int i;
|
||||
i = 1;
|
||||
</verb></tscreen>
|
||||
|
||||
But beware: To maximize your savings, don't mix uninitialized and initialized
|
||||
variables. Create one block of initialized variables and one of uniniitalized
|
||||
ones. The reason for this is, that the compiler will sum up the space needed
|
||||
for uninitialized variables as long as possible, and then allocate the space
|
||||
once for all these variables. If you mix uninitialized and initialized
|
||||
variables, you force the compiler to allocate space for the uninitialized
|
||||
variables each time, it parses an initialized one. So do this:
|
||||
|
||||
<tscreen><verb>
|
||||
int i, j;
|
||||
int a = 3;
|
||||
int b = 0;
|
||||
</verb></tscreen>
|
||||
|
||||
instead of
|
||||
|
||||
<tscreen><verb>
|
||||
int i;
|
||||
int a = 3;
|
||||
int j;
|
||||
int b = 0;
|
||||
</verb></tscreen>
|
||||
|
||||
The latter will work, but will create larger and slower code.
|
||||
|
||||
|
||||
|
||||
<sect>Use the array operator [] even for pointers<p>
|
||||
|
||||
When addressing an array via a pointer, don't use the plus and dereference
|
||||
operators, but the array operator. This will generate better code in some
|
||||
common cases.
|
||||
|
||||
Don't use
|
||||
|
||||
<tscreen><verb>
|
||||
char* a;
|
||||
char b, c;
|
||||
char b = *(a + c);
|
||||
</verb></tscreen>
|
||||
|
||||
Use
|
||||
|
||||
<tscreen><verb>
|
||||
char* a;
|
||||
char b, c;
|
||||
char b = a[c];
|
||||
</verb></tscreen>
|
||||
|
||||
instead.
|
||||
|
||||
|
||||
|
||||
<sect>Use register variables with care<p>
|
||||
|
||||
Register variables may give faster and shorter code, but they do also have an
|
||||
overhead. Register variables are actually zero page locations, so using them
|
||||
saves roughly one cycle per access. The calling routine may also use register
|
||||
variables, so the old values have to be saved on function entry and restored
|
||||
on exit. Saving an d restoring has an overhead of about 70 cycles per 2 byte
|
||||
variable. It is easy to see, that - apart from the additional code that is
|
||||
needed to save and restore the values - you need to make heavy use of a
|
||||
variable to justify the overhead.
|
||||
|
||||
As a general rule: Use register variables only for pointers that are
|
||||
dereferenced several times in your function, or for heavily used induction
|
||||
variables in a loop (with several 100 accesses).
|
||||
|
||||
When declaring register variables, try to keep them together, because this
|
||||
will allow the compiler to save and restore the old values in one chunk, and
|
||||
not in several.
|
||||
|
||||
And remember: Register variables must be enabled with <tt/-r/ or <tt/-Or/.
|
||||
|
||||
|
||||
|
||||
<sect>Decimal constants greater than 0x7FFF are actually long ints<p>
|
||||
|
||||
The language rules for constant numeric values specify that decimal constants
|
||||
without a type suffix that are not in integer range must be of type long int
|
||||
or unsigned long int. So a simple constant like 40000 is of type long int!
|
||||
This is often unexpected and may cause an expression to be evaluated with 32
|
||||
bits. While in many cases the compiler takes care about it, in some places it
|
||||
can't. So be careful when you get a warning like
|
||||
|
||||
<tscreen><verb>
|
||||
test.c(7): Warning: Constant is long
|
||||
</verb></tscreen>
|
||||
|
||||
Use the <tt/U/, <tt/L/ or <tt/UL/ suffixes to tell the compiler the desired
|
||||
type of a numeric constant.
|
||||
|
||||
|
||||
|
||||
<sect>Access to parameters in variadic functions is expensive<p>
|
||||
|
||||
Since cc65 has the "wrong" calling order, the location of the fixed parameters
|
||||
in a variadic function (a function with a variable parameter list) depends on
|
||||
the number and size of variable arguments passed. Since this number and size
|
||||
is unknown at compile time, the compiler will generate code to calculate the
|
||||
location on the stack when needed.
|
||||
|
||||
Because of this additional code, accessing the fixed parameters in a variadic
|
||||
function is much more expensive than access to parameters in a "normal"
|
||||
function. Unfortunately, this additional code is also invisible to the
|
||||
programmer, so it is easy to forget.
|
||||
|
||||
As a rule of thumb, if you access such a parameter more than once, you should
|
||||
think about copying it into a normal variable and using this variable instead.
|
||||
|
||||
|
||||
</article>
|
||||
|
||||
730
doc/customizing.sgml
Normal file
730
doc/customizing.sgml
Normal file
@ -0,0 +1,730 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>Defining a Custom cc65 Target
|
||||
<author>Bruce Reidenbach
|
||||
<date>2010-02-22
|
||||
|
||||
<abstract>
|
||||
This section provides step-by-step instructions on how to use the cc65
|
||||
toolset for a custom hardware platform (a target system not currently
|
||||
supported by the cc65 library set).
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
The cc65 toolset provides a set of pre-defined libraries that allow the
|
||||
user to target the executable image to a variety of hardware platforms.
|
||||
In addition, the user can create a customized environment so that the
|
||||
executable can be targeted to a custom platform. The following
|
||||
instructions provide step-by-step instructions on how to customize the
|
||||
toolset for a target that is not supported by the standard cc65
|
||||
installation.
|
||||
|
||||
The platform used in this example is a Xilinx Field Programmable Gate
|
||||
Array (FPGA) with an embedded 65C02 core. The processor core supports
|
||||
the additional opcodes/addressing modes of the 65SC02, along with the
|
||||
STP and WAI instructions. These instructions will create a set of files
|
||||
to create a custom target, named SBC, for <bf>S</bf>ingle <bf>B</bf>oard
|
||||
<bf>C</bf>omputer.
|
||||
|
||||
<sect>System Memory Map Definition<p>
|
||||
|
||||
The targeted system uses block RAM contained on the XILINX FPGA for the
|
||||
system memory (both RAM and ROM). The block RAMs are available in
|
||||
various aspect ratios, and they will be used in this system as 2K*8
|
||||
devices. There will be two RAMs used for data storage, starting at
|
||||
location $0000 and growing upwards. There will be one ROM (realized as
|
||||
initialized RAM) used code storage, starting at location $FFFF and
|
||||
growing downwards.
|
||||
|
||||
The cc65 toolset requires a memory configuration file to define the
|
||||
memory that is available to the cc65 run-time environment, which is
|
||||
defined as follows:
|
||||
|
||||
<tscreen><code>
|
||||
MEMORY {
|
||||
ZP: start = $0, size = $100, type = rw, define = yes;
|
||||
RAM: start = $200, size = $0E00, define = yes;
|
||||
ROM: start = $F800, size = $0800, file = %O;
|
||||
}
|
||||
</code></tscreen>
|
||||
|
||||
ZP defines the available zero page locations, which in this case starts
|
||||
at $0 and has a length of $100. Keep in mind that certain systems may
|
||||
require access to some zero page locations, so the starting address may
|
||||
need to be adjusted accordingly to prevent cc65 from attempting to reuse
|
||||
those locations. Also, at a minimum, the cc65 run-time environment uses
|
||||
26 zero page locations, so the smallest zero page size that can be
|
||||
specified is $1A. The usable RAM memory area begins after the 6502
|
||||
stack storage in page 1, so it is defined as starting at location $200
|
||||
and filling the remaining 4K of space (4096 - 2 *
|
||||
256 = 3584 = $0E00). The 2K of ROM space begins at
|
||||
address $F800 and goes to $FFFF (size = $0800).
|
||||
|
||||
Next, the memory segments within the memory devices need to be defined.
|
||||
A standard segment definition is used, with one notable exception. The
|
||||
interrupt and reset vector locations need to be defined at locations
|
||||
$FFFA through $FFFF. A special segment named VECTORS is defined that
|
||||
resides at these locations. Later, the interrupt vector map will be
|
||||
created and placed in the VECTORS segment, and the linker will put these
|
||||
vectors at the proper memory locations. The segment definition is:
|
||||
|
||||
<tscreen><code>
|
||||
SEGMENTS {
|
||||
ZEROPAGE: load = ZP, type = zp, define = yes;
|
||||
DATA: load = ROM, type = rw, define = yes, run = RAM;
|
||||
BSS: load = RAM, type = bss, define = yes;
|
||||
HEAP: load = RAM, type = bss, optional = yes;
|
||||
STARTUP: load = ROM, type = ro;
|
||||
INIT: load = ROM, type = ro, optional = yes;
|
||||
CODE: load = ROM, type = ro;
|
||||
RODATA: load = ROM, type = ro;
|
||||
VECTORS: load = ROM, type = ro, start = $FFFA;
|
||||
}
|
||||
</code></tscreen>
|
||||
|
||||
The meaning of each of these segments is as follows.
|
||||
|
||||
<p><tt> ZEROPAGE: </tt>Data in page 0, defined by ZP as starting at $0 with length $100
|
||||
<p><tt> DATA: </tt>Initialized data that can be modified by the program, stored in RAM
|
||||
<p><tt> BSS: </tt>Uninitialized data stored in RAM (used for variable storage)
|
||||
<p><tt> HEAP: </tt>Uninitialized C-level heap storage in RAM, optional
|
||||
<p><tt> STARTUP: </tt>The program initialization code, stored in ROM
|
||||
<p><tt> INIT: </tt>The code needed to initialize the system, stored in ROM
|
||||
<p><tt> CODE: </tt>The program code, stored in ROM
|
||||
<p><tt> RODATA: </tt>Initialized data that cannot be modified by the program, stored in ROM
|
||||
<p><tt> VECTORS: </tt>The interrupt vector table, stored in ROM at location $FFFA
|
||||
|
||||
A note about initialized data: any variables that require an initial
|
||||
value, such as external (global) variables, require that the initial
|
||||
values be stored in the ROM code image. However, variables stored in
|
||||
ROM cannot change; therefore the data must be moved into variables that
|
||||
are located in RAM. Specifying <tt>run = RAM</tt> as part of
|
||||
the DATA segment definition will indicate that those variables will
|
||||
require their initialization value to be copied via a call to the
|
||||
<tt>copydata</tt> routine in the startup assembly code. In addition,
|
||||
there are system level variables that will need to be initialized as
|
||||
well, especially if the heap segment is used via a C-level call to
|
||||
<tt>malloc ()</tt>.
|
||||
|
||||
The final section of the definition file contains the data constructors
|
||||
and destructors used for system startup. In addition, if the heap is
|
||||
used, the maximum C-level stack size needs to be defined in order for
|
||||
the system to be able to reliably allocate blocks of memory. The stack
|
||||
size selection must be greater than the maximum amount of storage
|
||||
required to run the program, keeping in mind that the C-level subroutine
|
||||
call stack and all local variables are stored in this stack. The
|
||||
<tt>FEATURES</tt> section defines the required constructor/destructor
|
||||
attributes and the <tt>SYMBOLS</tt> section defines the stack size. The
|
||||
constructors will be run via a call to <tt>initlib</tt> in the startup
|
||||
assembly code and the destructors will be run via an assembly language
|
||||
call to <tt>donelib</tt> during program termination.
|
||||
|
||||
<tscreen><code>
|
||||
FEATURES {
|
||||
CONDES: segment = STARTUP,
|
||||
type = constructor,
|
||||
label = __CONSTRUCTOR_TABLE__,
|
||||
count = __CONSTRUCTOR_COUNT__;
|
||||
CONDES: segment = STARTUP,
|
||||
type = destructor,
|
||||
label = __DESTRUCTOR_TABLE__,
|
||||
count = __DESTRUCTOR_COUNT__;
|
||||
}
|
||||
|
||||
SYMBOLS {
|
||||
# Define the stack size for the application
|
||||
__STACKSIZE__: value = $0200, weak = yes;
|
||||
}
|
||||
</code></tscreen>
|
||||
|
||||
These definitions are placed in a file named "sbc.cfg"
|
||||
and are referred to during the ld65 linker stage.
|
||||
|
||||
<sect>Startup Code Definition<p>
|
||||
|
||||
In the cc65 toolset, a startup routine must be defined that is executed
|
||||
when the CPU is reset. This startup code is marked with the STARTUP
|
||||
segment name, which was defined in the system configuration file as
|
||||
being in read only memory. The standard convention used in the
|
||||
predefined libraries is that this code is resident in the crt0 module.
|
||||
For this custom system, all that needs to be done is to perform a little
|
||||
bit of 6502 housekeeping, set up the C-level stack pointer, initialize
|
||||
the memory storage, and call the C-level routine <tt>main ()</tt>.
|
||||
The following code was used for the crt0 module, defined in the file
|
||||
"crt0.s":
|
||||
|
||||
<tscreen><code>
|
||||
; ---------------------------------------------------------------------------
|
||||
; crt0.s
|
||||
; ---------------------------------------------------------------------------
|
||||
;
|
||||
; Startup code for cc65 (Single Board Computer version)
|
||||
|
||||
.export _init, _exit
|
||||
.import _main
|
||||
|
||||
.export __STARTUP__ : absolute = 1 ; Mark as startup
|
||||
.import __RAM_START__, __RAM_SIZE__ ; Linker generated
|
||||
|
||||
.import copydata, zerobss, initlib, donelib
|
||||
|
||||
.include "zeropage.inc"
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Place the startup code in a special segment
|
||||
|
||||
.segment "STARTUP"
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; A little light 6502 housekeeping
|
||||
|
||||
_init: LDX #$FF ; Initialize stack pointer to $01FF
|
||||
TXS
|
||||
CLD ; Clear decimal mode
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Set cc65 argument stack pointer
|
||||
|
||||
LDA #<(__RAM_START__ + __RAM_SIZE__)
|
||||
STA sp
|
||||
LDA #>(__RAM_START__ + __RAM_SIZE__)
|
||||
STA sp+1
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Initialize memory storage
|
||||
|
||||
JSR zerobss ; Clear BSS segment
|
||||
JSR copydata ; Initialize DATA segment
|
||||
JSR initlib ; Run constructors
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Call main()
|
||||
|
||||
JSR _main
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Back from main (this is also the _exit entry): force a software break
|
||||
|
||||
_exit: JSR donelib ; Run destructors
|
||||
BRK
|
||||
</code></tscreen>
|
||||
|
||||
The following discussion explains the purpose of several important
|
||||
assembler level directives in this file.
|
||||
|
||||
<tscreen><verb>
|
||||
.export _init, _exit
|
||||
</verb></tscreen>
|
||||
|
||||
This line instructs the assembler that the symbols <tt>_init</tt> and
|
||||
<tt>_exit</tt> are to be accessible from other modules. In this
|
||||
example, <tt>_init</tt> is the location that the CPU should jump to when
|
||||
reset, and <tt>_exit</tt> is the location that will be called when the
|
||||
program is finished.
|
||||
|
||||
<tscreen><verb>
|
||||
.import _main
|
||||
</verb></tscreen>
|
||||
|
||||
This line instructs the assembler to import the symbol <tt>_main</tt>
|
||||
from another module. cc65 names all C-level routines as
|
||||
{underscore}{name} in assembler, thus the <tt>main ()</tt> routine
|
||||
in C is named <tt>_main</tt> in the assembler. This is how the startup
|
||||
code will link to the C-level code.
|
||||
|
||||
<tscreen><verb>
|
||||
.export __STARTUP__ : absolute = 1 ; Mark as startup
|
||||
</verb></tscreen>
|
||||
|
||||
This line marks this code as startup code (code that is executed when
|
||||
the processor is reset), which will then be automatically linked into
|
||||
the executable code.
|
||||
|
||||
<tscreen><verb>
|
||||
.import __RAM_START__, __RAM_SIZE__ ; Linker generated
|
||||
</verb></tscreen>
|
||||
|
||||
This line imports the RAM starting address and RAM size constants, which
|
||||
are used to initialize the cc65 C-level argument stack pointer.
|
||||
|
||||
<tscreen><verb>
|
||||
.segment "STARTUP"
|
||||
</verb></tscreen>
|
||||
|
||||
This line instructs the assembler that the code is to be placed in the
|
||||
STARTUP segment of memory.
|
||||
|
||||
<tscreen><verb>
|
||||
JSR zerobss ; Clear BSS segment
|
||||
JSR copydata ; Initialize DATA segment
|
||||
JSR initlib ; Run constructors
|
||||
</verb></tscreen>
|
||||
|
||||
These three lines initialize the external (global) and system
|
||||
variables. The first line sets the BSS segment -- the memory locations
|
||||
used for external variables -- to 0. The second line copies the
|
||||
initialization value stored in ROM to the RAM locations used for
|
||||
initialized external variables. The last line runs the constructors
|
||||
that are used to initialize the system run-time variables.
|
||||
|
||||
<tscreen><verb>
|
||||
JSR _main
|
||||
</verb></tscreen>
|
||||
|
||||
This is the actual call to the C-level <tt>main ()</tt> routine,
|
||||
which is called after the startup code completes.
|
||||
|
||||
<tscreen><verb>
|
||||
_exit: JSR donelib ; Run destructors
|
||||
BRK
|
||||
</verb></tscreen>
|
||||
|
||||
This is the code that will be executed when <tt>main ()</tt>
|
||||
terminates. The first thing that must be done is run the destructors
|
||||
via a call to <tt>donelib</tt>. Then the program can terminate. In
|
||||
this example, the program is expected to run forever. Therefore, there
|
||||
needs to be a way of indicating when something has gone wrong and the
|
||||
system needs to be shut down, requiring a restart only by a hard reset.
|
||||
The BRK instruction will be used to indicate a software fault. This is
|
||||
advantageous because cc65 uses the BRK instruction as the fill byte in
|
||||
the final binary code. In addition, the hardware has been designed to
|
||||
force the data lines to $00 for all illegal memory accesses, thereby
|
||||
also forcing a BRK instruction into the CPU.
|
||||
|
||||
<sect>Custom Run-Time Library Creation<p>
|
||||
|
||||
The next step in customizing the cc65 toolset is creating a run-time
|
||||
library for the targeted hardware. The easiest way to do this is to
|
||||
modify a standard library from the cc65 distribution. In this example,
|
||||
there is no console I/O, mouse, joystick, etc. in the system, so it is
|
||||
most appropriate to use the simplest library as the base, which is for
|
||||
the Watara Supervision and is named "supervision.lib" in the
|
||||
lib directory of the distribution.
|
||||
|
||||
The only modification required is to replace the <tt>crt0</tt> module in
|
||||
the supervision.lib library with custom startup code. This is simply
|
||||
done by first copying the library and giving it a new name, compiling
|
||||
the startup code with ca65, and finally using the ar65 archiver to
|
||||
replace the module in the new library. The steps are shown below:
|
||||
|
||||
<tscreen><verb>
|
||||
$ copy "C:\Program Files\cc65\lib\supervision.lib" sbc.lib
|
||||
$ ca65 crt0.s
|
||||
$ ar65 a sbc.lib crt0.o
|
||||
</verb></tscreen>
|
||||
|
||||
<sect>Interrupt Service Routine Definition<p>
|
||||
|
||||
For this system, the CPU is put into a wait condition prior to allowing
|
||||
interrupt processing. Therefore, the interrupt service routine is very
|
||||
simple: return from all valid interrupts. However, as mentioned
|
||||
before, the BRK instruction is used to indicate a software fault, which
|
||||
will call the same interrupt service routine as the maskable interrupt
|
||||
signal IRQ. The interrupt service routine must be able to tell the
|
||||
difference between the two, and act appropriately.
|
||||
|
||||
The interrupt service routine shown below includes code to detect when a
|
||||
BRK instruction has occurred and stops the CPU from further processing.
|
||||
The interrupt service routine is in a file named
|
||||
"interrupt.s".
|
||||
|
||||
<tscreen><code>
|
||||
; ---------------------------------------------------------------------------
|
||||
; interrupt.s
|
||||
; ---------------------------------------------------------------------------
|
||||
;
|
||||
; Interrupt handler.
|
||||
;
|
||||
; Checks for a BRK instruction and returns from all valid interrupts.
|
||||
|
||||
.import _stop
|
||||
.export _irq_int, _nmi_int
|
||||
|
||||
.segment "CODE"
|
||||
|
||||
.PC02 ; Force 65C02 assembly mode
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Non-maskable interrupt (NMI) service routine
|
||||
|
||||
_nmi_int: RTI ; Return from all NMI interrupts
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Maskable interrupt (IRQ) service routine
|
||||
|
||||
_irq_int: PHX ; Save X register contents to stack
|
||||
TSX ; Transfer stack pointer to X
|
||||
PHA ; Save accumulator contents to stack
|
||||
INX ; Increment X so it points to the status
|
||||
INX ; register value saved on the stack
|
||||
LDA $100,X ; Load status register contents
|
||||
AND #$10 ; Isolate B status bit
|
||||
BNE break ; If B = 1, BRK detected
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; IRQ detected, return
|
||||
|
||||
irq: PLA ; Restore accumulator contents
|
||||
PLX ; Restore X register contents
|
||||
RTI ; Return from all IRQ interrupts
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; BRK detected, stop
|
||||
|
||||
break: JMP _stop ; If BRK is detected, something very bad
|
||||
; has happened, so stop running
|
||||
</code></tscreen>
|
||||
|
||||
The following discussion explains the purpose of several important
|
||||
assembler level directives in this file.
|
||||
|
||||
<tscreen><verb>
|
||||
.import _stop
|
||||
</verb></tscreen>
|
||||
|
||||
This line instructs the assembler to import the symbol <tt>_stop</tt>
|
||||
from another module. This routine will be called if a BRK instruction
|
||||
is encountered, signaling a software fault.
|
||||
|
||||
<tscreen><verb>
|
||||
.export _irq_int, _nmi_int
|
||||
</verb></tscreen>
|
||||
|
||||
This line instructs the assembler that the symbols <tt>_irq_int</tt> and
|
||||
<tt>_nmi_int</tt> are to be accessible from other modules. In this
|
||||
example, the address of these symbols will be placed in the interrupt
|
||||
vector table.
|
||||
|
||||
<tscreen><verb>
|
||||
.segment "CODE"
|
||||
</verb></tscreen>
|
||||
|
||||
This line instructs the assembler that the code is to be placed in the
|
||||
CODE segment of memory. Note that because there are 65C02 mnemonics in
|
||||
the assembly code, the assembler is forced to use the 65C02 instruction
|
||||
set with the <tt>.PC02</tt> directive.
|
||||
|
||||
The final step is to define the interrupt vector memory locations.
|
||||
Recall that a segment named VECTORS was defined in the memory
|
||||
configuration file, which started at location $FFFA. The addresses of
|
||||
the interrupt service routines from "interrupt.s" along with
|
||||
the address for the initialization code in crt0 are defined in a file
|
||||
named "vectors.s". Note that these vectors will be placed in
|
||||
memory in their proper little-endian format as:
|
||||
|
||||
<p><tt> $FFFA - $FFFB:</tt> NMI interrupt vector (low byte, high byte)
|
||||
<p><tt> $FFFC - $FFFD:</tt> Reset vector (low byte, high byte)
|
||||
<p><tt> $FFFE - $FFFF:</tt> IRQ/BRK interrupt vector (low byte, high byte)
|
||||
|
||||
using the <tt>.addr</tt> assembler directive. The contents of the file are:
|
||||
|
||||
<tscreen><code>
|
||||
; ---------------------------------------------------------------------------
|
||||
; vectors.s
|
||||
; ---------------------------------------------------------------------------
|
||||
;
|
||||
; Defines the interrupt vector table.
|
||||
|
||||
.import _init
|
||||
.import _nmi_int, _irq_int
|
||||
|
||||
.segment "VECTORS"
|
||||
|
||||
.addr _nmi_int ; NMI vector
|
||||
.addr _init ; Reset vector
|
||||
.addr _irq_int ; IRQ/BRK vector
|
||||
</code></tscreen>
|
||||
|
||||
The cc65 toolset will replace the address symbols defined here with the
|
||||
actual addresses of the routines during the link process.
|
||||
|
||||
<sect>Adding Custom Instructions<p>
|
||||
|
||||
The cc65 instruction set only supports the WAI (Wait for Interrupt) and
|
||||
STP (Stop) instructions when used with the 65816 CPU (accessed via the
|
||||
--cpu command line option of the ca65 macro assembler). The 65C02 core
|
||||
used in this example supports these two instructions, and in fact the
|
||||
system benefits from the use of both the WAI and STP instructions.
|
||||
|
||||
In order to use the WAI instruction in this case, a C routine named
|
||||
"wait" was created that consists of the WAI opcode followed by
|
||||
a subroutine return. It was convenient in this example to put the IRQ
|
||||
interrupt enable in this subroutine as well, since interrupts should
|
||||
only be enabled when the code is in this wait condition.
|
||||
|
||||
For both the WAI and STP instructions, the assembler is
|
||||
"fooled" into placing those opcodes into memory by inserting a
|
||||
single byte of data that just happens to be the opcode for those
|
||||
instructions. The assembly code routines are placed in a file, named
|
||||
"wait.s", which is shown below:
|
||||
|
||||
<tscreen><code>
|
||||
; ---------------------------------------------------------------------------
|
||||
; wait.s
|
||||
; ---------------------------------------------------------------------------
|
||||
;
|
||||
; Wait for interrupt and return
|
||||
|
||||
.export _wait, _stop
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Wait for interrupt: Forces the assembler to emit a WAI opcode ($CB)
|
||||
; ---------------------------------------------------------------------------
|
||||
|
||||
.segment "CODE"
|
||||
|
||||
.proc _wait: near
|
||||
|
||||
CLI ; Enable interrupts
|
||||
.byte $CB ; Inserts a WAI opcode
|
||||
RTS ; Return to caller
|
||||
|
||||
.endproc
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Stop: Forces the assembler to emit a STP opcode ($DB)
|
||||
; ---------------------------------------------------------------------------
|
||||
|
||||
.proc _stop: near
|
||||
|
||||
.byte $DB ; Inserts a STP opcode
|
||||
|
||||
.endproc
|
||||
</code></tscreen>
|
||||
|
||||
The label <tt>_wait</tt>, when exported, can be called by using the
|
||||
<tt>wait ()</tt> subroutine call in C. The section is marked as
|
||||
code so that it will be stored in read-only memory, and the procedure is
|
||||
tagged for 16-bit absolute addressing via the "near"
|
||||
modifier. Similarly, the <tt>_stop</tt> routine can be called from
|
||||
within the C-level code via a call to <tt>stop ()</tt>. In
|
||||
addition, the routine can be called from assembly code by calling
|
||||
<tt>_stop</tt> (as was done in the interrupt service routine).
|
||||
|
||||
<sect>Hardware Drivers<p>
|
||||
|
||||
Oftentimes, it can be advantageous to create small application helpers
|
||||
in assembly language to decrease codespace and increase execution speed
|
||||
of the overall program. An example of this would be the transfer of
|
||||
characters to a FIFO (<bf>F</bf>irst-<bf>I</bf>n,
|
||||
<bf>F</bf>irst-<bf>O</bf>ut) storage buffer for transmission over a
|
||||
serial port. This simple action could be performed by an assembly
|
||||
language driver which would execute much quicker than coding it in C.
|
||||
The following discussion outlines a method of interfacing a C program
|
||||
with an assembly language subroutine.
|
||||
|
||||
The first step in creating the assembly language code for the driver is
|
||||
to determine how to pass the C arguments to the assembly language
|
||||
routine. The cc65 toolset allows the user to specify whether the data
|
||||
is passed to a subroutine via the stack or by the processor registers by
|
||||
using the <tt>__fastcall__</tt> function declaration (note that there
|
||||
are two underscore characters in front of and two behind the
|
||||
<tt>fastcall</tt> declaration). When <tt>__fastcall__</tt> is
|
||||
specified, the rightmost argument in the function call is passed to the
|
||||
subroutine using the 6502 registers instead of the stack. Note that if
|
||||
there is only one argument in the function call, the execution overhead
|
||||
required by the stack interface routines is completely avoided.
|
||||
|
||||
Without <tt>__fastcall__</tt>, the argument is loaded in the A and X
|
||||
registers and then pushed onto the stack via a call to <tt>pushax</tt>.
|
||||
The first thing the subroutine does is retrieve the argument from the
|
||||
stack via a call to <tt>ldax0sp</tt>, which copies the values into the A
|
||||
and X. When the subroutine is finished, the values on the stack must be
|
||||
popped off and discarded via a jump to <tt>incsp2</tt>, which includes
|
||||
the RTS subroutine return command. This is shown in the following code
|
||||
sample.
|
||||
|
||||
Calling sequence:
|
||||
|
||||
<tscreen><verb>
|
||||
lda #<(L0001) ; Load A with the high order byte
|
||||
ldx #>(L0001) ; Load X with the low order byte
|
||||
jsr pushax ; Push A and X onto the stack
|
||||
jsr _foo ; Call foo, i.e., foo (arg)
|
||||
</verb></tscreen>
|
||||
|
||||
Subroutine code:
|
||||
|
||||
<tscreen><verb>
|
||||
_foo: jsr ldax0sp ; Retrieve A and X from the stack
|
||||
sta ptr ; Store A in ptr
|
||||
stx ptr+1 ; Store X in ptr+1
|
||||
... ; (more subroutine code goes here)
|
||||
jmp incsp2 ; Pop A and X from the stack (includes return)
|
||||
</verb></tscreen>
|
||||
|
||||
If <tt>__fastcall__</tt> is specified, the argument is loaded into the A
|
||||
and X registers as before, but the subroutine is then called
|
||||
immediately. The subroutine does not need to retrieve the argument
|
||||
since the value is already available in the A and X registers.
|
||||
Furthermore, the subroutine can be terminated with an RTS statement
|
||||
since there is no stack cleanup which needs to be performed. This is
|
||||
shown in the following code sample.
|
||||
|
||||
Calling sequence:
|
||||
|
||||
<tscreen><verb>
|
||||
lda #<(L0001) ; Load A with the high order byte
|
||||
ldx #>(L0001) ; Load X with the low order byte
|
||||
jsr _foo ; Call foo, i.e., foo (arg)
|
||||
</verb></tscreen>
|
||||
|
||||
Subroutine code:
|
||||
|
||||
<tscreen><verb>
|
||||
_foo: sta ptr ; Store A in ptr
|
||||
stx ptr+1 ; Store X in ptr+1
|
||||
... ; (more subroutine code goes here)
|
||||
rts ; Return from subroutine
|
||||
</verb></tscreen>
|
||||
|
||||
The hardware driver in this example writes a string of character data to
|
||||
a hardware FIFO located at memory location $1000. Each character is
|
||||
read and is compared to the C string termination value ($00), which will
|
||||
terminate the loop. All other character data is written to the FIFO.
|
||||
For convenience, a carriage return/line feed sequence is automatically
|
||||
appended to the serial stream. The driver defines a local pointer
|
||||
variable which is stored in the zero page memory space in order to allow
|
||||
for retrieval of each character in the string via the indirect indexed
|
||||
addressing mode.
|
||||
|
||||
The assembly language routine is stored in a file names
|
||||
"rs232_tx.s" and is shown below:
|
||||
|
||||
<tscreen><code>
|
||||
; ---------------------------------------------------------------------------
|
||||
; rs232_tx.s
|
||||
; ---------------------------------------------------------------------------
|
||||
;
|
||||
; Write a string to the transmit UART FIFO
|
||||
|
||||
.export _rs232_tx
|
||||
.exportzp _rs232_data: near
|
||||
|
||||
.define TX_FIFO $1000 ; Transmit FIFO memory location
|
||||
|
||||
.zeropage
|
||||
|
||||
_rs232_data: .res 2, $00 ; Reserve a local zero page pointer
|
||||
|
||||
.segment "CODE"
|
||||
|
||||
.proc _rs232_tx: near
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Store pointer to zero page memory and load first character
|
||||
|
||||
sta _rs232_data ; Set zero page pointer to string address
|
||||
stx _rs232_data+1 ; (pointer passed in via the A/X registers)
|
||||
ldy #00 ; Initialize Y to 0
|
||||
lda (_rs232_data) ; Load first character
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Main loop: read data and store to FIFO until \0 is encountered
|
||||
|
||||
loop: sta TX_FIFO ; Loop: Store character in FIFO
|
||||
iny ; Increment Y index
|
||||
lda (_rs232_data),y ; Get next character
|
||||
bne loop ; If character == 0, exit loop
|
||||
|
||||
; ---------------------------------------------------------------------------
|
||||
; Append CR/LF to output stream and return
|
||||
|
||||
lda #$0D ; Store CR
|
||||
sta TX_FIFO
|
||||
lda #$0A ; Store LF
|
||||
sta TX_FIFO
|
||||
rts ; Return
|
||||
|
||||
.endproc
|
||||
</code></tscreen>
|
||||
|
||||
<sect>Hello World! Example<p>
|
||||
|
||||
The following short example demonstrates programming in C using the cc65
|
||||
toolset with a custom run-time environment. In this example, a Xilinx
|
||||
FPGA contains a UART which is connected to a 65c02 processor with FIFO
|
||||
(<bf>F</bf>irst-<bf>I</bf>n, <bf>F</bf>irst-<bf>O</bf>ut) storage to
|
||||
buffer the data. The C program will wait for an interrupt generated by
|
||||
the receive UART and then respond by transmitting the string "Hello
|
||||
World! " every time a question mark character is received via a
|
||||
call to the hardware driver <tt>rs232_tx ()</tt>. The driver
|
||||
prototype uses the <tt>__fastcall__</tt> extension to indicate that the
|
||||
driver does not use the stack. The FIFO data interface is at address
|
||||
$1000 and is defined as the symbolic constant <tt>FIFO_DATA</tt>.
|
||||
Writing to <tt>FIFO_DATA</tt> transfers a byte of data into the transmit
|
||||
FIFO for subsequent transmission over the serial interface. Reading
|
||||
from <tt>FIFO_DATA</tt> transfers a byte of previously received data out
|
||||
of the receive FIFO. The FIFO status data is at address $1001 and is
|
||||
defined as the symbolic constant <tt>FIFO_STATUS</tt>. For convenience,
|
||||
the symbolic constants <tt>TX_FIFO_FULL</tt> (which isolates bit 0 of
|
||||
the register) and <tt>RX_FIFO_EMPTY</tt> (which isolates bit 1 of the
|
||||
register) have been defined to read the FIFO status.
|
||||
|
||||
The following C code is saved in the file "main.c". As this
|
||||
example demonstrates, the run-time environment has been set up such that
|
||||
all of the behind-the-scene work is transparent to the user.
|
||||
|
||||
<tscreen><code>
|
||||
#define FIFO_DATA (*(unsigned char *) 0x1000)
|
||||
#define FIFO_STATUS (*(unsigned char *) 0x1001)
|
||||
|
||||
#define TX_FIFO_FULL (FIFO_STATUS & 0x01)
|
||||
#define RX_FIFO_EMPTY (FIFO_STATUS & 0x02)
|
||||
|
||||
extern void wait ();
|
||||
extern void __fastcall__ rs232_tx (char *str);
|
||||
|
||||
int main () {
|
||||
while (1) { // Run forever
|
||||
wait (); // Wait for an RX FIFO interrupt
|
||||
|
||||
while (RX_FIFO_EMPTY == 0) { // While the RX FIFO is not empty
|
||||
if (FIFO_DATA == '?') { // Does the RX character = '?'
|
||||
rs232_tx ("Hello World!"); // Transmit "Hello World!"
|
||||
} // Discard any other RX characters
|
||||
}
|
||||
}
|
||||
|
||||
return (0); // We should never get here!
|
||||
}
|
||||
</code></tscreen>
|
||||
|
||||
<sect>Putting It All Together<p>
|
||||
|
||||
The following commands will create a ROM image named "a.out"
|
||||
that can be used as the initialization data for the Xilinx Block RAM
|
||||
used for code storage:
|
||||
|
||||
<tscreen><verb>
|
||||
$ cc65 -t none -O --cpu 65sc02 main.c
|
||||
$ ca65 --cpu 65sc02 main.s
|
||||
$ ca65 --cpu 65sc02 rs232_tx.s
|
||||
$ ca65 --cpu 65sc02 interrupt.s
|
||||
$ ca65 --cpu 65sc02 vectors.s
|
||||
$ ca65 --cpu 65sc02 wait.s
|
||||
$ ld65 -C sbc.cfg -m main.map interrupt.o vectors.o wait.o rs232_tx.o
|
||||
main.o sbc.lib
|
||||
</verb></tscreen>
|
||||
|
||||
During the C-level code compilation phase (<tt>cc65</tt>), assumptions
|
||||
about the target system are disabled via the <tt>-t none</tt> command
|
||||
line option. During the object module linker phase (<tt>ld65</tt>), the
|
||||
target customization is enabled via inclusion of the <tt>sbc.lib</tt>
|
||||
file and the selection of the configuration file via the <tt>-C
|
||||
sbc.cfg</tt> command line option.
|
||||
|
||||
The 65C02 core used most closely matches the cc65 toolset processor
|
||||
named 65SC02 (the 65C02 extensions without the bit manipulation
|
||||
instructions), so all the commands specify the use of that processor via
|
||||
the <tt>--cpu 65sc02</tt> option.
|
||||
|
||||
</article>
|
||||
685
doc/da65.sgml
Normal file
685
doc/da65.sgml
Normal file
@ -0,0 +1,685 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>da65 Users Guide
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2003-08-08
|
||||
|
||||
<abstract>
|
||||
da65 is a 6502/65C02 disassembler that is able to read user supplied
|
||||
information about its input data for better results. The output is ready for
|
||||
feeding into ca65, the macro assembler supplied with the cc65 C compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with
|
||||
the cc65 C compiler and generates output that is suitable for the ca65
|
||||
macro assembler.
|
||||
|
||||
Besides generating output for ca65, one of the design goals was that the user
|
||||
is able to feed additional information about the code into the disassembler
|
||||
for improved results. This information may include the location and size of
|
||||
tables, and their format.
|
||||
|
||||
One nice advantage of this concept is that disassembly of copyrighted binaries
|
||||
may be handled without problems: One can just pass the information file for
|
||||
disassembling the binary, so everyone with a legal copy of the binary can
|
||||
generate a nicely formatted disassembly with readable labels and other
|
||||
information.
|
||||
|
||||
|
||||
<sect>Usage<p>
|
||||
|
||||
|
||||
<sect1>Command line option overview<p>
|
||||
|
||||
The assembler accepts the following options:
|
||||
|
||||
<tscreen><verb>
|
||||
---------------------------------------------------------------------------
|
||||
Usage: da65 [options] [inputfile]
|
||||
Short options:
|
||||
-g Add debug info to object file
|
||||
-h Help (this text)
|
||||
-i name Specify an info file
|
||||
-o name Name the output file
|
||||
-v Increase verbosity
|
||||
-F Add formfeeds to the output
|
||||
-S addr Set the start/load address
|
||||
-V Print the disassembler version
|
||||
|
||||
Long options:
|
||||
--argument-column n Specify argument start column
|
||||
--comment-column n Specify comment start column
|
||||
--comments n Set the comment level for the output
|
||||
--cpu type Set cpu type
|
||||
--debug-info Add debug info to object file
|
||||
--formfeeds Add formfeeds to the output
|
||||
--help Help (this text)
|
||||
--hexoffs Use hexadecimal label offsets
|
||||
--info name Specify an info file
|
||||
--label-break n Add newline if label exceeds length n
|
||||
--mnemonic-column n Specify mnemonic start column
|
||||
--pagelength n Set the page length for the listing
|
||||
--start-addr addr Set the start/load address
|
||||
--text-column n Specify text start column
|
||||
--verbose Increase verbosity
|
||||
--version Print the disassembler version
|
||||
---------------------------------------------------------------------------
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<sect1>Command line options in detail<p>
|
||||
|
||||
Here is a description of all the command line options:
|
||||
|
||||
<descrip>
|
||||
|
||||
<label id="option--argument-column">
|
||||
<tag><tt>--argument-column n</tt></tag>
|
||||
|
||||
Specifies the column where the argument for a mnemonic or pseudo instruction
|
||||
starts.
|
||||
|
||||
|
||||
<label id="option--comment-column">
|
||||
<tag><tt>--comment-column n</tt></tag>
|
||||
|
||||
Specifies the column where the comment for an instruction starts.
|
||||
|
||||
|
||||
<label id="option--comments">
|
||||
<tag><tt>--comments n</tt></tag>
|
||||
|
||||
Set the comment level for the output. Valid arguments are 0..4. Greater
|
||||
values will increase the level of additional information written to the
|
||||
output file in form of comments.
|
||||
|
||||
|
||||
<label id="option--cpu">
|
||||
<tag><tt>--cpu type</tt></tag>
|
||||
|
||||
Set the CPU type. The option takes a parameter, which may be one of
|
||||
|
||||
6502, 6502x, 65sc02, 65c02, huc6280
|
||||
|
||||
6502x is the NMOS 6502 with illegal opcodes. huc6280 is the CPU of the PC
|
||||
engine. Support for the 65816 is currently not available.
|
||||
|
||||
|
||||
<label id="option--formfeeds">
|
||||
<tag><tt>-F, --formfeeds</tt></tag>
|
||||
|
||||
Add formfeeds to the generated output. This feature is useful together
|
||||
with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
|
||||
If <tt/--formfeeds/ is given, a formfeed is added to the output after each
|
||||
page.
|
||||
|
||||
|
||||
<tag><tt>-g, --debug-info</tt></tag>
|
||||
|
||||
This option adds the <tt/.DEBUGINFO/ command to the output file, so the
|
||||
assembler will generate debug information when reassembling the generated
|
||||
output.
|
||||
|
||||
|
||||
<tag><tt>-h, --help</tt></tag>
|
||||
|
||||
Print the short option summary shown above.
|
||||
|
||||
|
||||
<label id="option--hexoffs">
|
||||
<tag><tt>--hexoffs</tt></tag>
|
||||
|
||||
Output label offsets in hexadecimal instead of decimal notation.
|
||||
|
||||
|
||||
<label id="option--info">
|
||||
<tag><tt>-i name, --info name</tt></tag>
|
||||
|
||||
Specify an info file. The info file contains global options that may
|
||||
override or replace command line options plus informations about the code
|
||||
that has to be disassembled. See the separate section <ref id="infofile"
|
||||
name="Info File Format">.
|
||||
|
||||
|
||||
<label id="option-o">
|
||||
<tag><tt>-o name</tt></tag>
|
||||
|
||||
Specify a name for an output file. The default is to use <tt/stdout/, so
|
||||
without this switch or the corresponding <ref id="global-options"
|
||||
name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
|
||||
the output will go to the terminal.
|
||||
|
||||
|
||||
<label id="option--label-break">
|
||||
<tag><tt>--label-break n</tt></tag>
|
||||
|
||||
Adds a newline if the length of a label exceeds the given length.
|
||||
Note: If the label would run into the code in the mid column, a
|
||||
linefeed is always inserted regardless of this setting.
|
||||
|
||||
This option overrides the <ref id="global-options" name="global option">
|
||||
<tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
|
||||
|
||||
|
||||
<label id="option--mnemonic-column">
|
||||
<tag><tt>--mnemonic-column n</tt></tag>
|
||||
|
||||
Specifies the column where a mnemonic or pseudo instrcuction is output.
|
||||
|
||||
|
||||
<label id="option--pagelength">
|
||||
<tag><tt>--pagelength n</tt></tag>
|
||||
|
||||
Sets the length of a listing page in lines. After this number of lines, a
|
||||
new page header is generated. If the <tt><ref id="option--formfeeds"
|
||||
name="--formfeeds"></tt> is also given, a formfeed is inserted before
|
||||
generating the page header.
|
||||
|
||||
A value of zero for the page length will disable paging of the output.
|
||||
|
||||
|
||||
<label id="option--start-addr">
|
||||
<tag><tt>-S addr, --start-addr addr</tt></tag>
|
||||
|
||||
Specify the start/load address of the binary code that is going to be
|
||||
disassembled. The given address is interpreted as an octal value if
|
||||
preceded with a '0' digit, as a hexadecimal value if preceded
|
||||
with '0x', '0X', or '$', and as a decimal value in all other cases. If no
|
||||
start address is specified, $10000 minus the size of the input file is used.
|
||||
|
||||
|
||||
<label id="option--text-column">
|
||||
<tag><tt>--text-column n</tt></tag>
|
||||
|
||||
Specifies the column where additional text is output. This additional text
|
||||
consists of the bytes encoded in this line in text representation.
|
||||
|
||||
|
||||
<tag><tt>-v, --verbose</tt></tag>
|
||||
|
||||
Increase the disassembler verbosity. Usually only needed for debugging
|
||||
purposes. You may use this option more than one time for even more
|
||||
verbose output.
|
||||
|
||||
|
||||
<tag><tt>-V, --version</tt></tag>
|
||||
|
||||
Print the version number of the assembler. If you send any suggestions
|
||||
or bugfixes, please include the version number.
|
||||
|
||||
</descrip>
|
||||
<p>
|
||||
|
||||
|
||||
<sect>Detailed workings<p>
|
||||
|
||||
<sect1>Supported CPUs<p>
|
||||
|
||||
The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
|
||||
the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
|
||||
for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
|
||||
|
||||
With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
|
||||
disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
|
||||
latter understands the same opcodes as the former, plus 16 additional bit
|
||||
manipulation and bit test-and-branch commands.
|
||||
|
||||
While there is some code for the 65816 in the sources, it is currently
|
||||
unsupported.
|
||||
|
||||
|
||||
<sect1>Attribute map<p>
|
||||
|
||||
The disassembler works by creating an attribute map for the whole address
|
||||
space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
|
||||
external info file (if given) is read. Disassembly is done in several passes.
|
||||
In all passes with the exception of the last one, information about the
|
||||
disassembled code is gathered and added to the symbol and attribute maps. The
|
||||
last pass generates output using the information from the maps.
|
||||
|
||||
<sect1>Labels<p>
|
||||
|
||||
Some instructions may generate labels in the first pass, while most other
|
||||
instructions do not generate labels, but use them if they are available. Among
|
||||
others, the branch and jump instructions will generate labels for the target
|
||||
of the branch in the first pass. External labels (taken from the info file)
|
||||
have precedence over internally generated ones, They must be valid identifiers
|
||||
as specified for the ca65 assembler. Internal labels (generated by the
|
||||
disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
|
||||
address of the label in upper case letters. You should probably avoid using
|
||||
such label names for external labels.
|
||||
|
||||
|
||||
<sect1>Info File<p>
|
||||
|
||||
The info file is used to pass additional information about the input code to
|
||||
the disassembler. This includes label names, data areas or tables, and global
|
||||
options like input and output file names. See the <ref id="infofile"
|
||||
name="next section"> for more information.
|
||||
|
||||
|
||||
|
||||
<sect>Info File Format<label id="infofile"><p>
|
||||
|
||||
The info file contains lists of specifications grouped together. Each group
|
||||
directive has an identifying token and an attribute list enclosed in curly
|
||||
braces. Attributes have a name followed by a value. The syntax of the value
|
||||
depends on the type of the attribute. String attributes are places in double
|
||||
quotes, numeric attributes may be specified as decimal numbers or hexadecimal
|
||||
with a leading dollar sign. There are also attributes where the attribute
|
||||
value is a keyword, in this case the keyword is given as is (without quotes or
|
||||
anything). Each attribute is terminated by a semicolon.
|
||||
|
||||
<tscreen><verb>
|
||||
group-name { attribute1 attribute-value; attribute2 attribute-value; }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<sect1>Comments<p>
|
||||
|
||||
Comments start with a hash mark (<tt/#/) and extend from the position of
|
||||
the mark to the end of the current line. Hash marks inside of strings will
|
||||
of course <em/not/ start a comment.
|
||||
|
||||
|
||||
<sect1>Specifying global options<label id="global-options"><p>
|
||||
|
||||
Global options may be specified in a group with the name <tt/GLOBAL/. The
|
||||
following attributes are recognized:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/ARGUMENTCOLUMN/</tag>
|
||||
This attribute specifies the column in the output, where the argument for
|
||||
an opcode or pseudo instruction starts. The corresponding command line
|
||||
option is
|
||||
<tt><ref id="option--argument-column" name="--argument-column"></tt>.
|
||||
|
||||
|
||||
<tag><tt/COMMENTCOLUMN/</tag>
|
||||
This attribute specifies the column in the output, where the comment starts
|
||||
in a line. It is only used for in-line comments. The corresponding command
|
||||
line option is
|
||||
<tt><ref id="option--comment-column" name="--comment-column"></tt>.
|
||||
|
||||
|
||||
<label id="COMMENTS">
|
||||
<tag><tt/COMMENTS/</tag>
|
||||
This attribute may be used instead of the <tt><ref id="option--comments"
|
||||
name="--comments"></tt> option on the command line. It takes a numerical
|
||||
parameter between 0 and 4. Higher values increase the amount of information
|
||||
written to the output file in form of comments.
|
||||
|
||||
|
||||
<tag><tt/CPU/</tag>
|
||||
This attribute may be used instead of the <tt><ref id="option--cpu"
|
||||
name="--cpu"></tt> option on the command line. For possible values see
|
||||
there. The value is a string and must be enclosed in quotes.
|
||||
|
||||
|
||||
<tag><tt/HEXOFFS/</tag>
|
||||
The attribute is followed by a boolean value. If true, offsets to labels are
|
||||
output in hex, otherwise they're output in decimal notation. The default is
|
||||
false. The attribute may be changed on the command line using the <tt><ref
|
||||
id="option--hexoffs" name="--hexoffs"></tt> option.
|
||||
|
||||
|
||||
<tag><tt/INPUTNAME/</tag>
|
||||
The attribute is followed by a string value, which gives the name of the
|
||||
input file to read. If it is present, the disassembler does not accept an
|
||||
input file name on the command line.
|
||||
|
||||
|
||||
<tag><tt/INPUTOFFS/</tag>
|
||||
The attribute is followed by a numerical value that gives an offset into
|
||||
the input file which is skipped before reading data. The attribute may be
|
||||
used to skip headers or unwanted code sections in the input file.
|
||||
|
||||
|
||||
<tag><tt/INPUTSIZE/</tag>
|
||||
<tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
|
||||
data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
|
||||
is ignored.
|
||||
|
||||
|
||||
<label id="LABELBREAK">
|
||||
<tag><tt/LABELBREAK/</tag>
|
||||
<tt/LABELBREAK/ is followed by a numerical value that specifies the label
|
||||
length that will force a newline. To have all labels on their own lines,
|
||||
you may set this value to zero.
|
||||
|
||||
See also the <tt><ref id="option--label-break" name="--label-break"></tt>
|
||||
command line option. A <tt/LABELBREAK/ statement in the info file will
|
||||
override any value given on the command line.
|
||||
|
||||
|
||||
<tag><tt/MNEMONICCOLUMN/</tag>
|
||||
This attribute specifies the column in the output, where the mnemonic or
|
||||
pseudo instruction is placed. The corresponding command line option is
|
||||
<tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>.
|
||||
|
||||
|
||||
<tag><tt/NEWLINEAFTERJMP/</tag>
|
||||
This attribute is followed by a boolean value. When true, a newline is
|
||||
inserted after each <tt/JMP/ instruction. The default is false.
|
||||
|
||||
|
||||
<tag><tt/NEWLINEAFTERRTS/</tag>
|
||||
This attribute is followed by a boolean value. When true, a newline is
|
||||
inserted after each <tt/RTS/ instruction. The default is false.
|
||||
|
||||
|
||||
<label id="OUTPUTNAME">
|
||||
<tag><tt/OUTPUTNAME/</tag>
|
||||
The attribute is followed by string value, which gives the name of the
|
||||
output file to write. If it is present, specification of an output file on
|
||||
the command line using the <tt><ref id="option-o" name="-o"></tt> option is
|
||||
not allowed.
|
||||
|
||||
The default is to use <tt/stdout/ for output, so without this attribute or
|
||||
the corresponding command line option <tt/<ref id="option-o" name="-o">/
|
||||
the output will go to the terminal.
|
||||
|
||||
|
||||
<tag><tt/PAGELENGTH/</tag>
|
||||
This attribute may be used instead of the <tt><ref id="option--pagelength"
|
||||
name="--pagelength"></tt> option on the command line. It takes a numerical
|
||||
parameter. Using zero as page length (which is the default) means that no
|
||||
pages are generated.
|
||||
|
||||
|
||||
<tag><tt/STARTADDR/</tag>
|
||||
This attribute may be used instead of the <tt><ref id="option--start-addr"
|
||||
name="--start-addr"></tt> option on the command line. It takes a numerical
|
||||
parameter. The default for the start address is $10000 minus the size of
|
||||
the input file (this assumes that the input file is a ROM that contains the
|
||||
reset and irq vectors).
|
||||
|
||||
|
||||
<tag><tt/TEXTCOLUMN/</tag>
|
||||
This attribute specifies the column, where the data bytes are output
|
||||
translated into ASCII text. It is only used if
|
||||
<tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The
|
||||
corresponding command line option is
|
||||
<tt><ref id="option--text-column" name="--text-column"></tt>.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect1>Specifying Ranges<p>
|
||||
|
||||
The <tt/RANGE/ directive is used to give information about address ranges. The
|
||||
following attributes are recognized:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt>COMMENT</tt></tag>
|
||||
This attribute is only allowed if a label is also given. It takes a string
|
||||
as argument. See the description of the <tt><ref id="infofile-label"
|
||||
name="LABEL"></tt> directive for an explanation.
|
||||
|
||||
<tag><tt>END</tt></tag>
|
||||
This gives the end address of the range. The end address is inclusive, that
|
||||
means, it is part of the range. Of course, it may not be smaller than the
|
||||
start address.
|
||||
|
||||
<tag><tt>NAME</tt></tag>
|
||||
This is a convenience attribute. It takes a string argument and will cause
|
||||
the disassembler to define a label for the start of the range with the
|
||||
given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
|
||||
directive is not needed.
|
||||
|
||||
<tag><tt>START</tt></tag>
|
||||
This gives the start address of the range.
|
||||
|
||||
<tag><tt>TYPE</tt></tag>
|
||||
This attribute specifies the type of data within the range. The attribute
|
||||
value is one of the following keywords:
|
||||
|
||||
<descrip>
|
||||
<tag><tt>ADDRTABLE</tt></tag>
|
||||
The range consists of data and is disassembled as a table of words
|
||||
(16 bit values). The difference to the <tt/WORDTABLE/ type is that
|
||||
a label is defined for each entry in the table.
|
||||
|
||||
<tag><tt>BYTETABLE</tt></tag>
|
||||
The range consists of data and is disassembled as a byte table.
|
||||
|
||||
<tag><tt>CODE</tt></tag>
|
||||
The range consists of code.
|
||||
|
||||
<tag><tt>DBYTETABLE</tt></tag>
|
||||
The range consists of data and is disassembled as a table of dbytes
|
||||
(double byte values, 16 bit values with the low byte containing the
|
||||
most significant byte of the 16 bit value).
|
||||
|
||||
<tag><tt>DWORDTABLE</tt></tag>
|
||||
The range consists of data and is disassembled as a table of double
|
||||
words (32 bit values).
|
||||
|
||||
<tag><tt>RTSTABLE</tt></tag>
|
||||
The range consists of data and is disassembled as a table of words (16 bit
|
||||
values). The values are interpreted as words that are pushed onto the
|
||||
stack and jump to it via <tt/RTS/. This means that they contain
|
||||
<tt/address-1/ of a function, for which a label will get defined by the
|
||||
disassembler.
|
||||
|
||||
<tag><tt>SKIP</tt></tag>
|
||||
The range is simply ignored when generating the output file. Please note
|
||||
that this means that reassembling the output file will <em/not/ generate
|
||||
the original file, not only because the missing piece in between, but also
|
||||
because the following code will be located on wrong addresses. Output
|
||||
generated with <tt/SKIP/ ranges will need manual rework.
|
||||
|
||||
<tag><tt>TEXTTABLE</tt></tag>
|
||||
The range consists of readable text.
|
||||
|
||||
<tag><tt>WORDTABLE</tt></tag>
|
||||
The range consists of data and is disassembled as a table of words
|
||||
(16 bit values).
|
||||
|
||||
</descrip>
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect1>Specifying Labels<label id="infofile-label"><p>
|
||||
|
||||
The <tt/LABEL/ directive is used to give names for labels in the disassembled
|
||||
code. The following attributes are recognized:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt>ADDR</tt></tag>
|
||||
Followed by a numerical value. Specifies the value of the label.
|
||||
|
||||
<tag><tt>COMMENT</tt></tag>
|
||||
Attribute argument is a string. The comment will show up in a separate line
|
||||
before the label, if the label is within code or data range, or after the
|
||||
label if it is outside.
|
||||
|
||||
Example output:
|
||||
|
||||
<tscreen><verb>
|
||||
foo := $0001 ; Comment for label named "foo"
|
||||
|
||||
; Comment for label named "bar"
|
||||
bar:
|
||||
</verb></tscreen>
|
||||
|
||||
<tag><tt>NAME</tt></tag>
|
||||
The attribute is followed by a string value which gives the name of the
|
||||
label. Empty names are allowed, in this case the disassembler will create
|
||||
an unnamed label (see the assembler docs for more information about unnamed
|
||||
labels).
|
||||
|
||||
<tag><tt>SIZE</tt></tag>
|
||||
This attribute is optional and may be used to specify the size of the data
|
||||
that follows. If a size greater than 1 is specified, the disassembler will
|
||||
create labels in the form <tt/label+offs/ for all bytes within the given
|
||||
range, where <tt/label/ is the label name given with the <tt/NAME/
|
||||
attribute, and <tt/offs/ is the offset within the data.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect1>Specifying Segments<label id="infofile-segment"><p>
|
||||
|
||||
The <tt/SEGMENT/ directive is used to specify a segment within the
|
||||
disassembled code. The following attributes are recognized:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt>START</tt></tag>
|
||||
Followed by a numerical value. Specifies the start address of the segment.
|
||||
|
||||
<tag><tt>END</tt></tag>
|
||||
Followed by a numerical value. Specifies the end address of the segment. The
|
||||
end address is last the address that is part of the segment.
|
||||
|
||||
<tag><tt>NAME</tt></tag>
|
||||
The attribute is followed by a string value which gives the name of the
|
||||
segment.
|
||||
</descrip>
|
||||
|
||||
All attributes are mandatory. Segments may not overlap. Since there is no
|
||||
explicit "end this segment" pseudo op, the disassembler cannot notify the
|
||||
assembler that one segment has ended. This may lead to errors if you don't
|
||||
define your segments carefully. As a rule of thumb, if you're using segments,
|
||||
your should define segments for all disassembled code.
|
||||
|
||||
|
||||
<sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
|
||||
|
||||
The <tt/ASMINC/ directive is used to give the names of input files containing
|
||||
symbol assignments in assembler syntax:
|
||||
|
||||
<tscreen><verb>
|
||||
Name = value
|
||||
Name := value
|
||||
</verb></tscreen>
|
||||
|
||||
The usual conventions apply for symbol names. Values may be specified as hex
|
||||
(leading $), binary (leading %) or decimal. The values may optionally
|
||||
be signed.
|
||||
|
||||
NOTE: The include file parser is very simple. Expressions are not allowed, and
|
||||
anything but symbol assignments is flagged as an error (but see the
|
||||
<tt/IGNOREUNKNOWN/ directive below).
|
||||
|
||||
The following attributes are recognized:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt>FILE</tt></tag>
|
||||
Followed by a string value. Specifies the name of the file to read.
|
||||
|
||||
<tag><tt>COMMENTSTART</tt></tag>
|
||||
The optional attribute is followed by a character constant. It specifies the
|
||||
character that starts a comment. The default value is a semicolon. This
|
||||
value is ignored if <tt/IGNOREUNKNOWN/ is true.
|
||||
|
||||
<tag><tt>IGNOREUNKNOWN</tt></tag>
|
||||
This attribute is optional and is followed by a boolean value. It allows to
|
||||
ignore input lines that don't have a valid syntax. This allows to read in
|
||||
assembler include files that contain more than just symbol assignments.
|
||||
Note: When this attribute is used, the disassembler will ignore any errors
|
||||
in the given include file. This may have undesired side effects.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect1>An Info File Example<p>
|
||||
|
||||
The following is a short example for an info file that contains most of the
|
||||
directives explained above:
|
||||
|
||||
<tscreen><verb>
|
||||
# This is a comment. It extends to the end of the line
|
||||
GLOBAL {
|
||||
OUTPUTNAME "kernal.s";
|
||||
INPUTNAME "kernal.bin";
|
||||
STARTADDR $E000;
|
||||
PAGELENGTH 0; # No paging
|
||||
CPU "6502";
|
||||
};
|
||||
|
||||
# One segment for the whole stuff
|
||||
SEGMENT { START $E000; END $FFFF; NAME kernal; };
|
||||
|
||||
RANGE { START $E612; END $E631; TYPE Code; };
|
||||
RANGE { START $E632; END $E640; TYPE ByteTable; };
|
||||
RANGE { START $EA51; END $EA84; TYPE RtsTable; };
|
||||
RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
|
||||
RANGE { START $ED08; END $ED11; TYPE AddrTable; };
|
||||
|
||||
# Zero page variables
|
||||
LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
|
||||
LABEL { NAME "sal"; ADDR $93; };
|
||||
LABEL { NAME "sah"; ADDR $94; };
|
||||
LABEL { NAME "sas"; ADDR $95; };
|
||||
|
||||
# Stack
|
||||
LABEL { NAME "stack"; ADDR $100; SIZE 255; };
|
||||
|
||||
# Indirect vectors
|
||||
LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
|
||||
LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
|
||||
LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
|
||||
|
||||
# Jump table at end of kernal ROM
|
||||
LABEL { NAME "kscrorg"; ADDR $FFED; };
|
||||
LABEL { NAME "kplot"; ADDR $FFF0; };
|
||||
LABEL { NAME "kiobase"; ADDR $FFF3; };
|
||||
LABEL { NAME "kgbye"; ADDR $FFF6; };
|
||||
|
||||
# Hardware vectors
|
||||
LABEL { NAME "hanmi"; ADDR $FFFA; };
|
||||
LABEL { NAME "hares"; ADDR $FFFC; };
|
||||
LABEL { NAME "hairq"; ADDR $FFFE; };
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<sect>Copyright<p>
|
||||
|
||||
da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von
|
||||
Bassewitz. For usage of the binaries and/or sources the following
|
||||
conditions do apply:
|
||||
|
||||
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>
|
||||
|
||||
|
||||
|
||||
|
||||
154
doc/debugging.sgml
Normal file
154
doc/debugging.sgml
Normal file
@ -0,0 +1,154 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Using emulators with cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>03.12.2000
|
||||
|
||||
<abstract>
|
||||
How to debug your code using the VICE and Oricutron emulators.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This document describes how to debug your programs using the cc65 development
|
||||
tools and the VICE CBM emulator.
|
||||
|
||||
|
||||
|
||||
<sect>What is VICE?<p>
|
||||
|
||||
VICE is an emulator for many of the CBM machines. It runs on Unix, MS-DOS,
|
||||
Win32, OS/2, Acorn RISC OS, BeOS, QNX 6.x, Amiga, GP2X and Mac OS X. It emulates
|
||||
the Commodore 64, 128, VIC20, PET and the 600/700 machines. For more information
|
||||
see the VICE home page:
|
||||
|
||||
<htmlurl url="http://www.viceteam.org/">
|
||||
|
||||
VICE has a builtin machine language monitor that may be used for debugging
|
||||
your programs. Using an emulator for debugging has some advantages:
|
||||
|
||||
<itemize>
|
||||
|
||||
<item>Since you're using a crossassembler/-compiler anyway, you don't need to
|
||||
transfer the program to the real machine until it is done.
|
||||
|
||||
<item>An emulator allows many things that are almost impossible one of the
|
||||
original machines. You may set watchpoints (detect read or write access to
|
||||
arbitary addresses), debug interrupt handlers and even debug routines that run
|
||||
inside the 1541 floppy.
|
||||
|
||||
<item>You may use the label file generated by the linker to make much more use
|
||||
from the monitor.
|
||||
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect>How to prepare your programs<p>
|
||||
|
||||
VICE support is mostly done via a label file that is generated by the linker
|
||||
and that may be read by the VICE monitor, so it knows about your program.
|
||||
Source level debugging is <tt/not/ available, you have to debug your programs
|
||||
in the assembler view.
|
||||
|
||||
The first step is to generate object files that contain information about
|
||||
<em/all/ labels in your sources, not just the exported ones. This can be done
|
||||
by several means:
|
||||
|
||||
<itemize>
|
||||
|
||||
<item>Use the -g switch on the assembler command line.
|
||||
|
||||
<item>Use the
|
||||
<tscreen><verb>
|
||||
.debuginfo +
|
||||
</verb></tscreen>
|
||||
command in your source.
|
||||
|
||||
<item>Use the <tt/-g/ switch when invoking the compiler. The compiler will
|
||||
then place a <tt/.debuginfo/ command into the generated assembler source.
|
||||
|
||||
</itemize>
|
||||
|
||||
So, if you have just C code, all you need is to invoke the compiler with
|
||||
<tt/-g/. If you're using assembler code, you have to use <tt/-g/ for the
|
||||
assembler, or add "<tt/.debuginfo on/" to your source files. Since the
|
||||
generated debug info is not appended to the generated executables, it is a
|
||||
good idea to always use <tt/-g/. It makes the object files and libraries
|
||||
slightly larger (˜30%), but this is usually not a problem.
|
||||
|
||||
The second step is to tell the linker that it should generate a VICE label
|
||||
file. This is done by the <tt/-Ln/ switch followed by the name of the label
|
||||
file (I'm usually using a <tt/.lbl/ extension for these files). An example for
|
||||
a linker command line would be:
|
||||
|
||||
<tscreen><verb>
|
||||
ld65 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib
|
||||
</verb></tscreen>
|
||||
or
|
||||
<tscreen><verb>
|
||||
ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.lib
|
||||
</verb></tscreen>
|
||||
|
||||
This will generate a file named hello.lbl that contains all symbols used in
|
||||
your program.
|
||||
|
||||
<bf>Note</bf>: The runtime libraries and startup files were generated with
|
||||
debug info, so you don't have to care about this.
|
||||
|
||||
|
||||
|
||||
<sect>How to use the label file with VICE<p>
|
||||
|
||||
Load your program, then enter the monitor and use the "<tt/ll/" command to
|
||||
load your label file like this:
|
||||
|
||||
<tscreen><verb>
|
||||
ll "hello.lbl"
|
||||
</verb></tscreen>
|
||||
|
||||
You will get lots of warnings and even a few errors. You may ignore safely all
|
||||
these warnings and errors as long as they reference any problems VICE thinks
|
||||
it has with the labels.
|
||||
|
||||
After loading the labels, they are used by VICE in the disassembler listing,
|
||||
and you may use them whereever you need to specify an address. Try
|
||||
|
||||
<tscreen><verb>
|
||||
d ._main
|
||||
</verb></tscreen>
|
||||
|
||||
as an example (note that VICE needs a leading dot before all labels, and that
|
||||
the compiler prepends an underline under most named labels).
|
||||
|
||||
|
||||
|
||||
<sect>How to use the label file with Oricutron<p>
|
||||
|
||||
Load your program, then enter the monitor and use the "<tt/sl/" command to
|
||||
load your label file like this:
|
||||
|
||||
<tscreen><verb>
|
||||
sl hello.sym
|
||||
</verb></tscreen>
|
||||
|
||||
After loading the labels, they are used by Oricutron in the disassembler listing,
|
||||
and you may use them whereever you need to specify an address. Try
|
||||
|
||||
<tscreen><verb>
|
||||
d ._main
|
||||
</verb></tscreen>
|
||||
|
||||
as an example (note that VICE needs a leading dot before all labels, and that
|
||||
the compiler prepends an underline under most named labels).
|
||||
|
||||
|
||||
|
||||
</article>
|
||||
134
doc/dio.sgml
Normal file
134
doc/dio.sgml
Normal file
@ -0,0 +1,134 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>Diskette Sector I/O Routines
|
||||
<author>Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org">
|
||||
<date>20-Feb-2005
|
||||
|
||||
<abstract>
|
||||
The cc65 library provides functions to read and write raw disk sectors.
|
||||
Include the dio.h header file to get the necessary definitions.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Opening the disk for low level I/O<p>
|
||||
|
||||
Prior to using these functions a handle to the device has to be obtained. This
|
||||
is done with the <tt>dio_open</tt> function. After use, the handle should be
|
||||
released with the <tt>dio_close</tt> function.
|
||||
|
||||
<tscreen><verb>
|
||||
dhandle_t __fastcall__ dio_open (unsigned char device);
|
||||
</verb></tscreen>
|
||||
|
||||
The <tt>device</tt> specifies the device to access, with 0 being the first
|
||||
device, 1 the second, and so on.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_close (dhandle_t handle);
|
||||
</verb></tscreen>
|
||||
|
||||
Closes a handle obtained by <tt>dio_open</tt>. Returns status code.
|
||||
<p>
|
||||
|
||||
<sect>Reading and writing sectors<p>
|
||||
|
||||
The read and write functions are:
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_read (dhandle_t handle,
|
||||
unsigned sect_num,
|
||||
void *buffer);
|
||||
</verb></tscreen>
|
||||
|
||||
This function will read the sector specified by <tt>sect_num</tt> into the memory
|
||||
location at buffer.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_write (dhandle_t handle,
|
||||
unsigned sect_num,
|
||||
const void *buffer);
|
||||
</verb></tscreen>
|
||||
|
||||
This function will write the memory contents at buffer to the sector specified
|
||||
by <tt>sect_num</tt>. No verify is performed.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
|
||||
unsigned sect_num,
|
||||
const void *buffer);
|
||||
</verb></tscreen>
|
||||
|
||||
This function will write the memory contents at buffer to the sector specified
|
||||
by <tt>sect_num</tt>. A verification is performed.
|
||||
<p>
|
||||
|
||||
Use the <tt><ref name="dio_query_sectsize" id="sectsizecount"></tt> function to query
|
||||
the size of a sector and the <tt><ref name="dio_query_sectcount" id="sectsizecount"></tt>
|
||||
function to query the number of available sectors.
|
||||
<p>
|
||||
|
||||
All these functions will return 0 for success and an OS specific error code in
|
||||
case of failure.
|
||||
<p>
|
||||
|
||||
<sect>Querying sector size and count<label id="sectsizecount"><p>
|
||||
|
||||
Some systems support multiple diskette formats which have different sector sizes
|
||||
and/or different sector counts.
|
||||
<p>
|
||||
|
||||
The following function returns the sector size of the currently inserted disk:
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned __fastcall__ dio_query_sectsize (dhandle_t handle);
|
||||
</verb></tscreen>
|
||||
|
||||
On the Atari platform, the sector size is handled specially. Please refer
|
||||
to the DIO section in the <htmlurl url="atari.html" name="Atari">
|
||||
specific platform documentation.
|
||||
<p>
|
||||
|
||||
The following function returns the sector count of the currently inserted disk:
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned __fastcall__ dio_query_sectcount (dhandle_t handle);
|
||||
</verb></tscreen>
|
||||
|
||||
<sect>Converting sector numbers<p>
|
||||
|
||||
Since the read and write functions expect a sector number, for systems where
|
||||
the sectors aren't addressed by a logical sector number (e.g. CBM devices),
|
||||
there are 2 conversion functions. One of them converts a logical sector number
|
||||
to a head/track/sector triple. The other conversion function works the other
|
||||
way round.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
|
||||
const dio_phys_pos *physpos,
|
||||
unsigned *sectnum);
|
||||
</verb></tscreen>
|
||||
|
||||
This function converts track/head/sector to logical sector number.
|
||||
|
||||
<tscreen><verb>
|
||||
unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle,
|
||||
const unsigned *sectnum,
|
||||
dio_phys_pos *physpos);
|
||||
</verb></tscreen>
|
||||
|
||||
This function converts a logical sector number to track/head/sector notation.
|
||||
<p>
|
||||
|
||||
Note, that on systems which natively use logical sector numbers (e.g. Atari),
|
||||
the conversion functions are dummies. They ignore head/track
|
||||
(<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>).
|
||||
The logical sector number is returned as physical sector and vice versa.
|
||||
<p>
|
||||
|
||||
|
||||
</article>
|
||||
33
doc/doc.css
Normal file
33
doc/doc.css
Normal file
@ -0,0 +1,33 @@
|
||||
body {
|
||||
font-family: arial, helvetica, sans-serif;
|
||||
font-size: 100%;
|
||||
text-align: justify;
|
||||
margin-left: 110px;
|
||||
margin-top: 10px;
|
||||
margin-right: 30px;
|
||||
margin-bottom: 10px;
|
||||
background-image: url(doc.png);
|
||||
background-repeat: repeat-y;
|
||||
}
|
||||
|
||||
h1, h2, h2 a:link, h2 a:active, h2 a:visited {
|
||||
font-weight: bold;
|
||||
font-style: italic;
|
||||
text-align: left;
|
||||
color: #DB3232;
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 250%;
|
||||
text-shadow: 2px 2px 6px #505050;
|
||||
letter-spacing: 2px;
|
||||
padding-top: 40px;
|
||||
}
|
||||
|
||||
h2 {
|
||||
font-size: 160%;
|
||||
text-shadow: 2px 2px 6px #303030;
|
||||
letter-spacing: 1px;
|
||||
margin-top: 2em;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
BIN
doc/doc.png
Normal file
BIN
doc/doc.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.3 KiB |
7439
doc/funcref.sgml
Normal file
7439
doc/funcref.sgml
Normal file
File diff suppressed because it is too large
Load Diff
1662
doc/geos.sgml
Normal file
1662
doc/geos.sgml
Normal file
File diff suppressed because it is too large
Load Diff
392
doc/grc65.sgml
Normal file
392
doc/grc65.sgml
Normal file
@ -0,0 +1,392 @@
|
||||
<!doctype linuxdoc system>
|
||||
<article>
|
||||
|
||||
<!-- Title information -->
|
||||
|
||||
<title>grc65 -- GEOS Resource Compiler
|
||||
<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl">
|
||||
<and><url name="Greg King" url="mailto:gngking@erols.com">
|
||||
<date>VII 2000; VI,VII 2002; 2005-8-3
|
||||
<abstract>
|
||||
This document describes a compiler that can create GEOS headers and menues for
|
||||
cc65-compiled programs.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview
|
||||
<p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to
|
||||
generate required and optional resources. A required resource for every GEOS
|
||||
application is the header, that is: an icon, some strings, and some addresses.
|
||||
Optional resources might be menu definitions, other headers (e.g., for data
|
||||
files of an app.), dialog definitions, etc. Without an application's header,
|
||||
GEOS is unable to load and start it.
|
||||
|
||||
Currently, <bf/grc65/ supports only menues and the required header definition,
|
||||
along with support for building applications with VLIR-structured overlays.
|
||||
|
||||
<bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s).
|
||||
That is because the application header data must be in assembly format, while
|
||||
the menu definitions can be translated easily into C. The purpose of the C
|
||||
file is to include it as a header in only one project file. The assembly source
|
||||
should be processed by <bf/ca65/ and linked to the application (read about
|
||||
<ref name="the building process" id="building-seq">).
|
||||
|
||||
|
||||
|
||||
<sect>Usage
|
||||
<p>grc65 accepts the following options:
|
||||
|
||||
<tscreen><verb>
|
||||
---------------------------------------------------------------------------
|
||||
Usage: grc65 [options] file
|
||||
Short options:
|
||||
-V Print the version number
|
||||
-h Help (this text)
|
||||
-o name Name the C output file
|
||||
-s name Name the asm output file
|
||||
-t sys Set the target system
|
||||
|
||||
Long options:
|
||||
--help Help (this text)
|
||||
--target sys Set the target system
|
||||
--version Print the version number
|
||||
---------------------------------------------------------------------------
|
||||
</verb></tscreen>
|
||||
Default output names are made from input names with extensions replaced by
|
||||
<tt/.h/ and <tt/.s/.
|
||||
|
||||
|
||||
|
||||
<sect>Resource file format
|
||||
<p>A resource file has the name extension <tt/.grc/. That is not required, but
|
||||
it will make for an easier recognition of the file's purpose. Also, <bf/cl65/
|
||||
recognizes those files. <bf/grc65/'s parser is very weak at the moment; so,
|
||||
read the comments carefully, and write resources exactly as they are written
|
||||
here. Look out for CAPS and small letters. Everything after a '<tt/;/'
|
||||
until the end of the line is considered as a comment and ignored. See the
|
||||
included <ref name="commented example .grc file" id="example-grc"> for a
|
||||
better view of the situation.
|
||||
|
||||
|
||||
<sect1>Menu definition
|
||||
<p><tscreen><verb>
|
||||
MENU menuName leftx,topy <ORIENTATION> {
|
||||
"item name 1" <MENU_TYPE> pointer
|
||||
...
|
||||
"item name x" <MENU_TYPE> pointer
|
||||
}</verb></tscreen>
|
||||
The definition starts with the keyword <tt/MENU/, then comes the menu's name,
|
||||
which will be represented in C as <tt/const void/. Then are the co-ordinates
|
||||
of the top left corner of the menu box. The position of the bottom right
|
||||
corner is estimated, based on the length of item names and the menu's
|
||||
orientation. It means that the menu box always will be as large as it should
|
||||
be. Then, there's the orientation keyword; it can be either <tt/HORIZONTAL/ or
|
||||
<tt/VERTICAL/. Between <tt/{/ and <tt/}/, there's the menu's
|
||||
content. It consists of item definitions. First is an item name -- it has to
|
||||
be in quotes. Next is a menu-type bit. It can be <tt/MENU_ACTION/ or
|
||||
<tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit
|
||||
(see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of
|
||||
them). You can use C logical operators in expressions, but you have to do it
|
||||
without spaces. So a dynamically created submenu will be something like:
|
||||
<tscreen><verb>
|
||||
"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen>
|
||||
The last part of the item definition is a pointer which can be any name that is
|
||||
present in the C source code that includes the generated header. It can point
|
||||
to a function or to another menu definition.
|
||||
|
||||
If you are doing sub(sub)menu definitions, remember to place the lowest level
|
||||
definition first, and the top-level menu as the last one. That way the C
|
||||
compiler won't complain about unknown names.
|
||||
|
||||
|
||||
<sect1>Header definition
|
||||
<p><tscreen><verb>
|
||||
HEADER <GEOS_TYPE> "dosname" "classname" "version" {
|
||||
author "Joe Schmoe"
|
||||
info "This is my killer-app!"
|
||||
date yy mm dd hh ss
|
||||
dostype SEQ
|
||||
mode any
|
||||
structure SEQ
|
||||
icon "sprite.raw"
|
||||
}</verb></tscreen>
|
||||
The header definition describes the GEOS header sector which is unique to
|
||||
each file. The definition starts with the keyword <tt/HEADER/, then goes the
|
||||
GEOS file-type. You can use only <tt/APPLICATION/ here at the moment. Then,
|
||||
there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS
|
||||
Class name (up to 12 characters), and the version info (up to 4 characters).
|
||||
The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the
|
||||
major, and <em/y/ is the minor, version number. Those fields, along with both
|
||||
braces, are required. The lines between braces are optional, and will be replaced
|
||||
by default and current values. The keyword <tt/author/ and its value in quotes name
|
||||
the programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can
|
||||
have up to 95 characters. If the <tt/date/ field is omitted, then the time of
|
||||
that compilation will be placed into the header. Note that, if you do specify
|
||||
the date, you have to write all 5 numbers. The <tt/dostype/ can be <tt/SEQ/,
|
||||
<tt/PRG/, or <tt/USR/. <tt/USR/ is used by default; GEOS usually doesn't care.
|
||||
The <tt/mode/ can be <tt/any/, <tt/40only/, <tt/80only/, or <tt/c64only/; and,
|
||||
it describes system requirements. <tt/any/ will work on both 64-GEOS and
|
||||
128-GEOS, in 40- and 80-column modes. <tt/40only/ will work on 128-GEOS in
|
||||
40-column mode only. <tt/80only/ will work on only 128-GEOS in 80-column mode,
|
||||
and <tt/c64only/ will work on only 64-GEOS. The default value for
|
||||
<tt/structure/ is <tt/SEQ/ (sequential). You can put <tt/VLIR/ there, too; but
|
||||
then, you also have to put in a third type of resource -- a memory definition.
|
||||
The value of <tt/icon/ is a quoted file-name. The first 63 bytes of this file
|
||||
are expected to represent a standard monochrome VIC sprite. The file gets accessed
|
||||
when the generated assembly source is being processed by <bf/ca65/. Examples for
|
||||
programs generating such files are <em/Sprite Painter/, <em/SpritePad/ and the
|
||||
<url name="sp65 sprite and bitmap utility" url="sp65.html">. The default <tt/icon/
|
||||
is an empty frame internally represented in the generated assembly file.
|
||||
|
||||
|
||||
<sect1>Memory definition
|
||||
<p><tscreen><verb>
|
||||
MEMORY {
|
||||
stacksize 0x0800
|
||||
overlaysize 0x2000
|
||||
overlaynums 0 1 2 4 5
|
||||
}</verb></tscreen>
|
||||
The memory definition is unique to each file and describes several attributes related
|
||||
to the memory layout. It consists of the keyword <tt/MEMORY/ followed by braces which
|
||||
contain optional lines. The value of <tt/stacksize/ can be either decimal (e.g.
|
||||
<tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/). The default value
|
||||
of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be
|
||||
either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied
|
||||
background screen buffer while the latter means that the program uses the memory of the
|
||||
background screen buffer for own purposes. The default value of <tt/yes/ comes from the
|
||||
linker configuration file. If the <tt/structure/ in the header definition is set to the
|
||||
value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the
|
||||
VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number
|
||||
0. It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g.
|
||||
<tt/0x1000/). <tt/overlaynums/ defines the VLIR record numbers used by the application.
|
||||
Skipped numbers denote empty records. In the example, record number 3 is missing. Read
|
||||
<ref name="this description" id="building-vlir"> for details.
|
||||
|
||||
|
||||
|
||||
<sect>Building a GEOS sequential application<label id="building-seq">
|
||||
<p>Before proceeding, please read the <url name="compiler" url="cc65.html">,
|
||||
<url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html">
|
||||
documentation, and find the appropriate sections about building programs, in
|
||||
general.
|
||||
|
||||
GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in
|
||||
the GEOS world. It means that each file built with the cc65 package has to be
|
||||
deconverted in GEOS, before it can be run. You can read a step-by-step
|
||||
description of that in the <url name="GEOS section of the cc65 Compiler Intro"
|
||||
url="intro-6.html#ss6.5">.
|
||||
|
||||
Each project consists of four parts, two are provided by cc65. Those parts
|
||||
are:<enum>
|
||||
<item>application header
|
||||
<item>start-up object
|
||||
<item>application objects
|
||||
<item>system library
|
||||
</enum>
|
||||
<bf/2./ and <bf/4./ come with cc65; however you have to write the application
|
||||
yourself ;-)
|
||||
|
||||
The application header is defined in the <tt/HEADER/ section of the <tt/.grc/
|
||||
file and is processed into an assembly <tt/.s/ file. You must assemble it, with
|
||||
<bf/ca65/, into the object <tt/.o/ format.
|
||||
|
||||
Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C
|
||||
source), &dquot;<tt/test.h/&dquot; (a header file), and
|
||||
&dquot;<tt/testres.grc/&dquot; (with menu and header definitions). Note the
|
||||
fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot;
|
||||
because you will have to be very careful with names (<bf/grc65/ will make
|
||||
&dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of
|
||||
&dquot;<tt/test.grc/&dquot; by default; and you don't want that because
|
||||
&dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and
|
||||
&dquot;<tt/test.h/&dquot; is something completely different)!
|
||||
|
||||
<bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
|
||||
<tscreen><verb>
|
||||
#include <geos.h>
|
||||
#include "testres.h"
|
||||
</verb></tscreen>
|
||||
There are no other includes.
|
||||
|
||||
|
||||
<sect1>Building the GEOS application using cl65
|
||||
<p>This is a simple one step process:
|
||||
<tscreen><verb>
|
||||
cl65 -t geos-cbm -O -o test.cvt testres.grc test.c
|
||||
</verb></tscreen>
|
||||
Always place the <tt/.grc/ file as first input file on the command-line in order
|
||||
to make sure that the generated <tt/.h/ file is available when it is needed for
|
||||
inclusion by a <tt/.c/ file.
|
||||
|
||||
|
||||
<sect1>Building the GEOS application without cl65
|
||||
<sect2>First step -- compiling the resources
|
||||
<p>
|
||||
<tscreen><verb>
|
||||
grc65 -t geos-cbm testres.grc
|
||||
</verb></tscreen>
|
||||
will produce two output files: &dquot;<tt/testres.h/&dquot; and
|
||||
&dquot;<tt/testres.s/&dquot;.
|
||||
|
||||
Note that &dquot;<tt/testres.h/&dquot; is included at the top of
|
||||
&dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step.
|
||||
|
||||
<sect2>Second step -- assembling the application header
|
||||
<p>
|
||||
<tscreen><verb>
|
||||
ca65 -t geos-cbm testres.s
|
||||
</verb></tscreen>
|
||||
And, voilá -- &dquot;<tt/testres.o/&dquot; is ready.
|
||||
|
||||
<sect2>Third step -- compiling the code
|
||||
<p>
|
||||
<tscreen><verb>
|
||||
cc65 -t geos-cbm -O test.c
|
||||
ca65 -t geos-cbm test.s
|
||||
</verb></tscreen>
|
||||
That way, you have a &dquot;<tt/test.o/&dquot; object file which
|
||||
contains all of the executable code.
|
||||
|
||||
<sect2>Fourth and last step -- linking the application
|
||||
<p>
|
||||
<tscreen><verb>
|
||||
ld65 -t geos-cbm -o test.cvt testres.o test.o geos-cbm.lib
|
||||
</verb></tscreen>
|
||||
The last file is the GEOS system library.
|
||||
|
||||
The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
|
||||
contained in the well-known GEOS <em/Convert/ format. Note that its name
|
||||
(<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name
|
||||
that was given in the header definition.
|
||||
|
||||
At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is
|
||||
required for the correct process of GEOS sequential application building.
|
||||
|
||||
|
||||
|
||||
<sect>Building a GEOS VLIR overlay application<label id="building-vlir">
|
||||
<p>Large GEOS applications typically don't fit in one piece in their designated
|
||||
memory area. They are therefore split into overlays which are loaded into memory
|
||||
on demand. The individual overlays are stored as records of a VLIR (Variable
|
||||
Length Index Record) file. When GEOS starts a VLIR overlay appliation it loads
|
||||
record number 0 which is supposed to contain the main program. The record numbers
|
||||
starting with 1 are to be used for the actual overlays.
|
||||
|
||||
In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting
|
||||
of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/".
|
||||
|
||||
|
||||
<sect1>Building the GEOS overlay application using cl65
|
||||
<p>This is a simple one step process:
|
||||
<tscreen><verb>
|
||||
cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c
|
||||
</verb></tscreen>
|
||||
Always place the <tt/.grc/ file as first input file on the command-line in order
|
||||
to make sure that the generated <tt/.h/ file is available when it is needed for
|
||||
inclusion by a <tt/.c/ file.
|
||||
|
||||
You will almost certainly want to generate a map file that shows (beside a lot of
|
||||
other infos) how large your individual overlays are. This info is necessary to tune
|
||||
the distribution of code into the overlays and to optimize the memory area reserved
|
||||
for the overlays.
|
||||
|
||||
|
||||
<sect1>Building the GEOS overlay application without cl65
|
||||
<sect2>First step -- compiling the overlay resources
|
||||
<p>
|
||||
<tscreen><verb>
|
||||
grc65 -t geos-cbm overlay-demores.grc
|
||||
</verb></tscreen>
|
||||
|
||||
<sect2>Second step -- assembling the overlay application header
|
||||
<p>
|
||||
<tscreen><verb>
|
||||
ca65 -t geos-cbm overlay-demores.s
|
||||
</verb></tscreen>
|
||||
|
||||
<sect2>Third step -- compiling the overlay code
|
||||
<p>
|
||||
<tscreen><verb>
|
||||
cc65 -t geos-cbm -O overlay-demo.c
|
||||
ca65 -t geos-cbm overlay-demo.s
|
||||
</verb></tscreen>
|
||||
|
||||
<sect2>Fourth and last step -- linking the overlay application
|
||||
<p>
|
||||
<tscreen><verb>
|
||||
ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos-cbm.lib
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
|
||||
<sect>Bugs and feedback
|
||||
<p>This is the first release of <bf/grc65/, and it contains bugs, for sure! I
|
||||
am aware of them; I know that the parser is weak, and if you don't follow the
|
||||
grammar rules strictly, then everything will crash. However, if you find an
|
||||
interesting bug, mail me. :-) Mail me also for help with writing your
|
||||
<tt/.grc/ file correctly if you have problems with it. I would appreciate
|
||||
comments also, and help on this file because I am sure that it can be written
|
||||
better.
|
||||
|
||||
|
||||
|
||||
<sect>Legal stuff
|
||||
<p><bf/grc65/ is covered by the same license as the whole cc65 package, so you
|
||||
should see its documentation for more info. Anyway, if you like it, and want
|
||||
to encourage me to work more on it, send me a postcard with a sight of your
|
||||
neighbourhood, city, region, etc. Or, just e-mail me with info that you
|
||||
actually used it. See <url name="the GEOSLib documentation" url="geos.html">
|
||||
for addresses.
|
||||
|
||||
|
||||
|
||||
<appendix>
|
||||
<sect>Appendix A -- example.grc<label id="example-grc">
|
||||
<p><tscreen><verb>
|
||||
; Note that MENU can define both menues and submenues.
|
||||
; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT
|
||||
; any spaces between the arguments (the parser is simple and weak).
|
||||
|
||||
MENU subMenu1 15,0 VERTICAL
|
||||
; This is a vertical menu, placed at (15,0).
|
||||
{
|
||||
; There are three items, all of them will call functions.
|
||||
; The first and third ones are normal functions, see GEOSLib documentation for
|
||||
; information about what the second function should return (it's a dynamic one).
|
||||
"subitem1" MENU_ACTION smenu1
|
||||
"subitem2" MENU_ACTION|DYN_SUB_MENU smenu2
|
||||
"subitem3" MENU_ACTION smenu3
|
||||
}
|
||||
|
||||
;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... }
|
||||
|
||||
MENU mainMenu 0,0 HORIZONTAL
|
||||
; Here, we have our main menu, placed at (0,0), and it is a horizontal menu.
|
||||
; Because it is a top-level menu, you would register it in your C source by
|
||||
; using: DoMenu(&ero;mainMenu);
|
||||
{
|
||||
; There are two items -- a submenu and an action.
|
||||
; This calls a submenu named subMenu1 (see previous definition).
|
||||
"first sub-menu" SUB_MENU subMenu1
|
||||
; This will work the same as an EnterDeskTop() call in C source code.
|
||||
"quit" MENU_ACTION EnterDeskTop
|
||||
}
|
||||
|
||||
;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version"
|
||||
|
||||
HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
|
||||
; This is a header for an APPLICATION which will be seen in the directory as a
|
||||
; file named MyFirstApp with the Class-string "Class Name V1.0"
|
||||
{
|
||||
; Not all fields are required, default and current values will be used.
|
||||
author "Maciej Witkowiak" ; always in quotes!
|
||||
info "Information text" ; always in quotes!
|
||||
; date yy mm dd hh ss ; always 5 fields!
|
||||
; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case)
|
||||
; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case)
|
||||
mode c64only ; can be: any, 40only, 80only, c64only
|
||||
}</verb></tscreen>
|
||||
</article>
|
||||
4
doc/header.html
Normal file
4
doc/header.html
Normal file
@ -0,0 +1,4 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
|
||||
150
doc/index.sgml
Normal file
150
doc/index.sgml
Normal file
@ -0,0 +1,150 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>cc65 Documentation Overview
|
||||
<author><htmlurl url="https://github.com/oliverschmidt/cc65" name="">
|
||||
<date>
|
||||
|
||||
<sect>Program documentation<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><htmlurl url="ar65.html" name="ar65.html"></tag>
|
||||
Describes the ar65 archiver.
|
||||
|
||||
<tag><htmlurl url="ca65.html" name="ca65.html"></tag>
|
||||
Describes the ca65 macro assembler.
|
||||
|
||||
<tag><htmlurl url="cc65.html" name="cc65.html"></tag>
|
||||
Describes the cc65 C compiler.
|
||||
|
||||
<tag><htmlurl url="cl65.html" name="cl65.html"></tag>
|
||||
Describes the cl65 compile & link utility.
|
||||
|
||||
<tag><htmlurl url="co65.html" name="co65.html"></tag>
|
||||
Describes the co65 object-file converter.
|
||||
|
||||
<tag><htmlurl url="da65.html" name="da65.html"></tag>
|
||||
Describes the da65 6502/65C02 disassembler.
|
||||
|
||||
<tag><htmlurl url="grc65.html" name="grc65.html"></tag>
|
||||
Describes the GEOS resource compiler (grc65).
|
||||
|
||||
<tag><htmlurl url="ld65.html" name="ld65.html"></tag>
|
||||
Describes the ld65 linker.
|
||||
|
||||
<tag><htmlurl url="od65.html" name="od65.html"></tag>
|
||||
Describes the od65 object-file analyzer.
|
||||
|
||||
<tag><htmlurl url="sp65.html" name="sp65.html"></tag>
|
||||
Describes the sprite and bitmap utility.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect>Usage<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><htmlurl url="intro.html" name="intro.html"></tag>
|
||||
Describes the use of the tools, by building a short &dquot;hello world&dquot;
|
||||
example.
|
||||
|
||||
<tag><htmlurl url="coding.html" name="coding.html"></tag>
|
||||
Contains hints on creating the most effective code with cc65.
|
||||
|
||||
<tag><htmlurl url="using-make.html" name="using-make.html"></tag>
|
||||
Build programs, using the GNU Make utility.
|
||||
|
||||
<tag><htmlurl url="customizing.html" name="customizing.html"></tag>
|
||||
How to use the cc65 toolset for a custom hardware platform (a target system
|
||||
not currently supported by the cc65 library set).
|
||||
|
||||
<tag><htmlurl url="debugging.html" name="debugging.html"></tag>
|
||||
Debug programs, using the VICE emulator.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect>Library information and other references<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><htmlurl url="funcref.html" name="funcref.html"></tag>
|
||||
A (currently incomplete) function reference.
|
||||
|
||||
<tag><htmlurl url="dio.html" name="dio.html"></tag>
|
||||
Low-level disk I/O API.
|
||||
|
||||
<tag><htmlurl url="geos.html" name="geos.html"></tag>
|
||||
The GEOSLib manual.
|
||||
|
||||
<tag><htmlurl url="library.html" name="library.html"></tag>
|
||||
An overview over the cc65 runtime and C libraries.
|
||||
|
||||
<tag><htmlurl url="smc.html" name="smc.html"></tag>
|
||||
Describes Christian Krügers macro package for writing self modifying
|
||||
assembler code.
|
||||
|
||||
<tag><url name="6502 Binary Relocation Format document"
|
||||
url="http://www.6502.org/users/andre/o65/fileformat.html"></tag>
|
||||
Describes the o65 file format that is used for dynamically loadable modules
|
||||
and LUnix programs.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect>Platform-specific information<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><htmlurl url="apple2.html" name="apple2.html"></tag>
|
||||
Topics specific to the Apple ][.
|
||||
|
||||
<tag><htmlurl url="apple2enh.html" name="apple2enh.html"></tag>
|
||||
Topics specific to the enhanced Apple //e.
|
||||
|
||||
<tag><htmlurl url="atari.html" name="atari.html"></tag>
|
||||
Topics specific to the Atari 8-bit machines.
|
||||
|
||||
<tag><htmlurl url="atmos.html" name="atmos.html"></tag>
|
||||
Topics specific to the Oric Atmos.
|
||||
|
||||
<tag><htmlurl url="c128.html" name="c128.html"></tag>
|
||||
Topics specific to the Commodore 128.
|
||||
|
||||
<tag><htmlurl url="c16.html" name="c16.html"></tag>
|
||||
Topics specific to the Commodore 16/116.
|
||||
|
||||
<tag><htmlurl url="c64.html" name="c64.html"></tag>
|
||||
Topics specific to the Commodore 64.
|
||||
|
||||
<tag><htmlurl url="cbm510.html" name="cbm510.html"></tag>
|
||||
Topics specific to the Commodore 510.
|
||||
|
||||
<tag><htmlurl url="cbm610.html" name="cbm610.html"></tag>
|
||||
Topics specific to the Commodore 610.
|
||||
|
||||
<tag><htmlurl url="lynx.html" name="lynx.html"></tag>
|
||||
Topics specific to the Atari Lynx Game Console.
|
||||
|
||||
<tag><htmlurl url="nes.html" name="nes.html"></tag>
|
||||
Topics specific to the Nintendo Entertainment System.
|
||||
|
||||
<tag><htmlurl url="pet.html" name="pet.html"></tag>
|
||||
Topics specific to the Commodore PET machines.
|
||||
|
||||
<tag><htmlurl url="plus4.html" name="plus4.html"></tag>
|
||||
Topics specific to the Commodore Plus/4.
|
||||
|
||||
<tag><htmlurl url="supervision.html" name="supervision.html"></tag>
|
||||
Topics specific to the Supervision Console.
|
||||
|
||||
<tag><htmlurl url="vic20.html" name="vic20.html"></tag>
|
||||
Topics specific to the Commodore VIC20.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
</article>
|
||||
|
||||
527
doc/intro.sgml
Normal file
527
doc/intro.sgml
Normal file
@ -0,0 +1,527 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>cc65 Compiler Intro
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">,
|
||||
<and>CbmNut, <htmlurl url="mailto:cbmnut@hushmail.com" name="cbmnut@hushmail.com">,
|
||||
<and><url name="Greg King" url="mailto:gngking@erols.com">
|
||||
<date>2005-7-22
|
||||
|
||||
<abstract>
|
||||
How to use the cc65 C language system -- an introduction.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This is a short intro of how to use the compiler and the bin-utils. It contains
|
||||
a step-by-step example of how to build a complete application from one C and
|
||||
one assembly modules. This file does <em/not/ contain a complete reference for
|
||||
the tools used in the process. There are separate files describing those tools,
|
||||
in detail (see <url url="index.html">).
|
||||
|
||||
I do assume that you have downloaded and installed the compiler and
|
||||
target-specific files. Windows users should use the friendly .exe installer
|
||||
(named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the
|
||||
version number if necessary). It does not only install the target files, but
|
||||
will also set up necessary environment variables for you.
|
||||
|
||||
If you're going for the .ZIP archives, please note that there is one file for
|
||||
the host platform (Windows, DOS or OS/2), one file for each target platform
|
||||
(C64 or whatever) and a separate file containing the docs (which include the
|
||||
file you're currently reading). So for most uses, you will need at least 3
|
||||
files and unpack all three into one directory. In case of the .ZIP archives,
|
||||
you will also need to set the environment variables <tt/CC65_INC/,
|
||||
<tt/LD65_LIB/ and <tt/LD65_CFG/ as described below.
|
||||
|
||||
<bf/Note/: There is a much simpler way to compile this example, by using the
|
||||
<bf/cl65/ compile-and-link utility. However, it makes sense to understand how
|
||||
the separate steps work. How to do the example with the <bf/cl65/ utility is
|
||||
described <ref id="using-cl65" name="later">.
|
||||
|
||||
|
||||
<sect1>Before we start<p>
|
||||
|
||||
You will find a copy of the sample modules, used in the next section, in the
|
||||
"<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with
|
||||
missing include files and/or libraries, please check the environment variables
|
||||
<tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the
|
||||
<tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you
|
||||
installed cc65.
|
||||
|
||||
|
||||
<sect1>The sample modules<p>
|
||||
|
||||
To explain the development flow, I will use the following example modules:
|
||||
|
||||
hello.c:
|
||||
<tscreen><code>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
|
||||
extern const char text[]; /* In text.s */
|
||||
|
||||
int main (void)
|
||||
{
|
||||
printf ("%s\n", text);
|
||||
return EXIT_SUCCESS;
|
||||
}
|
||||
</code></tscreen>
|
||||
|
||||
text.s:
|
||||
<tscreen><code>
|
||||
.export _text
|
||||
_text: .asciiz "Hello world!"
|
||||
</code></tscreen>
|
||||
|
||||
|
||||
<sect1>Translation phases<p>
|
||||
|
||||
We assume that the target file should be named "hello", and the target system
|
||||
is the C64.
|
||||
|
||||
<tscreen><verb>
|
||||
+---------+
|
||||
| hello.c |
|
||||
+---------+
|
||||
|
|
||||
cc65
|
||||
\/
|
||||
+---------+ +---------+ +---------+
|
||||
| hello.s | | text.s | | crt0.o |
|
||||
+---------+ +---------+ +---------+
|
||||
| | |
|
||||
ca65 ca65 ar65
|
||||
\/ \/ \/
|
||||
+---------+ +---------+ +---------+
|
||||
| hello.o | | text.o | | c64.lib |
|
||||
+---------+ +---------+ +---------+
|
||||
| \ /
|
||||
| \ /
|
||||
| \ /
|
||||
+----------------------->ld65<
|
||||
\/
|
||||
hello
|
||||
</verb></tscreen>
|
||||
|
||||
<tt/crt0.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime
|
||||
and C library) are provided in binary form in the cc65 package. Actually, the
|
||||
startup code is contained in the library, so you won't need to care about it.
|
||||
|
||||
|
||||
|
||||
<sect>The compiler<p>
|
||||
|
||||
The compiler translates one C source into one assembly source, for each
|
||||
invocation. It does <em/not/ create object files directly, and it is <em/not/
|
||||
able to translate more than one file per run.
|
||||
|
||||
In the example above, we would use the following command line, to translate
|
||||
<tt/hello.c/ into <tt/hello.s/:
|
||||
|
||||
<tscreen><verb>
|
||||
cc65 -O -t c64 hello.c
|
||||
</verb></tscreen>
|
||||
|
||||
The <tt/-O/ switch tells the compiler to do an additional optimizer run, which
|
||||
is usually a good idea, since it makes the code smaller. If you don't care
|
||||
about the size, but want to have slightly faster code, use <tt/-Oi/ to inline
|
||||
some runtime functions.
|
||||
|
||||
The <tt/-t/ switch is followed by the target system name.
|
||||
|
||||
If the compiler does not complain about errors in our "hello world" program, we
|
||||
will have a file named "<tt/hello.s/", in our directory, that contains the
|
||||
assembly source for the <bf/hello/ module.
|
||||
|
||||
For more information about the compiler, see <url url="cc65.html">.
|
||||
|
||||
|
||||
|
||||
<sect>The assembler<p>
|
||||
|
||||
The assembler translates one assembly source into an object file, for each
|
||||
invocation. The assembler is <em/not/ able to translate more than one source
|
||||
file per run.
|
||||
|
||||
Let's translate the "hello.s" and "text.s" files from our example:
|
||||
|
||||
<tscreen><verb>
|
||||
ca65 hello.s
|
||||
ca65 -t c64 text.s
|
||||
</verb></tscreen>
|
||||
|
||||
The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the
|
||||
text is converted from the input character-set (usually ISO-8859-1) into the
|
||||
target character-set (PETSCII, in this example) by the assembler. The
|
||||
compiler-generated file <tt/hello.s/ does not contain any character constants,
|
||||
so specification of a target is not necessary (it wouldn't do any harm,
|
||||
however).
|
||||
|
||||
If the assembler does not complain, we should now have two object files (named
|
||||
<tt/hello.o/ and <tt/text.o/) in the current directory.
|
||||
|
||||
For more information about the assembler, see <url url="ca65.html">.
|
||||
|
||||
|
||||
|
||||
<sect>The linker<p>
|
||||
|
||||
The linker combines several object and library files into one output file.
|
||||
<bf/ld65/ is very configurable, but fortunately has built-in configurations,
|
||||
so we don't need to mess with configuration files, here.
|
||||
|
||||
The compiler uses small functions to do things that cannot be done inline
|
||||
without a big impact on code size. Those runtime functions, together with the
|
||||
C library, are in an object-file archive named after the system, in this case,
|
||||
"<tt/c64.lib/". We have to specify that file on the command line, so that the
|
||||
linker can resolve those functions.
|
||||
|
||||
Let's link our files to get the final executable:
|
||||
|
||||
<tscreen><verb>
|
||||
ld65 -o hello -t c64 hello.o text.o c64.lib
|
||||
</verb></tscreen>
|
||||
|
||||
The argument after <tt/-o/ specifies the name of the output file, the argument
|
||||
after <tt/-t/ gives the target system. The following arguments are object
|
||||
files or libraries. Since the target library resolves imports in <tt/hello.o/
|
||||
and <tt/text.o/, it must be specified <em/after/ those files.
|
||||
|
||||
After a successful linker run, we have a file named "<tt/hello/", ready for
|
||||
our C64!
|
||||
|
||||
For more information about the linker, see <url url="ld65.html">.
|
||||
|
||||
|
||||
|
||||
<sect>The easy way (using the cl65 utility)<label id="using-cl65"><p>
|
||||
|
||||
The <bf/cl65/ utility is able to do all of the steps described above, in just
|
||||
one command line, and it has defaults for some options that are very
|
||||
well-suited for our example.
|
||||
|
||||
To compile both files into one executable, enter:
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -O hello.c text.s
|
||||
</verb></tscreen>
|
||||
|
||||
The <bf/cl65/ utility knows how to translate C files into object files (it will
|
||||
call the compiler, and then the assembler). It does know also how to create
|
||||
object files from assembly files (it will call only the assembler, for that).
|
||||
It knows how to build an executable (it will pass all object files to the
|
||||
linker). And finally, it has the C64 as a default target, and will supply the
|
||||
correct startup file and runtime library names to the linker, so you don't
|
||||
have to care about that.
|
||||
|
||||
The one-liner above should give you a C64 executable named "<tt/hello/" in the
|
||||
current directory.
|
||||
|
||||
For more information about the compile & link utility, see <url
|
||||
url="cl65.html">.
|
||||
|
||||
|
||||
|
||||
<sect>Running The Executable<p>
|
||||
|
||||
<em/Note: this section is incomplete!/
|
||||
|
||||
Depending on the target, cc65 chooses several methods of making a program
|
||||
available for execution. Here, we list sample emulators and instructions for
|
||||
running the program. Unless noted, similar instructions would also apply to a
|
||||
real machine. One word of advice: we suggest you clear the screen at the
|
||||
start, and wait for a keypress at the end of your program, as each target
|
||||
varies in its start and exit conditions.
|
||||
|
||||
|
||||
<sect1>Apple
|
||||
|
||||
<sect2>AppleWin<p>
|
||||
Available at <url
|
||||
url="http://applewin.berlios.de/">:
|
||||
|
||||
Emulates Apple ][/enhanced Apple //e computers, with
|
||||
sound, video, joysticks, serial port, and disk images. Includes monitor. Only
|
||||
for Windows. The package comes with a DOS 3.3 disk (called "master.dsk") image;
|
||||
however, you will need <bf/AppleCommander 1.3.5/ or later (available at <url
|
||||
url="http://applecommander.sourceforge.net/">).
|
||||
|
||||
Compile the tutorial with
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -O -t apple2 hello.c text.s
|
||||
</verb></tscreen>
|
||||
for the Apple ][, or:
|
||||
<tscreen><verb>
|
||||
cl65 -O -t apple2enh hello.c text.s
|
||||
</verb></tscreen>
|
||||
for the enhanced Apple //e.
|
||||
|
||||
Then, put the file onto an Apple disk image, for use with an emulator. Copy
|
||||
the <tt/master.dsk/ which comes with <bf/AppleWin/, and rename it to
|
||||
<tt/cc65.dsk/, then use <bf/AppleCommander/:
|
||||
|
||||
<tscreen><verb>
|
||||
java -jar ac.jar -cc65 cc65.dsk test B < hello
|
||||
</verb></tscreen>
|
||||
|
||||
Note that a convention in the Apple world is that "hello" is the file which is
|
||||
run automatically upon booting a DOS disk, sort of like the "autoexec.bat" of
|
||||
the MSDOS/Windows world. We've avoided that in the example, however. Also,
|
||||
the <tt/B/ parameter must be in caps., and "test" is the name of the program as
|
||||
it will appear on the Apple disk.
|
||||
|
||||
Start the emulator, click on the <bf/Disk 1/ icon, and point to <bf/cc65.dsk/;
|
||||
then, click the big Apple logo, to boot the system. Then, type this on the
|
||||
Apple:
|
||||
|
||||
<tscreen><verb>
|
||||
BRUN TEST
|
||||
</verb></tscreen>
|
||||
|
||||
You will see the "Hello, World!" appear on the same line. Thanks to Oliver
|
||||
Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> for his help
|
||||
in completing this section.
|
||||
|
||||
|
||||
<sect1>Atari
|
||||
|
||||
<sect2>Atari800Win PLus<p>
|
||||
Available at <url
|
||||
url="http://www.atari.org.pl/PLus/index_us.htm">:
|
||||
|
||||
Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk
|
||||
images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM
|
||||
expansions. Includes monitor. Unfortunately, only for Windows. You will need
|
||||
the emulator, "atarixl.rom" or "atariosb.rom"/"ataribas.rom", and "dos25.xfd"
|
||||
files (not supplied).
|
||||
|
||||
Compile the tutorial with
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -O -t atari hello.c text.s
|
||||
</verb></tscreen>
|
||||
|
||||
Start the emulator, choose <bf/File>Autoboot image/ or <bf/File>Load
|
||||
executable/, and point to the "<bf/hello/" executable. It is customary to
|
||||
rename executables of that type to "<bf/hello.xex/". The file has a 7-byte
|
||||
header meant to be loaded directly from Atari DOS 2/2.5 or compatibles.
|
||||
|
||||
On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible.
|
||||
Turn on the computer, type
|
||||
|
||||
<tscreen><verb>
|
||||
DOS
|
||||
</verb></tscreen>
|
||||
|
||||
at the BASIC prompt, then choose <bf/N. CREATE MEM.SAV/,
|
||||
then choose <bf/L. BINARY LOAD/, and enter <tt/HELLO/.
|
||||
|
||||
The emulation, also, supports that method. Look at <bf/Atari>Settings/, and
|
||||
check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari>Hard
|
||||
disks/, and set the path of <bf/H1:/ to your executables directory, then use
|
||||
"<bf/H0:HELLO.XEX/" in the above procedure (after pressing <tt/L/), to access
|
||||
your harddrive directly.
|
||||
|
||||
<bf/Note/: There is no delay after the program exits, as you are returned
|
||||
to the DOS menu. Your C program should wait for a keypress if you want to see
|
||||
any output.
|
||||
|
||||
|
||||
<sect1>Atmos
|
||||
|
||||
<sect2>Oricutron<p>
|
||||
Available at <url
|
||||
url="http://code.google.com/p/oriculator/">:
|
||||
|
||||
Emulates Oric-1 and Atmos computers, with sound, disk images,
|
||||
scanline-exact NTSC/PAL video, and movie export. Includes monitor.
|
||||
Fortunately for all SDL platforms. You will just need the emulator, all
|
||||
ROMs are supplied.
|
||||
|
||||
Compile the tutorial with
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -O -t atmos hello.c text.s -o hello.tap
|
||||
</verb></tscreen>
|
||||
|
||||
Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to
|
||||
the "<bf/hello.tap/" executable. The file has an auto start header meant to
|
||||
be loaded directly from tape.
|
||||
|
||||
On a real Atmos, you would need a tape drive.
|
||||
Turn on the computer, type
|
||||
|
||||
<tscreen><verb>
|
||||
CLOAD""
|
||||
</verb></tscreen>
|
||||
|
||||
at the BASIC prompt.
|
||||
|
||||
The emulation, also, supports that method.
|
||||
|
||||
|
||||
<sect1>Commodore
|
||||
|
||||
<sect2>VICE<p>
|
||||
Available at <url
|
||||
url="http://vice-emu.sourceforge.net/">:
|
||||
|
||||
Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports
|
||||
printers, serial port and adapters, stereo sound, disk drives and images, RAM expansions,
|
||||
cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, graphics tablet,
|
||||
lightpens, and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2,
|
||||
BeOS x86, Acorn RISC OS, and most Unixes.
|
||||
|
||||
Compile the tutorial with
|
||||
<tscreen><verb>
|
||||
cl65 -O -t <sys> hello.c text.s
|
||||
</verb></tscreen>
|
||||
Substitute the name of a Commodore computer for that <tt/<sys>/:
|
||||
<itemize>
|
||||
<item><tt/c128/
|
||||
<item><tt/c16/
|
||||
<item><tt/c64/
|
||||
<item><tt/cbm510/
|
||||
<item><tt/cbm610/
|
||||
<item><tt/pet/
|
||||
<item><tt/plus4/
|
||||
<item><tt/vic20/
|
||||
</itemize>
|
||||
|
||||
Start the desired version of the emulator (CBM610 programs run on
|
||||
the CBM II [<tt/xcbm2/] emulator).
|
||||
|
||||
In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape
|
||||
image...</bf>, choose your executable, and click <bf/OK/.
|
||||
|
||||
In the Unix versions, hold down the mouse's first button. Move the pointer to
|
||||
<bf>Smart-attach disk/tape...</bf>, and release the button. Choose your
|
||||
executable, and click <bf/Autostart/.
|
||||
|
||||
The file has a 14-byte header which corresponds to a PRG-format BASIC program,
|
||||
consisting of a single line, similar to this:
|
||||
|
||||
<tscreen><code>
|
||||
1000 sys2061
|
||||
</code></tscreen>
|
||||
|
||||
On a real Commodore with attached disk drive, you would type:
|
||||
|
||||
<tscreen><verb>
|
||||
LOAD "0:HELLO",8
|
||||
</verb></tscreen>
|
||||
|
||||
for VIC-20/C64, or:
|
||||
|
||||
<tscreen><verb>
|
||||
DLOAD "HELLO"
|
||||
</verb></tscreen>
|
||||
|
||||
on PET/CBM II/C128/C16/Plus 4; then, type
|
||||
|
||||
<tscreen><verb>
|
||||
RUN
|
||||
</verb></tscreen>
|
||||
|
||||
On a Commodore 128, you can combine those two commands:
|
||||
<tscreen><verb>
|
||||
RUN "HELLO"
|
||||
</verb></tscreen>
|
||||
|
||||
The output will appear on a separate line, and you will be returned to a BASIC
|
||||
prompt.
|
||||
|
||||
|
||||
<sect1>GEOS<p>
|
||||
Available at <it/Click Here Software's/ <url
|
||||
url="http://cbmfiles.com/geos/index.html" name="GEOS download section">:
|
||||
|
||||
<it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it>
|
||||
It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User
|
||||
Interface) for Commodore's computer models <bf/64/ and <bf/128/. It can be
|
||||
controlled by many different types of input devices:
|
||||
<itemize>
|
||||
<item>keyboard
|
||||
<item>joysticks
|
||||
<item>mice
|
||||
<item>trackballs
|
||||
<item>graphics drawing tablets
|
||||
<item>light-pens
|
||||
</itemize>
|
||||
|
||||
The tutorial files are different for GEOS. You will find them "next door," in
|
||||
"<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and
|
||||
"<tt/hello1res.grc/".
|
||||
|
||||
Compile the tutorial with
|
||||
<tscreen><verb>
|
||||
cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c
|
||||
</verb></tscreen>
|
||||
Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk.
|
||||
|
||||
Boot the GEOS master disk/image.
|
||||
|
||||
<quote>
|
||||
When you want to run GEOS in an emulator, you must adjust that emulator so that
|
||||
it does a "true drive" emulation. Each emulator has its own way of turning that
|
||||
feature on.
|
||||
</quote>
|
||||
|
||||
<quote>
|
||||
VICE even has different ways that depend on which operating system is running
|
||||
the emulator.
|
||||
<itemize>
|
||||
<item>In Windows, you must click on <bf/Options/ (in an always visible menu).
|
||||
Then, you must click on <bf/True drive emulation/.
|
||||
<item>In Unix, you must <em/hold down/ the second button on your mouse. Move
|
||||
the pointer down to <bf/Drive settings/. Then, move the pointer over to
|
||||
<bf/Enable true drive emulation/. (If there is a check-mark in front of
|
||||
those words, that feature already is turned on -- then, move the pointer
|
||||
off of that menu.) Release the mouse button.
|
||||
</itemize>
|
||||
</quote>
|
||||
|
||||
Find the <bf/CONVERT/ program on the boot disk [tap the 6-key; then, you
|
||||
should see its icon in the fourth position on the <bf/deskTop/'s directory
|
||||
notePad]. Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click
|
||||
it to run that program. Click on the <bf/Disk/ icon; put the disk with
|
||||
"<tt/hello1/" into the drive; and, click the <bf/OK/ icon. Use the little
|
||||
icons under the list of file-names to move through that list until you find
|
||||
"<tt/hello1/". Click on it; and then, click on the <bf/Convrt/ icon.
|
||||
<bf/CONVERT/ will ask you to confirm that you choose the correct file; click
|
||||
<bf/YES/ if you did (or, click <bf/NO/ if you made a mistake). After the
|
||||
program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will
|
||||
announce what it did -- click on <bf/OK/. <bf/CONVERT/ will show the file list
|
||||
again. This time, click on <bf/Quit/.
|
||||
|
||||
(You might need to put the boot disk back into the drive, in order to reload
|
||||
<bf/deskTop/. Then, you must swap back to the disk with the tutorial program
|
||||
on it, and click on its disk icon [on the right side of the screen].)
|
||||
|
||||
Now, you must find <bf/hello1/. Click on the lower left-hand corner of the
|
||||
directory notePad. Look at the eight file-positions on each page until you see
|
||||
<bf/hello1/. Double-click on its icon.
|
||||
|
||||
The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
|
||||
reading it.
|
||||
|
||||
|
||||
<sect1>Contributions wanted<p>
|
||||
|
||||
We need your help! Recommended emulators and instructions for other targets
|
||||
are missing. We suggest that you choose emulators with good compatibility.
|
||||
Also, being able to run all computers in the target series is good for
|
||||
target compatibility testing. A machine-language monitor is almost essential
|
||||
for debugging, but a native debugger could be used, as well.
|
||||
|
||||
Finally, emulators which run on Unix or Windows would help to reach a wider
|
||||
audience.
|
||||
|
||||
</article>
|
||||
1086
doc/ld65.sgml
Normal file
1086
doc/ld65.sgml
Normal file
File diff suppressed because it is too large
Load Diff
240
doc/library.sgml
Normal file
240
doc/library.sgml
Normal file
@ -0,0 +1,240 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>cc65 Library Overview
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2000-12-02, 2002-11-26
|
||||
|
||||
<abstract>
|
||||
An overview over the runtime and C libraries that come with the cc65 compiler,
|
||||
including a discussion of the differences to the ISO standard.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains a short overview of the libraries available for the cc65 C
|
||||
compiler. Please have a look at the <htmlurl url="funcref.html" name="function
|
||||
reference"> for a list function by function. Since the function reference is
|
||||
not complete (I'm working on that) it may happen that you don't find a
|
||||
specific function. In this case, have a look into the header files. All
|
||||
functions, that are not defined by the ISO C standard have a short comment in
|
||||
the headers, explaining their use.
|
||||
|
||||
|
||||
|
||||
<sect>ISO C compatible library<p>
|
||||
|
||||
The C library contains a large subset of the ISO C library. Functions are
|
||||
usually missing in areas, where there is no support on typical 6502 systems.
|
||||
Wide character sets are an example for this.
|
||||
|
||||
I will not go into detail about the ISO functions. If a function is not
|
||||
mentioned here explicitly, expect it to be available and to behave as defined
|
||||
in the C standard.
|
||||
|
||||
Functions that are <em/not/ available:
|
||||
|
||||
<itemize>
|
||||
<item><tt>tmpfile/tmpnam</tt>
|
||||
<p>
|
||||
<item><tt>system</tt>
|
||||
<p>
|
||||
<item>All functions that handle floating point numbers in some manner.
|
||||
<p>
|
||||
<item>The <tt/ldiv/ function (cc65 is currently not able to return structs
|
||||
with a size not equal to 1, 2 or 4 bytes by value).
|
||||
<p>
|
||||
<item>All functions handling wide character strings.
|
||||
<p>
|
||||
<item>Signals and all related functions (having <tt/SIGSEGV/ would be
|
||||
cool:-)
|
||||
<p>
|
||||
<item><tt>setbuf/setvbuf</tt>
|
||||
</itemize>
|
||||
|
||||
Functions not available on all supported systems:
|
||||
|
||||
<itemize>
|
||||
<item><tt>fopen/fread/fwrite/fclose/fputs/fgets/fscanf</tt>: The functions
|
||||
are built on open/read/write/close. These latter functions are not available
|
||||
on all systems.
|
||||
<p>
|
||||
<item><tt>ftell/fseek/fgetpos/fsetpos</tt>: Support depends on the
|
||||
capabilities of the target machine.
|
||||
<p>
|
||||
<item><tt>rename/remove/rewind</tt>: Support depends on the capabilities of
|
||||
the target machine.
|
||||
<p>
|
||||
<item><tt>time</tt>: Since many of the supported systems do not have a real
|
||||
time clock, which means that the <tt/time/ function is not available. Please
|
||||
note that the other functions from <tt/time.h/ <em/are/ available.
|
||||
</itemize>
|
||||
|
||||
|
||||
Functions that are limited in any way:
|
||||
|
||||
<itemize>
|
||||
<item><tt>strcspn/strpbrk/strspn</tt>: These functions have a length
|
||||
limitation of 256 for the second string argument. Since this string gives a
|
||||
character set, and there are only 256 distinct characters, this shouldn't be
|
||||
a problem.
|
||||
<p>
|
||||
<item><tt>getenv</tt>: Since there is no such thing as an environment on all
|
||||
supported systems, the <tt/getenv/ function will always return a <tt/NULL/
|
||||
pointer.
|
||||
<p>
|
||||
<item><tt>locale</tt>: There is no other locale than the "C" locale. The
|
||||
native locale is identical to the "C" locale.
|
||||
</itemize>
|
||||
|
||||
|
||||
In addition to these limitations, some more functions are limited if inlined
|
||||
versions are requested by using -Os:
|
||||
|
||||
<itemize>
|
||||
<item>The <tt/strlen/ function only works for strings with a maximum length
|
||||
of 255 characters.
|
||||
<p>
|
||||
<item>The <tt/isxxx/ character classification functions from
|
||||
<tt/<ctype.h>/ will give unpredictable results if the argument is not
|
||||
in character range (0..255). This limitation may be removed by #undef'ing
|
||||
the function name (when using <tt/-Os/, the functions are actually macros
|
||||
that expand to inline assembler code, but the real functions are still
|
||||
available if the macro definition is removed).
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect>CPU specific stuff - 6502.h<p>
|
||||
|
||||
The header file 6502.h contains some functions that make only sense with the
|
||||
6502 CPU. Examples are macros to insert more or less useful instructions into
|
||||
your C code, or a function to call arbitrary machine language subroutines,
|
||||
passing registers in and out.
|
||||
|
||||
|
||||
|
||||
<sect>Target specific stuff<p>
|
||||
|
||||
For each supported system there's a header file that contains calls or defines
|
||||
specific for this system. So, when programming for the C64, include c64.h, for
|
||||
the C128, include c128.h and so on. To make the task for the Commodore systems
|
||||
easier, there is also a header file named cbm.h that will define stuff common
|
||||
for all CBM systems, and include the header file for the specific target
|
||||
system.
|
||||
|
||||
The header files contain
|
||||
|
||||
<itemize>
|
||||
|
||||
<item>Defines for special keys (like function keys)
|
||||
|
||||
<item>Defines for special characters (like the graphics characters)
|
||||
|
||||
<item>Variables with a fixed address in memory that may be used to access
|
||||
special hardware. For the C64 and C128 there is a variable struct named
|
||||
<tt/SID/. Writing to the fields of this struct will write to the SID device
|
||||
instead. Using these variables will make your program more readable and more
|
||||
portable. Don't fear ineffective code when using these variables, the
|
||||
compiler will translate reads and writes to these structs into direct memory
|
||||
accesses.
|
||||
|
||||
<item>Other routines that make only sense for a specific system. One example
|
||||
are routines to write memory locations in the system bank for the CBM PET-II
|
||||
family.
|
||||
|
||||
</itemize>
|
||||
|
||||
|
||||
<sect>Direct console I/O - <tt/conio.h/<p>
|
||||
|
||||
The <tt/conio.h/ header file contains a large set of functions that do screen
|
||||
and keyboard I/O. The functions will write directly to the screen or poll the
|
||||
keyboard directly with no more help from the operating system than needed.
|
||||
This has some disadvantages, but on the other side it's fast and reasonably
|
||||
portable. conio implementations exist for the following targets:
|
||||
|
||||
<itemize>
|
||||
<item>apple2
|
||||
<item>apple2enh
|
||||
<item>atari
|
||||
<item>atarixl
|
||||
<item>atmos
|
||||
<item>c16 (works also for the c116 with up to 32K memory)
|
||||
<item>c64
|
||||
<item>c128
|
||||
<item>plus4 (or expanded c16/c116)
|
||||
<item>cbm510 (40 column video)
|
||||
<item>cbm610 (all CBM series-II computers with 80 column video)
|
||||
<item>geos-apple
|
||||
<item>geos-cbm
|
||||
<item>nes
|
||||
<item>pet (all CBM PET systems except the 2001)
|
||||
<item>vic20
|
||||
</itemize>
|
||||
|
||||
The conio.h header file does also include the system specific header files
|
||||
which define constants for special characters and keys.
|
||||
|
||||
|
||||
|
||||
<sect>Using the joystick - <tt/joystick.h/<p>
|
||||
|
||||
For systems that have a joystick, <tt/joystick.h/ will define a subroutine to
|
||||
read the current value, including constants to evaluate the result of this
|
||||
function.
|
||||
|
||||
|
||||
|
||||
<sect>Using a mouse - <tt/mouse.h/<p>
|
||||
|
||||
Some target machines support a mouse. Mouse support is currently available for
|
||||
the following targets:
|
||||
|
||||
<itemize>
|
||||
<item>apple2
|
||||
<item>apple2enh
|
||||
<item>atari
|
||||
<item>atarixl
|
||||
<item>c64
|
||||
<item>c128
|
||||
</itemize>
|
||||
|
||||
The available functions are declared in <tt/mouse.h/.
|
||||
|
||||
|
||||
<sect>Copyright<p>
|
||||
|
||||
This C runtime library implementation for the cc65 compiler is (C)
|
||||
Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries
|
||||
and/or sources the following conditions do apply:
|
||||
|
||||
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>
|
||||
|
||||
|
||||
|
||||
351
doc/lynx.sgml
Normal file
351
doc/lynx.sgml
Normal file
@ -0,0 +1,351 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Atari Lynx specific information for cc65
|
||||
<author>Karri Kaksonen, <htmlurl url="mailto:karri@sipo.fi" name="karri@sipo.fi">
|
||||
Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2011-04-01
|
||||
|
||||
<abstract>
|
||||
An overview over the Atari Lynx runtime system as it is implemented for the
|
||||
cc65 C compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the Atari Lynx runtime system as it comes
|
||||
with the cc65 C compiler. It describes the memory layout, Lynx specific header
|
||||
files, available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that Lynx specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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>Building your first Hello World application<p>
|
||||
|
||||
Here is a small traditional Hello World program for the Atari Lynx.
|
||||
|
||||
<tscreen><verb>
|
||||
#include <lynx.h>
|
||||
#include <tgi.h>
|
||||
#include <6502.h>
|
||||
|
||||
void main(void) {
|
||||
tgi_install(tgi_static_stddrv);
|
||||
tgi_init();
|
||||
CLI();
|
||||
while (tgi_busy())
|
||||
;
|
||||
tgi_clear();
|
||||
tgi_setcolor(COLOR_GREEN);
|
||||
tgi_outtextxy(0, 0, "Hello World");
|
||||
tgi_updatedisplay();
|
||||
while (1)
|
||||
;
|
||||
}
|
||||
</verb></tscreen>
|
||||
|
||||
The lynx.h contains all kind of system dependent things.
|
||||
|
||||
The tgi.h contains the graphics driver functions.
|
||||
|
||||
The 6502.h is needed for executing the CLI() command.
|
||||
|
||||
As the Atari Lynx does not have ASCII characters available you need to use
|
||||
the Tiny Graphics Interface library for producing letters on the screen.
|
||||
|
||||
The cc65 compiler suite has a graphics library called "Tiny Graphics
|
||||
Interface". This interface has some relocatable code. In order to use this
|
||||
in your own program you need to load it at run time.
|
||||
|
||||
Unfortunately the Lynx does not have a disk drive from where to load it.
|
||||
Therefore you must already load it at compile time. The easiest way is to
|
||||
automatically link it in statically from the Lynx C library.
|
||||
|
||||
<tscreen><verb>
|
||||
cl65 -t lynx -o game.lnx main.c
|
||||
</verb></tscreen>
|
||||
|
||||
This will create a bootable cart image called game.lnx
|
||||
|
||||
|
||||
<sect>Binary format<p>
|
||||
|
||||
The standard binary output format generated by the linker for the Lynx target
|
||||
is a cart image. By specifying the config file lynx-bll.cfg the linker will
|
||||
generate BLL download compatible binary files.
|
||||
|
||||
It is of course possible to change this behaviour by using a modified startup
|
||||
file and linker config.
|
||||
|
||||
The bootloader used in the cc65 lynx library uses a very minimal bootloader
|
||||
that does not check the cart or show a title screen.
|
||||
|
||||
The advantage of this bootloader is that it allows creation of cart images to
|
||||
many common formats.
|
||||
|
||||
Cart sizes
|
||||
<tscreen><verb>
|
||||
Block size Rom size Description
|
||||
512 bytes 128k Standard old games like Warbirds
|
||||
1024 bytes 256k Most common format for homebrew. Also newer games like Lemmings
|
||||
2048 bytes 512k Largest games like EOTB
|
||||
</verb></tscreen>
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs with the default setup run with the I/O area and the
|
||||
kernal enabled, which gives a usable memory range of $200 - $C037.
|
||||
|
||||
Special locations:
|
||||
<tscreen><verb>
|
||||
0000 - 00FF Zero page
|
||||
0100 - 01FF Machine stack
|
||||
|
||||
A058 - C037 Collision buffer
|
||||
C038 - E017 Screen buffer 1
|
||||
E018 - FFF7 Screen buffer 0
|
||||
FFF8 - FFFF Hardware vectors
|
||||
</verb></tscreen>
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
No conio support is currently available for the Lynx.
|
||||
|
||||
<tag/Keyboard/
|
||||
The Lynx "flabode" keys, Opt 1, Pause and Opt 2 are implemented using the
|
||||
conio interface. The only characters the keyboard is able to produce are
|
||||
'R' for Restart (Opt 1 + Pause), 'F' for flip (Opt 2 + Pause),
|
||||
'P' for pause, '1' for Opt 1, '2' for Opt 2, '3' for Opt 1 + Opt 2 and
|
||||
'?' for all keys down at the same time.
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $C037 (or $A057 if collision
|
||||
detection is enabled) and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
<tag/Screen/
|
||||
The collision detection screen is at $A058 if it is enabled. The
|
||||
double buffered screens are at $C038 and $E018.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing Lynx specific code may use the <tt/lynx.h/ header file.
|
||||
|
||||
|
||||
<sect1>Lynx specific functions<p>
|
||||
|
||||
<itemize>
|
||||
<item>lynx_eeprom_erase
|
||||
<item>lynx_eeprom_read
|
||||
<item>lynx_eeprom_write
|
||||
<item>lynx_eeread
|
||||
<item>lynx_eewrite
|
||||
<item>lynx_exec
|
||||
<item>lynx_load
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect1>Hardware access<p>
|
||||
|
||||
The following pseudo variables declared in the <tt/lynx.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/MIKEY/</tag>
|
||||
The <tt/MIKEY/ structure allows access to MIKEY chip. See the <tt/_mikey.h/
|
||||
header file located in the include directory for the declaration of the
|
||||
structure.
|
||||
|
||||
<tag><tt/SUZY/</tag>
|
||||
The <tt/SUZY/ structure allows access to SUZY chip. See the <tt/_suzy.h/
|
||||
header file located in the include directory for the declaration of the
|
||||
structure.
|
||||
|
||||
</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>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/lynx-160-102-16.tgi (lynx_160_102_16_tgi)/</tag>
|
||||
A TGI driver for the standard graphics mode (160×102 in 16 colors).
|
||||
|
||||
The TGI driver is implemented as an interrupt driven dual buffering device.
|
||||
To use it as a single-buffer device set draw page and view page to the same
|
||||
value 0 or 1;
|
||||
|
||||
The TGI driver has a few Lynx-specific extensions.
|
||||
|
||||
Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx
|
||||
sprite on screen.
|
||||
|
||||
Calling tgi_flip() or tgi_ioctl(1, 0) will do a flip screen.
|
||||
|
||||
Calling tgi_setbgcolor(bgcolor) or tgi_ioctl(2, bgindex) will set the text
|
||||
background color to the index defined by bgindex. If bgindex is 0 then the
|
||||
background color is transparent.
|
||||
|
||||
To set the framerate of the display hardware call tgi_setframerate(rate) or
|
||||
tgi_ioctl(3, rate). The supported framerates are 50, 60 and 75 frames per
|
||||
second. Actually there is no real reason to use anything else than 75 frames
|
||||
per second.
|
||||
|
||||
To check if the drawing engine is busy with the previous swap you can
|
||||
call tgi_busy or tgi_ioctl(4, 0). It returns 0 if idle and 1 if busy
|
||||
|
||||
To update displays you can call tgi_updatedisplay() or tgi_ioctl(4, 1) it
|
||||
will wait for the next VBL interrupt and set the draw buffer to the
|
||||
view buffer. The draw buffer is also changed to (drawbuffer xor 1).
|
||||
|
||||
You can also enable or disable collision detection by a call to
|
||||
tgi_setcollisiondetection(active) or tgi_ioctl(5, active). The collision
|
||||
result is located before the sprite structure by default in this driver.
|
||||
|
||||
In order to reserve memory for the collision detection buffer you need to
|
||||
specify lynx-coll.cfg as the configuration file to the linker.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
No extended memory drivers are currently available for the Lynx.
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/lynx-stdjoy.joy (lynx_stdjoy_joy)/</tag>
|
||||
A joystick driver for the standard buttons.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the Lynx.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/lynx-comlynx.ser (lynx_comlynx_ser)/</tag>
|
||||
A serial driver for the ComLynx port.
|
||||
|
||||
The ComLynx port has Tx and Rx wired together. Every byte is sent
|
||||
to all connected Lynxes. Only one Lynx can send at a time. There is no
|
||||
protocol created for communication. You are on your own.
|
||||
|
||||
If the Lynx returns framing error then it is likely that another Lynx is
|
||||
sending data at the same time.
|
||||
|
||||
The Lynx can also send a break and receive a break. The Lynx break is
|
||||
recognized if the bit is down for 24 bit cycles or more.
|
||||
|
||||
To send a break you just set the break bit. The length of the break depends
|
||||
on how long this bit is down.
|
||||
|
||||
The driver supports the baudrates:
|
||||
<itemize>
|
||||
<item>62500
|
||||
<item>31250
|
||||
<item>9600
|
||||
<item>7200
|
||||
<item>4800
|
||||
<item>3600
|
||||
<item>2400
|
||||
<item>1800
|
||||
<item>1200
|
||||
<item>600
|
||||
<item>300
|
||||
<item>150
|
||||
<item>134.5
|
||||
<item>110
|
||||
<item>75
|
||||
</itemize>
|
||||
The parity bit supports MARK and SPACE. It also supports EVEN and ODD parity
|
||||
but the parity bit is included in the calculation. Most of us don't want it
|
||||
this way. But there is nothing we can do about it.
|
||||
|
||||
The Lynx hardware will always check parity on incoming traffic. Currently
|
||||
the driver cannot receive data from standard PC's due to this parity bug.
|
||||
For working with Lynx to Lynx communication use EVEN parity.
|
||||
|
||||
To send data to standard PC's use MARK or SPACE as parity setting.
|
||||
|
||||
There is always only one stop bit. And the data length is always 8 bits.
|
||||
|
||||
We have no handshaking available. Even software handshake is impossible
|
||||
as ComLynx has only one wire for the data.
|
||||
|
||||
Both transmit and receive are interrupt driven.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
|
||||
<sect>Cart access<p>
|
||||
|
||||
At this point in time there is no support for the cart filesystem yet. I have
|
||||
a <tt/lynx-cart-demo/ example project that uses an interrupt driven display,
|
||||
has support for the cart filesystem and an abcmusic sound module.
|
||||
|
||||
At some point in time we may find a way to rewrite these to fit the way the
|
||||
cc65 drivers require. But for the time being you can create less portable
|
||||
applications using these Lynx specific modules in <tt/lynx-cart-demo/.
|
||||
|
||||
|
||||
<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>
|
||||
188
doc/nes.sgml
Normal file
188
doc/nes.sgml
Normal file
@ -0,0 +1,188 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Nintendo Entertainment System specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
|
||||
<date>2005-07-17
|
||||
|
||||
<abstract>
|
||||
An overview over the NES runtime system as it is implemented for the
|
||||
cc65 C compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the NES runtime system as it comes
|
||||
with the cc65 C compiler. It describes the memory layout, NES specific header
|
||||
files, available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that NES specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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 NES target
|
||||
is a machine language program with an INES cartridge header. It is of course
|
||||
possible to change this behaviour by using a modified startup file and linker
|
||||
config.
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs with the default setup run with the I/O area and a
|
||||
CHR bank enabled, which gives a usable memory range of $8000 - $FFF3.
|
||||
All boot ROM entry points may be called directly without additional code.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen is located at VRAM $2000.
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $7FFF and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing NES specific code may use the <tt/nes.h/ header file.
|
||||
|
||||
|
||||
<sect1>NES specific functions<p>
|
||||
|
||||
<itemize>
|
||||
<item>waitvblank
|
||||
<item>get_tv
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect1>Hardware access<p>
|
||||
|
||||
The following pseudo variables declared in the <tt/nes.inc/ include file do
|
||||
allow access to hardware located in the address space.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/PPU/</tag>
|
||||
The <tt/PPU/ defines allow access to the PPU chip.
|
||||
|
||||
<tag><tt/APU/</tag>
|
||||
The <tt/APU/ defines allow access to the APU chip.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Loadable drivers<p>
|
||||
|
||||
All drivers must be statically linked because no file I/O is available.
|
||||
The names in the parentheses denote the symbols to be used for static linking of the drivers.
|
||||
|
||||
|
||||
<sect1>Graphics drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/nes-64-56-2.tgi (nes_64_56_2)/</tag>
|
||||
This driver features a resolution of 64×56 with 2 colors using the
|
||||
CHR bank.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
No extended memory drivers are currently available for the NES.
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/nes-stdjoy.joy (nes_stdjoy)/</tag>
|
||||
A joystick driver for the standard four buttons joypad is available.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the NES.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
No serial drivers are currently available for the NES.
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
<sect1>Disk I/O<p>
|
||||
|
||||
The existing library for the NES doesn't implement C file
|
||||
I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines.
|
||||
|
||||
To be more concrete, this limitation means that you cannot use any of the
|
||||
following functions (and a few others):
|
||||
|
||||
<itemize>
|
||||
<item>fclose
|
||||
<item>fopen
|
||||
<item>fread
|
||||
<item>fprintf
|
||||
<item>fputc
|
||||
<item>fscanf
|
||||
<item>fwrite
|
||||
<item>...
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
215
doc/od65.sgml
Normal file
215
doc/od65.sgml
Normal file
@ -0,0 +1,215 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>od65 Users Guide
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2010-07-30
|
||||
|
||||
<abstract>
|
||||
od65 is the object file dump utility. It is able to output most parts of
|
||||
<htmlurl url="ca65.html" name="ca65"> generated object files in readable form.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
od65 is an object file dump utility. It is able to output most parts of
|
||||
<htmlurl url="ca65.html" name="ca65"> generated object files in readable form.
|
||||
Since the contents and format of the object files are not documented
|
||||
elsewhere and may change at any time, this tool is a portable way to look at
|
||||
the contents.
|
||||
|
||||
Apart from curiosity, most people don't need to use this tool.
|
||||
|
||||
|
||||
|
||||
<sect>Usage<p>
|
||||
|
||||
The od65 utility dumps contents of one or more ca65 generated object file to
|
||||
standard output. It has no cross-version compatibility, so you have to use
|
||||
a version that matches the version of ca65 used to create the object files.
|
||||
|
||||
|
||||
<sect1>Command line option overview<p>
|
||||
|
||||
The program may be called as follows:
|
||||
|
||||
<tscreen><verb>
|
||||
---------------------------------------------------------------------------
|
||||
Usage: od65 [options] file [options] [file]
|
||||
Short options:
|
||||
-h Help (this text)
|
||||
-H Dump the object file header
|
||||
-S Dump segments sizes
|
||||
-V Print the version number and exit
|
||||
|
||||
Long options:
|
||||
--dump-all Dump all object file information
|
||||
--dump-dbgsyms Dump debug symbols
|
||||
--dump-exports Dump exported symbols
|
||||
--dump-files Dump the source files
|
||||
--dump-header Dump the object file header
|
||||
--dump-imports Dump imported symbols
|
||||
--dump-lineinfo Dump line information
|
||||
--dump-options Dump object file options
|
||||
--dump-segments Dump the segments in the file
|
||||
--dump-segsize Dump segments sizes
|
||||
--help Help (this text)
|
||||
--version Print the version number and exit
|
||||
---------------------------------------------------------------------------
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<sect1>Command line options in detail<label id="cmdline-opt-detail"><p>
|
||||
|
||||
Here is a description of all the command line options:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt>--dump-all</tt></tag>
|
||||
|
||||
This will output all information, od65 is able to process. The option is a
|
||||
shortcut for specifying all the other <tt/--dump/ options.
|
||||
|
||||
|
||||
<tag><tt>--dump-dbgsyms</tt></tag>
|
||||
|
||||
Dump all debug symbols contained in the object file.
|
||||
|
||||
|
||||
<tag><tt>--dump-exports</tt></tag>
|
||||
|
||||
Dump all exported symbols contained in the object file.
|
||||
|
||||
|
||||
<tag><tt>--dump-files</tt></tag>
|
||||
|
||||
Dump the file table contained in the object file.
|
||||
|
||||
|
||||
<tag><tt>-H, --dump-header</tt></tag>
|
||||
|
||||
Dump the object file header.
|
||||
|
||||
|
||||
<tag><tt>--dump-imports</tt></tag>
|
||||
|
||||
Dump the list of imported symbols contained in the object file.
|
||||
|
||||
|
||||
<tag><tt>--dump-lineinfo</tt></tag>
|
||||
|
||||
Dump the line info contained in the object file.
|
||||
|
||||
|
||||
<tag><tt>--dump-segments</tt></tag>
|
||||
|
||||
Dump the list of segments contained in the object file.
|
||||
|
||||
|
||||
<tag><tt>--dump-scopes</tt></tag>
|
||||
|
||||
Dump the scope (lexical level) information contained in the object file.
|
||||
|
||||
|
||||
<tag><tt>-S, --dump-segsize</tt></tag>
|
||||
|
||||
Dump the sizes of all segments contained in the object file. This option is
|
||||
quite useful to determine the effect of measures that increase or decrease
|
||||
code size.
|
||||
|
||||
|
||||
<tag><tt>-h, --help</tt></tag>
|
||||
|
||||
Print the short option summary shown above.
|
||||
|
||||
|
||||
<tag><tt>-V, --version</tt></tag>
|
||||
|
||||
Print the version number of the compiler. When submitting a bug report,
|
||||
please include the operating system you're using, and the compiler
|
||||
version.
|
||||
</descrip>
|
||||
|
||||
|
||||
<sect>Input and output<p>
|
||||
|
||||
The converter will read one or more object files per invocation and write the
|
||||
contents in readable format to standard output. Please note that you need to
|
||||
specify any of the <tt/--dump/ options listed <ref id="cmdline-opt-detail"
|
||||
name="above">, otherwise no useful output will be generated.
|
||||
|
||||
Example output for the command
|
||||
<tscreen><verb>
|
||||
od65 --dump-header --dump-files t.o
|
||||
</verb></tscreen>
|
||||
<tscreen><verb>
|
||||
t.o:
|
||||
Header:
|
||||
Magic: 0x616E7A55
|
||||
Version: 12
|
||||
Flags: 0x0001 (OBJ_FLAGS_DBGINFO)
|
||||
Options:
|
||||
Offset: 88
|
||||
Size: 9
|
||||
Files:
|
||||
Offset: 97
|
||||
Size: 10
|
||||
Segments:
|
||||
Offset: 107
|
||||
Size: 101
|
||||
Imports:
|
||||
Offset: 208
|
||||
Size: 1
|
||||
Exports:
|
||||
Offset: 209
|
||||
Size: 1
|
||||
Debug symbols:
|
||||
Offset: 210
|
||||
Size: 55
|
||||
Line infos:
|
||||
Offset: 265
|
||||
Size: 1
|
||||
String pool:
|
||||
Offset: 266
|
||||
Size: 80
|
||||
Files:
|
||||
Count: 1
|
||||
Index: 0
|
||||
Name: "t.s"
|
||||
Size: 402
|
||||
Modification time: 1280498435 (Fri Jul 30 16:00:35 2010)
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<sect>Copyright<p>
|
||||
|
||||
od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the
|
||||
binaries and/or sources the following conditions apply:
|
||||
|
||||
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>
|
||||
|
||||
252
doc/pet.sgml
Normal file
252
doc/pet.sgml
Normal file
@ -0,0 +1,252 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Commodore PET specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
|
||||
<date>2005-05-24
|
||||
|
||||
<abstract>
|
||||
An overview over the PET runtime system as it is implemented for the cc65 C
|
||||
compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the PET runtime system as it comes with the
|
||||
cc65 C compiler. It describes the memory layout, PET specific header files,
|
||||
available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that PET specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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 PET target
|
||||
is a machine language program with a one line BASIC stub, which calls the
|
||||
machine language part via SYS. This means that a program can be loaded as
|
||||
BASIC program and started with RUN. It is of course possible to change this
|
||||
behaviour by using a modified startup file and linker config.
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs with the default setup run with the I/O area and the
|
||||
kernal and BASIC ROM enabled, which gives a usable memory range of
|
||||
$0400 - $7FFF (32KB machine).
|
||||
All ROM entry points may be called directly without additional code.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen is located at $8000.
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $7FFF and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing PET specific code may use the <tt/pet.h/ or <tt/cbm.h/
|
||||
header files. Using the later may be an option when writing code for more than
|
||||
one CBM platform, since it includes <tt/pet.h/ and declares several functions
|
||||
common to all CBM platforms.
|
||||
|
||||
|
||||
<sect1>PET specific functions<p>
|
||||
|
||||
There are currently no special PET functions.
|
||||
|
||||
|
||||
|
||||
<sect1>CBM specific functions<p>
|
||||
|
||||
Some functions are available for all (or at least most) of the Commodore
|
||||
machines. See the <htmlurl url="funcref.html" name="function reference"> for
|
||||
declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>cbm_close
|
||||
<item>cbm_closedir
|
||||
<item>cbm_k_setlfs
|
||||
<item>cbm_k_setnam
|
||||
<item>cbm_k_load
|
||||
<item>cbm_k_save
|
||||
<item>cbm_k_open
|
||||
<item>cbm_k_close
|
||||
<item>cbm_k_readst
|
||||
<item>cbm_k_chkin
|
||||
<item>cbm_k_ckout
|
||||
<item>cbm_k_basin
|
||||
<item>cbm_k_bsout
|
||||
<item>cbm_k_clrch
|
||||
<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/pet.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/PIA1, PIA2/</tag>
|
||||
Access to the two PIA (peripheral interface adapter) chips is available via
|
||||
the <tt/PIA1/ and <tt/PIA2/ variables. The structure behind these variables
|
||||
is explained in <tt/_pia.h/.
|
||||
|
||||
<tag><tt/VIA/</tag>
|
||||
The <tt/VIA/ structure allows access to the VIA (versatile interface
|
||||
adapter). See the <tt/_6522.h/ header file located in the include
|
||||
directory for the declaration of the structure.
|
||||
|
||||
</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 currently available for the PET.
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
No extended memory drivers are currently available for the PET.
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/pet-ptvjoy.joy (pet_ptvjoy_joy)/</tag>
|
||||
Driver for the Protovision 4-player adapter contributed by Groepaz. See
|
||||
<htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
|
||||
name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
|
||||
building instructions. Up to two joysticks are supported.
|
||||
|
||||
<tag><tt/pet-stdjoy.joy (pet_stdjoy_joy)/</tag>
|
||||
Driver for the standard PET userport joystick.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the PET.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
No serial drivers are currently available for the PET.
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/. Since this is not
|
||||
supported 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 runtime for the PET 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
|
||||
when they are linked into a program. See the discussion of the <tt/.CONDES/
|
||||
feature in the <htmlurl url="ca65.html" name="assembler manual">.
|
||||
|
||||
|
||||
<sect1>Using extended memory<p>
|
||||
|
||||
The extended memory at $9000 of the CBM 8x96 may be added to the heap by using
|
||||
the following code:
|
||||
|
||||
<tscreen><verb>
|
||||
/* Check for the existence of RAM */
|
||||
if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) {
|
||||
/* Add it to the heap */
|
||||
_heapadd ((void *) 0x9000, 0x2000);
|
||||
}
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<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>
|
||||
260
doc/plus4.sgml
Normal file
260
doc/plus4.sgml
Normal file
@ -0,0 +1,260 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Commodore Plus/4 specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2003-12-14
|
||||
|
||||
<abstract>
|
||||
An overview over the Plus/4 runtime system as it is implemented for the cc65 C
|
||||
compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the Plus/4 runtime system as it comes with the
|
||||
cc65 C compiler. It describes the memory layout, Plus/4 specific header files,
|
||||
available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that Plus/4 specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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.
|
||||
|
||||
Since the Plus/4 and the Commodore 16/116 are almost identical (the latter are
|
||||
missing the 6551 ACIA and do only have 16KB of memory), the <htmlurl
|
||||
url="c16.html" name="C16 documentation"> is also worth a look. The difference
|
||||
between both cc65 targets is that the Plus/4 runtime uses banking to support
|
||||
full 64K RAM, while the C16 does not use banking and supports up to 32K RAM.
|
||||
Because banking is not needed, most C16 programs will be somewhat smaller than
|
||||
the same program compiled for the Plus/4. However, programs compiled for the
|
||||
C16 will always run on the Plus/4, while the reverse is not necessarily true.
|
||||
|
||||
|
||||
<sect>Binary format<p>
|
||||
|
||||
The standard binary output format generated by the linker for the Plus/4
|
||||
target is a machine language program with a one line BASIC stub, which calls
|
||||
the machine language part via SYS. This means that a program can be loaded as
|
||||
BASIC program and started with RUN. It is of course possible to change this
|
||||
behaviour by using a modified startup file and linker config.
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs with the default setup run with the kernal and basic
|
||||
banked out. This gives a usable memory range of $1000 - $FD00.
|
||||
Having the kernal and basic ROMs banked out means, that no ROM entry points
|
||||
may be called directly from user code.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen is located at $C00 (as in the standard setup).
|
||||
|
||||
<tag/Color RAM/
|
||||
The color RAM is located at $800 (standard location).
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $FCFF and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing Plus/4 specific code may use the <tt/plus4.h/ or <tt/cbm.h/
|
||||
header files. Using the later may be an option when writing code for more than
|
||||
one CBM platform, since it includes <tt/plus4.h/ and declares several functions
|
||||
common to all CBM platforms.
|
||||
|
||||
Please note that most of the header file declarations from the <tt/plus4.h/
|
||||
header file are shared between the C16 and Plus/4 configurations. For this
|
||||
reason, most of it is located in a common header file named <tt/cbm264.h/.
|
||||
|
||||
|
||||
|
||||
<sect1>Plus/4 specific functions<p>
|
||||
|
||||
There are currently no special Plus/4 functions.
|
||||
|
||||
|
||||
<sect1>CBM specific functions<p>
|
||||
|
||||
Some functions are available for all (or at least most) of the Commodore
|
||||
machines. See the <htmlurl url="funcref.html" name="function reference"> for
|
||||
declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>cbm_close
|
||||
<item>cbm_closedir
|
||||
<item>cbm_k_setlfs
|
||||
<item>cbm_k_setnam
|
||||
<item>cbm_k_load
|
||||
<item>cbm_k_save
|
||||
<item>cbm_k_open
|
||||
<item>cbm_k_close
|
||||
<item>cbm_k_readst
|
||||
<item>cbm_k_chkin
|
||||
<item>cbm_k_ckout
|
||||
<item>cbm_k_basin
|
||||
<item>cbm_k_bsout
|
||||
<item>cbm_k_clrch
|
||||
<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/plus4.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/TED/</tag>
|
||||
The <tt/TED/ structure allows access to the TED chip. See the
|
||||
<tt/_ted.h/ header file located in the include directory for the
|
||||
declaration of the structure.
|
||||
|
||||
<tag><tt/COLOR_RAM/</tag>
|
||||
A character array that mirrors the color RAM of the Plus/4 at $0800.
|
||||
|
||||
</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 currently available for the Plus/4.
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
No extended memory drivers are currently available for the Plus/4.
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/plus4-stdjoy.joy (plus4_stdjoy_joy)/</tag>
|
||||
Supports up to two joysticks connected to the standard joysticks port of
|
||||
the Plus/4.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the Plus/4.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/plus4-stdser.ser (plus4_stdser_ser)/</tag>
|
||||
Driver for the 6551 ACIA chip built into the Plus/4. Supports up to 19200
|
||||
baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note
|
||||
that because of the peculiarities of the 6551 chip transmits are not
|
||||
interrupt driven, and the transceiver blocks if the receiver asserts flow
|
||||
control because of a full buffer.
|
||||
|
||||
You need an adapter to use the builtin port, since the output levels
|
||||
available at the user port don't follow the RS232 standard.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/. Since this is not
|
||||
supported 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 runtime for the Plus/4 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
|
||||
when they are linked into a program. See the discussion of the <tt/.CONDES/
|
||||
feature in the <htmlurl 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>
|
||||
596
doc/smc.sgml
Normal file
596
doc/smc.sgml
Normal file
@ -0,0 +1,596 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>ca65 Macros for Self Modifying Code
|
||||
<author>Christian Krüger
|
||||
<date>2012-02-19
|
||||
|
||||
<abstract>
|
||||
The 'smc.inc' macro package for ca65 eases the use, increases the safeness and
|
||||
self-explanation of 'self-modifying-code' (SMC).
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
When reading assembler sources, self modifying code is often hard to identify
|
||||
and applying it needs a lot of discipline.
|
||||
|
||||
Since the cacheless 6502 is a thankful target of such kind of code, the macro
|
||||
package will not only reduce this complexness, but also document the use. The
|
||||
resulting source is more self-explanatory and so easier to maintain.
|
||||
|
||||
While for general purposes SMC is not a desired form for implementations, it
|
||||
can be quite useful for a small range of scenarios. Normally SMC will be
|
||||
introduced when optimizing code in respect to:
|
||||
|
||||
<itemize>
|
||||
<item>speed and/or
|
||||
<item>size.
|
||||
</itemize>
|
||||
|
||||
Please mind that SMC can only be applied for code in RAM, which means that a
|
||||
general purpose library with SMC excludes ROM targets!
|
||||
|
||||
The ca65 SMC macro package consists of two files:
|
||||
|
||||
<itemize>
|
||||
<item><tt>smc.inc</tt>
|
||||
<item><tt>opcodes.inc</tt>
|
||||
</itemize>
|
||||
|
||||
The latter is only needed if you also plan to modify opcodes and not only data
|
||||
within your code.
|
||||
|
||||
<sect>Usage<p>
|
||||
The use of the macros is quite simple:
|
||||
|
||||
Original:
|
||||
|
||||
<tscreen><verb>
|
||||
PHA
|
||||
JSR SUBROUTINE
|
||||
PLA
|
||||
</verb></tscreen>
|
||||
|
||||
By applying SMC, the speed will now be increased by once cycle:
|
||||
|
||||
SMC:
|
||||
|
||||
<tscreen><verb>
|
||||
SMC_StoreValue RestoreAccu
|
||||
JSR SUBROUTINE
|
||||
SMC RestoreAccu, { LDA #SMC_Value }
|
||||
</verb></tscreen>
|
||||
|
||||
The first line stores the value of the accu into the '<tt>RestoreAccu</tt>'
|
||||
labeled SMC target.
|
||||
|
||||
Please note:
|
||||
<enum>
|
||||
<item> for all SMC store or transfer operations, a second argument can be
|
||||
given. This determines the register for the operation:
|
||||
'<tt>SMC_StoreValue Label, y</tt>' will store the value of the
|
||||
Y-register.
|
||||
|
||||
If the second argument is missing, the accu will be used automatically.
|
||||
|
||||
<item> The label targets a 'special SMC namespace'. It fits only to
|
||||
destinations which are introduced with the macro '<tt>SMC</tt>'. A
|
||||
normal label '<tt>RestoreAccu</tt>' wouldn't match and could even
|
||||
coexist (even if you should abstain from doing so).
|
||||
|
||||
<item> The macro '<tt>SMC_StoreValue</tt>' takes care, that the store
|
||||
operation will occur on the value-position of a SMC-instruction. As
|
||||
you will see, other macros influence other instruction part positions.
|
||||
There is no consistency check, if the targeted SMC instruction acually
|
||||
contains a value. Storing a 'value' on an immplied SMC instruction
|
||||
would corrupt the following memory cell!
|
||||
</enum>
|
||||
|
||||
The second line needs no further explanation, this is just a placeholder for
|
||||
some code in the example.
|
||||
|
||||
The third line is the code line which is about to be modified. It has to start
|
||||
with the '<tt>SMC</tt>' macro and must be labeled, so that the modification
|
||||
can be designated. Then the unmodified code is given in curly braces.
|
||||
|
||||
Please note the usage of the value placeholder 'SMC_Value'. Using such a
|
||||
placeholder has two advantages:
|
||||
|
||||
<enum>
|
||||
<item> The code is better documented. It is clearly visible that the given
|
||||
value is about to be changed.
|
||||
<item> When examining an (initial) disassembly (e.g. in a debugger), these
|
||||
placegolders can be better identified: They are fixed and, you may
|
||||
notice that below, quite eye catching defined.
|
||||
</enum>
|
||||
|
||||
<sect1>Argument placeholders<p>
|
||||
|
||||
There are four kinds of placeholders:
|
||||
|
||||
<descrip>
|
||||
|
||||
<label id="Address placeholder">
|
||||
<tag><tt>SMC_AbsAdr</tt></tag>
|
||||
|
||||
Used to indicate an address. The value is '<tt>$FADE</tt>'.
|
||||
|
||||
Example: <tt>STA SMC_AbsAdr</tt>
|
||||
|
||||
|
||||
<label id="Zero-Page-Address placeholder">
|
||||
<tag><tt>SMC_ZpAdr</tt></tag>
|
||||
|
||||
Used to indicate a zero-page-address. The value is '<tt>$00</tt>'.
|
||||
|
||||
Example: <tt>LDA SMC_ZpAdr</tt>
|
||||
|
||||
|
||||
<label id="Opcode placeholder">
|
||||
<tag><tt>SMC_Opcode</tt></tag>
|
||||
|
||||
Used to indicate an instruction. The value is '<tt>NOP</tt>'.
|
||||
|
||||
Example: <tt>SMC_Opcode</tt>
|
||||
|
||||
|
||||
<label id="Immediate value placeholder">
|
||||
<tag><tt>SMC_Value</tt></tag>
|
||||
|
||||
Used to indicate a value. The value is '<tt>$42</tt>'.
|
||||
|
||||
Example: <tt>LDX #SMC_Value</tt>
|
||||
</descrip>
|
||||
|
||||
Attention: Often code is modified after the initial use - where using the
|
||||
placeholders does not makes sense. Please mind also, that in very variable
|
||||
expressions (e.g. opcode and argument is about to be changed), placeholders
|
||||
can lead to unidentifyable code for a debugger/disassembler:
|
||||
|
||||
<tt>SMC Example, { SMC_Opcode SMC_AbsAdr } </tt>
|
||||
|
||||
Since the opcode is '<tt/NOP/', the value '<tt/$DE/' from '<tt/$FADE/' will
|
||||
interpreted as opcode in a disassembler too. This breaks the correct
|
||||
disassembly, because '<tt/$DE/' is interpreted as '<tt/DEC abx/'. Establishing
|
||||
a valid placeholder instruction may be better:
|
||||
|
||||
<tt>SMC Example, { sta SMC_AbsAdr } ; Note: Opcode will be modified too!</tt>
|
||||
|
||||
<sect1>Accessing opcodes<p>
|
||||
|
||||
Some macros are designed to access the instruction of a code line. To increase
|
||||
readability, please use the opcodes as defined in the '<tt>opcodes.inc</tt>'
|
||||
file.
|
||||
|
||||
<descrip>
|
||||
|
||||
<label id="Transfer opcode">
|
||||
<tag><tt>SMC_TransferOpcode label, opcode (, register)</tt></tag>
|
||||
Loads and store an opcode to given SMC instruction.
|
||||
|
||||
Example:
|
||||
|
||||
<tscreen><verb>
|
||||
SMC SumRegister, { LDA #10 }
|
||||
JSR OUTPUT
|
||||
SMC_TransferOpcode SumRegister, OPC_ADC_imm, x
|
||||
</verb></tscreen>
|
||||
|
||||
The macro above will load the opcode '<tt>ADC #</tt>' into the x - register
|
||||
and stores it at the place of the '<tt>LDA #</tt>'.
|
||||
|
||||
<label id="Load opcode">
|
||||
<tag><tt>SMC_LoadOpcode label (, register)</tt></tag>
|
||||
Loads the opcode of a SMC line to the given register.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
SMC ShiftOrNothing, { LSL }
|
||||
SMC_LoadOpcode ShiftOrNothing, y
|
||||
CPY #OPC_NOP
|
||||
BEQ Exit
|
||||
</verb></tscreen>
|
||||
|
||||
<label id="Store opcode">
|
||||
<tag><tt>SMC_StoreOpcode label (, register)</tt></tag>
|
||||
Stores the value of the given register at the opcode place of a SMC line.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
SetBoldMode:
|
||||
LDA #OPC_INX
|
||||
SMC_StoreOpcode AdaptCharWidth
|
||||
SMC_StoreOpcode AdaptUnderlineWidth
|
||||
RTS
|
||||
...
|
||||
SMC AdaptCharWidth, { NOP }
|
||||
...
|
||||
SMC AdaptUnderlineWidth, { NOP }
|
||||
</verb></tscreen>
|
||||
|
||||
</descrip>
|
||||
|
||||
<sect1>Accessing arguments<p>
|
||||
|
||||
These marcos are determined to get, set and change arguments of instructions:
|
||||
|
||||
<descrip>
|
||||
|
||||
<label id="Change branch">
|
||||
<tag><tt>SMC_ChangeBranch label, destination (, register)</tt></tag>
|
||||
|
||||
Used to modify the destination of a branch instruction. If the adress offset
|
||||
exceeds the supported range of 8-bit of the 6502, a error will be thrown.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
Disable Handler:
|
||||
SMC_ChangeBranch BranchToHandler, Exit
|
||||
RTS
|
||||
...
|
||||
LDA warning
|
||||
SMC BranchToHandler, { BNE Handler }
|
||||
Exit:
|
||||
RTS
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Transfer value">
|
||||
<tag><tt>SMC_TransferValue label, value (, register)</tt></tag>
|
||||
|
||||
Changes the value of a SMC line.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
ClearDefault:
|
||||
SMC_TransferValue LoadDefault, 0
|
||||
RTS
|
||||
...
|
||||
SMC LoadDefault, { LDX #25 }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Load value">
|
||||
<tag><tt>SMC_LoadValue label (, register)</tt></tag>
|
||||
|
||||
Retreives the value of a SMC line.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
ShowDefault:
|
||||
SMC_LoadValue LoadDefault
|
||||
JSR PrintValue
|
||||
RTS
|
||||
...
|
||||
SMC LoadDefault, { LDX #25 }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Store value">
|
||||
<tag><tt>SMC_StoreValue label (, register)</tt></tag>
|
||||
|
||||
Stores the value in the register to given SMC line.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
InitCounters:
|
||||
LDY #0
|
||||
SMC_StoreValue GetI, y
|
||||
SMC_StoreValue GetJ, y
|
||||
SMC_StoreValue GetK, y
|
||||
...
|
||||
SMC GetI, { LDX #SMC_Value }
|
||||
...
|
||||
SMC GetJ, { LDX #SMC_Value }
|
||||
...
|
||||
SMC GetK, { LDX #SMC_Value }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Transfer low-byte">
|
||||
<tag><tt>SMC_TransferLowByte label, value (, register)</tt></tag>
|
||||
|
||||
Does the same as '<tt>SMC_TransferValue</tt>' but should be used for
|
||||
low-bytes of adresses for better readability.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
ActivateSecondDataSet:
|
||||
SMC_TransferLowByte LoadData, $40
|
||||
RTS
|
||||
...
|
||||
SMC LoadData, { LDA $2000 }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Load low-byte">
|
||||
<tag><tt>SMC_LoadLowByte label (, register)</tt></tag>
|
||||
|
||||
Does the same as '<tt>SMC_LoadValue</tt>' but should be used for low-bytes
|
||||
of adresses for better readability.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
IsSecondDataSetActive:
|
||||
SMC_LoadLowByte LoadData, y
|
||||
CPY #$40
|
||||
BNE NotActive
|
||||
...
|
||||
SMC LoadData, { LDA $2000 }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Store low-byte">
|
||||
<tag><tt>SMC_StoreLowByte label (, register)</tt></tag>
|
||||
|
||||
Does the same as '<tt>SMC_StoreValue</tt>' but should be used for low-bytes
|
||||
of adresses for better readability.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
InitStructureBaseAddresses:
|
||||
LDX #0
|
||||
SMC_StoreLowByte GetPlayerGraphic, x
|
||||
SMC_StoreLowByte GetObjectGraphic, x
|
||||
SMC_StoreLowByte StoreCollisionData, x
|
||||
RTS
|
||||
...
|
||||
SMC GetPlayerGraphic, { LDX $2000 }
|
||||
...
|
||||
SMC GetObjectGraphic, { LDA $2100,x }
|
||||
...
|
||||
SMC StoreCollisionData, { STY $2200 }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Transfer high-byte">
|
||||
<tag><tt>SMC_TransferHighByte label, value (, register)</tt></tag>
|
||||
|
||||
Loads and stores the given value via the named register to the high-byte
|
||||
adress portion of an SMC-instruction.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
PlaySFX:
|
||||
SMC GetVolume { LDA $3200,x }
|
||||
STA SoundOut
|
||||
INX
|
||||
BNE PlaySFX
|
||||
...
|
||||
PlayOtherSound:
|
||||
SMC_TransferHighByte GetVolume, $34
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Load high-byte">
|
||||
<tag><tt>SMC_LoadHighByte label (, register)</tt></tag>
|
||||
|
||||
Loads the high-byte part of an SMC-instruction adress to the given register.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
PlaySFX:
|
||||
SMC GetVolume { LDA $3200,x }
|
||||
...
|
||||
SMC_LoadHighByte GetVolume
|
||||
cmp #$34
|
||||
beq OtherSoundPlaying
|
||||
...
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Store high-byte">
|
||||
<tag><tt>SMC_StoreHighByte label (, register)</tt></tag>
|
||||
|
||||
Stores the high-byte adress part of an SMC-instruction from the given
|
||||
register.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
SetupLevel2:
|
||||
LDX #(>Level2Base)
|
||||
SMC_StoreHighByte GetLevelData, x
|
||||
SMC_StoreHighByte GetScreenData, x
|
||||
SMC_StoreHighByte GetSoundData, x
|
||||
RTS
|
||||
...
|
||||
SMC GetLevelData, { LDA Level1Base+Data }
|
||||
...
|
||||
SMC GetScreenData, { LDA Level1Base+Screen, x }
|
||||
...
|
||||
SMC GetSoundData, { LDA Level1Base+Sound, y }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Transfer single adress">
|
||||
<tag><tt>SMC_TransferAddressSingle label, address (, register)</tt></tag>
|
||||
|
||||
Transfers the contents of the given address via the given register to the
|
||||
designated SMC instruction.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
PrintHello:
|
||||
SMC_TransferAddressSingle GetChar, #HelloMsg
|
||||
...
|
||||
LDX #0
|
||||
NextChar:
|
||||
SMC GetChar, { LDA SMC_AbsAdr, x }
|
||||
BEQ leave
|
||||
JSR CharOut
|
||||
INX
|
||||
BNE NextChar
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Transfer adress">
|
||||
<tag><tt>SMC_TransferAddress label, address</tt></tag>
|
||||
|
||||
Loads contents of given address to A/X and stores the result to SMC
|
||||
instruction. Allows reuse of register contents by using
|
||||
'<tt>SMC_StoreAddress</tt>' for multiple SMC instruction modifications.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
SMC_TransferAddress JumpTo, #CloseChannel
|
||||
...
|
||||
SMC JumpTo, { JMP OpenChannel }
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<label id="Store address">
|
||||
<tag><tt>SMC_StoreAddress label</tt></tag>
|
||||
|
||||
Stores the address value in a/x to a SMC instruction address position.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
SMC_StoreAddress GetData
|
||||
...
|
||||
SMC GetData, { LDA SMC_AbsAdr }
|
||||
</verb></tscreen>
|
||||
|
||||
</descrip>
|
||||
|
||||
<sect1>Operational macros<p>
|
||||
|
||||
These marcos are determined to let read/modify/write opcodes work on parts of
|
||||
SMC instructions.
|
||||
|
||||
<descrip>
|
||||
|
||||
<label id="Operate on value">
|
||||
<tag><tt>SMC_OperateOnValue opcode, label</tt></tag>
|
||||
|
||||
Let given opcode work on the value part of a SMC instruction.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
SMC_OperateOnValue ASL, LoadMask ; shift mask to left
|
||||
...
|
||||
SMC LoadMask, { LDA #$20 }
|
||||
</verb></tscreen>
|
||||
|
||||
<label id="Operate on low-byte">
|
||||
<tag><tt>SMC_OperateOnLowByte opcode, label</tt></tag>
|
||||
|
||||
Same as '<tt/SMC_OperateOnValue/' but renamed for better readability when
|
||||
accessing low-bytes of address.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
SMC_OperateOnLowByte DEC, AccessData
|
||||
...
|
||||
SMC AccessData, { LDX Data }
|
||||
</verb></tscreen>
|
||||
|
||||
<label id="Operate on high-byte">
|
||||
<tag><tt>SMC_OperateOnHighByte opcode, label</tt></tag>
|
||||
|
||||
Let the given opcode work on the high-byte part on a SMC-instruction.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
NextPage:
|
||||
SMC_OperateOnHighByte INC, GetPageData
|
||||
...
|
||||
SMC GetPageData, { LDA SourceData, X }
|
||||
</verb></tscreen>
|
||||
</descrip>
|
||||
|
||||
<sect1>Scope macros<p>
|
||||
|
||||
These marcos are determined to export and import SMC labels out of the current
|
||||
file scope. Please handle with care! If you cannot abstain from leaving the
|
||||
file scope, you should at least document the exported SMC lines very well. On
|
||||
import side no checking is available if the SMC line is correct accessed (e.g.
|
||||
invalid access to the value of an implied instruction)!
|
||||
|
||||
<descrip>
|
||||
<label id="Export SMC line under given name">
|
||||
<tag><tt>SMC_Export alias, label</tt></tag>
|
||||
|
||||
SMC label will be exported under given alias.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
.proc GetValue
|
||||
SMC LoadValue, { LDA #12 }
|
||||
rts
|
||||
.endproc
|
||||
|
||||
SMC_Export GetValueLoader, GetValue::LoadValue
|
||||
</verb></tscreen>
|
||||
|
||||
<label id="Import SMC alias">
|
||||
<tag><tt>SMC_Import alias</tt></tag>
|
||||
|
||||
SMC line is made accessible under given alias.
|
||||
|
||||
Example:
|
||||
<tscreen><verb>
|
||||
SMC_Import GetValueLoader
|
||||
...
|
||||
SMC_TransferValue GetValueLoader, #47
|
||||
...
|
||||
</verb></tscreen>
|
||||
</descrip>
|
||||
|
||||
<sect>A complex example<p>
|
||||
Let's have a look on a quite sophisticated example for the usage of SMC. It
|
||||
not only modifies code, but also the modification of the code is modified -
|
||||
allowing reuse of some instructions.
|
||||
|
||||
The code is from my 'memset()'implementation:
|
||||
|
||||
<descrip>
|
||||
<tscreen><verb>
|
||||
1: ...
|
||||
2: SMC_StoreAddress StoreAccuFirstSection
|
||||
3:
|
||||
4: StoreToFirstSection:
|
||||
5: SMC StoreAccuFirstSection, { sta SMC_AbsAdr, Y }
|
||||
6: ...
|
||||
7: RestoreCodeBranchBaseAdr:
|
||||
8: SMC FirstIncHighByte, { SMC_OperateOnHighByte inc, StoreAccuFirstSection } ; code will be overwritten to 'beq RestoreCode' (*)
|
||||
9: ...
|
||||
10: SMC_TransferOpcode FirstIncHighByte, OPC_BEQ , x ; change code marked above with (*)
|
||||
11: SMC_TransferValue FirstIncHighByte, #(restoreCode - RestoreCodeBranchBaseAdr-2), x ; set relative adress to 'RestoreCode'
|
||||
12: ...
|
||||
13: restoreCode:
|
||||
14: SMC_TransferOpcode FirstIncHighByte, OPC_INC_abs , x ; restore original code...
|
||||
15: SMC_TransferValue FirstIncHighByte, #(<(StoreToFirstSection+2)), x ; (second byte of inc contained low-byte of adress)
|
||||
16: ...
|
||||
</verb></tscreen>
|
||||
|
||||
Some explanation:
|
||||
|
||||
Line 2: The register pair A/X contains an address, which is stored on the
|
||||
address location of a SMC line called 'StoreAccuFirstSection'. According to
|
||||
cc65's calling convention, the low-byte is in accu while the high-byte is in
|
||||
the X-register.
|
||||
|
||||
Line 5: The (modified) address is accessed.
|
||||
|
||||
Line 8: We have a line here, which is about to be modified (it begins with
|
||||
SMC), but itself modifies code. Please note: Contrary to the rest of SMC-line
|
||||
modifying macros, the 'OperateOn'-macros just expand their given arguments
|
||||
into a single instruction line. These can be changed of course too.
|
||||
|
||||
Line 10,11: These lines construct a branch operation for line 8: The
|
||||
X-register will be used to change it from 'inc StoreAccuFirstSection+2'
|
||||
(high-byte operation) to 'beq restoreCode'. Please note: To calculate the
|
||||
relaive branch offset, we introduced a second label
|
||||
('RestoreCodeBranchBaseAdr') for to calculate it. Some could also use the
|
||||
internal name of the SMC label, but you should abstain to do so - it may be
|
||||
changed in the future...
|
||||
|
||||
Line 14,15: The original code from line 8 is reestablished.
|
||||
</descrip>
|
||||
</article>
|
||||
|
||||
415
doc/sp65.sgml
Normal file
415
doc/sp65.sgml
Normal file
@ -0,0 +1,415 @@
|
||||
<!doctype linuxdoc system> <!-- -*- text-mode -*- -->
|
||||
|
||||
<article>
|
||||
<title>sp65 Users Guide
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>2012-03-11
|
||||
|
||||
<abstract>
|
||||
sp65 is a sprite and bitmap utility that is part of the cc65 development suite.
|
||||
It is used to convert graphics and bitmaps into the target formats of the
|
||||
supported machines.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
sp65 is a tool that converts images from common formats into formats used
|
||||
on the 6502 platforms that are the targets of the cc65 compiler suite. In
|
||||
addition, it allows some very simple operation with loaded graphics data, like
|
||||
using part of an image for further processing.
|
||||
|
||||
The utility has been designed in a way that adding additional source or target
|
||||
formats is easy. The final output is either binary, or C/assembler source.
|
||||
|
||||
|
||||
|
||||
<sect>Usage<p>
|
||||
|
||||
|
||||
<sect1>Command line option overview<p>
|
||||
|
||||
The sp65 utility accepts the following options:
|
||||
|
||||
<tscreen><verb>
|
||||
---------------------------------------------------------------------------
|
||||
Usage: sp65 [options] file [options] [file]
|
||||
Short options:
|
||||
-V Print the version number and exit
|
||||
-c fmt[,attrlist] Convert into target format
|
||||
-h Help (this text)
|
||||
-lc List all possible conversions
|
||||
-r file[,attrlist] Read an input file
|
||||
-v Increase verbosity
|
||||
-w file[,attrlist] Write the output to a file
|
||||
|
||||
Long options:
|
||||
--convert-to fmt[,attrlist] Convert into target format
|
||||
--help Help (this text)
|
||||
--list-conversions List all possible conversions
|
||||
--pop Restore the original loaded image
|
||||
--read file[,attrlist] Read an input file
|
||||
--slice x,y,w,h Generate a slice from the loaded bitmap
|
||||
--verbose Increase verbosity
|
||||
--version Print the version number and exit
|
||||
--write file[,attrlist] Write the output to a file
|
||||
---------------------------------------------------------------------------
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<sect1>Command line options in detail<p>
|
||||
|
||||
Below is a description of all the command line options. For the concept of
|
||||
attribute lists see <ref id="attr-lists" name="below">.
|
||||
|
||||
<descrip>
|
||||
|
||||
<label id="option--convert-to">
|
||||
<tag><tt>-c, --convert-to format[,attrlist]</tt></tag>
|
||||
|
||||
Convert a bitmap into one of the supported target formats. The option
|
||||
argument must at least contain the "format" attribute. For more attributes,
|
||||
see section <ref id="conversions" name="Conversions">.
|
||||
|
||||
|
||||
<label id="option--help">
|
||||
<tag><tt>-h, --help</tt></tag>
|
||||
|
||||
Print the short option summary shown above.
|
||||
|
||||
|
||||
<label id="option--list-conversions">
|
||||
<tag><tt>-lc, --list-conversions</tt></tag>
|
||||
|
||||
Print a list of possible conversions.
|
||||
|
||||
|
||||
<label id="option--pop">
|
||||
<tag><tt>--pop</tt></tag>
|
||||
|
||||
Restore the working copy of the bitmap from the one originally loaded from
|
||||
the file. This may for example be used when creating several output files
|
||||
from one input file.
|
||||
|
||||
|
||||
<label id="option--read">
|
||||
<tag><tt>-r, --read filename[,attrlist]</tt></tag>
|
||||
|
||||
Read an input file. The option argument must at least contain the "name"
|
||||
attribute. See <ref id="input-formats" name="input formats"> for more
|
||||
information.
|
||||
|
||||
|
||||
<label id="option-v">
|
||||
<tag><tt>-v, --verbose</tt></tag>
|
||||
|
||||
Increase verbosity. Usually only needed for debugging purposes. You may use
|
||||
this option more than one time for even more verbose output.
|
||||
|
||||
|
||||
<label id="option-V">
|
||||
<tag><tt>-V, --version</tt></tag>
|
||||
|
||||
Print the version number of the assembler. If you send any suggestions or
|
||||
bugfixes, please include the version number.
|
||||
|
||||
|
||||
<label id="option--write">
|
||||
<tag><tt>-w, --write filename[,attrlist]</tt></tag>
|
||||
|
||||
Write an output file. The option argument must at least contain the "name"
|
||||
attribute. See <ref id="output-formats" name="output formats"> for more
|
||||
information.
|
||||
|
||||
</descrip>
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<sect>Processing pipeline<label id="processing-pipeline"><p>
|
||||
|
||||
sp65 consists of
|
||||
|
||||
<itemize>
|
||||
<item>Front ends that read graphics data,
|
||||
<item>processors for graphics data,
|
||||
<item>converters
|
||||
<item>and output modules for several formats.
|
||||
</itemize>
|
||||
|
||||
These modules can be combined to a pipeline that reads data, does some
|
||||
optional bitmap processing, converts the bitmap into a target format, and
|
||||
writes this binary data to disk in one of several forms.
|
||||
|
||||
|
||||
|
||||
<sect>Attribute lists<label id="attr-lists"><p>
|
||||
|
||||
As described in <ref id="processing-pipeline" name="Processing pipeline">,
|
||||
sp65 consists of lots of different modules that may be combined in different
|
||||
ways, to convert an input bitmap to some output.
|
||||
|
||||
Many of the processors and converters have options to change the way, they're
|
||||
working. To avoid having lots of command line options that must be parsed on
|
||||
high level and passed down to the relevant parts of the program, sp65 features
|
||||
something called "attribute lists". Attribute lists are lists of
|
||||
attribute/value pairs. These lists are parsed by the main program module
|
||||
without any knowledge about their meaning. Lower level parts just grab the
|
||||
attributes they need.
|
||||
|
||||
In general, attribute lists look like this:
|
||||
|
||||
<tscreen><verb>
|
||||
attr1=val1[,attr2=val2[,...]]
|
||||
</verb></tscreen>
|
||||
|
||||
Instead of the comma, colons may also be used (even mixed).
|
||||
|
||||
To simplify things and to make the most common options look "normal", some
|
||||
mandatory attributes may be given without an attribute name. If the attribute
|
||||
name is missing, the default name is determined by the position. For example,
|
||||
the option <tt/<ref id="option--read" name="--read">/ does always need a file
|
||||
name. The attribute name for the file name is "name". To avoid having to type
|
||||
|
||||
<tscreen><verb>
|
||||
sp65 --read name=ball.pcx ...
|
||||
</verb></tscreen>
|
||||
|
||||
the first attribute gets the default name "name" assigned. So if the first
|
||||
attribute doesn't have a name, it is assumed that it is the file name. This
|
||||
means that instead of the line above, one can also use
|
||||
|
||||
<tscreen><verb>
|
||||
sp65 --read ball.pcx ...
|
||||
</verb></tscreen>
|
||||
|
||||
The second attribute for <tt/--read/ is the format of the input file. So when
|
||||
using
|
||||
|
||||
<tscreen><verb>
|
||||
sp65 --read ball.pic:pcx ...
|
||||
</verb></tscreen>
|
||||
|
||||
a PCX file named "ball.pic" is read. The long form would be
|
||||
|
||||
<tscreen><verb>
|
||||
sp65 --read name=ball.pic:format=pcx ...
|
||||
</verb></tscreen>
|
||||
|
||||
Changing the order of the attributes is possible only when explicitly
|
||||
specifying the names of the attributes. Using
|
||||
|
||||
<tscreen><verb>
|
||||
sp65 --read pcx:ball.pic ...
|
||||
</verb></tscreen>
|
||||
|
||||
will make sp65 complain, because it tries to read a file named "pcx" with an
|
||||
(unknown) format of "ball.pic". The following however will work:
|
||||
|
||||
<tscreen><verb>
|
||||
sp65 --read format=pcx:name=ball.pic ...
|
||||
</verb></tscreen>
|
||||
|
||||
The attributes that are valid for each processor or converter are listed
|
||||
below.
|
||||
|
||||
|
||||
|
||||
<sect>Input formats<label id="input-formats"><p>
|
||||
|
||||
Input formats are either specified explicitly when using <tt/<ref
|
||||
id="option--read" name="--read">/, or are determined by looking at the
|
||||
extension of the file name given.
|
||||
|
||||
<sect1>PCX<p>
|
||||
|
||||
While sp65 is prepared for more, this is currently the only possible input
|
||||
format. There are no additional attributes for this format.
|
||||
|
||||
|
||||
|
||||
<sect>Conversions<label id="conversions"><p>
|
||||
|
||||
<sect1>GEOS bitmap<p>
|
||||
|
||||
The current bitmap working copy is converted to a GEOS compacted bitmap. This
|
||||
format is used by several GEOS functions (i.e. 'BitmapUp') and is described
|
||||
in 'The Official GEOS Programmers Reference Guide', chapter 4, section
|
||||
'Bit-Mapped Graphics'.
|
||||
|
||||
|
||||
<sect1>GEOS icon<p>
|
||||
|
||||
The current bitmap working copy is converted to GEOS icon format. A GEOS icon
|
||||
has the same format as a C64 high resolution sprite (24x21, monochrome, 63
|
||||
bytes). There are no additional attributes for this conversion.
|
||||
|
||||
|
||||
<sect1>Koala image<p>
|
||||
|
||||
|
||||
<sect1>Lynx sprite<p>
|
||||
|
||||
Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size
|
||||
of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by
|
||||
102 pixels which makes very large sprites useless.
|
||||
|
||||
The number per pixels is taken from the number of colors of the input bitmap.
|
||||
|
||||
There are a few attributes that you can give to the conversion software.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag/mode/
|
||||
The first is what kind of encoding to use for the sprite. The attribute for
|
||||
this is called "mode" and the possible values are "literal", "packed" or
|
||||
"transparent". The default is "packed" if no mode is specified.
|
||||
|
||||
The "literal" is a totally literal mode with no packing. In this mode the
|
||||
number of pixels per scanline will be a multiple of 8 both right and left from
|
||||
the action point.
|
||||
|
||||
If the source bitmap edge ends with a color where the least significant bit is
|
||||
one then there will be an extra 8 zero bits on that scan line.
|
||||
|
||||
So if you are using totally literal sprites and intend to change them at
|
||||
runtime then please add a single pixel border far left and far right with
|
||||
zeros in order to prevent graphical glitches in the game.
|
||||
|
||||
The standard encoding is called "packed". In this mode the sprite is packed
|
||||
using run-length encoding and literal coding mixed for optimisation to
|
||||
produce a small sprite.
|
||||
|
||||
The last encoding mode "transparent" is like packed. But here we know that
|
||||
the index 0 will be transparent so we can clip off all 0 pixels from the left
|
||||
and right edge of the sprite. This will produce the smallest sprite possible
|
||||
on the Lynx. The sprite is not rectangular anymore.
|
||||
|
||||
<tag/ax/
|
||||
The sprite is painted around the Anchor point. The anchor point x can be
|
||||
between 0 and the width of the sprite - 1. If anchor point x is zero then
|
||||
painting the sprite in location 10,20 will set the left edge of the sprite
|
||||
10 pixels from the left of the Lynx screen. When the sprite is scaled by
|
||||
hardware the anchor point stays in place and the sprite grows or shrinks
|
||||
around the anchor point. The default value is 0 (left).
|
||||
|
||||
<tag/ay/
|
||||
The sprite is painted around the Anchor point. The anchor point y can be
|
||||
between 0 and the height of the sprite - 1. If anchor point y is zero then
|
||||
painting the sprite in location 10,20 will set the top of the sprite 20
|
||||
pixels from the top of the Lynx screen. When the sprite is scaled by
|
||||
hardware the anchor point stays in place and the sprite grows or shrinks
|
||||
around the anchor point. The default value is 0 (top).
|
||||
|
||||
</descrip>
|
||||
|
||||
<sect1>VIC2 sprite<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect>Output formats<label id="output-formats"><p>
|
||||
|
||||
Using <tt/<ref id="option--write" name="--write">/ it is possible to write
|
||||
processed data to an output file. An attribute "name" is mandatory, it is used
|
||||
as the file name for the output. The output format can be specified using an
|
||||
attribute named "format". If this attribute doesn't exist, the output format
|
||||
is determined by looking at the file name extension.
|
||||
|
||||
|
||||
<sect1>Binary<p>
|
||||
|
||||
For this format, the processed data is written to the output file in raw
|
||||
binary format. There are no additional attributes (besides "name" and
|
||||
"format") for this output format.
|
||||
|
||||
|
||||
<sect1>Assembler code<p>
|
||||
|
||||
For this format, the processed data is written to the output file in ca65
|
||||
assembler format. There are several attributes for this output format:
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag/base/
|
||||
The value for this attribute specifies the numeric base for the data
|
||||
values. It may be either 2, 10 or 16. The default is 16. If the base is
|
||||
2, the numbers are prefixed by '%', if the base is 16, the numbers are
|
||||
prefixed by '$'. For base 10, there is no prefix.
|
||||
|
||||
<tag/bytesperline/
|
||||
The value for this attribute specifies the number of bytes output in one
|
||||
line of the assembler file. The default is 16.
|
||||
|
||||
<tag/ident/
|
||||
This is an optional attribute. When given, the output processor will wrap
|
||||
the data into a <tt/.PROC/ with the given name. In addition, three constants
|
||||
are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/
|
||||
and <tt/HEIGHT/.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
|
||||
<sect1>C code<p>
|
||||
|
||||
When using C output format, a small piece of C source code is generated that
|
||||
defines the data containing the output in an array of <tt/unsigned char/.
|
||||
|
||||
Possible attributes for this format are:
|
||||
|
||||
<descrip>
|
||||
<tag/base/
|
||||
The value for this attribute specifies the numeric base for the data values.
|
||||
It may be either 10 or 16. The default is 16. If the base is 16, the numbers
|
||||
are prefixed by 0x. For base 10, there is no prefix.
|
||||
|
||||
<tag/bytesperline/
|
||||
The value for this attribute specifies the number of bytes output in one
|
||||
line of the C source code. The default is 16.
|
||||
|
||||
<tag/ident/
|
||||
This is an optional attribute. When given, the output processor will wrap
|
||||
the data into an array of unsigned char with the given name. In addition,
|
||||
three <tt/#define/s are added for <tt/<ident>_COLORS/,
|
||||
<tt/<ident>_WIDTH/ and <tt/<ident>_HEIGHT/.
|
||||
|
||||
</descrip>
|
||||
|
||||
|
||||
|
||||
<sect>Copyright<p>
|
||||
|
||||
sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz
|
||||
and others. For usage of the binaries and/or sources the following conditions
|
||||
do apply:
|
||||
|
||||
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>
|
||||
|
||||
|
||||
|
||||
170
doc/supervision.sgml
Normal file
170
doc/supervision.sgml
Normal file
@ -0,0 +1,170 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Watara Supervision specific information for cc65
|
||||
<author>Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
|
||||
<date>2005-07-17
|
||||
|
||||
<abstract>
|
||||
An overview over the Supervision runtime system as it is implemented for the
|
||||
cc65 C compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the Supervision runtime system as it comes
|
||||
with the cc65 C compiler. It describes the memory layout, Supervision specific header
|
||||
files, available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that Supervision specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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 Supervision target
|
||||
is a 2×16 kbyte machine language program. It is of course
|
||||
possible to change this behaviour by using one of the different linker configs.
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs with the default setup run with the I/O area enabled,
|
||||
which gives a usable memory range of $8000 - $FFF9.
|
||||
More ROM may need additional bankswitching code.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
<!-- The text screen is located at VRAM $4000.-->
|
||||
No conio support is currently available for the Supervision.
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $1FFF and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing Supervision specific code may use the <tt/supervision.h/ header file.
|
||||
|
||||
|
||||
<sect1>Supervision specific functions<p>
|
||||
|
||||
<itemize>
|
||||
<item>waitvblank
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect1>Hardware access<p>
|
||||
|
||||
The following pseudo variables declared in the <tt/supervision.inc/ include file do
|
||||
allow access to hardware located in the address space.
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/IO/</tag>
|
||||
The <tt/IO/ defines allow access to the IO chip.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Loadable drivers<p>
|
||||
|
||||
<sect1>Graphics drivers<p>
|
||||
|
||||
No graphics drivers are currently available for the Supervision.
|
||||
<!--A TGI driver for the standard graphics mode (160×160 in 4 colors) is
|
||||
available, but must be statically linked, because no file I/O is available.
|
||||
See the documentation for the <htmlurl url="co65.html" name="co65 utility">
|
||||
for information on how to do that.-->
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
No extended memory drivers are currently available for the Supervision.
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
No joystick drivers are currently available for the Supervision.
|
||||
<!--A joystick driver for the standard buttons is available, but must be
|
||||
statically linked, because no file I/O is available. See the documentation for
|
||||
the <htmlurl url="co65.html" name="co65 utility"> for information on how to do
|
||||
that.-->
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the Supervision.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
No communication port drivers are currently available for the Supervision.
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
<sect1>Disk I/O<p>
|
||||
|
||||
The existing library for the Supervision doesn't implement C file
|
||||
I/O. There are even no hacks for the <tt/read()/ and <tt/write()/ routines.
|
||||
|
||||
To be more concrete, this limitation means that you cannot use any of the
|
||||
following functions (and a few others):
|
||||
|
||||
<itemize>
|
||||
<item>fclose
|
||||
<item>fopen
|
||||
<item>fread
|
||||
<item>fprintf
|
||||
<item>fputc
|
||||
<item>fscanf
|
||||
<item>fwrite
|
||||
<item>...
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
156
doc/using-make.sgml
Normal file
156
doc/using-make.sgml
Normal file
@ -0,0 +1,156 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Using GNU Make with cc65
|
||||
<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de">
|
||||
<date>2009-06-26
|
||||
|
||||
<abstract>
|
||||
How to build your program using the GNU Make utility.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This document describes how to build your programs using the cc65 development
|
||||
tools and the GNU Make utility.
|
||||
|
||||
The cc65 development package doesn't come with a make utility. However this is
|
||||
no issue because GNU Make works very nicely with cc65.
|
||||
|
||||
|
||||
|
||||
<sect>What is GNU Make?<p>
|
||||
|
||||
GNU Make is a both very powerful and very popular make utility. It might even
|
||||
be called the de facto standard for make utilities. For more information see
|
||||
the GNU Make home page:
|
||||
|
||||
<url url="http://www.gnu.org/software/make/">
|
||||
|
||||
The cc65 development package is available as binaries for several host systems
|
||||
and can easily built for quite some additional systems. The very same is true
|
||||
for GNU Make so a cc65-based project coming with a GNU Make Makefile can easily
|
||||
be built by any cc65 developer no matter what host system is used.
|
||||
|
||||
Because of the strong alignment of the cc65 compiler with the ISO C standard it
|
||||
is very well feasible to compile a single C code base both with the cc65
|
||||
compiler and other C compilers like for example GCC. GNU Make turns out to be
|
||||
very well suited to build projects for several target systems using multiple
|
||||
compilers as it isn't tied to any C compiler.
|
||||
|
||||
|
||||
|
||||
<sect>A sample Makefile<p>
|
||||
|
||||
This Makefile is a fully functional sample for compiling several C sources
|
||||
(here <tt/foo.c/ and <tt/bar.c/) and link the resulting object files into an
|
||||
executable program (here <tt/foobar/):
|
||||
|
||||
<tscreen><verb>
|
||||
SOURCES = foo.c bar.c
|
||||
|
||||
PROGRAM = foobar
|
||||
|
||||
ifdef CC65_TARGET
|
||||
CC = $(CC65_HOME)/bin/cl65
|
||||
CFLAGS = -t $(CC65_TARGET) --create-dep $(<:.c=.d) -O
|
||||
LDFLAGS = -t $(CC65_TARGET) -m $(PROGRAM).map
|
||||
else
|
||||
CC = gcc
|
||||
CFLAGS = -MMD -MP -O
|
||||
LDFLAGS = -Wl,-Map,$(PROGRAM).map
|
||||
endif
|
||||
|
||||
########################################
|
||||
|
||||
.SUFFIXES:
|
||||
.PHONY: all clean
|
||||
all: $(PROGRAM)
|
||||
|
||||
ifneq ($(MAKECMDGOALS),clean)
|
||||
-include $(SOURCES:.c=.d)
|
||||
endif
|
||||
|
||||
%.o: %.c
|
||||
$(CC) -c $(CFLAGS) -o $@ $<
|
||||
|
||||
$(PROGRAM): $(SOURCES:.c=.o)
|
||||
$(CC) $(LDFLAGS) -o $@ $^
|
||||
|
||||
clean:
|
||||
$(RM) $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map
|
||||
</verb></tscreen>
|
||||
|
||||
<bf/Important:/ When using the sample Makefile above via copy & paste it is
|
||||
necessary to replace the eight spaces at the beginning of command lines (lines
|
||||
26, 29 and 32) with a tab character (ASCII code 9).
|
||||
|
||||
|
||||
<sect1>Invoking the sample Makefile<p>
|
||||
|
||||
Without any specific configuration the sample Makefile will compile and link
|
||||
using GCC. In order to rather use cc65 the variable <tt/CC65_TARGET/ needs to be
|
||||
defined. This may by done as an environment variable or simply as part of the
|
||||
Makefile. However to quickly switch between compilers and/or cc65 targets it is
|
||||
best done on the GNU Make command line like this:
|
||||
|
||||
<tscreen><verb>
|
||||
make CC65_TARGET=c64
|
||||
</verb></tscreen>
|
||||
|
||||
The sample Makefile presumes the variable <tt/CC65_HOME/ to point to the
|
||||
directory cc65 is located in. Again there are several ways to define this
|
||||
variable but as its value typically won't change often it is best done as an
|
||||
environment variable. On Windows the cc65 .exe installer package takes care
|
||||
of creating a <tt/CC65_HOME/ environment variable.
|
||||
|
||||
|
||||
<sect1>Understanding the sample Makefile<p>
|
||||
|
||||
Most parts of the sample Makefile follow the guidelines in the
|
||||
<htmlurl url="http://www.gnu.org/software/make/manual/make.html" name="GNU Make Manual">
|
||||
that can be searched online for background information. The automatic generation of
|
||||
dependency however rather works as described by the GNU Make maintainer Paul D. Smith in
|
||||
<htmlurl url="http://make.paulandlesley.org/autodep.html#advanced" name="Advanced Auto-Dependencies">.
|
||||
Fortunately both GCC and cc65 directly support this method in the meantime.
|
||||
|
||||
|
||||
<sect1>Invoking the sample Makefile on Windows<p>
|
||||
|
||||
The recommended way to use GNU Make on Windows is to install it as part of a
|
||||
Cygwin environment. For more information see the Cygwin home page:
|
||||
|
||||
<url url="http://www.cygwin.com/">
|
||||
|
||||
If however installing Cygwin shouldn't be an option for one or the other reason
|
||||
then the sample Makefile may be invoked from the Windows Command Prompt (cmd.exe)
|
||||
by downloading the following programs:
|
||||
|
||||
<itemize>
|
||||
<item>make.exe: <url url="http://gnuwin32.sourceforge.net/packages/make.htm">
|
||||
<item>rm.exe: <url url="http://gnuwin32.sourceforge.net/packages/coreutils.htm">
|
||||
</itemize>
|
||||
|
||||
|
||||
|
||||
<sect>Target-specific Variable Values<p>
|
||||
|
||||
The very limited resources of the cc65 target machines now and then require
|
||||
manual optimization of the build process by compiling individual source files
|
||||
with different compiler options. GNU Make offers
|
||||
<htmlurl url="http://www.gnu.org/software/make/manual/html_node/Target_002dspecific.html" name="Target-specific Variable Values">
|
||||
perfectly suited for doing so. For example placing the code of the two modules
|
||||
<tt/foo/ and <tt/bar/ in the segment <tt/FOOBAR/ can be archived with this
|
||||
target-specific variable definition:
|
||||
|
||||
<tscreen><verb>
|
||||
foo.o bar.o: CFLAGS += --code-name FOOBAR
|
||||
</verb></tscreen>
|
||||
|
||||
</article>
|
||||
260
doc/vic20.sgml
Normal file
260
doc/vic20.sgml
Normal file
@ -0,0 +1,260 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Commodore VIC20 (aka VC20) specific information for cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
|
||||
<date>2004-09-13
|
||||
|
||||
<abstract>
|
||||
An overview over the VIC20 runtime system as it is implemented for the cc65 C
|
||||
compiler.
|
||||
</abstract>
|
||||
|
||||
<!-- Table of contents -->
|
||||
<toc>
|
||||
|
||||
<!-- Begin the document -->
|
||||
|
||||
<sect>Overview<p>
|
||||
|
||||
This file contains an overview of the VIC20 runtime system as it comes with the
|
||||
cc65 C compiler. It describes the memory layout, VIC20 specific header files,
|
||||
available drivers, and any pitfalls specific to that platform.
|
||||
|
||||
Please note that VIC20 specific functions are just mentioned here, they are
|
||||
described in detail in the separate <htmlurl 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 VIC20 target
|
||||
is a machine language program with a one line BASIC stub, which calls the
|
||||
machine language part via SYS. This means that a program can be loaded as
|
||||
BASIC program and started with RUN. It is of course possible to change this
|
||||
behaviour by using a modified startup file and linker config.
|
||||
|
||||
|
||||
<sect>Memory layout<p>
|
||||
|
||||
cc65 generated programs with the default setup run with unexpanded memory
|
||||
(RAM at $A000 - $BFFF may be used for the heap),
|
||||
which gives a usable memory range of $1000 - $1DFF.
|
||||
All ROM entry points may be called directly without additional code.
|
||||
|
||||
Special locations:
|
||||
|
||||
<descrip>
|
||||
<tag/Text screen/
|
||||
The text screen is located at $1E00 (as in the standard setup).
|
||||
|
||||
<tag/Stack/
|
||||
The C runtime stack is located at $1DFF and growing downwards.
|
||||
|
||||
<tag/Heap/
|
||||
The C heap is located at the end of the program and grows towards the C
|
||||
runtime stack.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
|
||||
<sect>Platform specific header files<p>
|
||||
|
||||
Programs containing VIC20 specific code may use the <tt/vic20.h/ or <tt/cbm.h/
|
||||
header files. Using the later may be an option when writing code for more than
|
||||
one CBM platform, since it includes <tt/vic20.h/ and declares several functions
|
||||
common to all CBM platforms.
|
||||
|
||||
|
||||
<sect1>VIC20 specific functions<p>
|
||||
|
||||
There are currently no special VIC20 functions.
|
||||
|
||||
|
||||
|
||||
<sect1>CBM specific functions<p>
|
||||
|
||||
Some functions are available for all (or at least most) of the Commodore
|
||||
machines. See the <htmlurl url="funcref.html" name="function reference"> for
|
||||
declaration and usage.
|
||||
|
||||
<itemize>
|
||||
<item>cbm_close
|
||||
<item>cbm_closedir
|
||||
<item>cbm_k_setlfs
|
||||
<item>cbm_k_setnam
|
||||
<item>cbm_k_load
|
||||
<item>cbm_k_save
|
||||
<item>cbm_k_open
|
||||
<item>cbm_k_close
|
||||
<item>cbm_k_readst
|
||||
<item>cbm_k_chkin
|
||||
<item>cbm_k_ckout
|
||||
<item>cbm_k_basin
|
||||
<item>cbm_k_bsout
|
||||
<item>cbm_k_clrch
|
||||
<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/vic20.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/VIC/</tag>
|
||||
The <tt/VIC/ structure allows access to the VIC (the graphics
|
||||
controller). See the <tt/_vic.h/ header file located in the include
|
||||
directory for the declaration of the structure.
|
||||
|
||||
<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 these variables
|
||||
is explained in <tt/_6522.h/.
|
||||
|
||||
<tag><tt/COLOR_RAM/</tag>
|
||||
A character array that mirrors the color RAM of the VIC20 at $9600.
|
||||
|
||||
</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 currently available for the VIC20.
|
||||
|
||||
|
||||
<sect1>Extended memory drivers<p>
|
||||
|
||||
No extended memory drivers are currently available for the VIC20.
|
||||
|
||||
|
||||
<sect1>Joystick drivers<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag><tt/vic20-stdjoy.joy (vic20_stdjoy_joy)/</tag>
|
||||
Supports one standard joystick connected to the joysticks port of the VIC20.
|
||||
|
||||
<tag><tt/vic20-ptvjoy.joy (vic20_ptvjoy_joy)/</tag>
|
||||
Driver for the Protovision 4-player adapter contributed by Groepaz. See
|
||||
<htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
|
||||
name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
|
||||
building instructions. Up to three joysticks are supported.
|
||||
|
||||
</descrip><p>
|
||||
|
||||
|
||||
<sect1>Mouse drivers<p>
|
||||
|
||||
No mouse drivers are currently available for the VIC20.
|
||||
|
||||
|
||||
<sect1>RS232 device drivers<p>
|
||||
|
||||
No VIC1011 drivers are currently available for the VIC20.
|
||||
|
||||
|
||||
|
||||
<sect>Limitations<p>
|
||||
|
||||
|
||||
|
||||
<sect>Other hints<p>
|
||||
|
||||
<sect1>Escape code<p>
|
||||
|
||||
For an Esc press CTRL and [ key.
|
||||
|
||||
<sect1>Passing arguments to the program<p>
|
||||
|
||||
Command line arguments can be passed to <tt/main()/. Since this is not
|
||||
supported 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>Using extended memory<p>
|
||||
|
||||
The extended memory at $A000 may be added to the heap by using the following
|
||||
code:
|
||||
|
||||
<tscreen><verb>
|
||||
/* Check for the existence of RAM */
|
||||
if (PEEK(0xA000) == POKE(0xA000, PEEK(0xA000)+1)) {
|
||||
/* Add it to the heap */
|
||||
_heapadd ((void *) 0xA000, 0x2000);
|
||||
}
|
||||
</verb></tscreen>
|
||||
|
||||
|
||||
<sect1>Interrupts<p>
|
||||
|
||||
The runtime for the VIC20 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
|
||||
when they are linked into a program. See the discussion of the <tt/.CONDES/
|
||||
feature in the <htmlurl 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>
|
||||
@ -82,7 +82,7 @@ define INSTALL_recipe
|
||||
|
||||
$(if $(prefix),,$(error variable `prefix' must be set))
|
||||
$(INSTALL) -d $(subst ..,$(DESTDIR)$(datadir),$(dir))
|
||||
$(INSTALL) -m644 $(dir)/* $(subst ..,$(DESTDIR)$(datadir),$(dir))
|
||||
$(INSTALL) -m644 $(dir)/*.* $(subst ..,$(DESTDIR)$(datadir),$(dir))
|
||||
|
||||
endef
|
||||
|
||||
|
||||
18
src/Makefile
18
src/Makefile
@ -1,3 +1,7 @@
|
||||
.SUFFIXES:
|
||||
|
||||
.PHONY: all bin $(PROGS) mostlyclean clean install avail unavail
|
||||
|
||||
ifeq ($(shell echo),)
|
||||
|
||||
PROGS = ar65 \
|
||||
@ -22,18 +26,16 @@ LD65_OBJ = $(datadir)/lib
|
||||
LD65_CFG = $(datadir)/cfg
|
||||
|
||||
CFLAGS += -MMD -MP -O -std=c89 -I common \
|
||||
-Wall -Wextra -Wno-char-subscripts -Werror $(USER_CFLAGS) \
|
||||
-Wall -Wextra -Wno-char-subscripts $(USER_CFLAGS) \
|
||||
-DCA65_INC=$(CA65_INC) -DCC65_INC=$(CC65_INC) \
|
||||
-DLD65_LIB=$(LD65_LIB) -DLD65_OBJ=$(LD65_OBJ) -DLD65_CFG=$(LD65_CFG)
|
||||
|
||||
CFLAGS += $(if $(TRAVIS),-Werror)
|
||||
|
||||
LDLIBS += -lm
|
||||
|
||||
INSTALL = install
|
||||
|
||||
.SUFFIXES:
|
||||
|
||||
.PHONY: all bin $(PROGS) mostlyclean clean install avail unavail
|
||||
|
||||
all bin: $(PROGS)
|
||||
|
||||
mostlyclean:
|
||||
@ -116,10 +118,6 @@ $(foreach prog,$(PROGS),$(eval $(call PROG_template,$(prog))))
|
||||
|
||||
else # cmd.exe
|
||||
|
||||
.SUFFIXES:
|
||||
|
||||
.PHONY: all bin mostlyclean clean
|
||||
|
||||
all bin:
|
||||
msbuild cc65.sln /p:configuration=release /consoleloggerparameters:disableconsolecolor
|
||||
|
||||
@ -129,4 +127,6 @@ mostlyclean:
|
||||
clean:
|
||||
msbuild cc65.sln /p:configuration=release /consoleloggerparameters:disableconsolecolor /target:$@
|
||||
|
||||
install avail unavail:
|
||||
|
||||
endif # cmd.exe
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -64,10 +64,11 @@
|
||||
|
||||
/* Name of the library file */
|
||||
const char* LibName = 0;
|
||||
static char* NewLibName = 0;
|
||||
|
||||
/* File descriptor for the library file */
|
||||
FILE* NewLib = 0;
|
||||
static FILE* Lib = 0;
|
||||
static FILE* NewLib = 0;
|
||||
|
||||
/* The library header */
|
||||
static LibHeader Header = {
|
||||
@ -246,10 +247,16 @@ void LibOpen (const char* Name, int MustExist, int NeedTemp)
|
||||
}
|
||||
|
||||
if (NeedTemp) {
|
||||
|
||||
/* Create the temporary library name */
|
||||
NewLibName = xmalloc (strlen (Name) + strlen (".temp") + 1);
|
||||
strcpy (NewLibName, Name);
|
||||
strcat (NewLibName, ".temp");
|
||||
|
||||
/* Create the temporary library */
|
||||
NewLib = tmpfile ();
|
||||
NewLib = fopen (NewLibName, "w+b");
|
||||
if (NewLib == 0) {
|
||||
Error ("Cannot create temporary file: %s", strerror (errno));
|
||||
Error ("Cannot create temporary library file: %s", strerror (errno));
|
||||
}
|
||||
|
||||
/* Write a dummy header to the temp file */
|
||||
@ -378,7 +385,7 @@ void LibClose (void)
|
||||
LibName, strerror (errno));
|
||||
}
|
||||
|
||||
/* Copy the new library to the new one */
|
||||
/* Copy the temporary library to the new one */
|
||||
fseek (NewLib, 0, SEEK_SET);
|
||||
while ((Count = fread (Buf, 1, sizeof (Buf), NewLib)) != 0) {
|
||||
if (fwrite (Buf, 1, Count, Lib) != Count) {
|
||||
@ -394,6 +401,9 @@ void LibClose (void)
|
||||
if (NewLib && fclose (NewLib) != 0) {
|
||||
Error ("Problem closing temporary library file: %s", strerror (errno));
|
||||
}
|
||||
if (NewLibName && remove (NewLibName) != 0) {
|
||||
Error ("Problem deleting temporary library file: %s", strerror (errno));
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
||||
@ -51,9 +51,6 @@
|
||||
/* Name of the library file */
|
||||
extern const char* LibName;
|
||||
|
||||
/* File descriptor for the new library file */
|
||||
extern FILE* NewLib;
|
||||
|
||||
|
||||
|
||||
/*****************************************************************************/
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
</ClCompile>
|
||||
|
||||
@ -585,11 +585,6 @@ static const struct {
|
||||
}
|
||||
};
|
||||
|
||||
#ifdef SUNPLUS
|
||||
/* Table for the SUNPLUS CPU */
|
||||
#include "sunplus.inc"
|
||||
#endif
|
||||
|
||||
/* Instruction table for the SWEET16 pseudo CPU */
|
||||
static const struct {
|
||||
unsigned Count;
|
||||
@ -781,11 +776,6 @@ static const InsTable* InsTabs[CPU_COUNT] = {
|
||||
(const InsTable*) &InsTab65SC02,
|
||||
(const InsTable*) &InsTab65C02,
|
||||
(const InsTable*) &InsTab65816,
|
||||
#ifdef SUNPLUS
|
||||
(const InsTable*) &InsTabSunPlus,
|
||||
#else
|
||||
0,
|
||||
#endif
|
||||
(const InsTable*) &InsTabSweet16,
|
||||
(const InsTable*) &InsTabHuC6280,
|
||||
0, /* Mitsubishi 740 */
|
||||
|
||||
@ -1810,14 +1810,6 @@ static void DoSmart (void)
|
||||
|
||||
|
||||
|
||||
static void DoSunPlus (void)
|
||||
/* Switch to the SUNPLUS CPU */
|
||||
{
|
||||
SetCPU (CPU_SUNPLUS);
|
||||
}
|
||||
|
||||
|
||||
|
||||
static void DoTag (void)
|
||||
/* Allocate space for a struct */
|
||||
{
|
||||
@ -2093,7 +2085,6 @@ static CtrlDesc CtrlCmdTab [] = {
|
||||
{ ccNone, DoUnexpected }, /* .STRING */
|
||||
{ ccNone, DoUnexpected }, /* .STRLEN */
|
||||
{ ccNone, DoStruct },
|
||||
{ ccNone, DoSunPlus },
|
||||
{ ccNone, DoTag },
|
||||
{ ccNone, DoUnexpected }, /* .TCOUNT */
|
||||
{ ccNone, DoUnexpected }, /* .TIME */
|
||||
|
||||
@ -276,7 +276,6 @@ struct DotKeyword {
|
||||
{ ".STRING", TOK_STRING },
|
||||
{ ".STRLEN", TOK_STRLEN },
|
||||
{ ".STRUCT", TOK_STRUCT },
|
||||
{ ".SUNPLUS", TOK_SUNPLUS },
|
||||
{ ".TAG", TOK_TAG },
|
||||
{ ".TCOUNT", TOK_TCOUNT },
|
||||
{ ".TIME", TOK_TIME },
|
||||
|
||||
@ -244,7 +244,6 @@ typedef enum token_t {
|
||||
TOK_STRING,
|
||||
TOK_STRLEN,
|
||||
TOK_STRUCT,
|
||||
TOK_SUNPLUS,
|
||||
TOK_TAG,
|
||||
TOK_TCOUNT,
|
||||
TOK_TIME,
|
||||
|
||||
@ -46,7 +46,7 @@
|
||||
<ClCompile>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -143,7 +143,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_LIB;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_LIB;_DEBUG</PreprocessorDefinitions>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
<Link>
|
||||
@ -161,7 +161,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<FunctionLevelLinking>true</FunctionLevelLinking>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_LIB;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_LIB;NDEBUG</PreprocessorDefinitions>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
<Link>
|
||||
|
||||
@ -58,7 +58,6 @@ const char* CPUNames[CPU_COUNT] = {
|
||||
"65SC02",
|
||||
"65C02",
|
||||
"65816",
|
||||
"sunplus",
|
||||
"sweet16",
|
||||
"huc6280",
|
||||
"m740",
|
||||
@ -72,7 +71,6 @@ const unsigned CPUIsets[CPU_COUNT] = {
|
||||
CPU_ISET_6502 | CPU_ISET_65SC02,
|
||||
CPU_ISET_6502 | CPU_ISET_65SC02 | CPU_ISET_65C02,
|
||||
CPU_ISET_6502 | CPU_ISET_65SC02 | CPU_ISET_65C02 | CPU_ISET_65816,
|
||||
CPU_ISET_SUNPLUS,
|
||||
CPU_ISET_SWEET16,
|
||||
CPU_ISET_6502 | CPU_ISET_65SC02 | CPU_ISET_65C02 | CPU_ISET_HUC6280,
|
||||
CPU_ISET_6502 | CPU_ISET_M740,
|
||||
|
||||
@ -53,7 +53,6 @@ typedef enum {
|
||||
CPU_65SC02,
|
||||
CPU_65C02,
|
||||
CPU_65816,
|
||||
CPU_SUNPLUS, /* Not in the freeware version - sorry */
|
||||
CPU_SWEET16,
|
||||
CPU_HUC6280, /* Used in PC engine */
|
||||
CPU_M740, /* Mitsubishi 740 series MCUs */
|
||||
@ -68,7 +67,6 @@ enum {
|
||||
CPU_ISET_65SC02 = 1 << CPU_65SC02,
|
||||
CPU_ISET_65C02 = 1 << CPU_65C02,
|
||||
CPU_ISET_65816 = 1 << CPU_65816,
|
||||
CPU_ISET_SUNPLUS = 1 << CPU_SUNPLUS,
|
||||
CPU_ISET_SWEET16 = 1 << CPU_SWEET16,
|
||||
CPU_ISET_HUC6280 = 1 << CPU_HUC6280,
|
||||
CPU_ISET_M740 = 1 << CPU_M740,
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -48,7 +48,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -63,7 +63,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
@ -47,7 +47,7 @@
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
@ -62,7 +62,7 @@
|
||||
<WarningLevel>Level3</WarningLevel>
|
||||
<PrecompiledHeader>
|
||||
</PrecompiledHeader>
|
||||
<PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions>
|
||||
<AdditionalIncludeDirectories>common</AdditionalIncludeDirectories>
|
||||
<TreatWarningAsError>true</TreatWarningAsError>
|
||||
</ClCompile>
|
||||
|
||||
0
src/ca65html/ca65html → util/ca65html
Executable file → Normal file
0
src/ca65html/ca65html → util/ca65html
Executable file → Normal file
Loading…
x
Reference in New Issue
Block a user