Unified · Split
| @@ -1,52 +1,97 @@ | ||
| 1 | −<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> | |
| 2 | −<html> | |
| 3 | −<head> | |
| 4 | − <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| 5 | − <title> Tiny C Compiler Reference Documentation </title> | |
| 6 | −</head> | |
| 7 | −<body> | |
| 8 | − | |
| 9 | −<center> | |
| 10 | −<h1> | |
| 11 | −Tiny C Compiler Reference Documentation | |
| 12 | −</h1> | |
| 13 | −</center> | |
| 14 | − | |
| 15 | −<h2>Introduction</h2> | |
| 1 | +\input texinfo @c -*- texinfo -*- | |
| 2 | + | |
| 3 | +@settitle Tiny C Compiler Reference Documentation | |
| 4 | +@titlepage | |
| 5 | +@sp 7 | |
| 6 | +@center @titlefont{Tiny C Compiler Reference Documentation} | |
| 7 | +@sp 3 | |
| 8 | +@end titlepage | |
| 9 | + | |
| 10 | +@chapter Introduction | |
| 16 | 11 | |
| 17 | 12 | TinyCC (aka TCC) is a small but hyper fast C compiler. Unlike other C |
| 18 | 13 | compilers, it is meant to be self-suffisant: you do not need an |
| 19 | 14 | external assembler or linker because TCC does that for you. |
| 20 | −<P> | |
| 21 | −TCC compiles so <em>fast</em> that even for big projects <tt>Makefile</tt>s may | |
| 15 | + | |
| 16 | +TCC compiles so @emph{fast} that even for big projects @code{Makefile}s may | |
| 22 | 17 | not be necessary. |
| 23 | −<P> | |
| 18 | + | |
| 24 | 19 | TCC not only supports ANSI C, but also most of the new ISO C99 |
| 25 | 20 | standard and many GNUC extensions. |
| 26 | −<P> | |
| 27 | −TCC can also be used to make <I>C scripts</I>, | |
| 28 | −i.e. pieces of C source that you run as a Perl or Python | |
| 29 | −script. Compilation is so fast that your script will be as fast as if | |
| 30 | −it was an executable. | |
| 31 | −<P> | |
| 32 | −TCC can also automatically generate <A HREF="#bounds">memory and bound | |
| 33 | −checks</A> while allowing all C pointers operations. TCC can do these | |
| 34 | −checks even if non patched libraries are used. | |
| 35 | −</P> | |
| 36 | − | |
| 37 | −<h2>Full ANSI C support</h2> | |
| 21 | + | |
| 22 | +TCC can also be used to make @emph{C scripts}, i.e. pieces of C source | |
| 23 | +that you run as a Perl or Python script. Compilation is so fast that | |
| 24 | +your script will be as fast as if it was an executable. | |
| 25 | + | |
| 26 | +TCC can also automatically generate memory and bound checks | |
| 27 | +(@xref{bounds}) while allowing all C pointers operations. TCC can do | |
| 28 | +these checks even if non patched libraries are used. | |
| 29 | + | |
| 30 | +With @code{libtcc}, you can use TCC as a backend for dynamic code | |
| 31 | +generation (@xref{libtcc}). | |
| 32 | + | |
| 33 | +@node invoke | |
| 34 | +@chapter Command line invocation | |
| 35 | + | |
| 36 | +@example | |
| 37 | +usage: tcc [-Idir] [-Dsym[=val]] [-Usym] [-llib] [-g] [-b] | |
| 38 | + [-i infile] infile [infile_args...] | |
| 39 | +@end example | |
| 40 | + | |
| 41 | +@table @samp | |
| 42 | +@item -Idir | |
| 43 | +Specify an additionnal include path. The default ones are: | |
| 44 | +@file{/usr/include}, @code{prefix}@file{/lib/tcc/include} (@code{prefix} | |
| 45 | +is usually @file{/usr} or @file{/usr/local}). | |
| 46 | + | |
| 47 | +@item -Dsym[=val] | |
| 48 | +Define preprocessor symbol 'sym' to | |
| 49 | +val. If val is not present, its value is '1'. Function-like macros can | |
| 50 | +also be defined: @code{'-DF(a)=a+1'} | |
| 51 | + | |
| 52 | +@item -Usym | |
| 53 | +Undefine preprocessor symbol 'sym'. | |
| 54 | + | |
| 55 | +@item -lxxx | |
| 56 | +Dynamically link your program with library | |
| 57 | +libxxx.so. Standard library paths are checked, including those | |
| 58 | +specified with LD_LIBRARY_PATH. | |
| 59 | + | |
| 60 | +@item -g | |
| 61 | +Generate run time debug information so that you get clear run time | |
| 62 | +error messages: @code{ test.c:68: in function 'test5()': dereferencing | |
| 63 | +invalid pointer} instead of the laconic @code{Segmentation | |
| 64 | +fault}. | |
| 65 | + | |
| 66 | +@item -b | |
| 67 | +Generate additionnal support code to check | |
| 68 | +memory allocations and array/pointer bounds. '-g' is implied. Note | |
| 69 | +that the generated code is slower and bigger in this case. | |
| 70 | + | |
| 71 | +@item -i file | |
| 72 | +Compile C source 'file' before main C source. With this | |
| 73 | +command, multiple C files can be compiled and linked together. | |
| 74 | + | |
| 75 | +@end table | |
| 76 | + | |
| 77 | +Note: the @code{-o file} option to generate an ELF executable is | |
| 78 | +currently unsupported. | |
| 79 | + | |
| 80 | +@chapter C language support | |
| 81 | + | |
| 82 | +@section ANSI C | |
| 38 | 83 | |
| 39 | 84 | TCC implements all the ANSI C standard, including structure bit fields |
| 40 | −and floating point numbers (<tt>long double</tt>, <tt>double</tt>, and | |
| 41 | −<tt>float</tt> fully supported). The following limitations are known: | |
| 85 | +and floating point numbers (@code{long double}, @code{double}, and | |
| 86 | +@code{float} fully supported). The following limitations are known: | |
| 42 | 87 | |
| 43 | −<ul> | |
| 44 | − <li> The preprocessor tokens are the same as C. It means that in some | |
| 88 | +@itemize | |
| 89 | + @item The preprocessor tokens are the same as C. It means that in some | |
| 45 | 90 | rare cases, preprocessed numbers are not handled exactly as in ANSI |
| 46 | 91 | C. This approach has the advantage of being simpler and FAST! |
| 47 | −</ul> | |
| 92 | +@end itemize | |
| 48 | 93 | |
| 49 | −<h2>ISOC99 extensions</h2> | |
| 94 | +@section ISOC99 extensions | |
| 50 | 95 | |
| 51 | 96 | TCC implements many features of the new C standard: ISO C99. Currently |
| 52 | 97 | missing items are: complex and imaginary numbers and variable length |
| @@ -54,77 +99,77 @@ arrays. · 1 unmodified line | ||
| 54 | 99 | |
| 55 | 100 | Currently implemented ISOC99 features: |
| 56 | 101 | |
| 57 | −<ul> | |
| 102 | +@itemize | |
| 58 | 103 | |
| 59 | −<li> 64 bit <tt>'long long'</tt> types are fully supported. | |
| 104 | +@item 64 bit @code{'long long'} types are fully supported. | |
| 60 | 105 | |
| 61 | −<li> The boolean type <tt>'_Bool'</tt> is supported. | |
| 106 | +@item The boolean type @code{'_Bool'} is supported. | |
| 62 | 107 | |
| 63 | −<li> <tt>'__func__'</tt> is a string variable containing the current | |
| 108 | +@item @code{'__func__'} is a string variable containing the current | |
| 64 | 109 | function name. |
| 65 | 110 | |
| 66 | −<li> Variadic macros: <tt>__VA_ARGS__</tt> can be used for | |
| 111 | +@item Variadic macros: @code{__VA_ARGS__} can be used for | |
| 67 | 112 | function-like macros: |
| 68 | −<PRE> | |
| 113 | +@example | |
| 69 | 114 | #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__) |
| 70 | −</PRE> | |
| 71 | −<tt>dprintf</tt> can then be used with a variable number of parameters. | |
| 115 | +@end example | |
| 116 | +@code{dprintf} can then be used with a variable number of parameters. | |
| 72 | 117 | |
| 73 | −<li> Declarations can appear anywhere in a block (as in C++). | |
| 118 | +@item Declarations can appear anywhere in a block (as in C++). | |
| 74 | 119 | |
| 75 | −<li> Array and struct/union elements can be initialized in any order by | |
| 120 | +@item Array and struct/union elements can be initialized in any order by | |
| 76 | 121 | using designators: |
| 77 | −<PRE> | |
| 122 | +@example | |
| 78 | 123 | struct { int x, y; } st[10] = { [0].x = 1, [0].y = 2 }; |
| 79 | 124 | |
| 80 | 125 | int tab[10] = { 1, 2, [5] = 5, [9] = 9}; |
| 81 | −</PRE> | |
| 126 | +@end example | |
| 82 | 127 | |
| 83 | −<li> Compound initializers are supported: | |
| 84 | −<PRE> | |
| 128 | +@item Compound initializers are supported: | |
| 129 | +@example | |
| 85 | 130 | int *p = (int []){ 1, 2, 3 }; |
| 86 | −</PRE> | |
| 131 | +@end example | |
| 87 | 132 | to initialize a pointer pointing to an initialized array. The same |
| 88 | 133 | works for structures and strings. |
| 89 | 134 | |
| 90 | −<li> Hexadecimal floating point constants are supported: | |
| 91 | −<PRE> | |
| 135 | +@item Hexadecimal floating point constants are supported: | |
| 136 | +@example | |
| 92 | 137 | double d = 0x1234p10; |
| 93 | −</PRE> | |
| 138 | +@end example | |
| 94 | 139 | is the same as writing |
| 95 | −<PRE> | |
| 140 | +@example | |
| 96 | 141 | double d = 4771840.0; |
| 97 | −</PRE> | |
| 142 | +@end example | |
| 98 | 143 | |
| 99 | −<li> <tt>'inline'</tt> keyword is ignored. | |
| 144 | +@item @code{'inline'} keyword is ignored. | |
| 100 | 145 | |
| 101 | −<li> <tt>'restrict'</tt> keyword is ignored. | |
| 102 | −</ul> | |
| 146 | +@item @code{'restrict'} keyword is ignored. | |
| 147 | +@end itemize | |
| 103 | 148 | |
| 104 | −<h2>GNU C extensions</h2> | |
| 149 | +@section GNU C extensions | |
| 105 | 150 | |
| 106 | 151 | TCC implements some GNU C extensions: |
| 107 | 152 | |
| 108 | −<ul> | |
| 153 | +@itemize | |
| 109 | 154 | |
| 110 | −<li> array designators can be used without '=': | |
| 111 | −<PRE> | |
| 155 | +@item array designators can be used without '=': | |
| 156 | +@example | |
| 112 | 157 | int a[10] = { [0] 1, [5] 2, 3, 4 }; |
| 113 | −</PRE> | |
| 158 | +@end example | |
| 114 | 159 | |
| 115 | −<li> Structure field designators can be a label: | |
| 116 | −<PRE> | |
| 160 | +@item Structure field designators can be a label: | |
| 161 | +@example | |
| 117 | 162 | struct { int x, y; } st = { x: 1, y: 1}; |
| 118 | −</PRE> | |
| 163 | +@end example | |
| 119 | 164 | instead of |
| 120 | −<PRE> | |
| 165 | +@example | |
| 121 | 166 | struct { int x, y; } st = { .x = 1, .y = 1}; |
| 122 | −</PRE> | |
| 167 | +@end example | |
| 123 | 168 | |
| 124 | −<li> <tt>'\e'</tt> is ASCII character 27. | |
| 169 | +@item @code{'\e'} is ASCII character 27. | |
| 125 | 170 | |
| 126 | −<li> case ranges : ranges can be used in <tt>case</tt>s: | |
| 127 | −<PRE> | |
| 171 | +@item case ranges : ranges can be used in @code{case}s: | |
| 172 | +@example | |
| 128 | 173 | switch(a) { |
| 129 | 174 | case 1 ... 9: |
| 130 | 175 | printf("range 1 to 9\n"); |
| @@ -133,104 +178,104 @@ instead of · 2 unmodified lines | ||
| 133 | 178 | printf("unexpected\n"); |
| 134 | 179 | break; |
| 135 | 180 | } |
| 136 | −</PRE> | |
| 181 | +@end example | |
| 137 | 182 | |
| 138 | −<li> The keyword <tt>__attribute__</tt> is handled to specify variable or | |
| 183 | +@item The keyword @code{__attribute__} is handled to specify variable or | |
| 139 | 184 | function attributes. The following attributes are supported: |
| 140 | − <ul> | |
| 141 | − <li> <tt>aligned(n)</tt>: align data to n bytes (must be a power of two). | |
| 185 | + @itemize | |
| 186 | + @item @code{aligned(n)}: align data to n bytes (must be a power of two). | |
| 142 | 187 | |
| 143 | − <li> <tt>section(name)</tt>: generate function or data in assembly | |
| 188 | + @item @code{section(name)}: generate function or data in assembly | |
| 144 | 189 | section name (name is a string containing the section name) instead |
| 145 | 190 | of the default section. |
| 146 | 191 | |
| 147 | − <li> <tt>unused</tt>: specify that the variable or the function is unused. | |
| 192 | + @item @code{unused}: specify that the variable or the function is unused. | |
| 193 | + | |
| 194 | + @item @code{cdecl}: use standard C calling convention. | |
| 148 | 195 | |
| 149 | − <li> <tt>cdecl</tt>: use standard C calling convention. | |
| 196 | + @item @code{stdcall}: use Pascal-like calling convention. | |
| 150 | 197 | |
| 151 | − <li> <tt>stdcall</tt>: use Pascal-like calling convention. | |
| 198 | + @end itemize | |
| 152 | 199 | |
| 153 | − </ul> | |
| 154 | −<BR> | |
| 155 | 200 | Here are some examples: |
| 156 | −<PRE> | |
| 201 | +@example | |
| 157 | 202 | int a __attribute__ ((aligned(8), section(".mysection"))); |
| 158 | −</PRE> | |
| 159 | −<BR> | |
| 160 | −align variable <tt>'a'</tt> to 8 bytes and put it in section <tt>.mysection</tt>. | |
| 203 | +@end example | |
| 161 | 204 | |
| 162 | −<PRE> | |
| 205 | +align variable @code{'a'} to 8 bytes and put it in section @code{.mysection}. | |
| 206 | + | |
| 207 | +@example | |
| 163 | 208 | int my_add(int a, int b) __attribute__ ((section(".mycodesection"))) |
| 164 | 209 | { |
| 165 | 210 | return a + b; |
| 166 | 211 | } |
| 167 | −</PRE> | |
| 168 | −<BR> | |
| 169 | −generate function <tt>'my_add'</tt> in section <tt>.mycodesection</tt>. | |
| 170 | −</ul> | |
| 212 | +@end example | |
| 213 | + | |
| 214 | +generate function @code{'my_add'} in section @code{.mycodesection}. | |
| 215 | + | |
| 216 | +@item GNU style variadic macros: | |
| 217 | +@example | |
| 218 | + #define dprintf(fmt, args...) printf(fmt, ## args) | |
| 219 | + | |
| 220 | + dprintf("no arg\n"); | |
| 221 | + dprintf("one arg %d\n", 1); | |
| 222 | +@end example | |
| 171 | 223 | |
| 172 | −<h2>TinyCC extensions</h2> | |
| 224 | +@end itemize | |
| 173 | 225 | |
| 174 | −I have added some extensions I find interesting: | |
| 226 | +@section TinyCC extensions | |
| 175 | 227 | |
| 176 | −<ul> | |
| 228 | +@itemize | |
| 177 | 229 | |
| 178 | −<li> <tt>__TINYC__</tt> is a predefined macro to <tt>'1'</tt> to | |
| 230 | +@item @code{__TINYC__} is a predefined macro to @code{'1'} to | |
| 179 | 231 | indicate that you use TCC. |
| 180 | 232 | |
| 181 | −<li> <tt>'#!'</tt> at the start of a line is ignored to allow scripting. | |
| 233 | +@item @code{'#!'} at the start of a line is ignored to allow scripting. | |
| 182 | 234 | |
| 183 | −<li> Binary digits can be entered (<tt>'0b101'</tt> instead of | |
| 184 | −<tt>'5'</tt>). | |
| 235 | +@item Binary digits can be entered (@code{'0b101'} instead of | |
| 236 | +@code{'5'}). | |
| 185 | 237 | |
| 186 | −<li> <tt>__BOUNDS_CHECKING_ON</tt> is defined if bound checking is activated. | |
| 238 | +@item @code{__BOUNDS_CHECKING_ON} is defined if bound checking is activated. | |
| 187 | 239 | |
| 188 | −</ul> | |
| 240 | +@end itemize | |
| 189 | 241 | |
| 190 | −<h2>TinyCC Memory and Bound checks</h2> | |
| 191 | −<A NAME="bounds"></a> | |
| 242 | +@node bounds | |
| 243 | +@chapter TinyCC Memory and Bound checks | |
| 192 | 244 | |
| 193 | −This feature is activated with the <A HREF="#invoke"><tt>'-b'</tt> | |
| 194 | −option</A>. | |
| 195 | −<P> | |
| 196 | −Note that pointer size is <em>unchanged</em> and that code generated | |
| 197 | −with bound checks is <em>fully compatible</em> with unchecked | |
| 245 | +This feature is activated with the @code{'-b'} (@xref{invoke}). | |
| 246 | + | |
| 247 | +Note that pointer size is @emph{unchanged} and that code generated | |
| 248 | +with bound checks is @emph{fully compatible} with unchecked | |
| 198 | 249 | code. When a pointer comes from unchecked code, it is assumed to be |
| 199 | 250 | valid. Even very obscure C code with casts should work correctly. |
| 200 | −</P> | |
| 201 | −<P> To have more information about the ideas behind this method, <A | |
| 202 | −HREF="http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html">check | |
| 203 | −here</A>. | |
| 204 | −</P> | |
| 205 | −<P> | |
| 251 | + | |
| 252 | +To have more information about the ideas behind this method, check at | |
| 253 | +@url{http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html}. | |
| 254 | + | |
| 206 | 255 | Here are some examples of catched errors: |
| 207 | −</P> | |
| 208 | −<TABLE BORDER=1> | |
| 209 | −<TR> | |
| 210 | −<TD> | |
| 211 | −<PRE> | |
| 256 | + | |
| 257 | +@table @asis | |
| 258 | + | |
| 259 | +@item Invalid range with standard string function: | |
| 260 | +@example | |
| 212 | 261 | { |
| 213 | 262 | char tab[10]; |
| 214 | 263 | memset(tab, 0, 11); |
| 215 | 264 | } |
| 216 | −</PRE> | |
| 217 | −</TD><TD VALIGN=TOP>Invalid range with standard string function</TD> | |
| 265 | +@end example | |
| 218 | 266 | |
| 219 | −<TR> | |
| 220 | −<TD> | |
| 221 | −<PRE> | |
| 267 | +@item Bound error in global or local arrays: | |
| 268 | +@example | |
| 222 | 269 | { |
| 223 | 270 | int tab[10]; |
| 224 | 271 | for(i=0;i<11;i++) { |
| 225 | 272 | sum += tab[i]; |
| 226 | 273 | } |
| 227 | 274 | } |
| 228 | −</PRE> | |
| 229 | −</TD><TD VALIGN=TOP>Bound error in global or local arrays</TD> | |
| 275 | +@end example | |
| 230 | 276 | |
| 231 | −<TR> | |
| 232 | −<TD> | |
| 233 | −<PRE> | |
| 277 | +@item Bound error in allocated data: | |
| 278 | +@example | |
| 234 | 279 | { |
| 235 | 280 | int *tab; |
| 236 | 281 | tab = malloc(20 * sizeof(int)); |
| @@ -239,12 +284,10 @@ Here are some examples of catched errors: · 2 unmodified lines | ||
| 239 | 284 | } |
| 240 | 285 | free(tab); |
| 241 | 286 | } |
| 242 | −</PRE> | |
| 243 | −</TD><TD VALIGN=TOP>Bound error in allocated data</TD> | |
| 287 | +@end example | |
| 244 | 288 | |
| 245 | −<TR> | |
| 246 | −<TD> | |
| 247 | −<PRE> | |
| 289 | +@item Access to a freed region: | |
| 290 | +@example | |
| 248 | 291 | { |
| 249 | 292 | int *tab; |
| 250 | 293 | tab = malloc(20 * sizeof(int)); |
| @@ -253,70 +296,382 @@ Here are some examples of catched errors: · 2 unmodified lines | ||
| 253 | 296 | sum += tab4[i]; |
| 254 | 297 | } |
| 255 | 298 | } |
| 256 | −</PRE> | |
| 257 | −</TD><TD VALIGN=TOP>Access to a freed region</TD> | |
| 299 | +@end example | |
| 258 | 300 | |
| 259 | −<TR> | |
| 260 | −<TD> | |
| 261 | −<PRE> | |
| 301 | +@item Freeing an already freed region: | |
| 302 | +@example | |
| 262 | 303 | { |
| 263 | 304 | int *tab; |
| 264 | 305 | tab = malloc(20 * sizeof(int)); |
| 265 | 306 | free(tab); |
| 266 | 307 | free(tab); |
| 267 | 308 | } |
| 268 | −</PRE> | |
| 269 | −</TD><TD VALIGN=TOP>Freeing an already freed region</TD> | |
| 309 | +@end example | |
| 270 | 310 | |
| 271 | −</TABLE> | |
| 311 | +@end table | |
| 272 | 312 | |
| 273 | −<h2> Command line invocation </h2> | |
| 274 | −<A NAME="invoke"></a> | |
| 313 | +@node libtcc | |
| 314 | +@chapter The @code{libtcc} library | |
| 275 | 315 | |
| 276 | −<PRE> | |
| 277 | −usage: tcc [-Idir] [-Dsym[=val]] [-Usym] [-llib] [-g] [-b] | |
| 278 | − [-i infile] infile [infile_args...] | |
| 279 | −</PRE> | |
| 316 | +The @code{libtcc} library enables you to use TCC as a backend for | |
| 317 | +dynamic code generation. | |
| 280 | 318 | |
| 281 | −<table> | |
| 282 | −<tr><td>'-Idir'</td> | |
| 283 | −<td>Specify an additionnal include path. The default ones are: | |
| 284 | −/usr/include, /usr/lib/tcc, /usr/local/lib/tcc.</td> | |
| 319 | +Read the @file{libtcc.h} to have an overview of the API. Read | |
| 320 | +@file{libtcc_test.c} to have a very simple example. | |
| 285 | 321 | |
| 286 | −<tr><td>'-Dsym[=val]'</td> <td>Define preprocessor symbol 'sym' to | |
| 287 | −val. If val is not present, its value is '1'. Function-like macros can | |
| 288 | −also be defined: <tt>'-DF(a)=a+1'</tt></td> | |
| 322 | +The idea consists in giving a C string containing the program you want | |
| 323 | +to compile directly to @code{libtcc}. Then the @code{main()} function of | |
| 324 | +the compiled string can be launched. | |
| 289 | 325 | |
| 290 | −<tr><td>'-Usym'</td> <td>Undefine preprocessor symbol 'sym'.</td> | |
| 326 | +@chapter Developper's guide | |
| 291 | 327 | |
| 292 | −<tr><td>'-lxxx'</td> | |
| 293 | −<td>Dynamically link your program with library | |
| 294 | −libxxx.so. Standard library paths are checked, including those | |
| 295 | −specified with LD_LIBRARY_PATH.</td> | |
| 328 | +This chapter gives some hints to understand how TCC works. You can skip | |
| 329 | +it if you do not intend to modify the TCC code. | |
| 296 | 330 | |
| 297 | −<tr><td>'-g'</td> | |
| 298 | −<td>Generate run time debug information so that you get clear run time | |
| 299 | −error messages: <tt> test.c:68: in function 'test5()': dereferencing | |
| 300 | −invalid pointer</tt> instead of the laconic <tt>Segmentation | |
| 301 | −fault</tt>. | |
| 302 | −</td> | |
| 331 | +@section File reading | |
| 303 | 332 | |
| 304 | −<tr><td>'-b'</td> <td>Generate additionnal support code to check | |
| 305 | −memory allocations and array/pointer bounds. '-g' is implied. Note | |
| 306 | −that the generated code is slower and bigger in this case. | |
| 307 | −</td> | |
| 308 | − | |
| 309 | −<tr><td>'-i file'</td> | |
| 310 | −<td>Compile C source 'file' before main C source. With this | |
| 311 | −command, multiple C files can be compiled and linked together.</td> | |
| 312 | −</table> | |
| 313 | −<br> | |
| 314 | −Note: the <tt>'-o file'</tt> option to generate an ELF executable is | |
| 315 | −currently unsupported. | |
| 333 | +The @code{BufferedFile} structure contains the context needed to read a | |
| 334 | +file, including the current line number. @code{tcc_open()} opens a new | |
| 335 | +file and @code{tcc_close()} closes it. @code{inp()} returns the next | |
| 336 | +character. | |
| 337 | + | |
| 338 | +@section Lexer | |
| 339 | + | |
| 340 | +@code{next()} reads the next token in the current | |
| 341 | +file. @code{next_nomacro()} reads the next token without macro | |
| 342 | +expansion. | |
| 343 | + | |
| 344 | +@code{tok} contains the current token (see @code{TOK_xxx}) | |
| 345 | +constants. Identifiers and keywords are also keywords. @code{tokc} | |
| 346 | +contains additionnal infos about the token (for example a constant value | |
| 347 | +if number or string token). | |
| 348 | + | |
| 349 | +@section Parser | |
| 350 | + | |
| 351 | +The parser is hardcoded (yacc is not necessary). It does only one pass, | |
| 352 | +except: | |
| 353 | + | |
| 354 | +@itemize | |
| 355 | + | |
| 356 | +@item For initialized arrays with unknown size, a first pass | |
| 357 | +is done to count the number of elements. | |
| 358 | + | |
| 359 | +@item For architectures where arguments are evaluated in | |
| 360 | +reverse order, a first pass is done to reverse the argument order. | |
| 361 | + | |
| 362 | +@end itemize | |
| 363 | + | |
| 364 | +@section Types | |
| 365 | + | |
| 366 | +The types are stored in a single 'int' variable. It was choosen in the | |
| 367 | +first stages of development when tcc was much simpler. Now, it may not | |
| 368 | +be the best solution. | |
| 369 | + | |
| 370 | +@example | |
| 371 | +#define VT_INT 0 /* integer type */ | |
| 372 | +#define VT_BYTE 1 /* signed byte type */ | |
| 373 | +#define VT_SHORT 2 /* short type */ | |
| 374 | +#define VT_VOID 3 /* void type */ | |
| 375 | +#define VT_PTR 4 /* pointer */ | |
| 376 | +#define VT_ENUM 5 /* enum definition */ | |
| 377 | +#define VT_FUNC 6 /* function type */ | |
| 378 | +#define VT_STRUCT 7 /* struct/union definition */ | |
| 379 | +#define VT_FLOAT 8 /* IEEE float */ | |
| 380 | +#define VT_DOUBLE 9 /* IEEE double */ | |
| 381 | +#define VT_LDOUBLE 10 /* IEEE long double */ | |
| 382 | +#define VT_BOOL 11 /* ISOC99 boolean type */ | |
| 383 | +#define VT_LLONG 12 /* 64 bit integer */ | |
| 384 | +#define VT_LONG 13 /* long integer (NEVER USED as type, only | |
| 385 | + during parsing) */ | |
| 386 | +#define VT_BTYPE 0x000f /* mask for basic type */ | |
| 387 | +#define VT_UNSIGNED 0x0010 /* unsigned type */ | |
| 388 | +#define VT_ARRAY 0x0020 /* array type (also has VT_PTR) */ | |
| 389 | +#define VT_BITFIELD 0x0040 /* bitfield modifier */ | |
| 390 | + | |
| 391 | +#define VT_STRUCT_SHIFT 16 /* structure/enum name shift (16 bits left) */ | |
| 392 | +@end example | |
| 393 | + | |
| 394 | +When a reference to another type is needed (for pointers, functions and | |
| 395 | +structures), the @code{32 - VT_STRUCT_SHIFT} high order bits are used to | |
| 396 | +store an identifier reference. | |
| 397 | + | |
| 398 | +The @code{VT_UNSIGNED} flag can be set for chars, shorts, ints and long | |
| 399 | +longs. | |
| 400 | + | |
| 401 | +Arrays are considered as pointers @code{VT_PTR} with the flag | |
| 402 | +@code{VT_ARRAY} set. | |
| 403 | + | |
| 404 | +The @code{VT_BITFIELD} flag can be set for chars, shorts, ints and long | |
| 405 | +longs. If it is set, then the bitfield position is stored from bits | |
| 406 | +VT_STRUCT_SHIFT to VT_STRUCT_SHIFT + 5 and the bit field size is stored | |
| 407 | +from bits VT_STRUCT_SHIFT + 6 to VT_STRUCT_SHIFT + 11. | |
| 408 | + | |
| 409 | +@code{VT_LONG} is never used except during parsing. | |
| 410 | + | |
| 411 | +During parsing, the storage of an object is also stored in the type | |
| 412 | +integer: | |
| 413 | + | |
| 414 | +@example | |
| 415 | +#define VT_EXTERN 0x00000080 /* extern definition */ | |
| 416 | +#define VT_STATIC 0x00000100 /* static variable */ | |
| 417 | +#define VT_TYPEDEF 0x00000200 /* typedef definition */ | |
| 418 | +@end example | |
| 419 | + | |
| 420 | +@section Symbols | |
| 421 | + | |
| 422 | +All symbols are stored in hashed symbol stacks. Each symbol stack | |
| 423 | +contains @code{Sym} structures. | |
| 424 | + | |
| 425 | +@code{Sym.v} contains the symbol name (remember | |
| 426 | +an idenfier is also a token, so a string is never necessary to store | |
| 427 | +it). @code{Sym.t} gives the type of the symbol. @code{Sym.r} is usually | |
| 428 | +the register in which the corresponding variable is stored. @code{Sym.c} is | |
| 429 | +usually a constant associated to the symbol. | |
| 430 | + | |
| 431 | +Four main symbol stacks are defined: | |
| 432 | + | |
| 433 | +@table @code | |
| 434 | + | |
| 435 | +@item define_stack | |
| 436 | +for the macros (@code{#define}s). | |
| 437 | + | |
| 438 | +@item global_stack | |
| 439 | +for the global variables, functions and types. | |
| 440 | + | |
| 441 | +@item extern_stack | |
| 442 | +for the external symbols shared between files. | |
| 443 | + | |
| 444 | +@item local_stack | |
| 445 | +for the local variables, functions and types. | |
| 446 | + | |
| 447 | +@item label_stack | |
| 448 | +for the local labels (for @code{goto}). | |
| 449 | + | |
| 450 | +@end table | |
| 451 | + | |
| 452 | +@code{sym_push()} is used to add a new symbol in the local symbol | |
| 453 | +stack. If no local symbol stack is active, it is added in the global | |
| 454 | +symbol stack. | |
| 455 | + | |
| 456 | +@code{sym_pop(st,b)} pops symbols from the symbol stack @var{st} until | |
| 457 | +the symbol @var{b} is on the top of stack. If @var{b} is NULL, the stack | |
| 458 | +is emptied. | |
| 459 | + | |
| 460 | +@code{sym_find(v)} return the symbol associated to the identifier | |
| 461 | +@var{v}. The local stack is searched first from top to bottom, then the | |
| 462 | +global stack. | |
| 463 | + | |
| 464 | +@section Sections | |
| 465 | + | |
| 466 | +The generated code and datas are written in sections. The structure | |
| 467 | +@code{Section} contains all the necessary information for a given | |
| 468 | +section. @code{new_section()} creates a new section. ELF file semantics | |
| 469 | +is assumed for each section. | |
| 470 | + | |
| 471 | +The following sections are predefined: | |
| 472 | + | |
| 473 | +@table @code | |
| 474 | + | |
| 475 | +@item text_section | |
| 476 | +is the section containing the generated code. @var{ind} contains the | |
| 477 | +current position in the code section. | |
| 478 | + | |
| 479 | +@item data_section | |
| 480 | +contains initialized data | |
| 481 | + | |
| 482 | +@item bss_section | |
| 483 | +contains uninitialized data | |
| 484 | + | |
| 485 | +@item bounds_section | |
| 486 | +@itemx lbounds_section | |
| 487 | +are used when bound checking is activated | |
| 488 | + | |
| 489 | +@item stab_section | |
| 490 | +@itemx stabstr_section | |
| 491 | +are used when debugging is actived to store debug information | |
| 492 | + | |
| 493 | +@item symtab_section | |
| 494 | +@itemx strtab_section | |
| 495 | +contain the exported symbols (currently only used for debugging). | |
| 496 | + | |
| 497 | +@end table | |
| 498 | + | |
| 499 | +@section Code generation | |
| 500 | + | |
| 501 | +@subsection Introduction | |
| 502 | + | |
| 503 | +The TCC code generator directly generates linked binary code in one | |
| 504 | +pass. It is rather unusual these days (see gcc for example which | |
| 505 | +generates text assembly), but it allows to be very fast and surprisingly | |
| 506 | +not so complicated. | |
| 507 | + | |
| 508 | +The TCC code generator is register based. Optimization is only done at | |
| 509 | +the expression level. No intermediate representation of expression is | |
| 510 | +kept except the current values stored in the @emph{value stack}. | |
| 511 | + | |
| 512 | +On x86, three temporary registers are used. When more registers are | |
| 513 | +needed, one register is flushed in a new local variable. | |
| 514 | + | |
| 515 | +@subsection The value stack | |
| 516 | + | |
| 517 | +When an expression is parsed, its value is pushed on the value stack | |
| 518 | +(@var{vstack}). The top of the value stack is @var{vtop}. Each value | |
| 519 | +stack entry is the structure @code{SValue}. | |
| 520 | + | |
| 521 | +@code{SValue.t} is the type. @code{SValue.r} indicates how the value is | |
| 522 | +currently stored in the generated code. It is usually a CPU register | |
| 523 | +index (@code{REG_xxx} constants), but additionnal values and flags are | |
| 524 | +defined: | |
| 525 | + | |
| 526 | +@example | |
| 527 | +#define VT_CONST 0x00f0 /* constant in vc | |
| 528 | + (must be first non register value) */ | |
| 529 | +#define VT_LLOCAL 0x00f1 /* lvalue, offset on stack */ | |
| 530 | +#define VT_LOCAL 0x00f2 /* offset on stack */ | |
| 531 | +#define VT_CMP 0x00f3 /* the value is stored in processor flags (in vc) */ | |
| 532 | +#define VT_JMP 0x00f4 /* value is the consequence of jmp true (even) */ | |
| 533 | +#define VT_JMPI 0x00f5 /* value is the consequence of jmp false (odd) */ | |
| 534 | +#define VT_LVAL 0x0100 /* var is an lvalue */ | |
| 535 | +#define VT_FORWARD 0x0200 /* value is forward reference */ | |
| 536 | +#define VT_MUSTCAST 0x0400 /* value must be casted to be correct (used for | |
| 537 | + char/short stored in integer registers) */ | |
| 538 | +#define VT_MUSTBOUND 0x0800 /* bound checking must be done before | |
| 539 | + dereferencing value */ | |
| 540 | +#define VT_BOUNDED 0x8000 /* value is bounded. The address of the | |
| 541 | + bounding function call point is in vc */ | |
| 542 | +#define VT_LVAL_BYTE 0x1000 /* lvalue is a byte */ | |
| 543 | +#define VT_LVAL_SHORT 0x2000 /* lvalue is a short */ | |
| 544 | +#define VT_LVAL_UNSIGNED 0x4000 /* lvalue is unsigned */ | |
| 545 | +#define VT_LVAL_TYPE (VT_LVAL_BYTE | VT_LVAL_SHORT | VT_LVAL_UNSIGNED) | |
| 546 | +@end example | |
| 547 | + | |
| 548 | +@table @code | |
| 549 | + | |
| 550 | +@item VT_CONST | |
| 551 | +indicates that the value is a constant. It is stored in the union | |
| 552 | +@code{SValue.c}, depending on its type. | |
| 553 | + | |
| 554 | +@item VT_LOCAL | |
| 555 | +indicates a local variable pointer at offset @code{SValue.c.i} in the | |
| 556 | +stack. | |
| 557 | + | |
| 558 | +@item VT_CMP | |
| 559 | +indicates that the value is actually stored in the CPU flags (i.e. the | |
| 560 | +value is the consequence of a test). The value is either 0 or 1. The | |
| 561 | +actual CPU flags used is indicated in @code{SValue.c.i}. | |
| 562 | + | |
| 563 | +@item VT_JMP | |
| 564 | +@itemx VT_JMPI | |
| 565 | +indicates that the value is the consequence of a jmp. For VT_JMP, it is | |
| 566 | +1 if the jump is taken, 0 otherwise. For VT_JMPI it is inverted. | |
| 567 | + | |
| 568 | +These values are used to compile the @code{||} and @code{&&} logical | |
| 569 | +operators. | |
| 570 | + | |
| 571 | +@item VT_LVAL | |
| 572 | +is a flag indicating that the value is actually an lvalue (left value of | |
| 573 | +an assignment). It means that the value stored is actually a pointer to | |
| 574 | +the wanted value. | |
| 575 | + | |
| 576 | +Understanding the use @code{VT_LVAL} is very important if you want to | |
| 577 | +understand how TCC works. | |
| 578 | + | |
| 579 | +@item VT_LVAL_BYTE | |
| 580 | +@itemx VT_LVAL_SHORT | |
| 581 | +@itemx VT_LVAL_UNSIGNED | |
| 582 | +if the lvalue has an integer type, then these flags give its real | |
| 583 | +type. The type alone is not suffisant in case of cast optimisations. | |
| 584 | + | |
| 585 | +@item VT_LLOCAL | |
| 586 | +is a saved lvalue on the stack. @code{VT_LLOCAL} should be suppressed | |
| 587 | +ASAP because its semantics are rather complicated. | |
| 588 | + | |
| 589 | +@item VT_MUSTCAST | |
| 590 | +indicates that a cast to the value type must be performed if the value | |
| 591 | +is used (lazy casting). | |
| 592 | + | |
| 593 | +@item VT_FORWARD | |
| 594 | +indicates that the value is a forward reference to a variable or a function. | |
| 595 | + | |
| 596 | +@item VT_MUSTBOUND | |
| 597 | +@itemx VT_BOUNDED | |
| 598 | +are only used for optional bound checking. | |
| 599 | + | |
| 600 | +@end table | |
| 601 | + | |
| 602 | +@subsection Manipulating the value stack | |
| 603 | + | |
| 604 | +@code{vsetc()} and @code{vset()} pushes a new value on the value | |
| 605 | +stack. If the previous @code{vtop} was stored in a very unsafe place(for | |
| 606 | +example in the CPU flags), then some code is generated to put the | |
| 607 | +previous @code{vtop} in a safe storage. | |
| 608 | + | |
| 609 | +@code{vpop()} pops @code{vtop}. In some cases, it also generates cleanup | |
| 610 | +code (for example if stacked floating point registers are used as on | |
| 611 | +x86). | |
| 612 | + | |
| 613 | +The @code{gv(rc)} function generates code to evaluate @code{vtop} (the | |
| 614 | +top value of the stack) into registers. @var{rc} selects in which | |
| 615 | +register class the value should be put. @code{gv()} is the @emph{most | |
| 616 | +important function} of the code generator. | |
| 617 | + | |
| 618 | +@code{gv2()} is the same as @code{gv()} but for the top two stack | |
| 619 | +entries. | |
| 620 | + | |
| 621 | +@subsection CPU dependent code generation | |
| 622 | + | |
| 623 | +See the @file{i386-gen.c} file to have an example. | |
| 624 | + | |
| 625 | +@table @code | |
| 626 | + | |
| 627 | +@item load() | |
| 628 | +must generate the code needed to load a stack value into a register. | |
| 629 | + | |
| 630 | +@item store() | |
| 631 | +must generate the code needed to store a register into a stack value | |
| 632 | +lvalue. | |
| 633 | + | |
| 634 | +@item gfunc_start() | |
| 635 | +@itemx gfunc_param() | |
| 636 | +@itemx gfunc_call() | |
| 637 | +should generate a function call | |
| 638 | + | |
| 639 | +@item gfunc_prolog() | |
| 640 | +@itemx gfunc_epilog() | |
| 641 | +should generate a function prolog/epilog. | |
| 642 | + | |
| 643 | +@item gen_opi(op) | |
| 644 | +must generate the binary integer operation @var{op} on the two top | |
| 645 | +entries of the stack which are guaranted to contain integer types. | |
| 646 | + | |
| 647 | +The result value should be put on the stack. | |
| 648 | + | |
| 649 | +@item gen_opf(op) | |
| 650 | +same as @code{gen_opi()} for floating point operations. The two top | |
| 651 | +entries of the stack are guaranted to contain floating point values of | |
| 652 | +same types. | |
| 653 | + | |
| 654 | +@item gen_cvt_itof() | |
| 655 | +integer to floating point conversion. | |
| 656 | + | |
| 657 | +@item gen_cvt_ftoi() | |
| 658 | +floating point to integer conversion. | |
| 659 | + | |
| 660 | +@item gen_cvt_ftof() | |
| 661 | +floating point to floating point of different size conversion. | |
| 662 | + | |
| 663 | +@item gen_bounded_ptr_add() | |
| 664 | +@item gen_bounded_ptr_deref() | |
| 665 | +are only used for bound checking. | |
| 666 | + | |
| 667 | +@end table | |
| 668 | + | |
| 669 | +@section Optimizations done | |
| 316 | 670 | |
| 317 | −<hr> | |
| 318 | −Copyright (c) 2001, 2002 Fabrice Bellard <hr> | |
| 319 | −Fabrice Bellard - <em> fabrice.bellard at free.fr </em> - <A HREF="http://bellard.org/"> http://bellard.org/ </A> - <A HREF="http://www.tinycc.org/"> http://www.tinycc.org/ </A> | |
| 671 | +Constant propagation is done for all operations. Multiplications and | |
| 672 | +divisions are optimized to shifts when appropriate. Comparison | |
| 673 | +operators are optimized by maintaining a special cache for the | |
| 674 | +processor flags. &&, || and ! are optimized by maintaining a special | |
| 675 | +'jump target' value. No other jump optimization is currently performed | |
| 676 | +because it would require to store the code in a more abstract fashion. | |
| 320 | 677 | |
| 321 | −</body> | |
| 322 | −</html> | |