|
@@ -0,0 +1,210 @@
|
|
|
+[Main]
|
|
|
+Title=ld-tigcc Command-Line Options
|
|
|
+
|
|
|
+[Top]
|
|
|
+In <CODE>ld-tigcc</CODE>, options and input files may appear in any order in
|
|
|
+the command line. Input files may be either object or archive (static
|
|
|
+library) files. They are handled differently depending on the type of the
|
|
|
+file: Object files are read completely in the order they are supplied;
|
|
|
+archive file members are read only if the program references a symbol they
|
|
|
+export. If multiple archive files export the same symbol,
|
|
|
+<CODE>ld-tigcc</CODE> uses the archive that is supplied first.
|
|
|
+<BR><BR>
|
|
|
+Output file names and variable names are usually set according to the name of
|
|
|
+the first object file in the command line, but they may be changed using the
|
|
|
+<B>'--output'</B> and <B>'--varname'</B> options described below. The file
|
|
|
+extensions depend on the exact output format used; they are usually what the
|
|
|
+transferring software expects them to be.
|
|
|
+<BR><BR>
|
|
|
+<CODE>ld-tigcc</CODE> recognizes the following options:
|
|
|
+<DL>
|
|
|
+<DT><B>-h</B>
|
|
|
+<BR><B>--help</B>
|
|
|
+<DD>Print a short description of all available options.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--version</B>
|
|
|
+<DD>Print the version number of the tool and a short copyright notice.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>-v</B>
|
|
|
+<BR><B>--verbose</B>
|
|
|
+<DD>Print statistics about the linked program before terminating. These
|
|
|
+include the target calculators, program variable name and size, data variable
|
|
|
+size, BSS size (size of all uninitialized global variables), the total number
|
|
|
+of absolute relocs, the number of relocs which appear in the native format of
|
|
|
+the target OS, and optimization possibilities or results. In the IDE, these
|
|
|
+statistics are displayed automatically, unless this is turned off in the
|
|
|
+preferences or the program is run automatically after successful linking. If
|
|
|
+the linking process fails, no statistics are shown.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--dump</B>
|
|
|
+<DD>Display all dumps of the program contents during the entire linking
|
|
|
+process. For details about dumps, see <A HREF="$$LINK(dump)">ld-tigcc
|
|
|
+Program Dumps</A>.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--dump<I>n</I></B>
|
|
|
+<DD>Display the <I>n</I>-th dump of the program contents. For details on the
|
|
|
+different linking stages and the associated dump numbers, see
|
|
|
+<A HREF="$$LINK(dump)">ld-tigcc Program Dumps</A>.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--native</B>
|
|
|
+<DD>Use TIGCC native mode by default. Without this option, the linker starts
|
|
|
+in kernel mode (for compatibility with existing programs), but this may be
|
|
|
+changed using special symbols (see <A HREF="$$LINK(control)">Symbols to
|
|
|
+Control the Linker</A>). For more information about modes, see
|
|
|
+<A HREF="$$LINK(modes)">TIGCC Linker Modes</A>.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--fargo</B>
|
|
|
+<DD>Use Fargo II mode and compile for the TI-92. This option is only
|
|
|
+available if Fargo support is compiled in. It exists for compatibility with
|
|
|
+existing Fargo II programs, which do not explicitly specify a mode and a
|
|
|
+target calculator.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--flash-os</B>
|
|
|
+<DD>Use Flash OS mode. This mode creates an unsigned Flash operating system
|
|
|
+upgrade for the TI-89, TI-92+ and Voyage 200 calculators. (TI-89 Titanium
|
|
|
+Flash upgrades are currently <I>not</I> supported.) This option is only
|
|
|
+available if Flash OS support is compiled in.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--remove-unused</B>
|
|
|
+<DD>Remove unused sections. If a section is not referenced by another
|
|
|
+section, this option causes it to be removed. Startup sections are never
|
|
|
+removed; neither is the first section in Nostub mode. Note that in some
|
|
|
+cases, the linker cannot determine whether a section can be removed before
|
|
|
+merging it with another section; in this case, it is not removed even though
|
|
|
+it may not be referenced at all.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--optimize-relocs</B>
|
|
|
+<DD>Update the destination symbol of relocation entries to the nearest
|
|
|
+available symbol, thereby making the offset as small as possible. This
|
|
|
+improves the readability of dumps and some diagnostic messages, but should
|
|
|
+not have any other effect than this.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--optimize-code</B>
|
|
|
+<DD>Perform all code optimizations, including NOP, return, branch, move,
|
|
|
+test, and calculation optimization. Note that it is possible for code
|
|
|
+optimization to create invalid code or accidentally change data instead of
|
|
|
+code. The probability is not very high, so you should really enable code
|
|
|
+optimization at least partially, but if your program crashes for no apparent
|
|
|
+reason, try turning off code optimization. For more information about
|
|
|
+optimization, see <A HREF="$$LINK(bincode)">TIGCC Linker Binary Code
|
|
|
+Fixup</A>.
|
|
|
+<DL>
|
|
|
+<DT><B>--optimize-nops</B>
|
|
|
+<DD>Perform <A HREF="$$LINK(bincode_nop)">NOP instruction removal</A>.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--optimize-returns</B>
|
|
|
+<DD>Perform <A HREF="$$LINK(bincode_return)">return sequence
|
|
|
+optimization</A>.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--optimize-branches</B>
|
|
|
+<DD>Perform <A HREF="$$LINK(bincode_branch)">branch optimization</A>.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--optimize-moves</B>
|
|
|
+<DD>Perform <A HREF="$$LINK(bincode_move)">move/load/push optimization</A>.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--optimize-tests</B>
|
|
|
+<DD>Perform <A HREF="$$LINK(bincode_test)">compare/test optimization</A>.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--optimize-calcs</B>
|
|
|
+<DD>Perform <A HREF="$$LINK(bincode_calculation)">calculation
|
|
|
+optimization</A>.
|
|
|
+</DL>
|
|
|
+<DT><B>--cut-ranges</B>
|
|
|
+<DD>Optimization has two effects: It can reduce the number of relocation
|
|
|
+entries, and it can make instructions smaller. Usually, the space gained from
|
|
|
+making the instructions smaller is filled with NOPs. If this option is used,
|
|
|
+the linker will attempt to cut out these ranges of code instead, making the
|
|
|
+size of the executable even smaller. This only works for input files that
|
|
|
+were assembled in all-relocs mode, but this is handled automatically if this
|
|
|
+option is used via the <CODE>tigcc</CODE> front-end or the TIGCC IDE.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--reorder-sections</B>
|
|
|
+<DD>Reorder sections to make references shorter. The fixups (see above) can
|
|
|
+then fit those shorter references into smaller and faster addressing modes,
|
|
|
+so using this option can improve both size and speed. It can also allow the
|
|
|
+fixups to remove relocations or to turn F-Line jumps into faster branches.
|
|
|
+Since computing the optimal reordering is NP complete and <I>very</I>
|
|
|
+expensive in practical terms (the factorial of the number of sections is a
|
|
|
+<I>huge</I> factor), section reordering is implemented through heuristics.
|
|
|
+Therefore, the result is not guaranteed to be optimal. There are rare cases
|
|
|
+where section reordering can still take exponential time, these are due to
|
|
|
+hardcoded short references between sections rendering some reorderings
|
|
|
+impossible. In this case, the linker will emit warnings as impossible
|
|
|
+reorderings are encountered so you can follow the process, or stop it (and
|
|
|
+go fix your program, hardcoded short references between sections are not a
|
|
|
+good idea, that's what linker optimization is for!) if it takes too long.
|
|
|
+Startup sections can be reordered only with other startup sections with the
|
|
|
+<I>same</I> startup number. Non-startup sections can be reordered only with
|
|
|
+other non-startup sections. Sections which are emitted separately (e.g. a
|
|
|
+dynamically allocated BSS section or a data section in an external file)
|
|
|
+cannot be reordered at all.
|
|
|
+<DT><B>--merge-constants</B>
|
|
|
+<DD>Merge identical constants (including strings) to avoid duplication.
|
|
|
+Constant merging works on all symbols (actually, the ranges included within
|
|
|
+2 symbols, where symbols at the same position are considered the same
|
|
|
+symbol) in sections marked mergeable. Constants can be merged if they are
|
|
|
+identical or if one of them is a prefix of the other. This can be used by
|
|
|
+the compiler to avoid duplicating string literals (and, if desired by the
|
|
|
+user, other constants) in multiple object files. Unaligned and aligned
|
|
|
+sections are distinguished to keep the linker from accidentally breaking
|
|
|
+the alignment while merging aligned constants with unaligned ones which
|
|
|
+happen to contain them as a prefix.
|
|
|
+<DT><B>--omit-bss-init</B>
|
|
|
+<DD>Skip the initialization of the BSS section, which holds uninitialized
|
|
|
+global variables. Older versions of TIGCC never initialized the BSS section,
|
|
|
+so many older programs do not rely on the initialization. If you use this
|
|
|
+option, you must be sure that there is really no code that relies on the
|
|
|
+initialization of global variables to zero (which means, among other things,
|
|
|
+that you have to use the <A HREF="$$INFOLINK(comopts)">compiler option</A>
|
|
|
+<B>'-fno-zero-initialized-in-bss'</B>). For a safer alternative, try the
|
|
|
+<A HREF="$$LINK(control_ld_omit_bss_init)">__ld_omit_bss_init</A> control
|
|
|
+symbol.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--outputbin</B>
|
|
|
+<DD>Instead of creating a wrapped calculator variable that includes a folder
|
|
|
+and variable name, a checksum, and some extra information, write only the raw
|
|
|
+contents of the variable to the file. The file extension is changed in a way
|
|
|
+that allows different files to be generated for each target calculator but
|
|
|
+prevents confusion between raw and wrapped data.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>-o <I>file</I></B>
|
|
|
+<BR><B>--output <I>file</I></B>
|
|
|
+<DD>Write the output to the file named <I>file</I>.<I>ext</I>, where
|
|
|
+<I>ext</I> is the extension that fits the file type. <I>file</I> may include
|
|
|
+a path, but if it includes its own extension, <I>ext</I> will be appended
|
|
|
+anyway. This also sets the variable name to something that resembles
|
|
|
+<I>file</I> as closely as possible. Note that it does not do any error
|
|
|
+checking on the characters of the <I>file</I> parameter.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>-n [<I>folder</I>\]<I>name</I></B>
|
|
|
+<BR><B>--varname [<I>folder</I>\]<I>name</I></B>
|
|
|
+<DD>Include the folder name <I>folder</I> (<CODE>main</CODE> if unspecified)
|
|
|
+and variable name <I>name</I> in the wrapper file. If the file is not wrapped
|
|
|
+(i.e. if <B>'--outputbin'</B> has been specified), this option has no effect.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>-d [<I>folder</I>\]<I>name</I></B>
|
|
|
+<BR><B>--data-var [<I>folder</I>\]<I>name</I></B>
|
|
|
+<DD>Exclude all non-executable data (global variables) from the program and
|
|
|
+create an external variable for it. Note that you are absolutely required to
|
|
|
+make sure that no code is executed from the data section; otherwise it will
|
|
|
+crash depending on the calculator model: Newer calculators have a protection
|
|
|
+device that lets the operating system restrict the areas code can be executed
|
|
|
+from. <I>name</I> is the variable name to be assigned to the data variable.
|
|
|
+<I>folder</I> defines the folder of the variable; if it is not specified, the
|
|
|
+folder from the <B>'--varname'</B> option is used.
|
|
|
+<BR><BR>
|
|
|
+<DT><B>--data-var-copy=<I>condition</I></B>
|
|
|
+<DD>Defines when to create a copy of the data variable in RAM. If
|
|
|
+<I>condition</I> is <CODE>always</CODE>, the program will always work on a
|
|
|
+copy in RAM, which means that you may rely on the data being the same on
|
|
|
+every start of the program. However, if the data variable is not archived,
|
|
|
+you may easily run out of available memory. <CODE>archived</CODE> causes a
|
|
|
+copy to be created only if the data variable is archived; this is the
|
|
|
+default. If the variable is not archived, the program will work on the actual
|
|
|
+contents of the variable, so the values of all global variables will be kept
|
|
|
+even after the program finishes. <CODE>never</CODE> tells the linker to work
|
|
|
+on the original variable unconditionally, but since you may not write to the
|
|
|
+archive memory, you have to make sure that you never modify the value of a
|
|
|
+global variable. If the <B>'--data-var'</B> option is not specified as well,
|
|
|
+this option has no effect.
|
|
|
+</DL>
|