6502/cc65
1
0
Fork 0
mirror of https://github.com/cc65/cc65.git synced 2025-04-05 13:37:17 +00:00
Code Issues Projects Releases Wiki Activity

Merge https://github.com/cc65/cc65 into c1p

Browse Source
This commit is contained in:
Stephan Mühlstrasser 2014-11-02 16:17:16 +01:00
commit 0b186407f1
1110 changed files with 69611 additions and 13294 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

@ -1,7 +1,10 @@
/bin/
/emd/
/html/
/info/
/joy/
/lib/
/libwrk/
/mou/
/ser/
/targetutil/

18
.travis.yml
View File

@ -1,2 +1,16 @@
language: c
script: make
language:
- c
install:
- sudo apt-get install linuxdoc-tools linuxdoc-tools-info binutils-mingw-w64-i686 gcc-mingw-w64-i686 sshpass
script:
- make bin USER_CFLAGS=-Werror
- make lib QUIET=1
- make -C src clean
- make bin USER_CFLAGS=-Werror CROSS_COMPILE=i686-w64-mingw32-
- make doc zip
after_success:
- make -f Makefile.travis
env:
global:
- secure: "h+hoQdEHGPLNwaqGKmSaM8NBRDLc2X+W05VsnNG2Feq/wPv/AiBjONNlzN7jRf6D6f3aoPXaQ2Lc3bYWdxGvFRCmwiofdxkJI9n5L8HPHLZ2lf37MQsXmGJzoTFOvjPLj73H6HlbI9Ux0El3zO6hvalxiXj6TfoZ41dbhNyvpYk="
- secure: "A4hMEe5RRfUtYjFGbT7QAvT1Tyo434N+/TiuQeQ4q0L46c79LnXuGQzbFLOFZshZiplLkJr7lFg466CoI1bf2L0cQOew/LesMhE75v0HQ7tZnExWhdpAk0ri6nWixbjn/dmQ0+HxjzJ48A44DMMBYcvSIsO4vflvuJ8etfSg42k="

14
Makefile
View File

