mirror of
https://github.com/adtools/clib2.git
synced 2025-12-08 14:59:05 +00:00
- 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
@@ -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.
|
|
||||||
30
documentation/BUILDING.html
Normal file
30
documentation/BUILDING.html
Normal file
@@ -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!
|
|
||||||
67
documentation/GCC-68K.html
Normal file
67
documentation/GCC-68K.html
Normal file
@@ -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
|
|
||||||
250
documentation/README.html
Normal file
250
documentation/README.html
Normal file
@@ -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>
|
||||||
Reference in New Issue
Block a user