Sign in Join
Wiki copytemporary

System unit structure: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: System unit structure

OldNewLine
1+(work in progress - incomplete!)
2+
3+This page is supposed to document functions and procedures serving as "interfaces" between common and platform specific parts of [[System unit|unit System]] as well as commonly used subroutines for particular tasks performed during unit System initialization and specify their behaviour. This should then serve as specification for maintainers of existing and new platforms to ensure fully compatible behaviour (as far as possible considering limitations of the individual platforms).
4+
5+Usually, all listed routines are mandatory (at least as stub) unless specifically mentioned otherwise - see section Features below for exceptions. If name of the usual source file containing implemenation of the particular routine is not mentioned, it's supposed to be system.pas for platform specific parts and system.inc for the shared routines.
6+
7+## Source file structure
8+
9+Similarly to other parts of FPC RTL (and also units included in packages), the general pattern is that units requiring at least some platform / target specific parts have the main source file (system.pas in case of unit System) in the specific subdirectory specific for the particular target, but this file refers an include file containing the common interface (systemh.inc) and another include file containing implementation of platform independent stuff (system.inc) - obviously, we try to share as much as possible rather than duplicating the same code on several places. The parts shared for all targets (like the two include files mentioned above) are stored in /rtl/inc.
10+
11+In the particular case of unit System (and partly also some other more complex units), there are quite a few more include files involved, though. In addition to parts which are shared among all targets, there are also parts which may be shared for all targets on a particular CPU / platform stored in a subdirectory named after the CPU / platform (e.g. in /rtl/i386/, /rtl/x86_64/, /rtl/aarch64/, /rtl/jvm/, etc.). Moreover, there may be parts which are shared by several targets having certain similar aspects - e.g. various BSD based targets have shared parts in /rtl/bsd/, all *NIX targets have shared parts in /rtl/unix/ and various MS Windows targets may use shared parts in /rtl/win/.
12+
13+Finally, the complexity of the System unit led to the situation that the common implementation part expects certain parts of the target-specific implementation in specifically named include files which need to be made available in the subdirectory for the particular target, or possibly in a subdirectory shared among several targets as mentioned above. As an example, target specific implementation of file handling needs to be provided in file sysfile.inc.
14+
15+You might wonder how the compiler knows where to find the different include files - this is handled in the Makefile (generated from Makefile.fpc rules using our fpcmake tool - see /utils/fpcm/).
16+
17+## Features
18+
19+Certain targets are not capable to provide certain functionality due to their limited nature (typically certain embedded systems, etc.). In order to provide this level of flexibility without sacrificing the aim of sharing as much code as possible, there are conditional defines set for individual targets specifying features available for that targets. The list of features enabled for all targets by default is specified at the beginning of systemh.inc. Targets which need to limit the set of supported features need to include {\$DEFINE FPC_HAS_FEATURE_SUPPORT} at the beginning of their System unit (before {\$I systemh.inc}). As of time of writing this, the following features are included in the default (full) set using conditional defines:
20+
21+- {\$define FPC_HAS_FEATURE_HEAP} - dynamic memory management using heap
22+- {\$define FPC_HAS_FEATURE_INITFINAL} - initialization and finalization
23+- {\$define FPC_HAS_FEATURE_RTTI} - Runt-Time Type Information
24+- {\$define FPC_HAS_FEATURE_CLASSES} - classes
25+- {\$define FPC_HAS_FEATURE_EXCEPTIONS} - exceptions
26+- {\$define FPC_HAS_FEATURE_EXITCODE} - returning of exit code when finishing the program
27+- {\$define FPC_HAS_FEATURE_ANSISTRINGS} - AnsiString type (variable length strings)
28+- {\$define FPC_HAS_FEATURE_WIDESTRINGS} - WideString type
29+- {\$define FPC_HAS_FEATURE_TEXTIO} - text file input/output
30+- {\$define FPC_HAS_FEATURE_CONSOLEIO} - input/output using console
31+- {\$define FPC_HAS_FEATURE_FILEIO} - general file input/output
32+- {\$define FPC_HAS_FEATURE_RANDOM} - random number generator
33+- {\$define FPC_HAS_FEATURE_VARIANTS} - variants
34+- {\$define FPC_HAS_FEATURE_OBJECTS} - objects
35+- {\$define FPC_HAS_FEATURE_DYNARRAYS} - dynamic arrays
36+- {\$define FPC_HAS_FEATURE_THREADING} - multithreading (note that this just specifies that the RTL structures for multithreading support are included; it doesn't necessarily mean, that the target must allow creating multiple threads (e.g. MS-DOS based targets don't allow that at the moment due to missing support from the operating system, although it might be technically possible to provide implementation at the RTL or user code level)
37+- {\$define FPC_HAS_FEATURE_COMMANDARGS} - command-line arguments
38+- {\$define FPC_HAS_FEATURE_PROCESSES} - running of other processes
39+- {\$define FPC_HAS_FEATURE_STACKCHECK} - stack checking
40+- {\$define FPC_HAS_FEATURE_DYNLIBS} - dynamic libraries
41+- {\$define FPC_HAS_FEATURE_OBJECTIVEC1} - ObjectiveC classes
42+- {\$define FPC_HAS_FEATURE_UNICODESTRINGS} - UnicodeString type
43+
44+## Types
45+
46+The following types are assumed to be defined in platform specific part of System unit interface.
47+
48+- THandle
49+- TThreadID
50+- TRTLCriticalSection
51+- PRTLCriticalSection
52+
53+## Constants and variables
54+
55+The following list includes mandatory constants and variables that have to be declared (and usually initialized to reasonable values for the particular platform) for all platforms:
56+
57+- LineEnding
58+- DirectorySeparator
59+- DriveSeparator
60+- PathSeparator
61+- MaxExitCode
62+- MaxPathLen
63+- UnusedHandle
64+- StdInputHandle
65+- StdOutputHandle
66+- StdErrorHandle
67+- LFNSupport
68+- FileNameCaseSensitive
69+- CtrlZMarksEof
70+- sLineBreak
71+- DefaultTextLineBreakStyle
72+- ArgC
73+- ArgV
74+- EnvC
75+- EnvP
76+
77+\<TODO\>
78+
79+## Initialization
80+
81+### Shared
82+
83+#### InitHeap
84+
85+Implemented in heap.inc.
86+
87+Initialization of internal structures used by the default heap memory manager. No heap may be used before calling InitHeap.
88+
89+#### SysInitExceptions
90+
91+Initialization of internal structures used by the exception support.
92+
93+\<TODO\>
94+
95+#### OpenStdIO
96+
97+Common part of initialization for standard file variables. It's similar to [[Assign]] and Reset/[[Rewrite]] calls for normal text files, but the files are associated with empty file names and no attempt is made to open the files (they're assumed to be already open).
98+
99+\<TODO\>
100+
101+#### InitSystemThreads
102+
103+\<TODO\>
104+
105+#### SetThreadManager
106+
107+\<TODO\>
108+
109+#### InitHeapMutexes
110+
111+\<TODO\>
112+
113+#### InitVariantManager
114+
115+\<TODO\>
116+
117+#### InitWideStringManager
118+
119+\<TODO\>
120+
121+#### Sysinit unit and indirect entry information
122+
123+(note: This is currently at very initial stage and applies only to i386-win32 target)
124+
125+Supporting runtime packages requires possibility to link the system unit and the main program into different executable modules. Therefore, global information generated by compiler, such as unit initialization table, cannot be directly referenced from the system unit. Instead, it is referenced from a separate small unit ('sysinit') and passed to routines in system unit via function arguments. The module entry point is placed in sysinit unit, too. A copy of sysinit unit is statically linked into every executable module, so every module ends up containing the initialization table only for the units it actually contains.
126+
127+This global information is not limited to unit initialization table, see TEntryInformation record for complete list.
128+
129+A target may have more than one sysinit unit, each solving specific initialization tasks. A particular unit to use is determined by compiler, see InitSysInitUnitName method in descendants of TLinker class. For example, while normally using sysinitpas.pp, complier will use sysinitcyg.pp instead if it detects linking with cygwin libraries.
130+
131+### Platform specific
132+
133+#### unit initialization
134+
135+The following tasks are performed:
136+
137+- IsLibrary variable initialization (true if running in a shared library, false otherwise)
138+- ProcessID and ThreadID variables initialization
139+- IsConsole variable initialization (true if running in a text console, false if running in windowed GUI application)
140+- ExitProc variable initialization \<TODO\>
141+- Heap initialization (calling shared InitHeap)
142+- Initialization of potential procedural variables and/or parameters needed to support System unit routines requiring different implementation depending on detected version of operating system (possibly including dynamic loading of procedures or functions from shared libraries where appropriate) - see [[OS aware RTL]]
143+- InOutRes variable initialization (set to 0)
144+- Environment variables initialization (EnvC and EnvP), usually by calling InitEnvironment - only needed for platforms not providing access to these variables natively
145+- Internal thread manager is initialized by calling InitSystemThreads
146+- Internal variant manager is initialized by calling InitVariantManager
147+- Internal widestring manager is initialized by calling InitWideStringManager
148+
149+#### InitEnvironment
150+
151+Only needed for platforms not providing access to EnvC and EnvP variables natively.
152+
153+Procedure checks amount of environment variables and stores it in EnvC. Then memory for EnvP^ is allocated from heap (array of EnvC + 1 items of type PChar - the list pointer will point to nil). Finally the individual items in the array are initialized with PChars pointing to null terminated strings containing the environment variable name, equal sign and the environment variable value. Memory for the individual null terminated strings may be allocated from heap for these strings and they may be copied there if needed (i.e. if the particular platform doesn't provide pointer to a fixed location for these strings in required format).
154+
155+#### InitArguments
156+
157+Only needed for platforms not providing access to ArgC, ArgV and/or CmdLine variables natively.
158+
159+\<TODO\>
160+
161+#### SysInitStdIO
162+
163+Initialization of standard file variables (Input, Output, ErrOutput, StdOut and StdErr).
164+
165+\<TODO\>
166+
167+### SysSetCtrlBreakHandler
168+
169+Unlike some other target specific functions, this function is optional (controlled using {\$DEFINE FPC_HAS_SETCTRLBREAKHANDLER} before {\$I system.inc}). It allows the target to provide its own implementation of a function for setting up own a handler for the Ctrl-Break handler. This may be necessary e.g. if the handler needs to be somehow initialized before it could be used (e.g. by specifically allowing triggering Ctrl-Break event as an exception at the operating system level). The default implementation is the following:
170+
171+ function SysSetCtrlBreakHandler (Handler: TCtrlBreakHandler): TCtrlBreakHandler;
172+ begin
173+ (* Return either nil or previous handler *)
174+ SysSetCtrlBreakHandler := CtrlBreakHandler;
175+ CtrlBreakHandler := Handler;
176+ end;
177+
178+Setting up CtrlBreakHandler allows specific handling of Ctrl-Break key combination rather than having this combination interpreted at the operating system level (translating it to an attempt to terminate the running program). As an example, this functionality may be used in units Crt and/or Keyboard in package rtl-console (/packages/rtl-console/). TCtrlBreakHandler is defined as follows:
179+
180+ type
181+ TCtrlBreakHandler = function (CtrlBreak: boolean): boolean;
182+
183+When CtrlBreakHandler is called, the CtrlBreak parameter set to true signalizes a Ctrl-Break signal, otherwise it means that the call was triggered by Ctrl-C keyboard combination. The handler is supposed to return true if the signal has been processed, false means that default exception handling should be used.
184+
185+## General tasks
186+
187+### Platform specific
188+
189+#### File handling
190+
191+Usually implemented in file sysfile.inc.
192+
193+##### Do_Close
194+
195+##### Do_Erase
196+
197+##### Do_Rename
198+
199+##### Do_Read
200+
201+##### Do_Write
202+
203+##### Do_FilePos
204+
205+##### Do_Seek
206+
207+##### Do_SeekEnd
208+
209+##### Do_FileSize
210+
211+##### Do_Truncate
212+
213+##### Do_Open
214+
215+##### Do_IsDevice
216+
217+#### Heap management
218+
219+##### SysOSAlloc
220+
221+##### SysOSFree
222+
223+#### Threading Support
224+
225+##### SysInitThreadVar
226+
227+##### SysRelocateThreadVar
228+
229+#### Other
230+
231+##### System_Exit
232+
233+## Public routines
234+
235+The following routines are part of System unit interface and are supposed to be implemented fully in platform specific way. Their specification is available in FPC documentation, so they're listed here mostly for completeness sake to provide complete list for porting purposes.
236+
237+### Directory handling
238+
239+Usually implemented in sysdir.inc.
240+
241+- MkDir
242+- RmDir
243+- ChDir
244+- GetDir
245+
246+### Other
247+
248+- Randomize
249+- ParamCount, ParamStr (possibly to be moved to common - \<TODO\>)
250+
251+## Finalization
252+
253+### Shared
254+
255+#### InternalExit
256+
257+\<TODO\>
258+
259+#### FinalizeHeap
260+
261+\<TODO\>
262+
263+### Platform specific
264+
265+#### FinalDeallocation
266+
267+\<TODO\>
268+
269+---
270+*From the Free Pascal wiki, page "System unit structure", as it stood on 2022-09-03 after a change by Kai Burghardt, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
271+Category: FPC internals
272+Category: RTL

Back to history