Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / llvm / 3ac1ab835caacdeebbd0d7b4d69160f283928d21 / . / docs / SystemLibrary.html
blob: 8334a4198410b89d0962734f89f2ffa630e0c54d [file] [log] [blame]
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>System Library</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
9
Misha Brukmanebbbf252004-07-21 18:02:43 +0000[diff] [blame]10<div class="doc_title">System Library</div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]11<ul>
12 <li><a href="#abstract">Abstract</a></li>
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]13 <li><a href="#requirements">Keeping LLVM Portable</a>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]14 <ol>
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]15 <li><a href="#headers">Don't Include System Headers</a></li>
16 <li><a href="#expose">Don't Expose System Headers</a></li>
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]17 <li><a href="#c_headers">Allow Standard C Header Files</a></li>
18 <li><a href="#cpp_headers">Allow Standard C++ Header Files</a></li>
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]19 <li><a href="#highlev">High-Level Interface</a></li>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]20 <li><a href="#nofunc">No Exposed Functions</a></li>
21 <li><a href="#nodata">No Exposed Data</a></li>
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]22 <li><a href="#nodupl">No Duplicate Implementations</a></li>
23 <li><a href="#nounused">No Unused Functionality</a></li>
24 <li><a href="#virtuals">No Virtual Methods</a></li>
25 <li><a href="#softerrors">Minimize Soft Errors</a></li>
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]26 <li><a href="#throw">Throw Only std::string</a></li>
27 <li><a href="#throw_spec">No throw() Specifications</a></li>
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]28 <li><a href="#organization">Code Organization</a></li>
29 <li><a href="#semantics">Consistent Semantics</a></li>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]30 <li><a href="#bug">Tracking Bugzilla Bug: 351</a></li>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]31 </ol></li>
32</ul>
33
34<div class="doc_author">
Duncan Sands8036ca42007-03-30 12:22:09 +0000[diff] [blame]35 <p>Written by <a href="mailto:rspencer@x10sys.com">Reid Spencer</a></p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]36</div>
37
38
39<!-- *********************************************************************** -->
40<div class="doc_section"><a name="abstract">Abstract</a></div>
41<div class="doc_text">
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]42 <p>This document provides some details on LLVM's System Library, located in
43 the source at <tt>lib/System</tt> and <tt>include/llvm/System</tt>. The
44 library's purpose is to shield LLVM from the differences between operating
45 systems for the few services LLVM needs from the operating system. Much of
46 LLVM is written using portability features of standard C++. However, in a few
47 areas, system dependent facilities are needed and the System Library is the
48 wrapper around those system calls.</p>
49 <p>By centralizing LLVM's use of operating system interfaces, we make it
50 possible for the LLVM tool chain and runtime libraries to be more easily
51 ported to new platforms since (theoretically) only <tt>lib/System</tt> needs
52 to be ported. This library also unclutters the rest of LLVM from #ifdef use
53 and special cases for specific operating systems. Such uses are replaced
54 with simple calls to the interfaces provided in <tt>include/llvm/System</tt>.
55 </p>
56 <p>Note that the System Library is not intended to be a complete operating
57 system wrapper (such as the Adaptive Communications Environment (ACE) or
58 Apache Portable Runtime (APR)), but only provides the functionality necessary
59 to support LLVM.
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]60 <p>The System Library was written by Reid Spencer who formulated the
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]61 design based on similar work originating from the eXtensible Programming
62 System (XPS). Several people helped with the effort; especially,
63 Jeff Cohen and Henrik Bach on the Win32 port.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]64</div>
65
66<!-- *********************************************************************** -->
67<div class="doc_section">
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]68 <a name="requirements">Keeping LLVM Portable</a>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]69</div>
70<div class="doc_text">
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]71 <p>In order to keep LLVM portable, LLVM developers should adhere to a set of
72 portability rules associated with the System Library. Adherence to these rules
73 should help the System Library achieve its goal of shielding LLVM from the
74 variations in operating system interfaces and doing so efficiently. The
75 following sections define the rules needed to fulfill this objective.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]76</div>
77
78<!-- ======================================================================= -->
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]79<div class="doc_subsection"><a name="headers">Don't Inlcude System Headers</a>
80</div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]81<div class="doc_text">
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]82 <p>Except in <tt>lib/System</tt>, no LLVM source code should directly
83 <tt>#include</tt> a system header. Care has been taken to remove all such
84 <tt>#includes</tt> from LLVM while <tt>lib/System</tt> was being
85 developed. Specifically this means that header files like "unistd.h",
86 "windows.h", "stdio.h", and "string.h" are forbidden to be included by LLVM
87 source code outside the implementation of <tt>lib/System</tt>.</p>
88 <p>To obtain system-dependent functionality, existing interfaces to the system
89 found in <tt>include/llvm/System</tt> should be used. If an appropriate
90 interface is not available, it should be added to <tt>include/llvm/System</tt>
91 and implemented in <tt>lib/System</tt> for all supported platforms.</p>
92</div>
93
94<!-- ======================================================================= -->
95<div class="doc_subsection"><a name="expose">Don't Expose System Headers</a>
96</div>
Reid Spencerd593afc2005-01-05 18:21:39 +0000[diff] [blame]97<div class="doc_text">
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]98 <p>The System Library must shield LLVM from <em>all</em> system headers. To
99 obtain system level functionality, LLVM source must
100 <tt>#include "llvm/System/Thing.h"</tt> and nothing else. This means that
101 <tt>Thing.h</tt> cannot expose any system header files. This protects LLVM
102 from accidentally using system specific functionality and only allows it
103 via the <tt>lib/System</tt> interface.</p>
104</div>
105
106<!-- ======================================================================= -->
Reid Spencerd593afc2005-01-05 18:21:39 +0000[diff] [blame]107<div class="doc_subsection"><a name="c_headers">Use Standard C Headers</a></div>
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]108<div class="doc_text">
109 <p>The <em>standard</em> C headers (the ones beginning with "c") are allowed
110 to be exposed through the <tt>lib/System</tt> interface. These headers and
111 the things they declare are considered to be platform agnostic. LLVM source
112 files may include them directly or obtain their inclusion through
113 <tt>lib/System</tt> interfaces.</p>
114</div>
115
116<!-- ======================================================================= -->
117<div class="doc_subsection"><a name="cpp_headers">Use Standard C++ Headers</a>
118</div>
119<div class="doc_text">
120 <p>The <em>standard</em> C++ headers from the standard C++ library and
121 standard template library may be exposed through the <tt>lib/System</tt>
122 interface. These headers and the things they declare are considered to be
123 platform agnostic. LLVM source files may include them or obtain their
124 inclusion through lib/System interfaces.</p>
125</div>
126
127<!-- ======================================================================= -->
128<div class="doc_subsection"><a name="highlev">High Level Interface</a></div>
129<div class="doc_text">
130 <p>The entry points specified in the interface of lib/System must be aimed at
131 completing some reasonably high level task needed by LLVM. We do not want to
132 simply wrap each operating system call. It would be preferable to wrap several
133 operating system calls that are always used in conjunction with one another by
134 LLVM.</p>
135 <p>For example, consider what is needed to execute a program, wait for it to
136 complete, and return its result code. On Unix, this involves the following
137 operating system calls: <tt>getenv, fork, execve,</tt> and <tt>wait</tt>. The
138 correct thing for lib/System to provide is a function, say
139 <tt>ExecuteProgramAndWait</tt>, that implements the functionality completely.
140 what we don't want is wrappers for the operating system calls involved.</p>
141 <p>There must <em>not</em> be a one-to-one relationship between operating
142 system calls and the System library's interface. Any such interface function
143 will be suspicious.</p>
144</div>
145
146<!-- ======================================================================= -->
147<div class="doc_subsection"><a name="nounused">No Unused Functionality</a></div>
148<div class="doc_text">
149 <p>There must be no functionality specified in the interface of lib/System
150 that isn't actually used by LLVM. We're not writing a general purpose
151 operating system wrapper here, just enough to satisfy LLVM's needs. And, LLVM
152 doesn't need much. This design goal aims to keep the lib/System interface
153 small and understandable which should foster its actual use and adoption.</p>
154</div>
155
156<!-- ======================================================================= -->
157<div class="doc_subsection"><a name="nodupl">No Duplicate Implementations</a>
158</div>
159<div class="doc_text">
160 <p>The implementation of a function for a given platform must be written
161 exactly once. This implies that it must be possible to apply a function's
162 implementation to multiple operating systems if those operating systems can
163 share the same implementation. This rule applies to the set of operating
164 systems supported for a given class of operating system (e.g. Unix, Win32).
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]165 </p>
166</div>
167
168<!-- ======================================================================= -->
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]169<div class="doc_subsection"><a name="virtuals">No Virtual Methods</a></div>
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]170<div class="doc_text">
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]171 <p>The System Library interfaces can be called quite frequently by LLVM. In
172 order to make those calls as efficient as possible, we discourage the use of
173 virtual methods. There is no need to use inheritance for implementation
174 differences, it just adds complexity. The <tt>#include</tt> mechanism works
175 just fine.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]176</div>
177
178<!-- ======================================================================= -->
179<div class="doc_subsection"><a name="nofunc">No Exposed Functions</a></div>
180<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]181 <p>Any functions defined by system libraries (i.e. not defined by lib/System)
182 must not be exposed through the lib/System interface, even if the header file
183 for that function is not exposed. This prevents inadvertent use of system
184 specific functionality.</p>
185 <p>For example, the <tt>stat</tt> system call is notorious for having
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]186 variations in the data it provides. <tt>lib/System</tt> must not declare
187 <tt>stat</tt> nor allow it to be declared. Instead it should provide its own
188 interface to discovering information about files and directories. Those
189 interfaces may be implemented in terms of <tt>stat</tt> but that is strictly
190 an implementation detail. The interface provided by the System Library must
191 be implemented on all platforms (even those without <tt>stat</tt>).</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]192</div>
193
194<!-- ======================================================================= -->
195<div class="doc_subsection"><a name="nodata">No Exposed Data</a></div>
196<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]197 <p>Any data defined by system libraries (i.e. not defined by lib/System) must
198 not be exposed through the lib/System interface, even if the header file for
199 that function is not exposed. As with functions, this prevents inadvertent use
200 of data that might not exist on all platforms.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]201</div>
202
203<!-- ======================================================================= -->
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]204<div class="doc_subsection"><a name="softerrors">Minimize Soft Errors</a></div>
205<div class="doc_text">
206 <p>Operating system interfaces will generally provide error results for every
207 little thing that could go wrong. In almost all cases, you can divide these
208 error results into two groups: normal/good/soft and abnormal/bad/hard. That
209 is, some of the errors are simply information like "file not found",
210 "insufficient privileges", etc. while other errors are much harder like
211 "out of space", "bad disk sector", or "system call interrupted". We'll call
212 the first group "<i>soft</i>" errors and the second group "<i>hard</i>"
213 errors.<p>
214 <p>lib/System must always attempt to minimize soft errors and always just
215 throw a std::string on hard errors. This is a design requirement because the
216 minimization of soft errors can affect the granularity and the nature of the
217 interface. In general, if you find that you're wanting to throw soft errors,
218 you must review the granularity of the interface because it is likely you're
219 trying to implement something that is too low level. The rule of thumb is to
220 provide interface functions that <em>can't</em> fail, except when faced with
221 hard errors.</p>
222 <p>For a trivial example, suppose we wanted to add an "OpenFileForWriting"
223 function. For many operating systems, if the file doesn't exist, attempting
224 to open the file will produce an error. However, lib/System should not
225 simply throw that error if it occurs because its a soft error. The problem
226 is that the interface function, OpenFileForWriting is too low level. It should
227 be OpenOrCreateFileForWriting. In the case of the soft "doesn't exist" error,
228 this function would just create it and then open it for writing.</p>
229 <p>This design principle needs to be maintained in lib/System because it
230 avoids the propagation of soft error handling throughout the rest of LLVM.
231 Hard errors will generally just cause a termination for an LLVM tool so don't
232 be bashful about throwing them.</p>
233 <p>Rules of thumb:</p>
234 <ol>
235 <li>Don't throw soft errors, only hard errors.</li>
236 <li>If you're tempted to throw a soft error, re-think the interface.</li>
237 <li>Handle internally the most common normal/good/soft error conditions
238 so the rest of LLVM doesn't have to.</li>
239 </ol>
240</div>
241
242<!-- ======================================================================= -->
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]243<div class="doc_subsection"><a name="throw">Throw Only std::string</a></div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]244<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]245 <p>If an error occurs that lib/System cannot handle, the only action taken by
246 lib/System is to throw an instance of std:string. The contents of the string
247 must explain both what happened and the context in which it happened. The
248 format of the string should be a (possibly empty) list of contexts each
249 terminated with a : and a space, followed by the error message, optionally
250 followed by a reason, and optionally followed by a suggestion.</p>
251 <p>For example, failure to open a file named "foo" could result in a message
252 like:</p>
253 <ul><li>foo: Unable to open file because it doesn't exist."</li></ul>
254 <p>The "foo:" part is the context. The "Unable to open file" part is the error
255 message. The "because it doesn't exist." part is the reason. This message has
John Criswell98d06362004-11-21 14:58:12 +0000[diff] [blame]256 no suggestion. Where possible, the implementation of lib/System should use
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]257 operating system specific facilities for converting the error code returned by
258 a system call into an error message. This will help to make the error message
259 more familiar to users of that type of operating system.</p>
260 <p>Note that this requirement precludes the throwing of any other exceptions.
261 For example, various C++ standard library functions can cause exceptions to be
262 thrown (e.g. out of memory situation). In all cases, if there is a possibility
263 that non-string exceptions could be thrown, the lib/System library must ensure
264 that the exceptions are translated to std::string form.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]265</div>
266
267<!-- ======================================================================= -->
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]268<div class="doc_subsection"><a name="throw_spec">No throw Specifications</a>
269</div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]270<div class="doc_text">
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]271 <p>None of the lib/System interface functions may be declared with C++
272 <tt>throw()</tt> specifications on them. This requirement makes sure that the
John Criswell98d06362004-11-21 14:58:12 +0000[diff] [blame]273 compiler does not insert additional exception handling code into the interface
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]274 functions. This is a performance consideration: lib/System functions are at
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]275 the bottom of many call chains and as such can be frequently called. We
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]276 need them to be as efficient as possible.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]277</div>
278
279<!-- ======================================================================= -->
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]280<div class="doc_subsection"><a name="organization">Code Organization</a></div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]281<div class="doc_text">
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]282 <p>Implementations of the System Library interface are separated by their
283 general class of operating system. Currently only Unix and Win32 classes are
284 defined but more could be added for other operating system classifications.
285 To distinguish which implementation to compile, the code in lib/System uses
286 the LLVM_ON_UNIX and LLVM_ON_WIN32 #defines provided via configure through the
287 llvm/Config/config.h file. Each source file in lib/System, after implementing
288 the generic (operating system independent) functionality needs to include the
289 correct implementation using a set of <tt>#if defined(LLVM_ON_XYZ)</tt>
290 directives. For example, if we had lib/System/File.cpp, we'd expect to see in
291 that file:</p>
292 <pre><tt>
293 #if defined(LLVM_ON_UNIX)
294 #include "Unix/File.cpp"
295 #endif
296 #if defined(LLVM_ON_WIN32)
297 #include "Win32/File.cpp"
298 #endif
299 </tt></pre>
300 <p>The implementation in lib/System/Unix/File.cpp should handle all Unix
301 variants. The implementation in lib/System/Win32/File.cpp should handle all
302 Win32 variants. What this does is quickly differentiate the basic class of
303 operating system that will provide the implementation. The specific details
304 for a given platform must still be determined through the use of
305 <tt>#ifdef</tt>.</p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]306</div>
307
308<!-- ======================================================================= -->
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]309<div class="doc_subsection"><a name="semantics">Consistent Semantics</a></div>
Reid Spencer7acb8662004-08-27 02:08:04 +0000[diff] [blame]310<div class="doc_text">
Reid Spencer0c004852005-01-05 18:17:10 +0000[diff] [blame]311 <p>The implementation of a lib/System interface can vary drastically between
312 platforms. That's okay as long as the end result of the interface function
313 is the same. For example, a function to create a directory is pretty straight
314 forward on all operating system. System V IPC on the other hand isn't even
315 supported on all platforms. Instead of "supporting" System V IPC, lib/System
316 should provide an interface to the basic concept of inter-process
317 communications. The implementations might use System V IPC if that was
318 available or named pipes, or whatever gets the job done effectively for a
319 given operating system. In all cases, the interface and the implementation
320 must be semantically consistent. </p>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]321</div>
322
323<!-- ======================================================================= -->
Chris Lattner05540a72004-07-17 18:50:19 +0000[diff] [blame]324<div class="doc_subsection"><a name="bug">Bug 351</a></div>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]325<div class="doc_text">
Reid Spencer05fe4b02006-03-14 05:39:39 +0000[diff] [blame]326 <p>See <a href="http://llvm.org/PR351">bug 351</a>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]327 for further details on the progress of this work</p>
328</div>
329
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]330<!-- *********************************************************************** -->
331
332<hr>
333<address>
334 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]335 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]336 <a href="http://validator.w3.org/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]337 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]338
339 <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br>
Reid Spencer05fe4b02006-03-14 05:39:39 +0000[diff] [blame]340 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
Reid Spencer4f6015a2004-07-17 10:04:49 +0000[diff] [blame]341 Last modified: $Date$
342</address>
343</body>
344</html>