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

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