doc/vclib.texi

This chapter describes the C library usually provided with @command{vbcc}.


@section Introduction

To execute code compiled by @command{vbcc}, a library is needed. It
provides basic interfaces to the underlying operating system or
hardware as well as a set of often used functions.

A big part of the library is portable across all architectures. However,
some functions (e.g. for input/output or memory allocation) are
naturally dependent on the operating system or hardware. There are
several sections in this chapter dealing with different versions of
the library.

The library itself often is split into several parts. A startup-code
will do useful initializations, like setting up IO, parsing the command
line or initializing variables and hardware.

The biggest part of the functions will usually be stored in one library file.
The name and format of this file depends on the conventions of the underlying
system (e.g. @file{vc.lib} or @file{libvc.a}).

Often, floating point code (if available) is stored in a different file
(e.g. @file{m.lib} or @file{libm.a}). If floating point is used in an
application, it might be necessary to explicitly link with this library
(e.g. by specifying @file{-lm}).

In many cases, the include files provide special inline-code or similar
optimizations. Therefore, it is recommended to always include the
corresponding include file when using a library function. Even if it
is not necessary in all cases, it may affect the quality of the generated
code.

The library implements the functions specified by ISO9899:1989 as well
as a part of the new functions from ISO9899:1999.

@section Legal

Most parts of this library are public domain. However, for some systems,
parts may be under a different license. Please consult the system
specific documentation. Usually, linking against this library will
not put any restrictions on the created executable unless otherwise
mentioned.

Parts of the math library (e.g. transcendental functions) are derived
from Sun's free math library:
@example
 * ====================================================
 * Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.
 *
 * Developed at SunPro, a Sun Microsystems, Inc. business.
 * Permission to use, copy, modify, and distribute this
 * software is freely granted, provided that this notice 
 * is preserved.
 * ====================================================
@end example

@node SoftfloatHauser
The softfloat functions, used by some targets, are derived from John
Hauser's IEC/IEEE Floating-point Artithmetic Package:

@example
This C source file is part of the SoftFloat IEC/IEEE Floating-point
Arithmetic Package, Release 2.

