pd.if.org Git - pdclib/blob - personality.txt

   1 // ----------------------------------------------------------------------------
   2 // $Id$
   3 // ----------------------------------------------------------------------------
   4 // Public Domain C Library - http://pdclib.sourceforge.net
   5 // This code is Public Domain. Use, modify, and redistribute at will.
   6 // ----------------------------------------------------------------------------
   7 // Description of the personality concept
   8 // ----------------------------------------------------------------------------
   9
  10 The pdclib is aimed at providing a fully conforming implementation of the C99
  11 standard library, with a focus on adaptability to diverse environments.
  12
  13 That means, an effort was made to make this library useful to you, no matter if
  14 you are looking for a replacement for the CLib provided by your system vendor,
  15 for a basic CLib to develop your own operating system on / with, or for a "bare
  16 bones" CLib to test your software against a strict "standard only" library.
  17
  18 The traditional way of providing this kind of cross-platform support is the
  19 preprocessor directive '#ifdef'. However, careless use of this feature can make
  20 source code next to intelligible and hard to maintain. Hence, an effort was
  21 made to encapsule such platform dependencies, by the concept of "personality
  22 modules".
  23
  24 A personality module consists of three parts: drop-ins, glue code, and the
  25 header file "__personality.h", in an appropriately named subdirectory of
  26 pdclib/personalities.
  27
  28 // ----------------------------------------------------------------------------
  29 // DROP-INS
  30
  31 The standard includes limits.h and stdint.h define various intrinsics of the
  32 integer types of a platform. The standard include float.h does the same for the
  33 floating point types. Throughout pdclib, these defines have been put to maximum
  34 use.
  35
  36 Each personality module must provide those three include files, so that pdclib
  37 "knows" about the data type intrinsics of the platform in question. The files
  38 are simply "dropped" into the pdclib/includes subdirectory prior to building
  39 pdclib.
  40
  41 // ----------------------------------------------------------------------------
  42 // GLUE CODE
  43
  44 Most functions of pdclib could be implemented generically - i.e., any supported
  45 platform uses identical source code for them. Some functions, however, interact
  46 closely with the operating system at one point or another. pdclib implements
  47 the "top half" of those functions, where possible. The "bottom half" has to be
  48 provided by the operating system.
  49
  50 If pdclib is used on a host OS, as replacement for a vendor-supplied CLib, the
  51 personality module should contain the "glue code" necessary to match the OS
  52 provided services to pdclib's top/bottom interface (see below).
  53
  54 When a new operating system uses pdclib as "native" C standard library, the
  55 documentation of the top/bottom interfaces (see below) should help in bringing
  56 OS and pdclib together. In this case, no dedicated "glue code" is necessary.
  57
  58 // ----------------------------------------------------------------------------
  59 // __PERSONALITY.H
  60
  61 At some points within the library, information about the environment is needed
  62 which cannot be derived from the drop-ins. In those places, "__personality.h"
  63 is included; this file defines a couple of symbols specifying those environment
  64 options for the personality module. A template for __personality.h can be found
  65 in the pdclib/personalities directory.
  66
  67 The symbols defined in personality.h are all named __PERSONALITY_*, with "*"
  68 being replaced with a service or feature provded or not provided. Never is the
  69 name of an OS, compiler, or hardware used in such symbols - later generations
  70 of either might provide a service that older ones did not, and it is also more
  71 self-explanatory if the symbol reads "__PERSONALITY_SUPPORTS_XYZ" instead of
  72 "__PERSONALITY_MyOS", which basically leaves the reader clueless as to what
  73 makes MyOS special in this case - information that might be outdated already
  74 without anyone being the wiser.
  75
  76 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
  77 modules need not be changed. The default goes without saying, so to speak.
  78
  79 // ----------------------------------------------------------------------------
  80 // TOP/BOTTOM INTERFACE
  81
  82 What follows is a documentation of the "bottom half" functions required by
  83 pdclib, with an exact description of interface, required functionality, etc.