@ -1,6 +1,11 @@
all mostlyclean clean:
.PHONY: all mostlyclean clean install zip avail unavail bin lib doc
.SUFFIXES:
all mostlyclean clean install zip:
@$(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 avail unavail bin lib
.SUFFIXES:

37
Makefile.travis Normal file
View File

@ -0,0 +1,37 @@
.PHONY: all gh-pages sf-files
.SUFFIXES:
all: gh-pages sf-files
GH_NAME = Oliver Schmidt
GH_MAIL = ol.sc@web.de
GH_PATH = ../gh-pages
gh-pages:
ifdef GH_TOKEN
@echo 'git clone --branch=gh-pages https://$$(GH_TOKEN)@github.com/cc65/cc65.git $(GH_PATH)'
@git clone --branch=gh-pages https://$(GH_TOKEN)@github.com/cc65/cc65.git $(GH_PATH)
cd $(GH_PATH) && git config user.name "$(GH_NAME)"
cd $(GH_PATH) && git config user.email "$(GH_MAIL)"
cd $(GH_PATH) && git config push.default simple
cd $(GH_PATH) && $(RM) -r doc
cd $(GH_PATH) && mkdir doc
cp html/*.* $(GH_PATH)/doc
cd $(GH_PATH) && git add -A doc
-cd $(GH_PATH) && git commit -m "Updated from commit $(TRAVIS_COMMIT)."
cd $(GH_PATH) && git push
endif
SF_USER = oliverschmidt
SF_HOST = frs.sourceforge.net
SF_FILE = /home/frs/project/cc65/cc65-snapshot-win64.zip
SCPFLAGS = -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -q
sf-files:
ifdef SF_PASS
echo $(TRAVIS_COMMIT) | zip -z cc65
@echo 'sshpass -p $$(SF_PASS) scp $(SCPFLAGS) cc65.zip $(SF_USER)@$(SF_HOST):$(SF_FILE)'
@sshpass -p $(SF_PASS) scp $(SCPFLAGS) cc65.zip $(SF_USER)@$(SF_HOST):$(SF_FILE)
endif

32
README
View File

@ -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.

32
README.md Normal file
View File

@ -0,0 +1,32 @@
[documentation](http://cc65.github.io/cc65/doc)
[wiki](https://github.com/cc65/wiki/wiki)
[![build status](https://travis-ci.org/cc65/cc65.png)](https://travis-ci.org/cc65/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.
- the Atari 5200 console.
- GEOS for the C64, C128 and Apple //e.
- the Nintendo Entertainment System (NES) console.
- 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.

251
asminc/atari.inc
View File

@ -318,7 +318,7 @@ APPMHI = $0E ;APPLICATIONS MEMORY HI LIMIT
INTZBS = $10 ;INTERRUPT HANDLER
POKMSK = $10 ;SYSTEM MASK FOR POKEY IRG ENABLE
POKMSK = $10 ;SYSTEM MASK FOR POKEY IRQ ENABLE (shadow of IRQEN)
BRKKEY = $11 ;BREAK KEY FLAG
RTCLOK = $12 ;REAL TIME CLOCK (IN 16 MSEC UNITS>
BUFADR = $15 ;INDIRECT BUFFER ADDRESS REGISTER
@ -485,10 +485,10 @@ VKEYBD = $0208 ;POKEY KEYBOARD IRQ VECTOR
VSERIN = $020A ;POKEY SERIAL INPUT READY IRQ
VSEROR = $020C ;POKEY SERIAL OUTPUT READY IRQ
VSEROC = $020E ;POKEY SERIAL OUTPUT COMPLETE IRQ
VTIMR1 = $0210 ;POKEY TIMER 1 IRG
VTIMR2 = $0212 ;POKEY TIMER 2 IRG
VTIMR4 = $0214 ;POKEY TIMER 4 IRG
VIMIRQ = $0216 ;IMMEDIATE IRG VECTOR
VTIMR1 = $0210 ;POKEY TIMER 1 IRQ
VTIMR2 = $0212 ;POKEY TIMER 2 IRQ
VTIMR4 = $0214 ;POKEY TIMER 4 IRQ
VIMIRQ = $0216 ;IMMEDIATE IRQ VECTOR
CDTMV1 = $0218 ;COUNT DOWN TIMER 1
CDTMV2 = $021A ;COUNT DOWN TIMER 2
CDTMV3 = $021C ;COUNT DOWN TIMER 3
@ -762,7 +762,15 @@ DOS = $0700
CARTCS = $BFFA ;##rev2## 2-byte cartridge coldstart address
CART = $BFFC ;##rev2## 1-byte cartridge present indicator
;0=Cart Exists
CARTFG = $BFFD ;##rev2## 1-byte cartridge flags
;D7 0=Not a Diagnostic Cart
; 1=Is a Diagnostic cart and control is
; given to cart before any OS is init.
;D2 0=Init but Do not Start Cart
; 1=Init and Start Cart
;D0 0=Do not boot disk
; 1=Boot Disk
CARTAD = $BFFE ;##rev2## 2-byte cartridge start vector
;-------------------------------------------------------------------------
@ -770,83 +778,7 @@ CARTAD = $BFFE ;##rev2## 2-byte cartridge start vector
;-------------------------------------------------------------------------
GTIA = $D000 ;CTIA/GTIA area
; Read/Write Addresses
CONSOL = $D01F ;console switches and speaker control
; Read Addresses
M0PF = $D000 ;missile 0 and playfield collision
M1PF = $D001 ;missile 1 and playfield collision
M2PF = $D002 ;missile 2 and playfield collision
M3PF = $D003 ;missile 3 and playfield collision
P0PF = $D004 ;player 0 and playfield collision
P1PF = $D005 ;player 1 and playfield collision
P2PF = $D006 ;player 2 and playfield collision
P3PF = $D007 ;player 3 and playfield collision
M0PL = $D008 ;missile 0 and player collision
M1PL = $D009 ;missile 1 and player collision
M2PL = $D00A ;missile 2 and player collision
M3PL = $D00B ;missile 3 and player collision
P0PL = $D00C ;player 0 and player collision
P1PL = $D00D ;player 1 and player collision
P2PL = $D00E ;player 2 and player collision
P3PL = $D00F ;player 3 and player collision
TRIG0 = $D010 ;joystick trigger 0
TRIG1 = $D011 ;joystick trigger 1
TRIG2 = $D012 ;cartridge interlock
TRIG3 = $D013 ;ACMI module interlock
PAL = $D014 ;##rev2## PAL/NTSC indicator
; Write Addresses
HPOSP0 = $D000 ;player 0 horizontal position
HPOSP1 = $D001 ;player 1 horizontal position
HPOSP2 = $D002 ;player 2 horizontal position
HPOSP3 = $D003 ;player 3 horizontal position
HPOSM0 = $D004 ;missile 0 horizontal position
HPOSM1 = $D005 ;missile 1 horizontal position
HPOSM2 = $D006 ;missile 2 horizontal position
HPOSM3 = $D007 ;missile 3 horizontal position
SIZEP0 = $D008 ;player 0 size
SIZEP1 = $D009 ;player 1 size
SIZEP2 = $D00A ;player 2 size
SIZEP3 = $D00B ;player 3 size
SIZEM = $D00C ;missile sizes
GRAFP0 = $D00D ;player 0 graphics
GRAFP1 = $D00E ;player 1 graphics
GRAFP2 = $D00F ;player 2 graphics
GRAFP3 = $D010 ;player 3 graphics
GRAFM = $D011 ;missile graphics
COLPM0 = $D012 ;player-missile 0 color/luminance
COLPM1 = $D013 ;player-missile 1 color/luminance
COLPM2 = $D014 ;player-missile 2 color/luminance
COLPM3 = $D015 ;player-missile 3 color/luminance
COLPF0 = $D016 ;playfield 0 color/luminance
COLPF1 = $D017 ;playfield 1 color/luminance
COLPF2 = $D018 ;playfield 2 color/luminance
COLPF3 = $D019 ;playfield 3 color/luminance
COLBK = $D01A ;background color/luminance
PRIOR = $D01B ;priority select
VDELAY = $D01C ;vertical delay
GRACTL = $D01D ;graphic control
HITCLR = $D01E ;collision clear
.include "atari_gtia.inc"
;-------------------------------------------------------------------------
; PBI Address Equates
@ -862,6 +794,20 @@ PDVI = $D1FF ;##rev2## parallel device IRQ status
PDVS = $D1FF ;##rev2## parallel device select
;-------------------------------------------------------------------------
; POKEY Address Equates
;-------------------------------------------------------------------------
POKEY = $D200 ;POKEY area
.include "atari_pokey.inc"
;-------------------------------------------------------------------------
; ANTIC Address Equates
;-------------------------------------------------------------------------
ANTIC = $D400 ;ANTIC area
.include "atari_antic.inc"
; PBI RAM Address Equates
PBIRAM = $D600 ;##rev2## parallel bus interface RAM area
@ -874,52 +820,6 @@ PDIRQV = $D808 ;##rev2## parallel device IRQ vector
PDID2 = $D80B ;##rev2## parallel device ID 2
PDVV = $D80D ;##rev2## parallel device vector table
;-------------------------------------------------------------------------
; POKEY Address Equates
;-------------------------------------------------------------------------
POKEY = $D200 ;POKEY area
; Read Addresses
POT0 = $D200 ;potentiometer 0
POT1 = $D201 ;potentiometer 1
POT2 = $D202 ;potentiometer 2
POT3 = $D203 ;potentiometer 3
POT4 = $D204 ;potentiometer 4
POT5 = $D205 ;potentiometer 5
POT6 = $D206 ;potentiometer 6
POT7 = $D207 ;potentiometer 7
ALLPOT = $D208 ;potentiometer port status
KBCODE = $D209 ;keyboard code
RANDOM = $D20A ;random number generator
SERIN = $D20D ;serial port input
IRQST = $D20E ;IRQ interrupt status
SKSTAT = $D20F ;serial port and keyboard status
; Write Addresses
AUDF1 = $D200 ;channel 1 audio frequency
AUDC1 = $D201 ;channel 1 audio control
AUDF2 = $D202 ;channel 2 audio frequency
AUDC2 = $D203 ;channel 2 audio control
AUDF3 = $D204 ;channel 3 audio frequency
AUDC3 = $D205 ;channel 3 audio control
AUDF4 = $D206 ;channel 4 audio frequency
AUDC4 = $D207 ;channel 4 audio control
AUDCTL = $D208 ;audio control
STIMER = $D209 ;start timers
SKRES = $D20A ;reset SKSTAT status
POTGO = $D20B ;start potentiometer scan sequence
SEROUT = $D20D ;serial port output
IRQEN = $D20E ;IRQ interrupt enable
SKCTL = $D20F ;serial port and keyboard control
;-------------------------------------------------------------------------
; PIA Address Equates
;-------------------------------------------------------------------------
@ -932,33 +832,6 @@ PORTB = $D301 ;port B direction register or memory management
PACTL = $D302 ;port A control
PBCTL = $D303 ;port B control
;-------------------------------------------------------------------------
; ANTIC Address Equates
;-------------------------------------------------------------------------
ANTIC = $D400 ;ANTIC area
; Read Addresses
VCOUNT = $D40B ;vertical line counter
PENH = $D40C ;light pen horizontal position
PENV = $D40D ;light pen vertical position
NMIST = $D40F ;NMI interrupt status
; Write Addresses
DMACTL = $D400 ;DMA control
CHACTL = $D401 ;character control
DLISTL = $D402 ;low display list address
DLISTH = $D403 ;high display list address
HSCROL = $D404 ;horizontal scroll
VSCROL = $D405 ;vertical scroll
PMBASE = $D407 ;player-missile base address
CHBASE = $D409 ;character base address
WSYNC = $D40A ;wait for HBLANK synchronization
NMIEN = $D40E ;NMI enable
NMIRES = $D40F ;NMI interrupt reset
;-------------------------------------------------------------------------
; Floating Point Package Address Equates
;-------------------------------------------------------------------------
@ -1131,74 +1004,6 @@ MYDOS = 3
XDOS = 4
NODOS = 255
;-------------------------------------------------------------------------
; Antic opcodes
;-------------------------------------------------------------------------
; usage example:
;
; ScreenDL:
; .byte DL_BLK8
; .byte DL_BLK8
; .byte DL_CHR40x8x1 + DL_LMS + DL_DLI
; .word ScreenAlignment
; .byte DL_BLK1 + DL_DLI
; .byte DL_MAP320x1x1 + DL_LMS
; .word Screen
;
; .repeat 99
; .byte DL_MAP320x1x1
; .endrepeat
; .byte DL_MAP320x1x1 + DL_LMS
; .word Screen + 40 * 100 ; 100 lines a 40 byte, 'Screen' has to be aligned correctly!
; .repeat 92
; .byte DL_MAP320x1x1
; .endrepeat
;
; .byte DL_JVB
; absolute instructions (non mode lines)
DL_JMP = 1
DL_JVB = 65
DL_BLK1 = 0
DL_BLK2 = 16
DL_BLK3 = 32
DL_BLK4 = 48
DL_BLK5 = 64
DL_BLK6 = 80
DL_BLK7 = 96
DL_BLK8 = 112
; absolute instructions (mode lines)
DL_CHR40x8x1 = 2 ; monochrome, 40 character & 8 scanlines per mode line (GR. 0)
DL_CHR40x10x1 = 3 ; monochrome, 40 character & 10 scanlines per mode line
DL_CHR40x8x4 = 4 ; colour, 40 character & 8 scanlines per mode line (GR. 12)
DL_CHR40x16x4 = 5 ; colour, 40 character & 16 scanlines per mode line (GR. 13)
DL_CHR20x8x2 = 6 ; colour (duochrome per character), 20 character & 8 scanlines per mode line (GR. 1)
DL_CHR20x16x2 = 7 ; colour (duochrome per character), 20 character & 16 scanlines per mode line (GR. 2)
DL_MAP40x8x4 = 8 ; colour, 40 pixel & 8 scanlines per mode line (GR. 3)
DL_MAP80x4x2 = 9 ; 'duochrome', 80 pixel & 4 scanlines per mode line (GR.4)
DL_MAP80x4x4 = 10 ; colour, 80 pixel & 4 scanlines per mode line (GR.5)
DL_MAP160x2x2 = 11 ; 'duochrome', 160 pixel & 2 scanlines per mode line (GR.6)
DL_MAP160x1x2 = 12 ; 'duochrome', 160 pixel & 1 scanline per mode line (GR.14)
DL_MAP160x2x4 = 13 ; 4 colours, 160 pixel & 2 scanlines per mode line (GR.7)
DL_MAP160x1x4 = 14 ; 4 colours, 160 pixel & 1 scanline per mode line (GR.15)
DL_MAP320x1x1 = 15 ; monochrome, 320 pixel & 1 scanline per mode line (GR.8)
; modifiers on mode lines...
DL_HSCROL = 16
DL_VSCROL = 32
DL_LMS = 64
; general modifier...
DL_DLI = 128
;-------------------------------------------------------------------------
; End of atari.inc
;-------------------------------------------------------------------------

116
asminc/atari5200.inc Normal file
View File

@ -0,0 +1,116 @@
;-------------------------------------------------------------------------
; Atari 5200 System Equates
; by Christian Groessler <chris@groessler.org>
; taken from EQUATES.INC from Atari Inc.
;-------------------------------------------------------------------------
;-------------------------------------------------------------------------
; ATASCII CHARACTER DEFS
;-------------------------------------------------------------------------
ATEOL = $9B ;END-OF-LINE, used by CONIO
;-------------------------------------------------------------------------
; Zero Page
;-------------------------------------------------------------------------
POKMSK = $00 ;Mask for Pokey IRQ enable
RTCLOK = $01 ;60 hz. clock
JUMP = $01
CRITIC = $03 ;Critical section
ATRACT = $04 ;Attract Mode
SDLSTL = $05 ;DLISTL Shadow
SDLSTH = $06 ;DLISTH "
SDMCTL = $07 ;DMACTL "
PCOLR0 = $08 ;COLPM0 Shadow
PCOLR1 = $09 ;COLPM1 "
PCOLR2 = $0A ;COLPM2 "
PCOLR3 = $0B ;COLPM3 "
COLOR0 = $0C ;COLPF0 Shadow
COLOR1 = $0D ;COLPF1 "
COLOR2 = $0E ;COLPF2 "
COLOR3 = $0F ;COLPF3 "
COLOR4 = $10 ;COLBK "
PADDL0 = $11 ;POT0 Shadow
PADDL1 = $12 ;POT1 "
PADDL2 = $13 ;POT2 "
PADDL3 = $14 ;POT3 "
PADDL4 = $15 ;POT4 "
PADDL5 = $16 ;POT5 "
PADDL6 = $17 ;POT6 "
PADDL7 = $18 ;POT7 "
; cc65 runtime zero page variables
ROWCRS_5200 = $19
COLCRS_5200 = $1A
SAVMSC = $1B ; pointer to screen memory (conio)
;-------------------------------------------------------------------------
; Page #2
;-------------------------------------------------------------------------
;Interrupt Vectors
VIMIRQ = $0200 ;Immediate IRQ
;Preset $FC03 (SYSIRQ)
VVBLKI = $0202 ;Vblank immediate
;Preset $FCB8 (SYSVBL)
VVBLKD = $0204 ;Vblank deferred
;Preset $FCB2 (XITVBL)
VDSLST = $0206 ;Display List
;Preset $FEA1 (OSDLI)
VKYBDI = $0208 ;Keyboard immediate
;Preset $FD02 (SYSKBD)
VKYBDF = $020A ;Deferred Keyboard
;Preset $FCB2 (XITVBL)
VTRIGR = $020C ;Soft Trigger
VBRKOP = $020E ;BRK Opcode
VSERIN = $0210 ;Serial in Ready
VSEROR = $0212 ;Serial Out Ready
VSEROC = $0214 ;Serial Output complete
VTIMR1 = $0216 ;Pokey Timer 1
VTIMR2 = $0218 ;Pokey Timer 2
VTIMR4 = $021A ;Pokey Timer 4
;-------------------------------------------------------------------------
; CTIA/GTIA Address Equates
;-------------------------------------------------------------------------
GTIA = $C000 ;CTIA/GTIA area
.include "atari_gtia.inc"
;-------------------------------------------------------------------------
; ANTIC Address Equates
;-------------------------------------------------------------------------
ANTIC = $D400 ;ANTIC area
.include "atari_antic.inc"
;-------------------------------------------------------------------------
; POKEY Address Equates
;-------------------------------------------------------------------------
POKEY = $E800 ;POKEY area
.include "atari_pokey.inc"
;-------------------------------------------------------------------------
; Cartridge Parameters
;-------------------------------------------------------------------------
CARTNM = $BFE8 ;Cartridge Name Area
COPYD = $BFFC ;Copyright Decade in Cart
COPYR = $BFFD ;Copyright Year in Cart
; $FF=Diagnostic Cart
GOCART = $BFFE ;Cartridge Start Vector
CHRORG = $F800 ;Character Generator Base

93
asminc/atari_antic.inc Normal file
View File

@ -0,0 +1,93 @@
;-------------------------------------------------------------------------
; ANTIC Address Equates
;-------------------------------------------------------------------------
; Read Addresses
VCOUNT = ANTIC + $0B ;vertical line counter
PENH = ANTIC + $0C ;light pen horizontal position
PENV = ANTIC + $0D ;light pen vertical position
NMIST = ANTIC + $0F ;NMI interrupt status
; Write Addresses
DMACTL = ANTIC + $00 ;DMA control
CHACTL = ANTIC + $01 ;character control
DLISTL = ANTIC + $02 ;low display list address
DLISTH = ANTIC + $03 ;high display list address
HSCROL = ANTIC + $04 ;horizontal scroll
VSCROL = ANTIC + $05 ;vertical scroll
PMBASE = ANTIC + $07 ;player-missile base address
CHBASE = ANTIC + $09 ;character base address
WSYNC = ANTIC + $0A ;wait for HBLANK synchronization
NMIEN = ANTIC + $0E ;NMI enable
NMIRES = ANTIC + $0F ;NMI interrupt reset
;-------------------------------------------------------------------------
; Antic opcodes
;-------------------------------------------------------------------------
; usage example:
;
; ScreenDL:
; .byte DL_BLK8
; .byte DL_BLK8
; .byte DL_CHR40x8x1 + DL_LMS + DL_DLI
; .word ScreenAlignment
; .byte DL_BLK1 + DL_DLI
; .byte DL_MAP320x1x1 + DL_LMS
; .word Screen
;
; .repeat 99
; .byte DL_MAP320x1x1
; .endrepeat
; .byte DL_MAP320x1x1 + DL_LMS
; .word Screen + 40 * 100 ; 100 lines a 40 byte, 'Screen' has to be aligned correctly!
; .repeat 92
; .byte DL_MAP320x1x1
; .endrepeat
;
; .byte DL_JVB
; absolute instructions (non mode lines)
DL_JMP = 1
DL_JVB = 65
DL_BLK1 = 0
DL_BLK2 = 16
DL_BLK3 = 32
DL_BLK4 = 48
DL_BLK5 = 64
DL_BLK6 = 80
DL_BLK7 = 96
DL_BLK8 = 112
; absolute instructions (mode lines)
DL_CHR40x8x1 = 2 ; monochrome, 40 character & 8 scanlines per mode line (GR. 0)
DL_CHR40x10x1 = 3 ; monochrome, 40 character & 10 scanlines per mode line
DL_CHR40x8x4 = 4 ; colour, 40 character & 8 scanlines per mode line (GR. 12)
DL_CHR40x16x4 = 5 ; colour, 40 character & 16 scanlines per mode line (GR. 13)
DL_CHR20x8x2 = 6 ; colour (duochrome per character), 20 character & 8 scanlines per mode line (GR. 1)
DL_CHR20x16x2 = 7 ; colour (duochrome per character), 20 character & 16 scanlines per mode line (GR. 2)
DL_MAP40x8x4 = 8 ; colour, 40 pixel & 8 scanlines per mode line (GR. 3)
DL_MAP80x4x2 = 9 ; 'duochrome', 80 pixel & 4 scanlines per mode line (GR.4)
DL_MAP80x4x4 = 10 ; colour, 80 pixel & 4 scanlines per mode line (GR.5)
DL_MAP160x2x2 = 11 ; 'duochrome', 160 pixel & 2 scanlines per mode line (GR.6)
DL_MAP160x1x2 = 12 ; 'duochrome', 160 pixel & 1 scanline per mode line (GR.14)
DL_MAP160x2x4 = 13 ; 4 colours, 160 pixel & 2 scanlines per mode line (GR.7)
DL_MAP160x1x4 = 14 ; 4 colours, 160 pixel & 1 scanline per mode line (GR.15)
DL_MAP320x1x1 = 15 ; monochrome, 320 pixel & 1 scanline per mode line (GR.8)
; modifiers on mode lines...
DL_HSCROL = 16
DL_VSCROL = 32
DL_LMS = 64
; general modifier...
DL_DLI = 128

81
asminc/atari_gtia.inc Normal file
View File

@ -0,0 +1,81 @@
;-------------------------------------------------------------------------
; CTIA/GTIA Address Equates
;-------------------------------------------------------------------------
; Read/Write Addresses
CONSOL = GTIA + $1F ;console switches and speaker control
; Read Addresses
M0PF = GTIA + $00 ;missile 0 and playfield collision
M1PF = GTIA + $01 ;missile 1 and playfield collision
M2PF = GTIA + $02 ;missile 2 and playfield collision
M3PF = GTIA + $03 ;missile 3 and playfield collision
P0PF = GTIA + $04 ;player 0 and playfield collision
P1PF = GTIA + $05 ;player 1 and playfield collision
P2PF = GTIA + $06 ;player 2 and playfield collision
P3PF = GTIA + $07 ;player 3 and playfield collision
M0PL = GTIA + $08 ;missile 0 and player collision
M1PL = GTIA + $09 ;missile 1 and player collision
M2PL = GTIA + $0A ;missile 2 and player collision
M3PL = GTIA + $0B ;missile 3 and player collision
P0PL = GTIA + $0C ;player 0 and player collision
P1PL = GTIA + $0D ;player 1 and player collision
P2PL = GTIA + $0E ;player 2 and player collision
P3PL = GTIA + $0F ;player 3 and player collision
TRIG0 = GTIA + $10 ;joystick trigger 0
TRIG1 = GTIA + $11 ;joystick trigger 1
TRIG2 = GTIA + $12 ;cartridge interlock
TRIG3 = GTIA + $13 ;ACMI module interlock
PAL = GTIA + $14 ;##rev2## PAL/NTSC indicator
; Write Addresses
HPOSP0 = GTIA + $00 ;player 0 horizontal position
HPOSP1 = GTIA + $01 ;player 1 horizontal position
HPOSP2 = GTIA + $02 ;player 2 horizontal position
HPOSP3 = GTIA + $03 ;player 3 horizontal position
HPOSM0 = GTIA + $04 ;missile 0 horizontal position
HPOSM1 = GTIA + $05 ;missile 1 horizontal position
HPOSM2 = GTIA + $06 ;missile 2 horizontal position
HPOSM3 = GTIA + $07 ;missile 3 horizontal position
SIZEP0 = GTIA + $08 ;player 0 size
SIZEP1 = GTIA + $09 ;player 1 size
SIZEP2 = GTIA + $0A ;player 2 size
SIZEP3 = GTIA + $0B ;player 3 size
SIZEM = GTIA + $0C ;missile sizes
GRAFP0 = GTIA + $0D ;player 0 graphics
GRAFP1 = GTIA + $0E ;player 1 graphics
GRAFP2 = GTIA + $0F ;player 2 graphics
GRAFP3 = GTIA + $10 ;player 3 graphics
GRAFM = GTIA + $11 ;missile graphics
COLPM0 = GTIA + $12 ;player-missile 0 color/luminance
COLPM1 = GTIA + $13 ;player-missile 1 color/luminance
COLPM2 = GTIA + $14 ;player-missile 2 color/luminance
COLPM3 = GTIA + $15 ;player-missile 3 color/luminance
COLPF0 = GTIA + $16 ;playfield 0 color/luminance
COLPF1 = GTIA + $17 ;playfield 1 color/luminance
COLPF2 = GTIA + $18 ;playfield 2 color/luminance
COLPF3 = GTIA + $19 ;playfield 3 color/luminance
COLBK = GTIA + $1A ;background color/luminance
PRIOR = GTIA + $1B ;priority select
VDELAY = GTIA + $1C ;vertical delay
GRACTL = GTIA + $1D ;graphic control
HITCLR = GTIA + $1E ;collision clear

44
asminc/atari_pokey.inc Normal file
View File

@ -0,0 +1,44 @@
;-------------------------------------------------------------------------
; POKEY Address Equates
;-------------------------------------------------------------------------
; Read Addresses
POT0 = POKEY + $00 ;potentiometer 0
POT1 = POKEY + $01 ;potentiometer 1
POT2 = POKEY + $02 ;potentiometer 2
POT3 = POKEY + $03 ;potentiometer 3
POT4 = POKEY + $04 ;potentiometer 4
POT5 = POKEY + $05 ;potentiometer 5
POT6 = POKEY + $06 ;potentiometer 6
POT7 = POKEY + $07 ;potentiometer 7
ALLPOT = POKEY + $08 ;potentiometer port status
KBCODE = POKEY + $09 ;keyboard code
RANDOM = POKEY + $0A ;random number generator
SERIN = POKEY + $0D ;serial port input
IRQST = POKEY + $0E ;IRQ interrupt status
SKSTAT = POKEY + $0F ;serial port and keyboard status
; Write Addresses
AUDF1 = POKEY + $00 ;channel 1 audio frequency
AUDC1 = POKEY + $01 ;channel 1 audio control
AUDF2 = POKEY + $02 ;channel 2 audio frequency
AUDC2 = POKEY + $03 ;channel 2 audio control
AUDF3 = POKEY + $04 ;channel 3 audio frequency
AUDC3 = POKEY + $05 ;channel 3 audio control
AUDF4 = POKEY + $06 ;channel 4 audio frequency
AUDC4 = POKEY + $07 ;channel 4 audio control
AUDCTL = POKEY + $08 ;audio control
STIMER = POKEY + $09 ;start timers
SKRES = POKEY + $0A ;reset SKSTAT status
POTGO = POKEY + $0B ;start potentiometer scan sequence
SEROUT = POKEY + $0D ;serial port output
IRQEN = POKEY + $0E ;IRQ interrupt enable
SKCTL = POKEY + $0F ;serial port and keyboard control

1
asminc/atmos.inc
View File

@ -90,6 +90,7 @@ SCREEN := $BB80
; ---------------------------------------------------------------------------
; ROM entries
GETLINE := $C592
TEXT := $EC21
HIRES := $EC33
CURSET := $F0C8

1
asminc/c128.inc
View File

@ -32,6 +32,7 @@ FETCH := $2A2 ; Fetch subroutine in RAM
FETVEC := $2AA ; Vector patch location for FETCH
STASH := $2AF ; Stash routine in RAM
STAVEC := $2B9 ; Vector patch location for STASH
IRQInd := $2FD ; JMP $0000 -- used as indirect IRQ vector
PALFLAG := $A03 ; $FF=PAL, $00=NTSC
INIT_STATUS := $A04 ; Flags: Reset/Restore initiation status
FKEY_LEN := $1000 ; Function key lengths

4
asminc/cbm510.inc
View File

@ -4,7 +4,7 @@
; Taken from a kernal disassembly done by myself in 2000/2001.
;
; 2001-09-13, Ullrich von Bassewitz
; 2013-08-26, Greg King
; 2014-04-02, Greg King
;-----------------------------------------------------------------------------
@ -14,6 +14,8 @@ ExecReg := $00 ; Controls execution memory bank
IndReg := $01 ; Controls indirect indexed load-store bank
TXTPTR := $85 ; Far pointer into BASIC source code
FNAM := $90 ; Far pointer to LOAD/SAVE file-name
FNAM_LEN := $9D ; Holds length of file-name
; ---------------------------------------------------------------------------
; Screen size

4
asminc/cbm610.inc
View File

@ -4,7 +4,7 @@
; Taken from a kernal disassembly done by myself in 1987.
;
; 1998-09-28, Ullrich von Bassewitz
; 2013-08-26, Greg King
; 2014-04-02, Greg King
; ---------------------------------------------------------------------------
@ -14,6 +14,8 @@ ExecReg := $00 ; Controls execution memory bank
IndReg := $01 ; Controls indirect indexed load-store bank
TXTPTR := $85 ; Far pointer into BASIC source code
FNAM := $90 ; Far pointer to LOAD/SAVE file-name
FNAM_LEN := $9D ; Holds length of file-name
; ---------------------------------------------------------------------------
; Screen size

9
asminc/cpu.mac
View File

@ -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

13
asminc/module.mac Normal file
View File

@ -0,0 +1,13 @@
.ifndef DYN_DRV
DYN_DRV = 1
.endif
.macro module_header module_label
.if DYN_DRV
.segment "HEADER"
.else
.data
.export module_label
module_label:
.endif
.endmacro

16
asminc/mouse-kernel.inc
View File

@ -78,6 +78,10 @@
.byte
CSHOW .addr
.byte
CPREP .addr
.byte
CDRAW .addr
.byte
CMOVEX .addr
.byte
CMOVEY .addr
@ -90,14 +94,16 @@
.struct MOUSE_CALLBACKS
HIDE .addr ; Hide the mouse cursor
SHOW .addr ; Show the mouse cursor
MOVEX .addr ; Move the mouse cursor
MOVEY .addr ; Dito for Y
PREP .addr ; Prepare to move the mouse cursor
DRAW .addr ; Draw the mouse cursor
MOVEX .addr ; Move the mouse cursor to X coord
MOVEY .addr ; Move the mouse cursor to Y coord
.endstruct
;------------------------------------------------------------------------------
; The mouse API version, stored in MOUSE_HDR::VERSION
MOUSE_API_VERSION = $04
MOUSE_API_VERSION = $05
;------------------------------------------------------------------------------
; Bitmapped mouse driver flags, stored in MOUSE_HDR::FLAGS.
@ -169,12 +175,10 @@ MOUSE_BTN_RIGHT = $01
.global mouse_uninstall
.global mouse_hide
.global mouse_show
.global mouse_setbox
.global mouse_setbox
.global mouse_getbox
.global mouse_move
.global mouse_buttons
.global mouse_pos
.global mouse_info
.global mouse_ioctl

1
asminc/ser-error.inc
View File

@ -48,6 +48,7 @@
SER_ERR_INIT_FAILED ; Initialization failed
SER_ERR_INV_IOCTL ; IOCTL not supported
SER_ERR_INSTALLED ; A driver is already installed
SER_ERR_NOT_OPEN ; Driver not open
SER_ERR_COUNT ; Special: Number of error codes
.endenum

1
asminc/ser-kernel.inc
View File

@ -96,6 +96,7 @@ SER_BAUD_115200 = $12
SER_BAUD_230400 = $13
SER_BAUD_31250 = $14
SER_BAUD_62500 = $15
SER_BAUD_56_875 = $16
; Data bit settings
SER_BITS_5 = $00

12
cfg/apple2-asm.cfg
View File

@ -8,13 +8,15 @@ SYMBOLS {
__LOADSIZE__: type = weak, value = __BSS_RUN__ - __CODE_RUN__;
}
MEMORY {
ZP: start = $0080, size = $001A, define = yes;
HEADER: file = %O, start = $0000, size = $0004;
RAM: file = %O, start = %S, size = $C000 - %S;
}
SEGMENTS {
EXEHDR: load = HEADER, type = ro, optional = yes;
CODE: load = RAM, type = rw, optional = yes, define = yes;
RODATA: load = RAM, type = ro, optional = yes;
DATA: load = RAM, type = rw, optional = yes;
BSS: load = RAM, type = bss, optional = yes, define = yes;
ZEROPAGE: load = ZP, type = zp, optional = yes;
EXEHDR: load = HEADER, type = ro, optional = yes;
CODE: load = RAM, type = rw, optional = yes, define = yes;
RODATA: load = RAM, type = ro, optional = yes;
DATA: load = RAM, type = rw, optional = yes;
BSS: load = RAM, type = bss, optional = yes, define = yes;
}

4
cfg/apple2-overlay.cfg
View File

@ -41,13 +41,13 @@ SEGMENTS {
ZEROPAGE: load = ZP, type = zp;
EXEHDR: load = HEADER, type = ro;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro;
LOWCODE: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro;
RODATA: load = RAM, type = ro;
DATA: load = RAM, type = rw;
ZPSAVE: load = RAM, type = bss, define = yes;
BSS: load = RAM, type = bss, define = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes, optional = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
OVERLAY1: load = OVL1, type = ro, define = yes, optional = yes;
OVERLAY2: load = OVL2, type = ro, define = yes, optional = yes;

6
cfg/apple2-system.cfg
View File

@ -17,14 +17,14 @@ MEMORY {
SEGMENTS {
ZEROPAGE: load = ZP, type = zp;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro;
LOWCODE: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro;
RODATA: load = RAM, type = ro;
DATA: load = RAM, type = rw;
ZPSAVE: load = RAM, type = bss, define = yes;
BSS: load = RAM, type = bss, define = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes, optional = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
}
FEATURES {
CONDES: type = constructor,

6
cfg/apple2.cfg
View File

@ -24,14 +24,14 @@ SEGMENTS {
ZEROPAGE: load = ZP, type = zp;
EXEHDR: load = HEADER, type = ro;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro;
LOWCODE: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro;
RODATA: load = RAM, type = ro;
DATA: load = RAM, type = rw;
ZPSAVE: load = RAM, type = bss, define = yes;
BSS: load = RAM, type = bss, define = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes, optional = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
}
FEATURES {
CONDES: type = constructor,

4
cfg/apple2enh-overlay.cfg
View File

@ -41,13 +41,13 @@ SEGMENTS {
ZEROPAGE: load = ZP, type = zp;
EXEHDR: load = HEADER, type = ro;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro;
LOWCODE: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro;
RODATA: load = RAM, type = ro;
DATA: load = RAM, type = rw;
ZPSAVE: load = RAM, type = bss, define = yes;
BSS: load = RAM, type = bss, define = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes, optional = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
OVERLAY1: load = OVL1, type = ro, define = yes, optional = yes;
OVERLAY2: load = OVL2, type = ro, define = yes, optional = yes;

6
cfg/apple2enh-system.cfg
View File

@ -17,14 +17,14 @@ MEMORY {
SEGMENTS {
ZEROPAGE: load = ZP, type = zp;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro;
LOWCODE: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro;
RODATA: load = RAM, type = ro;
DATA: load = RAM, type = rw;
ZPSAVE: load = RAM, type = bss, define = yes;
BSS: load = RAM, type = bss, define = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes, optional = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
}
FEATURES {
CONDES: type = constructor,

6
cfg/apple2enh.cfg
View File

@ -24,14 +24,14 @@ SEGMENTS {
ZEROPAGE: load = ZP, type = zp;
EXEHDR: load = HEADER, type = ro;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro;
LOWCODE: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro;
RODATA: load = RAM, type = ro;
DATA: load = RAM, type = rw;
ZPSAVE: load = RAM, type = bss, define = yes;
BSS: load = RAM, type = bss, define = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
INIT: load = MOVE, run = RAM, type = ro, define = yes, optional = yes;
LC: load = MOVE, run = LC, type = ro, optional = yes;
}
FEATURES {
CONDES: type = constructor,

3
cfg/atari-asm.cfg
View File

@ -24,6 +24,7 @@ SEGMENTS {
RODATA: load = RAM, type = ro optional = yes;
DATA: load = RAM, type = rw optional = yes;
BSS: load = RAM, type = bss, define = yes, optional = yes;
ZEROPAGE: load = ZP, type = zp;
ZEROPAGE: load = ZP, type = zp, optional = yes;
EXTZP: load = ZP, type = zp, optional = yes; # to enable modules to be able to link to C and assembler programs
AUTOSTRT: load = TRAILER, type = ro, optional = yes;
}

44
cfg/atari-cart.cfg Normal file
View File

@ -0,0 +1,44 @@
FEATURES {
STARTADDRESS: default = $2000;
}
SYMBOLS {
__CARTSIZE__: type = weak, value = $2000; # possible values: $2000 and $4000
__CART_HEADER__: type = import;
__STACKSIZE__: type = weak, value = $0800; # 2k stack
__STARTADDRESS__: type = export, value = %S;
__RESERVED_MEMORY__: type = export, value = $0000;
__CARTFLAGS__: type = weak, value = $01; # see documentation for other possible values
}
MEMORY {
ZP: file = "", define = yes, start = $0082, size = $007E;
RAM: file = "", define = yes, start = %S, size = __CARTSIZE__;
ROM: file = %O, define = yes, start = $C000 - __CARTSIZE__, size = __CARTSIZE__ - 6, fill = yes, fillval = $FF;
CARTID: file = %O, start = $BFFA, size = $0006;
}
SEGMENTS {
STARTUP: load = ROM, type = ro, define = yes, optional = yes;
LOWCODE: load = ROM, type = ro, define = yes, optional = yes;
INIT: load = ROM, type = ro, optional = yes;
CODE: load = ROM, type = ro, define = yes;
RODATA: load = ROM, type = ro, optional = yes;
DATA: load = ROM, run = RAM, type = rw, define = yes, optional = yes;
BSS: load = RAM, type = bss, define = yes, optional = yes;
CARTHDR: load = CARTID, type = ro;
ZEROPAGE: load = ZP, type = zp, optional = yes;
EXTZP: load = ZP, type = zp, optional = yes;
}
FEATURES {
CONDES: type = constructor,
label = __CONSTRUCTOR_TABLE__,
count = __CONSTRUCTOR_COUNT__,
segment = INIT;
CONDES: type = destructor,
label = __DESTRUCTOR_TABLE__,
count = __DESTRUCTOR_COUNT__,
segment = RODATA;
CONDES: type = interruptor,
label = __INTERRUPTOR_TABLE__,
count = __INTERRUPTOR_COUNT__,
segment = RODATA,
import = __CALLIRQ__;
}

40
cfg/atari-cassette.cfg Normal file
View File

@ -0,0 +1,40 @@
FEATURES {
STARTADDRESS: default = $0900;
}
SYMBOLS {
__STACKSIZE__: type = weak, value = $0800; # 2k stack
__RESERVED_MEMORY__: type = weak, value = $0000;
__STARTADDRESS__: type = export, value = %S;
_cas_hdr: type = import;
}
MEMORY {
ZP: file = "", define = yes, start = $0082, size = $007E;
RAM: file = %O, define = yes, start = %S, size = $BC20 - __STACKSIZE__ - __RESERVED_MEMORY__ - %S;
}
SEGMENTS {
CASHDR: load = RAM, type = ro;
STARTUP: load = RAM, type = ro, define = yes, optional = yes;
LOWCODE: load = RAM, type = ro, define = yes, optional = yes;
INIT: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro, define = yes;
RODATA: load = RAM, type = ro, optional = yes;
DATA: load = RAM, type = rw, optional = yes;
BSS: load = RAM, type = bss, define = yes, optional = yes;
ZEROPAGE: load = ZP, type = zp, optional = yes;
EXTZP: load = ZP, type = zp, optional = yes;
}
FEATURES {
CONDES: type = constructor,
label = __CONSTRUCTOR_TABLE__,
count = __CONSTRUCTOR_COUNT__,
segment = INIT;
CONDES: type = destructor,
label = __DESTRUCTOR_TABLE__,
count = __DESTRUCTOR_COUNT__,
segment = RODATA;
CONDES: type = interruptor,
label = __INTERRUPTOR_TABLE__,
count = __INTERRUPTOR_COUNT__,
segment = RODATA,
import = __CALLIRQ__;
}

43
cfg/atari5200.cfg Normal file
View File

@ -0,0 +1,43 @@
SYMBOLS {
__CARTSIZE__: type = weak, value = $4000; # possible values: $4000 and $8000
__CART_ENTRY__: type = import;
__STACKSIZE__: type = weak, value = $0400; # 4 pages stack
__RESERVED_MEMORY__: type = export, value = $01E0; # space for 20x24 screen buffer (default display list is in ROM)
}
MEMORY {
ZP: file = "", start = $001D, size = $00E3, define = yes;
RAM: file = "", start = $021C, size = $4000 - __STACKSIZE__ - __RESERVED_MEMORY__ - $021C, define = yes;
ROM: file = %O, start = $C000 - __CARTSIZE__, size = __CARTSIZE__ - $18, define = yes, fill = yes, fillval = $FF;
CARTNAME: file = %O, start = $BFE8, size = $0014 fill = yes, fillval = $40;
CARTYEAR: file = %O, start = $BFFC, size = $0002 fill = yes, fillval = $59;
CARTENTRY: file = %O, start = $BFFE, size = $0002;
}
SEGMENTS {
STARTUP: load = ROM, type = ro, define = yes, optional = yes;
LOWCODE: load = ROM, type = ro, define = yes, optional = yes;
INIT: load = ROM, type = ro, optional = yes;
CODE: load = ROM, type = ro, define = yes;
RODATA: load = ROM, type = ro, optional = yes;
DATA: load = ROM, run = RAM, type = rw, define = yes, optional = yes;
BSS: load = RAM, type = bss, define = yes, optional = yes;
CARTNAME: load = CARTNAME, type = ro, define = yes;
CARTYEAR: load = CARTYEAR, type = ro, define = yes;
CARTENTRY: load = CARTENTRY, type = ro, define = yes;
ZEROPAGE: load = ZP, type = zp, optional = yes;
EXTZP: load = ZP, type = zp, optional = yes;
}
FEATURES {
CONDES: type = constructor,
label = __CONSTRUCTOR_TABLE__,
count = __CONSTRUCTOR_COUNT__,
segment = INIT;
CONDES: type = destructor,
label = __DESTRUCTOR_TABLE__,
count = __DESTRUCTOR_COUNT__,
segment = RODATA;
CONDES: type = interruptor,
label = __INTERRUPTOR_TABLE__,
count = __INTERRUPTOR_COUNT__,
segment = RODATA,
import = __CALLIRQ__;
}

2
cfg/c64-asm.cfg
View File

@ -5,6 +5,7 @@ SYMBOLS {
__LOADADDR__: type = import;
}
MEMORY {
ZP: file = "", start = $0002, size = $001A, define = yes;
LOADADDR: file = %O, start = %S - 2, size = $0002;
RAM: file = %O, start = %S, size = $D000 - %S;
}
@ -15,4 +16,5 @@ SEGMENTS {
RODATA: load = RAM, type = ro, optional = yes;
DATA: load = RAM, type = rw, optional = yes;
BSS: load = RAM, type = bss, optional = yes;
ZEROPAGE: load = ZP, type = zp, optional = yes;
}

2
cfg/lynx-bll.cfg
View File

@ -12,7 +12,7 @@ MEMORY {
SEGMENTS {
BLLHDR: load = HEADER, type = ro;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro, optional = yes;
LOWCODE: load = RAM, type = ro, define = yes, optional = yes;
INIT: load = RAM, type = ro, define = yes, optional = yes;
CODE: load = RAM, type = ro, define = yes;
RODATA: load = RAM, type = ro, define = yes;

2
cfg/lynx-coll.cfg
View File

@ -18,7 +18,7 @@ SEGMENTS {
BOOTLDR: load = BOOT, type = ro;
DIRECTORY: load = DIR, type = ro;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro, optional = yes;
LOWCODE: load = RAM, type = ro, define = yes, optional = yes;
INIT: load = RAM, type = ro, define = yes, optional = yes;
CODE: load = RAM, type = ro, define = yes;
RODATA: load = RAM, type = ro, define = yes;

2
cfg/lynx-uploader.cfg
View File

@ -20,7 +20,7 @@ SEGMENTS {
BOOTLDR: load = BOOT, type = ro;
DIRECTORY:load = DIR, type = ro;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro, optional = yes;
LOWCODE: load = RAM, type = ro, define = yes, optional = yes;
INIT: load = RAM, type = ro, define = yes, optional = yes;
CODE: load = RAM, type = ro, define = yes;
RODATA: load = RAM, type = ro, define = yes;

2
cfg/lynx.cfg
View File

@ -18,7 +18,7 @@ SEGMENTS {
BOOTLDR: load = BOOT, type = ro;
DIRECTORY: load = DIR, type = ro;
STARTUP: load = RAM, type = ro, define = yes;
LOWCODE: load = RAM, type = ro, optional = yes;
LOWCODE: load = RAM, type = ro, define = yes, optional = yes;
INIT: load = RAM, type = ro, define = yes, optional = yes;
CODE: load = RAM, type = ro, define = yes;
RODATA: load = RAM, type = ro, define = yes;

18
cfg/module.cfg
View File

@ -1,16 +1,16 @@
MEMORY {
ZP: file = %O, start = $0000, size = $0100, type = rw, define = yes;
ZP: start = $0000, size = $0100;
COMBINED: file = %O, start = $0000, size = $FFFF;
}
SEGMENTS {
JUMPTABLE: load = COMBINED, type = ro;
INIT: load = COMBINED, type = ro, optional = yes;
CODE: load = COMBINED, type = ro;
RODATA: load = COMBINED, type = ro;
DATA: load = COMBINED, type = rw, define = yes;
BSS: load = COMBINED, type = bss, define = yes;
ZEROPAGE: load = ZP, type = zp;
EXTZP: load = ZP, type = zp, optional = yes;
ZEROPAGE: load = ZP, type = zp;
EXTZP: load = ZP, type = zp, optional = yes;
HEADER: load = COMBINED, type = ro;
INIT: load = COMBINED, type = ro, optional = yes;
CODE: load = COMBINED, type = ro;
RODATA: load = COMBINED, type = ro;
DATA: load = COMBINED, type = rw;
BSS: load = COMBINED, type = bss;
}
FILES {
%O: format = o65;

64
doc/Makefile Normal file
View File

@ -0,0 +1,64 @@
ifneq ($(shell echo),)
CMD_EXE = 1
endif
.PHONY: all mostlyclean clean install zip doc html info gh-pages
.SUFFIXES:
htmldir = $(prefix)/share/doc/cc65$(DESTPACKAGE_SUFFIX)/html
infodir = $(prefix)/share/info
all mostlyclean:
ifdef CMD_EXE
clean install zip doc:
else # CMD_EXE
SGMLS := $(wildcard *.sgml)
../html/coding.html ../html/index.html: \
TOC_LEVEL = 0
TOC_LEVEL = 2
INSTALL = install
clean:
$(RM) -r ../html ../info
install:
$(if $(prefix),,$(error variable `prefix' must be set))
ifeq ($(wildcard ../html),../html)
$(INSTALL) -d $(DESTDIR)$(htmldir)
$(INSTALL) -m644 ../html/*.* $(DESTDIR)$(htmldir)
endif
ifeq ($(wildcard ../info),../info)
$(INSTALL) -d $(DESTDIR)$(infodir)
$(INSTALL) -m644 ../info/*.* $(DESTDIR)$(infodir)
endif
zip:
@cd .. && zip cc65 html/*.*
doc: html info
html: $(addprefix ../html/,$(SGMLS:.sgml=.html) doc.css doc.png)
info: $(addprefix ../info/,$(SGMLS:.sgml=.info))
../html ../info:
@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
../info/%.info: %.sgml | ../info
@cd ../info && linuxdoc -B info ../doc/$<
endif # CMD_EXE

531
doc/apple2.sgml Normal file
View File

@ -0,0 +1,531 @@
<!doctype linuxdoc system>
<article>
<title>Apple&nbsp;&rsqb;&lsqb; specific information for cc65
<author><url url="mailto:ol.sc@web.de" name="Oliver Schmidt">
<date>2014-04-10
<abstract>
An overview over the Apple&nbsp;&rsqb;&lsqb; 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&nbsp;&rsqb;&lsqb; runtime system
as it comes with the cc65 C compiler. It describes the memory layout,
Apple&nbsp;&rsqb;&lsqb; specific header files, available drivers, and any
pitfalls specific to that platform.
Please note that Apple&nbsp;&rsqb;&lsqb; specific functions are just mentioned
here, they are described in detail in the separate <url url="funcref.html"
name="function reference">. Even functions marked as "platform dependent" may
be available on more than one platform. Please see the function reference for
more information.
<sect>Binary format<p>
The standard binary file format generated by the linker for the
Apple&nbsp;&rsqb;&lsqb; 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
&dollar;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 &dollar;2000 so there
is no need for a header. Thus the linker configuration
<ref id="apple-sys-cfg" 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
&dollar;803 to &dollar;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 <ref id="link-configs" name="linker configuration">.
<sect>Linker configurations<label id="link-configs"><p>
The ld65 linker comes with a default config file for the Apple&nbsp;&rsqb;&lsqb;,
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 &lt;configfile&gt;/.
<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 &dollar;D400 to &dollar;DFFF.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;803 to &dollar;95FF (35.5 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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 &dollar;803 to &dollar;95FF (35.5 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D000 to &dollar;FFFF (12 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;803)
<tag><tt/HEADER:/ Binary file header</tag>
DOS 3.3 header (address and length)
</descrip><p>
<sect1><tt/apple2-system.cfg/<label id="apple-sys-cfg"><p>
Configuration for a system program running on ProDOS 8.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;2000 to &dollar;BEFF (39.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Fixed (&dollar;2000)
<tag><tt/HEADER:/ Binary file header</tag>
None
</descrip><p>
<sect1><tt/apple2-loader.cfg/<label id="apple-load-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&nbsp;&rsqb;&lsqb; 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 &dollar;2000. Thus with the default start
address &dollar;800 the main memory area is increased by 6 KB.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;800 to &dollar;BEFF (45.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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&nbsp;&rsqb;&lsqb; 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 &dollar;800 to &dollar;BEFF (45.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D000 to &dollar;DFFF (4 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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 &dollar;2000.
For cc65 programs this means that the 6 KB from &dollar;800 to &dollar;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 &dollar;800 to &dollar;2000 is to link it as binary
(as opposed to system) program using the linker configuration
<ref id="apple-load-cfg" name="apple2-loader.cfg"> with start address
&dollar;803 and load it with the targetutil LOADER.SYSTEM. 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 &lt;program&gt;.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 <ref id="apple-sys-cfg" name="apple2-system.cfg">, but
uses the heap either explicitly or implicitly (i.e. by loading a driver) then
the memory from &dollar;800 to &dollar;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 &dollar;800 and
the program start address for the 1 KB I/O buffers. For system programs (with
start address &dollar;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&nbsp;&rsqb;&lsqb; specific code may use the
<tt/apple2.h/ header file.
<sect1>Apple&nbsp;&rsqb;&lsqb; specific functions<p>
The functions listed below are special for the Apple&nbsp;&rsqb;&lsqb;. See
the <url 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&times;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&times;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 &dollar;803 to &dollar;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&nbsp;&rsqb;&lsqb;.
</descrip><p>
<sect1>Mouse drivers<p>
<descrip>
<tag><tt/a2.stdmou.mou (a2_stdmou_mou)/</tag>
Driver for the AppleMouse&nbsp;II Card. Searches all Apple&nbsp;II slots
for an AppleMouse&nbsp;II Card compatible firmware. The default bounding
box is &lsqb;0..279,0..191&rsqb;.
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&nbsp;&rsqb;&lsqb; (in contrast to an Apple&nbsp;//e) because the
AppleMouse&nbsp;II Card firmware writes to the hires page when initializing
on that machine.
Note that the Apple&nbsp;&rsqb;&lsqb; 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&nbsp;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&nbsp;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&nbsp;&rsqb;&lsqb;
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&nbsp;&rsqb;&lsqb; has no color text mode. Therefore the functions textcolor(),
bgcolor() and bordercolor() have no effect.
<tag/Cursor/
The Apple&nbsp;&rsqb;&lsqb; 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&nbsp;&rsqb;&lsqb; 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 <url
url="ca65.html" name="assembler manual">.
<sect1>DIO<p>
<descrip>
<tag/Drive ID/
The function <url url="dio.html#s1" name="dio_open()"> has the single
parameter <tt/device/ to identify the device to be opened. Therefore an
Apple&nbsp;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 <url url="dio.html#s3" 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>

537
doc/apple2enh.sgml Normal file
View File

@ -0,0 +1,537 @@
<!doctype linuxdoc system>
<article>
<title>Enhanced&nbsp;Apple&nbsp;//e specific information for cc65
<author><url url="mailto:ol.sc@web.de" name="Oliver Schmidt">
<date>2014-04-10
<abstract>
An overview over the enhanced&nbsp;Apple&nbsp;//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&nbsp;Apple&nbsp;//e runtime system
as it comes with the cc65 C compiler. It describes the memory layout,
enhanced&nbsp;Apple&nbsp;//e specific header files, available drivers, and any
pitfalls specific to that platform.
Please note that enhanced&nbsp;Apple&nbsp;//e specific functions are just mentioned
here, they are described in detail in the separate <url url="funcref.html"
name="function reference">. Even functions marked as "platform dependent" may
be available on more than one platform. Please see the function reference for
more information.
<sect>Binary format<p>
The standard binary file format generated by the linker for the
enhanced&nbsp;Apple&nbsp;//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
&dollar;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 &dollar;2000 so there
is no need for a header. Thus the linker configuration
<ref id="apple-sys-cfg" 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
&dollar;803 to &dollar;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 <ref id="link-configs" name="linker configuration">.
<sect>Linker configurations<label id="link-configs"><p>
The ld65 linker comes with a default config file for the enhanced&nbsp;Apple&nbsp;//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 &lt;configfile&gt;/.
<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 &dollar;D400 to &dollar;DFFF.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;803 to &dollar;95FF (35.5 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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 &dollar;803 to &dollar;95FF (35.5 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D000 to &dollar;FFFF (12 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;803)
<tag><tt/HEADER:/ Binary file header</tag>
DOS 3.3 header (address and length)
</descrip><p>
<sect1><tt/apple2enh-system.cfg/<label id="apple-sys-cfg"><p>
Configuration for a system program running on ProDOS 8.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;2000 to &dollar;BEFF (39.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Fixed (&dollar;2000)
<tag><tt/HEADER:/ Binary file header</tag>
None
</descrip><p>
<sect1><tt/apple2enh-loader.cfg/<label id="apple-load-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&nbsp;&rsqb;&lsqb; 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 &dollar;2000. Thus with the default start
address &dollar;800 the main memory area is increased by 6 KB.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;800 to &dollar;BEFF (45.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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&nbsp;&rsqb;&lsqb; 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 &dollar;800 to &dollar;BEFF (45.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D000 to &dollar;DFFF (4 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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 &dollar;2000.
For cc65 programs this means that the 6 KB from &dollar;800 to &dollar;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 &dollar;800 to &dollar;2000 is to link it as binary
(as opposed to system) program using the linker configuration
<ref id="apple-load-cfg" name="apple2enh-loader.cfg"> with start address
&dollar;803 and load it with the targetutil LOADER.SYSTEM. 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 &lt;program&gt;.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 <ref id="apple-sys-cfg" name="apple2enh-system.cfg">, but
uses the heap either explicitly or implicitly (i.e. by loading a driver) then
the memory from &dollar;800 to &dollar;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 &dollar;800 and
the program start address for the 1 KB I/O buffers. For system programs (with
start address &dollar;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&nbsp;Apple&nbsp;//e specific code may use the
<tt/apple2enh.h/ header file.
<sect1>Enhanced&nbsp;Apple&nbsp;//e specific functions<p>
The functions listed below are special for the enhanced&nbsp;Apple&nbsp;//e. See
the <url 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&times;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&times;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 &dollar;803 to &dollar;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&nbsp;Apple&nbsp;//e.
</descrip><p>
<sect1>Mouse drivers<p>
<descrip>
<tag><tt/a2e.stdmou.mou (a2e_stdmou_mou)/</tag>
Driver for the AppleMouse&nbsp;II Card. Searches all Apple&nbsp;II slots
for an AppleMouse&nbsp;II Card compatible firmware. The default bounding
box is &lsqb;0..279,0..191&rsqb;.
Note that the enhanced&nbsp;Apple&nbsp;//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&nbsp;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&nbsp;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&nbsp;Apple&nbsp;//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&nbsp;Apple&nbsp;//e has no color text mode. Therefore the functions
textcolor(), bgcolor() and bordercolor() have no effect.
<tag/Cursor/
The enhanced&nbsp;Apple&nbsp;//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&nbsp;Apple&nbsp;//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 <url
url="ca65.html" name="assembler manual">.
<sect1>DIO<p>
<descrip>
<tag/Drive ID/
The function <url url="dio.html#s1" name="dio_open()"> has the single
parameter <tt/device/ to identify the device to be opened. Therefore an
Apple&nbsp;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 <url url="dio.html#s3" 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
View File

@ -0,0 +1,148 @@
<!doctype linuxdoc system>
<article>
<title>ar65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<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>

1015
doc/atari.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

199
doc/atari5200.sgml Normal file
View File

@ -0,0 +1,199 @@
<!doctype linuxdoc system>
<article>
<title>Atari 5200 specific information for cc65
<author>
<url url="mailto:chris@groessler.org" name="Christian Groessler"><newline>
<date>2014-05-27
<abstract>
An overview over the Atari 5200 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 5200 runtime system as it comes
with the cc65 C compiler. It describes the memory layout, Atari 5200 specific header
files, available drivers, and any pitfalls specific to that platform.
Please note that Atari 5200 specific functions are just mentioned here, they are
described in detail in the separate <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the Atari 5200 target
is a cartridge image. 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 use the RAM space from &dollar;021C to
&dollar;3FFF. If you want to reserve memory for the display list and screen buffer
you should define the __RESERVED_MEMORY__ linker variable. The number
of bytes specified by __RESERVED_MEMORY__ are lowering the top of
memory, therefore the available
RAM memory for the program is &dollar;021C to &dollar;3FFF-__RESERVED_MEMORY__.
The default linker config file sets __RESERVED_MEMORY__ to &dollar;1E0
to reserve space for an optional CONIO text screen.
Special locations:
<descrip>
<tag/Text screen/
The text screen is only enabled if any of the CONIO output functions
is used in the program. Its size is 20x24 characters (Antic mode 6,
BASIC mode 1). The text screen is located at &dollar;3E00. The
address of the screen memory is available at runtime in the variable
SAVMSC (&dollar;001B).<p>
If the program doesn't use any CONIO output functions it needs to setup its own
display list.
<tag/Stack/
The C runtime stack is located at &dollar;3FFF-__RESERVED_MEMORY__ 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 Atari 5200 specific code may use the <tt/atari5200.h/ header file.
<sect1>Atari 5200 specific functions<p>
<itemize>
<item>TBD.
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/atari5200.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.
</descrip><p>
<sect>Loadable drivers<p>
All drivers must be statically linked because no disk 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>
No graphics drivers are currently available for the Atari 5200.
<sect1>Extended memory drivers<p>
No extended memory drivers are available for the Atari 5200.
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/atr5200std.joy (atr5200std_joy)/</tag>
A joystick driver for the standard Atari 5200 joystick is
available. Depending on the version of the 5200 console, two or four joysticks can be attached.
</descrip><p>
<sect1>Mouse drivers<p>
No mouse drivers are available for the Atari 5200.
<sect1>RS232 device drivers<p>
No serial drivers are available for the Atari 5200.
<sect>Limitations<p>
<sect1>Disk I/O<p>
Disk I/O is not supported by the <tt/atari5200/ target. This 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>

259
doc/atmos.sgml Normal file
View File

@ -0,0 +1,259 @@
<!doctype linuxdoc system>
<article>
<title>Oric Atmos-specific information for cc65
<author>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<date>2014-03-27
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the Atmos target
is a machine language program with a 17 byte tape header including a cc65 tag.
The standard load and autostart address is &dollar;500.
<sect>Memory layout<p>
In the standard setup, cc65 generated programs use the memory from
&dollar;500 to &dollar;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 &dollar;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 <url
url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>atmos_load
<item>atmos_save
<item>atmos_explode
<item>atmos_ping
<item>atmos_shoot
<item>atmos_tick
<item>atmos_tock
<item>atmos_zap
</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 &quot;Limitations&quot;">), 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>
The default drivers, <tt/tgi_stddrv (tgi_static_stddrv)/, point to <tt/atmos-240-200-2.tgi (atmos_240_200_2_tgi)/.
<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&times;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&times;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 are hacks for the <tt/read()/ and <tt/write()/ routines in
place, which will make functions work that read from and write to <tt/stdout/
(like <tt/printf()/). However, those functions have some shortcomings which
won't be fixed, because they're going to be replaced anyway.
To be more concrete, the 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 that is not
supported directly 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 <url url="ca65.html" name="assembler manual">.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
<enum>
<item> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
<item> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.
<item> This notice may not be removed or altered from any source
distribution.
</enum>
</article>

359
doc/c128.sgml Normal file
View File

@ -0,0 +1,359 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 128-specific information for cc65
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2014-04-12
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the 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 &dollar;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 &dollar;1C00 - &dollar;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 &dollar;400 (as in the standard setup).
<tag/Stack/
The C runtime stack is located at &dollar;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 <url
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 <url 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 &dollar;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>
The default drivers, <tt/tgi_stddrv (tgi_static_stddrv)/, point to <tt/c128-vdc.tgi (c128_vdc_tgi)/.
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 the 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>
The default drivers, <tt/joy_stddrv (joy_static_stddrv)/, point to <tt/c128-stdjoy.joy (c128_stdjoy_joy)/.
<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 Uz. See <url
url="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 ports of
the C128.
</descrip><p>
<sect1>Mouse drivers<p>
The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c128-1351.mou (c128_1351_mou)/.
<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 BPS, 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
&dollar;C00 and &dollar;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 directly by BASIC, the following syntax was chosen:
<tscreen><verb>
RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
<item>Arguments are separated by spaces.
<item>Arguments may be quoted.
<item>Leading and trailing spaces around an argument are ignored. Spaces within
a quoted argument are allowed.
<item>The first argument passed to <tt/main()/ is the program name.
<item>A maximum number of 10 arguments (including the program name) are
supported.
</enum>
<sect1>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupts<p>
The 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 <url url="ca65.html" name="assembler manual">.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
<enum>
<item> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
<item> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.
<item> This notice may not be removed or altered from any source
distribution.
</enum>
</article>

264
doc/c16.sgml Normal file
View File

@ -0,0 +1,264 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 16/116 specific information for cc65
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2014-04-10
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
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 <url
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 &dollar;1000 - &dollar;4000
(or &dollar;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 &dollar;C00 (as in the standard setup).
<tag/Color RAM/
The color RAM is located at &dollar;800 (standard location).
<tag/Stack/
The C runtime stack is located at &dollar;3FFF (&dollar;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 <url 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 &dollar;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 <url url="ca65.html" name="assembler manual">.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
<enum>
<item> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
<item> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.
<item> This notice may not be removed or altered from any source
distribution.
</enum>
</article>

406
doc/c64.sgml Normal file
View File

@ -0,0 +1,406 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 64-specific information for cc65
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2014-04-14
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the 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
&dollar;0800 - &dollar;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 &dollar;400 (as in the standard setup).
<tag/Stack/
The C runtime stack is located at &dollar;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&nbsp;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 &lt;configfile&gt;/.
<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 &dollar;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 &dollar;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 <url
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 <url 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 &dollar;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>
The default drivers, <tt/joy_stddrv (joy_static_stddrv)/, point to <tt/c64-stdjoy.joy (c64_stdjoy_joy)/.
<descrip>
<tag><tt/c64-hitjoy.joy (c64_hitjoy_joy)/</tag>
Driver for the Digital Excess &amp; Hitmen adapter contributed by Groepaz.
See <url url="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
<url url="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>
The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c64-1351.mou (c64_1351_mou)/.
<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 BPS, 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 the <tt/[/ key.
<sect1>Passing arguments to the program<p>
Command-line arguments can be passed to <tt/main()/. Since this is not
supported directly by BASIC, the following syntax was chosen:
<tscreen><verb>
RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
<item>Arguments are separated by spaces.
<item>Arguments may be quoted.
<item>Leading and trailing spaces around an argument are ignored. Spaces within
a quoted argument are allowed.
<item>The first argument passed to <tt/main()/ is the program name.
<item>A maximum number of 10 arguments (including the program name) are
supported.
</enum>
<sect1>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupts<p>
The 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 <url url="ca65.html" name="assembler manual">.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
<enum>
<item> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
<item> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.
<item> This notice may not be removed or altered from any source
distribution.
</enum>
</article>

4753
doc/ca65.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

328
doc/cbm510.sgml Normal file
View File

@ -0,0 +1,328 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 510 (aka P500) specific information for cc65
<author>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<date>2014-04-25
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
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. That means that a
program can be loaded as a BASIC program, and started with RUN. It is, of course,
possible to change that behaviour by using a modified 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
&dollar;0002 and &dollar;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 &dollar;FF81.
The main startup code is located at &dollar;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 &dollar;FF81, and grows 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 <url
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 <url 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.
<em/Note:/ 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 these variables. 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 ports of
the Commodore 510.
</descrip><p>
<sect1>Mouse drivers<p>
The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/cbm510-joy.mou (cbm510_joy_mou)/.
<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 BPS, 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&micro;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 arguments can be passed to <tt/main()/. Since that is not
supported directly by BASIC, the following syntax was chosen:
<tscreen><verb>
RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
<item>Arguments are separated by spaces.
<item>Arguments may be quoted.
<item>Leading and trailing spaces around an argument are ignored. Spaces within
a quoted argument are allowed.
<item>The first argument passed to <tt/main()/ is the program name.
<item>A maximum number of 10 arguments (including the program name) are
supported.
</enum>
<sect1>Program return code<p>
The program return code (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 <url url="ca65.html" name="assembler manual">.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
<enum>
<item> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
<item> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.
<item> This notice may not be removed or altered from any source
distribution.
</enum>
</article>

310
doc/cbm610.sgml Normal file
View File

@ -0,0 +1,310 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 610-specific information for cc65
<author>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<date>2014-04-25
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
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 built-in 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. That means that a
program can be loaded as a BASIC program, and started with RUN. It is, of course,
possible to change that behaviour by using a modified 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
&dollar;0002 and &dollar;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 &dollar;FF81. The main startup code is located at
&dollar;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 &dollar;FF81, and grows 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 <url
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 <url 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.
<em/Note:/ 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 these variables. 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 BPS, 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&micro;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 arguments can be passed to <tt/main()/. Since that is not
supported directly by BASIC, the following syntax was chosen:
<tscreen><verb>
RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
<item>Arguments are separated by spaces.
<item>Arguments may be quoted.
<item>Leading and trailing spaces around an argument are ignored. Spaces within
a quoted argument are allowed.
<item>The first argument passed to <tt/main()/ is the program name.
<item>A maximum number of 10 arguments (including the program name) are
supported.
</enum>
<sect1>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>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 <url url="ca65.html" name="assembler manual">.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
<enum>
<item> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
<item> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.
<item> This notice may not be removed or altered from any source
distribution.
</enum>
</article>

1393
doc/cc65.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

307
doc/cl65.sgml Normal file
View File

@ -0,0 +1,307 @@
<!doctype linuxdoc system>
<article>
<title>cl65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>01.08.2000, 27.11.2000, 02.10.2001
<abstract>
cl65 is the compile &amp; 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
View File

@ -0,0 +1,344 @@
<!doctype linuxdoc system>
<article>
<title>co65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<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
View File

@ -0,0 +1,308 @@
<!doctype linuxdoc system>
<article>
<title>cc65 coding hints
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<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 &lsqb;&rsqb; 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
View 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&nbsp;=&nbsp;3584&nbsp;=&nbsp;$0E00). The 2K of ROM space begins at
address $F800 and goes to $FFFF (size&nbsp;=&nbsp;$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&nbsp;=&nbsp;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&nbsp;()</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 &quot;sbc.cfg&quot;
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&nbsp;()</tt>.
The following code was used for the crt0 module, defined in the file
&quot;crt0.s&quot;:
<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 &quot;zeropage.inc&quot;
; ---------------------------------------------------------------------------
; Place the startup code in a special segment
.segment &quot;STARTUP&quot;
; ---------------------------------------------------------------------------
; A little light 6502 housekeeping
_init: LDX #$FF ; Initialize stack pointer to $01FF
TXS
CLD ; Clear decimal mode
; ---------------------------------------------------------------------------
; Set cc65 argument stack pointer
LDA #&lt;(__RAM_START__ + __RAM_SIZE__)
STA sp
LDA #&gt;(__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&nbsp;()</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 &quot;STARTUP&quot;
</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&nbsp;()</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 &quot;supervision.lib&quot; 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 &quot;C:\Program Files\cc65\lib\supervision.lib&quot; 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
&quot;interrupt.s&quot;.
<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 &quot;CODE&quot;
.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 &quot;CODE&quot;
</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 &quot;interrupt.s&quot; along with
the address for the initialization code in crt0 are defined in a file
named &quot;vectors.s&quot;. Note that these vectors will be placed in
memory in their proper little-endian format as:
<p><tt> $FFFA&nbsp;-&nbsp;$FFFB:</tt> NMI interrupt vector (low byte, high byte)
<p><tt> $FFFC&nbsp;-&nbsp;$FFFD:</tt> Reset vector (low byte, high byte)
<p><tt> $FFFE&nbsp;-&nbsp;$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 &quot;VECTORS&quot;
.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
&quot;wait&quot; 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
&quot;fooled&quot; 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
&quot;wait.s&quot;, 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 &quot;CODE&quot;
.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&nbsp;()</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 &quot;near&quot;
modifier. Similarly, the <tt>_stop</tt> routine can be called from
within the C-level code via a call to <tt>stop&nbsp;()</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 #&lt;(L0001) ; Load A with the high order byte
ldx #&gt;(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 #&lt;(L0001) ; Load A with the high order byte
ldx #&gt;(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
&quot;rs232_tx.s&quot; 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 &quot;CODE&quot;
.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 &quot;Hello
World! &quot; every time a question mark character is received via a
call to the hardware driver <tt>rs232_tx&nbsp;()</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 &quot;main.c&quot;. 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 &amp; 0x01)
#define RX_FIFO_EMPTY (FIFO_STATUS &amp; 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 (&quot;Hello World!&quot;); // Transmit &quot;Hello World!&quot;
} // 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 &quot;a.out&quot;
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
View File

@ -0,0 +1,685 @@
<!doctype linuxdoc system>
<article>
<title>da65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<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 &dollar;), 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
View File

@ -0,0 +1,154 @@
<!doctype linuxdoc system>
<article>
<title>Using emulators with cc65
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2014-04-11
<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:
<url url="http://vice-emu.sourceforge.net/">.
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 (&tilde;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
View File

@ -0,0 +1,134 @@
<!doctype linuxdoc system>
<article>
<title>Diskette Sector I/O Routines
<author><url url="mailto:chris@groessler.org" name="Christian Groessler">
<date>2014-04-10
<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 <url 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
View 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
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 KiB

7486
doc/funcref.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

1659
doc/geos.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

393
doc/grc65.sgml Normal file
View File

@ -0,0 +1,393 @@
<!doctype linuxdoc system>
<article>
<!-- Title information -->
<title>grc65 -- GEOS Resource Compiler
<author>
<url url="mailto:ytm@elysium.pl" name="Maciej 'YTM/Elysium' Witkowiak">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<date>2014-04-24
<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/&lcub;/ and <tt/&rcub;/, 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.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&aacute; -- &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
View 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">

153
doc/index.sgml Normal file
View File

@ -0,0 +1,153 @@
<!doctype linuxdoc system>
<article>
<title>cc65 Documentation Overview
<author><url url="https://github.com/cc65/cc65/">
<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 &amp; 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&uuml;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&nbsp;&rsqb;&lsqb;.
<tag><htmlurl url="apple2enh.html" name="apple2enh.html"></tag>
Topics specific to the enhanced&nbsp;Apple&nbsp;//e.
<tag><htmlurl url="atari.html" name="atari.html"></tag>
Topics specific to the Atari 8-bit machines.
<tag><htmlurl url="atari5200.html" name="atari5200.html"></tag>
Topics specific to the Atari 5200 Game Console.
<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>

528
doc/intro.sgml Normal file
View File

@ -0,0 +1,528 @@
<!doctype linuxdoc system>
<article>
<title>cc65 Compiler Intro
<author>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:cbmnut@hushmail.com" name="CbmNut">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<date>2014-4-24
<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.
<em/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 &amp; 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&nbsp;&rsqb;&lsqb;/enhanced&nbsp;Apple&nbsp;//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&nbsp;&rsqb;&lsqb;, or:
<tscreen><verb>
cl65 -O -t apple2enh hello.c text.s
</verb></tscreen>
for the enhanced&nbsp;Apple&nbsp;//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 "Hello, World!" appear on the same line. Thanks to
<url url="mailto:ol.sc@web.de" name="Oliver Schmidt"> 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&gt;Autoboot image/ or <bf/File&gt;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&gt;Settings/, and
check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari&gt;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.
<em/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 &lt;sys&gt; hello.c text.s
</verb></tscreen>
Substitute the name of a Commodore computer for that <tt/&lt;sys&gt;/:
<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 &lsqb;<tt/xcbm2/&rsqb; emulator).
In the Windows versions of VICE, choose <bf>File&gt;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 &lsqb;tap the 6-key; then, you
should see its icon in the fourth position on the <bf/deskTop/'s directory
notePad&rsqb;. 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 &lsqb;on the right side of the screen&rsqb;.)
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>

1088
doc/ld65.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

240
doc/library.sgml Normal file
View File

@ -0,0 +1,240 @@
<!doctype linuxdoc system>
<article>
<title>cc65 Library Overview
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2014-04-12
<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 <url 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/&lt;ctype.h&gt;/ 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>

352
doc/lynx.sgml Normal file
View File

@ -0,0 +1,352 @@
<!doctype linuxdoc system>
<article>
<title>Atari Lynx specific information for cc65
<author>
<url url="mailto:karri@sipo.fi" name="Karri Kaksonen">,<newline>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2014-04-12
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
<sect>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 &dollar;200 - &dollar;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 &dollar;C037 (or &dollar;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 &dollar;A058 if it is enabled. The
double buffered screens are at &dollar;C038 and &dollar;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&times;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>

189
doc/nes.sgml Normal file
View File

@ -0,0 +1,189 @@
<!doctype linuxdoc system>
<article>
<title>Nintendo Entertainment System specific information for cc65
<author>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">
<date>2014-04-12
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the 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 &dollar;8000 - &dollar;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 &dollar;2000.
<tag/Stack/
The C runtime stack is located at &dollar;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&times;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
View File

@ -0,0 +1,215 @@
<!doctype linuxdoc system>
<article>
<title>od65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2014-04-14
<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>

256
doc/pet.sgml Normal file
View File

@ -0,0 +1,256 @@
<!doctype linuxdoc system>
<article>
<title>Commodore PET-specific information for cc65
<author>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">
<date>2014-04-12
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the 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
&dollar;0400 - &dollar;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 &dollar;8000.
<tag/Stack/
The C runtime stack is located at &dollar;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 <url 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>
The default drivers, <tt/joy_stddrv (joy_static_stddrv)/, point to <tt/pet-stdjoy.joy (pet_stdjoy_joy)/.
<descrip>
<tag><tt/pet-ptvjoy.joy (pet_ptvjoy_joy)/</tag>
Driver for the Protovision 4-player adapter contributed by Groepaz. See
<url url="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 that is not
supported directly by BASIC, the following syntax was chosen:
<tscreen><verb>
RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
<item>Arguments are separated by spaces.
<item>Arguments may be quoted.
<item>Leading and trailing spaces around an argument are ignored. Spaces within
a quoted argument are allowed.
<item>The first argument passed to <tt/main()/ is the program name.
<item>A maximum number of 10 arguments (including the program name) are
supported.
</enum>
<sect1>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupts<p>
The 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 <url 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
View File

@ -0,0 +1,260 @@
<!doctype linuxdoc system>
<article>
<title>Commodore Plus/4 specific information for cc65
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2014-04-12
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
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 <url
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 &dollar;1000 - &dollar;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 &dollar;C00 (as in the standard setup).
<tag/Color RAM/
The color RAM is located at &dollar;800 (standard location).
<tag/Stack/
The C runtime stack is located at &dollar;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 <url 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 &dollar;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 <url url="ca65.html" name="assembler manual">.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
<enum>
<item> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
<item> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.
<item> This notice may not be removed or altered from any source
distribution.
</enum>
</article>

593
doc/smc.sgml Normal file
View File

@ -0,0 +1,593 @@
<!doctype linuxdoc system>
<article>
<title>ca65 Macros for Self Modifying Code
<author>Christian Kr&uuml;ger
<date>2014-04-24
<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.
<descrip>
<tag/The code is from my 'memset()'implementation:/
<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>
<tag/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
View File

@ -0,0 +1,415 @@
<!doctype linuxdoc system> <!-- -*- text-mode -*- -->
<article>
<title>sp65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<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 '&dollar;'. 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/&lt;ident&gt;_COLORS/,
<tt/&lt;ident&gt;_WIDTH/ and <tt/&lt;ident&gt;_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
View File

@ -0,0 +1,170 @@
<!doctype linuxdoc system>
<article>
<title>Watara Supervision specific information for cc65
<author><url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">
<date>2014-04-12
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the Supervision target
is a 2&times;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 &dollar;8000 - &dollar;FFF9.
More ROM may need additional bankswitching code.
Special locations:
<descrip>
<tag/Text screen/
<!-- The text screen is located at VRAM &dollar;4000.-->
No conio support is currently available for the Supervision.
<tag/Stack/
The C runtime stack is located at &dollar;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&times;160 in 4 colors) is
available, but must be statically linked, because no file I/O is available.
See the documentation for the <url 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 <url 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
View File

@ -0,0 +1,156 @@
<!doctype linuxdoc system>
<article>
<title>Using GNU Make with cc65
<author><url url="mailto:ol.sc@web.de" name="Oliver Schmidt">
<date>2014-04-12
<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
<url 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
<url url="http://make.paulandlesley.org/autodep.html#advanced" name="&dquot;Advanced Auto-Dependencies&dquot;">.
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><url name="make.exe" url="http://gnuwin32.sourceforge.net/packages/make.htm">
<item><url name="rm.exe" 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
<url 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 achieved with this
target-specific variable definition:
<tscreen><verb>
foo.o bar.o: CFLAGS += --code-name FOOBAR
</verb></tscreen>
</article>

264
doc/vic20.sgml Normal file
View File

@ -0,0 +1,264 @@
<!doctype linuxdoc system>
<article>
<title>Commodore VIC20 (aka VC20) specific information for cc65
<author>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">
<date>2014-04-12
<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 <url url="funcref.html" name="function
reference">. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the 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 &dollar;A000 - &dollar;BFFF may be used for the heap),
which gives a usable memory range of &dollar;1000 - &dollar;1DFF.
All ROM entry points may be called directly without additional code.
Special locations:
<descrip>
<tag/Text screen/
The text screen is located at &dollar;1E00 (as in the standard setup).
<tag/Stack/
The C runtime stack is located at &dollar;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 <url 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 &dollar;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>
The default drivers, <tt/joy_stddrv (joy_static_stddrv)/, point to <tt/vic20-stdjoy.joy (vic20_stdjoy_joy)/.
<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
<url url="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 the <tt/[/ key.
<sect1>Passing arguments to the program<p>
Command-line arguments can be passed to <tt/main()/. Since that is not
supported directly by BASIC, the following syntax was chosen:
<tscreen><verb>
RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
<item>Arguments are separated by spaces.
<item>Arguments may be quoted.
<item>Leading and trailing spaces around an argument are ignored. Spaces within
a quoted argument are allowed.
<item>The first argument passed to <tt/main()/ is the program name.
<item>A maximum number of 10 arguments (including the program name) are
supported.
</enum>
<sect1>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>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 <url url="ca65.html" name="assembler manual">.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
<enum>
<item> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
<item> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.
<item> This notice may not be removed or altered from any source
distribution.
</enum>
</article>

20
include/6502.h
View File

@ -82,21 +82,21 @@ struct regs {
#define F6502_C 0x01 /* C flag */
/* Function to call any machine language subroutine. All registers in the
* regs structure are passed into the routine and the results are passed
* out. The B flag is ignored on input. The called routine must end with
* an RTS.
*/
** regs structure are passed into the routine and the results are passed
** out. The B flag is ignored on input. The called routine must end with
** an RTS.
*/
void __fastcall__ _sys (struct regs* r);
/* Set and reset the break vector. The given user function is called if
* a break occurs. The values of the registers may be read from the brk_...
* variables. The value in brk_pc will point to the address that contains
* the brk instruction.
* The set_brk function will install an exit handler that will reset the
* vector if the program ends.
*/
** a break occurs. The values of the registers may be read from the brk_...
** variables. The value in brk_pc will point to the address that contains
** the brk instruction.
** The set_brk function will install an exit handler that will reset the
** vector if the program ends.
*/
extern unsigned char brk_a; /* A register value */
extern unsigned char brk_x; /* X register value */

8
include/_6522.h
View File

@ -36,10 +36,10 @@
/* Define a structure with the 6522 register offsets.
* NOTE: The timer registers are not declared as 16 bit registers, because
* the order in which the two 8 bit halves are written is important, and
* the compiler doesn't guarantee any order when writing 16 bit values.
*/
** NOTE: The timer registers are not declared as 16 bit registers, because
** the order in which the two 8 bit halves are written is important, and
** the compiler doesn't guarantee any order when writing 16 bit values.
*/
struct __6522 {
unsigned char prb; /* Port register B */
unsigned char pra; /* Port register A */

6
include/_6525.h
View File

@ -39,9 +39,9 @@
/* Define a structure with the 6525 register offsets. The shadow registers
* (if port C is unused) are currently not implemented, we would need a
* union to do that, however that would introduce an additional name.
*/
** (if port C is unused) are currently not implemented, we would need a
** union to do that, however that would introduce an additional name.
*/
struct __6525 {
unsigned char pra; /* Port register A */
unsigned char prb; /* Port register B */

8
include/_6526.h
View File

@ -39,10 +39,10 @@
/* Define a structure with the 6526 register offsets.
* NOTE: The timer registers are not declared as 16 bit registers, because
* the order in which the two 8 bit halves are written is important, and
* the compiler doesn't guarantee any order when writing 16 bit values.
*/
** NOTE: The timer registers are not declared as 16 bit registers, because
** the order in which the two 8 bit halves are written is important, and
** the compiler doesn't guarantee any order when writing 16 bit values.
*/
struct __6526 {
unsigned char pra; /* Port register A */
unsigned char prb; /* Port register B */

24
include/_heap.h
View File

@ -1,9 +1,9 @@
/*
* _heap.h
*
* Ullrich von Bassewitz, 1998-06-03, 2004-12-19
*
*/
** _heap.h
**
** Ullrich von Bassewitz, 1998-06-03, 2004-12-19
**
*/
@ -12,11 +12,11 @@
/* Structure that preceeds a user block in most cases.
* The aligned_malloc function may generate blocks where the start pointer
* and size are splitted to handle a memory hole that is needed for
* alignment.
*/
/* Structure that preceeds a user block in most cases.
** The aligned_malloc function may generate blocks where the start pointer
** and size are splitted to handle a memory hole that is needed for
** alignment.
*/
struct usedblock {
unsigned size;
struct usedblock* start;
@ -26,8 +26,8 @@ struct usedblock {
#define HEAP_ADMIN_SPACE sizeof (struct usedblock)
/* The data type used to implement the free list.
* Beware: Field order is significant!
*/
** Beware: Field order is significant!
*/
struct freeblock {
unsigned size;
struct freeblock* next;

4
include/_vic2.h
View File

@ -39,8 +39,8 @@
/* Define a structure with the vic register offsets. In cc65 mode, there
* are aliases for the field accessible as arrays.
*/
** are aliases for the field accessible as arrays.
*/
#if __CC65_STD__ == __CC65_STD_CC65__
struct __vic2 {
union {

54
include/apple2.h
View File

@ -109,23 +109,23 @@
extern unsigned char _dos_type;
/* Valid _dos_type values:
*
* AppleDOS 3.3 - 0x00
* ProDOS 8 1.0.1 - 0x10
* ProDOS 8 1.0.2 - 0x10
* ProDOS 8 1.1.1 - 0x11
* ProDOS 8 1.2 - 0x12
* ProDOS 8 1.3 - 0x13
* ProDOS 8 1.4 - 0x14
* ProDOS 8 1.5 - 0x15
* ProDOS 8 1.6 - 0x16
* ProDOS 8 1.7 - 0x17
* ProDOS 8 1.8 - 0x18
* ProDOS 8 1.9 - 0x18 (!)
* ProDOS 8 2.0.1 - 0x21
* ProDOS 8 2.0.2 - 0x22
* ProDOS 8 2.0.3 - 0x23
*/
**
** AppleDOS 3.3 - 0x00
** ProDOS 8 1.0.1 - 0x10
** ProDOS 8 1.0.2 - 0x10
** ProDOS 8 1.1.1 - 0x11
** ProDOS 8 1.2 - 0x12
** ProDOS 8 1.3 - 0x13
** ProDOS 8 1.4 - 0x14
** ProDOS 8 1.5 - 0x15
** ProDOS 8 1.6 - 0x16
** ProDOS 8 1.7 - 0x17
** ProDOS 8 1.8 - 0x18
** ProDOS 8 1.9 - 0x18 (!)
** ProDOS 8 2.0.1 - 0x21
** ProDOS 8 2.0.2 - 0x22
** ProDOS 8 2.0.3 - 0x23
*/
@ -136,9 +136,9 @@ extern unsigned char _dos_type;
/* The file stream implementation and the POSIX I/O functions will use the
* following variables to determine the file type, aux type and creation time
* stamp to use.
*/
** following variables to determine the file type, aux type and creation time
** stamp to use.
*/
extern unsigned char _filetype; /* Default: 6 */
extern unsigned int _auxtype; /* Default: 0 */
extern struct {
@ -179,18 +179,18 @@ void rebootafterexit (void);
#define ser_apple2_slot(num) ser_ioctl (0, (void*) (num))
/* Select a slot number from 1 to 7 prior to ser_open.
* The default slot number is 2.
*/
** The default slot number is 2.
*/
#define tgi_apple2_mix(onoff) tgi_ioctl (0, (void*) (onoff))
/* If onoff is 1, graphics/text mixed mode is enabled.
* If onoff is 0, graphics/text mixed mode is disabled.
*/
** If onoff is 0, graphics/text mixed mode is disabled.
*/
/* The following #defines will cause the matching functions calls in conio.h
* to be overlaid by macros with the same names, saving the function call
* overhead.
*/
** to be overlaid by macros with the same names, saving the function call
** overhead.
*/
#define _textcolor(color) COLOR_WHITE
#define _bgcolor(color) COLOR_BLACK
#define _bordercolor(color) COLOR_BLACK

8
include/apple2enh.h
View File

@ -109,8 +109,8 @@ extern void a2e_lo_tgi[];
void __fastcall__ textframe (unsigned char width, unsigned char height,
unsigned char style);
/* Output a frame on the text screen with the given width and height
* starting at the current cursor position and using the given style.
*/
** starting at the current cursor position and using the given style.
*/
void __fastcall__ textframexy (unsigned char x, unsigned char y,
unsigned char width, unsigned char height,
@ -119,8 +119,8 @@ void __fastcall__ textframexy (unsigned char x, unsigned char y,
unsigned __fastcall__ videomode (unsigned mode);
/* Set the video mode, return the old mode. Call with one of the VIDEOMODE_xx
* constants.
*/
** constants.
*/

33
include/atari.h
View File

@ -169,9 +169,16 @@ extern char *_getdefdev(void); /* get default floppy device */
/* global variables */
extern unsigned char _dos_type; /* the DOS flavour */
#ifndef __ATARIXL__
extern void atr130_emd[];
extern void atrstd_joy[]; /* referred to by joy_static_stddrv[] */
extern void atrmj8_joy[];
extern void atrjoy_mou[];
extern void atrst_mou[]; /* referred to by mouse_static_stddrv[] */
extern void atrami_mou[];
extern void atrtrk_mou[];
extern void atrtt_mou[];
extern void atrrdev_ser[];
extern void atr3_tgi[];
extern void atr4_tgi[];
extern void atr5_tgi[];
@ -187,6 +194,32 @@ extern void atr11_tgi[];
extern void atr14_tgi[];
extern void atr15_tgi[];
extern void atr15p2_tgi[];
#else
extern void atrx130_emd[];
extern void atrxstd_joy[]; /* referred to by joy_static_stddrv[] */
extern void atrxmj8_joy[];
extern void atrxjoy_mou[];
extern void atrxst_mou[]; /* referred to by mouse_static_stddrv[] */
extern void atrxami_mou[];
extern void atrxtrk_mou[];
extern void atrxtt_mou[];
extern void atrxrdev_ser[];
extern void atrx3_tgi[];
extern void atrx4_tgi[];
extern void atrx5_tgi[];
extern void atrx6_tgi[];
extern void atrx7_tgi[];
extern void atrx8_tgi[]; /* referred to by tgi_static_stddrv[] */
extern void atrx8p2_tgi[];
extern void atrx9_tgi[];
extern void atrx9p2_tgi[];
extern void atrx10_tgi[];
extern void atrx10p2_tgi[];
extern void atrx11_tgi[];
extern void atrx14_tgi[];
extern void atrx15_tgi[];
extern void atrx15p2_tgi[];
#endif
/* provide old names for backwards compatibility */
#ifdef ATARI_COMPAT_PRE_2_11

107
include/atari5200.h Normal file
View File

@ -0,0 +1,107 @@
/*****************************************************************************/
/* */
/* atari5200.h */
/* */
/* Atari 5200 system specific definitions */
/* */
/* */
/* */
/* (C) 2014 Christian Groessler <chris@groessler.org> */
/* */
/* */
/* This software is provided 'as-is', without any expressed or implied */
/* warranty. In no event will the authors be held liable for any damages */
/* arising from the use of this software. */
/* */
/* Permission is granted to anyone to use this software for any purpose, */
/* including commercial applications, and to alter it and redistribute it */
/* freely, subject to the following restrictions: */
/* */
/* 1. The origin of this software must not be misrepresented; you must not */
/* claim that you wrote the original software. If you use this software */
/* in a product, an acknowledgment in the product documentation would be */
/* appreciated but is not required. */
/* 2. Altered source versions must be plainly marked as such, and must not */
/* be misrepresented as being the original software. */
/* 3. This notice may not be removed or altered from any source */
/* distribution. */
/* */
/*****************************************************************************/
#ifndef _ATARI5200_H
#define _ATARI5200_H
/* Check for errors */
#if !defined(__ATARI5200__)
# error This module may only be used when compiling for the Atari 5200!
#endif
/* no support for dynamically loadable drivers */
#define DYN_DRV 0
/* the addresses of the static drivers */
extern void atr5200std_joy[]; /* referred to by joy_static_stddrv[] */
/* make GTIA color value */
#define _gtia_mkcolor(hue,lum) (((hue) << 4) | ((lum) << 1))
/* luminance values go from 0 (black) to 7 (white) */
/* hue values */
#define HUE_GREY 0
#define HUE_GOLD 1
#define HUE_GOLDORANGE 2
#define HUE_REDORANGE 3
#define HUE_ORANGE 4
#define HUE_MAGENTA 5
#define HUE_PURPLE 6
#define HUE_BLUE 7
#define HUE_BLUE2 8
#define HUE_CYAN 9
#define HUE_BLUEGREEN 10
#define HUE_BLUEGREEN2 11
#define HUE_GREEN 12
#define HUE_YELLOWGREEN 13
#define HUE_YELLOW 14
#define HUE_YELLOWRED 15
/* Color defines, similar to c64 colors (untested) */
#define COLOR_BLACK _gtia_mkcolor(HUE_GREY,0)
#define COLOR_WHITE _gtia_mkcolor(HUE_GREY,7)
#define COLOR_RED _gtia_mkcolor(HUE_REDORANGE,1)
#define COLOR_CYAN _gtia_mkcolor(HUE_CYAN,3)
#define COLOR_VIOLET _gtia_mkcolor(HUE_PURPLE,4)
#define COLOR_GREEN _gtia_mkcolor(HUE_GREEN,2)
#define COLOR_BLUE _gtia_mkcolor(HUE_BLUE,2)
#define COLOR_YELLOW _gtia_mkcolor(HUE_YELLOW,7)
#define COLOR_ORANGE _gtia_mkcolor(HUE_ORANGE,5)
#define COLOR_BROWN _gtia_mkcolor(HUE_YELLOW,2)
#define COLOR_LIGHTRED _gtia_mkcolor(HUE_REDORANGE,6)
#define COLOR_GRAY1 _gtia_mkcolor(HUE_GREY,2)
#define COLOR_GRAY2 _gtia_mkcolor(HUE_GREY,3)
#define COLOR_LIGHTGREEN _gtia_mkcolor(HUE_GREEN,6)
#define COLOR_LIGHTBLUE _gtia_mkcolor(HUE_BLUE,6)
#define COLOR_GRAY3 _gtia_mkcolor(HUE_GREY,5)
/* get_tv return values */
#define AT_NTSC 0
#define AT_PAL 1
/* Define hardware */
#include <_gtia.h>
#define GTIA_READ (*(struct __gtia_read*)0xC000)
#define GTIA_WRITE (*(struct __gtia_write*)0xC000)
#include <_pokey.h>
#define POKEY_READ (*(struct __pokey_read*)0xE800)
#define POKEY_WRITE (*(struct __pokey_write*)0xE800)
#include <_antic.h>
#define ANTIC (*(struct __antic*)0xD400)
/* End of atari5200.h */
#endif /* #ifndef _ATARI5200_H */

14
include/c128.h
View File

@ -129,7 +129,7 @@ extern void c128_reu_emd[];
extern void c128_vdc_emd[];
extern void c128_ptvjoy_joy[];
extern void c128_stdjoy_joy[]; /* Referred to by joy_static_stddrv[] */
extern void c128_1351_mous[]; /* Referred to by mouse_static_stddrv[] */
extern void c128_1351_mou[]; /* Referred to by mouse_static_stddrv[] */
extern void c128_joy_mou[];
extern void c128_inkwell_mou[];
extern void c128_pot_mou[];
@ -141,21 +141,21 @@ extern void c128_vdc2_tgi[];
unsigned __fastcall__ videomode (unsigned Mode);
/* Set the video mode, return the old mode. Call with one of the VIDEOMODE_xx
* constants.
*/
** constants.
*/
void toggle_videomode (void);
/* Toggle the video mode between 40 and 80 chars (calls SWAPPER).
* THIS FUNCTION IS DEPRECATED, please use videomode instead!
*/
** THIS FUNCTION IS DEPRECATED, please use videomode instead!
*/
void c64mode (void);
/* Switch the C128 into C64 mode. Note: This function will not return! */
void fast (void);
/* Switch the CPU into 2MHz mode. Note: This will disable video when in
* 40 column mode.
*/
** 40 column mode.
*/
void slow (void);
/* Switch the CPU into 1MHz mode. */

98
include/cbm.h
View File

@ -82,8 +82,8 @@
/* The file stream implementation and the POSIX I/O functions will
* use the following variable to determine the file type to use.
*/
** use the following variable to determine the file type to use.
*/
extern char _filetype; /* Defaults to 's' */
@ -162,10 +162,10 @@ unsigned char get_tv (void);
/* Constants to use with cbm_open() for openning a file for reading or
* writing without the need to append ",r" or ",w" to the filename.
*
* e.g., cbm_open(2, 8, CBM_READ, "0:data,s");
*/
** writing without the need to append ",r" or ",w" to the filename.
**
** e.g., cbm_open(2, 8, CBM_READ, "0:data,s");
*/
#define CBM_READ 0 /* default is ",p" */
#define CBM_WRITE 1 /* ditto */
#define CBM_SEQ 2 /* default is ",r" -- or ",s" when writing */
@ -202,79 +202,79 @@ void cbm_k_unlsn (void);
/* The cbm_* I/O functions below set _oserror (see errno.h),
* in case of an error.
*
* error-code BASIC error
* ---------- -----------
* 1 = too many files
* 2 = file open
* 3 = file not open
* 4 = file not found
* 5 = device not present
* 6 = not input-file
* 7 = not output-file
* 8 = missing file-name
* 9 = illegal device-number
*
* 10 = STOP-key pushed
* 11 = general I/O-error
*/
** in case of an error.
**
** error-code BASIC error
** ---------- -----------
** 1 = too many files
** 2 = file open
** 3 = file not open
** 4 = file not found
** 5 = device not present
** 6 = not input-file
** 7 = not output-file
** 8 = missing file-name
** 9 = illegal device-number
**
** 10 = STOP-key pushed
** 11 = general I/O-error
*/
unsigned int cbm_load (const char* name, unsigned char device, void* data);
/* Loads file "name", from given device, to given address -- or, to the load
* address of the file if "data" is the null pointer (like load"name",8,1
* in BASIC).
* Returns number of bytes that were loaded if loading was successful;
* otherwise 0, "_oserror" contains an error-code, then (see table above).
*/
** address of the file if "data" is the null pointer (like load"name",8,1
** in BASIC).
** Returns number of bytes that were loaded if loading was successful;
** otherwise 0, "_oserror" contains an error-code, then (see table above).
*/
unsigned char __fastcall__ cbm_save (const char* name, unsigned char device,
const void* addr, unsigned int size);
/* Saves "size" bytes, starting at "addr", to a file.
* Returns 0 if saving was successful, otherwise an error-code (see table
* above).
*/
** Returns 0 if saving was successful, otherwise an error-code (see table
** above).
*/
unsigned char __fastcall__ cbm_open (unsigned char lfn, unsigned char device,
unsigned char sec_addr, const char* name);
/* Opens a file. Works just like the BASIC command.
* Returns 0 if openning was successful, otherwise an error-code (see table
* above).
*/
** Returns 0 if openning was successful, otherwise an error-code (see table
** above).
*/
void __fastcall__ cbm_close (unsigned char lfn);
/* Closes a file */
int __fastcall__ cbm_read (unsigned char lfn, void* buffer, unsigned int size);
/* Reads up to "size" bytes from a file into "buffer".
* Returns the number of actually-read bytes, 0 if there are no bytes left.
* -1 in case of an error; then, _oserror contains an error-code (see table
* above). (Remember: 0 means end-of-file; -1 means error.)
*/
** Returns the number of actually-read bytes, 0 if there are no bytes left.
** -1 in case of an error; then, _oserror contains an error-code (see table
** above). (Remember: 0 means end-of-file; -1 means error.)
*/
int __fastcall__ cbm_write (unsigned char lfn, const void* buffer,
unsigned int size);
/* Writes up to "size" bytes from "buffer" to a file.
* Returns the number of actually-written bytes, or -1 in case of an error;
* _oserror contains an error-code, then (see above table).
*/
** Returns the number of actually-written bytes, or -1 in case of an error;
** _oserror contains an error-code, then (see above table).
*/
unsigned char cbm_opendir (unsigned char lfn, unsigned char device, ...);
/* Opens directory listing. Returns 0 if opening directory was successful;
* otherwise, an error-code corresponding to cbm_open(). As an optional
* argument, the name of the directory may be passed to the function. If
* no explicit name is specified, "$" is used.
*/
** otherwise, an error-code corresponding to cbm_open(). As an optional
** argument, the name of the directory may be passed to the function. If
** no explicit name is specified, "$" is used.
*/
unsigned char __fastcall__ cbm_readdir (unsigned char lfn,
struct cbm_dirent* l_dirent);
/* Reads one directory line into cbm_dirent structure.
* Returns 0 if reading directory-line was successful.
* Returns non-zero if reading directory failed, or no more file-names to read.
* Returns 2 on last line. Then, l_dirent->size = the number of "blocks free."
*/
** Returns 0 if reading directory-line was successful.
** Returns non-zero if reading directory failed, or no more file-names to read.
** Returns 2 on last line. Then, l_dirent->size = the number of "blocks free."
*/
void __fastcall__ cbm_closedir (unsigned char lfn);
/* Closes directory by cbm_close(lfn) */

6
include/cbm610.h
View File

@ -138,9 +138,9 @@ void __fastcall__ pokewsys (unsigned addr, unsigned val);
/* The following #defines will cause the matching functions calls in conio.h
* to be overlaid by macros with the same names, saving the function call
* overhead.
*/
** to be overlaid by macros with the same names, saving the function call
** overhead.
*/
#define _textcolor(color) COLOR_WHITE
#define _bgcolor(color) COLOR_BLACK
#define _bordercolor(color) COLOR_BLACK

18
include/cbm_filetype.h
View File

@ -52,9 +52,9 @@
/* CBM FILE TYPES. The definitions are used within standard headers, so we
* be careful with identifiers in the user name space.
* "Regular" files have a special bit set so it's easier to pick them out.
*/
** be careful with identifiers in the user name space.
** "Regular" files have a special bit set so it's easier to pick them out.
*/
#define _CBM_T_REG 0x10U /* Bit set for regular files */
#define _CBM_T_SEQ 0x10U
#define _CBM_T_PRG 0x11U
@ -93,12 +93,12 @@
unsigned char __fastcall__ _cbm_filetype (unsigned char c);
/* Map the start character for a file type to one of the file types above.
* Note: 'd' will always mapped to CBM_T_DEL. The calling function has to
* look at the following character to determine if the file type is actually
* CBM_T_DIR.
* This is a function used by the implementation. There is usually no need
* to call it from user code.
*/
** Note: 'd' will always mapped to CBM_T_DEL. The calling function has to
** look at the following character to determine if the file type is actually
** CBM_T_DIR.
** This is a function used by the implementation. There is usually no need
** to call it from user code.
*/

28
include/cc65.h
View File

@ -46,17 +46,17 @@
long __fastcall__ cc65_idiv32by16r16 (long rhs, int lhs);
/* Divide a 32 bit signed value by a 16 bit signed value yielding a 16
* bit result and a 16 bit remainder. The former is returned in the lower 16
* bit of the result, the latter in the upper. If you don't need the
* remainder, just assign (or cast) to an int.
*/
** bit result and a 16 bit remainder. The former is returned in the lower 16
** bit of the result, the latter in the upper. If you don't need the
** remainder, just assign (or cast) to an int.
*/
unsigned long __fastcall__ cc65_udiv32by16r16 (unsigned long rhs, unsigned lhs);
/* Divide a 32 bit unsigned value by a 16 bit unsigned value yielding a 16
* bit result and a 16 bit remainder. The former is returned in the lower 16
* bit of the result, the latter in the upper. If you don't need the
* remainder, just assign (or cast) to an unsigned.
*/
** bit result and a 16 bit remainder. The former is returned in the lower 16
** bit of the result, the latter in the upper. If you don't need the
** remainder, just assign (or cast) to an unsigned.
*/
int __fastcall__ cc65_imul8x8r16 (signed char lhs, signed char rhs);
/* Multiplicate two signed 8 bit to yield an signed 16 bit result */
@ -69,21 +69,21 @@ unsigned __fastcall__ cc65_umul8x8r16 (unsigned char lhs, unsigned char rhs);
unsigned long __fastcall__ cc65_umul16x8r32 (unsigned lhs, unsigned char rhs);
/* Multiplicate an unsigned 16 bit by an unsigned 8 bit number yielding a 24
* bit unsigned result that is extended to 32 bits for easier handling from C.
*/
** bit unsigned result that is extended to 32 bits for easier handling from C.
*/
unsigned long __fastcall__ cc65_umul16x16r32 (unsigned lhs, unsigned rhs);
/* Multiplicate two unsigned 16 bit to yield an unsigned 32 bit result */
int __fastcall__ cc65_sin (unsigned x);
/* Return the sine of the argument, which must be in range 0..360. The result
* is in 8.8 fixed point format, which means that 1.0 = $100 and -1.0 = $FF00.
*/
** is in 8.8 fixed point format, which means that 1.0 = $100 and -1.0 = $FF00.
*/
int __fastcall__ cc65_cos (unsigned x);
/* Return the cosine of the argument, which must be in range 0..360. The result
* is in 8.8 fixed point format, which means that 1.0 = $100 and -1.0 = $FF00.
*/
** is in 8.8 fixed point format, which means that 1.0 = $100 and -1.0 = $FF00.
*/

64
include/conio.h
View File

@ -34,18 +34,18 @@
/*
* This is the direct console interface for cc65. I do not like the function
* names very much, but the first version started as a rewrite of Borland's
* conio, and, even if the interface has changed, the names did not.
*
* The interface does direct screen I/O, so it is fast enough for most
* programs. I did not implement text windows, since many applications do
* not need them and should not pay for the additional overhead. It should
* be easy to add text windows on a higher level if needed,
*
* Most routines do not check the parameters. This may be unfortunate but is
* also related to speed. The coordinates are always 0/0 based.
*/
** This is the direct console interface for cc65. I do not like the function
** names very much, but the first version started as a rewrite of Borland's
** conio, and, even if the interface has changed, the names did not.
**
** The interface does direct screen I/O, so it is fast enough for most
** programs. I did not implement text windows, since many applications do
** not need them and should not pay for the additional overhead. It should
** be easy to add text windows on a higher level if needed,
**
** Most routines do not check the parameters. This may be unfortunate but is
** also related to speed. The coordinates are always 0/0 based.
*/
@ -128,9 +128,9 @@ int __fastcall__ vcprintf (const char* format, va_list ap);
char cgetc (void);
/* Return a character from the keyboard. If there is no character available,
* the function waits until the user does press a key. If cursor is set to
* 1 (see below), a blinking cursor is displayed while waiting.
*/
** the function waits until the user does press a key. If cursor is set to
** 1 (see below), a blinking cursor is displayed while waiting.
*/
int cscanf (const char* format, ...);
/* Like scanf(), but uses direct keyboard input */
@ -140,14 +140,14 @@ int __fastcall__ vcscanf (const char* format, va_list ap);
unsigned char __fastcall__ cursor (unsigned char onoff);
/* If onoff is 1, a cursor is displayed when waiting for keyboard input. If
* onoff is 0, the cursor is hidden when waiting for keyboard input. The
* function returns the old cursor setting.
*/
** onoff is 0, the cursor is hidden when waiting for keyboard input. The
** function returns the old cursor setting.
*/
unsigned char __fastcall__ revers (unsigned char onoff);
/* Enable/disable reverse character display. This may not be supported by
* the output device. Return the old setting.
*/
** the output device. Return the old setting.
*/
unsigned char __fastcall__ textcolor (unsigned char color);
/* Set the color for text output. The old color setting is returned. */
@ -160,16 +160,16 @@ unsigned char __fastcall__ bordercolor (unsigned char color);
void __fastcall__ chline (unsigned char length);
/* Output a horizontal line with the given length starting at the current
* cursor position.
*/
** cursor position.
*/
void __fastcall__ chlinexy (unsigned char x, unsigned char y, unsigned char length);
/* Same as "gotoxy (x, y); chline (length);" */
void __fastcall__ cvline (unsigned char length);
/* Output a vertical line with the given length at the current cursor
* position.
*/
** position.
*/
void __fastcall__ cvlinexy (unsigned char x, unsigned char y, unsigned char length);
/* Same as "gotoxy (x, y); cvline (length);" */
@ -196,14 +196,14 @@ void __fastcall__ cputhex16 (unsigned val);
/* On some platforms, functions are not available or are dummys. To suppress
* the call to these functions completely, the platform header files may
* define macros for these functions that start with an underline. If such a
* macro exists, a new macro is defined here, that expands to the one with the
* underline. The reason for this two stepped approach is that it is sometimes
* necessary to take the address of the function, which is not possible when
* using a macro. Since the function prototype is still present, #undefining
* the macro will give access to the actual function.
*/
** the call to these functions completely, the platform header files may
** define macros for these functions that start with an underline. If such a
** macro exists, a new macro is defined here, that expands to the one with the
** underline. The reason for this two stepped approach is that it is sometimes
** necessary to take the address of the function, which is not possible when
** using a macro. Since the function prototype is still present, #undefining
** the macro will give access to the actual function.
*/
#if defined(_textcolor)
# define textcolor(x) _textcolor(x)

12
include/ctype.h
View File

@ -85,12 +85,12 @@ unsigned char __fastcall__ toascii (unsigned char c);
/* When inlining-of-known-functions is enabled, overload most of the above
* functions by macroes. The function prototypes are available again after
* #undef'ing the macroes.
* Please note that the following macroes do NOT handle EOF correctly, as
* stated in the manual. If you need correct behaviour for EOF, don't
* use -Os, or #undefine the following macroes.
*/
** functions by macroes. The function prototypes are available again after
** #undef'ing the macroes.
** Please note that the following macroes do NOT handle EOF correctly, as
** stated in the manual. If you need correct behaviour for EOF, don't
** use -Os, or #undefine the following macroes.
*/
#ifdef __OPT_s__
#define isalnum(c) (__AX__ = (c), \

80
include/dbg.h
View File

@ -34,24 +34,24 @@
/*
* This is the interface to the cc65 debugger. Since many of the functions
* used for the debugger are quite usable even in another context, they
* are declared here.
*
* To use the debugger, just call DbgInit in your application. Once it has
* been called, the debugger will catch any BRK opcode. Use the BREAK macro
* defined below to insert breakpoints into your code.
*
* There are currently a lot of things that cannot be debugged, graphical
* applications are an example. The debugger does not save your screen
* contents, so even your text screen gets destroyed. However, you can
* debug the C and runtime library, even if the debugger is using this
* stuff itself.
*
* Note: When using the debugger, there are some other identifiers with
* external linkage, that start with Dbg. Avoid those names if you use the
* module.
*/
** This is the interface to the cc65 debugger. Since many of the functions
** used for the debugger are quite usable even in another context, they
** are declared here.
**
** To use the debugger, just call DbgInit in your application. Once it has
** been called, the debugger will catch any BRK opcode. Use the BREAK macro
** defined below to insert breakpoints into your code.
**
** There are currently a lot of things that cannot be debugged, graphical
** applications are an example. The debugger does not save your screen
** contents, so even your text screen gets destroyed. However, you can
** debug the C and runtime library, even if the debugger is using this
** stuff itself.
**
** Note: When using the debugger, there are some other identifiers with
** external linkage, that start with Dbg. Avoid those names if you use the
** module.
*/
@ -68,35 +68,35 @@
unsigned __fastcall__ DbgDisAsm (unsigned Addr, char* Buf, unsigned char Len);
/* Disassemble one instruction at address addr into the given buffer.
* The resulting line has the format, "AAAA__BB_BB_BB___OPC_OPERAND",
* where AAAA is the hexadecimal representation of addr, BB are the
* bytes (in hex) that make the instruction, OPC is the mnemonic, and
* OPERAND is an operand for the instruction.
* The buffer is filled with spaces up to the given length and terminated as
* a usual C string. NOTE: Buf must be able to hold Len+1 characters.
* The function returns the length of the disassembled instruction, so,
* to disassemble the next instruction, add the return value to addr
* and call the function again.
*/
** The resulting line has the format, "AAAA__BB_BB_BB___OPC_OPERAND",
** where AAAA is the hexadecimal representation of addr, BB are the
** bytes (in hex) that make the instruction, OPC is the mnemonic, and
** OPERAND is an operand for the instruction.
** The buffer is filled with spaces up to the given length and terminated as
** a usual C string. NOTE: Buf must be able to hold Len+1 characters.
** The function returns the length of the disassembled instruction, so,
** to disassemble the next instruction, add the return value to addr
** and call the function again.
*/
unsigned __fastcall__ DbgDisAsmLen (unsigned Addr);
/* Disassemble one instruction, but do only return the length, do not
* create a visible representation. This function is useful when
* disassembling backwards, it is much faster than DbgDisAsm.
*/
** create a visible representation. This function is useful when
** disassembling backwards, it is much faster than DbgDisAsm.
*/
int __fastcall__ DbgIsRAM (unsigned Addr);
/* Return true if we can read and write the given address */
char* DbgMemDump (unsigned Addr, char* Buf, unsigned char Len);
/* Create a line of a memory dump in the given buffer. The buffer contains
* the starting address (4 digits hex), then Len bytes in this format:
* "AAAA__XX_YY_ZZ_...". The passed char buffer must hold Len*3+5 bytes
* plus a terminator byte.
* The function does not work correctly if the created string is longer
* than 255 bytes.
* The return value is Buf.
*/
** the starting address (4 digits hex), then Len bytes in this format:
** "AAAA__XX_YY_ZZ_...". The passed char buffer must hold Len*3+5 bytes
** plus a terminator byte.
** The function does not work correctly if the created string is longer
** than 255 bytes.
** The return value is Buf.
*/
@ -108,8 +108,8 @@ char* DbgMemDump (unsigned Addr, char* Buf, unsigned char Len);
void __fastcall__ DbgInit (unsigned unused);
/* Initialize the debugger. Use 0 as parameter. The debugger will popup on
* next brk encountered.
*/
** next brk encountered.
*/
#define BREAK() __asm__ ("brk")
/* Use this to insert breakpoints into your code */

8
include/dio.h
View File

@ -36,10 +36,10 @@
/* Please note: All functions in this file will set _oserror *and* return its
* value. The only exception is dio_open, which will return NULL, but _oserror
* will be set. All function will also set _oserror in case of successful
* execution, effectively clearing it.
*/
** value. The only exception is dio_open, which will return NULL, but _oserror
** will be set. All function will also set _oserror in case of successful
** execution, effectively clearing it.
*/

48
include/em.h
View File

@ -56,10 +56,10 @@
#define EM_ERR_INSTALLED 5 /* A driver is already installed */
/* Parameters for the em_copy_... functions. NOTE: The first seven bytes
* have the same order and alignment as needed for the Commodore REU, so
* don't change the order without changing the assembler file that defines
* the struct offsets and the code in the REU driver.
*/
** have the same order and alignment as needed for the Commodore REU, so
** don't change the order without changing the assembler file that defines
** the struct offsets and the code in the REU driver.
*/
struct em_copy {
void* buf; /* Memory buffer to copy from or to */
unsigned char offs; /* Offset into page */
@ -87,44 +87,44 @@ unsigned char __fastcall__ em_install (void* driver);
unsigned char em_uninstall (void);
/* Uninstall the currently loaded driver and return an error code.
* Note: This call does not free allocated memory.
*/
** Note: This call does not free allocated memory.
*/
unsigned em_pagecount (void);
/* Return the total number of 256 byte pages available in extended memory. */
void* __fastcall__ em_map (unsigned page);
/* Unmap the current page from memory and map a new one. The function returns
* a pointer to the location of the page in memory. Note: Without calling
* em_commit, the old contents of the memory window may be lost!
*/
** a pointer to the location of the page in memory. Note: Without calling
** em_commit, the old contents of the memory window may be lost!
*/
void* __fastcall__ em_use (unsigned page);
/* Tell the driver that the memory window is associated with a given page.
* This call is very similar to em_map. The difference is that the driver
* does not necessarily transfer the current contents of the extended
* memory into the returned window. If you're going to just write to the
* window and the current contents of the window are invalid or no longer
* use, this call may perform better than em_map.
*/
** This call is very similar to em_map. The difference is that the driver
** does not necessarily transfer the current contents of the extended
** memory into the returned window. If you're going to just write to the
** window and the current contents of the window are invalid or no longer
** use, this call may perform better than em_map.
*/
void em_commit (void);
/* Commit changes in the memory window to extended storage. If the contents
* of the memory window have been changed, these changes may be lost if
* em_map, em_copyfrom or em_copyto are called without calling em_commit
* first. Note: Not calling em_commit does not mean that the changes are
* discarded, it does just mean that some drivers will discard the changes.
*/
** of the memory window have been changed, these changes may be lost if
** em_map, em_copyfrom or em_copyto are called without calling em_commit
** first. Note: Not calling em_commit does not mean that the changes are
** discarded, it does just mean that some drivers will discard the changes.
*/
void __fastcall__ em_copyfrom (const struct em_copy* copy_data);
/* Copy from extended into linear memory. Note: This may invalidate the
* currently mapped page.
*/
** currently mapped page.
*/
void __fastcall__ em_copyto (const struct em_copy* copy_data);
/* Copy from linear into extended memory. Note: This may invalidate the
* currently mapped page.
*/
** currently mapped page.
*/

6
include/em/em-kernel.h
View File

@ -7,7 +7,7 @@
/* */
/* */
/* (C) 2002-2003 Ullrich von Bassewitz */
/* Römerstrasse 52 */
/* Roemerstrasse 52 */
/* D-70794 Filderstadt */
/* EMail: uz@cc65.org */
/* */
@ -45,8 +45,8 @@
/* A structure that describes the header of an extended memory driver loaded
* into memory.
*/
** into memory.
*/
typedef struct {
/* Driver header */

16
include/errno.h
View File

@ -84,23 +84,23 @@ extern int _errno;
int __fastcall__ _osmaperrno (unsigned char oserror);
/* Map an operating system specific error code (for example from _oserror)
* into one of the E... codes above. It is user callable.
*/
** into one of the E... codes above. It is user callable.
*/
unsigned char __fastcall__ _seterrno (unsigned char code);
/* Set errno to a specific error code and return zero. Used by the library */
int __fastcall__ _directerrno (unsigned char code);
/* Set errno to a specific error code, clear _oserror and return -1. Used
* by the library.
*/
** by the library.
*/
int __fastcall__ _mappederrno (unsigned char code);
/* Set _oserror to the given platform specific error code. If it is a real
* error code (not zero) set errno to the corresponding system error code
* and return -1. Otherwise return zero.
* Used by the library.
*/
** error code (not zero) set errno to the corresponding system error code
** and return -1. Otherwise return zero.
** Used by the library.
*/

Some files were not shown because too many files have changed in this diff Show More