Written by John R. Hauser.  This work was made possible in part by the
International Computer Science Institute, located at Suite 600, 1947 Center
Street, Berkeley, California 94704.  Funding was partially provided by the
National Science Foundation under grant MIP-9311980.  The original version
of this code was written as part of a project to build a fixed-point vector
processor in collaboration with the University of California at Berkeley,
overseen by Profs. Nelson Morgan and John Wawrzynek.  More information
is available through the web page `http://HTTP.CS.Berkeley.EDU/~jhauser/
arithmetic/softfloat.html'.

THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE.  Although reasonable effort
has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT
TIMES RESULT IN INCORRECT BEHAVIOR.  USE OF THIS SOFTWARE IS RESTRICTED TO
PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY
AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE.

Derivative works are acceptable, even for commercial purposes, so long as
(1) they include prominent notice that the work is derivative, and (2) they
include prominent notice akin to these three paragraphs for those parts of
this code that are retained.
@end example


@section Global Variables

@subsection timezone

On some host operating systems vclib might be unable to determine the
current time zone, which is required for functions like
@code{mktime()} or @code{localtime()} to work. Here you can overwrite
the following variables:

@table @code
@item long __gmtoffset
  Offset in minutes, west of Greenwich Mean Time (GMT).
@item int __dstflag
  Set to non-zero, when Daylight Saving Time is active.
@end table

Targets which can determine their current time zone, will do so by
initializing these variables on startup.


@section Embedded Systems

This section describes specifics of the C library for embedded systems.

@subsection Startup

The startup is usually split into two parts. The first part is done by
assembly code that produces the object file @file{lib/startup.o}. This
assembly code is usually provided with vbcc and may have to be adapted to
the hardware you are using. The key actions that have to be performed by this
code are:

@table @minus
@item hardware initialization
        It may be necessary to perform some hardware initialization right
        at the beginning, e.g. to configure the memory system. This has to
        be modified by the user.

@item variable initializations
        When running code from ROM, some memory sections have to be
        initialized. Usually, the init-values of initialized variables
        have to be copied from ROM to the data segment and the values of
        un-initialized variables have to be cleared in the bss segment.
        This code is usually provided in the startup code.

@item stack pointer
        The stack pointer has to be set to a suitable memory area.
        The startup code
        will set the stack pointer to the value of the pointer @code{__stack}.
        There is a default stack provided in the C library which will be used
        unless the application defines its own stack using, for example, the
        following code (assuming that the stack grows downwards):
@example
#define STACKSIZE <whatever>

static long mystack[STACKSIZE/sizeof(long)];
char *__stack=((char*)mystack)+STACKSIZE;
@end example

@item calling @code{__main}
        After all the above initializations have been performed, the function
        @code{__main()} has to be called. This function is provided by the
        library and performs high-level initializations, if necessary (mainly
        it calls constructors created by the linker) and will then call the
        user @code{main()} function. Note that the library
        may not work correctly if the user @code{main()} function is called
        directly from the startup code.

@end table

@subsection Heap

When dynamic memory management is used (e.g. by using the @code{malloc()}
function), a heap memory area is needed to allocate memory from. The
@code{malloc()} function assumes that @code{__heapptr} is a variable pointing
to the beginning of the heap memory and that @code{__heapsize} specifies
the size of the heap area in bytes. The library will provide a default heap
memory area that can be replaced by adding, for example, the following file
to the application:
@example
#define HEAPSIZE <whatever>

char __heap[HEAPSIZE],*__heapptr=__heap;
size_t __heapsize=HEAPSIZE;
@end example


@subsection Input/Output

The standard C input/output functions are provided also for embedded systems.
Reading/writing to a stream will be directed to void unless the following
low-level I/O-functions are provided by the application:
@example
int __open(const char *name,const char *mode);
void __close(int h);
size_t __read(int h,char *p,size_t l);
size_t __write(int h,const char *p,size_t l);
off_t __seek(int h,off_t offset,int origin);
@end example

The @code{__open()} function receives a name and a mode string (as in the C
@code{fopen()} function) as arguments and has to return a file-descriptor if
it is possible to open this file. The other functions are equivalent to the
corresponding POSIX functions. @code{__seek} can be implemented to return 
@code{-1} if the functionality is not needed.

Also, @code{stdin, stdout} and @code{stderr} can be used with the standard
descriptors.

@subsection CTRL-C Handling

Some targets implement handlers to terminate the program on ctrl-c or a
similar signal. This usually has the same effect as calling
@code{exit(20)}.

If you want to change or disable the ctrl-c handling, you can overwrite
the function @code{void _chkabort(void)}.

@subsection Floating Point

Whether floating point is supported, depends on the target architecture and
chip. If it is supported, there will usually be a math-library that has to
be linked (using option @option{-lm}) when floating point is used.

@subsection Useless Functions

Of course, some of the C library functions can not be implemented reasonably on
embedded systems. These functions are contained in the library but will
always return an error value. Mainly affected are:

@table @minus
@item locale
@item time
@item signal
@item filesystem functions
@end table

Depending on the hardware provided by a system it is possible to implement
these functions and add them to the application. In this case, the new
functions will be used rather than the default ones returning only error
values.

@subsection Linking/Locating

To produce ROM images (e.g. in the form of absolute ELF executables, Intel
Hex files or Motorola S-Records), the linker is called with a linker script.
This script can be used to join together different sections of the input files
and locate them to suitable absolute memory areas. Also, this linker script
can be used to set symbols that may be used by the application or the startup
code, e.g. addresses of data sections, initialization values or small data
pointers.

Code or data that has to reside at special locations can be put into a special
section using the @code{__section} attribute. This section can then be
placed at the desired location using the linker script.

Usually, an example linker script will be provided. While this is often not
suitable for different chips, it may serve as a starting point.


@section AmigaOS/68k

This section describes specifics of the C library for AmigaOS/68k
provided by the target @file{m68k-amigaos}.
The relevant files are @file{startup.o}, @file{minstart.o}, @file{minres.o},
@file{vc.lib}, @file{vcs.lib}, @file{mieee.lib}, @file{mieees.lib},
@file{m881.lib}, @file{m881s.lib}, @file{m040.lib}, @file{m040s.lib},
@file{m060.lib}, @file{m060s.lib}, @file{msoft.lib}, @file{msofts.lib},
@file{amiga.lib}, @file{amigas.lib}, @file{auto.lib} and @file{autos.lib},
@file{reaction.lib}, @file{reactions.lib}.

Note that @file{extra.lib} is no longer part of the vbcc distribution.
It was replaced by 'PosixLib', available on Aminet
@file{dev/c/vbcc_PosixLib.lha}, which has a much more comprehensive
support for POSIX and Unix functions.

The following config files are available:
@table @code
@item aos68k
  Standard startup code (@file{startup.o}) with command line parsing
  and optional Workbench startup (@xref{Standard Startup}).
@item aos68km
  Minimal startup code (@file{minstart.o}) without command line
  parsing. You have to open all libraries yourself (@xref{Minimal Startup}).
@item aos68kr
  Minimal startup code (@file{minres.o}) for resident programs.
  Always compiles in small data mode and links with @file{vcs.lib}
  (@xref{Minimal Resident}).
@end table

@node Standard Startup
@subsection Startup

    The startup code currently consists of a slightly modified standard
    Amiga startup (@file{startup.o}). The startup code sets up some
    global variables and initializes stdin, stdout and stderr.
    The exit code closes all open files and frees all memory.
    If you link with a math library the startup/exit code will be taken
    from there if necessary.


@node Floating point
@subsection Floating point

    Note that you have to link with a math library if you want to use
    floating point. All math functions, special startup code and
    printf/scanf functions which support floating point are contained in
    the math libraries only.
    At the moment there are five math libraries:
 
@table @file
@item mieee.lib
   This one uses the C= math libraries. The startup code
                    will always open MathIeeeSingBas.library,
                    MathIeeeDoubBas.library and MathIeeeDoubTrans.library.
                    Float return values are passed in d0, double return
                    values are passed in d0/d1.
                    A 68000 is sufficient to use this library.
                    You must not specify @option{-fpu=...}
                    when you use this library.
   By default all floating point routines are provided via stub functions in
   @file{mieee.lib}. With the option @option{-amiga-softfloat} you can tell
   @command{vbccm68k} to generate inline code for calling the
   MathIeee libraries directly.
 
@item msoft.lib
    This one is based on John Hauser's IEC/IEEE Floating-point Arithmetic
    Package (@xref{SoftfloatHauser}) and doesn't need any system libraries for
    FP emulation. May be slower than the ROM libraries, though.
    Otherwise everything mentioned for @file{mieee.lib} applies here
    as well.
    Note that you have to call the @command{vc} frontend with the
    @option{-rmcfg-amiga-softfloat} option, when your config file contains
    @option{-amiga-softfloat} (which is the case for @file{aos68k}
    since vbcc V0.9h).

@item m881.lib
    This one uses direct FPU instructions and function
                    return values are passed in fp0. You must have a
                    68020 or higher and an FPU to use this library. You
                    also have to specify @option{-fpu=68881} or
                    @option{-fpu=68882}.
                    Several FPU instructions that have to be emulated on
                    040/060 may be used.
 
@item m040.lib
    This one uses only direct FPU instructions that do not
                    have to be emulated on a 68040. Other functions use
                    the Motorola emulation routines modified by
                    Aki M Laukkanen and Matthew Hey.
                    It should be used for programs compiled for 68040
                    with FPU.
                    Return values are passed in fp0.

@item m060.lib
    This one uses only direct FPU instructions that do not
                    have to be emulated on a 68060. Other functions use
                    the Motorola emulation routines modified by
                    Aki M Laukkanen and Matthew Hey.
                    It should be used for programs compiled for 68060
                    with FPU.
                    Return values are passed in fp0.
@end table

Depending on the CPU/FPU selected, including @file{math.h} will
cause inline-code generated for certain math functions.

@node amiga-stack
@subsection Stack

An application can specify the stack-size needed by defining a variable
@code{__stack} (of type @code{size_t}) with external linkage, e.g.

@example
size_t __stack=65536; /* 64KB stack-size */
@end example

The startup code will check whether the stack-size specified is larger
than the default stack-size (as set in the shell) and switch to a new
stack of appropriate size, if necessary.

If the @option{-stack-check} option is specified when compiling, the
library will check for a stack overflow and abort the program, if the
stack overflows. Note, however, that only code compiled with this
option will be checked. Calls to libraries which have not been compiled
with @option{-stack-check} or calls to OS function may cause a stack
overflow which is not noticed.

Additionally, if @option{-stack-check} is used, the maximum stack-size
used can be read by querying the external variable @code{__stack_usage}.

@example
#include <stdio.h>

extern size_t __stack_usage;

main()
@{
    do_program();
    printf("stack used: %lu\n",(unsigned long)__stack_usage);
@}
@end example

Like above, the stack used by functions not compiled using
@option{-stack-check} or OS functions is ignored.

@node amigasmalldata
@subsection Small data model

When using the small data model of the 68k series CPUs, you also have
to link with appropriate libraries. Most libraries documented here are
also available as small data versions (with an 's' attached to the
file name). Exceptions are the math libraries.

To compile and link a program using the small data model a command like

@example
vc test.c -o test -sd -lvcs -lamigas
@end example

might be used.

@subsection Restrictions

The following list contains some restrictions of this version of the
library:

@table @code

@item tmpfile()
The @code{tmpfile()} function always returns an error.

@item clock()
The @code{clock()} function always returns -1. This is correct,
according to the C standard, because on AmigaOS it is not possible to
obtain the time used by the calling process.

@end table

@node Minimal Startup
@subsection Minimal Startup 

If you want to write programs that use only Amiga functions and none from
vc.lib you can use @file{minstart.o} instead of @file{startup.o} and
produce smaller executables. You can also achieve that by simply using
the @file{aos68km} config file instead.

This startup code does not set up everything needed by vc.lib, so you
must not use most of these functions (string and ctype functions are ok,
but most other functions - especially I/O and memory handling - must not
be used).
@code{exit()} is supplied by minstart and can be used.
 
The command line is not parsed, but passed to @code{main()} as a single
string,
so you can declare main as
@code{int main(char *command)} or @code{int main(void)}.
 
Also no Amiga libraries are opened (but @code{SysBase} is set up), so you
have to define and open @code{DOSBase} yourself if you need it.
If you want to use floating point with the IEEE libraries
or @option{-amiga-softfloat} you have to
define and open MathIeeeSingBas.library, MathIeeeDoubBas.library and
MathIeeeDoubTrans.library (in this order!) and link with mieee.lib (if
compiled for FPU this is not needed).
 
A hello world using minstart could look like this:

@example 
#include <proto/exec.h>
#include <proto/dos.h>
 
struct DosLibrary *DOSBase;
 
int main()
@{
    if(DOSBase=(struct DosLibrary *)OpenLibrary("dos.library",0))@{
        Write(Output(),"Hello, world!\n",14);
        CloseLibrary((struct Library *)DOSBase);
    @}
    return 0;
@}

@end example

This can yield an executable of under 256 bytes when compiled with
@option{-sc -sd} and linked with @file{minstart.o} and @code{amigas.lib}
(using @command{vlink} - may not work with other linkers).

@node Minimal Resident
@subsection Minimal Startup for resident programs

AmigaOS can keep special "pure" programs resident in RAM, and restart them
from there without having to load them again from disk. To make it easy to
create such reentrant programs, even with static data, you can link with the
special startup code @file{minres.o}, which is a minimal startup code for
resident programs. Or simply use the config file @file{aos68kr} instead.
Everything mentioned for @file{minstart.o} in the previous section is also
valid for @file{minres.o}.

To create real resident programs you have to follow the following rules:
@itemize @minus

@item Compile all your code for the small data model (@option{-sd} option).

@item Avoid absolute references to small data symbols.
      Usually these are constant pointers to static data.
      The following example creates such an illegal relocation:
@example
int x;
int const *p = &x;
@end example
@command{vlink} warns about all potential problems.

@item Link with the @file{minres.o} startup code,
      and use the small data
      versions of linker libraries (@file{vcs.lib}, @file{amigas.lib}, etc.).

@item Set the Pure flag in the file attributes.
      Load the program into RAM
      with the AmigaDOS @command{resident} command.

@end itemize


@node amigalib
@subsection amiga.lib

To write programs using AmigaOS (rather than standard C functions
only), a replacement for the original (copyrighted) @file{amiga.lib}
is provided with @command{vbcc}. This replacement is adapted to vbcc,
does not cause collisions with some functions (e.g. @code{sprintf})
provided by the original @file{amiga.lib} and is available for the
small data mode as well. It is recommended to always use this library
rather than the original version.

Additionally, there are header files (in the @file{proto}- and
@file{inline}-subdirectories) which cause inlined calls to Amiga
library functions.

Besides some support functions @file{amiga.lib} contains stub routines
to call functions from all common AmigaOS libraries with stack arguments.
By including the library's proto header file you make sure that AmigaOS
functions are called directly by inline code, unless @code{_NO_INLINE}
is defined.

Preprocessor defines to control the behaviour of vbcc's proto headers:
@table @code
@item __NOLIBBASE__
  Do not declare the library base symbol.
@item _NO_INLINE
  Do not use optimized inline code for library function calls.
@end table

Note that the OS-call inlines have been generated using the NDK3.2 clib
header files, while trying to keep compatibility to NDK3.9, so it is
advised to use one of the two NDKs for development.
Otherwise you will get warnings about missing @code{CONST} typedefs and
similar.

Specify @option{-lamiga} to link with @file{amiga.lib}.

@node autolib
@subsection auto.lib

    To link with @file{auto.lib} (or the small data version
    @file{autos.lib}) specify
    the @option{-lauto} or @option{-lautos} option to @command{vc}.
 
    When you are calling a standard Amiga library function without
    having defined the corresponding library base, then the library base
    as well as code to open/close it will be taken from @file{auto.lib}.
 
    By default, @file{auto.lib} will try to open any library version. If you
    need at least a certain version you can define and set a variable
    _<library-base>Ver with external linkage, e.g. (on file-scope):

@example 
        int _IntuitionBaseVer = 39;
@end example

    Note that your program will abort before reaching @code{main()} if one
    of the libraries cannot be opened. Also note that @file{auto.lib}
    depends on constructor/destructor handling in vclib, which means it
    cannot work when linking without vclib, without standard startup code,
    or only with a minimal startup code, like @file{minstart.o}.

@subsection reaction.lib

The @file{reaction.lib} in @command{vbcc} is a port of Stephan Rupprecht's
rewrite of the copyrighted linker library, extended and fixed by
Olaf Barthel for the NDK 3.2 release. This version should work in
combination with NDK 3.9 as well.

To link with @file{reaction.lib} (or the small data version
@file{reactions.lib}) specify the @option{-lreaction} or
@option{-lreactions} option to @command{vc}.

The library contains ReAction GUI class support functions and their
autoinitialization code. Refer to @file{reaction_lib.doc} from your
NDK Autodocs for more information. As documented there, the version
used to automatically open the classes can be defined by the variable
@code{__reactionversion} with external linkage. Otherwise a default
of version 0 is used.


@section Kickstart1.x/68k

This section describes specifics of the C library for Amiga Kickstart 1.2
and 1.3 provided by the target @file{m68k-kick13}.
The relevant files are @file{startup.o}, @file{minstart.o}, @file{minres.o},
@file{startup16.o}, @file{minstart16.o}, @file{minres16.o},
@file{vc.lib}, @file{vcs.lib}, @file{m13.lib}, @file{m13s.lib},
@file{msoft.lib}, @file{msofts.lib}, @file{m881.lib}, @file{m881s.lib},
@file{amiga.lib}, @file{amigas.lib}, @file{auto.lib} and @file{autos.lib},
@file{vc16.lib}, @file{vc16s.lib}, @file{m1316.lib}, @file{m1316s.lib},
@file{msoft16.lib}, @file{msoft16s.lib}, @file{m88116.lib}, @file{m88116s.lib},
@file{amiga16.lib}, @file{amiga16s.lib}, @file{auto16.lib} and
@file{auto16s.lib}.

This target makes it possible to develop programs targeted for these older
versions of the Amiga operating system, using the original Commodore
Kickstart 1.3 header files. Note that there are also libraries and
config files for using a 16-bit int ABI, which was common at that time,
and may have some advantages on 16-bit CPUs, like the 68000 or 68010.

The following config files are available:
@table @code
@item kick13
  Standard startup code (@file{startup.o}) with command line parsing
  and optional Workbench startup (@xref{Startup13}) using 32-bit int.
@item kick13m
  Minimal startup code (@file{minstart.o}) without command line
  parsing. You have to open all libraries yourself (@xref{Minimal Startup})
  using 32-bit int.
@item kick13r
  Minimal startup code (@file{minres.o}) for resident programs.
  Always compiles in small data mode and links with @file{vcs.lib}
  (@xref{Minimal Resident}) using 32-bit int.
@item kick13s
  Standard startup code (@file{startup.o}) with command line parsing
  and optional Workbench startup (@xref{Startup13}) using 16-bit int.
@item kick13sm
  Minimal startup code (@file{minstart.o}) without command line
  parsing. You have to open all libraries yourself (@xref{Minimal Startup})
  using 16-bit int.
@item kick13sr
  Minimal startup code (@file{minres.o}) for resident programs.
  Always compiles in small data mode and links with @file{vcs.lib}
  (@xref{Minimal Resident}) using 16-bit int.
@end table

@node Startup13
@subsection Startup

    The startup code currently consists of a slightly modified standard
    AmigaOS 1.3 startup (@file{startup.o}). The startup code sets up some
    global variables and initializes stdin, stdout and stderr.
    The exit code closes all open files and frees all memory.
    If you link with a math library the startup/exit code will be taken
    from there if necessary.


@subsection Floating point

    Note that you have to link with a math library if you want to use
    floating point. All math functions, special startup code and
    printf/scanf functions which support floating point are contained in
    the math libraries only.
    At the moment there are two math libraries:
 
@table @file
@item m13.lib
   This one uses the C= math libraries present under Kickstart 1.2 and 1.3.
   The startup code will always open mathffp.library,
   MathIeeeDoubBas.library and MathIeeeDoubTrans.library.
   Note that all single precision floating point calculations take place
   in FFP format and have to be converted between FFP and IEEE by the
   library.
                    Float return values are passed in d0, double return
                    values are passed in d0/d1.
                    A 68000 is sufficient to use this library.
                    You must not specify @option{-fpu=...}
                    when you use this library.

@item msoft.lib
    This one is based on John Hauser's IEC/IEEE Floating-point Arithmetic
    Package (@xref{SoftfloatHauser}) and doesn't need any system libraries for
    FP emulation. May be slower than the ROM libraries, though.
    Otherwise everything mentioned for @file{m13.lib} applies here
    as well.
 
@item m881.lib
    This one uses direct FPU instructions and function
                    return values are passed in fp0. You must have a
                    68020 or higher and an FPU to use this library. You
                    also have to specify @option{-fpu=68881}.
                    Several FPU instructions that have to be emulated on
                    040/060 may be used.
@end table

@subsection Stack

Stack-checking is available similar to AmigaOS/68k (@xref{amiga-stack}).
But there is no automatic stack-extension under Kickstart 1.3 and a
@code{__stack} variable will be ignored.

@subsection Small data model

Small data is supported as described for AmigaOS/68k (@xref{amigasmalldata}).
The startup code takes care of clearing the unititalized part of a
small data section (which Kickstart 1.x fails to do).

@subsection Restrictions

The following list contains some restrictions of this version of the
library:

@table @code

@item tmpfile()
The @code{tmpfile()} function always returns an error.

@item clock()
The @code{clock()} function always returns -1. This is correct,
according to the C standard, because on AmigaOS it is not possible to
obtain the time used by the calling process.

@end table

@subsection amiga.lib

@xref{amigalib}.

This version of @file{amiga.lib} only supports the functionality present
in Kickstart 1.2/1.3.

@subsection auto.lib

This library corresponds to the AmigaOS/68k version (@xref{autolib}), but
only supports libraries of Kickstart 1.3.

@subsection Minimal Startup 

You can use @file{minstart.o} similar to AmigaOS/68k (@xref{Minimal Startup}).

@subsection Minimal Startup for Resident Programs

You can use @file{minres.o} similar to AmigaOS/68k (@xref{Minimal Resident}).


@section PowerUp/PPC

This section describes specifics of the C library for PowerUp/PPC
provided by the target @file{ppc-powerup}.
The relevant files are @file{startup.o}, @file{minstart.o},
@file{libvc.a}, @file{libvcs.a}, @file{libm.a}, @file{libms.a}
@file{libamiga.a}, @file{libamigas.a},
@file{libauto.a} and @file{libautos.a}.

Note that @file{libextra.a} is no longer part of the vbcc distribution.
It was replaced by 'PosixLib', available on Aminet
@file{dev/c/vbcc_PosixLib.lha}, which has a much more comprehensive
support for POSIX and Unix functions.

@subsection Startup
 
    The startup code @file{startup.o} sets up some
    global variables and initializes stdin, stdout and stderr.
    The exit code closes all open files and frees all memory.
    If you link with a math library the startup/exit code will be taken
    from there if necessary.

@subsection Floating point
 
    Note that you have to link with a math library if you want to use
    floating point. All math functions, special startup code and
    printf/scanf functions which support floating point are contained in
    the math libraries only.

    The math library (@file{libm.a}) is linked against the floating point
    library libmoto by Motorola.

Depending on the CPU/FPU selected, including @file{math.h} will
cause inline-code generated for certain math functions.

@subsection Stack

Stack-handling is similar to AmigaOS/68k (@xref{amiga-stack}).
The only difference is that stack-swapping cannot be done. If the
default stack-size is less than the stack-size specified with
@code{__stack} the program will abort.

@subsection Small data model
 
When using the small data model of the PPC series CPUs, you also have
to link with appropriate libraries. Most libraries documented here are
also available as small data versions (with an 's' attached to the
file name). Exceptions are the math libraries.
 
To compile and link a program using the small data model a command like
 
@example
vc test.c -o test -sd -lvcs -lamigas
@end example
 
might be used.

@subsection Restrictions
 
The following list contains some restrictions of this version of the
library:
 
@table @code
 
@item tmpfile()
The @code{tmpfile()} function always returns an error.
 
@item clock()
The @code{clock()} function always returns -1. This is correct,
according to the C standard, because on AmigaOS it is not possible to
obtain the time used by the calling process.

@end table

@subsection Minimal Startup

The provided minimal startup code (@file{minstart.o}) is used
similarly like the one for 68k (@xref{Minimal Startup}). Only use
it if you know what you are doing.

@subsection libamiga.a

To write programs accessing AmigaOS (rather than standard C functions
only), a replacement for the original (copyrighted) @file{amiga.lib}
is provided with @command{vbcc}. This replacement (@file{libamiga.a})
automatically performs a necessary context switch to the 68k to execute
the system call. Furthermore, it is adapted to vbcc,
does not cause collisions with some functions (e.g. @code{sprintf})
provided by the original @file{amiga.lib} and is available in
small data.

Specify @option{-lamiga} to link with @file{libamiga.a}.
 
@subsection libauto.a
 
This library corresponds to the AmigaOS/68k version (@xref{autolib}).

@section WarpOS/PPC
 
This section describes specifics of the C library for WarpOS/PPC
provided by the target @file{ppc-warpos}.
The relevant files are @file{startup.o}, 
@file{vc.lib}, @file{m.lib}, @file{amiga.lib} and @file{auto.lib}.

Note that @file{extra.lib} is no longer part of the vbcc distribution.
It was replaced by 'PosixLib', available on Aminet
@file{dev/c/vbcc_PosixLib.lha}, which has a much more comprehensive
support for POSIX and Unix functions.

@subsection Startup
 
    The startup code @file{startup.o} sets up some
    global variables and initializes stdin, stdout and stderr.
    The exit code closes all open files and frees all memory.
    If you link with a math library the startup/exit code will be taken
    from there if necessary. 

@subsection Floating point
 
    Note that you have to link with a math library if you want to use
    floating point. All math functions, special startup code and
    printf/scanf functions which support floating point are contained in
    the math libraries only.

    The math library (@file{m.lib}) contains functions from Sun's
    portable floating point library. Additionally, there is a
    @command{vbcc} version of Andreas Heumann's @file{ppcmath.lib}.
    These routines are linked against Motorola's floating point
    routines optimized for PowerPC and therefore are much faster.

    To make use of this library, link with @file{ppcmath.lib} before
    @file{m.lib}, e.g.

@example
    vc test.c -lppcmath -lm
@end example
    

 
Depending on the CPU/FPU selected, including @file{math.h} will
cause inline-code generated for certain math functions.

@subsection Stack

Stack-handling is similar to AmigaOS/68k (@xref{amiga-stack}).

@subsection Restrictions
 
The following list contains some restrictions of this version of the
library:
 
@table @code
 
@item tmpfile()
The @code{tmpfile()} function always returns an error.
 
@item clock()
The @code{clock()} function always returns -1. This is correct,
according to the C standard, because on AmigaOS it is not possible to
obtain the time used by the calling process.
 
@end table

@subsection amiga.lib
 
To write programs accessing AmigaOS (rather than standard C functions
only), a replacement for the original (copyrighted) @file{amiga.lib}
is provided with @command{vbcc}. This replacement
automatically performs a necessary context switch to the 68k to execute
the system call. Furthermore, it is adapted to vbcc,
does not cause collisions with some functions (e.g. @code{sprintf})
provided by the original @file{amiga.lib} and is available in
small data.
 
Specify @option{-lamiga} to link with @file{amiga.lib}.

 
@subsection auto.lib
 
This library corresponds to the AmigaOS/68k version (@xref{autolib}).
 

@section MorphOS/PPC
 
This section describes specifics of the C library for MorphOS/PPC
provided by the target @file{ppc-morphos}.
The relevant files are @file{startup.o}, @file{minstart.o},
@file{libvc.a}, @file{libvcs.a}, @file{libm.a}, @file{libms.a}
@file{libamiga.a}, @file{libamigas.a},
@file{libauto.a} and @file{libautos.a}.

Note that @file{libextra.a} is no longer part of the vbcc distribution.
It was replaced by 'PosixLib', available on Aminet
@file{dev/c/vbcc_PosixLib.lha}, which has a much more comprehensive
support for POSIX and Unix functions.
 
@subsection Startup
 
    The startup code @file{startup.o} sets up some
    global variables and initializes stdin, stdout and stderr.
    The exit code closes all open files and frees all memory.
    If you link with a math library the startup/exit code will be taken
    from there if necessary.
 
@subsection Floating point
 
    Note that you have to link with a math library if you want to use
    floating point. All math functions, special startup code and
    printf/scanf functions which support floating point are contained in
    the math libraries only.
 
    The math library (@file{libm.a}) is linked against the floating point
    library libmoto by Motorola.
 
Depending on the CPU/FPU selected, including @file{math.h} will
cause inline-code generated for certain math functions.

@subsection Stack

Stack-handling is similar to AmigaOS/68k (@xref{amiga-stack}).

@subsection Small data model
 
When using the small data model of the PPC series CPUs, you also have
to link with appropriate libraries. Most libraries documented here are
also available as small data versions (with an 's' attached to the
file name). Exceptions are the math libraries.
 
To compile and link a program using the small data model a command like
 
@example
vc test.c -o test -sd -lvcs -lamigas
@end example
 
might be used.

@subsection Restrictions
 
The following list contains some restrictions of this version of the
library:
 
@table @code
 
@item tmpfile()
The @code{tmpfile()} function always returns an error.
 
@item clock()
The @code{clock()} function always returns -1. This is correct,
according to the C standard, because on MorphOS it is not possible to
obtain the time used by the calling process.
 
@end table

@subsection libamiga.a

To write programs using AmigaOS compatible functions, a replacement for
the original (copyrighted) @file{amiga.lib}
is provided with @command{vbcc}. This replacement (@file{libamiga.a})
will invoke the MorphOS 68k emulator to execute the system function.
Furthermore, it is adapted to vbcc and
does not cause collisions with some functions (e.g. @code{sprintf})
and is available in small data.

Specify @option{-lamiga} to link with @file{libamiga.a}.


@subsection libauto.a
 
This library corresponds to the AmigaOS/68k version (@xref{autolib}).
 

@section AmigaOS4/PPC
 
This section describes specifics of the C library for AmigaOS4/PPC
provided by the target @file{ppc-amigaos}.
The relevant files are @file{startup.o}, @file{minstart.o},
@file{libvc.a}, @file{libvcs.a}, @file{libm.a}, @file{libms.a}
@file{libamiga.a}, @file{libamigas.a},
@file{libauto.a} and @file{libautos.a}.

Note that @file{libextra.a} is no longer part of the vbcc distribution.
It was replaced by 'PosixLib', available on Aminet
@file{dev/c/vbcc_PosixLib.lha}, which has a much more comprehensive
support for POSIX and Unix functions.
 
@subsection Startup
 
The startup code @file{startup.o} sets up some
global variables and initializes stdin, stdout and stderr.
Then it runs all constructors of dynamically linked libraries, before
entering the main program.
The exit code runs all destructors of dynamically linked libraries,
closes all open files and frees all memory.
If you link with a math library the startup/exit code will be taken
from there if necessary.
 
@subsection Floating point
 
Note that you have to link with a math library if you want to use
floating point. All math functions, special startup code and
printf/scanf functions which support floating point are contained in
the math libraries only.

The math library (@file{libm.a}) is linked against the floating point
library libmoto by Motorola.
 
Depending on the CPU/FPU selected, including @file{math.h} will
cause inline-code generated for certain math functions.

@subsection Stack

There is no automatic stack extension for AmigaOS 4! This should be
done automatically by the operating system.

@subsection Small data model
 
When using the small data model of the PPC series CPUs, you also have
to link with appropriate libraries. Most libraries documented here are
also available as small data versions (with an 's' attached to the
file name). Exceptions are the math libraries.
 
To compile and link a program using the small data model a command like
 
@example
vc test.c -o test -sd -lvcs -lamigas
@end example
 
might be used.

@subsection Dynamic linking
Since @file{elf.library} @code{V52.2} AmigaOS4 supports dynamic linking with
shared object files (@file{.so} extension), similar to Unix. The default
behaviour is to prefer linking against a shared object over a static
library. To force static linking you might want to give the
@option{-static} option to the @file{vc} frontend.

@subsection Restrictions
 
The following list contains some restrictions of this version of the
library:
 
@table @code
 
@item tmpfile()
The @code{tmpfile()} function always returns an error.
 
@item clock()
The @code{clock()} function always returns -1. This is correct,
according to the C standard, because on AmigaOS it is not possible to
obtain the time used by the calling process.

@item Small data in dynamically linked executables
There is a bug in @file{elf.library} @code{V52.4} (and earlier), which
doesn't load @code{.sdata} and @code{.sbss} as a contiguous block into
memory, when the executable requires dynamic linking. I decided against
writing a workaround, as the bug should be fixed in OS4.

@end table

@subsection libamiga.a

In contrast to other amigalibs the OS4 @file{libamiga.a} doesn't contain
any stubs for calling system functions. AmigaOS 4 system calls are done
through special macros in the SDK's interface header files.

The library only includes some remaining amigalib functions, not already
integrated into the OS, like @code{CreateIO()}, but its use is discouraged.

Specify @option{-lamiga} to link with @file{libamiga.a}.


@subsection libauto.a

Include auto-open and -close functions for the most common OS libraries and
interfaces. May also be used together with newlib (see below).
 

@subsection newlib

@subsubsection Introduction

    newlib.library is a shared AmigaOS4 library, which is covered by
    several BSD like licenses,
    and includes standard ANSI and POSIX functions as well as some
    functions common in Unix, BSD and similar operating systems. It is
    part of the OS4 SDK.

    The config file @file{newlib} will be created on installation to
    use the paths for header files and libraries pointing to the
    newlib from the SDK. 

    What are the main differences between vclib and newlib?

@itemize @minus
@item vclib contains (almost) only standard ANSI-C and some ISO-C99
      functions. If you want to port Unix programs you will probably
      miss a lot of functions.
      Also newlib supports things like mapping Unix directory paths to
      Amiga paths or expanding wildcards in command lines automatically.
 
@item Programs compiled for newlib will be shorter because the code for all
      functions is not contained in the executable itself.

@item Programs compiled for newlib will need the shared object
      @file{libc.so} present when started.

@item Programs compiled for newlib will probably need more memory because
      the entire (rather large) @file{libc.so} will be loaded into memory.
      With vclib only the functions your program uses will be in RAM.
      However if you have several programs using newlib at the same
      time only one copy of @file{libc.so} should be loaded.
@end itemize

    Things you should note:
 
@itemize @minus
@item With newlib you do not need extra math-libraries.
 
@item You must link with a vbcc-specific @file{startup.o} from the newlib
      @file{lib/} directory as startup code.
      The config-file @file{newlib} will usually take care of this.
 
@item You _must_ use the newlib-includes from the SDK
      rather than the ones which are for vc.lib.
      The config-file @file{newlib} will usually take care of this.

@item There may be vbcc-related bugs in the SDK-newlib. Patches are
      automatically installed when using the Amiga Installer. When
      installing the target manually, you also have to fix the SDK
      manually. For a list of known SDK bugs at this point of time,
      @xref{Known Newlib Bugs}.
@end itemize

@node Known Newlib Bugs
@subsubsection Known Newlib Bugs

@itemize @minus

@item The @code{__asm_toupper()} and @code{__asm_tolower()} assembler inlines
      in @file{newlib/include/ctype.h} are wrong, which makes
      @code{toupper()} and @code{tolower()} fail when including
      @file{ctype.h}. Fix:
@example
--- ctype.h.orig	2006-04-03 18:00:00.000000000 +0200
+++ ctype.h	2017-05-07 19:32:00.000000000 +0200
@@@@ -64,8 +64,8 @@@@
 #elif defined(__VBCC__)
 int __asm_toupper(__reg("r3") int) =
         "\t.extern\t__ctype_ptr\n"
-        "\tlis\t11,(__ctype_ptr)@@ha\n"
-        "\taddi\t11,11,(__ctype_ptr)@@l\n"
+        "\tlis\t11,__ctype_ptr@@ha\n"
+        "\tlwz\t11,11,__ctype_ptr@@l(11)\n"
         "\tlbzx\t12,11,3\n"
         "\tandi.\t12,12,2\n"
         "\tbeq\t$+8\n"
@@@@ -73,8 +73,8 @@@@
         "#barrier";
 int __asm_tolower(__reg("r3") int) =
         "\t.extern\t__ctype_ptr\n"
-        "\tlis\t11,(__ctype_ptr)@@ha\n"
-        "\taddi\t11,11,(__ctype_ptr)@@l\n"
+        "\tlis\t11,__ctype_ptr@@ha\n"
+        "\tlwz\t11,11,__ctype_ptr@@l(11)\n"
         "\tlbzx\t12,11,3\n"
         "\tandi.\t12,12,1\n"
         "\tbeq\t$+8\n"
@end example
Note: This should be fixed with the latest OS4 SDK, and the V0.9h
installer will no longer install a patch!

@item Newlib's @file{libauto.a} contains no working vbcc-style
constructors or destructors for auto-opening or -closing of libraries.
You can work-around it, by copying vclib's @file{libauto.a} to
newlib's lib-directory. Rename it, if you don't want to overwrite
the gcc-version of it.

@item Some header files, like @file{sys/stat.h}, use the reserved vbcc
attribute @code{__mask} as an argument name. The config file should
take care of that, by redefining it as @code{___mask}.

@end itemize

@subsubsection Usage

To compile a program to use newlib for OS4 you must make sure the proper
config-file (@file{newlib}) is used, e.g.
 
@example
        vc +newlib hello.c
@end example

With a new SDK this will usually generate a dynamically linked executable,
which requires @file{libc.so}. To force a statically linked executable:

@example
        vc +newlib -static hello.c
@end example


@section Atari TOS/MiNT

This section describes specifics of the C library for Atari TOS and MiNT.
M680x0 processors are supported by the target @file{m68k-atari}, while
ColdFire processors are supported by the target @file{cf-atari}. Both
share the same startup-code and are based on common library sources and
header files. Executables linked with this C library run on plain TOS as
well as on MiNT, without modifications.

The relevant files are @file{startup.o}, @file{minstart.o},
@file{libvc.a}, @file{libm.a}, @file{libgem.a}. For the M68k target
there are also math libs with FPU support (@file{libm881.a},
@file{libm040.a} and @file{libm060.a}) and 16-bit integer versions
of all libraries (@file{lib*16.a}).

The following config files are available:
@table @code
@item tos
  M68k 32-bit @code{int} for classic TOS machines.
@item tos16
  M68k 16-bit @code{int} for classic TOS machines.
@item mint
  M68k 32-bit @code{int} for MiNT. Also works on classic machines,
  but uses an embedded a.out header for MiNT, includes a changeable
  @code{__stksize} and sets the FastLoad, FastRAM and FastAlloc flags
  in the header.
@item mintcf
  ColdFire 32-bit @code{int}. Otherwise same as @file{mint}.
@end table

@subsection Startup
 
The startup code @file{startup.o} sets up some
global variables and initializes stdin, stdout and stderr and returns
the unneeded memory to the system.
The exit code closes all open files and frees all memory.

@subsection Floating point

Note that you have to link with a math library if you want to use
floating point. All math functions, special startup code and
printf/scanf functions which support floating point are contained in
the math libraries only.

On the M68k target you have the option to enable FPU support with
the @option{-fpu} option and choose the appropriate math library
(@xref{Floating point}). Otherwise, there is a soft-float library,
which is compatible with all the Atari models without an FPU.

@subsection Stack

The default stack size is 64k. There is a MiNT tool called @file{stack}
which can adjust the stack size of an executable to any value, by looking
for a symbol named @code{__stksize} (defined by vclib's startup code).

Additionally the required stack size can be specified by defining a
variable @code{__stack} (of type @code{size_t}) with external linkage, as
in other vbcc targets.

@subsection 16-bit integer model

The default libraries use 32-bit @code{int} types, but you may want to
use 16-bit @code{int} types for compatibility reasons. In this case you
have to specify the config file @code{tos16} and link with the appropriate
16-bit libraries (which have a '@file{16}' attached to their name).

To compile and link a program using 16-bit integers a command like

@example
vc +tos16 test.c -o test -lm16 -lvc16
@end example
 
may be used. There are no 16-bit versions for ColdFire targets,
because this is strictly a 32-bit CPU.

@subsection Restrictions
 
The following list contains some restrictions of this version of the
library:
 
@table @code
 
@item tmpfile()
The @code{tmpfile()} function always returns an error.
 
@item clock()
The @code{clock()} function always returns -1. This is correct,
according to the C standard, because neither under TOS nor under MiNT it
is possible to obtain the time used by the calling process.

@end table

@section VideoCore/Linux

This section describes specifics of the C library for VideoCore under Linux
provided by the target @file{vidcore-linux}.

The relevant files are @code{vcload}, @file{startup.o},
@file{libvc.a}, @file{libm.a}, @file{libms.a}.

The config file @code{vc4-linux} is part of the library.

@subsection Startup
 
The startup code @file{startup.o} sets up stack and heap and provides
a function @code{__armcall()} to transfer control to the loader on
the ARM side.
The startup process calls constructors to set up some
global variables and initialize stdin, stdout and stderr if needed.

@subsection Floating point

Note that you have to link with a math library if you want to use
floating point operations that are not natively implemented.
All math functions, special startup code and
printf/scanf functions which support floating point are contained in
the math libraries only.

@subsection Stack

The library contains a default stack of 32KB. If another size is needed,
you can add the following to your project:

@example
        .align  4
        .space  <desired-size, suitably aligned>
___stackend:
        .global ___stackend
@end example

@subsection Heap

Currently, a global variable of 16KB is used to get memory for
malloc() etc.  If another size is needed,
you can add the following to your project:

@example
#define HEAPSIZE <desired size>

char __heap[HEAPSIZE],*__heapptr=__heap;
size_t __heapsize=HEAPSIZE;
@end example

Note that this mechanism will likely be changed in the future!

@subsection System Calls

To access system functions from the VideoCore-side, the function
@code{__armcall()} can be used. It will save the current context and return
to the loader. Registers @code{r0-r5} (the function arguments) will be saved
and are available to the loader. The loader can then execute the system
call and resume execution, passing the return value of the system
function.

Resuming is done by calling the image with offset 2.

This functionality can also be used for debugging purposes.

@subsection Loader

A loader is required to execute VideoCore code from the ARM side. For
standalone VideoCore code, the provided loader can be used. Usually, it
will be necessary to adapt the loader to communicate between ARM and
VideoCore side during runtime.

@subsubsection Object Format

Currently, the loader loads an simple binary image that must be pc-relative
and located to address 0x00000000. Additionally, if present, a file
with extension @file{.reltext} will be loaded for some limited
relocation. This file contains a 32bit word containing the number of
relocations followed by n 32bit words containing an offset. For each
offset, the address will be relocated to the image load address.

@subsubsection Command line arguments

@code{vcload [-debug] [-cache] [-offset] <image-name>}

The loader currently has the following options:

@table @code

@item -debug

    The loader will enter debug mode (see below).

@item -cache

    The loader will set the LSB in the start address when executing
    code. This is supposed to inhibit a cache flush.

    Just for testing!

@item -offset

    The loader will allocate 1 KB more memory than required and leaves
    this space unused at the beginning of the allocated memory.

    Just for testing!

@end table

@subsubsection Debug Mode

In debug mode, the loader will wait for user input before starting the
VideoCore code as well as after every @code{__armcall}.

The following commands are available:

@table @code
@item w <addr> [<num>]
      Display <num> 32bit words starting at <addr>.
      <addr> must be the offset into the image. If <num> is omitted,
      one unit is displayed.

      If one word is displayed, it is additionally displayed translated
      as an offset into the image.

@item h <addr> [<num>]
      Display <num> 16bit halfwords starting at <addr>.
      <addr> must be the offset into the image. If <num> is omitted,
      one unit is displayed.

@item b <addr> [<num>]
      Display <num> 8bit bytes starting at <addr>.
      <addr> must be the offset into the image. If <num> is omitted,
      one unit is displayed.

@item c
      Start/continue execution.

@item q
      Quit.

@item bp <addr>
      Set a breakpoint at <addr>.

      This is currently a very crude implementation. It will just write
      a branch to @code{__armcall()} to <addr>. If everything works well,
      you will end in the debugger if <addr> is reached. However, the
      arguments passed are random (and might be dangerous syscalls by 
      accident). Also, the old code at this address is currently not
      restored.

      As a result, you must not continue execution after hitting a
      breakpoint!
@end table


@subsection Restrictions
 
The following list contains some restrictions of this version of the
library:
 
@itemize @minus
 
@item no real floating point support yet

@item lots, lots, lots...


@end itemize

@section ATARI Jaguar/68k

This section describes specifics of the C library for ATARI Jaguar
provided by the target @file{m68k-jaguar}.

The relevant files are @file{startup.o},
@file{libvc.a}, @file{libm.a}, @file{libjag.a}.

The config files @code{jaguar_unix} and @code{jaguar_windows} are part of the library.

@subsection Startup
 
The startup code @file{startup.o} sets up stack and heap.
The startup process calls constructors to set up some
global variables and initialize stdin, stdout and stderr.

The ATARI Jaguar has no OS, so it is impossible to define how input, output and files
can be handled. There are a few set of function you have to define if you want to use stdio.

Alternatively you can use the @file{libjag.a}. This library initializes a console window with stdout
support and uses optionally a SkunkBoard to redirect stderr and file I/O.

@subsection Floating point

Note that you have to link with a math library if you want to use
floating point operations that are not natively implemented.
All math functions, special startup code and
printf/scanf functions which support floating point are contained in
the math library only. Consider the ATARI Jaguar does not own a FPU so this library is pretty slow.

@subsection Stack

The library contains a default stack of 32KB. If another size is needed,
you can add a global variable named __stack to your code:

@example

/* Set 64kB stack */
unsigned long __stack = 65536;

@end example

@subsection Heap

Currently the free RAM is used as global heapsize for malloc() etc.

It is necessary to place a symbol named _BSS_END at the end of the BSS segment.
The heap allocates the free RAM between _BSS_END and the bottom of the stack.

If less size is needed feel free to manipulate the value of _BSS_END.

All allocated heap objects can be used as internal JAGUAR objects, because they are qhrase aligned.

@subsection stdio support

The ATARI Jaguar lacks stdio support. So the @file{libvc.a} has just empty stub functions for
open, close, read and write, which you may overwrite if you need stdio.
Alternatively you can use @file{libjag.a} which has simple stdio
and file I/O functionality.

@example
/**
 * param name: name mentioned in fopen
 * param mode: mode mentioned in fopen
 * returns: > 0 a valid file handle
 *          < 0 to indicate an error
 *          the values 0,1,2 are used by stdin, stdout and stderr
 *
 * No need to handle stdin, stdout and stderr here
 */
int jagopen(const char *name,const char *mode)

/**
 * param handle: handle from jagopen
 *
 * No need to handle stdin, stdout and stderr here
 */
void jagclose(int handle)

/**
 * param handle: handle from jagopen
 * param p: points to the char buffer to fill.
 * param l: buffer size of p
 * returns: >=0 number of read bytes
            <0 indicate an error
 *
 * Handle stdin, stdout and stderr here
 */
size_t jagread(int handle,char *p,size_t l)

/**
 * param handle: handle from jagopen
 * param p: points to the char buffer to write.
 * param l: number of bytes of p
 * returns: >=0 number of bytes written
            <0 indicate an error
 *
 * Handle stdin, stdout and stderr here
 */
size_t jagwrite(int handle,const char *p, size_t l)

/**
 * param handle: handle from jagopen
 * param offset: number of bytes to seek.
 * param direction: see fseek direction
 * returns: =0 successful seek
            <>0 indicate an error
            -1: seek not supported
 *
 * Handle stdin, stdout and stderr here
 */
long jagseek(int handle,long offset,int direction)
@end example

@subsection The jaglib

The jaglib @file{libjag.a} provides simple functions to support your first
steps in ATARI Jaguar programming. It initializes a simple console output window and comes with 
an old ATARI character set.
If a SkunkBoard is available I/O functionality can be redirected.

Your first Jaguar program can look like this:

@example

#include <stdio.h>

int main()
@{
    printf("Hello, world\n");
@}

@end example

Keep in mind: Your JAGUAR will get a red background color to indicate @code{main()} has exited.

The jaglib API documentation is available in a separate document. There is more demo code
available in the @uref{https://github.com/toarnold/jaglib-demo, jaglib-demo} gibhub repository.

@section 6502/C64

This is a port of vclib to the C64.

@subsection Startup and Memory

Startup and memory layout is described in the following paragraphs.

@subsubsection Startup

The default linker file creates program files that are loaded to address
0x801. A BASIC line is included so that the program can be started using @code{RUN}
from BASIC. The startup code
will turn off the BASIC ROM to allow usage of RAM until 0xD000 and most of the
zero page without need for any special handling. The BSS segment will be cleared
during startup.

With the default configuration, after exiting the C program, an infinite loop will
be entered. When using the @code{+c64r} config, the program will return to BASIC
an can be started again.
However, this needs additional memory as the init values for the data section have
to be stored in RAM. Also, some register values and zero page contents have to be
saved. The overhead depends on the amount of initialized variables.

@subsubsection Command line

Command line parameters are supported by using the convention/code submitted by
Stefan Haubenthal. 

Command-lines look like these lines:

@example
   run
   run : rem
   run:rem arg1 " arg 2 is quoted "  arg3 "" arg5
@end example



@subsubsection Zero Page

@code{vbcc} uses a number of zero page locations for register variables, stack
pointer etc. in section @code{zpage}. Also, variables can be mapped to zero page using
the @code{__zpage} attribute. By default the area @code{0x02..0x8d}
is used, but this can be changed in the linker file.

@subsubsection Stack

By default, the user stack is mapped from @code{0xC800..0xD000}. The size can be
changed at the top of @code{vlink.cmd}.

@subsubsection Heap

Code and data/BSS are mapped starting after the BASIC init line.
The heap is placed in the remaining space to stack start.

@subsubsection Banking

The following banking models are supported:

@table @code
@item -reuflat
      This library supports a REU using a flat 16MB address space. The memory has to
      be addressed through far-pointers. It is not possible to declare variables in
      the REU nor to place code in the REU. The memory is addressed as 0x000000 to
      0xFFFFFF. All accesses through far-pointers are addressing the REU. It is not
      possible to address the C64 memory through a far-pointer.

      Far-pointer arithmetic only works on the lower 16bits. It is not possible to
      cross a bank boundary using far-pointers. Huge-pointers will support this, but
      are not yet fully implemented. In the meantime it is possible to use long integers
      and cast them to far-pointers.

      Use @code{-lreuflat} to link with this library. Note that the library does
      not check for the presence of a REU.

@item -reubank
      This configuration reserves a 16KB memory space within the C64 memory as window
      for banking. As the bank number is stored as a single byte (with bank
      255 denoting the unbanked memory), it is only possible to address up to
      about 4MB of memory in the REU.

      Variables and code can be mapped into the REU using the @code{__bank()} attribute
      or @code{#pragma bank}. When calling a banked function, the corresponding bank
      will be copied from the REU into the C64 memory window.

      Use the @code{+c64reu} configuration to use this mechanism. Currently the
      linker file provides 8 banks resulting in a 128K REU image. More banks can
      be added for larger expansions.

      The configuration will create a usually C64 prg file containing the unbanked
      code and data as well as a REU image with extension @code{.b0}. It must
      be loaded (e.g. with an emulator or the TurboChameleon) before the prg file
      can is executed.
@end table


@subsection Runtime

Apart from standard C library functions, @code{libvc.a} also provides a few
runtime support functions needed by the compiler. Apart from the math and
floating point functions mentioned in the documentation of the 6502 backend,
it includes functions for saving/restoring registers.

@subsection @code{stdio}

stdio supports @code{stdout}, @code{stderr} (both using the
screen) and @code{stdin} (keyboard). Both are unbuffered by default.

Furthermore, file IO with standard C functions is supported 
for 1541 and compatible disk drives. Other devices have not been tested.
Only sequential reading and writing of files is supported. No seeking etc.
There are hardcoded limits for the maximum number of open files and the
maximum length of filenames.

The @code{remove()} and @code{rename()} functions are supported using 1541

By default, device ID 8 is used. Another device ID can be specified as prefix
to the filename:

@example
  /* try to open file "test" on the second drive */
  FILE *f;
  f=fopen("9:test","r"); 
  ...
@end example

@code{printf/scanf} functions which support floating point are contained in
the math library only.


@subsection Floating Point / wozfp

When using floating point, the math library @code{libm.a} must be linked using
the @code{-lm} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on Steve Wozniaks routines from the 70s,
somewhat adapted to the ABI of @code{vbcc}. These functions are small and
reasonably usable, but they do not fully satisfy the requirements of C99.

Only a part of the C library functions for floating point is implemented. The
list currently includes:

@itemize
@item @code{exp()}
@item @code{pow()}
@item @code{log()}
@item @code{log10()}
@end itemize

@subsection Floating Point / IEEE

When using IEEE floating point, @code{-ieee} must be specified and the math library
@code{libmieee.a} must be linked using
the @code{-lmieee} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on SANE,
somewhat adapted to the ABI of @code{vbcc} using wrapper functions.
These functions should be fully C and IEEE compliant and provide precise results for
32 and 64bit floating point numbers (the library actually internally calculates
all operation using 80bits, but vbcc currently only uses up to 64 bits).

Currently, this library probably must be run from RAM.

Most parts of the C library functions for floating point are implemented. The
list currently includes:

@itemize
@item @code{exp(), expf(), expl()}
@item @code{exp2(), exp2f(), exp2l()}
@item @code{exp1m(), exp1mf(), exp1ml()}
@item @code{pow(), powf(), powl()}
@item @code{log(), logf(), logl()}
@item @code{log1p(), log1pf(), log1pl()}
@item @code{log2(), log2f(), log2l()}
@item @code{log10(), log10f(), log10l()}
@item @code{sqrt(), sqrtf(), sqrtl()}
@item @code{sin(), sinf(), sinl()}
@item @code{cos(), cosf(), cosl()}
@item @code{tan(), tanf(), tanl()}
@item @code{atan(), atanf(), atanl()}


@end itemize

@section 6502/NES

This is a port of vclib to the NES console.


@subsection Startup and Memory

Startup and memory layout is dependent on the ROM used. Currently two example configurations
are provided. They can be selected with @code{+nrom256v} and @code{+unrom512v}. Have a
look at the corresponding linker scripts in @code{vbcc/targets/6502-nes} for further
details.

The necessary library routines to support configurations with several ROM banks are
included.

@subsubsection Zero Page

@code{vbcc} uses a number of zero page locations for register variables, stack
pointer etc. in section @code{zpage}. Also, variables can be mapped to zero page using
the @code{__zpage} attribute. The entire zero page can be used, but this can be changed
in the linker file.

@subsubsection Stack

By default, the user stack starts from @code{0x0800} growing downwards.

@subsubsection Heap

By default, code and data/BSS are mapped starting after the system stack at @code{0x0200}.
The heap is placed in the remaining space to stack start.

@subsection Runtime

Apart from standard C library functions, @code{libvc.a} also provides a few
runtime support functions needed by the compiler. Apart from the math and
floating point functions mentioned in the documentation of the 6502 backend,
it includes functions for saving/restoring registers.

@subsection @code{stdio}

At the moment, stdio only supports @code{stdout}, @code{stderr} (both using the
screen) and @code{stdin} (simple input via joypad).

@code{printf/scanf} functions which support floating point are contained in
the math library only.

For input, up/down changes the current character, left/right moves the cursor,
the B button deletes from the cursor position, and the A button confirms the input.
You do not want to use this in real code.

The library contains a default character set. To replace it, link an object that
contains a character set mapped to section @code{chars} and defines the global symbol
@code{___stdchr}.

To replace stdio, the function @code{__read()} and @code{__write()} have to be
implemented.

@subsection Interrupts

The library contains a default NMI implementation that is used for stdio handling
and the @code{clock()}-function. It can be replaced by linking with an own
implementation that starts at the global symbol @code{___nmi}. In this case the stdio and
timing functions from vclib can not be used.

@code{___irq} can be used to overwrite the other IRQ vector. The default implementation
in the library immediately returns.

@subsection Floating Point / wozfp

When using floating point, the math library @code{libm.a} must be linked using
the @code{-lm} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on Steve Wozniaks routines from the 70s,
somewhat adapted to the ABI of @code{vbcc}. These functions are small and
reasonably usable, but they do not fully satisfy the requirements of C99.

Only a part of the C library functions for floating point is implemented. The
list currently includes:

@itemize
@item @code{exp()}
@item @code{pow()}
@item @code{log()}
@item @code{log10()}
@end itemize

@subsection Floating Point / IEEE

IEEE floating point is currently not available for this target.


@section 6502/Atari

This is a port of vclib to Atari 8bit computers.

@subsection Startup and Memory

Startup and memory layout is described in the following paragraphs.

@subsubsection Startup

The default linker file creates program files that are loaded to address
0x600. The memory area can be adapted by changing @code{MEMSTART} and
@code{MEMEND} in @code{vlink.cmd}.

With the default configuration, after exiting the C program, it will wait
for pressing the return key before returning to DOS.

@subsubsection Command line

Command line parameters are not yet supported.

@subsubsection Zero Page

@code{vbcc} uses a number of zero page locations for register variables, stack
pointer etc. in section @code{zpage}. Also, variables can be mapped to zero page using
the @code{__zpage} attribute. By default the area @code{0x82..0xFF}
is used, but this can be changed in the linker file.

@subsubsection Stack

By default, the startup code maps the user stack from
@code{MEMTOP-STACKLEN..MEMTOP}.
The size can be changed at the top of @code{vlink.cmd}.

@subsubsection Heap

Code and data/BSS are mapped starting at @code{MEMSTART}.
The heap is placed in the remaining space to stack start.

@subsubsection Banking

Banking support for this target has not yet been implemented.

@subsection Runtime

Apart from standard C library functions, @code{libvc.a} also provides a few
runtime support functions needed by the compiler. Apart from the math and
floating point functions mentioned in the documentation of the 6502 backend,
it includes functions for saving/restoring registers.

@subsection @code{stdio}

At the moment, stdio only supports @code{stdout}, @code{stderr} (both using the
screen) and @code{stdin} (keyboard). Both are line-buffered by default.

@code{printf/scanf} functions which support floating point are contained in
the math library only.


@subsection Floating Point / wozfp

When using floating point, the math library @code{libm.a} must be linked using
the @code{-lm} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on Steve Wozniaks routines from the 70s,
somewhat adapted to the ABI of @code{vbcc}. These functions are small and
reasonably usable, but they do not fully satisfy the requirements of C99.

Only a part of the C library functions for floating point is implemented. The
list currently includes:

@itemize
@item @code{exp()}
@item @code{pow()}
@item @code{log()}
@item @code{log10()}
@end itemize

@subsection Floating Point / IEEE

When using IEEE floating point, @code{-ieee} must be specified and the math library
@code{libmieee.a} must be linked using
the @code{-lmieee} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on SANE,
somewhat adapted to the ABI of @code{vbcc} using wrapper functions.
These functions should be fully C and IEEE compliant and provide precise results for
32 and 64bit floating point numbers (the library actually internally calculates
all operation using 80bits, but vbcc currently only uses up to 64 bits).

Currently, this library probably must be run from RAM.

Most parts of the C library functions for floating point are implemented. The
list currently includes:

@itemize
@item @code{exp(), expf(), expl()}
@item @code{exp2(), exp2f(), exp2l()}
@item @code{exp1m(), exp1mf(), exp1ml()}
@item @code{pow(), powf(), powl()}
@item @code{log(), logf(), logl()}
@item @code{log1p(), log1pf(), log1pl()}
@item @code{log2(), log2f(), log2l()}
@item @code{log10(), log10f(), log10l()}
@item @code{sqrt(), sqrtf(), sqrtl()}
@item @code{sin(), sinf(), sinl()}
@item @code{cos(), cosf(), cosl()}
@item @code{tan(), tanf(), tanl()}
@item @code{atan(), atanf(), atanl()}


@end itemize

@section 6502/BBC Micro/Master

This is a port of vclib to BBC 8bit computers.

@subsection Startup and Memory

Startup and memory layout is described in the following paragraphs.

@subsubsection Startup

The default linker file creates program files that are loaded to address
0x1900 up to 0x7B00 with 256 bytes of software stack. The memory area can be adapted by
changing @code{OSHWM}, @code{HIMEM} and @code{STACKSTART} in @code{vlink.cmd}.

With the default configuration (@code{+bbc}), after exiting the C program, the code will 
enter an endless loop. If the reentrant configs are used (@code{+bbcr} or
@code{+bbcbr}), the program will return to the command prompt. As this
requires saving the zero page, a bit more memory is used.


@subsubsection Command line

If @code{main()} uses arguments, the command line parameters will be passed
accordingly. There are hardcoded limits to the number of arguments (currently 8)
and the maximum total command length (currently 80).

Space is used to separate arguments. The quote character (@code{"}) can be used
to group arguments containing spaces.


@subsubsection Zero Page

@code{vbcc} uses a number of zero page locations for register variables, stack
pointer etc. in section @code{zpage}. Also, variables can be mapped to zero page using
the @code{__zpage} attribute. By default the area @code{0x00..0x90}
is used, but this can be changed in the linker file.

@subsubsection Stack

By default, the startup code maps the user stack from
@code{STACKSTART..HIMEM}.
The size can be changed at the top of @code{vlink.cmd}.

@subsubsection Heap

Code and data/BSS are mapped starting at @code{OSHWM}.
The heap is placed in the remaining space to stack start.

@subsubsection Banking

When using the @code{+bbcb} or @code{bbcbr} configurations, vbcc supports
banked memory, including automated bank-switching. Up to 16 sections of 16K
size are supported. Each section starts at 0x8000.

The corresponding linker
files @code{vlinkb.cmd} and @code{vlinkbr.cmd} can be edited to choose the
banks that are required. Unused banks can be removed by commenting out
(using old-style C-comments) the corresponding entries in the @code{SECTIONS}
part of the linker file. When using bank 1-3 the section in the linker file
could look like this:

@example
  ...

SECTIONS
@{
  text : @{*(text)@} >ram
  .dtors : @{ *(.dtors) @} > ram
  .ctors : @{ *(.ctors) @} > ram
  rodata : @{*(rodata)@} >ram
  data: @{*(data)@} >ram
  init : @{*(init)@} >ram
  zpage (NOLOAD) : @{*(zpage) *(zp1) *(zp2)@} >zero
  bss (NOLOAD): @{*(bss)@} >ram

/*
  b0 : @{.=PAGEADDR; *(text0) *(rodata0) *(data0) *(bss0)
       RESERVE(PAGEADDR+PAGESIZE-.);
      @} >b0 AT>dummy0
*/

  b1 : @{.=PAGEADDR; *(text1) *(rodata1) *(data1) *(bss1)
       RESERVE(PAGEADDR+PAGESIZE-.);
      @} >b1 AT>dummy1

  b2 : @{.=PAGEADDR; *(text2) *(rodata2) *(data2) *(bss2)
       RESERVE(PAGEADDR+PAGESIZE-.);
      @} >b2 AT>dummy2

  b3 : @{.=PAGEADDR; *(text3) *(rodata3) *(data3) *(bss3)
       RESERVE(PAGEADDR+PAGESIZE-.);
      @} >b3 AT>dummy3
/*
  b4 : @{.=PAGEADDR; *(text4) *(rodata4) *(data4) *(bss4)
       RESERVE(PAGEADDR+PAGESIZE-.);
      @} >b4 AT>dummy4
*/

  ...

@end example

During the linking process, apart from the normal output file, a 16K large
image for each bank and a loader script will be generated. E.g. when using banks 
1-3 and using the output file name test, the following files will be generated:

@table @code
@item @code{test}
      The unbanked code/data.

@item @code{test.inf}
      Info file with start address.

@item @code{testb1}
      Image for bank1.

@item @code{testb2}
      Image for bank2.

@item @code{testb2}
      Image for bank2.

@item @code{loadtest}
 Loader

@end table

The contents of the loader @code{loadtest} will look like this:

@example
*srload testb1 8000 1
*srload testb2 8000 2
*srload testb3 8000 3
*run test
@end example

The program can be started with @code{*exec loadtest}.

@subsection Runtime

Apart from standard C library functions, @code{libvc.a} also provides a few
runtime support functions needed by the compiler. Apart from the math and
floating point functions mentioned in the documentation of the 6502 backend,
it includes functions for saving/restoring registers.

@subsection @code{stdio}

@code{stdout}, @code{stderr} (both using the screen) and @code{stdin} (keyboard)
are supported. Furthermore normal file operations are possible using the 
usual C functions. There are hardcoded limits on the maximum number of
simultaneously open files as well as the length of filenames.

Sequential reading and writing is supported, but no seeking. Furthermore, the
@code{remove()} call is supported.

When using stdio to emit VDU control sequences, the function
@code{__vdu_sequence()} is available to ensure verbatim 1:1 transmission
of all characters:

@example
 /* print diagonal line */
 __vdu_sequence(1);
 for(int i=0;i<20;i++)
   printf("\x1f%c%cO",i,i);
 __vdu_sequence(0);
@end example

@code{printf/scanf} functions which support floating point are contained in
the math library only.


@subsection Floating Point / wozfp

When using floating point, the math library @code{libm.a} must be linked using
the @code{-lm} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on Steve Wozniaks routines from the 70s,
somewhat adapted to the ABI of @code{vbcc}. These functions are small and
reasonably usable, but they do not fully satisfy the requirements of C99.

Only a part of the C library functions for floating point is implemented. The
list currently includes:

@itemize
@item @code{exp()}
@item @code{pow()}
@item @code{log()}
@item @code{log10()}
@end itemize

@subsection Floating Point / IEEE

When using IEEE floating point, @code{-ieee} must be specified and the math library
@code{libmieee.a} must be linked using
the @code{-lmieee} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on SANE,
somewhat adapted to the ABI of @code{vbcc} using wrapper functions.
These functions should be fully C and IEEE compliant and provide precise results for
32 and 64bit floating point numbers (the library actually internally calculates
all operation using 80bits, but vbcc currently only uses up to 64 bits).

Currently, this library probably must be run from RAM.

Most parts of the C library functions for floating point are implemented. The
list currently includes:

@itemize
@item @code{exp(), expf(), expl()}
@item @code{exp2(), exp2f(), exp2l()}
@item @code{exp1m(), exp1mf(), exp1ml()}
@item @code{pow(), powf(), powl()}
@item @code{log(), logf(), logl()}
@item @code{log1p(), log1pf(), log1pl()}
@item @code{log2(), log2f(), log2l()}
@item @code{log10(), log10f(), log10l()}
@item @code{sqrt(), sqrtf(), sqrtl()}
@item @code{sin(), sinf(), sinl()}
@item @code{cos(), cosf(), cosl()}
@item @code{tan(), tanf(), tanl()}
@item @code{atan(), atanf(), atanl()}


@end itemize



@section 6502/MEGA65

This is a port of vclib to the MEGA65. This port is intended for the C65 mode
with a C65 or compatible ROM (although the ROM is not used after the
program is started). The C64 configuration can be used to create programs for
the C64 mode.


@subsection Startup and Memory

Startup and memory layout is described in the following paragraphs.

The following basic configurations are available. See below for more details:

@table @code
@item +m65s
      Standard unbanked configuration.

@item +m65sr
      Standard unbanked reentrant configuration.

@item +m65sb
      Standard banked configuration.

@item +m65l
      Large unbanked configuration.

@item +m65lr
      Large unbanked reentrant configuration.

@item +m65lb
      Large banked configuration.

@end table

@subsubsection Startup

The default linker file creates program files that are loaded to address
0x2001. A BASIC line is included so that the program can be started using @code{RUN}
from BASIC. The startup code
will switch to VIC-IV mode, remove write protection of ROM banks, turn on full
speed and change to a suitable mapping.
The BSS segment will be cleared during startup.

There are two sets of configurations that affect the configuration of
upper memory. The standard versions (@code{+m65s, +m65sr, +m65sb})
will keep the IO area mapped in at $D000.
This will limit the contiguous memory block for unbanked configurations to 0xCFFF. 
For banked configurations (see below) it will make a 16K window from
0x8000..0xBFFF available for banking. The large configurations
(@code{+m65l, +m65lr, +m65lb}) will move the upper bound for unbanked programs
to 0xFFFF. With banking, 32K window will be available from 0x8000..0xFFFF.
In both cases the total amount of memory available for banking is the same in
both configurations.

While the large configurations provide larger contiguous memory areas, accesses
to the IO area have to be made through extended 28bit instructions which are
much larger and slower. For programs doing many IO accesses, the standard
configurations are recommended.

With the default configurations, after exiting the C program, an infinite loop will
be entered. When using the reentrant (@code{+m65sr, +m65lr}) configs, the
program will return to BASIC an can be started again.
However, this needs additional memory as the init values for the data section have
to be stored in RAM. Also, some register values and zero page contents have to be
saved. The overhead depends on the amount of initialized variables.

Caution: The current configuration assumes that the Z register always contains 0.
To work correctly, the Z register has to be 0 when C code is
executed. The startup code will set it correctly and the compiler generated code will
not touch it. However, when calling other code you may have to take care
to save/restore the Z register or to set the Z register to 0 again.

@subsubsection Command line

Command line parameters are supported by using the convention/code submitted by
Stefan Haubenthal. 

Command-lines look like these lines:

@example
   run
   run : rem
   run:rem arg1 " arg 2 is quoted "  arg3 "" arg5
@end example



@subsubsection Zero Page

@code{vbcc} uses a number of zero page locations for register variables, stack
pointer etc. in section @code{zpage}. Also, variables can be mapped to zero page using
the @code{__zpage} attribute. By default the area @code{0x02..0xFF}
is used, but this can be changed in the linker file.

@subsubsection Stack

By default, the user stack is mapped from @code{0xB800..0xC000}. For the banked version,
it is mapped from @code{0x7800..0x8000}.  The size can be
changed at the top of @code{vlink.cmd} and @code{vlinkbank.cmd}.

@subsubsection Heap

Code and data/BSS are mapped starting after the BASIC init line.
The heap is placed in the remaining space depending on the configuration.

@subsubsection Banking

The following banking models are supported:

@table @code
@item +m65sb
      16K window at 0x8000 with IO area mapped in at all times.

@item +m65lb
      32K window at 0x8000.
@end table


Automated bank switching is supported in both modes. The mapping of banks to
real memory in the standard configuration is like this:
@example
Unbanked:       0x000000..0x007FFF
Bank0:          0x008000..0x00BFFF
Bank1:          0x00C000..0x00FFFF
Bank2:          0x010000..0x013FFF
Bank3:          0x014000..0x017FFF
         ...
@end example

On the large configuration, it looks like this:
@example
Unbanked:       0x000000..0x007FFF
Bank0:          0x008000..0x00FFFF
Bank1:          0x010000..0x017FFF
Bank2:          0x018000..0x01FFFF
Bank3:          0x020000..0x027FFF
         ...
@end example

In both cases, the program start is moved to 0x1000.
When using the banked configurations, the code can not be simply loaded from
BASIC. The linker will create on large image without any BASIC lines. The
file can be executed from SD-card by using a special loader that can be loaded
from BASIC off a disk or disk image. When specifying a name as command line
argument (see above), the loader will try to load this image from SD-card. If
no argument is given, the loader will look for a file of the same name.
Therefore by renaming the loader it can be made to automatically run a
specific file.

If the loader is on the current disk/image and @code{myimage} on the SD:
@example
LOAD "LOADER"
RUN:REM MYIMAGE
@end example

After renaming @code{LOADER} to @code{MYIMAGE}, it can be done like this:
@example
RUN "MYIMAGE"
@end example

The colour RAM will be relocated to 0xFF80800 before loading to avoid being
overwritten through the window at 0x1F800.

@subsection Runtime

Apart from standard C library functions, @code{libvc.a} also provides a few
runtime support functions needed by the compiler. Apart from the math and
floating point functions mentioned in the documentation of the 6502 backend,
it includes functions for saving/restoring registers.

@subsection @code{stdio}

At the moment, stdio only supports @code{stdout}, @code{stderr} (both using the
screen) and @code{stdin} (keyboard). Both are unbuffered by default.
Using those streams will directly access the screen buffer and keyboard
hardware. No ROM functions are needed once the program runs.

Furthermore it is possible to read files on the SD-card using standard
C functions after opening them using @code{fopen()}. Hyppo services are
used to read those files. There are several limitations due to the
restrictions of Hyppo:

@itemize
@item Files can only be read sequentially, no seeking etc.
@item Files can not be written to.
@item Only one file can be open at the same time.
@end itemize


@code{printf/scanf} functions which support floating point are contained in
the math library only.

@subsection Multiplication/Division

When generating code for the MEGA65, @code{vbcc} will make use of hardware
multiplier/divider. This can greatly improve performance of such operations.
Please note the following issues:

@itemize
@item Some versions of the MEGA65 core contain a bug in the hardware divider
      which will calculate wrong results in certain cases. As workaround you can
      specify option @code{-div-bug} to use (much slower) 6502 software
      routines instead. Multiplication is not affected by the bug and will still
      be using the hardware multiplier.

@item The hardware multiplier registers are mapped in the IO area. When using
      the large configurations (@code{+m65l, +m65lr, +m65lb}), they can only
      be accessed using extended 28bit instructions. The code generator and
      library functions will handle this, but there is some overhead (still
      nowhere near using software multiplication). If your code is speed
      critical and uses many multiplications we strongly recomment to use
      the standard configurations (@code{+m65s, +m65sr, +m65sb}). Those will
      set the option @code{-m65io} that tells @code{vbcc} to use faster
      direct IO accesses.
@end itemize
      
@subsection Interrupts

The provided configurations will disable interrupts on the MEGA65. All the
library functions are written to work with disabled interrupts and do not use
any ROM routines. The interrupt handlers in existing C65 ROMs do not work well
with assembly language code and deficiencies in the mapping hardware make it
very hard to use the ROM in a non-BASIC environment.

If an application wants to use interrupts, interrupt vectors have to be
installed at 0xFFFA..0xFFFF. Take care that there are always valid vectors
visible at this address (especially in a banked configuration). Also take
care that those always point to a valid handler that is visible (i.e. do
not use an ISR in banked memory).


@subsection Floating Point / wozfp

When using floating point, the math library @code{libm.a} must be linked using
the @code{-lm} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on Steve Wozniaks routines from the 70s,
somewhat adapted to the ABI of @code{vbcc}. These functions are small and
reasonably usable, but they do not fully satisfy the requirements of C99.

Only a part of the C library functions for floating point is implemented. The
list currently includes:

@itemize
@item @code{exp()}
@item @code{pow()}
@item @code{log()}
@item @code{log10()}
@end itemize

@subsection Floating Point / IEEE

When using IEEE floating point, @code{-ieee} must be specified and the math library
@code{libmieee.a} must be linked using
the @code{-lmieee} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on SANE,
somewhat adapted to the ABI of @code{vbcc} using wrapper functions.
These functions should be fully C and IEEE compliant and provide precise results for
32 and 64bit floating point numbers (the library actually internally calculates
all operation using 80bits, but vbcc currently only uses up to 64 bits).

Currently, this library probably must be run from RAM.

Most parts of the C library functions for floating point are implemented. The
list currently includes:

@itemize
@item @code{exp(), expf(), expl()}
@item @code{exp2(), exp2f(), exp2l()}
@item @code{exp1m(), exp1mf(), exp1ml()}
@item @code{pow(), powf(), powl()}
@item @code{log(), logf(), logl()}
@item @code{log1p(), log1pf(), log1pl()}
@item @code{log2(), log2f(), log2l()}
@item @code{log10(), log10f(), log10l()}
@item @code{sqrt(), sqrtf(), sqrtl()}
@item @code{sin(), sinf(), sinl()}
@item @code{cos(), cosf(), cosl()}
@item @code{tan(), tanf(), tanl()}
@item @code{atan(), atanf(), atanl()}


@end itemize

@section 6502/X16

This is a port of vclib to the Commander X16.


@subsection Startup and Memory

Startup and memory layout is described in the following paragraphs.

@subsubsection Startup

The default linker file creates program files that are loaded to address
0x801. A BASIC line is included so that the program can be started using @code{RUN}
from BASIC. The startup code
will turn off the BASIC ROM to allow usage of RAM until 0x9F00 and most of the
zero page without need for any special handling. The BSS segment will be cleared
during startup.

With the default configuration, after exiting the C program, an infinite loop will
be entered. When using the @code{+x16r} config, the program will return to BASIC
an can be started again.
However, this needs additional memory as the init values for the data section have
to be stored in RAM. Also, some register values and zero page contents have to be
saved. The overhead depends on the amount of initialized variables.

@subsubsection Command line

Command line parameters are supported by using the convention/code submitted by
Stefan Haubenthal. 

Command-lines look like these lines:

@example
   run
   run : rem
   run:rem arg1 " arg 2 is quoted "  arg3 "" arg5
@end example



@subsubsection Zero Page

@code{vbcc} uses a number of zero page locations for register variables, stack
pointer etc. in section @code{zpage}. Also, variables can be mapped to zero page using
the @code{__zpage} attribute. By default the area @code{0x02..0x7e}
is used, but this can be changed in the linker file.

@subsubsection Stack

By default, the user stack is mapped from @code{0x9700..0x9F00}. The size can be
changed at the top of @code{vlink.cmd}.

@subsubsection Heap

Code and data/BSS are mapped starting after the BASIC init line.
The heap is placed in the remaining space to stack start.

@subsubsection Banking

Banking support for this target is not yet implemented.


@subsection Runtime

Apart from standard C library functions, @code{libvc.a} also provides a few
runtime support functions needed by the compiler. Apart from the math and
floating point functions mentioned in the documentation of the 6502 backend,
it includes functions for saving/restoring registers.

@subsection @code{stdio}

At the moment, stdio only supports @code{stdout}, @code{stderr} (both using the
screen) and @code{stdin} (keyboard). Both are unbuffered by default.

@code{printf/scanf} functions which support floating point are contained in
the math library only.


@subsection Floating Point / wozfp

When using floating point, the math library @code{libm.a} must be linked using
the @code{-lm} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on Steve Wozniaks routines from the 70s,
somewhat adapted to the ABI of @code{vbcc}. These functions are small and
reasonably usable, but they do not fully satisfy the requirements of C99.

Only a part of the C library functions for floating point is implemented. The
list currently includes:

@itemize
@item @code{exp()}
@item @code{pow()}
@item @code{log()}
@item @code{log10()}
@end itemize

@subsection Floating Point / IEEE

When using IEEE floating point, @code{-ieee} must be specified and the math library
@code{libmieee.a} must be linked using
the @code{-lmieee} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on SANE,
somewhat adapted to the ABI of @code{vbcc} using wrapper functions.
These functions should be fully C and IEEE compliant and provide precise results for
32 and 64bit floating point numbers (the library actually internally calculates
all operation using 80bits, but vbcc currently only uses up to 64 bits).

Currently, this library probably must be run from RAM.

Most parts of the C library functions for floating point are implemented. The
list currently includes:

@itemize
@item @code{exp(), expf(), expl()}
@item @code{exp2(), exp2f(), exp2l()}
@item @code{exp1m(), exp1mf(), exp1ml()}
@item @code{pow(), powf(), powl()}
@item @code{log(), logf(), logl()}
@item @code{log1p(), log1pf(), log1pl()}
@item @code{log2(), log2f(), log2l()}
@item @code{log10(), log10f(), log10l()}
@item @code{sqrt(), sqrtf(), sqrtl()}
@item @code{sin(), sinf(), sinl()}
@item @code{cos(), cosf(), cosl()}
@item @code{tan(), tanf(), tanl()}
@item @code{atan(), atanf(), atanl()}


@end itemize

@section 6502/PET

This is a port of vclib to the CBM PET series of computers.

@subsection Startup and Memory

Startup and memory layout is described in the following paragraphs.

@subsubsection Startup

The default linker file creates program files that are loaded to address
0x401. A BASIC line is included so that the program can be started using @code{RUN}
from BASIC. RAM is available until 0x7FFF and most of the
zero page without need for any special handling. The BSS segment will be cleared
during startup.

With the default configuration, after exiting the C program, an infinite loop will
be entered. When using the @code{+petr} config, the program will return to BASIC
an can be started again.
However, this needs additional memory as the init values for the data section have
to be stored in RAM. Also, some register values and zero page contents have to be
saved. The overhead depends on the amount of initialized variables.

@subsubsection Command line

Command line parameters are supported by using the convention/code submitted by
Stefan Haubenthal. 

Command-lines look like these lines:

@example
   run
   run : rem
   run:rem arg1 " arg 2 is quoted "  arg3 "" arg5
@end example



@subsubsection Zero Page

@code{vbcc} uses a number of zero page locations for register variables, stack
pointer etc. in section @code{zpage}. Also, variables can be mapped to zero page using
the @code{__zpage} attribute. By default the area @code{0x02..0x8d}
is used, but this can be changed in the linker file.

@subsubsection Stack

By default, the user stack is mapped from @code{0x7F00..0x7FFF}. The size can be
changed at the top of @code{vlink.cmd}.

@subsubsection Heap

Code and data/BSS are mapped starting after the BASIC init line.
The heap is placed in the remaining space to stack start.

@subsubsection Banking

Automated banking is currently not supported.


@subsection Runtime

Apart from standard C library functions, @code{libvc.a} also provides a few
runtime support functions needed by the compiler. Apart from the math and
floating point functions mentioned in the documentation of the 6502 backend,
it includes functions for saving/restoring registers.

@subsection @code{stdio}

At the moment, stdio only supports @code{stdout}, @code{stderr} (both using the
screen) and @code{stdin} (keyboard). Both are unbuffered by default.

@code{printf/scanf} functions which support floating point are contained in
the math library only.


@subsection Floating Point / wozfp

When using floating point, the math library @code{libm.a} must be linked using
the @code{-lm} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on Steve Wozniaks routines from the 70s,
somewhat adapted to the ABI of @code{vbcc}. These functions are small and
reasonably usable, but they do not fully satisfy the requirements of C99.

Only a part of the C library functions for floating point is implemented. The
list currently includes:

@itemize
@item @code{exp()}
@item @code{pow()}
@item @code{log()}
@item @code{log10()}
@end itemize

@subsection Floating Point / IEEE

When using IEEE floating point, @code{-ieee} must be specified and the math library
@code{libmieee.a} must be linked using
the @code{-lmieee} option. It contains the floating routines as well as versions of
the @code{printf/scanf} family that support floating point.

The floating point routines are based on SANE,
somewhat adapted to the ABI of @code{vbcc} using wrapper functions.
These functions should be fully C and IEEE compliant and provide precise results for
32 and 64bit floating point numbers (the library actually internally calculates
all operation using 80bits, but vbcc currently only uses up to 64 bits).

Currently, this library probably must be run from RAM.

Most parts of the C library functions for floating point are implemented. The
list currently includes:

@itemize
@item @code{exp(), expf(), expl()}
@item @code{exp2(), exp2f(), exp2l()}
@item @code{exp1m(), exp1mf(), exp1ml()}
@item @code{pow(), powf(), powl()}
@item @code{log(), logf(), logl()}
@item @code{log1p(), log1pf(), log1pl()}
@item @code{log2(), log2f(), log2l()}
@item @code{log10(), log10f(), log10l()}
@item @code{sqrt(), sqrtf(), sqrtl()}
@item @code{sin(), sinf(), sinl()}
@item @code{cos(), cosf(), cosl()}
@item @code{tan(), tanf(), tanl()}
@item @code{atan(), atanf(), atanl()}


@end itemize