contiki-apple2/readme.txt

Contiki on the Apple ][ (Oliver Schmidt)
========================================


Contiki for the Apple ][ comes in two variants:

1. 'Contiki40' runs in 40 column text mode and requires at least an Apple ][+
   with Language Card resulting in 64kB memory.

2. 'Contiki80' runs in 80 column text mode and requires at least an enhanced
   Apple //e with Extended 80 Column Board resulting in 128kB memory.
   
The remainder of this text describes Contiki80.


Installation
------------

1. Get the 'cc65 complete cross development package' from 06/01/2006 or later:
   http://www.cc65.org


2. Build the two targets apple2enh and programsenh.


3. Get the 'a2tools' by Terry Kyriacopoulos:
   ftp://ftp.apple.asimov.net/pub/apple_II/unsorted/a2tools.zip


4. Get the 'Apple][ ProDOS 8 system program for loading binary programs':
   ftp://ftp.musoftware.de/pub/uz/cc65/contrib/loader-1.2.zip


5. Use the 'a2tools' to copy these files into a DOS 3.3 disk image:

   a2tools in b      dos33.dsk CONTIKI.SYSTEM loader~1.sys
   a2tools in -r b   dos33.dsk CONTIKI        contiki
   a2tools in b.0000 dos33.dsk A2E.STDMOU.MOU a2estd~1.mou
   a2tools in b.0000 dos33.dsk ABOUT.PRG      about.prg
   a2tools in b.0000 dos33.dsk ABOUT.DSC      about.dsc
   a2tools in b.0000 dos33.dsk CALC.PRG       calc.prg
   a2tools in b.0000 dos33.dsk CALC.DSC       calc.dsc
   a2tools in b.0000 dos33.dsk CONFIG.PRG     config.prg
   a2tools in b.0000 dos33.dsk CONFIGEDIT.PRG config~1.prg
   a2tools in b.0000 dos33.dsk CONFIGEDIT.DSC config~1.dsc
   a2tools in b.0000 dos33.dsk DHCP.PRG       dhcp.prg
   a2tools in b.0000 dos33.dsk DHCP.DSC       dhcp.dsc
   a2tools in b.0000 dos33.dsk DIRECTORY.PRG  direct~1.prg
   a2tools in b.0000 dos33.dsk DIRECTORY.DSC  direct~1.dsc
   a2tools in b.0000 dos33.dsk EMAIL.PRG      email.prg
   a2tools in b.0000 dos33.dsk EMAIL.DSC      email.dsc
   a2tools in b.0000 dos33.dsk FTP.PRG        ftp.prg
   a2tools in b.0000 dos33.dsk FTP.DSC        ftp.dsc
   a2tools in b.0000 dos33.dsk IRC.PRG        irc.prg
   a2tools in b.0000 dos33.dsk IRC.DSC        irc.dsc
   a2tools in b.0000 dos33.dsk MEMSTAT.PRG    memstat.prg
   a2tools in b.0000 dos33.dsk MEMSTAT.DSC    memstat.dsc
   a2tools in b.0000 dos33.dsk PROCESSES.PRG  proces~1.prg
   a2tools in b.0000 dos33.dsk PROCESSES.DSC  proces~1.dsc
   a2tools in b.0000 dos33.dsk SHELL.PRG      shell.prg
   a2tools in b.0000 dos33.dsk SHELL.DSC      shell.dsc
   a2tools in b.0000 dos33.dsk TELNET.PRG     telnet.prg
   a2tools in b.0000 dos33.dsk TELNET.DSC     telnet.dsc
   a2tools in b.0000 dos33.dsk WEBSERVER.PRG  webser~1.prg
   a2tools in b.0000 dos33.dsk WEBSERVER.DSC  webser~1.dsc
   a2tools in b.0000 dos33.dsk WELCOME.PRG    welcome.prg
   a2tools in b.0000 dos33.dsk WGET.PRG       wget.prg
   a2tools in b.0000 dos33.dsk WGET.DSC       wget.dsc
   a2tools in b.0000 dos33.dsk WWW.PRG        www.prg
   a2tools in b.0000 dos33.dsk WWW.DSC        www.dsc
   a2tools in b.0000 dos33.dsk LANCEGS.DRV    lancegs.drv
   a2tools in b.0000 dos33.dsk LANCEGS.DSC    lancegs.dsc
   a2tools in b.0000 dos33.dsk UTHER.DRV      uther.drv
   a2tools in b.0000 dos33.dsk UTHER.DSC      uther.dsc
   a2tools in b.0000 dos33.dsk BOUNCE.SAV     bounce.sav
   a2tools in b.0000 dos33.dsk BOUNCE.DSC     bounce.dsc
   a2tools in b.0000 dos33.dsk PLASMA.SAV     plasma.sav
   a2tools in b.0000 dos33.dsk PLASMA.DSC     plasma.dsc
   a2tools in b.0000 dos33.dsk SSFIRE.SAV     ssfire.sav
   a2tools in b.0000 dos33.dsk SSFIRE.DSC     ssfire.dsc


6. Use any ProDOS 8 file utility program capable of reading DOS 3.3 files to
   copy the files from the DOS 3.3 disk to a ProDOS 8 disk.


7. Use BASIC.SYSTEM to convert the loader from a BIN to a SYS file:

   BLOAD  CONTIKI.SYSTEM
   DELETE CONTIKI.SYSTEM
   CREATE CONTIKI.SYSTEM,TSYS
   BSAVE  CONTIKI.SYSTEM,TSYS,A$2000,L465


Usage
-----

Select CONTIKI.SYSTEM from the ProDOS 8 dispatcher or use BASIC.SYSTEM:

   - CONTIKI.SYSTEM

1. CONTIKI.SYSTEM supports the ProDOS 8 startup file protocol. The startup file
   will be initially launched instead of WELCOME.PRG.

   The startup file support allows to open *.PRG files from the GS/OS finder:
   
   a) Give your Contiki disk the volume name /CONTIKI
   b) Copy contiki.icon to /CONTIKI/ICONS/CONTIKI.ICON
   c) Set the filetype of CONTIKI.ICON to $CA aka ICN
   d) Set the filetype of the *.PRG files to $FE aka REL
   
