update
[tinycc/miki.git] / tcc-doc.texi
blob8d252264341655a132d7be7dcebd541a1278eeb1
1 \input texinfo @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename tcc-doc.info
4 @settitle Tiny C Compiler Reference Documentation
5 @c %**end of header
7 @include config.texi
9 @iftex
10 @titlepage
11 @afourpaper
12 @sp 7
13 @center @titlefont{Tiny C Compiler Reference Documentation}
14 @sp 3
15 @end titlepage
16 @headings double
17 @end iftex
19 @c @ifhtml
20 @contents
21 @c @end ifhtml
23 @ifnothtml
24 @node Top, Introduction, (dir), (dir)
25 @top Tiny C Compiler Reference Documentation
27 This manual documents version @value{VERSION} of the Tiny C Compiler.
29 @menu
30 * Introduction::                Introduction to tcc.
31 * Invoke::                      Invocation of tcc (command line, options).
32 * Bounds::                      Automatic bounds-checking of C code.
33 * Libtcc::                      The libtcc library.
34 @end menu
35 @end ifnothtml
37 @node Introduction
38 @chapter Introduction
40 TinyCC (aka TCC) is a small but hyper fast C compiler. Unlike other C
41 compilers, it is meant to be self-relying: you do not need an
42 external assembler or linker because TCC does that for you.
44 TCC compiles so @emph{fast} that even for big projects @code{Makefile}s may
45 not be necessary. 
47 TCC not only supports ANSI C, but also most of the new ISO C99
48 standard and many GNUC extensions including inline assembly.
50 TCC can also be used to make @emph{C scripts}, i.e. pieces of C source
51 that you run as a Perl or Python script. Compilation is so fast that
52 your script will be as fast as if it was an executable.
54 TCC can also automatically generate memory and bound checks
55 (@pxref{Bounds}) while allowing all C pointers operations. TCC can do
56 these checks even if non patched libraries are used.
58 With @code{libtcc}, you can use TCC as a backend for dynamic code
59 generation (@pxref{Libtcc}).
61 @node Invoke
62 @chapter Command line invocation
64 [This manual documents version @value{VERSION} of the Tiny C Compiler]
66 @section Quick start
68 @example
69 @c man begin SYNOPSIS
70 usage: tcc [options] [@var{infile1} @var{infile2}@dots{}] [@option{-run} @var{infile} @var{args}@dots{}]
71 @c man end
72 @end example
74 @noindent
75 @c man begin DESCRIPTION
76 TCC options are a very much like gcc options. The main difference is that TCC
77 can also execute directly the resulting program and give it runtime
78 arguments.
80 Here are some examples to understand the logic:
82 @table @code
83 @item @samp{tcc -run a.c}
84 Compile @file{a.c} and execute it directly
86 @item @samp{tcc -run a.c arg1}
87 Compile a.c and execute it directly. arg1 is given as first argument to
88 the @code{main()} of a.c.
90 @item @samp{tcc a.c -run b.c arg1}
91 Compile @file{a.c} and @file{b.c}, link them together and execute them. arg1 is given
92 as first argument to the @code{main()} of the resulting program. Because
93 multiple C files are specified, @option{--} are necessary to clearly separate the
94 program arguments from the TCC options.
96 @item @samp{tcc -o myprog a.c b.c}
97 Compile @file{a.c} and @file{b.c}, link them and generate the executable @file{myprog}.
99 @item @samp{tcc -o myprog a.o b.o}
100 link @file{a.o} and @file{b.o} together and generate the executable @file{myprog}.
102 @item @samp{tcc -c a.c}
103 Compile @file{a.c} and generate object file @file{a.o}.
105 @item @samp{tcc -c asmfile.S}
106 Preprocess with C preprocess and assemble @file{asmfile.S} and generate
107 object file @file{asmfile.o}.
109 @item @samp{tcc -c asmfile.s}
110 Assemble (but not preprocess) @file{asmfile.s} and generate object file
111 @file{asmfile.o}.
113 @item @samp{tcc -r -o ab.o a.c b.c}
114 Compile @file{a.c} and @file{b.c}, link them together and generate the object file @file{ab.o}.
116 @end table
118 Scripting:
120 TCC can be invoked from @emph{scripts}, just as shell scripts. You just
121 need to add @code{#!/usr/local/bin/tcc -run} at the start of your C source:
123 @example
124 #!/usr/local/bin/tcc -run
125 #include <stdio.h>
127 int main() 
129     printf("Hello World\n");
130     return 0;
132 @end example
133 @c man end
135 @section Option summary
137 General Options:
139 @c man begin OPTIONS
140 @table @option
141 @item -v
142 Display current TCC version.
144 @item -c
145 Generate an object file (@option{-o} option must also be given).
147 @item -o outfile
148 Put object file, executable, or dll into output file @file{outfile}.
150 @item -Bdir
151 Set the path where the tcc internal libraries can be found (default is
152 @file{PREFIX/lib/tcc}).
154 @item -bench
155 Output compilation statistics.
157 @item -run source [args...]
159 Compile file @var{source} and run it with the command line arguments
160 @var{args}. In order to be able to give more than one argument to a
161 script, several TCC options can be given @emph{after} the
162 @option{-run} option, separated by spaces. Example:
164 @example
165 tcc "-run -L/usr/X11R6/lib -lX11" ex4.c
166 @end example
168 In a script, it gives the following header:
170 @example
171 #!/usr/local/bin/tcc -run -L/usr/X11R6/lib -lX11
172 #include <stdlib.h>
173 int main(int argc, char **argv)
175     ...
177 @end example
179 @end table
181 Preprocessor options:
183 @table @option
184 @item -Idir
185 Specify an additional include path. Include paths are searched in the
186 order they are specified.
188 System include paths are always searched after. The default system
189 include paths are: @file{/usr/local/include}, @file{/usr/include}
190 and @file{PREFIX/lib/tcc/include}. (@file{PREFIX} is usually
191 @file{/usr} or @file{/usr/local}).
193 @item -Dsym[=val]
194 Define preprocessor symbol @samp{sym} to
195 val. If val is not present, its value is @samp{1}. Function-like macros can
196 also be defined: @option{-DF(a)=a+1}
198 @item -Usym
199 Undefine preprocessor symbol @samp{sym}.
200 @end table
202 Warning options:
204 @table @option
205 @item -w
206 Disable all warnings.
208 @end table
210 Note: each of the following warning options has a negative form beginning with
211 @option{-Wno-}.
213 @table @option
214 @item -Wunsupported
215 Warn about unsupported GCC features that are ignored by TCC.
217 @item -Wwrite-strings
218 Make string constants being of type @code{const char *} intead of @code{char
221 @item -Werror
222 Abort compilation if warnings are issued.
224 @item -Wall 
225 Activate all warnings, except @option{-Werror}, @option{-Wunusupported} and
226 @option{-Wwrite-strings} (currently not useful).
228 @end table
230 Linker options:
232 @table @option
233 @item -Ldir
234 Specify an additional static library path for the @option{-l} option. The
235 default library paths are @file{/usr/local/lib}, @file{/usr/lib} and @file{/lib}.
237 @item -lxxx
238 Link your program with dynamic library libxxx.so or static library
239 libxxx.a. The library is searched in the paths specified by the
240 @option{-L} option.
242 @item -shared
243 Generate a shared library instead of an executable (@option{-o} option
244 must also be given).
246 @item -static
247 Generate a statically linked executable (default is a shared linked
248 executable) (@option{-o} option must also be given).
250 @item -rdynamic
251 Export global symbols to the dynamic linker. It is useful when a library
252 opened with @code{dlopen()} needs to access executable symbols.
254 @item -r
255 Generate an object file combining all input files (@option{-o} option must
256 also be given).
258 @end table
260 Debugger options:
262 @table @option
263 @item -g
264 Generate run time debug information so that you get clear run time
265 error messages: @code{ test.c:68: in function 'test5()': dereferencing
266 invalid pointer} instead of the laconic @code{Segmentation
267 fault}.
269 @item -b
270 Generate additional support code to check
271 memory allocations and array/pointer bounds. @option{-g} is implied. Note
272 that the generated code is slower and bigger in this case.
274 @item -bt N
275 Display N callers in stack traces. This is useful with @option{-g} or
276 @option{-b}.
278 @end table
280 Note: GCC options @option{-Ox}, @option{-fx} and @option{-mx} are
281 ignored.
282 @c man end
284 @ignore
286 @setfilename tcc
287 @settitle Tiny C Compiler
289 @c man begin SEEALSO
290 gcc(1)
291 @c man end
293 @c man begin AUTHOR
294 Fabrice Bellard
295 @c man end
297 @end ignore
299 @chapter C language support
301 @section ANSI C
303 TCC implements all the ANSI C standard, including structure bit fields
304 and floating point numbers (@code{long double}, @code{double}, and
305 @code{float} fully supported).
307 @section ISOC99 extensions
309 TCC implements many features of the new C standard: ISO C99. Currently
310 missing items are: complex and imaginary numbers and variable length
311 arrays.
313 Currently implemented ISOC99 features:
315 @itemize
317 @item 64 bit @code{long long} types are fully supported.
319 @item The boolean type @code{_Bool} is supported.
321 @item @code{__func__} is a string variable containing the current
322 function name.
324 @item Variadic macros: @code{__VA_ARGS__} can be used for
325    function-like macros:
326 @example
327     #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__)
328 @end example
330 @noindent
331 @code{dprintf} can then be used with a variable number of parameters.
333 @item Declarations can appear anywhere in a block (as in C++).
335 @item Array and struct/union elements can be initialized in any order by
336   using designators:
337 @example
338     struct @{ int x, y; @} st[10] = @{ [0].x = 1, [0].y = 2 @};
340     int tab[10] = @{ 1, 2, [5] = 5, [9] = 9@};
341 @end example
342     
343 @item Compound initializers are supported:
344 @example
345     int *p = (int [])@{ 1, 2, 3 @};
346 @end example
347 to initialize a pointer pointing to an initialized array. The same
348 works for structures and strings.
350 @item Hexadecimal floating point constants are supported:
351 @example
352           double d = 0x1234p10;
353 @end example
355 @noindent
356 is the same as writing 
357 @example
358           double d = 4771840.0;
359 @end example
361 @item @code{inline} keyword is ignored.
363 @item @code{restrict} keyword is ignored.
364 @end itemize
366 @section GNU C extensions
368 TCC implements some GNU C extensions:
370 @itemize
372 @item array designators can be used without '=': 
373 @example
374     int a[10] = @{ [0] 1, [5] 2, 3, 4 @};
375 @end example
377 @item Structure field designators can be a label: 
378 @example
379     struct @{ int x, y; @} st = @{ x: 1, y: 1@};
380 @end example
381 instead of
382 @example
383     struct @{ int x, y; @} st = @{ .x = 1, .y = 1@};
384 @end example
386 @item @code{\e} is ASCII character 27.
388 @item case ranges : ranges can be used in @code{case}s:
389 @example
390     switch(a) @{
391     case 1 @dots{} 9:
392           printf("range 1 to 9\n");
393           break;
394     default:
395           printf("unexpected\n");
396           break;
397     @}
398 @end example
400 @item The keyword @code{__attribute__} is handled to specify variable or
401 function attributes. The following attributes are supported:
402   @itemize
403   @item @code{aligned(n)}: align data to n bytes (must be a power of two).
405   @item @code{section(name)}: generate function or data in assembly
406   section name (name is a string containing the section name) instead
407   of the default section.
409   @item @code{unused}: specify that the variable or the function is unused.
411   @item @code{cdecl}: use standard C calling convention.
413   @item @code{stdcall}: use Pascal-like calling convention.
415   @end itemize
417 Here are some examples:
418 @example
419     int a __attribute__ ((aligned(8), section(".mysection")));
420 @end example
422 @noindent
423 align variable @code{a} to 8 bytes and put it in section @code{.mysection}.
425 @example
426     int my_add(int a, int b) __attribute__ ((section(".mycodesection"))) 
427     @{
428         return a + b;
429     @}
430 @end example
432 @noindent
433 generate function @code{my_add} in section @code{.mycodesection}.
435 @item GNU style variadic macros:
436 @example
437     #define dprintf(fmt, args@dots{}) printf(fmt, ## args)
439     dprintf("no arg\n");
440     dprintf("one arg %d\n", 1);
441 @end example
443 @item @code{__FUNCTION__} is interpreted as C99 @code{__func__} 
444 (so it has not exactly the same semantics as string literal GNUC
445 where it is a string literal).
447 @item The @code{__alignof__} keyword can be used as @code{sizeof} 
448 to get the alignment of a type or an expression.
450 @item The @code{typeof(x)} returns the type of @code{x}. 
451 @code{x} is an expression or a type.
453 @item Computed gotos: @code{&&label} returns a pointer of type 
454 @code{void *} on the goto label @code{label}. @code{goto *expr} can be
455 used to jump on the pointer resulting from @code{expr}.
457 @item Inline assembly with asm instruction:
458 @cindex inline assembly
459 @cindex assembly, inline
460 @cindex __asm__
461 @example
462 static inline void * my_memcpy(void * to, const void * from, size_t n)
464 int d0, d1, d2;
465 __asm__ __volatile__(
466         "rep ; movsl\n\t"
467         "testb $2,%b4\n\t"
468         "je 1f\n\t"
469         "movsw\n"
470         "1:\ttestb $1,%b4\n\t"
471         "je 2f\n\t"
472         "movsb\n"
473         "2:"
474         : "=&c" (d0), "=&D" (d1), "=&S" (d2)
475         :"0" (n/4), "q" (n),"1" ((long) to),"2" ((long) from)
476         : "memory");
477 return (to);
479 @end example
481 @noindent
482 @cindex gas
483 TCC includes its own x86 inline assembler with a @code{gas}-like (GNU
484 assembler) syntax. No intermediate files are generated. GCC 3.x named
485 operands are supported.
487 @item @code{__builtin_types_compatible_p()} and @code{__builtin_constant_p()} 
488 are supported.
490 @end itemize
492 @section TinyCC extensions
494 @itemize
496 @item @code{__TINYC__} is a predefined macro to @code{1} to
497 indicate that you use TCC.
499 @item @code{#!} at the start of a line is ignored to allow scripting.
501 @item Binary digits can be entered (@code{0b101} instead of
502 @code{5}).
504 @item @code{__BOUNDS_CHECKING_ON} is defined if bound checking is activated.
506 @end itemize
508 @chapter TinyCC Assembler
510 Since version 0.9.16, TinyCC integrates its own assembler. TinyCC
511 assembler supports a gas-like syntax (GNU assembler). You can
512 desactivate assembler support if you want a smaller TinyCC executable
513 (the C compiler does not rely on the assembler).
515 TinyCC Assembler is used to handle files with @file{.S} (C
516 preprocessed assembler) and @file{.s} extensions. It is also used to
517 handle the GNU inline assembler with the @code{asm} keyword.
519 @section Syntax
521 TinyCC Assembler supports most of the gas syntax. The tokens are the
522 same as C.
524 @itemize
526 @item C and C++ comments are supported.
528 @item Identifiers are the same as C, so you cannot use '.' or '$'.
530 @item Only 32 bit integer numbers are supported.
532 @end itemize
534 @section Expressions
536 @itemize
538 @item Integers in decimal, octal and hexa are supported.
540 @item Unary operators: +, -, ~.
542 @item Binary operators in decreasing priority order:
544 @enumerate
545 @item *, /, %
546 @item &, |, ^
547 @item +, -
548 @end enumerate
550 @item A value is either an absolute number or a label plus an offset. 
551 All operators accept absolute values except '+' and '-'. '+' or '-' can be
552 used to add an offset to a label. '-' supports two labels only if they
553 are the same or if they are both defined and in the same section.
555 @end itemize
557 @section Labels
559 @itemize
561 @item All labels are considered as local, except undefined ones.
563 @item Numeric labels can be used as local @code{gas}-like labels. 
564 They can be defined several times in the same source. Use 'b'
565 (backward) or 'f' (forward) as suffix to reference them:
567 @example
568  1:
569       jmp 1b /* jump to '1' label before */
570       jmp 1f /* jump to '1' label after */
571  1:
572 @end example
574 @end itemize
576 @section Directives
577 @cindex assembler directives
578 @cindex directives, assembler
579 @cindex .align
580 @cindex .skip
581 @cindex .space
582 @cindex .byte
583 @cindex .word
584 @cindex .short
585 @cindex .int
586 @cindex .long
587 @cindex .string
588 @cindex .globl
589 @cindex .section
590 @cindex .text
591 @cindex .data
592 @cindex .bss
594 All directives are preceeded by a '.'. The following directives are
595 supported:
597 @itemize
598 @item .align n[,value]
599 @item .skip n[,value]
600 @item .space n[,value]
601 @item .byte value1[,value2...]
602 @item .word value1[,value2...]
603 @item .short value1[,value2...]
604 @item .int value1[,value2...]
605 @item .long value1[,value2...]
606 @item .string string
607 @item .global symbol
608 @item .section section
609 @item .text
610 @item .data
611 @item .bss
612 @end itemize
614 @section X86 Assembler
615 @cindex assembler
617 All X86 opcodes are supported. Only ATT syntax is supported (source
618 then destination operand order). If no size suffix is given, TinyCC
619 tries to guess it from the operand sizes.
621 Currently, MMX opcodes are supported but not SSE ones.
623 @chapter TinyCC Linker
624 @cindex linker
626 @section ELF file generation
627 @cindex ELF
629 TCC can directly output relocatable ELF files (object files),
630 executable ELF files and dynamic ELF libraries without relying on an
631 external linker.
633 Dynamic ELF libraries can be output but the C compiler does not generate
634 position independent code (PIC). It means that the dynamic library
635 code generated by TCC cannot be factorized among processes yet.
637 TCC linker eliminates unreferenced object code in libraries. A single pass is
638 done on the object and library list, so the order in which object files and
639 libraries are specified is important (same constraint as GNU ld). No grouping
640 options (@option{--start-group} and @option{--end-group}) are supported.
642 @section ELF file loader
644 TCC can load ELF object files, archives (.a files) and dynamic
645 libraries (.so).
647 @section GNU Linker Scripts
648 @cindex scripts, linker
649 @cindex linker scripts
650 @cindex GROUP, linker command
651 @cindex FILE, linker command
652 @cindex OUTPUT_FORMAT, linker command
653 @cindex TARGET, linker command
655 Because on many Linux systems some dynamic libraries (such as
656 @file{/usr/lib/libc.so}) are in fact GNU ld link scripts (horrible!),
657 the TCC linker also supports a subset of GNU ld scripts.
659 The @code{GROUP} and @code{FILE} commands are supported. @code{OUTPUT_FORMAT}
660 and @code{TARGET} are ignored.
662 Example from @file{/usr/lib/libc.so}:
663 @example
664 /* GNU ld script
665    Use the shared library, but some functions are only in
666    the static library, so try that secondarily.  */
667 GROUP ( /lib/libc.so.6 /usr/lib/libc_nonshared.a )
668 @end example
670 @node Bounds
671 @chapter TinyCC Memory and Bound checks
672 @cindex bound checks
673 @cindex memory checks
675 This feature is activated with the @option{-b} (@pxref{Invoke}).
677 Note that pointer size is @emph{unchanged} and that code generated
678 with bound checks is @emph{fully compatible} with unchecked
679 code. When a pointer comes from unchecked code, it is assumed to be
680 valid. Even very obscure C code with casts should work correctly.
682 For more information about the ideas behind this method, see
683 @url{http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html}.
685 Here are some examples of caught errors:
687 @table @asis
689 @item Invalid range with standard string function:
690 @example
692     char tab[10];
693     memset(tab, 0, 11);
695 @end example
697 @item Out of bounds-error in global or local arrays:
698 @example
700     int tab[10];
701     for(i=0;i<11;i++) @{
702         sum += tab[i];
703     @}
705 @end example
707 @item Out of bounds-error in malloc'ed data:
708 @example
710     int *tab;
711     tab = malloc(20 * sizeof(int));
712     for(i=0;i<21;i++) @{
713         sum += tab4[i];
714     @}
715     free(tab);
717 @end example
719 @item Access of freed memory:
720 @example
722     int *tab;
723     tab = malloc(20 * sizeof(int));
724     free(tab);
725     for(i=0;i<20;i++) @{
726         sum += tab4[i];
727     @}
729 @end example
731 @item Double free:
732 @example
734     int *tab;
735     tab = malloc(20 * sizeof(int));
736     free(tab);
737     free(tab);
739 @end example
741 @end table
743 @node Libtcc
744 @chapter The @code{libtcc} library
746 The @code{libtcc} library enables you to use TCC as a backend for
747 dynamic code generation. 
749 Read the @file{libtcc.h} to have an overview of the API. Read
750 @file{libtcc_test.c} to have a very simple example.
752 The idea consists in giving a C string containing the program you want
753 to compile directly to @code{libtcc}. Then you can access to any global
754 symbol (function or variable) defined.
756 @chapter Developer's guide
758 This chapter gives some hints to understand how TCC works. You can skip
759 it if you do not intend to modify the TCC code.
761 @section File reading
763 The @code{BufferedFile} structure contains the context needed to read a
764 file, including the current line number. @code{tcc_open()} opens a new
765 file and @code{tcc_close()} closes it. @code{inp()} returns the next
766 character.
768 @section Lexer
770 @code{next()} reads the next token in the current
771 file. @code{next_nomacro()} reads the next token without macro
772 expansion.
774 @code{tok} contains the current token (see @code{TOK_xxx})
775 constants. Identifiers and keywords are also keywords. @code{tokc}
776 contains additional infos about the token (for example a constant value
777 if number or string token).
779 @section Parser
781 The parser is hardcoded (yacc is not necessary). It does only one pass,
782 except:
784 @itemize
786 @item For initialized arrays with unknown size, a first pass 
787 is done to count the number of elements.
789 @item For architectures where arguments are evaluated in 
790 reverse order, a first pass is done to reverse the argument order.
792 @end itemize
794 @section Types
796 The types are stored in a single 'int' variable. It was choosen in the
797 first stages of development when tcc was much simpler. Now, it may not
798 be the best solution.
800 @example
801 #define VT_INT        0  /* integer type */
802 #define VT_BYTE       1  /* signed byte type */
803 #define VT_SHORT      2  /* short type */
804 #define VT_VOID       3  /* void type */
805 #define VT_PTR        4  /* pointer */
806 #define VT_ENUM       5  /* enum definition */
807 #define VT_FUNC       6  /* function type */
808 #define VT_STRUCT     7  /* struct/union definition */
809 #define VT_FLOAT      8  /* IEEE float */
810 #define VT_DOUBLE     9  /* IEEE double */
811 #define VT_LDOUBLE   10  /* IEEE long double */
812 #define VT_BOOL      11  /* ISOC99 boolean type */
813 #define VT_LLONG     12  /* 64 bit integer */
814 #define VT_LONG      13  /* long integer (NEVER USED as type, only
815                             during parsing) */
816 #define VT_BTYPE      0x000f /* mask for basic type */
817 #define VT_UNSIGNED   0x0010  /* unsigned type */
818 #define VT_ARRAY      0x0020  /* array type (also has VT_PTR) */
819 #define VT_BITFIELD   0x0040  /* bitfield modifier */
821 #define VT_STRUCT_SHIFT 16   /* structure/enum name shift (16 bits left) */
822 @end example
824 When a reference to another type is needed (for pointers, functions and
825 structures), the @code{32 - VT_STRUCT_SHIFT} high order bits are used to
826 store an identifier reference.
828 The @code{VT_UNSIGNED} flag can be set for chars, shorts, ints and long
829 longs.
831 Arrays are considered as pointers @code{VT_PTR} with the flag
832 @code{VT_ARRAY} set.
834 The @code{VT_BITFIELD} flag can be set for chars, shorts, ints and long
835 longs. If it is set, then the bitfield position is stored from bits
836 VT_STRUCT_SHIFT to VT_STRUCT_SHIFT + 5 and the bit field size is stored
837 from bits VT_STRUCT_SHIFT + 6 to VT_STRUCT_SHIFT + 11.
839 @code{VT_LONG} is never used except during parsing.
841 During parsing, the storage of an object is also stored in the type
842 integer:
844 @example
845 #define VT_EXTERN  0x00000080  /* extern definition */
846 #define VT_STATIC  0x00000100  /* static variable */
847 #define VT_TYPEDEF 0x00000200  /* typedef definition */
848 @end example
850 @section Symbols
852 All symbols are stored in hashed symbol stacks. Each symbol stack
853 contains @code{Sym} structures.
855 @code{Sym.v} contains the symbol name (remember
856 an idenfier is also a token, so a string is never necessary to store
857 it). @code{Sym.t} gives the type of the symbol. @code{Sym.r} is usually
858 the register in which the corresponding variable is stored. @code{Sym.c} is
859 usually a constant associated to the symbol.
861 Four main symbol stacks are defined:
863 @table @code
865 @item define_stack
866 for the macros (@code{#define}s).
868 @item global_stack
869 for the global variables, functions and types.
871 @item local_stack
872 for the local variables, functions and types.
874 @item global_label_stack
875 for the local labels (for @code{goto}).
877 @item label_stack
878 for GCC block local labels (see the @code{__label__} keyword).
880 @end table
882 @code{sym_push()} is used to add a new symbol in the local symbol
883 stack. If no local symbol stack is active, it is added in the global
884 symbol stack.
886 @code{sym_pop(st,b)} pops symbols from the symbol stack @var{st} until
887 the symbol @var{b} is on the top of stack. If @var{b} is NULL, the stack
888 is emptied.
890 @code{sym_find(v)} return the symbol associated to the identifier
891 @var{v}. The local stack is searched first from top to bottom, then the
892 global stack.
894 @section Sections
896 The generated code and datas are written in sections. The structure
897 @code{Section} contains all the necessary information for a given
898 section. @code{new_section()} creates a new section. ELF file semantics
899 is assumed for each section.
901 The following sections are predefined:
903 @table @code
905 @item text_section
906 is the section containing the generated code. @var{ind} contains the
907 current position in the code section.
909 @item data_section
910 contains initialized data
912 @item bss_section
913 contains uninitialized data
915 @item bounds_section
916 @itemx lbounds_section
917 are used when bound checking is activated
919 @item stab_section
920 @itemx stabstr_section
921 are used when debugging is actived to store debug information
923 @item symtab_section
924 @itemx strtab_section
925 contain the exported symbols (currently only used for debugging).
927 @end table
929 @section Code generation
930 @cindex code generation
932 @subsection Introduction
934 The TCC code generator directly generates linked binary code in one
935 pass. It is rather unusual these days (see gcc for example which
936 generates text assembly), but it can be very fast and surprisingly
937 little complicated.
939 The TCC code generator is register based. Optimization is only done at
940 the expression level. No intermediate representation of expression is
941 kept except the current values stored in the @emph{value stack}.
943 On x86, three temporary registers are used. When more registers are
944 needed, one register is spilled into a new temporary variable on the stack.
946 @subsection The value stack
947 @cindex value stack, introduction
949 When an expression is parsed, its value is pushed on the value stack
950 (@var{vstack}). The top of the value stack is @var{vtop}. Each value
951 stack entry is the structure @code{SValue}.
953 @code{SValue.t} is the type. @code{SValue.r} indicates how the value is
954 currently stored in the generated code. It is usually a CPU register
955 index (@code{REG_xxx} constants), but additional values and flags are
956 defined:
958 @example
959 #define VT_CONST     0x00f0
960 #define VT_LLOCAL    0x00f1
961 #define VT_LOCAL     0x00f2
962 #define VT_CMP       0x00f3
963 #define VT_JMP       0x00f4
964 #define VT_JMPI      0x00f5
965 #define VT_LVAL      0x0100
966 #define VT_SYM       0x0200
967 #define VT_MUSTCAST  0x0400
968 #define VT_MUSTBOUND 0x0800
969 #define VT_BOUNDED   0x8000
970 #define VT_LVAL_BYTE     0x1000
971 #define VT_LVAL_SHORT    0x2000
972 #define VT_LVAL_UNSIGNED 0x4000
973 #define VT_LVAL_TYPE     (VT_LVAL_BYTE | VT_LVAL_SHORT | VT_LVAL_UNSIGNED)
974 @end example
976 @table @code
978 @item VT_CONST
979 indicates that the value is a constant. It is stored in the union
980 @code{SValue.c}, depending on its type.
982 @item VT_LOCAL
983 indicates a local variable pointer at offset @code{SValue.c.i} in the
984 stack.
986 @item VT_CMP
987 indicates that the value is actually stored in the CPU flags (i.e. the
988 value is the consequence of a test). The value is either 0 or 1. The
989 actual CPU flags used is indicated in @code{SValue.c.i}. 
991 If any code is generated which destroys the CPU flags, this value MUST be
992 put in a normal register.
994 @item VT_JMP
995 @itemx VT_JMPI
996 indicates that the value is the consequence of a conditional jump. For VT_JMP,
997 it is 1 if the jump is taken, 0 otherwise. For VT_JMPI it is inverted.
999 These values are used to compile the @code{||} and @code{&&} logical
1000 operators.
1002 If any code is generated, this value MUST be put in a normal
1003 register. Otherwise, the generated code won't be executed if the jump is
1004 taken.
1006 @item VT_LVAL
1007 is a flag indicating that the value is actually an lvalue (left value of
1008 an assignment). It means that the value stored is actually a pointer to
1009 the wanted value. 
1011 Understanding the use @code{VT_LVAL} is very important if you want to
1012 understand how TCC works.
1014 @item VT_LVAL_BYTE
1015 @itemx VT_LVAL_SHORT
1016 @itemx VT_LVAL_UNSIGNED
1017 if the lvalue has an integer type, then these flags give its real
1018 type. The type alone is not enough in case of cast optimisations.
1020 @item VT_LLOCAL
1021 is a saved lvalue on the stack. @code{VT_LLOCAL} should be eliminated
1022 ASAP because its semantics are rather complicated.
1024 @item VT_MUSTCAST
1025 indicates that a cast to the value type must be performed if the value
1026 is used (lazy casting).
1028 @item VT_SYM
1029 indicates that the symbol @code{SValue.sym} must be added to the constant.
1031 @item VT_MUSTBOUND
1032 @itemx VT_BOUNDED
1033 are only used for optional bound checking.
1035 @end table
1037 @subsection Manipulating the value stack
1038 @cindex value stack
1040 @code{vsetc()} and @code{vset()} pushes a new value on the value
1041 stack. If the previous @var{vtop} was stored in a very unsafe place(for
1042 example in the CPU flags), then some code is generated to put the
1043 previous @var{vtop} in a safe storage.
1045 @code{vpop()} pops @var{vtop}. In some cases, it also generates cleanup
1046 code (for example if stacked floating point registers are used as on
1047 x86).
1049 The @code{gv(rc)} function generates code to evaluate @var{vtop} (the
1050 top value of the stack) into registers. @var{rc} selects in which
1051 register class the value should be put. @code{gv()} is the @emph{most
1052 important function} of the code generator.
1054 @code{gv2()} is the same as @code{gv()} but for the top two stack
1055 entries.
1057 @subsection CPU dependent code generation
1058 @cindex CPU dependent
1059 See the @file{i386-gen.c} file to have an example.
1061 @table @code
1063 @item load()
1064 must generate the code needed to load a stack value into a register.
1066 @item store()
1067 must generate the code needed to store a register into a stack value
1068 lvalue.
1070 @item gfunc_start()
1071 @itemx gfunc_param()
1072 @itemx gfunc_call()
1073 should generate a function call
1075 @item gfunc_prolog()
1076 @itemx gfunc_epilog()
1077 should generate a function prolog/epilog.
1079 @item gen_opi(op)
1080 must generate the binary integer operation @var{op} on the two top
1081 entries of the stack which are guaranted to contain integer types.
1083 The result value should be put on the stack.
1085 @item gen_opf(op)
1086 same as @code{gen_opi()} for floating point operations. The two top
1087 entries of the stack are guaranted to contain floating point values of
1088 same types.
1090 @item gen_cvt_itof()
1091 integer to floating point conversion.
1093 @item gen_cvt_ftoi()
1094 floating point to integer conversion.
1096 @item gen_cvt_ftof()
1097 floating point to floating point of different size conversion.
1099 @item gen_bounded_ptr_add()
1100 @item gen_bounded_ptr_deref()
1101 are only used for bounds checking.
1103 @end table
1105 @section Optimizations done
1106 @cindex optimizations
1107 @cindex constant propagation
1108 @cindex strength reduction
1109 @cindex comparison operators
1110 @cindex caching processor flags
1111 @cindex flags, caching
1112 @cindex jump optimization
1113 Constant propagation is done for all operations. Multiplications and
1114 divisions are optimized to shifts when appropriate. Comparison
1115 operators are optimized by maintaining a special cache for the
1116 processor flags. &&, || and ! are optimized by maintaining a special
1117 'jump target' value. No other jump optimization is currently performed
1118 because it would require to store the code in a more abstract fashion.
1120 @unnumbered Concept Index
1121 @printindex cp
1123 @bye
1125 @c Local variables:
1126 @c fill-column: 78
1127 @c texinfo-column-for-description: 32
1128 @c End: