[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

12. C Library

This chapter describes the C library usually provided with vbcc.


12.1 Introduction

To execute code compiled by 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. ‘vc.lib’ or ‘libvc.a’).

Often, floating point code (if available) is stored in a different file (e.g. ‘m.lib’ or ‘libm.a’). If floating point is used in an application, it might be necessary to explicitly link with this library (e.g. by specifying ‘-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 small number of the new functions from ISO9899:1999.


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

 
 * ====================================================
 * 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.
 * ====================================================

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

 
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.

12.3 Embedded Systems

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


12.3.1 Startup

The startup is usually split into two parts. The first part is done by assembly code that produces the object 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:

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

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

- 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 __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):

 
#define STACKSIZE <whatever>

static long mystack[STACKSIZE/sizeof(long)];
char *__stack=((char*)mystack)+STACKSIZE;
- calling __main

After all the above initializations have been performed, the function __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 main() function. Note that the library may not work correctly if the user main() function is called directly from the startup code.


12.3.2 Heap

When dynamic memory management is used (e.g. by using the malloc() function), a heap memory area is needed to allocate memory from. The malloc() function assumes that __heapptr is a variable pointing to the beginning of the heap memory and that __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:

 
#define HEAPSIZE <whatever>

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

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

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

The __open() function receives a name and a mode string (as in the C 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.

Also, stdin, stdout and stderr can be used with the standard descriptors.


12.3.4 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 ‘-lm’) when floating point is used.


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

- locale
- time
- signal
- filesystem functions

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.


12.3.6 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 __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.


12.4 AmigaOS/68k

This section describes specifics of the C library for AmigaOS/68k. The relevant files are ‘startup.o’, ‘minstart.o’, ‘vc.lib’, ‘vcs.lib’, ‘mieee.lib’, ‘mieees.lib’, ‘m881.lib’, ‘m881s.lib’, ‘m040.lib’, ‘m040s.lib’ ‘amiga.lib’, ‘amigas.lib’, ‘auto.lib’ and ‘autos.lib’.

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


12.4.1 Startup

The startup code currently consists of a slightly modified standard Amiga startup (‘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.


12.4.2 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 three math libraries:

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 ‘-fpu=...’ when you use this library.

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 ‘-fpu=68881’. Several FPU instructions that have to be emulated on 040/060 may be used.

m040.lib

This one uses only direct FPU instructions that do not have to be emulated on a 040/060. Other functions use the Motorola emulation routines modified by Aki M Laukkanen. It should be used for programs compiled for 040 or 060 with FPU. Return values are passed in fp0.

Depending on the CPU/FPU selected, #including ‘math.h’ will cause inline-code generated for certain math functions.


12.4.3 Stack

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

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

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 ‘-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 ‘-stack-check’ or calls to OS function may cause a stack overflow which is not noticed.

Additionally, if ‘-stack-check’ is used, the maximum stack-size used can be read by querying the external variable __stack_usage.

 
#include <stdio.h>

extern size_t __stack_usage;

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

Like above, the stack used by functions not compiled using ‘-stack-check’ or OS functions is ignored.


12.4.4 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

 
vc test.c -o test -sd -lvcs -lamigas

might be used.


12.4.5 Restrictions

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

tmpfile()

The tmpfile() function always returns an error.

clock()

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


12.4.6 Minimal startup

If you want to write programs that use only Amiga functions and none from vc.lib you can use ‘minstart.o’ instead of ‘startup.o’ and produce smaller executables.

This is only useful for people who know enough about the Amiga shared libraries, the stubs in amiga.lib etc. If you do not know enough about those things better forget minstart at all.

This startup code does not set up all the things needed by vc.lib, so you must not use most of those functions (string and ctype funtions are ok, but most other functions - especially I/O and memory handling - must not be used). exit() is supplied by minstart and can be used.

The command line is not parsed, but passed to main() as a single string, so you can declare main as int main(char *command) or int main(void).

Also no Amiga libraries are opened (but SysBase ist set up), so you have to define and open DOSBase yourself if you need it. If you want to use floating point with the IEEE libraries 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:

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

This can yield an executable of under 300 bytes when compiled with ‘-sc -sd -O2’ and linked with ‘minstart.o’ and amigas.lib (using vlink - may not work with other linkers).


12.4.7 amiga.lib

To write programs accessing AmigaOS (rather than standard C functions only), a replacement for the original (copyrighted) ‘amiga.lib’ is provided with vbcc. This replacement is adapted to vbcc, does not cause collisions with some functions (e.g. sprintf) provided by the original ‘amiga.lib’ and is available in small data. It is recommended to always use this library rather than the original version.

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

Specify ‘-lamiga’ to link with ‘amiga.lib’.


12.4.8 auto.lib

To link with ‘auto.lib’ (or the small data version ‘autos.lib’) specify the ‘-lauto’ or ‘-lautos’ option to vc.

When you are calling a standard Amiga library function and do not have defined the corresponding library base then the library base as well as code to open/close it will be taken from ‘auto.lib’.

By default, ‘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):

 
        int _IntuitionBaseVer = 39;