2. Contiki includes mouse support for the AppleMouse II Card, the Apple //c and
   the Apple IIgs. All slots are searched for mouse firmware but if non is found
   the mouse support is silently turned off.
   
   IIgs ROM 3 users: Make sure to have set 'Slot 4' in the 'Control Panel' to
                     'Mouse Port' although this isn't necessary for GS/OS.


Implementation Notes
--------------------

1. File I/O

   Contiki loads programs, drivers and screensavers from disk using ProDOS 8.
   The ProDOS 8 file I/O library in the cc65 C-library is to large to be used
   to load WWW.PRG into a 64k Apple ][. Fortunately WWW.PRG itself does no file
   I/O but delegates that to WGET.PRG which is a lot smaller than WWW.PRG. so
   the solution is to have two different file I/O libaries.
   
   The first one is as small as possible and is only capable of reading one file
   at a time and only from the directory CONTIKI resides in. It is part of the
   Contiki kernel and thus called 'KernelFileSystem' (kfs). ProDOS 8 needs a 1kB
   I/O buffer aligned to a page boundary for every opoen file. The one and only
   I/O buffer necessary for fks is placed at $0800-$0BFF and serves as buffer
   for incoming/outgoing IP data as well.
   
   The other one which is called 'ContikiFileSystem' (cfs) is mapped to the
   existing cc65 C-library and linked into the programs (like WGET.PRG).
   
2. Memory Layout

   The Contiki memory layout is based on the standard cc65 layout which means
   that the binary is loaded to the lowest available address ($0C00 here) and
   contains the CODE, RODATA and DATA segments. The BSS segment is located
   directly above those and set to zero programatically. The cc65 stack (not
   to be confused with the 6502 stack at $0100-$01FF) starts at the highest
   available address and grows downwards. The heap is located between the BSS
   and the stack.
   
   But to satisfy the memory requirements of the larger Contiki programs
   several modifications were necessary:
   
   Generally it's very hard to make use of memory mapping for an event driven
   system like Contiki but the Apple //e allows to map only 8kB of Aux memory
   to the address space $2000-$3FFF to facilitate double hires graphics. This
   feature is accompanied by ProDOS 8 which allows to keep /RAM generally active
   while doing double hires graphics by saving a 8kB file as first file to /RAM
   and thus preserving $2000-$3FFF of Aux memory. Contiki makes use of all this
   double hires support while just staying in text mode and using the 8kB as
   additional memory.

   The additional 8kB are used to store the code of the uIP TCP/IP stack. They
   are mapped in both on calls from the Contiki event kernel to the TCP/IP stack
   process (poll and event handler) and calls to the uIP API from programs. Most
   of the time the 8kB are just kept mapped in when the uIP code calls other
   code. This is possible because the only memory not reachable from the uIP
   code are the corresponding 8kB of Main memory - and the Contiki kernel
   objects are linked in an order which makes only CTK code (which is never
   called by uIP code) use that 8kB of Main memory. The only call from uIP code
   that triggers mapping out the 8kB of Aux memory is the uIP upcall into a
   program for processing incoming IP data as some program may potentially call
   CTK code while processing that data.

   Beside that Contiki makes use of the Language Card bank 2 to store the code
   of the C-libary. Most of this 4 kB can be considered free although officially
   marked as reserved by ProDOS 8. Only $D100-$D3FF are actually used to store
   the ProDOS 8 dispatcher. As it is only used after terminating Contiki it can
   be saved to /RAM on startup and restored from there while cleanup.

   The code doing all that code relocation gets overwritten on setting the BSS
   segment to zero. The code doing this (and the C-library initialization) gets
   overwritten later by the heap content.
   
eof