mirror of
https://github.com/adtools/clib2.git
synced 2025-12-08 14:59:05 +00:00
f81dfdfca7
git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@14982 87f5fb63-7c3d-0410-a384-fd976d0f7a62
305 lines
16 KiB
HTML
305 lines
16 KiB
HTML
<!DOCTYPE html public "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<html>
|
|
<head>
|
|
<title>An ISO 'C' (1994) compliant runtime library for the Amiga</title>
|
|
<body>
|
|
|
|
<h1>An ISO 'C' (1994) compliant runtime library for the Amiga</h1>
|
|
|
|
<h2>1. What is this?</h2>
|
|
|
|
<p>This is my attempt to get Samba 2.2.x ported to the Amiga. My first Amiga
|
|
port required SAS/C and a number of strange tricks had to be pulled to get
|
|
it to support the kind of environment Samba needed. But with the
|
|
introduction of Samba 2.2.x many of those tricks did not work any more,
|
|
which is why I decided to attack the problem at the root, namely the
|
|
runtime library.</p>
|
|
|
|
<p>Because it was no longer possible to build Samba with SAS/C on the new
|
|
Amiga platform, the idea came up to move development to the GNU 'C'
|
|
compiler. This turned out to be a challenge due to its somewhat
|
|
underdeveloped runtime library and header files. Eventually, I decided to
|
|
rewrite that library from scratch.</p>
|
|
|
|
|
|
<h2>2. What does it do?</h2>
|
|
|
|
<p>Using <i>'C' - A reference manual</i> (4th edition) as a reference I wrote a set of
|
|
header files, then proceeded to implement each single function referenced in
|
|
them. With few exceptions in the area of wide character support, the result
|
|
should be a feature complete implementation of the ISO 'C' (1994) runtime
|
|
library.</p>
|
|
|
|
<p>Because Samba needs a few POSIX-like routines to be supported, the library
|
|
functionality is complemented by a set of routines described in <i>Advanced
|
|
programming in the Unix environent</i>.</p>
|
|
|
|
<p>This is not a portable implementation of the library in the sense that you
|
|
could move it from one 'C' compiler on one operating system to another.
|
|
This is an Amiga specific implementation.</p>
|
|
|
|
<p>The library supports floating point math, which, for the 68k platform, is
|
|
limited to IEEE single and double precision or M68881 inline math. There is no
|
|
support for the fast floating point (FFP) format or exclusive IEEE single
|
|
precision. You either get double precision (IEEE math) or extended precision
|
|
(M68881 inline math). What it is that you get is determined at compile time.
|
|
Use the <tt>IEEE_FLOATING_POINT_SUPPORT</tt> preprocessor symbol to activate IEEE math
|
|
code and the <tt>M68881_FLOATING_POINT_SUPPORT</tt> symbol for M68881 inline math.</p>
|
|
|
|
<p>For the PowerPC platform, the library uses code borrowed from fdlibm 5.3,
|
|
which is a portable library of arithmetic functions developed by Sun
|
|
Microsystems which, for example, is also used within the Java platform.</p>
|
|
|
|
<p>Not unlike SAS/C, you can configure a minimum stack size the program is to use
|
|
when it starts up. This is controlled via the <tt>__stack_size</tt> variable (see
|
|
<tt>stdlib_main.c</tt>).</p>
|
|
|
|
<p>I added some <tt>amiga.lib</tt> and <tt>debug.lib</tt> functionality to the library, but don't
|
|
count on it to be complete.</p>
|
|
|
|
<h3>2.1 Thread-safety</h3>
|
|
|
|
<p>The library code is supposed to be thread-safe if built with the <tt>__THREAD_SAFE</tt>
|
|
preprocesssor symbold defined. Note that 'thread-safe' does <em>not</em> mean
|
|
'reentrant'. Multiple callers for certain library functions are permitted, but
|
|
not for all of them. For example, <tt>mkdtemp()</tt> is not thread-safe, and neither is
|
|
<tt>rand()</tt> or <tt>localtime()</tt>. But as per <b>POSIX 1003.1c-1995</b> there are thread-safe
|
|
variants of <tt>rand()</tt> and <tt>localtime()</tt> called <tt>rand_r()</tt>, <tt>localtime_r()</tt>, and others.
|
|
The use of the socket I/O functions is still problematic because the
|
|
underlying <tt>bsdsocket.library</tt> API is not supposed to be used by any process
|
|
other than the one that opened it. Also yet unsolved is the issue of reading
|
|
error codes from the <tt>errno</tt> variable which currently always contains the
|
|
error code left by the last caller.</p>
|
|
|
|
|
|
<h2>3. What does it not do?</h2>
|
|
|
|
<p>This library is a departure from the typical 'C' runtime environments of the
|
|
past which had to run on all AmigaOS releases, down to Kickstart 1.1. This
|
|
very library was designed to take advantage of the routines available since
|
|
Kickstart 2.04 was introduced and virtually nobody ever put to use. This helps
|
|
to cut the code size, and it also helps to keep bugs out of the library by
|
|
falling back onto well-tested implementations. However, the catch is that the
|
|
code won't run under Kickstart 1.3 and below. But then these operating system
|
|
releases have been obsolete for more than a decade, and you can always go back
|
|
to a compiler environment which supports them.</p>
|
|
|
|
<p>There is very little support for <tt>amiga.lib</tt> functionality. There is <tt>NewList()</tt>,
|
|
<tt>HookEntry()</tt>, <tt>CallHook()</tt>, <tt>CallHookA()</tt>, the <tt>DoMethod()</tt> family, the RexxVars
|
|
family, but that's all. If you need more, you would have to implement it
|
|
yourself. Put another way, if you absolutely need functionality that is only
|
|
found in <tt>amiga.lib</tt>, you really shouldn't need in in the first place.</p>
|
|
|
|
|
|
<h2>4. Where does the source code come from?</h2>
|
|
|
|
<p>I originally thought that it might be helpful to piece this library together
|
|
from various sources, such as the BSD libc. Turned out that this code was so
|
|
'portable' that it became much more complex than it ought to be. Also, some
|
|
side-effects were present which considerably changed the behaviour of the
|
|
library. For example, the BSD libc uses <tt>bcopy()</tt> as an alias for <tt>memcpy()</tt>, and
|
|
unlike <tt>memcpy()</tt> is documented to, <tt>bcopy()</tt> supports overlapping copies.</p>
|
|
|
|
<p>Eventually, I wrote virtually all the code myself, borrowing algorithmic ideas
|
|
from the BSD libc and the Manx Aztec 'C' runtime library. Because I don't know
|
|
much about the environment GCC expects, I borrowed code snippets from libnix,
|
|
which was written by Matthias Fleischer and Gunther Nikl. This in particular
|
|
concerns the integer and floating point math support, the <tt>setjmp</tt>/<tt>longjmp</tt>
|
|
routines and the startup code. The M68881 inline math code comes from the
|
|
<tt><math-68881.h></tt> file written by Matthew Self <tt>(self@bayes.arc.nasa.gov)</tt>.</p>
|
|
|
|
|
|
<h2>5. Limitations and caveats</h2>
|
|
|
|
<p>There is hardly any documentation on the code I wrote. In part this is due to
|
|
the fact that the code itself is very simple in design. It should speak for
|
|
itself. However, to make a usable runtime library you have to have a user
|
|
documentation as in man pages or autodocs. We will eventually have to have
|
|
autodocs for this library.</p>
|
|
|
|
<p>The code is currently plastered with assertions and debug code. It is
|
|
therefore much larger than it ought to be and runs much slower than it ought
|
|
to be. For example, the <tt>malloc()</tt> routine will set the contents of the memory
|
|
allocated to a 'dirty' bit pattern which is likely to break software which
|
|
makes assumptions about its contents. Likewise, the <tt>free()</tt> routine will trash
|
|
the memory to deallocate with a different 'dirty' bit pattern to turn up reuse
|
|
of memory after deallocation. All these debugging features can be disabled by
|
|
defining the <tt>NDEBUG</tt> preprocessor symbol at compile time (see <tt><assert.h></tt>).</p>
|
|
|
|
<p>The exception handling in the math code is not particularly effective. For one
|
|
part this is due to the fact that there is no exception handler installed by
|
|
the runtime library when it starts up which could catch and process the error
|
|
conditions the CPU or FPU generates. The idea was to provide for a portable
|
|
runtime library with little to no assembly language involved. To make the
|
|
exception handling complete, such code would be necessary.</p>
|
|
|
|
<p>The library currently builds under SAS/C, but because the 'normal' program
|
|
startup code is not utilized, the base relative (A4) addressing does not work.
|
|
If you are going to test it, use the <tt>data=faronly</tt> option to compile the
|
|
library and the programs.</p>
|
|
|
|
<p>Different build makefiles are supplied for use with GCC. There is
|
|
<tt>GNUmakefile.68k</tt> for the 68k platform and <tt>GNUmakefile.os4</tt> for the AmigaOS4
|
|
PowerPC version.</p>
|
|
|
|
<h3>5.1 Floating point math and functions (<tt>scanf()</tt>, <tt>printf()</tt>, etc.) </h3>
|
|
|
|
<p>The plain <tt>libc.a</tt>, which your software would be linked against by default, does not contain
|
|
any floating point support code. This means, for example, that <tt>printf("%f",...)</tt> will not produce
|
|
the desired output and that <tt>scanf("%f",...)</tt> may not read any data at all. If your
|
|
program needs functions such as these or <tt>atod()</tt> then you must link against <tt>libm.a</tt> or
|
|
the equivalent.</p>
|
|
|
|
<p>To link the floating point support code with your software, use the <tt>-lm</tt> compiler option. Careful!
|
|
The order in which you specify the libraries to link against is important here. Thus, <tt>gcc -o test test.c -lm -lc</tt>
|
|
would correctly link the program <tt>test</tt> against the proper floating point math library, but
|
|
<tt>gcc -o test test.c -lc -lm</tt> would not.</p>
|
|
|
|
<h3>5.2 The thread-safe library</h3>
|
|
|
|
<p>Thread-safety does not imply that you can have multiple callers
|
|
access and close the same file. There is no resource tracking to that degree
|
|
yet. All that the thread-safety tries to afford you is not to get into big trouble
|
|
if simultaneous and overlapping accesses to files, memory allocation and other
|
|
resources are taking place.</p>
|
|
|
|
<p> Also take care with file I/O involving the <tt>stdin</tt>/<tt>stdout</tt>/<tt>stderr</tt>
|
|
streams; read/write operations on these streams will be mapped to the <tt>Input()</tt>/</tt>Output()</tt>/<tt>ErrorOutput()</tt>
|
|
file handles of the process performing these operations. Since only this small set of
|
|
operations is mapped, functions such as <tt>fcntl()</tt> or <tt>select()</tt> will not
|
|
work on the <tt>stdin</tt>/<tt>stdout</tt>/<tt>stderr</tt> streams and the corresponding
|
|
file descriptors <tt>STDIN_FILENO</tt>/<tt>STDOUT_FILENO</tt>/<tt>STDERR_FILENO</tt>.
|
|
It is therefore strongly recommended to use the thread-safe library only for applications
|
|
which can cope with the limitations described above.</p>
|
|
|
|
<h3>5.3 Using gmon (PowerPC only)</h3>
|
|
|
|
<p>To use profiling, two steps are required. First of all, your program must be compiled with
|
|
the gcc command line option <tt>-pg</tt>. This instructs the compiler to generate special
|
|
profiling code in the prologue and epilogue of each function. Additionally, the program
|
|
must be linked with <tt>libprofile.a</tt>. To do this, either manually add
|
|
<tt>-lprofile</tt> to the linker command line, or modify the specs file as follows.
|
|
Find the lines that look like this (it may actually differ silghtily from your specs file,
|
|
but the important thing is that the line before the line to be modified reads <tt>lib:</tt>):
|
|
<pre>
|
|
lib:
|
|
--start-group -lc --end-group
|
|
</pre>
|
|
You will have to modify this to look like this:
|
|
<pre>
|
|
lib:
|
|
%{pg: -lprofile} --start-group -lc --end-group
|
|
</pre>
|
|
Normally, the specs file is located at the compilers installation directory. For cross-compilers,
|
|
this is <tt>/usr/local/amiga/lib/gcc/ppc-amigaos/<i>compiler-version</i>/specs</tt>. For a native compiler,
|
|
it's in <tt>gcc:lib/gcc/ppc-amigaos/<i>compiler-version</i>/specs</tt>. Most likely, your compiler will already have this added to it's specs file.</p>
|
|
|
|
<p>Profiling makes use of a special PowerPC facility called the Performance Monitor. It
|
|
allows to "mark" tasks and count only during while a marked task is running. This allows
|
|
performance analysis to be made independant of the actual system load. The Performace Monitor
|
|
is available on all PowerPC models supported by AmigaOS 4 except for the <tt>603e</tt>, and
|
|
embedded versions of the PowerPC like the <tt>405</tt> and <tt>440</tt> series. Consult the manual
|
|
of the appropriate chip for more information.</p>
|
|
|
|
<h2>6. Conventions and design issues</h2>
|
|
|
|
<p>You will have noticed the 330+ files in this directory. This is not the best
|
|
way to organize a runtime library, but at least all the bits and pieces are in
|
|
plain sight. Each file stands for the one or two routines it contains. The
|
|
name indicates what routine(s) that might be. Each file name is prefixed by
|
|
the name of the header file in which the corresponding routine is defined. So,
|
|
for example, you will find that <tt>unistd_lchown.c</tt> contains the definition of
|
|
the <tt>lchown()</tt> routine, which has its prototype defined in the <tt><unistd.h></tt> header
|
|
file.</p>
|
|
|
|
<p>Internal function and variables which need to be visible across several
|
|
modules have names prefixed with two underscores, as in <tt>__stdio_init()</tt>.</p>
|
|
|
|
<p>All routines attempt to do error checking on their parameters. They will
|
|
either drop into an <tt>assert()</tt> or set an errno value and refuse to go any
|
|
further. This cuts performance but should help to catch the simple bugs quite
|
|
easily (<tt>NULL</tt> pointers).</p>
|
|
|
|
<p>Just like any halfway sane Amiga 'C' runtime library, this one performs its <tt>^C</tt>
|
|
checking in the I/O routines. Typically once upon entry and in every iteration
|
|
of the loop there might be it will quickly poll the <tt>^C</tt> signal and drop into
|
|
<tt>raise(SIGINT)</tt> in case the signal is set. This is just about the safest method
|
|
to solve the problem and should be much more robust than the ixemul approach
|
|
of 'interrupt anywhere - crash anywhere' using the task switch/launch hooks to
|
|
test for signals.</p>
|
|
|
|
<p>By default all library routines follow the ISO 'C' conventions in that where
|
|
implementation defined behaviour is permitted, the AmigaOS rules are followed.
|
|
For example, <tt>unlink()</tt> will by default operate like <tt>DeleteFile()</tt> and <tt>rename()</tt>
|
|
will return with an error code set if the name of the file/directory to be
|
|
renamed would collide with an existing directory entry. However, your program
|
|
can set a global variable <tt>__unix_semantics</tt> which will cause some routines to
|
|
perform like their Unix counterparts. This is necessary for Samba to work but
|
|
not a generally desirable feature. You have some Unix-like behaviour, but the
|
|
environment itself is not completely Unix- or POSIX-compliant. And it
|
|
shouldn't be. Don't make the mistake of trying to mold the environment into a
|
|
POSIX emulation. It doesn't work; AmigaOS is not Unix.</p>
|
|
|
|
|
|
<h2>7. The startup code</h2>
|
|
|
|
<p>There are three program startup files provided. The most simplistic is in
|
|
<tt>startup.c</tt> which I use for SAS/C. It just invokes the setup routine which
|
|
eventually calls <tt>main()</tt> and drops straight into <tt>exit()</tt>.</p>
|
|
|
|
<p>The <tt>ncrt0.S</tt> file was adapted from the libnix startup code which sets up the
|
|
base relative data area, if necessary (the <tt>SMALL_DATA</tt> preprocessor symbol must
|
|
be defined).</p>
|
|
|
|
<p>The <tt>nrcrt0.S</tt> file was adapted from libnix startup code, too, and sets up the
|
|
base relative data area for programs to be made resident. Note that the
|
|
<tt>geta4()</tt> stub is missing here; it wouldn't work in a resident program anyway.</p>
|
|
|
|
<p>The <tt>ncrt0.S</tt> and <tt>nrcrt0.S</tt> files are considerably smaller and less complex than
|
|
the libnix code they are based on. This is because in this library design all
|
|
the more complex tasks are performed in the <tt>stdlib_main.c</tt> file rather than in
|
|
assembly language.</p>
|
|
|
|
|
|
<h2>8. Documentation</h2>
|
|
|
|
<p>Well, you're reading it. There isn't anything much yet. You can consult the book
|
|
<i>'C' - A reference manual</i> and you could look at the
|
|
<a href="http://www.opengroup.org/onlinepubs/007904975">Open Group's Single Unix
|
|
Specification</a>.</p>
|
|
|
|
|
|
<h2>9. Legal status</h2>
|
|
|
|
<p>Because this library is in part based upon free software it would be
|
|
uncourteous not to make it free software itself. The BSD license would
|
|
probably be appropriate here.</p>
|
|
|
|
<p>The PowerPC math library is based in part on work by Sun Microsystems:</p>
|
|
|
|
<pre>
|
|
====================================================
|
|
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.
|
|
====================================================
|
|
</pre>
|
|
|
|
<h2>10. Contacting the author</h2>
|
|
|
|
<p>The basic work was done by Olaf Barthel during two weeks in July 2002. You
|
|
can reach me at:</p>
|
|
|
|
<p>Olaf Barthel<br>
|
|
Gneisenaustr. 43<br>
|
|
D-31275 Lehrte<br></p>
|
|
|
|
<p>Or via e-mail:</p>
|
|
|
|
<p>olsen@sourcery.han.de</p>
|
|
</body>
|
|
</html>
|