cc65/doc/apple3.sgml

<!doctype linuxdoc system>

<article>
<title>Apple&nbsp;/// specific information for cc65
<author><url url="https://github.com/robjustice" name="Robert Justice">

<abstract>
An overview over the Apple&nbsp;/// 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;/// runtime system as it
comes with the cc65 C compiler. It describes the memory layout, the
Apple&nbsp;/// specific header files, available drivers, and any pitfalls
specific to that platform.

Please note that Apple&nbsp;/// 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;/// target is an SOS interpreter program file. The linker
prepends a header that identifies the file to the SOS interpreter. This
header has the following layout:

<tscreen><verb>
"SOS NTRP"                      ; Interpreter label
.word $0000                     ; Option header length
.word __MAIN_START__            ; Code start address
.word code length               ; Code length
</verb></tscreen>

The default load address is &dollar;2000. A program is executed by an SOS
interpreter, i.e. it must be launched from a system that is able to run SOS
program files (the SOS interpreter that is part of the SOS disk system on the
Apple&nbsp;/// loads such files at boot time or from the interrupt loop).

The linker configuration sets the default file type of the generated file to
&dollar;000C (an SOS system file). This can be changed at link time, see the
<ref id="link-config" name="linker configuration"> section below.


<sect>Memory layout<p>

In the standard setup, cc65 generated programs use the memory from
&dollar;2000 to &dollar;B7FF, so about 38 KB of RAM are available. The memory
below &dollar;2000 is used by the SOS interpreter and must not be touched.

Special locations:

<descrip>

  <tag/Stack/
  The C runtime stack is located at the top of main memory (&dollar;B7FF) 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>


<sect>Linker configurations<label id="link-config"><p>

The ld65 linker comes with a default config file for the Apple&nbsp;///,
which is used via <tt/-t apple3/. The apple3 package currently doesn't
contain any additional secondary linker config files.


<sect1>Default config file (<tt/apple3.cfg/)<p>

Default configuration for a program to be executed by an SOS interpreter.

Parameters:

<descrip>

  <tag><tt/STARTADDRESS:/ Program start address</tag>
  &dollar;2000. The start address is fixed by the memory layout of the SOS
  interpreter and cannot be changed.

  <tag><tt/__EXEHDR__:/ SOS interpreter header</tag>
  Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the interpreter header.

  <tag><tt/__FILETYPE__:/ SOS file type</tag>
  Default: &dollar;000C (SOS system file). Use <tt/-D __FILETYPE__=&lt;type&gt;/
  to set a different file type.

  <tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
  Default: &dollar;0800. Use <tt/-D __STACKSIZE__=&lt;size&gt;/ to set a
  different stack size.

</descrip><p>


<sect>Platform specific header files<p>

Programs containing Apple&nbsp;/// specific code may use the
<tt/apple3.h/ and <tt/apple3_filetype.h/ header files.


<sect1>Apple&nbsp;/// specific functions<p>

The functions and variables listed below are special for the
Apple&nbsp;///. See the <url url="funcref.html" name="function reference">
for declaration and usage.

<itemize>
<item>_auxtype
<item>_datetime
<item>_filetype
<item>beep
<item>dir_entry_count
<item>dyn_chline
<item>dyn_chlinexy
<item>dyn_cvline
<item>dyn_cvlinexy
<item>file_set_auxtype
<item>file_set_type
<item>getdevicename
<item>rebootafterexit
<item>videomode
<item>waitvsync
<item>xpeek
<item>xpoke
</itemize>


<sect1>File handling<p>

The <tt/apple3_filetype.h/ header is included from <tt/apple3.h/ and defines
many SOS/ProDOS file type constants. See
<ref id="filetypes" name="Specifying file types for fopen"> below for an
example of how to use them.


<sect1>Hardware access<p>

The Apple&nbsp;/// memory is bank switched. The functions <tt/xpeek()/ and
<tt/xpoke()/ allow to access memory in any bank by temporarily setting the
interpreter extended addressing byte. For assembler programs the hardware
register and I/O definitions (VIA ports and timers, keyboard, speaker,
video modes, and so on) are available in the <tt/apple3.inc/ include file.


<sect>Loadable drivers<p>

The names in the parentheses denote the symbols to be used for static linking
of the drivers.


<sect1>Joystick drivers<p>

<descrip>

  <tag><tt/a3.stdjoy.joy (a3_stdjoy_joy)/</tag>
  Supports up to two standard joysticks connected to the game controller
  port. The joystick directions and buttons are read via the SOS
  <tt/GET_ANALOG/ device call.

</descrip><p>


<sect>Standard I/O<p>

The standard I/O streams <tt/stdin/, <tt/stdout/ and <tt/stderr/ are
connected to the console device. Reads from <tt/stdin/ turn the cursor on,
echo each character and convert carriage returns to line feeds. Writes to
<tt/stdout/ and <tt/stderr/ convert line feeds to carriage returns; the
output is written to the console in chunks (single SOS write calls) to speed
up the console output.

The console is initialized to 80 columns by default. The screen size can be
queried with <tt/screensize()/ and changed with <tt/videomode()/.

Up to 16 files may be open at the same time.


<sect>Other hints<p>


<sect1><tt/exec()/<p>

The function <tt/exec()/ terminates the running program and executes another
SOS program file. The executed file must have the SOS file type
(&dollar;000C).


<sect1>DIO<p>

<descrip>

  <tag/Device ID/
  The function <url url="dio.html#s1" name="dio_open()"> has the single
  parameter <tt/device/ to identify the device to be opened. The
  Apple&nbsp;/// assigns a device number to each device present in the
  system. <tt/dio_open()/ fails with <tt/_oserror/ &dollar;28 ("No device
  connected") if the device is invalid or not a block device.

  <tag/Sector size/
  The function <url url="dio.html#s3" name="dio_query_sectsize()"> always
  returns 512 bytes, which is the block size used by SOS.

  <tag/Sector count/
  The function <url url="dio.html#s3" name="dio_query_sectcount()"> returns
  the total number of blocks of the device, as reported by the SOS
  <tt/Get_Device_Info/ call.

</descrip><p>


<sect1>Video modes<p>

The function <tt/videomode()/ allows to switch between the text modes of the
Apple&nbsp;///. The following modes are supported:

<itemize>
<item><tt/VIDEOMODE_40x24/ - 40 columns, black &amp; white
<item><tt/VIDEOMODE_40x24C/ - 40 columns, color
<item><tt/VIDEOMODE_80x24/ - 80 columns, black &amp; white
</itemize>

After a program started the console defaults to 80 columns.


<sect1>Specifying file types for fopen<label id="filetypes"><p>

<descrip>

  <tag>Explanation of File Types</tag>

  SOS associates a file type and an auxiliary type with each file. These
  type specifications are separate from the file's name; the file name's
  suffix (a.k.a. extension) does not specify the file type.
  The SOS function for creating a file requires these types to be specified.

  In contrast, the ISO C function <tt/fopen()/ and the POSIX function
  <tt/open()/ have no parameter to specify either a file type or an
  auxiliary type. Therefore, some additional mechanism for specifying the
  file types is needed.

  <tag>Specifying the File Type and Auxiliary Type</tag>

  There are two global variables provided that allow the file type and
  auxiliary type to be specified before a call to <tt/fopen()/ or
  <tt/open()/. They are defined in <tt/apple3_filetype.h/:

  <tscreen>
  <verb>
  extern unsigned char _filetype;  /* Default: PRODOS_T_BIN */
  extern unsigned int _auxtype;    /* Default: 0            */
  </verb>
  </tscreen>

  The header file <tt/apple3_filetype.h/ also defines many values
  that can be used to set these variables. It is included in
  <tt/apple3.h/.

  <tag>Example</tag>

  A text file cannot be created with just the standard C functions because
  they default to the binary type <tt/PRODOS_T_BIN/. The <tt/_filetype/
  variable must be set to <tt/PRODOS_T_TXT/ to create a text file.

  For a text file, <tt/_auxtype/ specifies the record length. A zero record
  length text file is referred to as a sequential text file. This is
  equivalent to text files on other operating systems, except that the line
  terminator is a carriage return instead of a line-feed (Unix) or carriage
  return, line-feed pair (Windows).

  For this example, the <tt/_auxtype/ does not need to be set because it
  defaults to the desired value, which is zero.

  <tscreen>
  <verb>
    #include <stdio.h>
    #include <string.h>
    #include <errno.h>
    #include <apple3.h>

    void main(void)
    {
        FILE *out;
        char *name = "MY.FAVS";

        /*-----------------------------*/

        _filetype = PRODOS_T_TXT;
        _auxtype  = PRODOS_AUX_T_TXT_SEQ;

        /*-----------------------------*/

        if ((out = fopen(name, "w")) != NULL) {
            fputs("Jorah Mormont\r", out);
            fputs("Brienne of Tarth\r", out);
            if (fclose(out) == EOF) {
                fprintf(stderr, "fclose failed for %s: %s", name, strerror(errno));
            }
        }
        else {
            fprintf(stderr, "fopen failed for %s: %s", name, strerror(errno));
        }
    }
  </verb>
  </tscreen>

</descrip><p>


<sect>Limitations<p>


<sect1>Command line arguments<p>

The Apple&nbsp;/// does not have any command line support. A program started
from an interpreter will always get <tt/argc = 0/ and <tt/argv = NULL/, so
there is not even an <tt/argv[0]/.


<sect1>Direct console I/O<p>

The <tt/textcolor()/ and <tt/bgcolor()/ functions are supported via the SOS
console fore- and background color commands. <tt/bordercolor()/ has no
effect since the Apple&nbsp;/// has no border color. <tt/cpeekcolor()/
always returns white and <tt/cpeekrevers()/ always returns zero.


<sect1>Realtime clock<p>

SOS takes care of setting the file timestamps itself. Therefore the
<tt/_datetime/ variable is not used and there are no functions to read a
realtime clock.


<sect1>Interrupts<p>

There's currently no interrupt/IRQ support for the Apple&nbsp;/// runtime. A
program using an <tt/.INTERRUPTOR/ (see the discussion of the <tt/.CONDES/
feature in the <url url="ca65.html" name="assembler manual">) will fail to
link since no <tt/__CALLIRQ__/ module is provided for this target.


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