invocation_ld.hss 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209
  1. [Main]
  2. Title=ld-tigcc Command-Line Options
  3. [Top]
  4. In <CODE>ld-tigcc</CODE>, options and input files may appear in any order in
  5. the command line. Input files may be either object or archive (static
  6. library) files. They are handled differently depending on the type of the
  7. file: Object files are read completely in the order they are supplied;
  8. archive file members are read only if the program references a symbol they
  9. export. If multiple archive files export the same symbol,
  10. <CODE>ld-tigcc</CODE> uses the archive that is supplied first.
  11. <BR><BR>
  12. Output file names and variable names are usually set according to the name of
  13. the first object file in the command line, but they may be changed using the
  14. <B>'--output'</B> and <B>'--varname'</B> options described below. The file
  15. extensions depend on the exact output format used; they are usually what the
  16. transferring software expects them to be.
  17. <BR><BR>
  18. <CODE>ld-tigcc</CODE> recognizes the following options:
  19. <DL>
  20. <DT><B>-h</B>
  21. <BR><B>--help</B>
  22. <DD>Print a short description of all available options.
  23. <BR><BR>
  24. <DT><B>--version</B>
  25. <DD>Print the version number of the tool and a short copyright notice.
  26. <BR><BR>
  27. <DT><B>-v</B>
  28. <BR><B>--verbose</B>
  29. <DD>Print statistics about the linked program before terminating. These
  30. include the target calculators, program variable name and size, data variable
  31. size, BSS size (size of all uninitialized global variables), the total number
  32. of absolute relocs, the number of relocs which appear in the native format of
  33. the target OS, and optimization possibilities or results. In the IDE, these
  34. statistics are displayed automatically, unless this is turned off in the
  35. preferences or the program is run automatically after successful linking. If
  36. the linking process fails, no statistics are shown.
  37. <BR><BR>
  38. <DT><B>--dump</B>
  39. <DD>Display all dumps of the program contents during the entire linking
  40. process. For details about dumps, see <A HREF="$$LINK(dump)">ld-tigcc
  41. Program Dumps</A>.
  42. <BR><BR>
  43. <DT><B>--dump<I>n</I></B>
  44. <DD>Display the <I>n</I>-th dump of the program contents. For details on the
  45. different linking stages and the associated dump numbers, see
  46. <A HREF="$$LINK(dump)">ld-tigcc Program Dumps</A>.
  47. <BR><BR>
  48. <DT><B>--native</B>
  49. <DD>Use TIGCC native mode by default. Without this option, the linker starts
  50. in kernel mode (for compatibility with existing programs), but this may be
  51. changed using special symbols (see <A HREF="$$LINK(control)">Symbols to
  52. Control the Linker</A>). For more information about modes, see
  53. <A HREF="$$LINK(modes)">TIGCC Linker Modes</A>.
  54. <BR><BR>
  55. <DT><B>--fargo</B>
  56. <DD>Use Fargo II mode and compile for the TI-92. This option is only
  57. available if Fargo support is compiled in. It exists for compatibility with
  58. existing Fargo II programs, which do not explicitly specify a mode and a
  59. target calculator.
  60. <BR><BR>
  61. <DT><B>--flash-os</B>
  62. <DD>Use Flash OS mode. This mode creates an unsigned Flash operating system
  63. upgrade for the TI-89, TI-89 Titanium, TI-92+ and Voyage 200 calculators.
  64. This option is only available if Flash OS support is compiled in.
  65. <BR><BR>
  66. <DT><B>--remove-unused</B>
  67. <DD>Remove unused sections. If a section is not referenced by another
  68. section, this option causes it to be removed. Startup sections are never
  69. removed; neither is the first section in Nostub mode. Note that in some
  70. cases, the linker cannot determine whether a section can be removed before
  71. merging it with another section; in this case, it is not removed even though
  72. it may not be referenced at all.
  73. <BR><BR>
  74. <DT><B>--optimize-relocs</B>
  75. <DD>Update the destination symbol of relocation entries to the nearest
  76. available symbol, thereby making the offset as small as possible. This
  77. improves the readability of dumps and some diagnostic messages, but should
  78. not have any other effect than this.
  79. <BR><BR>
  80. <DT><B>--optimize-code</B>
  81. <DD>Perform all code optimizations, including NOP, return, branch, move,
  82. test, and calculation optimization. Note that it is possible for code
  83. optimization to create invalid code or accidentally change data instead of
  84. code. The probability is not very high, so you should really enable code
  85. optimization at least partially, but if your program crashes for no apparent
  86. reason, try turning off code optimization. For more information about
  87. optimization, see <A HREF="$$LINK(bincode)">TIGCC Linker Binary Code
  88. Fixup</A>.
  89. <DL>
  90. <DT><B>--optimize-nops</B>
  91. <DD>Perform <A HREF="$$LINK(bincode_nop)">NOP instruction removal</A>.
  92. <BR><BR>
  93. <DT><B>--optimize-returns</B>
  94. <DD>Perform <A HREF="$$LINK(bincode_return)">return sequence
  95. optimization</A>.
  96. <BR><BR>
  97. <DT><B>--optimize-branches</B>
  98. <DD>Perform <A HREF="$$LINK(bincode_branch)">branch optimization</A>.
  99. <BR><BR>
  100. <DT><B>--optimize-moves</B>
  101. <DD>Perform <A HREF="$$LINK(bincode_move)">move/load/push optimization</A>.
  102. <BR><BR>
  103. <DT><B>--optimize-tests</B>
  104. <DD>Perform <A HREF="$$LINK(bincode_test)">compare/test optimization</A>.
  105. <BR><BR>
  106. <DT><B>--optimize-calcs</B>
  107. <DD>Perform <A HREF="$$LINK(bincode_calculation)">calculation
  108. optimization</A>.
  109. </DL>
  110. <DT><B>--cut-ranges</B>
  111. <DD>Optimization has two effects: It can reduce the number of relocation
  112. entries, and it can make instructions smaller. Usually, the space gained from
  113. making the instructions smaller is filled with NOPs. If this option is used,
  114. the linker will attempt to cut out these ranges of code instead, making the
  115. size of the executable even smaller. This only works for input files that
  116. were assembled in all-relocs mode, but this is handled automatically if this
  117. option is used via the <CODE>tigcc</CODE> front-end or the TIGCC IDE.
  118. <BR><BR>
  119. <DT><B>--reorder-sections</B>
  120. <DD>Reorder sections to make references shorter. The fixups (see above) can
  121. then fit those shorter references into smaller and faster addressing modes,
  122. so using this option can improve both size and speed. It can also allow the
  123. fixups to remove relocations or to turn F-Line jumps into faster branches.
  124. Since computing the optimal reordering is NP complete and <I>very</I>
  125. expensive in practical terms (the factorial of the number of sections is a
  126. <I>huge</I> factor), section reordering is implemented through heuristics.
  127. Therefore, the result is not guaranteed to be optimal. There are rare cases
  128. where section reordering can still take exponential time, these are due to
  129. hardcoded short references between sections rendering some reorderings
  130. impossible. In this case, the linker will emit warnings as impossible
  131. reorderings are encountered so you can follow the process, or stop it (and
  132. go fix your program, hardcoded short references between sections are not a
  133. good idea, that's what linker optimization is for!) if it takes too long.
  134. Startup sections can be reordered only with other startup sections with the
  135. <I>same</I> startup number. Non-startup sections can be reordered only with
  136. other non-startup sections. Sections which are emitted separately (e.g. a
  137. dynamically allocated BSS section or a data section in an external file)
  138. cannot be reordered at all.
  139. <DT><B>--merge-constants</B>
  140. <DD>Merge identical constants (including strings) to avoid duplication.
  141. Constant merging works on all symbols (actually, the ranges included within
  142. 2 symbols, where symbols at the same position are considered the same
  143. symbol) in sections marked mergeable. Constants can be merged if they are
  144. identical or if one of them is a prefix of the other. This can be used by
  145. the compiler to avoid duplicating string literals (and, if desired by the
  146. user, other constants) in multiple object files. Unaligned and aligned
  147. sections are distinguished to keep the linker from accidentally breaking
  148. the alignment while merging aligned constants with unaligned ones which
  149. happen to contain them as a prefix.
  150. <DT><B>--omit-bss-init</B>
  151. <DD>Skip the initialization of the BSS section, which holds uninitialized
  152. global variables. Older versions of TIGCC never initialized the BSS section,
  153. so many older programs do not rely on the initialization. If you use this
  154. option, you must be sure that there is really no code that relies on the
  155. initialization of global variables to zero (which means, among other things,
  156. that you have to use the <A HREF="$$INFOLINK(comopts)">compiler option</A>
  157. <B>'-fno-zero-initialized-in-bss'</B>). For a safer alternative, try the
  158. <A HREF="$$LINK(control_ld_omit_bss_init)">__ld_omit_bss_init</A> control
  159. symbol.
  160. <BR><BR>
  161. <DT><B>--outputbin</B>
  162. <DD>Instead of creating a wrapped calculator variable that includes a folder
  163. and variable name, a checksum, and some extra information, write only the raw
  164. contents of the variable to the file. The file extension is changed in a way
  165. that allows different files to be generated for each target calculator but
  166. prevents confusion between raw and wrapped data.
  167. <BR><BR>
  168. <DT><B>-o <I>file</I></B>
  169. <BR><B>--output <I>file</I></B>
  170. <DD>Write the output to the file named <I>file</I>.<I>ext</I>, where
  171. <I>ext</I> is the extension that fits the file type. <I>file</I> may include
  172. a path, but if it includes its own extension, <I>ext</I> will be appended
  173. anyway. This also sets the variable name to something that resembles
  174. <I>file</I> as closely as possible. Note that it does not do any error
  175. checking on the characters of the <I>file</I> parameter.
  176. <BR><BR>
  177. <DT><B>-n [<I>folder</I>\]<I>name</I></B>
  178. <BR><B>--varname [<I>folder</I>\]<I>name</I></B>
  179. <DD>Include the folder name <I>folder</I> (<CODE>main</CODE> if unspecified)
  180. and variable name <I>name</I> in the wrapper file. If the file is not wrapped
  181. (i.e. if <B>'--outputbin'</B> has been specified), this option has no effect.
  182. <BR><BR>
  183. <DT><B>-d [<I>folder</I>\]<I>name</I></B>
  184. <BR><B>--data-var [<I>folder</I>\]<I>name</I></B>
  185. <DD>Exclude all non-executable data (global variables) from the program and
  186. create an external variable for it. Note that you are absolutely required to
  187. make sure that no code is executed from the data section; otherwise it will
  188. crash depending on the calculator model: Newer calculators have a protection
  189. device that lets the operating system restrict the areas code can be executed
  190. from. <I>name</I> is the variable name to be assigned to the data variable.
  191. <I>folder</I> defines the folder of the variable; if it is not specified, the
  192. folder from the <B>'--varname'</B> option is used.
  193. <BR><BR>
  194. <DT><B>--data-var-copy=<I>condition</I></B>
  195. <DD>Defines when to create a copy of the data variable in RAM. If
  196. <I>condition</I> is <CODE>always</CODE>, the program will always work on a
  197. copy in RAM, which means that you may rely on the data being the same on
  198. every start of the program. However, if the data variable is not archived,
  199. you may easily run out of available memory. <CODE>archived</CODE> causes a
  200. copy to be created only if the data variable is archived; this is the
  201. default. If the variable is not archived, the program will work on the actual
  202. contents of the variable, so the values of all global variables will be kept
  203. even after the program finishes. <CODE>never</CODE> tells the linker to work
  204. on the original variable unconditionally, but since you may not write to the
  205. archive memory, you have to make sure that you never modify the value of a
  206. global variable. If the <B>'--data-var'</B> option is not specified as well,
  207. this option has no effect.
  208. </DL>