mirror of https://github.com/adtools/clib2.git
- Replaced the plain text documentation with HTML versions.
git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@14861 87f5fb63-7c3d-0410-a384-fd976d0f7a62
This commit is contained in:
Olaf Barthel
parent
1bc19a04d3
commit
b2ddf28fa7
|
|
@ -1,19 +0,0 @@
|
|||
In order to build the library, you need a 'C' compiler (obvious, isn't it?) and
|
||||
a set of header files for the networking API definitions. The networking header
|
||||
files go into a directory "netinclude" which has to sit in the same directory as
|
||||
the source code and the "include" directory you find in there. I'm not currently
|
||||
supplying these header files here. Drop me a line, and I'll take care of that.
|
||||
|
||||
The SAS/C flavour (smakefile) should get the library built using the "large data"
|
||||
model. This rules out the use of residentable programs as the startup code I'm
|
||||
using is very primitive (startup.o) and doesn't tinker with A4 relative data
|
||||
addressing (and how this may be set up).
|
||||
|
||||
There are two makefiles for GCC, each a different flavour. There is "GNUmakefile.68k",
|
||||
which will build the library for GCC on the 68k platform ("classic" Amiga). This
|
||||
builds all variants of the library, for large data, small data, resident, whatever
|
||||
model. It's a lot of work and I don't recommend you do this on a plain 68k machine.
|
||||
It will literally (!) take hours. The other makefile flavour is for AmigaOS4 using
|
||||
the PowerPC hosted GCC system ("GNUmakefile.os4"). This builds only the large data
|
||||
version of the library, but this is usually all you need. Small data support is
|
||||
currently not implemented but might follow in the future.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
<!DOCTYPE html public "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Notes on building the library</title>
|
||||
<body>
|
||||
|
||||
<h1>Notes on building the library</h1>
|
||||
|
||||
<p>In order to build the library, you need a 'C' compiler (obvious, isn't it?) and
|
||||
a set of header files for the networking API definitions. The networking header
|
||||
files go into a directory <tt>netinclude</tt> which has to sit in the same directory as
|
||||
the source code and the <tt>include</tt> directory you find in there. I'm not currently
|
||||
supplying these header files here. Drop me a line, and I'll take care of that.</p>
|
||||
|
||||
<p>The SAS/C flavour (<tt>smakefile</tt>) should get the library built using the "large data"
|
||||
model. This rules out the use of residentable programs as the startup code I'm
|
||||
using is very primitive (<tt>startup.o</tt>) and doesn't tinker with A4 relative data
|
||||
addressing (and how this may be set up).</p>
|
||||
|
||||
<p>There are two makefiles for GCC, each a different flavour. There is <tt>GNUmakefile.68k</tt>,
|
||||
which will build the library for GCC on the 68k platform ("classic" Amiga). This
|
||||
builds all variants of the library, for large data, small data, resident, whatever
|
||||
model. It's a lot of work and I don't recommend you do this on a plain 68k machine.
|
||||
It will literally (!) take hours. The other makefile flavour is for AmigaOS4 using
|
||||
the PowerPC hosted GCC system (<tt>GNUmakefile.os4</tt>). This builds only the large data
|
||||
version of the library, but this is usually all you need. Small data support is
|
||||
currently not implemented but might follow in the future.</p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
You can use the 68k build of clib2 with the existing Amiga 68k ports of the
|
||||
GNU 'C' compiler. In order to do so, you need to modify the "specs" file which
|
||||
controls how the compiler(s) and the linker interact, and where the linker
|
||||
will look for the program startup code and library files. Also, you will need
|
||||
to copy the header files, startup code and library files to the locations
|
||||
where the 'C' compiler and linker expects them.
|
||||
|
||||
Please read the following description before you follow the instructions. The
|
||||
changes suggested may have unexpected side-effects!
|
||||
|
||||
I have provided a working "specs" file with this documentation file. To switch
|
||||
over an existing Amiga 68k port of GCC to use clib2, you would proceed as
|
||||
follows:
|
||||
|
||||
- Locate the directory within which GCC is installed. For example, this
|
||||
could be within a directory to which the name "ADE:", "GG:" or "GCC:"
|
||||
is assigned. For the sake of simplicity, the following notes assume
|
||||
that the assignment name is "GCC:"
|
||||
|
||||
- Make backup copies of the following directories and files:
|
||||
|
||||
GCC:lib/gcc-lib/amigaos/2.95.3/specs
|
||||
|
||||
(NOTE: Check the directory called "GCC:lib/gcc-lib/amigaos"
|
||||
first; the "2.95.3" quoted above refers to the version,
|
||||
revision and patch number of the GCC installed and your
|
||||
version number may differ!)
|
||||
|
||||
GCC:include
|
||||
GCC:lib
|
||||
|
||||
- Now you can proceed to install clib2; just copy the "include" and "lib"
|
||||
directories over, like this:
|
||||
|
||||
Copy include GCC:include all quiet
|
||||
Copy lib GCC:lib all quiet
|
||||
|
||||
- Finally, replace the "specs" file with the one provided:
|
||||
|
||||
Copy specs GCC:lib/gcc-lib/amigaos/2.95.3/specs
|
||||
|
||||
(NOTE: Check the directory called "GCC:lib/gcc-lib/amigaos"
|
||||
first; the "2.95.3" quoted above refers to the version,
|
||||
revision and patch number of the GCC installed and your
|
||||
version number may differ!)
|
||||
|
||||
Once you have completed these steps you should be able to build programs using
|
||||
the 68k build of clib2 and you currently installed GCC. Note that these
|
||||
changes may have the effect of rendering your C++ compiler unusable, so make
|
||||
sure that you've made backup copies of all files and directories first!
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
<!DOCTYPE html public "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>Notes on using the library with Amiga GCC (68k)</title>
|
||||
<body>
|
||||
|
||||
<h1>Notes on using the library with Amiga GCC (68k)</h1>
|
||||
|
||||
<p>You can use the 68k build of clib2 with the existing Amiga 68k ports of the
|
||||
GNU 'C' compiler. In order to do so, you need to modify the <tt>specs</tt> file which
|
||||
controls how the compiler(s) and the linker interact, and where the linker
|
||||
will look for the program startup code and library files. Also, you will need
|
||||
to copy the header files, startup code and library files to the locations
|
||||
where the 'C' compiler and linker expects them.</p>
|
||||
|
||||
<p>Please read the following description before you follow the instructions. The
|
||||
changes suggested may have unexpected side-effects!</p>
|
||||
|
||||
<p>I have provided a working <tt>specs</tt> file with this documentation file. To switch
|
||||
over an existing Amiga 68k port of GCC to use clib2, you would proceed as
|
||||
follows:</p>
|
||||
|
||||
<ul>
|
||||
<li> Locate the directory within which GCC is installed. For example, this
|
||||
could be within a directory to which the name <tt>ADE:</tt>, <tt>GG:</tt> or <tt>GCC:</tt>
|
||||
is assigned. For the sake of simplicity, the following notes assume
|
||||
that the assignment name is <tt>GCC:</tt>
|
||||
|
||||
<li> Make backup copies of the following directories and files:
|
||||
<ol>
|
||||
<li> <tt>GCC:lib/gcc-lib/amigaos/2.95.3/specs</tt><br>
|
||||
|
||||
<p>(NOTE: Check the directory called <tt>GCC:lib/gcc-lib/amigaos</tt>
|
||||
first; the "2.95.3" quoted above refers to the version,
|
||||
revision and patch number of the GCC installed and your
|
||||
version number may differ!)</p>
|
||||
|
||||
<li> <tt>GCC:include</tt>
|
||||
<li> <tt>GCC:lib</tt>
|
||||
|
||||
</ol>
|
||||
|
||||
<li> Now you can proceed to install clib2; just copy the <tt>include</tt> and <tt>lib</tt>
|
||||
directories over, like this:
|
||||
<ol>
|
||||
<li><kbd>Copy include GCC:include all quiet</kbd>
|
||||
<li><kbd>Copy lib GCC:lib all quiet</kbd>
|
||||
</ol>
|
||||
|
||||
<li> Finally, replace the <tt>specs</tt> file with the one provided:
|
||||
<ol>
|
||||
|
||||
<li> <kbd>Copy specs GCC:lib/gcc-lib/amigaos/2.95.3/specs</kbd><br>
|
||||
|
||||
<p>(NOTE: Check the directory called <tt>GCC:lib/gcc-lib/amigaos</tt>
|
||||
first; the "2.95.3" quoted above refers to the version,
|
||||
revision and patch number of the GCC installed and your
|
||||
version number may differ!)</p>
|
||||
</ol>
|
||||
</ul>
|
||||
|
||||
<p>Once you have completed these steps you should be able to build programs using
|
||||
the 68k build of clib2 and you currently installed GCC. Note that these
|
||||
changes may have the effect of rendering your C++ compiler unusable, so make
|
||||
sure that you've made backup copies of all files and directories first!</p>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,247 +0,0 @@
|
|||
An ISO 'C' (1994) compliant runtime library for the Amiga
|
||||
=========================================================
|
||||
|
||||
1. What is this?
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
2. What does it do?
|
||||
|
||||
Using "'C' - A reference manual" (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.
|
||||
|
||||
Because Samba needs a few POSIX-like routines to be supported, the library
|
||||
functionality is complemented by a set of routines described in "Advanced
|
||||
programming in the Unix environent".
|
||||
|
||||
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.
|
||||
|
||||
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 IEEE_FLOATING_POINT_SUPPORT preprocessor symbol to activate IEEE math
|
||||
code and the M68881_FLOATING_POINT_SUPPORT symbol for M68881 inline math.
|
||||
|
||||
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.
|
||||
|
||||
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 '__stack_size' variable (see
|
||||
"stdlib_main.c").
|
||||
|
||||
I added some amiga.lib and debug.lib functionality to the library, but don't
|
||||
count on it to be complete.
|
||||
|
||||
The library code is supposed to be thread-safe if built with the __THREAD_SAFE
|
||||
preprocesssor symbold defined. Note that 'thread-safe' does not mean
|
||||
'reentrant'. Multiple callers for certain library functions are permitted, but
|
||||
not for all of them. For example, mkdtemp() is not thread-safe, and neither is
|
||||
rand() or localtime(). But as per POSIX 1003.1c-1995 there are thread-safe
|
||||
variants of rand() and localtime() called rand_r(), localtime_r(), and others.
|
||||
The use of the socket I/O functions is still problematic because the
|
||||
underlying bsdsocket.library 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 'errno' variable which currently always contains the
|
||||
error code left by the last caller.
|
||||
|
||||
Take care: 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 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.
|
||||
|
||||
|
||||
3. What does it not do?
|
||||
|
||||
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.
|
||||
|
||||
Practically all library routines are implemented in a sort of naïve fashion.
|
||||
That is, they contain virtually no optimizations whatsoever. This is
|
||||
particularly apparent in workhorses such as memset() or memmove(). But then,
|
||||
the issue is easy testability and Amiga platform portability.
|
||||
|
||||
There is very little support for amiga.lib functionality. There is NewList(),
|
||||
HookEntry(), CallHook(), CallHookA(), the DoMethod() 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 amiga.lib, you really shouldn't need in in the first place.
|
||||
|
||||
|
||||
4. Where does the source code come from?
|
||||
|
||||
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 bcopy() as an alias for memcpy(), and
|
||||
unlike memcpy() is documented to, bcopy() supports overlapping copies.
|
||||
|
||||
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 setjmp/longjmp
|
||||
routines and the startup code. The M68881 inline math code comes from the
|
||||
<math-68881.h> file written by Matthew Self (self@bayes.arc.nasa.gov).
|
||||
|
||||
|
||||
5. Limitations and caveats
|
||||
|
||||
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.
|
||||
|
||||
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 malloc() 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 free() 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 NDEBUG preprocessor symbol at compile time (see <assert.h>).
|
||||
|
||||
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.
|
||||
|
||||
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 data=faronly option to compile the
|
||||
library and the programs.
|
||||
|
||||
Different build makefiles are supplied for use with GCC. There is
|
||||
GNUmakefile.68k for the 68k platform and GNUmakefile.os4 for the AmigaOS4
|
||||
PowerPC version.
|
||||
|
||||
|
||||
6. Conventions and design issues
|
||||
|
||||
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 "unistd_lchown.c" contains the definition of
|
||||
the lchown() routine, which has its prototype defined in the <unistd.h> header
|
||||
file.
|
||||
|
||||
Internal function and variables which need to be visible across several
|
||||
modules have names prefixed with two underscores, as in '__stdio_init()'.
|
||||
|
||||
All routines attempt to do error checking on their parameters. They will
|
||||
either drop into an assert() or set an errno value and refuse to go any
|
||||
further. This cuts performance but should help to catch the simple bugs quite
|
||||
easily (NULL pointers).
|
||||
|
||||
Just like any halfway sane Amiga 'C' runtime library, this one performs its ^C
|
||||
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 ^C signal and drop into
|
||||
raise(SIGINT) 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.
|
||||
|
||||
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, unlink() will by default operate like DeleteFile() and rename()
|
||||
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 '__unix_semantics' 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.
|
||||
|
||||
|
||||
7. The startup code
|
||||
|
||||
There are three program startup files provided. The most simplistic is in
|
||||
'startup.c' which I use for SAS/C. It just invokes the setup routine which
|
||||
eventually calls main() and drops straight into exit().
|
||||
|
||||
The ncrt0.S file was adapted from the libnix startup code which sets up the
|
||||
base relative data area, if necessary (the SMALL_DATA preprocessor symbol must
|
||||
be defined).
|
||||
|
||||
The nrcrt0.S 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
|
||||
geta4() stub is missing here; it wouldn't work in a resident program anyway.
|
||||
|
||||
The ncrt0.S and nrcrt0.S 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 stdlib_main.c file rather than in
|
||||
assembly language.
|
||||
|
||||
|
||||
8. Documentation
|
||||
|
||||
Well, you're reading it. There isn't anything much yet. You can consult the book
|
||||
"'C' - A reference manual" and you could look at the Open Group's Single Unix
|
||||
Specification at <http://www.opengroup.org/onlinepubs/007904975>.
|
||||
|
||||
|
||||
9. Legal status
|
||||
|
||||
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.
|
||||
|
||||
The PowerPC math library is based in part on work by Sun Microsystems:
|
||||
|
||||
====================================================
|
||||
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.
|
||||
====================================================
|
||||
|
||||
|
||||
|
||||
10. Contacting the author
|
||||
|
||||
The basic work was done by Olaf Barthel during two weeks in July 2002. You
|
||||
can reach me at:
|
||||
|
||||
Olaf Barthel
|
||||
Gneisenaustr. 43
|
||||
D-31275 Lehrte
|
||||
|
||||
Or via e-mail:
|
||||
|
||||
olsen@sourcery.han.de
|
||||
|
|
@ -0,0 +1,250 @@
|
|||
<!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>
|
||||
|
||||
<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 POSIX 1003.1c-1995 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>
|
||||
|
||||
<p>Take care: 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 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>
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
<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>
|
||||
Loading…
Reference in New Issue