[Tinycc-devel] [PATCH] [1/2] tcc-doc.texi

[Peter \"Firefly\" Lund]

Formating fixes...

 tcc-doc.texi |  299 +++++++++++++++++++++++++++++++++++++----------------------
 1 files changed, 190 insertions(+), 109 deletions(-)

-Peter

Why should George W. Bush care what the American people think?
After all they did not vote for him.


--- tcc-0.9.16/tcc-doc.texi     Mon Dec 30 20:07:52 2002
+++ tcc-3/tcc-doc.texi  Thu Mar  6 01:01:12 2003
@@ -1,12 +1,44 @@
 \input texinfo @c -*- texinfo -*-
-
address@hidden %**start of header
address@hidden tcc-doc.info
 @settitle Tiny C Compiler Reference Documentation
address@hidden %**end of header
+
address@hidden version.texi
+
address@hidden
+Bla bla bla
address@hidden ifinfo
+
address@hidden
 @titlepage
address@hidden
 @sp 7
 @center @titlefont{Tiny C Compiler Reference Documentation}
 @sp 3
 @end titlepage
address@hidden double
address@hidden iftex
+
address@hidden
address@hidden
address@hidden ifnothtml
+
address@hidden
address@hidden Top, Introduction, (dir), (dir)
address@hidden Tiny C Compiler Reference Documentation
+
+This manual documents version @value{VERSION} of the Tiny C Compiler.
+
address@hidden
+* Introduction::                Introduction to tcc.
+* Invoke::                      Invocation of tcc (command line, options).
+* Bounds::                      Automatic bounds-checking of C code.
+* Libtcc::                      bla bla bla.
address@hidden menu
address@hidden ifnottex

address@hidden Introduction
 @chapter Introduction

 TinyCC (aka TCC) is a small but hyper fast C compiler. Unlike other C
@@ -24,13 +56,13 @@
 your script will be as fast as if it was an executable.

 TCC can also automatically generate memory and bound checks
-(@xref{bounds}) while allowing all C pointers operations. TCC can do
+(@pxref{Bounds}) while allowing all C pointers operations. TCC can do
 these checks even if non patched libraries are used.

 With @code{libtcc}, you can use TCC as a backend for dynamic code
-generation (@xref{libtcc}).
+generation (@pxref{Libtcc}).

address@hidden invoke
address@hidden Invoke
 @chapter Command line invocation

 @section Quick start
@@ -41,45 +73,46 @@
            [--] infile1 [infile2... --] [infile_args...]
 @end example

-TCC options are a very much like gcc. The main difference is that TCC
address@hidden
+TCC options are a very much like gcc options. The main difference is that TCC
 can also execute directly the resulting program and give it runtime
 arguments.

 Here are some examples to understand the logic:

 @table @code
address@hidden tcc a.c
-Compile a.c and execute it directly
address@hidden @samp{tcc a.c}
+Compile @file{a.c} and execute it directly

address@hidden tcc a.c arg1
address@hidden @samp{tcc a.c arg1}
 Compile a.c and execute it directly. arg1 is given as first argument to
 the @code{main()} of a.c.

address@hidden tcc -- a.c b.c -- arg1
-Compile a.c and b.c, link them together and execute them. arg1 is given
address@hidden @samp{tcc -- a.c b.c -- arg1}
+Compile @file{a.c} and @file{b.c}, link them together and execute them. arg1 
is given
 as first argument to the @code{main()} of the resulting program. Because
-multiple C files are specified, @code{--} are necessary to clearly separate the
+multiple C files are specified, @option{--} are necessary to clearly separate 
the
 program arguments from the TCC options.

address@hidden tcc -o myprog a.c b.c
-Compile a.c and b.c, link them and generate the executable myprog.
address@hidden @samp{tcc -o myprog a.c b.c}
+Compile @file{a.c} and @file{b.c}, link them and generate the executable 
@file{myprog}.

address@hidden tcc -o myprog a.o b.o
-link a.o and b.o together and generate the executable myprog.
address@hidden @samp{tcc -o myprog a.o b.o}
+link @file{a.o} and @file{b.o} together and generate the executable 
@file{myprog}.

address@hidden tcc -c a.c
-Compile a.c and generate object file a.o
address@hidden @samp{tcc -c a.c}
+Compile @file{a.c} and generate object file @file{a.o}.

address@hidden tcc -c asmfile.S
-Preprocess with C preprocess and assemble asmfile.S and generate
-object file asmfile.o.
address@hidden @samp{tcc -c asmfile.S}
+Preprocess with C preprocess and assemble @file{asmfile.S} and generate
+object file @file{asmfile.o}.

address@hidden tcc -c asmfile.s
-Assemble (but not preprocess) asmfile.s and generate object file
-asmfile.o.
address@hidden @samp{tcc -c asmfile.s}
+Assemble (but not preprocess) @file{asmfile.s} and generate object file
address@hidden

address@hidden tcc -r -o ab.o a.c b.c
-Compile a.c and b.c, link them together and generate the object file ab.o.
address@hidden @samp{tcc -r -o ab.o a.c b.c}
+Compile @file{a.c} and @file{b.c}, link them together and generate the object 
file @file{ab.o}.

 @end table

@@ -93,19 +126,19 @@
 #include <stdio.h>

 int main()
-{
address@hidden
     printf("Hello World\n");
     return 0;
-}
address@hidden
 @end example

 @section Option summary

 General Options:

address@hidden @samp
address@hidden @option
 @item -c
-Generate an object file (@samp{-o} option must also be given).
+Generate an object file (@option{-o} option must also be given).

 @item -o outfile
 Put object file, executable, or dll into output file @file{outfile}.
@@ -120,54 +153,54 @@

 Preprocessor options:

address@hidden @samp
address@hidden @option
 @item -Idir
 Specify an additionnal include path. Include paths are searched in the
 order they are specified.

 System include paths are always searched after. The default system
 include paths are: @file{/usr/local/include}, @file{/usr/include}
-and @file{PREFIX/lib/tcc/include}. (@code{PREFIX} is usually
+and @file{PREFIX/lib/tcc/include}. (@file{PREFIX} is usually
 @file{/usr} or @file{/usr/local}).

 @item -Dsym[=val]
-Define preprocessor symbol 'sym' to
-val. If val is not present, its value is '1'. Function-like macros can
-also be defined: @code{'-DF(a)=a+1'}
+Define preprocessor symbol @samp{sym} to
+val. If val is not present, its value is @samp{1}. Function-like macros can
+also be defined: @option{-DF(a)=a+1}

 @item -Usym
-Undefine preprocessor symbol 'sym'.
+Undefine preprocessor symbol @samp{sym}.
 @end table

 Linker options:

address@hidden @samp
address@hidden @option
 @item -Ldir
-Specify an additionnal static library path for the @samp{-l} option. The
+Specify an additionnal static library path for the @option{-l} option. The
 default library paths are @file{/usr/local/lib}, @file{/usr/lib} and 
@file{/lib}.

 @item -lxxx
 Link your program with dynamic library libxxx.so or static library
 libxxx.a. The library is searched in the paths specified by the
address@hidden option.
address@hidden option.

 @item -shared
-Generate a shared library instead of an executable (@samp{-o} option
+Generate a shared library instead of an executable (@option{-o} option
 must also be given).

 @item -static
 Generate a statically linked executable (default is a shared linked
-executable) (@samp{-o} option must also be given).
+executable) (@option{-o} option must also be given).

 @item -r
-Generate an object file combining all input files (@samp{-o} option must
+Generate an object file combining all input files (@option{-o} option must
 also be given).

 @end table

 Debugger options:

address@hidden @samp
address@hidden @option
 @item -g
 Generate run time debug information so that you get clear run time
 error messages: @code{ test.c:68: in function 'test5()': dereferencing
@@ -176,16 +209,16 @@

 @item -b
 Generate additionnal support code to check
-memory allocations and array/pointer bounds. @samp{-g} is implied. Note
+memory allocations and array/pointer bounds. @option{-g} is implied. Note
 that the generated code is slower and bigger in this case.

 @item -bt N
-Display N callers in stack traces. This is useful with @samp{-g} or
address@hidden
+Display N callers in stack traces. This is useful with @option{-g} or
address@hidden

 @end table

-Note: GCC options @samp{-Ox}, @samp{-Wx}, @samp{-fx} and @samp{-mx} are
+Note: GCC options @option{-Ox}, @option{-Wx}, @option{-fx} and @option{-mx} are
 ignored.

 @chapter C language support
@@ -206,11 +239,11 @@

 @itemize

address@hidden 64 bit @code{'long long'} types are fully supported.
address@hidden 64 bit @code{long long} types are fully supported.

address@hidden The boolean type @code{'_Bool'} is supported.
address@hidden The boolean type @code{_Bool} is supported.

address@hidden @code{'__func__'} is a string variable containing the current
address@hidden @code{__func__} is a string variable containing the current
 function name.

 @item Variadic macros: @code{__VA_ARGS__} can be used for
@@ -218,6 +251,8 @@
 @example
     #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__)
 @end example
+
address@hidden
 @code{dprintf} can then be used with a variable number of parameters.

 @item Declarations can appear anywhere in a block (as in C++).
@@ -225,14 +260,14 @@
 @item Array and struct/union elements can be initialized in any order by
   using designators:
 @example
-    struct { int x, y; } st[10] = { [0].x = 1, [0].y = 2 };
+    struct @{ int x, y; @} st[10] = @{ [0].x = 1, [0].y = 2 @};

-    int tab[10] = { 1, 2, [5] = 5, [9] = 9};
+    int tab[10] = @{ 1, 2, [5] = 5, [9] = address@hidden;
 @end example

 @item Compound initializers are supported:
 @example
-    int *p = (int []){ 1, 2, 3 };
+    int *p = (int [])@{ 1, 2, 3 @};
 @end example
 to initialize a pointer pointing to an initialized array. The same
 works for structures and strings.
@@ -241,14 +276,16 @@
 @example
           double d = 0x1234p10;
 @end example
+
address@hidden
 is the same as writing
 @example
           double d = 4771840.0;
 @end example

address@hidden @code{'inline'} keyword is ignored.
address@hidden @code{inline} keyword is ignored.

address@hidden @code{'restrict'} keyword is ignored.
address@hidden @code{restrict} keyword is ignored.
 @end itemize

 @section GNU C extensions
@@ -259,30 +296,30 @@

 @item array designators can be used without '=':
 @example
-    int a[10] = { [0] 1, [5] 2, 3, 4 };
+    int a[10] = @{ [0] 1, [5] 2, 3, 4 @};
 @end example

 @item Structure field designators can be a label:
 @example
-    struct { int x, y; } st = { x: 1, y: 1};
+    struct @{ int x, y; @} st = @{ x: 1, y: address@hidden;
 @end example
 instead of
 @example
-    struct { int x, y; } st = { .x = 1, .y = 1};
+    struct @{ int x, y; @} st = @{ .x = 1, .y = address@hidden;
 @end example

address@hidden @code{'\e'} is ASCII character 27.
address@hidden @code{\e} is ASCII character 27.

 @item case ranges : ranges can be used in @code{case}s:
 @example
-    switch(a) {
-    case 1 ... 9:
+    switch(a) @{
+    case 1 @dots{} 9:
           printf("range 1 to 9\n");
           break;
     default:
           printf("unexpected\n");
           break;
-    }
+    @}
 @end example

 @item The keyword @code{__attribute__} is handled to specify variable or
@@ -307,20 +344,22 @@
     int a __attribute__ ((aligned(8), section(".mysection")));
 @end example

-align variable @code{'a'} to 8 bytes and put it in section @code{.mysection}.
address@hidden
+align variable @code{a} to 8 bytes and put it in section @code{.mysection}.

 @example
     int my_add(int a, int b) __attribute__ ((section(".mycodesection")))
-    {
+    @{
         return a + b;
-    }
+    @}
 @end example

-generate function @code{'my_add'} in section @code{.mycodesection}.
address@hidden
+generate function @code{my_add} in section @code{.mycodesection}.

 @item GNU style variadic macros:
 @example
-    #define dprintf(fmt, args...) printf(fmt, ## args)
+    #define dprintf(fmt, address@hidden) printf(fmt, ## args)

     dprintf("no arg\n");
     dprintf("one arg %d\n", 1);
@@ -341,26 +380,31 @@
 used to jump on the pointer resulting from @code{expr}.

 @item Inline assembly with asm instruction:
address@hidden inline assembly
address@hidden assembly, inline
address@hidden __asm__
 @example
 static inline void * my_memcpy(void * to, const void * from, size_t n)
-{
address@hidden
 int d0, d1, d2;
 __asm__ __volatile__(
-       "rep ; movsl\n\t"
-       "testb $2,%b4\n\t"
-       "je 1f\n\t"
-       "movsw\n"
-       "1:\ttestb $1,%b4\n\t"
-       "je 2f\n\t"
-       "movsb\n"
-       "2:"
-       : "=&c" (d0), "=&D" (d1), "=&S" (d2)
-       :"0" (n/4), "q" (n),"1" ((long) to),"2" ((long) from)
-       : "memory");
+        "rep ; movsl\n\t"
+        "testb $2,%b4\n\t"
+        "je 1f\n\t"
+        "movsw\n"
+        "1:\ttestb $1,%b4\n\t"
+        "je 2f\n\t"
+        "movsb\n"
+        "2:"
+        : "=&c" (d0), "=&D" (d1), "=&S" (d2)
+        :"0" (n/4), "q" (n),"1" ((long) to),"2" ((long) from)
+        : "memory");
 return (to);
-}
address@hidden
 @end example

address@hidden
address@hidden gas
 TCC includes its own x86 inline assembler with a @code{gas}-like (GNU
 assembler) syntax. No intermediate files are generated. GCC 3.x named
 operands are also supported.
@@ -371,13 +415,13 @@

 @itemize

address@hidden @code{__TINYC__} is a predefined macro to @code{'1'} to
address@hidden @code{__TINYC__} is a predefined macro to @code{1} to
 indicate that you use TCC.

address@hidden @code{'#!'} at the start of a line is ignored to allow scripting.
address@hidden @code{#!} at the start of a line is ignored to allow scripting.

address@hidden Binary digits can be entered (@code{'0b101'} instead of
address@hidden'5'}).
address@hidden Binary digits can be entered (@code{0b101} instead of
address@hidden).

 @item @code{__BOUNDS_CHECKING_ON} is defined if bound checking is activated.

@@ -452,6 +496,16 @@
 @end itemize

 @section Directives
address@hidden assembler directives
address@hidden directives, assembler
address@hidden .align
address@hidden .skip
address@hidden .space
address@hidden .byte
address@hidden .word
address@hidden .short
address@hidden .int
address@hidden .long

 All directives are preceeded by a '.'. The following directives are
 supported:
@@ -468,6 +522,7 @@
 @end itemize

 @section X86 Assembler
address@hidden assembler

 All X86 opcodes are supported. Only ATT syntax is supported (source
 then destination operand order). If no size suffix is given, TinyCC
@@ -476,8 +531,10 @@
 Currently, MMX opcodes are supported but not SSE ones.

 @chapter TinyCC Linker
address@hidden linker

 @section ELF file generation
address@hidden ELF

 TCC can directly output relocatable ELF files (object files),
 executable ELF files and dynamic ELF libraries without relying on an
@@ -498,6 +555,10 @@
 libraries (.so).

 @section GNU Linker Scripts
address@hidden scripts, linker
address@hidden linker scripts
address@hidden GROUP, linker command
address@hidden FILE, linker command

 Because on many Linux systems some dynamic libraries (such as
 @file{/usr/lib/libc.so}) are in fact GNU ld link scripts (horrible!),
@@ -513,10 +574,12 @@
 GROUP ( /lib/libc.so.6 /usr/lib/libc_nonshared.a )
 @end example

address@hidden bounds
address@hidden Bounds
 @chapter TinyCC Memory and Bound checks
address@hidden bound checks
address@hidden memory checks

-This feature is activated with the @code{'-b'} (@xref{invoke}).
+This feature is activated with the @option{-b} (@pxref{Invoke}).

 Note that pointer size is @emph{unchanged} and that code generated
 with bound checks is @emph{fully compatible} with unchecked
@@ -532,59 +595,59 @@

 @item Invalid range with standard string function:
 @example
-{
address@hidden
     char tab[10];
     memset(tab, 0, 11);
-}
address@hidden
 @end example

 @item Bound error in global or local arrays:
 @example
-{
address@hidden
     int tab[10];
-    for(i=0;i<11;i++) {
+    for(i=0;i<11;i++) @{
         sum += tab[i];
-    }
-}
+    @}
address@hidden
 @end example

 @item Bound error in allocated data:
 @example
-{
address@hidden
     int *tab;
     tab = malloc(20 * sizeof(int));
-    for(i=0;i<21;i++) {
+    for(i=0;i<21;i++) @{
         sum += tab4[i];
-    }
+    @}
     free(tab);
-}
address@hidden
 @end example

 @item Access to a freed region:
 @example
-{
address@hidden
     int *tab;
     tab = malloc(20 * sizeof(int));
     free(tab);
-    for(i=0;i<20;i++) {
+    for(i=0;i<20;i++) @{
         sum += tab4[i];
-    }
-}
+    @}
address@hidden
 @end example

 @item Freeing an already freed region:
 @example
-{
address@hidden
     int *tab;
     tab = malloc(20 * sizeof(int));
     free(tab);
     free(tab);
-}
address@hidden
 @end example

 @end table

address@hidden libtcc
address@hidden Libtcc
 @chapter The @code{libtcc} library

 The @code{libtcc} library enables you to use TCC as a backend for
@@ -597,7 +660,7 @@
 to compile directly to @code{libtcc}. Then the @code{main()} function of
 the compiled string can be launched.

address@hidden Developper's guide
address@hidden Developer's guide

 This chapter gives some hints to understand how TCC works. You can skip
 it if you do not intend to modify the TCC code.
@@ -768,6 +831,7 @@
 @end table

 @section Code generation
address@hidden code generation

 @subsection Introduction

@@ -784,6 +848,7 @@
 needed, one register is flushed in a new local variable.

 @subsection The value stack
address@hidden value stack, introduction

 When an expression is parsed, its value is pushed on the value stack
 (@var{vstack}). The top of the value stack is @var{vtop}. Each value
@@ -874,17 +939,18 @@
 @end table

 @subsection Manipulating the value stack
address@hidden value stack

 @code{vsetc()} and @code{vset()} pushes a new value on the value
-stack. If the previous @code{vtop} was stored in a very unsafe place(for
+stack. If the previous @var{vtop} was stored in a very unsafe place(for
 example in the CPU flags), then some code is generated to put the
-previous @code{vtop} in a safe storage.
+previous @var{vtop} in a safe storage.

address@hidden()} pops @code{vtop}. In some cases, it also generates cleanup
address@hidden()} pops @var{vtop}. In some cases, it also generates cleanup
 code (for example if stacked floating point registers are used as on
 x86).

-The @code{gv(rc)} function generates code to evaluate @code{vtop} (the
+The @code{gv(rc)} function generates code to evaluate @var{vtop} (the
 top value of the stack) into registers. @var{rc} selects in which
 register class the value should be put. @code{gv()} is the @emph{most
 important function} of the code generator.
@@ -893,7 +959,7 @@
 entries.

 @subsection CPU dependent code generation
-
address@hidden CPU dependent
 See the @file{i386-gen.c} file to have an example.

 @table @code
@@ -941,7 +1007,13 @@
 @end table

 @section Optimizations done
-
address@hidden optimizations
address@hidden constant propagation
address@hidden strength reduction
address@hidden comparison operators
address@hidden caching processor flags
address@hidden flags, caching
address@hidden jump optimization
 Constant propagation is done for all operations. Multiplications and
 divisions are optimized to shifts when appropriate. Comparison
 operators are optimized by maintaining a special cache for the
@@ -949,3 +1021,12 @@
 'jump target' value. No other jump optimization is currently performed
 because it would require to store the code in a more abstract fashion.

address@hidden Concept Index
address@hidden cp
+
address@hidden
+
address@hidden Local variables:
address@hidden fill-column: 78
address@hidden texinfo-column-for-description: 32
address@hidden End: