Unified · Split
| @@ -1,52 +1,97 @@ | |||
| 1 | <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> | 1 | \input texinfo @c -*- texinfo -*- |
| 2 | <html> | 2 | |
| 3 | <head> | 3 | @settitle Tiny C Compiler Reference Documentation |
| 4 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | 4 | @titlepage |
| 5 | <title> Tiny C Compiler Reference Documentation </title> | 5 | @sp 7 |
| 6 | </head> | 6 | @center @titlefont{Tiny C Compiler Reference Documentation} |
| 7 | <body> | 7 | @sp 3 |
| 8 | 8 | @end titlepage | |
| 9 | <center> | 9 | |
| 10 | <h1> | 10 | @chapter Introduction |
| 11 | Tiny C Compiler Reference Documentation | ||
| 12 | </h1> | ||
| 13 | </center> | ||
| 14 | |||
| 15 | <h2>Introduction</h2> | ||
| 16 | 11 | ||
| 17 | TinyCC (aka TCC) is a small but hyper fast C compiler. Unlike other C | 12 | TinyCC (aka TCC) is a small but hyper fast C compiler. Unlike other C |
| 18 | compilers, it is meant to be self-suffisant: you do not need an | 13 | compilers, it is meant to be self-suffisant: you do not need an |
| 19 | external assembler or linker because TCC does that for you. | 14 | external assembler or linker because TCC does that for you. |
| 20 | <P> | 15 | |
| 21 | TCC compiles so <em>fast</em> that even for big projects <tt>Makefile</tt>s may | 16 | TCC compiles so @emph{fast} that even for big projects @code{Makefile}s may |
| 22 | not be necessary. | 17 | not be necessary. |
| 23 | <P> | 18 | |
| 24 | TCC not only supports ANSI C, but also most of the new ISO C99 | 19 | TCC not only supports ANSI C, but also most of the new ISO C99 |
| 25 | standard and many GNUC extensions. | 20 | standard and many GNUC extensions. |
| 26 | <P> | 21 | |
| 27 | TCC can also be used to make <I>C scripts</I>, | 22 | TCC can also be used to make @emph{C scripts}, i.e. pieces of C source |
| 28 | i.e. pieces of C source that you run as a Perl or Python | 23 | that you run as a Perl or Python script. Compilation is so fast that |
| 29 | script. Compilation is so fast that your script will be as fast as if | 24 | your script will be as fast as if it was an executable. |
| 30 | it was an executable. | 25 | |
| 31 | <P> | 26 | TCC can also automatically generate memory and bound checks |
| 32 | TCC can also automatically generate <A HREF="#bounds">memory and bound | 27 | (@xref{bounds}) while allowing all C pointers operations. TCC can do |
| 33 | checks</A> while allowing all C pointers operations. TCC can do these | 28 | these checks even if non patched libraries are used. |
| 34 | checks even if non patched libraries are used. | 29 | |
| 35 | </P> | 30 | With @code{libtcc}, you can use TCC as a backend for dynamic code |
| 36 | 31 | generation (@xref{libtcc}). | |
| 37 | <h2>Full ANSI C support</h2> | 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 | TCC implements all the ANSI C standard, including structure bit fields | 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 | 85 | and floating point numbers (@code{long double}, @code{double}, and |
| 41 | <tt>float</tt> fully supported). The following limitations are known: | 86 | @code{float} fully supported). The following limitations are known: |
| 42 | 87 | ||
| 43 | <ul> | 88 | @itemize |
| 44 | <li> The preprocessor tokens are the same as C. It means that in some | 89 | @item The preprocessor tokens are the same as C. It means that in some |
| 45 | rare cases, preprocessed numbers are not handled exactly as in ANSI | 90 | rare cases, preprocessed numbers are not handled exactly as in ANSI |
| 46 | C. This approach has the advantage of being simpler and FAST! | 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 | TCC implements many features of the new C standard: ISO C99. Currently | 96 | TCC implements many features of the new C standard: ISO C99. Currently |
| 52 | missing items are: complex and imaginary numbers and variable length | 97 | missing items are: complex and imaginary numbers and variable length |
| @@ -54,77 +99,77 @@ arrays. · 1 unmodified line | |||
| 54 | 99 | ||
| 55 | Currently implemented ISOC99 features: | 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 | function name. | 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 | function-like macros: | 112 | function-like macros: |
| 68 | <PRE> | 113 | @example |
| 69 | #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__) | 114 | #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__) |
| 70 | </PRE> | 115 | @end example |
| 71 | <tt>dprintf</tt> can then be used with a variable number of parameters. | 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 | using designators: | 121 | using designators: |
| 77 | <PRE> | 122 | @example |
| 78 | struct { int x, y; } st[10] = { [0].x = 1, [0].y = 2 }; | 123 | struct { int x, y; } st[10] = { [0].x = 1, [0].y = 2 }; |
| 79 | 124 | ||
| 80 | int tab[10] = { 1, 2, [5] = 5, [9] = 9}; | 125 | int tab[10] = { 1, 2, [5] = 5, [9] = 9}; |
| 81 | </PRE> | 126 | @end example |
| 82 | 127 | ||
| 83 | <li> Compound initializers are supported: | 128 | @item Compound initializers are supported: |
| 84 | <PRE> | 129 | @example |
| 85 | int *p = (int []){ 1, 2, 3 }; | 130 | int *p = (int []){ 1, 2, 3 }; |
| 86 | </PRE> | 131 | @end example |
| 87 | to initialize a pointer pointing to an initialized array. The same | 132 | to initialize a pointer pointing to an initialized array. The same |
| 88 | works for structures and strings. | 133 | works for structures and strings. |
| 89 | 134 | ||
| 90 | <li> Hexadecimal floating point constants are supported: | 135 | @item Hexadecimal floating point constants are supported: |
| 91 | <PRE> | 136 | @example |
| 92 | double d = 0x1234p10; | 137 | double d = 0x1234p10; |
| 93 | </PRE> | 138 | @end example |
| 94 | is the same as writing | 139 | is the same as writing |
| 95 | <PRE> | 140 | @example |
| 96 | double d = 4771840.0; | 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. | 146 | @item @code{'restrict'} keyword is ignored. |
| 102 | </ul> | 147 | @end itemize |
| 103 | 148 | ||
| 104 | <h2>GNU C extensions</h2> | 149 | @section GNU C extensions |
| 105 | 150 | ||
| 106 | TCC implements some GNU C extensions: | 151 | TCC implements some GNU C extensions: |
| 107 | 152 | ||
| 108 | <ul> | 153 | @itemize |
| 109 | 154 | ||
| 110 | <li> array designators can be used without '=': | 155 | @item array designators can be used without '=': |
| 111 | <PRE> | 156 | @example |
| 112 | int a[10] = { [0] 1, [5] 2, 3, 4 }; | 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: | 160 | @item Structure field designators can be a label: |
| 116 | <PRE> | 161 | @example |
| 117 | struct { int x, y; } st = { x: 1, y: 1}; | 162 | struct { int x, y; } st = { x: 1, y: 1}; |
| 118 | </PRE> | 163 | @end example |
| 119 | instead of | 164 | instead of |
| 120 | <PRE> | 165 | @example |
| 121 | struct { int x, y; } st = { .x = 1, .y = 1}; | 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: | 171 | @item case ranges : ranges can be used in @code{case}s: |
| 127 | <PRE> | 172 | @example |
| 128 | switch(a) { | 173 | switch(a) { |
| 129 | case 1 ... 9: | 174 | case 1 ... 9: |
| 130 | printf("range 1 to 9\n"); | 175 | printf("range 1 to 9\n"); |
| @@ -133,104 +178,104 @@ instead of · 2 unmodified lines | |||
| 133 | printf("unexpected\n"); | 178 | printf("unexpected\n"); |
| 134 | break; | 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 | function attributes. The following attributes are supported: | 184 | function attributes. The following attributes are supported: |
| 140 | <ul> | 185 | @itemize |
| 141 | <li> <tt>aligned(n)</tt>: align data to n bytes (must be a power of two). | 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 | section name (name is a string containing the section name) instead | 189 | section name (name is a string containing the section name) instead |
| 145 | of the default section. | 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 | Here are some examples: | 200 | Here are some examples: |
| 156 | <PRE> | 201 | @example |
| 157 | int a __attribute__ ((aligned(8), section(".mysection"))); | 202 | int a __attribute__ ((aligned(8), section(".mysection"))); |
| 158 | </PRE> | 203 | @end example |
| 159 | <BR> | ||
| 160 | align variable <tt>'a'</tt> to 8 bytes and put it in section <tt>.mysection</tt>. | ||
| 161 | 204 | ||
| 162 | <PRE> | 205 | align variable @code{'a'} to 8 bytes and put it in section @code{.mysection}. |
| 206 | |||
| 207 | @example | ||
| 163 | int my_add(int a, int b) __attribute__ ((section(".mycodesection"))) | 208 | int my_add(int a, int b) __attribute__ ((section(".mycodesection"))) |
| 164 | { | 209 | { |
| 165 | return a + b; | 210 | return a + b; |
| 166 | } | 211 | } |
| 167 | </PRE> | 212 | @end example |
| 168 | <BR> | 213 | |
| 169 | generate function <tt>'my_add'</tt> in section <tt>.mycodesection</tt>. | 214 | generate function @code{'my_add'} in section @code{.mycodesection}. |
| 170 | </ul> | 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 | indicate that you use TCC. | 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 | 235 | @item Binary digits can be entered (@code{'0b101'} instead of |
| 184 | <tt>'5'</tt>). | 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> | 242 | @node bounds |
| 191 | <A NAME="bounds"></a> | 243 | @chapter TinyCC Memory and Bound checks |
| 192 | 244 | ||
| 193 | This feature is activated with the <A HREF="#invoke"><tt>'-b'</tt> | 245 | This feature is activated with the @code{'-b'} (@xref{invoke}). |
| 194 | option</A>. | 246 | |
| 195 | <P> | 247 | Note that pointer size is @emph{unchanged} and that code generated |
| 196 | Note that pointer size is <em>unchanged</em> and that code generated | 248 | with bound checks is @emph{fully compatible} with unchecked |
| 197 | with bound checks is <em>fully compatible</em> with unchecked | ||
| 198 | code. When a pointer comes from unchecked code, it is assumed to be | 249 | code. When a pointer comes from unchecked code, it is assumed to be |
| 199 | valid. Even very obscure C code with casts should work correctly. | 250 | valid. Even very obscure C code with casts should work correctly. |
| 200 | </P> | 251 | |
| 201 | <P> To have more information about the ideas behind this method, <A | 252 | To have more information about the ideas behind this method, check at |
| 202 | HREF="http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html">check | 253 | @url{http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html}. |
| 203 | here</A>. | 254 | |
| 204 | </P> | ||
| 205 | <P> | ||
| 206 | Here are some examples of catched errors: | 255 | Here are some examples of catched errors: |
| 207 | </P> | 256 | |
| 208 | <TABLE BORDER=1> | 257 | @table @asis |
| 209 | <TR> | 258 | |
| 210 | <TD> | 259 | @item Invalid range with standard string function: |
| 211 | <PRE> | 260 | @example |
| 212 | { | 261 | { |
| 213 | char tab[10]; | 262 | char tab[10]; |
| 214 | memset(tab, 0, 11); | 263 | memset(tab, 0, 11); |
| 215 | } | 264 | } |
| 216 | </PRE> | 265 | @end example |
| 217 | </TD><TD VALIGN=TOP>Invalid range with standard string function</TD> | ||
| 218 | 266 | ||
| 219 | <TR> | 267 | @item Bound error in global or local arrays: |
| 220 | <TD> | 268 | @example |
| 221 | <PRE> | ||
| 222 | { | 269 | { |
| 223 | int tab[10]; | 270 | int tab[10]; |
| 224 | for(i=0;i<11;i++) { | 271 | for(i=0;i<11;i++) { |
| 225 | sum += tab[i]; | 272 | sum += tab[i]; |
| 226 | } | 273 | } |
| 227 | } | 274 | } |
| 228 | </PRE> | 275 | @end example |
| 229 | </TD><TD VALIGN=TOP>Bound error in global or local arrays</TD> | ||
| 230 | 276 | ||
| 231 | <TR> | 277 | @item Bound error in allocated data: |
| 232 | <TD> | 278 | @example |
| 233 | <PRE> | ||
| 234 | { | 279 | { |
| 235 | int *tab; | 280 | int *tab; |
| 236 | tab = malloc(20 * sizeof(int)); | 281 | tab = malloc(20 * sizeof(int)); |
| @@ -239,12 +284,10 @@ Here are some examples of catched errors: · 2 unmodified lines | |||
| 239 | } | 284 | } |
| 240 | free(tab); | 285 | free(tab); |
| 241 | } | 286 | } |
| 242 | </PRE> | 287 | @end example |
| 243 | </TD><TD VALIGN=TOP>Bound error in allocated data</TD> | ||
| 244 | 288 | ||
| 245 | <TR> | 289 | @item Access to a freed region: |
| 246 | <TD> | 290 | @example |
| 247 | <PRE> | ||
| 248 | { | 291 | { |
| 249 | int *tab; | 292 | int *tab; |
| 250 | tab = malloc(20 * sizeof(int)); | 293 | tab = malloc(20 * sizeof(int)); |
| @@ -253,70 +296,382 @@ Here are some examples of catched errors: · 2 unmodified lines | |||
| 253 | sum += tab4[i]; | 296 | sum += tab4[i]; |
| 254 | } | 297 | } |
| 255 | } | 298 | } |
| 256 | </PRE> | 299 | @end example |
| 257 | </TD><TD VALIGN=TOP>Access to a freed region</TD> | ||
| 258 | 300 | ||
| 259 | <TR> | 301 | @item Freeing an already freed region: |
| 260 | <TD> | 302 | @example |
| 261 | <PRE> | ||
| 262 | { | 303 | { |
| 263 | int *tab; | 304 | int *tab; |
| 264 | tab = malloc(20 * sizeof(int)); | 305 | tab = malloc(20 * sizeof(int)); |
| 265 | free(tab); | 306 | free(tab); |
| 266 | free(tab); | 307 | free(tab); |
| 267 | } | 308 | } |
| 268 | </PRE> | 309 | @end example |
| 269 | </TD><TD VALIGN=TOP>Freeing an already freed region</TD> | ||
| 270 | 310 | ||
| 271 | </TABLE> | 311 | @end table |
| 272 | 312 | ||
| 273 | <h2> Command line invocation </h2> | 313 | @node libtcc |
| 274 | <A NAME="invoke"></a> | 314 | @chapter The @code{libtcc} library |
| 275 | 315 | ||
| 276 | <PRE> | 316 | The @code{libtcc} library enables you to use TCC as a backend for |
| 277 | usage: tcc [-Idir] [-Dsym[=val]] [-Usym] [-llib] [-g] [-b] | 317 | dynamic code generation. |
| 278 | [-i infile] infile [infile_args...] | ||
| 279 | </PRE> | ||
| 280 | 318 | ||
| 281 | <table> | 319 | Read the @file{libtcc.h} to have an overview of the API. Read |
| 282 | <tr><td>'-Idir'</td> | 320 | @file{libtcc_test.c} to have a very simple example. |
| 283 | <td>Specify an additionnal include path. The default ones are: | ||
| 284 | /usr/include, /usr/lib/tcc, /usr/local/lib/tcc.</td> | ||
| 285 | 321 | ||
| 286 | <tr><td>'-Dsym[=val]'</td> <td>Define preprocessor symbol 'sym' to | 322 | The idea consists in giving a C string containing the program you want |
| 287 | val. If val is not present, its value is '1'. Function-like macros can | 323 | to compile directly to @code{libtcc}. Then the @code{main()} function of |
| 288 | also be defined: <tt>'-DF(a)=a+1'</tt></td> | 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> | 328 | This chapter gives some hints to understand how TCC works. You can skip |
| 293 | <td>Dynamically link your program with library | 329 | it if you do not intend to modify the TCC code. |
| 294 | libxxx.so. Standard library paths are checked, including those | ||
| 295 | specified with LD_LIBRARY_PATH.</td> | ||
| 296 | 330 | ||
| 297 | <tr><td>'-g'</td> | 331 | @section File reading |
| 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> | ||
| 303 | 332 | ||
| 304 | <tr><td>'-b'</td> <td>Generate additionnal support code to check | 333 | The @code{BufferedFile} structure contains the context needed to read a |
| 305 | memory allocations and array/pointer bounds. '-g' is implied. Note | 334 | file, including the current line number. @code{tcc_open()} opens a new |
| 306 | that the generated code is slower and bigger in this case. | 335 | file and @code{tcc_close()} closes it. @code{inp()} returns the next |
| 307 | </td> | 336 | character. |
| 308 | 337 | ||
| 309 | <tr><td>'-i file'</td> | 338 | @section Lexer |
| 310 | <td>Compile C source 'file' before main C source. With this | 339 | |
| 311 | command, multiple C files can be compiled and linked together.</td> | 340 | @code{next()} reads the next token in the current |
| 312 | </table> | 341 | file. @code{next_nomacro()} reads the next token without macro |
| 313 | <br> | 342 | expansion. |
| 314 | Note: the <tt>'-o file'</tt> option to generate an ELF executable is | 343 | |
| 315 | currently unsupported. | 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> | 671 | Constant propagation is done for all operations. Multiplications and |
| 318 | Copyright (c) 2001, 2002 Fabrice Bellard <hr> | 672 | divisions are optimized to shifts when appropriate. Comparison |
| 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> | 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> | ||