// ----------------------------------------------------------------------------
// $Id$
// ----------------------------------------------------------------------------
// Public Domain C Library - http://pdclib.sourceforge.net
// This code is Public Domain. Use, modify, and redistribute at will.
// ----------------------------------------------------------------------------
// Description of the personality concept
// ----------------------------------------------------------------------------

The pdclib is aimed at providing a fully conforming implementation of the C99
standard library, with a focus on adaptability to diverse environments.

That means, an effort was made to make this library useful to you, no matter if
you are looking for a replacement for the CLib provided by your system vendor,
for a basic CLib to develop your own operating system on / with, or for a "bare
bones" CLib to test your software against a strict "standard only" library.

The traditional way of providing this kind of cross-platform support is the
preprocessor directive '#ifdef'. However, careless use of this feature can make
source code next to intelligible and hard to maintain. Hence, an effort was
made to encapsule such platform dependencies, by the concept of "personality
modules".

A personality module consists of three parts: drop-ins, glue code, and the
header file "__personality.h", in an appropriately named subdirectory of
pdclib/personalities.

// ----------------------------------------------------------------------------
// DROP-INS

The standard includes limits.h and stdint.h define various intrinsics of the
integer types of a platform. The standard include float.h does the same for the
floating point types. Throughout pdclib, these defines have been put to maximum
use.

Each personality module must provide those three include files, so that pdclib
"knows" about the data type intrinsics of the platform in question. The files
are simply "dropped" into the pdclib/includes subdirectory prior to building
pdclib.

// ----------------------------------------------------------------------------
// GLUE CODE 

Most functions of pdclib could be implemented generically - i.e., any supported
platform uses identical source code for them. Some functions, however, interact
closely with the operating system at one point or another. pdclib implements
the "top half" of those functions, where possible. The "bottom half" has to be
provided by the operating system.

If pdclib is used on a host OS, as replacement for a vendor-supplied CLib, the
personality module should contain the "glue code" necessary to match the OS
provided services to pdclib's top/bottom interface (see below).

When a new operating system uses pdclib as "native" C standard library, the
documentation of the top/bottom interfaces (see below) should help in bringing
OS and pdclib together. In this case, no dedicated "glue code" is necessary.

// ----------------------------------------------------------------------------
// __PERSONALITY.H

At some points within the library, information about the environment is needed
which cannot be derived from the drop-ins. In those places, "__personality.h"
is included; this file defines a couple of symbols specifying those environment
options for the personality module. A template for __personality.h can be found
in the pdclib/personalities directory.

The symbols defined in personality.h are all named __PERSONALITY_*, with "*"
being replaced with a service or feature provded or not provided. Never is the
name of an OS, compiler, or hardware used in such symbols - later generations
of either might provide a service that older ones did not, and it is also more
self-explanatory if the symbol reads "__PERSONALITY_SUPPORTS_XYZ" instead of
"__PERSONALITY_MyOS", which basically leaves the reader clueless as to what
makes MyOS special in this case - information that might be outdated already
without anyone being the wiser.

If a new, exotic personality is added that requires a new symbol to be added to personality.h, that symbol is always worded in a way that the old personality
modules need not be changed. The default goes without saying, so to speak.

// ----------------------------------------------------------------------------
// TOP/BOTTOM INTERFACE

What follows is a documentation of the "bottom half" functions required by
pdclib, with an exact description of interface, required functionality, etc.