From 2ba12e83b3599ca8f5d50c179fe5138fe956f0c9 Mon Sep 17 00:00:00 2001 From: Huang Zhaobin Date: Tue, 4 Aug 2026 00:59:13 +0800 Subject: [PATCH] doc: update tcc-doc.texi to match current implementation Most of the manual predates the x86-64, ARM64, RISC-V 64 and Mach-O targets, and parts of it describe things TCC never did or no longer does. Go through it against the sources: the target table, the C11 and GNU C extensions, the attributes, built-ins and pragmas, the command line options and their defaults, the assembler and linker chapters, the bound checks and the libtcc call sequence. The developer's guide had drifted the most, from CType and Sym.type down to gfunc_call() and next_c(), and is resynced as well. The option groups become @subheading instead of plain text. texi2pod.pl has no handler for it and would copy them verbatim into tcc.1, so add one beside the @subsection handler, and move '@c man begin OPTIONS' above the first heading so that all of them reach the man page. --- tcc-doc.texi | 888 ++++++++++++++++++++++++++++++++++++++++----------- texi2pod.pl | 2 + 2 files changed, 704 insertions(+), 186 deletions(-) diff --git a/tcc-doc.texi b/tcc-doc.texi index 6a1870ae..1ffc0b24 100644 --- a/tcc-doc.texi +++ b/tcc-doc.texi @@ -49,8 +49,8 @@ external assembler or linker because TCC does that for you. TCC compiles so @emph{fast} that even for big projects @code{Makefile}s may not be necessary. -TCC not only supports ANSI C, but also most of the new ISO C99 -standard and many GNUC extensions including inline assembly. +TCC not only supports ANSI C, but also most of the ISO C99 standard, +many ISO C11 features, and many GNUC extensions including inline assembly. TCC can also be used to make @emph{C scripts}, i.e. pieces of C source that you run as a Perl or Python script. Compilation is so fast that @@ -63,10 +63,23 @@ these checks even if non patched libraries are used. With @code{libtcc}, you can use TCC as a backend for dynamic code generation (@pxref{Libtcc}). -TCC mainly supports the i386 target on Linux and Windows. There are alpha -ports for the ARM (@code{arm-tcc}) and the TMS320C67xx targets -(@code{c67-tcc}). More information about the ARM port is available at -@url{http://lists.gnu.org/archive/html/tinycc-devel/2003-10/msg00044.html}. +TCC supports the following target and platform combinations: + +@multitable @columnfractions .15 .10 .12 .11 .11 .18 .09 +@item @strong{OS} @tab @strong{i386} @tab @strong{x86-64} @tab @strong{ARM} @tab @strong{ARM64} @tab @strong{RISC-V 64} @tab @strong{C67} +@item Linux @tab yes @tab yes @tab yes @tab yes @tab yes @tab yes +@item macOS @tab @tab yes @tab @tab yes @tab @tab +@item Windows @tab yes @tab yes @tab WinCE @tab yes @tab @tab +@item Android @tab yes @tab yes @tab yes @tab yes @tab @tab +@item FreeBSD @tab @tab yes @tab @tab yes @tab @tab +@item NetBSD @tab @tab yes @tab yes @tab yes @tab @tab +@item OpenBSD @tab yes @tab yes @tab @tab yes @tab yes @tab +@item DragonFly @tab @tab yes @tab @tab @tab @tab +@end multitable + +The TMS320C67xx (C67) target is a cross compiler for the digital signal +processors of that family. It outputs COFF instead of ELF and has neither +@file{libtcc1.a} nor bound checking. For usage on Windows, see also @url{tcc-win32.txt}. @@ -99,9 +112,9 @@ the @code{main()} of a.c. @item @samp{tcc a.c -run 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. -@ignore -Because multiple C files are specified, @option{--} are necessary to clearly +as first argument to the @code{main()} of the resulting program. +@ignore +Because multiple C files are specified, @option{--} are necessary to clearly separate the program arguments from the TCC options. @end ignore @@ -136,14 +149,14 @@ need to add @code{#!/usr/local/bin/tcc -run} at the start of your C source: #!/usr/local/bin/tcc -run #include -int main() +int main() @{ printf("Hello World\n"); return 0; @} @end example -TCC can read C source code from @emph{standard input} when @option{-} is used in +TCC can read C source code from @emph{standard input} when @option{-} is used in place of @option{infile}. Example: @example @@ -153,9 +166,9 @@ echo 'main()@{puts("hello");@}' | tcc -run - @section Option summary -General Options: - @c man begin OPTIONS +@subheading General Options + @table @option @item -c Generate an object file. @@ -176,6 +189,11 @@ In a script, it gives the following header: #!/usr/local/bin/tcc -run -L/usr/X11R6/lib -lX11 @end example +@item -rstdin file +With @option{-run}: reopen standard input from @file{file} before executing +the program. This is mainly useful when the C source itself was read from +standard input (see @option{-} above). + @item -v Display TCC version. @@ -185,19 +203,28 @@ Show included files. As sole argument, print search dirs. -vvv shows tries too @item -bench Display compilation statistics. +@item -dumpmachine +Print target machine architecture triplet. + +@item -dumpversion +Print TCC compiler version. + @end table -Preprocessor options: +@subheading Preprocessor Options @table @option @item -Idir Specify an additional 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}. (@file{PREFIX} is usually -@file{/usr} or @file{/usr/local}). +System include paths are always searched after. The defaults are +@file{@var{tccdir}/include} and then @file{/usr/include}, where +@var{tccdir} is the tcc private directory (@file{PREFIX/lib/tcc}, see +@option{-B}; @file{PREFIX} is usually @file{/usr} or @file{/usr/local}). +On Windows the defaults are @file{@var{tccdir}/include} and +@file{@var{tccdir}/include/winapi}. Use @option{-vv} as sole argument to +print the paths of the current build. @item -isystem dir Specify a system include path to be added to the defaults. @@ -234,7 +261,7 @@ Same as @option{-opt}. @end table -Compilation flags: +@subheading Compilation Flags Note: each of the following options has a negative form beginning with @option{-fno-}. @@ -246,8 +273,10 @@ Let the @code{char} type be unsigned. @item -fsigned-char Let the @code{char} type be signed. -@item -fno-common -Do not generate common symbols for uninitialized data. +@item -fcommon +Generate common symbols for uninitialized data. The default is +@option{-fno-common}, which puts tentative definitions directly in the +bss section. @item -fleading-underscore Add a leading underscore at the beginning of each C symbol. @@ -275,7 +304,7 @@ or sofile.tcov file is generated with code coverage. @end table -Warning options: +@subheading Warning Options @table @option @item -w @@ -305,18 +334,22 @@ Abort compilation if a warning is issued. Can be given an option to enable the specified warning and turn it into an error, for example @option{-Werror=unsupported}. -@item -Wall +@item -Wall Activate some useful warnings (@option{-Wimplicit-function-declaration}, -@option{-Wdiscard-qualifiers}). +@option{-Wdiscarded-qualifiers}). @end table -Linker options: +@subheading Linker Options @table @option @item -Ldir Specify an additional static library path for the @option{-l} option. The -default library paths are @file{/usr/local/lib}, @file{/usr/lib} and @file{/lib}. +defaults are the tcc private directory (see @option{-B}) and +@file{/usr/lib}, which the build may replace by the library directory of +the host (@file{/usr/lib64} or a multiarch triplet directory). On Windows +the default is @file{@var{tccdir}/lib}. Use @option{-vv} as sole argument +to print the paths of the current build. @item -lxxx Link your program with dynamic library libxxx.so or static library @@ -341,6 +374,9 @@ executable). Export global symbols to the dynamic linker. It is useful when a library opened with @code{dlopen()} needs to access executable symbols. +@item -pthread +Preprocess with @option{-D_REENTRANT} and link with @option{-lpthread}. + @item -r Generate an object file combining all input files. @@ -348,9 +384,8 @@ Generate an object file combining all input files. Don't implicitly link with libc, the C runtime files, and libtcc1. @item -Wl,-nostdlib -Don't search the default paths for libraries (@file{/usr/local/lib}, -@file{/usr/lib} and @file{/lib}). Only the paths specified with @option{-L} -and @env{LIBRARY_PATH} are searched. +Don't search the default library paths (see @option{-L}). Only the paths +specified with @option{-L} and @env{LIBRARY_PATH} are searched. @item -Wl,-rpath=path Put custom search path for dynamic libraries into executable. @@ -401,7 +436,7 @@ Turn on/off linking of all objects in archives. @end table -Debugger options: +@subheading Debugger Options @table @option @item -g @@ -427,22 +462,20 @@ is provided to trigger a stack trace with a message on demand. @end table -Misc options: +@subheading Misc Options @table @option @item -std=version -Define @code{__STDC_VERSION__}: @code{201112} if @option{version} is c11 or -gnu11; @code{199901} otherwise. +Define @code{__STDC_VERSION__} to @code{201112} if @option{version} is +c11 or gnu11; @code{199901} otherwise. @item -x[c|a|b|n] Specify content of next input file: respectively C, assembly, binary, or none. @item -O[n] -Same as @option{-D__OPTIMIZE__} except for -O0. - -@item -pthread -Preprocess with @option{-D_REENTRANT}, link with @option{-lpthread}. +Same as @option{-D__OPTIMIZE__} except for -O0. @option{-Os} is treated +the same as @option{-O1}. @item -M Just output makefile fragment with dependencies @@ -466,15 +499,12 @@ Mention all dependencies as targets too. Print the configured installation directory and a list of library and include directories tcc will search. -@item -dumpversion -Print version. - @item -dt With @option{-run}/@option{-E}: auto-define 'test_...' macros @end table -Target specific options: +@subheading Target Specific Options @table @option @item -mms-bitfields @@ -492,7 +522,49 @@ Pass command line to the i386/x86_64 cross compiler. @end table -Note: GCC options @option{-fx} and @option{-mx} are ignored. +@subheading macOS Specific Options (Mach-O Targets Only) + +@table @option +@item -dynamiclib +Generate a dynamic library instead of an executable. + +@item -install_name name +Set the install name for a dynamic library. + +@item -flat_namespace +Use a flat namespace (ignored, accepted for compatibility). + +@item -two_levelnamespace +Use a two-level namespace (default, accepted for compatibility). + +@item -undefined @var{treatment} +Specify how undefined symbols are treated (accepted for compatibility). + +@item -compatibility_version version +Set the compatibility version for a dynamic library. + +@item -current_version version +Set the current version for a dynamic library. + +@end table + +@subheading Tool Modes + +@table @option +@item tcc -ar [crstvx] lib [files] +Create a static library archive. TCC can function as an @command{ar} +replacement without requiring an external archiver tool. The +@code{[abdiopN]} keys are not supported. + +@item tcc -impdef lib.dll [-v] [-o lib.def] (Windows only) +Create a @file{.def} definition file from a DLL. + +@end table + +Note: GCC options @option{-fx}, @option{-mx}, @option{-arch}, @option{-C}, +@option{--param}, @option{-pedantic}, @option{-pie}, @option{-no-pie}, +@option{-pipe}, @option{-s}, and @option{-traditional} are ignored. +@option{-Wunsupported} makes TCC warn about them. @c man end @c man begin ENVIRONMENT @@ -574,7 +646,7 @@ function name. int tab[10] = @{ 1, 2, [5] = 5, [9] = 9@}; @end example - + @item Compound initializers are supported: @example int *p = (int [])@{ 1, 2, 3 @}; @@ -588,28 +660,64 @@ works for structures and strings. @end example @noindent -is the same as writing +is the same as writing @example double d = 4771840.0; @end example -@item @code{inline} keyword is ignored. +@item @code{inline} keyword is supported. Static inline functions are +emitted at the end of the compilation unit only if used. The behavior +of @code{extern inline} depends on @option{-fgnu89-inline} (@pxref{Invoke}). @item @code{restrict} keyword is ignored. @end itemize +@section ISO C11 extensions + +TCC implements several features of the ISO C11 standard: + +@itemize + +@item @code{_Generic} keyword for type-generic expressions: +@example + #define print_type(x) _Generic((x), \ + int: "int", \ + float: "float", \ + default: "other") +@end example + +@item @code{_Static_assert(expr, msg)} for compile-time assertions. +The single-argument form @code{_Static_assert(expr)} (C23) is also +supported. + +@item @code{_Atomic} type qualifier for atomic types. + +@item @code{_Thread_local} storage-class specifier for thread-local +storage. The GCC extension @code{__thread} is also supported. + +@item @code{_Noreturn} function specifier (equivalent to the +@code{__attribute__((noreturn))} GNU extension). + +@item @code{_Alignas(n)} specifier to request alignment of a variable +or structure field. + +@item @code{_Alignof} operator to query the alignment of a type or +expression. + +@end itemize + @section GNU C extensions TCC implements some GNU C extensions: @itemize -@item array designators can be used without '=': +@item array designators can be used without '=': @example int a[10] = @{ [0] 1, [5] 2, 3, 4 @}; @end example -@item Structure field designators can be a label: +@item Structure field designators can be a label: @example struct @{ int x, y; @} st = @{ x: 1, y: 1@}; @end example @@ -636,11 +744,26 @@ instead of @cindex packed attribute @cindex section attribute @cindex unused attribute +@cindex cleanup attribute +@cindex constructor attribute +@cindex destructor attribute +@cindex always_inline attribute +@cindex alias attribute +@cindex visibility attribute +@cindex weak attribute +@cindex noreturn attribute @cindex cdecl attribute @cindex stdcall attribute +@cindex fastcall attribute +@cindex thiscall attribute @cindex regparm attribute +@cindex mode attribute @cindex dllexport attribute +@cindex dllimport attribute @cindex nodecorate attribute +@cindex format attribute +@cindex used attribute +@cindex nodebug attribute @item The keyword @code{__attribute__} is handled to specify variable or function attributes. The following attributes are supported: @@ -657,18 +780,62 @@ name (name is a string containing the section name) instead of the default section. @item @code{unused}: specify that the variable or the function is unused. +Accepted but currently ignored. + + @item @code{cleanup(func)}: specify a function to be called automatically +when the variable goes out of scope. The cleanup function must take one +parameter, a pointer to a type compatible with the variable, and return +@code{void}. + + @item @code{constructor}: specify that the function is to be executed automatically before @code{main()} is called. + + @item @code{destructor}: specify that the function is to be executed automatically after @code{main()} returns or @code{exit()} is called. + + @item @code{always_inline}: force inline expansion of the function. + + @item @code{alias("target")}: declare the function or variable as an alias for symbol @code{target} (a string containing the target symbol name). + + @item @code{visibility("mode")}: set symbol visibility. Supported modes are @code{"default"}, @code{"hidden"}, @code{"internal"}, and @code{"protected"}. + + @item @code{weak}: declare the symbol as a weak symbol. + + @item @code{noreturn}: specify that the function does not return to its caller. @item @code{cdecl}: use standard C calling convention (default). @item @code{stdcall}: use Pascal-like calling convention. + @item @code{fastcall}: use fastcall calling convention (i386 only). + + @item @code{thiscall}: use C++-style thiscall calling convention (i386 only). + @item @code{regparm(n)}: use fast i386 calling convention. @var{n} must be between 1 and 3. The first @var{n} function parameters are respectively put in registers @code{%eax}, @code{%edx} and @code{%ecx}. - @item @code{dllexport}: export function from dll/executable (win32 only) + @item @code{__mode__(mode)}: specify the data type size mode for integer +variables or typedefs (supported modes: @code{__QI__}, @code{__HI__}, +@code{__SI__}, @code{__DI__}, @code{__word__}). The attribute is only +taken into account when it is given with the declaration specifiers, that +is before the declarator: +@example + typedef __attribute__ ((__mode__(__QI__))) int int8_type; +@end example - @item @code{nodecorate}: do not apply any decorations that would otherwise be applied when exporting function from dll/executable (win32 only) + @item @code{dllexport}: export function from dll/executable (win32 only). + + @item @code{dllimport}: import function from dll/executable (win32 only). + + @item @code{nodecorate}: do not apply any decorations that would otherwise be applied when exporting function from dll/executable (win32 only). + + @item @code{nodebug}: suppress debug information for the symbol. + + @item @code{format(archetype, fmt_idx, chk_idx)}: marks functions that +take @code{printf}- or @code{scanf}-style format strings. Accepted but +currently ignored (not checked by TCC). + + @item @code{used}: indicates that the symbol must be retained even if it +appears unreferenced. Accepted but currently ignored. @end itemize @@ -681,7 +848,7 @@ Here are some examples: 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"))) + int my_add(int a, int b) __attribute__ ((section(".mycodesection"))) @{ return a + b; @} @@ -690,6 +857,17 @@ align variable @code{a} to 8 bytes and put it in section @code{.mysection}. @noindent generate function @code{my_add} in section @code{.mycodesection}. +@example + void free_ptr(void *p) @{ free(*(void **)p); @} + void foo(void) @{ + char *buf __attribute__((cleanup(free_ptr))) = malloc(1024); + /* buf is freed automatically when leaving foo */ + @} +@end example + +@noindent +automatically call @code{free_ptr(&buf)} when variable @code{buf} goes out of scope. + @item GNU style variadic macros: @example #define dprintf(fmt, args@dots{}) printf(fmt, ## args) @@ -698,20 +876,35 @@ generate function @code{my_add} in section @code{.mycodesection}. dprintf("one arg %d\n", 1); @end example -@item @code{__FUNCTION__} is interpreted as C99 @code{__func__} +@item @code{__FUNCTION__} is interpreted as C99 @code{__func__} (so it has not exactly the same semantics as string literal GNUC where it is a string literal). -@item The @code{__alignof__} keyword can be used as @code{sizeof} +@item The @code{__alignof__} keyword can be used as @code{sizeof} to get the alignment of a type or an expression. -@item The @code{typeof(x)} returns the type of @code{x}. +@item The @code{typeof(x)} returns the type of @code{x}. @code{x} is an expression or a type. -@item Computed gotos: @code{&&label} returns a pointer of type +@item Computed gotos: @code{&&label} returns a pointer of type @code{void *} on the goto label @code{label}. @code{goto *expr} can be used to jump on the pointer resulting from @code{expr}. +@item Statement expressions: a compound statement enclosed in +parentheses may appear as an expression. The value of the expression is +the value of the last statement. This is commonly used in macros: +@example + #define max(a,b) (@{ int _a = (a), _b = (b); _a > _b ? _a : _b; @}) +@end example + +@item The @code{__label__} keyword declares local labels within a block: +@example + @{ __label__ done; /* ... */ done: ; @} +@end example + +@item The @code{__extension__} keyword suppresses warnings for GNU +extensions in strict compilation modes. + @item Inline assembly with asm instruction: @cindex inline assembly @cindex assembly, inline @@ -740,12 +933,65 @@ return (to); @cindex 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 supported. +operands are supported. @code{asm goto} is also supported for +control-flow transfer to C labels: +@example + asm goto ("jmp %l[label]" : : : : label); +@end example -@item @code{__builtin_types_compatible_p()} and @code{__builtin_constant_p()} -are supported. +@item The following GCC built-in functions are supported: + @itemize + @item @code{__builtin_types_compatible_p(type1, type2)}: returns 1 if @code{type1} is compatible with @code{type2}, 0 otherwise. + @item @code{__builtin_constant_p(exp)}: returns 1 if @code{exp} evaluates to a compile-time constant, 0 otherwise. + @item @code{__builtin_choose_expr(const_expr, exp1, exp2)}: evaluates to @code{exp1} if @code{const_expr} is non-zero, otherwise @code{exp2}. + @item @code{__builtin_expect(expr, expected)}: branch prediction hint (evaluates to @code{expr}). + @item @code{__builtin_unreachable()}: informs the compiler that the code location cannot be reached. + @item @code{__builtin_frame_address(level)}: returns the frame pointer address for stack level @code{level}. + @item @code{__builtin_return_address(level)}: returns the return address for stack level @code{level}. + @item @code{__builtin_offsetof(type, field)}: returns the byte offset of @code{field} within structure @code{type}. + @item Bit manipulation built-ins: @code{__builtin_clz}, +@code{__builtin_ctz}, @code{__builtin_ffs}, @code{__builtin_popcount}, +@code{__builtin_parity}, @code{__builtin_clrsb} (and their @code{l} / +@code{ll} type variants). + @item Variadic argument handling built-ins: @code{__builtin_va_start}, @code{__builtin_va_arg}, @code{__builtin_va_copy}, @code{__builtin_va_end}. + @item Memory and string built-ins (mapped to libc): +@code{__builtin_memcpy}, @code{__builtin_memmove}, +@code{__builtin_memset}, @code{__builtin_memcmp}, +@code{__builtin_strlen}, @code{__builtin_strcpy}, +@code{__builtin_strncpy}, @code{__builtin_strcmp}, +@code{__builtin_strncmp}, @code{__builtin_strcat}, +@code{__builtin_strncat}, @code{__builtin_strchr}, +@code{__builtin_strrchr}, @code{__builtin_strdup}, +@code{__builtin_malloc}, @code{__builtin_realloc}, +@code{__builtin_calloc}, @code{__builtin_memalign}, +@code{__builtin_free}, @code{__builtin_alloca}, +@code{__builtin_abort}. + @item Atomic built-ins: @code{__atomic_store}, +@code{__atomic_load}, @code{__atomic_exchange}, +@code{__atomic_compare_exchange}, @code{__atomic_fetch_add}, +@code{__atomic_fetch_sub}, @code{__atomic_fetch_or}, +@code{__atomic_fetch_xor}, @code{__atomic_fetch_and}, +@code{__atomic_fetch_nand}, and their reverse +@code{__atomic_add_fetch} variants. + @end itemize -@item @code{#pragma pack} is supported for win32 compatibility. +@item Pragmas supported by TinyCC: + @itemize + @item @code{#pragma pack(n)}, @code{#pragma pack()}, @code{#pragma pack(push)}, @code{#pragma pack(push, n)}, @code{#pragma pack(pop)}: set structure alignment or manipulate the packing alignment stack. + @item @code{#pragma push_macro("MACRO")} and @code{#pragma pop_macro("MACRO")}: push and pop macro definitions to/from a macro stack. + @item @code{#pragma once}: ensure the header file is included only once during compilation. + @item @code{#pragma comment(lib, "libname")}: specify a library to link automatically. + @item @code{#pragma comment(option, "flags")}: pass command line options directly within source code. + @end itemize + +@item Preprocessor features: + @itemize + @item @code{#include_next }: include the next file of the same name in the header search path order. + @item @code{#warning "message"}: emit a preprocessor warning message. + @item GNU empty variadic macro argument pasting: @code{, ##__VA_ARGS__} strips the leading comma when @code{__VA_ARGS__} is empty. + @item @code{__has_include()} and @code{__has_include("file")}: test whether a header file exists. Can be used in @code{#if} / @code{#elif} preprocessor conditions. + @item @code{__has_include_next()}: like @code{__has_include} but searches in the next include path, for use in wrapper headers. + @end itemize @end itemize @@ -783,9 +1029,12 @@ same as C. @item C and C++ comments are supported. -@item Identifiers are the same as C, so you cannot use '.' or '$'. +@item Identifiers are mostly the same as C. The dot (@code{.}) is +accepted as an identifier character in assembler code. The dollar +sign (@code{$}) is accepted with @option{-fdollars-in-identifiers}, +except in inline assembly on targets other than x86-64 and RISC-V 64. -@item Only 32 bit integer numbers are supported. +@item 64-bit integer numbers are supported. @end itemize @@ -800,15 +1049,16 @@ same as C. @item Binary operators in decreasing priority order: @enumerate -@item *, /, % +@item *, /, %, <<, >> @item &, |, ^ @item +, - @end enumerate -@item A value is either an absolute number or a label plus an offset. -All operators accept absolute values except '+' and '-'. '+' or '-' can be -used to add an offset to a label. '-' supports two labels only if they -are the same or if they are both defined and in the same section. +@item A value is either an absolute number or a label plus an offset. +Only the @code{+} and @code{-} operators can be used with labels (to +add or subtract an offset). All other operators require absolute +values. @code{-} supports two labels only if they are the same or if +they are both defined and in the same section. @end itemize @@ -818,7 +1068,7 @@ are the same or if they are both defined and in the same section. @item All labels are considered as local, except undefined ones. -@item Numeric labels can be used as local @code{gas}-like labels. +@item Numeric labels can be used as local @code{gas}-like labels. They can be defined several times in the same source. Use 'b' (backward) or 'f' (forward) as suffix to reference them: @@ -855,6 +1105,14 @@ They can be defined several times in the same source. Use 'b' @cindex string directive @cindex asciz directive @cindex ascii directive +@cindex p2align directive +@cindex balign directive +@cindex pushsection directive +@cindex popsection directive +@cindex set directive +@cindex weak directive +@cindex hidden directive +@cindex type directive All directives are preceded by a '.'. The following directives are supported: @@ -881,21 +1139,50 @@ supported: @item .string string[,...] @item .asciz string[,...] @item .ascii string[,...] +@item .p2align n +@item .balign n[,value] +@item .pushsection section +@item .popsection +@item .set symbol, expr +@item .weak symbol +@item .hidden symbol +@item .type symbol, type @end itemize @section X86 Assembler @cindex assembler -All X86 opcodes are supported. Only ATT syntax is supported (source -then destination operand order). If no size suffix is given, TinyCC -tries to guess it from the operand sizes. +All i386 opcodes are supported. Most common x86_64 opcodes are +supported, including MMX and a subset of the SSE instruction set; SSE2 +support is limited to a couple of instructions. Only AT&T syntax is +supported (source then destination operand order). If no size suffix is +given, TinyCC tries to guess it from the operand sizes. Note that more +recent extensions such as AVX, AVX2, and AVX-512 are @emph{not} +supported. -Currently, MMX opcodes are supported but not SSE ones. +x86_64 adds 64-bit operand support (the @code{q} suffix), additional +registers (@code{%r8}--@code{%r15}), and instructions such as +@code{cqto}, @code{pushfq}, @code{popfq}, @code{bswapq}, +@code{cmpxchg16b}, @code{movnti}, @code{prefetch*}, @code{lfence}, +@code{mfence}, @code{sfence}, and @code{endbr64} (Control-Flow +Enforcement). + +@section ARM, ARM64 and RISC-V Assemblers +@cindex assembler + +TCC also includes assemblers for the ARM (32-bit), ARM64 (AArch64) and +RISC-V 64 targets. These handle the same @file{.S} and @file{.s} file +extensions and support the same inline assembly mechanism as the x86 +assemblers. @node linker @chapter TinyCC Linker @cindex linker +TCC includes its own linker and can directly output executables, +shared libraries, and object files without relying on an external +linker. + @section ELF file generation @cindex ELF @@ -912,18 +1199,80 @@ done on the object and library list, so the order in which object files and libraries are specified is important (same constraint as GNU ld). No grouping options (@option{--start-group} and @option{--end-group}) are supported. +TCC generates standard ELF sections including @code{.text}, @code{.data}, +@code{.data.ro} (read only data), @code{.bss}, @code{.plt}, @code{.got}, +and @code{.eh_frame}. +Shared libraries additionally get @code{.gnu.hash}, @code{.gnu.version}, +@code{.dynamic}, and relocation sections (@code{.rela.got}, +@code{.rela.plt}). + +@cindex section boundary symbols +@cindex __start_SEC +@cindex __stop_SEC +TCC automatically defines @emph{section boundary symbols} +@code{__start_SEC} and @code{__stop_SEC} for every allocated section +whose name, without the leading dot, is a valid C identifier. These are +useful for iterating over section contents from C code: + +@example +extern char __start_text[], __stop_text[]; +size_t text_size = __stop_text - __start_text; +@end example + @section ELF file loader +@cindex ELF loader -TCC can load ELF object files, archives (.a files) and dynamic -libraries (.so). +TCC can load ELF object files, archives (@code{.a} files) and dynamic +libraries (@code{.so}). -@section PE-i386 file generation +@section PE file generation +@cindex PE @cindex PE-i386 +@cindex PE32+ -TCC for Windows supports the native Win32 executable file format (PE-i386). It -generates EXE files (console and gui) and DLL files. +TCC for Windows supports the native Win32 executable file format +(PE-i386). It generates PE32 (i386) and PE32+ (x86-64) executables, +as well as DLL files. TCC also supports PE with ARM64 machine type, +including @code{.pdata} unwind information for structured exception +handling. -For usage on Windows, see also tcc-win32.txt. +PE executables can target several subsystems (see @ref{Invoke,, the +@option{-Wl,-subsystem} option}); which ones are available depends on +the target. Standard PE sections are emitted (@code{.text}, +@code{.data}, @code{.rdata}, @code{.bss}, @code{.rsrc}, @code{.pdata}, +@code{.idata}, @code{.reloc}); the export directory goes to +@code{.rdata}. + +@section Mach-O file generation +@cindex Mach-O +@cindex macOS + +TCC on macOS produces Mach-O executables and dynamic libraries +(@code{.dylib}) for x86-64 and ARM64 (AArch64). The files TCC writes +always contain a single architecture. + +TCC can load Mach-O dynamic libraries and text-based stub files +(@code{.tbd}) for linking against system frameworks. Fat (universal) +libraries are accepted, the slice matching the target being selected. + +Mach-O output uses dyld chained fixups on both x86-64 and ARM64. + +@section Binary and COFF output +@cindex binary output +@cindex COFF + +In addition to the platform-native container formats, TCC supports: + +@table @code +@item Binary image +Raw binary output with no container headers. Selected via +@code{-Wl,--oformat=binary} (@pxref{Invoke}). Useful for bootloaders, +kernels, and embedded targets. Only valid for executable output. + +@item COFF +The TMS320C67xx (C67) target outputs COFF executables. Object files are +always written as ELF. +@end table @section GNU Linker Scripts @cindex scripts, linker @@ -988,6 +1337,24 @@ Here are some examples of caught errors: @} @end example +@item Out of bounds-error in alloca'ed data: +@example +@{ + char *p = alloca(10); + memset(p, 'a', 11); +@} +@end example + +@item Out of bounds-error in variable length arrays: +@example +@{ + int tab[n]; + for(i=0;ilink}). +It is needed for linking, not only for debugging. @end table @@ -1284,8 +1750,12 @@ The TCC code generator is register based. Optimization is only done at the expression level. No intermediate representation of expression is kept except the current values stored in the @emph{value stack}. -On x86, three temporary registers are used. When more registers are -needed, one register is spilled into a new temporary variable on the stack. +Each target declares the registers the code generator may use in +@code{reg_classes[]}, and @code{NB_REGS} gives their number: five on +i386 (@code{eax}, @code{ecx}, @code{edx}, @code{ebx}, which is only +usable when @code{USE_EBX} is set, and the top of the x87 stack), 25 on +x86-64, 28 on arm64. When more registers are needed, one register is +spilled into a new temporary variable on the stack. @subsection The value stack @cindex value stack, introduction @@ -1294,29 +1764,33 @@ 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 stack entry is the structure @code{SValue}. -@code{SValue.t} is the type. @code{SValue.r} indicates how the value is +@code{SValue.type} is the type. @code{SValue.r} indicates how the value is currently stored in the generated code. It is usually a CPU register index (@code{REG_xxx} constants), but additional values and flags are defined: @example -#define VT_CONST 0x00f0 -#define VT_LLOCAL 0x00f1 -#define VT_LOCAL 0x00f2 -#define VT_CMP 0x00f3 -#define VT_JMP 0x00f4 -#define VT_JMPI 0x00f5 -#define VT_LVAL 0x0100 -#define VT_SYM 0x0200 -#define VT_MUSTCAST 0x0400 -#define VT_MUSTBOUND 0x0800 -#define VT_BOUNDED 0x8000 -#define VT_LVAL_BYTE 0x1000 -#define VT_LVAL_SHORT 0x2000 -#define VT_LVAL_UNSIGNED 0x4000 -#define VT_LVAL_TYPE (VT_LVAL_BYTE | VT_LVAL_SHORT | VT_LVAL_UNSIGNED) +#define VT_VALMASK 0x003f /* mask for value location, register or: */ +#define VT_CONST 0x0030 /* constant in vc */ +#define VT_LLOCAL 0x0031 /* lvalue, offset on stack */ +#define VT_LOCAL 0x0032 /* offset on stack */ +#define VT_CMP 0x0033 /* the value is stored in processor flags */ +#define VT_JMP 0x0034 /* value is the consequence of jmp true (even) */ +#define VT_JMPI 0x0035 /* value is the consequence of jmp false (odd) */ +#define VT_LVAL 0x0100 /* var is an lvalue */ +#define VT_SYM 0x0200 /* a symbol value is added */ +#define VT_MUSTCAST 0x0C00 /* value must be casted to be correct */ +#define VT_NONCONST 0x1000 /* VT_CONST, but not an (C standard) integer + constant expression */ +#define VT_MUSTBOUND 0x4000 /* bound checking must be done before + dereferencing value */ +#define VT_BOUNDED 0x8000 /* value is bounded */ @end example +@code{SValue.r2} holds the second register when a value needs two of +them, as for a @code{long long} on a 32 bit target. It is set to +@code{VT_CONST} when it is not used. + @table @code @item VT_CONST @@ -1330,10 +1804,14 @@ stack. @item VT_CMP indicates that the value is actually stored in the CPU flags (i.e. the value is the consequence of a test). The value is either 0 or 1. The -actual CPU flags used is indicated in @code{SValue.c.i}. +comparison which set the flags is kept in @code{SValue.cmp_op}; +@code{SValue.cmp_r} is left to the code generator, which uses it to +remember where the compared values are on the targets that have no flags +register. If any code is generated which destroys the CPU flags, this value MUST be -put in a normal register. +put in a normal register. @code{vcheck_cmp()} does it, and the functions +which manipulate the value stack call it before generating code. @item VT_JMP @itemx VT_JMPI @@ -1341,7 +1819,9 @@ indicates that the value is the consequence of a conditional jump. For VT_JMP, it is 1 if the jump is taken, 0 otherwise. For VT_JMPI it is inverted. These values are used to compile the @code{||} and @code{&&} logical -operators. +operators. The jumps which still have to be resolved are chained in +@code{SValue.jtrue} and @code{SValue.jfalse}; @code{gvtst()} adds to +these lists and generates the final test. If any code is generated, this value MUST be put in a normal register. Otherwise, the generated code won't be executed if the jump is @@ -1350,17 +1830,11 @@ taken. @item VT_LVAL is a flag indicating that the value is actually an lvalue (left value of an assignment). It means that the value stored is actually a pointer to -the wanted value. +the wanted value. Understanding the use @code{VT_LVAL} is very important if you want to understand how TCC works. -@item VT_LVAL_BYTE -@itemx VT_LVAL_SHORT -@itemx VT_LVAL_UNSIGNED -if the lvalue has an integer type, then these flags give its real -type. The type alone is not enough in case of cast optimisations. - @item VT_LLOCAL is a saved lvalue on the stack. @code{VT_LVAL} must also be set with @code{VT_LLOCAL}. @code{VT_LLOCAL} can arise when a @code{VT_LVAL} in @@ -1369,11 +1843,20 @@ architecture-specific calling convention. @item VT_MUSTCAST indicates that a cast to the value type must be performed if the value -is used (lazy casting). +is used (lazy casting), as for a @code{char} or a @code{short} kept in an +integer register. It is a two bit field, so that the width the value has +to be casted from (@code{int} or @code{long long}) is remembered too. @item VT_SYM indicates that the symbol @code{SValue.sym} must be added to the constant. +@item VT_NONCONST +marks a @code{VT_CONST} value which only became constant through +optimization. Such a value is folded like any other constant, but it is +not a constant expression in the sense of the C standard: it is rejected +where the language requires one (@code{expr_const64()}) and it is not a +null pointer constant. + @item VT_MUSTBOUND @itemx VT_BOUNDED are only used for optional bound checking. @@ -1392,6 +1875,11 @@ previous @var{vtop} in a safe storage. code (for example if stacked floating point registers are used as on x86). +@code{vdup()}, @code{vswap()}, @code{vrotb()} and @code{vrott()} +duplicate, exchange and rotate the topmost entries. They all go through +@code{vcheck_cmp()} first, because a @code{VT_CMP} value may only stay on +top of the stack. + 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 @@ -1400,6 +1888,13 @@ important function} of the code generator. @code{gv2()} is the same as @code{gv()} but for the top two stack entries. +@code{get_reg(rc)} returns a free register of the class @var{rc}. When +they are all busy it spills the one held by the oldest value stack entry, +starting from the bottom of the stack so that the registers of the +operation being generated are never taken away. The spill itself is done +by @code{save_reg()}, which copies to the stack every value living in a +given register. + @subsection CPU dependent code generation @cindex CPU dependent See the @file{i386-gen.c} file to have an example. @@ -1413,10 +1908,11 @@ must generate the code needed to load a stack value into a register. must generate the code needed to store a register into a stack value lvalue. -@item gfunc_start() -@itemx gfunc_param() -@itemx gfunc_call() -should generate a function call +@item gfunc_call(nb_args) +should generate a function call, the arguments and the function address +being the @code{nb_args + 1} topmost entries of the value stack. +@code{gfunc_sret()} tells the parser how a structure return value is +passed for the target ABI. @item gfunc_prolog() @itemx gfunc_epilog() @@ -1442,6 +1938,23 @@ floating point to integer conversion. @item gen_cvt_ftof() floating point to floating point of different size conversion. +@item gen_cvt_csti() +performs the delayed cast of a @code{char} or a @code{short} held in an +integer register (see @code{VT_MUSTCAST}). + +@item gjmp() +@itemx gjmp_addr() +@itemx gjmp_cond() +@itemx gsym_addr() +generate unconditional and conditional jumps, and patch the jumps whose +target was not known yet. + +@item gen_vla_alloc() +@itemx gen_vla_sp_save() +@itemx gen_vla_sp_restore() +allocate a variable length array on the stack, and save and restore the +stack pointer around it. + @end table @section Optimizations done @@ -1453,9 +1966,12 @@ floating point to floating point of different size conversion. @cindex flags, caching @cindex 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 -processor flags. &&, || and ! are optimized by maintaining a special +divisions by a power of two are optimized to shifts, and operations +which are a no-operation for the given constant (@code{x*1}, +@code{x-0}, @code{x&-1}, @dots{}) are dropped. Constants added to a +symbol or to a local variable address are folded into the address. +Comparison operators are optimized by maintaining a special cache for +the processor flags. &&, || and ! are optimized by maintaining a special 'jump target' value. No other jump optimization is currently performed because it would require to store the code in a more abstract fashion. diff --git a/texi2pod.pl b/texi2pod.pl index d86e176f..0d1fa630 100755 --- a/texi2pod.pl +++ b/texi2pod.pl @@ -239,6 +239,8 @@ while(<$inf>) { and $_ = "\n=head2 $1\n"; /^\@subsection\s+(.+)$/ and $_ = "\n=head3 $1\n"; + /^\@subheading\s+(.+)$/ + and $_ = "\n=head3 $1\n"; # Block command handlers: /^\@itemize\s+(\@[a-z]+|\*|-)/ and do {