Note that your program will abort before reaching main() if one of the libraries cannot be opened. Also note that the dos.library will be openened by the standard startup code, not by auto.lib. This means you have to open dos.library yourself, when linking with ‘minstart.o’.


12.5 PowerUp/PPC

This section describes specifics of the C library for PowerUp/PPC. The relevant files are ‘startup.o’, ‘minstart.o’, ‘libvc.a’, ‘libvcs.a’, ‘libm.a’, ‘libms.a’ ‘libamiga.a’, ‘libamigas.a’, ‘libauto.a’ and ‘libautos.a’.

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


12.5.1 Startup

The startup code ‘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.


12.5.2 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 (‘libm.a’) is linked against the floating point library libmoto by Motorola.

Depending on the CPU/FPU selected, #including ‘math.h’ will cause inline-code generated for certain math functions.


12.5.3 Stack

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


12.5.4 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

 
vc test.c -o test -sd -lvcs -lamigas

might be used.


12.5.5 Restrictions

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

tmpfile()

The tmpfile() function always returns an error.

clock()

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


12.5.6 Minimal startup

The provided minimal startup code (‘minstart.o’) is used similarly like the one for 68k (See section Minimal startup). Only use it if you know what you are doing.


12.5.7 libamiga.a

To write programs accessing AmigaOS (rather than standard C functions only), a replacement for the original (copyrighted) ‘amiga.lib’ is provided with vbcc. This replacement (‘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. sprintf) provided by the original ‘amiga.lib’ and is available in small data.

Specify ‘-lamiga’ to link with ‘libamiga.a’.


12.5.8 libauto.a

This library corresponds to the AmigaOS/68k version (See section auto.lib).


12.6 WarpOS/PPC

This section describes specifics of the C library for WarpOS/PPC. The relevant files are ‘startup.o’, ‘vc.lib’, ‘m.lib’, ‘amiga.lib’ and ‘auto.lib’.

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


12.6.1 Startup

The startup code ‘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.


12.6.2 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 (‘m.lib’) contains functions from Sun’s portable floating point library. Additionally, there is a vbcc version of Andreas Heumann’s ‘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 ‘ppcmath.lib’ before ‘m.lib’, e.g.

 
    vc test.c -lppcmath -lm

Depending on the CPU/FPU selected, #including ‘math.h’ will cause inline-code generated for certain math functions.


12.6.3 Stack

Stack-handling is similar to AmigaOS/68k (See section Stack).


12.6.4 Restrictions

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

tmpfile()

The tmpfile() function always returns an error.

clock()

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


12.6.5 amiga.lib

To write programs accessing AmigaOS (rather than standard C functions only), a replacement for the original (copyrighted) ‘amiga.lib’ is provided with 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. sprintf) provided by the original ‘amiga.lib’ and is available in small data.

Specify ‘-lamiga’ to link with ‘amiga.lib’.


12.6.6 auto.lib

This library corresponds to the AmigaOS/68k version (See section auto.lib).


12.7 MorphOS/PPC

This section describes specifics of the C library for MorphOS/PPC. The relevant files are ‘startup.o’, ‘minstart.o’, ‘libvc.a’, ‘libvcs.a’, ‘libm.a’, ‘libms.a’ ‘libamiga.a’, ‘libamigas.a’, ‘libauto.a’ and ‘libautos.a’.

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


12.7.1 Startup

The startup code ‘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.


12.7.2 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 (‘libm.a’) is linked against the floating point library libmoto by Motorola.

Depending on the CPU/FPU selected, #including ‘math.h’ will cause inline-code generated for certain math functions.


12.7.3 Stack

Stack-handling is similar to AmigaOS/68k (See section Stack).


12.7.4 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

 
vc test.c -o test -sd -lvcs -lamigas

might be used.


12.7.5 Restrictions

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

tmpfile()

The tmpfile() function always returns an error.

clock()

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


12.7.6 libamiga.a

To write programs using AmigaOS compatible functions, a replacement for the original (copyrighted) ‘amiga.lib’ is provided with vbcc. This replacement (‘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. sprintf) and is available in small data.

Specify ‘-lamiga’ to link with ‘libamiga.a’.


12.7.7 libauto.a

This library corresponds to the AmigaOS/68k version (See section auto.lib).


12.8 AmigaOS4/PPC

This section describes specifics of the C library for AmigaOS4/PPC. The relevant files are ‘startup.o’, ‘minstart.o’, ‘libvc.a’, ‘libvcs.a’, ‘libm.a’, ‘libms.a’ ‘libamiga.a’, ‘libamigas.a’, ‘libauto.a’ and ‘libautos.a’.

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


12.8.1 Startup

The startup code ‘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.


12.8.2 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 (‘libm.a’) is linked against the floating point library libmoto by Motorola.

Depending on the CPU/FPU selected, #including ‘math.h’ will cause inline-code generated for certain math functions.


12.8.3 Stack

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


12.8.4 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

 
vc test.c -o test -sd -lvcs -lamigas

might be used.


12.8.5 Dynamic linking

Since ‘elf.libraryV52.2 AmigaOS4 supports dynamic linking with shared object files (‘.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 ‘-static’ option to the ‘vc’ frontend.


12.8.6 Restrictions

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

tmpfile()

The tmpfile() function always returns an error.

clock()

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

Small data in dynamically linked executables

There is a bug in ‘elf.libraryV52.4 (and earlier), which doesn’t load .sdata and .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.


12.8.7 libamiga.a

In contrast to other amigalibs the OS4 ‘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 CreateIO(), but its use is discouraged.

Specify ‘-lamiga’ to link with ‘libamiga.a’.


12.8.8 libauto.a

Auto-open -close functions for the following libraries are included:

Asl, CyberGfx, DataTypes, Dos, GadTools, Graphics, Icon, IFFParse, Intuition, Locale, LowLevel, Picasso96, BSDSocket, Utility, Workbench

Note that gcc’s ‘libauto.a’ doesn’t include CyberGfx.


12.8.9 newlib


12.8.9.1 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 ‘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?

Things you should note:


12.8.9.2 Usage

To compile a program to use newlib for OS4 you must make sure the proper config-file (‘newlib’) is used, e.g.

 
        vc +newlib hello.c

With a new SDK this will usually generate a dynamically linked executable, which requires ‘libc.so’. To force a statically linked executable:

 
        vc +newlib -static hello.c

12.9 Atari TOS/MiNT

This section describes specifics of the C library for Atari TOS and MiNT. M680x0 processors are supported by the target ‘m68k-atari’, while ColdFire processors are supported by the target ‘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 ‘startup.o’, ‘minstart.o’, ‘libvc.a’, ‘libvc16.a’, ‘libm.a’, ‘libm16.a’.

The following config files are available:

tos

M68k 32-bit int

tos16

M68k 16-bit int

toscf

ColdFire 32-bit int


12.9.1 Startup

The startup code ‘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.


12.9.2 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 (‘libm.a’) is a soft-float library, which is compatible with all the Atari models without an FPU. There may be real FPU support in future updates.


12.9.3 Stack

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

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


12.9.4 16-bit integer model

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

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

 
vc +tos16 test.c -o test -lm16 -lvc16

may be used. There are no 16-bit versions for ColdFire targets, because this is strictly a 32-bit CPU.


12.9.5 Restrictions

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

tmpfile()

The tmpfile() function always returns an error.

clock()

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


12.10 VideoCore/Linux

This section describes specifics of the C library for VideoCore under Linux.

The relevant files are vcload, ‘startup.o’, ‘libvc.a’, ‘libm.a’, ‘libms.a’.

The config file vc4-linux is part of the library.


12.10.1 Startup

The startup code ‘startup.o’ sets up stack and heap and provides a function __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.


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


12.10.3 Stack

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

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

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

 
#define HEAPSIZE <desired size>

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

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


12.10.5 System Calls

To access system functions from the VideoCore-side, the function __armcall() can be used. It will save the current context and return to the loader. Registers 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.


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


12.10.6.1 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 ‘.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.


12.10.6.2 Command line arguments

vcload [-debug] [-cache] [-offset] <image-name>

The loader currently has the following options:

-debug

The loader will enter debug mode (see below).

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

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


12.10.6.3 Debug Mode

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

The following commands are available:

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.

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.

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.

c

Start/continue execution.

q

Quit.

bp <addr>

Set a breakpoint at <addr>.

This is currently a very crude implementation. It will just write a branch to __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!


12.10.7 Restrictions

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


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by vb on January 3, 2015 using texi2html 1.82.