Browse Source

Import documentation and documentation and header generation tools.

git-svn-id: file:///var/svn/tigccpp/trunk/tigcc/doc/System/Info/ld@11 9552661e-59e3-4036-b4f2-dbe53926924f
kevinkofler 19 years ago
commit
974c8574b7
100 changed files with 2396 additions and 0 deletions
  1. 13 0
      bincode.hss
  2. 21 0
      bincode_branch.hss
  3. 23 0
      bincode_branch_fline.hss
  4. 12 0
      bincode_calculation.hss
  5. 15 0
      bincode_move.hss
  6. 11 0
      bincode_nop.hss
  7. 17 0
      bincode_return.hss
  8. 12 0
      bincode_test.hss
  9. 27 0
      compiling.hss
  10. 34 0
      control.hss
  11. 26 0
      control_calc.hss
  12. 7 0
      control_fargo.hss
  13. 11 0
      control_flag.hss
  14. 7 0
      control_flash_os.hss
  15. 7 0
      control_ld_ignore_global_imports.hss
  16. 24 0
      control_ld_omit_bss_init.hss
  17. 13 0
      control_ld_use_4byte_fline_jumps.hss
  18. 9 0
      control_ld_use_fline_jumps.hss
  19. 12 0
      control_lib_min_version.hss
  20. 10 0
      control_library.hss
  21. 7 0
      control_nostub.hss
  22. 8 0
      control_nostub_dll.hss
  23. 14 0
      control_ref_all.hss
  24. 7 0
      control_tigcc_native.hss
  25. 10 0
      control_version.hss
  26. 89 0
      dump.hss
  27. 110 0
      formats.hss
  28. 43 0
      global_imports.hss
  29. 142 0
      global_imports_auto.hss
  30. 32 0
      global_imports_conditional.hss
  31. 2 0
      insert.hss
  32. 20 0
      insert_compressed_bss_refs.hss
  33. 20 0
      insert_compressed_data_refs.hss
  34. 57 0
      insert_compressed_relocs.hss
  35. 33 0
      insert_compressed_rom_calls.hss
  36. 8 0
      insert_data_var_name.hss
  37. 11 0
      insert_fargo020_bss_refs.hss
  38. 34 0
      insert_fargo020_libs.hss
  39. 23 0
      insert_fargo021_bss_refs.hss
  40. 47 0
      insert_fargo021_libs.hss
  41. 21 0
      insert_fargo021_relocs.hss
  42. 26 0
      insert_fargo_exports.hss
  43. 19 0
      insert_kernel_bss_refs.hss
  44. 18 0
      insert_kernel_data_refs.hss
  45. 25 0
      insert_kernel_exports.hss
  46. 61 0
      insert_kernel_libs.hss
  47. 69 0
      insert_kernel_ram_calls.hss
  48. 59 0
      insert_kernel_relocs.hss
  49. 50 0
      insert_kernel_rom_calls.hss
  50. 21 0
      insert_nostub_comments.hss
  51. 92 0
      insert_preos_compressed_tables.hss
  52. 14 0
      invocation.hss
  53. 54 0
      invocation_ar.hss
  54. 210 0
      invocation_ld.hss
  55. 9 0
      ld.hss
  56. 18 0
      modes.hss
  57. 18 0
      modes_fargo.hss
  58. 24 0
      modes_flash_os.hss
  59. 9 0
      modes_kernel.hss
  60. 27 0
      modes_native.hss
  61. 19 0
      modes_nostub.hss
  62. 12 0
      modes_nostub_dll.hss
  63. 36 0
      operation.hss
  64. 55 0
      startup.hss
  65. 2 0
      symbols.hss
  66. 13 0
      symbols_comment.hss
  67. 14 0
      symbols_exit.hss
  68. 20 0
      symbols_extra_ram_addr.hss
  69. 24 0
      symbols_extraram.hss
  70. 8 0
      symbols_ld_bss_end.hss
  71. 10 0
      symbols_ld_bss_ref_count.hss
  72. 7 0
      symbols_ld_bss_size.hss
  73. 7 0
      symbols_ld_bss_start.hss
  74. 23 0
      symbols_ld_calc_const.hss
  75. 10 0
      symbols_ld_constructor_count.hss
  76. 9 0
      symbols_ld_constructors_end.hss
  77. 11 0
      symbols_ld_constructors_size.hss
  78. 10 0
      symbols_ld_constructors_start.hss
  79. 10 0
      symbols_ld_data_end.hss
  80. 12 0
      symbols_ld_data_ref_count.hss
  81. 9 0
      symbols_ld_data_size.hss
  82. 10 0
      symbols_ld_data_start.hss
  83. 11 0
      symbols_ld_data_var_name_end.hss
  84. 10 0
      symbols_ld_destructor_count.hss
  85. 9 0
      symbols_ld_destructors_end.hss
  86. 11 0
      symbols_ld_destructors_size.hss
  87. 10 0
      symbols_ld_destructors_start.hss
  88. 16 0
      symbols_ld_entry_point.hss
  89. 7 0
      symbols_ld_entry_point_plus_0x8000.hss
  90. 11 0
      symbols_ld_export_count.hss
  91. 8 0
      symbols_ld_file_version.hss
  92. 6 0
      symbols_ld_hardware_id.hss
  93. 7 0
      symbols_ld_has.hss
  94. 17 0
      symbols_ld_kernel_bss_table.hss
  95. 12 0
      symbols_ld_kernel_export_table.hss
  96. 8 0
      symbols_ld_kernel_flags.hss
  97. 13 0
      symbols_ld_lib_count.hss
  98. 8 0
      symbols_ld_nostub_comment_count.hss
  99. 18 0
      symbols_ld_program_size.hss
  100. 11 0
      symbols_ld_ram_call_count.hss

+ 13 - 0
bincode.hss

@@ -0,0 +1,13 @@
+[Main]
+Title=TIGCC Linker Binary Code Fixup
+Subsections=bincode_nop, bincode_return, bincode_branch, bincode_move, bincode_test, bincode_calculation
+
+[Top]
+The TIGCC linker can do many operations on binary code. If you want it to
+behave correctly in all cases, you need to make sure that no executable code
+is included in a data section, and no data is included in a code section.
+However, TIGCC usually merges all data into the code section to optimize
+references to it, so in rare cases it is possible for the linker to generate
+incorrect code.
+<BR><BR>
+Binary code fixup is divided into several categories:

+ 21 - 0
bincode_branch.hss

@@ -0,0 +1,21 @@
+[Main]
+Title=Branch Fixup and Optimization
+Subsections=bincode_branch_fline
+
+[Top]
+On some architectures, certain branches are not permitted. For example, on
+the MC68000 processor, it is not possible to branch to the next instruction
+using a short branch. While the assembler usually detects such invalid
+situations, they may still occur if the branch target is in a different
+section or file. The TIGCC linker detects such invalid situations and tries
+to resolve them as well as possible: If it is invalid for a branch at the end
+of a section to point to the beginning of the next section, it is removed
+unless it is a subroutine branch. For subroutine branches, a NOP instruction
+is inserted instead.
+<BR><BR>
+In addition to fixing invalid branches, the TIGCC linker can optimize branch
+instructions to reduce the number of absolute relocations needed. If an
+absolute branch (jump or subroutine branch) can be converted to a relative
+branch, the operating system does not need to insert the destination address
+at run time; therefore this will save space. Moreover, if range-cutting is
+enabled, optimizing branches can reduce the size of the code.

+ 23 - 0
bincode_branch_fline.hss

@@ -0,0 +1,23 @@
+[Main]
+Title=F-Line Branch Optimization
+
+[Top]
+The linker can convert absolute branches (which would normally need a
+relocation entry) into special relative F-Line sequences. These sequences are
+handled by an interrupt handler. The fact that an interrupt is needed makes
+these branches significantly slower, but using them can save quite a bit of
+space in the program.
+<BR><BR>
+There are two types of F-Line branches: The default version can be activated
+using the <A HREF="$$LINK(control_ld_use_fline_jumps)">__ld_use_fline_jumps</A>
+control symbol. Each branch has a size of six bytes. They are relative to
+their own address, which means that they can be supported by the AMS, and in
+fact, the AMS implements an interrupt handler for these branches starting
+from version 2.04. The other version can be activated using the
+<A HREF="$$LINK(control_ld_use_4byte_fline_jumps)">__ld_use_4byte_fline_jumps</A>
+control symbol. As the name says, each branch has a size of four bytes. They
+are relative to the program's entry point, so only an emulator that is
+installed from the program can handle them. Since they use codes that are
+otherwise used for ROM calls, this might break applications that are called
+from the program, if any. However, this is very unlikely, as the two ROM
+calls used are not defined yet.

+ 12 - 0
bincode_calculation.hss

@@ -0,0 +1,12 @@
+[Main]
+Title=Calculation Instruction Optimization
+
+[Top]
+If this type of optimization is turned on, then the TIGCC linker optimizes
+all instructions that perform calculations based on data stored in memory.
+This includes addition, subtraction, multiplication, division, and bitwise
+manipulation instructions.
+<BR><BR>
+This optimization can reduce the number of absolute references to locations
+inside the program, and it can also decrease the size of the code if
+range-cutting is enabled.

+ 15 - 0
bincode_move.hss

@@ -0,0 +1,15 @@
+[Main]
+Title=Move/Load/Push Instruction Optimization
+
+[Top]
+If this type of optimization is turned on, then the TIGCC linker optimizes
+all instructions that move data between two places. This includes
+instructions to move data between memory and registers or between two places
+in memory, instructions to load the address a of memory location into a
+register, and instructions to push the contents of a memory location on the
+stack. Note that due to the great variety of such instructions, this
+optimization is more likely to cause errors than others.
+<BR><BR>
+This optimization can reduce the number of absolute references to locations
+inside the program, and it can also decrease the size of the code if
+range-cutting is enabled.

+ 11 - 0
bincode_nop.hss

@@ -0,0 +1,11 @@
+[Main]
+Title=NOP Instruction Removal
+
+[Top]
+The TIGCC linker features the removal of unnecessary NOP instructions. For
+file formats which may insert a NOP (No OPeration) instruction at the end of
+a section in order to align its size to a specific boundary, it can remove
+this instruction to save a little space. Currently only the AmigaOS format is
+known to do this (see <A HREF="$$LINK(formats)">TIGCC Linker File
+Formats</A>). If the section ends with more than one NOP instruction, all
+instructions are kept.

+ 17 - 0
bincode_return.hss

@@ -0,0 +1,17 @@
+[Main]
+Title=Return Sequence Optimization
+
+[Top]
+The TIGCC linker can optimize function return sequences. If a section ends
+with a subroutine branch followed by a simple return instruction, the
+subroutine branch is converted into a simple unconditional branch (jump),
+and the return instruction is removed. Note that this may fail easily if
+there is a branch to the return instruction somewhere; if the return
+instruction is removed, the branch will point to arbitrary code or data.
+You can make this less likely by telling the assembler to emit all local
+labels, so the linker knows it cannot optimize a return sequence because
+there is a label in front of the return instruction. With the
+<A HREF="$$INFOLINK(gnuasm)">GNU Assembler</A>, this is done by using the
+<B>'--keep-locals'</B> option, which is included automatically if
+range-cutting is enabled. With the <A HREF="$$INFOLINK(a68k)">A68k Assembler</A>,
+the <B>'-d'</B> switch does the job.

+ 12 - 0
bincode_test.hss

@@ -0,0 +1,12 @@
+[Main]
+Title=Compare/Test Instruction Optimization
+
+[Top]
+If this type of optimization is turned on, then the TIGCC linker optimizes
+all instructions that compare the contents of a memory location with
+something. This includes operations that compare data and operations that
+test whether something is zero.
+<BR><BR>
+This optimization can reduce the number of absolute references to locations
+inside the program, and it can also decrease the size of the code if
+range-cutting is enabled.

+ 27 - 0
compiling.hss

@@ -0,0 +1,27 @@
+[Main]
+Title=Recompiling ld-tigcc and ar-tigcc
+
+[Top]
+Recompiling <CODE>ld-tigcc</CODE> and <CODE>ar-tigcc</CODE> (or the
+corresponding link DLL) from source may be useful if you want to make the
+linker as efficient as possible by disabling certain features. Recompilation
+requires <A HREF="http://gcc.gnu.org/">GCC</A> and
+<A HREF="http://www.gnu.org/software/make/">GNU make</A>. If you are using
+Linux, you may simply run <CODE>make</CODE> in the source code directory; the
+same is probably true for other Unix variants. If you are using Windows, you
+need to download <A HREF="http://www.mingw.org/msys.html">MSYS</A> or make
+some minor modifications to the makefile.
+<BR><BR>
+If you only want to disable some features, you can take a look at the
+definitions in the makefile (the file called <CODE>Makefile</CODE>). The
+<CODE>DEFINES</CODE> variable contains the general features to be included;
+<CODE>EXE_DEFINES</CODE> contains the features that should only be included
+in the executable files (not in the DLL). All available definitions are
+documented at the top of <CODE>generic.h</CODE>.
+<BR><BR>
+For example, if you want to disable support for the AmigaOS files generated
+by the <A HREF="$$INFOLINK(a68k)">A68k Assembler</A>, you may simply remove
+the <B>'-DAMIGAOS_SUPPORT'</B> definition from the <CODE>DEFINES</CODE>
+variable. Note that some combinations are invalid; for example, if you
+disable support for all object file formats, you will get a "file format not
+recognized" error whenever you try to link some files.

+ 34 - 0
control.hss

@@ -0,0 +1,34 @@
+[Main]
+Title=Symbols to Control the Linker
+Subsections=control_ref_all, control_tigcc_native, control_nostub, control_nostub_dll, control_fargo, control_flash_os, control_library, control_calc, control_flag, control_version, control_lib_min_version, control_ld_use_fline_jumps, control_ld_use_4byte_fline_jumps, control_ld_omit_bss_init, control_ld_ignore_global_imports
+
+[Top]
+In addition to options specified in the command line, the TIGCC linker can
+be controlled using special symbol names. They should be used directly only
+in assembly programs; C programs should rely on the appropriate library
+facilities if they are available.
+<BR><BR>
+These are the symbols the linker treats as control symbols:
+
+[Bottom]
+Symbols can be created in a variety of ways; they can be:
+<UL>
+<LI>labels;</LI>
+<LI>undefined exported symbols;</LI>
+<LI>imported (used but undefined) symbols;</LI>
+<LI>common symbols.</LI>
+</UL>
+Not all assemblers support all types of symbols; for example, the
+<A HREF="$$INFOLINK(a68k)">A68k assembler</A> does not support exporting
+symbols which are not defined somewhere in the same file. This assembler is
+also somewhat special from the linker's point of view: It only outputs
+exported and imported symbols by default; local labels can be supplied in a
+symbol table, but since it is optional, the linker does not use it to receive
+control information.
+<BR><BR>
+If a symbol is detected as a control symbol, it is not imported into the
+internal data structures as usual. There are two reasons for this: First,
+if a user accidentally defines a control symbol somewhere (some traditional
+control symbol names are quite short), the resulting error can help detect
+this problem. Second, if common symbols are used, they would waste space in
+the executable otherwise.

+ 26 - 0
control_calc.hss

@@ -0,0 +1,26 @@
+[Main]
+Title=_ti92, _ti89, _ti92plus, _v200
+Index=_ti92, _ti89, _ti92plus, _v200
+
+[Top]
+You need to define one or more of these symbols to specify the calculator for
+which the program is to be linked. This only controls which output files are
+created; the linker does not check whether a file format really exists for a
+given calculator. Kernel compatibility flags (see
+<A HREF="$$LINK(control_flag)">_flag_...</A>) are added according to the
+symbol:
+<BR><BR>
+<TABLE BORDER CELLPADDING="3">
+<TR>
+<TD VALIGN="TOP">_ti89</TD>
+<TD VALIGN="TOP">Flag 0 (0x01)</TD>
+</TR>
+<TR>
+<TD VALIGN="TOP">_ti92plus</TD>
+<TD VALIGN="TOP">Flag 1 (0x02)</TD>
+</TR>
+<TR>
+<TD VALIGN="TOP">_v200</TD>
+<TD VALIGN="TOP">Flag 5 (0x20)</TD>
+</TR>
+</TABLE>

+ 7 - 0
control_fargo.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=_fargo
+
+[Top]
+Defining this symbol switches to <A HREF="$$LINK(modes_fargo)">Fargo II
+mode</A>. If Fargo support is not compiled in, the symbol is not treated in a
+special way.

+ 11 - 0
control_flag.hss

@@ -0,0 +1,11 @@
+[Main]
+Title=_flag_...
+See Also=symbols_ld_kernel_flags: __ld_kernel_flags
+
+[Top]
+Defining _flag_<I>n</I> sets the <I>n</I>-th bit in the kernel compatibility
+flags. Some flags are reserved for calculator compatibility information (see
+<A HREF="$$LINK(control_calc)">here</A>); the others can be used to pass
+additional information to the kernel. Note that the meaning of a particular
+flag may vary between kernels. Kernel flags occupy a single byte; therefore
+the range of <I>n</I> is 0 through 7.

+ 7 - 0
control_flash_os.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=_flash_os
+
+[Top]
+Defining this symbol switches to <A HREF="$$LINK(modes_flash_os)">Flash OS
+mode</A>. If Flash OS support is not compiled in, the symbol is not treated in
+a special way.

+ 7 - 0
control_ld_ignore_global_imports.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=__ld_ignore_global_imports
+
+[Top]
+Defining this symbol in a source file tells the linker that from this file
+on, defining a <A HREF="$$LINK(control_ref_all)">__ref_all_...</A> symbol has
+no effect. This should not be used except in very special circumstances.

+ 24 - 0
control_ld_omit_bss_init.hss

@@ -0,0 +1,24 @@
+[Main]
+Title=__ld_omit_bss_init
+
+[Top]
+Defining this symbol in a source file tells the linker that this file does
+not depend on the initialization of the BSS section to zero. The result is
+that all uninitialized global variables defined in that file may contain
+garbage at the beginning of the program. This does not guarantee that the
+initialization is skipped; in fact, if at least one file needs the
+initialization, it is easier to initialize even the variables that were
+declared to not need it.
+<BR><BR>
+For pointer-based object file formats (such as COFF, the format used by the
+<A HREF="http://www.gnu.org/">GNU</A> tools included in TIGCC), this symbol
+really affects all variables in the file it is defined in. For sequential
+formats (such as the AmigaOS format used by the
+<A HREF="$$INFOLINK(a68k)">A68k assembler</A>), it affects only the parts
+that follow the symbol. Since BSS data usually appears at the end of the
+object file, this restriction should not have any effect.
+<BR><BR>
+<B>Note:</B> If you define this symbol, you should use the
+<A HREF="$$INFOLINK(comopts)">compiler option</A>
+<B>'-fno-zero-initialized-in-bss'</B>; otherwise even variables explicitly
+initialized to zero will contain garbage.

+ 13 - 0
control_ld_use_4byte_fline_jumps.hss

@@ -0,0 +1,13 @@
+[Main]
+Title=__ld_use_4byte_fline_jumps
+See Also=control_ld_use_fline_jumps: __ld_use_fline_jumps
+
+[Top]
+Defining this symbol tells the linker to use program-relative
+<A HREF="$$LINK(bincode_branch_fline)">F-Line branches</A> for branches which
+would otherwise need to be absolute. These branches are 4 bytes long, whereas
+normal relative F-Line branches have a size of 6 bytes. However, since they
+are relative to the program's entry point, the program must install its own
+emulator to handle them.
+<BR><BR>
+4 byte F-Line branches are useful only if range-cutting is enabled.

+ 9 - 0
control_ld_use_fline_jumps.hss

@@ -0,0 +1,9 @@
+[Main]
+Title=__ld_use_fline_jumps
+See Also=control_ld_use_4byte_fline_jumps: __ld_use_4byte_fline_jumps
+
+[Top]
+Defining this symbol tells the linker to use relative
+<A HREF="$$LINK(bincode_branch_fline)">F-Line branches</A> for branches which
+would otherwise need to be absolute. These are supported by AMS 2.04 or
+higher and by various F-Line emulators, including TIGCC's own emulator.

+ 12 - 0
control_lib_min_version.hss

@@ -0,0 +1,12 @@
+[Main]
+Title=...@version..., ...__version...
+Index=...@version..., ...__version..., Minimum Library Versions
+See Also=symbols_lib_call: Library Calls
+
+[Top]
+To specify a required minimum version number for a library used by the
+program, you can define <I>lib</I>@version<I>ver</I> or
+<I>lib</I>__version<I>ver</I>. <I>lib</I> is the name of the library (see
+<A HREF="$$LINK(symbols_lib_call)">Library Calls</A>); <I>ver</I> is the
+minimum version number to be accepted, interpreted as a hexadecimal value
+(see <A HREF="$$LINK(control_version)">_version...</A>).

+ 10 - 0
control_library.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=_library
+
+[Top]
+Defining this symbol causes a library to be created instead of a program.
+The linker will warn about program <A HREF="$$LINK(startup)">startup
+sections</A> being included, and depending on the
+<A HREF="$$LINK(modes)">linking mode</A> some different
+<A HREF="$$LINK(global_imports_auto)">automatic global imports</A> will be
+created.

+ 7 - 0
control_nostub.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=_nostub
+
+[Top]
+Defining this symbol switches to <A HREF="$$LINK(modes_nostub)">NoStub
+mode</A>. It can only be used in assembly files, since it is impossible to
+guarantee for some code to be at the beginning of the file.

+ 8 - 0
control_nostub_dll.hss

@@ -0,0 +1,8 @@
+[Main]
+Title=_nostub_dll
+
+[Top]
+Defining this symbol switches to <A HREF="$$LINK(modes_nostub_dll)">NoStub
+DLL mode</A> and tells the linker to compile a library instead of a program.
+If NoStub DLL support is not compiled in, the symbol is not treated in a
+special way.

+ 14 - 0
control_ref_all.hss

@@ -0,0 +1,14 @@
+[Main]
+Title=__ref_all_...
+
+[Top]
+Defining __ref_all_<I>name</I> creates a
+<A HREF="$$LINK(global_imports)">global import</A> for all symbols named
+<I>name</I>. Importing the same symbol twice does not have any particular
+effect; however, sometimes this is necessary if you want a global import to
+succeed as early as possible.
+<BR><BR>
+If none of the archives supplied to the linker exports a symbol with this
+name (or a related name using
+<A HREF="$$LINK(global_imports_conditional)">conditional reaction</A>), the
+linker outputs a warning.

+ 7 - 0
control_tigcc_native.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=_tigcc_native
+
+[Top]
+Defining this symbol switches to <A HREF="$$LINK(modes_native)">TIGCC native
+mode</A>. We recommend that you define this in all new programs, and then
+create or import <A HREF="$$LINK(startup)">startup sections</A>.

+ 10 - 0
control_version.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=_version...
+Index=File Version
+See Also=symbols_ld_file_version: __ld_file_version
+
+[Top]
+If you define the symbol _version<I>ver</I>, the program/library version
+number is set to <I>ver</I>, interpreted as a hexadecimal value. Note that
+the kernel format limits the reserved space for the version number to one
+byte; this means that kernels only accept two digits for <I>ver</I>.

+ 89 - 0
dump.hss

@@ -0,0 +1,89 @@
+[Main]
+Title=ld-tigcc Program Dumps
+
+[Top]
+If you turn on dumps in <CODE>ld-tigcc</CODE> (using the
+<B>'--dump[<I>n</I>]'</B> option), <CODE>ld-tigcc</CODE> prints the contents of
+the internal data structures to standard output between various events during
+the linking stage. These places are numbered, so that you can turn on a specific
+dump by adding an index to the option. The following table shows the current
+location of the different dumps:
+<DL>
+<DT><B>Dump 0</B>
+<DD>This dump is produced just after all object files have been imported.
+    Relocation entries that refer to different files have not been resolved yet;
+    neither have ROM/RAM/library call symbols been translated into actual
+    ROM/RAM/library calls. Archive members have only been imported if this was
+    specified by a global import.
+<BR><BR>
+<DT><B>Dump 1</B>
+<DD>Relocation entries have been resolved to the maximum extent possible. If
+    they could not be resolved to existing symbols or had been treated as
+    RAM/ROM/library calls, archive members have been imported for them.
+<BR><BR>
+<DT><B>Dump 2</B>
+<DD>All uninitialized and zero-data sections have been merged, as well as all
+    data sections if this was necessary. Automatic global imports have been
+    added.
+<BR><BR>
+<DT><B>Dump 3</B>
+<DD>All global imports have been processed; even the ones which contained
+    negations.
+<BR><BR>
+<DT><B>Dump 4</B>
+<DD>Relocation entries from the archive members which were just
+    imported by global imports have been resolved, possibly importing new
+    archive members.
+    If relocation optimization is enabled, another dump is appended with the
+    same contents after relocation optimization. If removal of unused
+    sections is enabled, a third dump is inserted after this removal.
+<BR><BR>
+<DT><B>Dump 5</B>
+<DD>All sections which are not externalized have been merged. Note that some
+    parts of the code fixup need to be done just before the sections are merged,
+    so there is also a lot of code fixup and optimization between dumps 4 and 5.
+<BR><BR>
+<DT><B>Dump 6</B>
+<DD>The remaining code fixup and optimization has been performed.
+<BR><BR>
+<DT><B>Dump 7</B>
+<DD>Certain built-in symbols whose value depends on the program contents have
+    been resolved. Insertions that were requested to be added at an arbitrary
+    place have been added to the end of the program.
+<BR><BR>
+<DT><B>Dump 8</B>
+<DD>Relative relocation entries have been replaced by the actual distances they
+    had represented.
+</DL>
+The program dumps are usually self-explaining; however, a few items require
+special attention:
+<DL>
+<DT><B>&lt;<I>n</I>B: <I>target</I> [- <I>relation</I>] [+/- offset]&gt;</B>
+<DD>Indicates a relocation entry or ROM/RAM/library call. <I>target</I> and
+    <I>relation</I> have the form <I>symbol</I>[+/-<I>offset</I>], which
+    stands for the address of <I>symbol</I>, corrected by <I>offset</I>.
+    <I>n</I> specifies the number of bytes reserved for the address/offset of
+    the target.
+<BR><BR>
+<DT><B>&lt;<I>n</I>B: ... (rel)&gt;</B>
+<DD>Indicates that the relocation entry is relative to its own address.
+<BR><BR>
+<DT><B>&lt;<I>n</I>B: <I>symbol</I> (?) ...&gt;</B>
+<DD>Indicates a relocation entry which has not been resolved yet.
+<BR><BR>
+<DT><B>&lt;<I>n</I>B: <I>symbol</I> (-&gt;) ...&gt;</B>
+<DD>Indicates a relocation entry pointing into another section.
+<BR><BR>
+<DT><B>&lt;<I>n</I>B: ...&gt; (!)</B>
+<DD>Indicates that the section data at the place of the relocation entry is
+    nonzero. This usually indicates a problem, but in rare cases, it is
+    valid. For example, if you use ROM/RAM/library calls with an offset, this
+    offset is usually emitted into the section contents, but the actual call
+    still exists.
+<BR><BR>
+<DT><B><I>address</I>: (!)</B>
+<DD>Indicates an internal inconsistency (for example an item outside of a
+    section, overlapping items, or an internal ordering error).
+</DL>
+Section offsets and data are always output in hexadecimal notation. Question
+marks indicate uninitialized data, which may have random content.

+ 110 - 0
formats.hss

@@ -0,0 +1,110 @@
+[Main]
+Title=TIGCC Linker File Formats
+
+[Top]
+The TIGCC linker recognizes several file formats. Currently, it can import
+COFF and AmigaOS files and export TIOS ASM files, Nostub DLL files (which are
+TIOS custom files with a special format), and Fargo II files (which are TIOS
+PRGM files with special hidden data). A small overview of the capabilities of
+each format is described in the following table:
+<BR><BR>
+<TABLE BORDER CELLPADDING="3">
+<TR>
+<TD><B>Format</B></TD>
+<TD><B>Sections</B></TD>
+<TD><B>Relocations</B></TD>
+<TD><B>Unresolved Relocations</B></TD>
+<TD><B>Symbols</B></TD>
+<TD><B>ROM Calls</B></TD>
+<TD><B>RAM Calls</B></TD>
+<TD><B>Library Calls</B></TD>
+<TD><B>Library Exports</B></TD>
+<TD><B>Debug Information</B></TD>
+<TD><B>Version Number</B></TD>
+<TD><B>Additional Information</B></TD>
+</TR>
+<TR>
+<TD VALIGN="TOP"><B>COFF</B></TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes (through unresolved relocations)</TD>
+<TD VALIGN="TOP">Yes (through unresolved relocations)</TD>
+<TD VALIGN="TOP">Yes (through unresolved relocations)</TD>
+<TD VALIGN="TOP">Yes (through symbols)</TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes (through symbols)</TD>
+<TD VALIGN="TOP">Yes (through symbols)</TD>
+</TR>
+<TR>
+<TD VALIGN="TOP"><B>AmigaOS</B></TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes (except 1-byte absolute)</TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes (through unresolved relocations)</TD>
+<TD VALIGN="TOP">Yes (through unresolved relocations)</TD>
+<TD VALIGN="TOP">Yes (through unresolved relocations)</TD>
+<TD VALIGN="TOP">Yes (through symbols)</TD>
+<TD VALIGN="TOP">Yes</TD>
+<TD VALIGN="TOP">Yes (through symbols)</TD>
+<TD VALIGN="TOP">Yes (through symbols)</TD>
+</TR>
+<TR>
+<TD VALIGN="TOP"><B>TIOS ASM</B></TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">4-byte absolute only</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No (but kernels exist that interpret a special header format)</TD>
+<TD VALIGN="TOP">No (but kernels exist that interpret a special header format)</TD>
+<TD VALIGN="TOP">No (but kernels exist that interpret a special header format)</TD>
+<TD VALIGN="TOP">No (but kernels exist that interpret a special header format)</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No (but kernels exist that interpret a special header format)</TD>
+<TD VALIGN="TOP">No (but kernels exist that interpret a special header format with a comment, and a header for additional information may be inserted manually)</TD>
+</TR>
+<TR>
+<TD VALIGN="TOP"><B>Nostub DLL</B></TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">4-byte absolute only</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">Yes (but required header is not inserted directly by the linker)</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">Yes (but required header is not inserted directly by the linker)</TD>
+<TD VALIGN="TOP">No</TD>
+</TR>
+<TR>
+<TD VALIGN="TOP"><B>Fargo II</B></TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">4-byte absolute only (but required header is not inserted directly by the linker)</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">Yes (through library calls, but required header is not inserted directly by the linker)</TD>
+<TD VALIGN="TOP">Yes (through library calls, but required header is not inserted directly by the linker)</TD>
+<TD VALIGN="TOP">Yes (but required header is not inserted directly by the linker)</TD>
+<TD VALIGN="TOP">Yes (but required header is not inserted directly by the linker)</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">Single comment only (but required header is not inserted directly by the linker)</TD>
+</TR>
+<TR>
+<TD VALIGN="TOP"><B>TI Flash OS (TIB, 89u/9xu/v2u)</B></TD>
+<TD VALIGN="TOP">2 fixed sections (24 KB startup, 1944/3992 KB main)</TD>
+<TD VALIGN="TOP">No, runs from fixed address</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">No</TD>
+<TD VALIGN="TOP">Yes (but not yet supported by the linker)</TD>
+<TD VALIGN="TOP">Product name and date stamp only (but not yet supported by the linker)</TD>
+</TR>
+</TABLE>

+ 43 - 0
global_imports.hss

@@ -0,0 +1,43 @@
+[Main]
+Title=Global Imports
+Subsections=global_imports_conditional, global_imports_auto
+
+[Top]
+Just like <A HREF="$$LINK(startup)">startup sections</A>, the concept of
+<U>global imports</U> is unique to the TIGCC linker. Global imports and
+startup sections are closely related to each other: It is best to keep
+startup sections in archive files, so they can be imported as needed, but
+the existing method of importing archive file members does not work. Usually,
+an archive file member is imported if a symbol it exports is referenced in
+a relocation entry. However, code that requires a specific startup section to
+be included does not necessarily reference any of the symbols in the
+corresponding archive member; it just needs the startup code to be there. A
+global import solves this problem by importing an archive member without
+inserting its address anywhere.
+<BR><BR>
+Actually, a global import imports all archive members that export the symbol
+referenced by the import (and even more, see
+<A HREF="$$LINK(global_imports_conditional)">Conditional Reaction to Global
+Imports</A>). If no archive member exports this symbol, a warning is emitted.
+This way, it is very easy to create archive files that react to multiple
+imports; for example:
+<UL>
+<LI>File 1 exports the symbols <I>A</I> and <I>B</I>.</LI>
+<LI>File 2 exports the symbols <I>B</I> and <I>C</I>.</LI>
+<LI>File 3 exports the symbols <I>A</I> and <I>C</I>.</LI>
+</UL>
+A global import for <I>A</I> would cause the files 1 and 3 to be included in
+the program. If it could only import one file, 6 files would be needed to get
+the same result:
+<UL>
+<LI>File 1 exports the symbol <I>A</I> and creates two global imports for <I>File4</I> and <I>File6</I>.</LI>
+<LI>File 2 exports the symbol <I>B</I> and creates two global imports for <I>File4</I> and <I>File5</I>.</LI>
+<LI>File 3 exports the symbol <I>C</I> and creates two global imports for <I>File5</I> and <I>File6</I>.</LI>
+<LI>File 4 exports the symbol <I>File4</I>.</LI>
+<LI>File 5 exports the symbol <I>File5</I>.</LI>
+<LI>File 6 exports the symbol <I>File6</I>.</LI>
+</UL>
+Global import can be created using the
+<A HREF="$$LINK(control_ref_all)">__ref_all_...</A> control symbol. Some
+global imports are also created automatically by the linker on certain
+conditions.

+ 142 - 0
global_imports_auto.hss

@@ -0,0 +1,142 @@
+[Main]
+Title=Automatically Created Global Imports
+Index=__kernel_program_header, __kernel_library_header, __fargo_program_header, __fargo_library_header, __flash_os_header, __nostub_comment_header, __handle_constructors, __handle_destructors, __handle_bss, __initialize_bss, __handle_relocs, __handle_rom_calls, __handle_ram_calls, __handle_libraries, __handle_data_var, __data_var_create_copy, __data_var_copy_if_archived
+
+[Top]
+In addition to user-defined global imports, the TIGCC linker also defines
+some global imports of its own, whenever special code is needed to handle a
+situation:
+<BR><BR>
+<DL>
+<DT><B>__kernel_program_header</B>
+<DD>This global import is created automatically if the linker
+    is operating in <A HREF="$$LINK(modes_kernel)">kernel mode</A>, and if the
+    file is not declared as a library (see the
+    <A HREF="$$LINK(control_library)">_library</A> control symbol).
+<BR><BR>
+<DT><B>__kernel_library_header</B>
+<DD>This global import is created automatically if the linker
+    is operating in <A HREF="$$LINK(modes_kernel)">kernel mode</A>, and if the
+    file is declared as a library (see the
+    <A HREF="$$LINK(control_library)">_library</A> control symbol).
+<BR><BR>
+<DT><B>__fargo_program_header</B>
+<DD>This global import is created automatically if the linker
+    is operating in <A HREF="$$LINK(modes_fargo)">Fargo II mode</A>, and if the
+    file is not declared as a library (see the
+    <A HREF="$$LINK(control_library)">_library</A> control symbol).
+<BR><BR>
+<DT><B>__fargo_library_header</B>
+<DD>This global import is created automatically if the linker
+    is operating in <A HREF="$$LINK(modes_fargo)">Fargo II mode</A>, and if the
+    file is declared as a library (see the
+    <A HREF="$$LINK(control_library)">_library</A> control symbol).
+<BR><BR>
+<DT><B>__flash_os_header</B>
+<DD>This global import is created automatically if the linker
+    is operating in <A HREF="$$LINK(modes_flash_os)">Flash OS mode</A>.
+<BR><BR>
+<DT><B>__nostub_comment_header</B>
+<DD>This global import is created automatically if NoStub data (comment) exports
+    are defined for the program. The file reacting to this import must use
+    <A HREF="$$LINK(symbols_ld_nostub_comment_count)">__ld_nostub_comment_count
+    </A> and
+    <A HREF="$$LINK(insert_nostub_comments)">__ld_insert_nostub_comments</A>
+    to insert the actual data exports into the header.
+<BR><BR>
+<DT><B>__handle_constructors</B>
+<DD>This global import is created automatically if constructors
+    are defined for the program. The file which handles this import must query
+    the constructor section using the
+    <A HREF="$$LINK(symbols_ld_constructors_start)">__ld_constructors_start</A>,
+    <A HREF="$$LINK(symbols_ld_constructors_end)">__ld_constructors_end</A>,
+    <A HREF="$$LINK(symbols_ld_constructors_size)">__ld_constructors_size</A>,
+    and <A HREF="$$LINK(symbols_ld_constructor_count)">__ld_constructor_count</A>
+    symbols.
+<BR><BR>
+<DT><B>__handle_destructors</B>
+<DD>This global import is created automatically if destructors
+    are defined for the program. The file which handles this import must query
+    the destructor section using the
+    <A HREF="$$LINK(symbols_ld_destructors_start)">__ld_destructors_start</A>,
+    <A HREF="$$LINK(symbols_ld_destructors_end)">__ld_destructors_end</A>,
+    <A HREF="$$LINK(symbols_ld_destructors_size)">__ld_destructors_size</A>,
+    and <A HREF="$$LINK(symbols_ld_destructor_count)">__ld_destructor_count</A>
+    symbols.
+<BR><BR>
+<DT><B>__handle_bss</B>
+<DD>This global import is created automatically if the program
+    contains a BSS section (a section containing uninitialized global variables).
+    No file needs to react to this import; if the BSS section is not created at
+    run time (using <A HREF="$$LINK(symbols_ld_bss_size)">__ld_bss_size</A>,
+    <A HREF="$$LINK(symbols_ld_bss_ref_count)">__ld_bss_ref_count</A>, and
+    an appropriate <A HREF="$$LINK(insert)">insertion</A> for the relocation), it
+    is simply passed on to the output file. If the output format does not support
+    sections, the BSS section is merged with the other sections. However, if the
+    program reacts to this import, it absolutely <I>must</I> handle the
+    relocation entries pointing into the BSS section.
+<BR><BR>
+<DT><B>__initialize_bss</B>
+<DD>This global import is created automatically if the program
+    contains a BSS section, and the program requires the contents of this section
+    to be initialized to zero. The file reacting to this import must use
+    <A HREF="$$LINK(symbols_ld_bss_start)">__ld_bss_start</A>,
+    <A HREF="$$LINK(symbols_ld_bss_end)">__ld_bss_end</A>, and
+    <A HREF="$$LINK(symbols_ld_bss_size)">__ld_bss_size</A> to query the location
+    and size of the BSS section.
+    <BR><BR>
+    <DT><B>__handle_relocs</B>
+    <DD>This global import is created automatically if the program
+    contains absolute relocation entries. If no file reacts to this import,
+    relocation entries have to be handled by the output format. The file reacting
+    to this import must use
+    <A HREF="$$LINK(symbols_ld_reloc_count)">__ld_reloc_count</A> and an
+    appropriate <A HREF="$$LINK(insert)">insertion</A> to get information about
+    the necessary relocation.
+<BR><BR>
+<DT><B>__handle_rom_calls</B>
+<DD>This global import is created automatically if the program
+    contains ROM calls. If no file reacts to this import, ROM calls are handled
+    by the output format. The file reacting to this import must use
+    <A HREF="$$LINK(symbols_ld_rom_call_count)">__ld_rom_call_count</A> and an
+    appropriate <A HREF="$$LINK(insert)">insertion</A> to get information about
+    the ROM calls.
+<BR><BR>
+<DT><B>__handle_ram_calls</B>
+<DD>This global import is created automatically if the program
+    contains RAM calls. If no file reacts to this import, RAM calls are handled
+    by the output format. The file reacting to this import must use
+    <A HREF="$$LINK(symbols_ld_ram_call_count)">__ld_ram_call_count</A> and an
+    appropriate <A HREF="$$LINK(insert)">insertion</A> to get information about
+    the RAM calls.
+<BR><BR>
+<DT><B>__handle_libraries</B>
+<DD>This global import is created automatically if the program
+    references at least one library. If no file reacts to this import, library
+    calls are handled by the output format. The file reacting to this import must
+    use <A HREF="$$LINK(symbols_ld_lib_count)">__ld_lib_count</A> and an
+    appropriate <A HREF="$$LINK(insert)">insertion</A> to get information about
+    the libraries.
+<BR><BR>
+<DT><B>__handle_data_var</B>
+<DD>This global import is created automatically if the data
+    section of the program is not included in the program itself but in an
+    external file. The file that handles this import must open this file and
+    relocate the program accordingly. It must refer to
+    <A HREF="$$LINK(symbols_ld_data_var_name_end)">__ld_data_var_name_end</A>,
+    <A HREF="$$LINK(symbols_ld_data_size)">__ld_data_size</A>, and an appropriate
+    <A HREF="$$LINK(insert)">insertion</A> for the relocation.
+<BR><BR>
+<DT><B>__data_var_create_copy</B>
+<DD>This global import is created automatically if the data
+    section of the program is not included in the program itself but in an
+    external file, and this file needs to be copied into memory (either always or
+    under certain circumstances).
+<BR><BR>
+<DT><B>__data_var_copy_if_archived</B>
+<DD>This global import is created automatically if the data
+    section of the program is not included in the program itself but in an
+    external file, and this file needs to be copied into memory only if it is
+    archived. This import is created only in combination with
+    __data_var_create_copy.
+</DL>

+ 32 - 0
global_imports_conditional.hss

@@ -0,0 +1,32 @@
+[Main]
+Title=Conditional Reaction to Global Imports
+Index=..._AND_..., NOT_...
+
+[Top]
+Sometimes, it is convenient for an archive member to react to a global import
+differently than just to be included whenever the import is created. For
+example, a startup section may be optimized better if a certain register
+already holds a certain value, otherwise it must compute the value by itself.
+The TIGCC linker defines two symbol operators for this purpose:
+<UL>
+<LI>..._AND_...</LI>
+<LI>NOT_...</LI>
+</UL>
+To be included only if the global imports <I>A</I> and <I>B</I> are defined,
+a file must export the symbol <CODE><I>A</I>_AND_<I>B</I></CODE>. To be
+included only if the global import <I>A</I> is not defined, a file must
+export the symbol <CODE>NOT_<I>A</I></CODE>. Symbol operators may be
+combined, i.e. a file exporting <CODE>NOT_<I>A</I>_AND_<I>B</I></CODE> is
+included only if no global import <I>A</I> exists, and a global import
+<I>B</I> is defined.
+<BR><BR>
+There is a small quirk related to negated conditions: At some point, the
+linker needs to assume that no global imports <I>A</I> and <I>B</I> exist,
+and any file exporting the symbol <CODE>NOT_<I>A</I></CODE> or
+<CODE>NOT_<I>B</I></CODE> needs to be imported. However, the file which
+exported <CODE>NOT_<I>B</I></CODE> may actually create a global import
+<I>A</I> after the file exporting <CODE>NOT_<I>A</I></CODE> has been
+imported. The linker does not detect this, so you need to be careful not to
+create such situations. They are especially difficult to detect if a lot of
+combinations of AND and NOT operators are used, and if a lot of files that
+react to global imports create imports of their own.

File diff suppressed because it is too large
+ 2 - 0
insert.hss


+ 20 - 0
insert_compressed_bss_refs.hss

@@ -0,0 +1,20 @@
+[Main]
+Title=__ld_insert_compressed_bss_refs
+See Also=insert_compressed_data_refs: __ld_insert_compressed_data_refs, insert_compressed_relocs: __ld_insert_compressed_relocs, insert_kernel_bss_refs: __ld_insert_kernel_bss_refs
+
+[Top]
+__ld_insert_compressed_bss_refs inserts relocs in the format defined in
+<A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>.
+The only differences are that the <I>relocation address</I> is not the entry
+point of the program but the beginning of the BSS section and that the
+reference symbol used if there is no previous reloc (i.e. for the first reloc)
+is <CODE>__ld_compressed_bss_refs_ref</CODE>.
+<BR><BR>
+If you insert these references, the linker assumes that the BSS section is
+handled by you; that is, you have to allocate it dynamically using
+<A HREF="$$LINK(symbols_ld_bss_size)">__ld_bss_size</A> and use a pointer to
+it as the <I>relocation address</I>.
+<BR><BR>
+<B>Note:</B> The limitations of
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A> also
+apply to this insertion.

+ 20 - 0
insert_compressed_data_refs.hss

@@ -0,0 +1,20 @@
+[Main]
+Title=__ld_insert_compressed_data_refs
+See Also=insert_compressed_bss_refs: __ld_insert_compressed_bss_refs, insert_compressed_relocs: __ld_insert_compressed_relocs, insert_kernel_data_refs: __ld_insert_kernel_data_refs
+
+[Top]
+__ld_insert_compressed_data_refs outputs references to the data section in the
+format defined in
+<A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>.
+The only differences are that the <I>relocation address</I> is not the entry
+point of the program but the beginning of the data section and that the
+reference symbol used if there is no previous reloc (i.e. for the first reloc)
+is <CODE>__ld_compressed_data_refs_ref</CODE>.
+<BR><BR>
+If you read the data from an external variable (see
+<A HREF="$$LINK(global_imports_auto)">__handle_data_var</A>), you have to use
+the address of the variable (or a copy) as the <I>relocation address</I>.
+<BR><BR>
+<B>Note:</B> The limitations of
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A> also
+apply to this insertion.

+ 57 - 0
insert_compressed_relocs.hss

@@ -0,0 +1,57 @@
+[Main]
+Title=__ld_insert_compressed_relocs
+See Also=insert_compressed_bss_refs: __ld_insert_compressed_bss_refs, insert_compressed_data_refs: __ld_insert_compressed_data_refs, insert_kernel_relocs: __ld_insert_kernel_relocs
+
+[Developer Notes]
+Warning: This table is referred to in other places. Please don't change the
+definition of "offset" if you don't know what you are doing. You'll risk
+breaking the definition of __ld_insert_compressed_rom_calls otherwise.
+
+[Top]
+__ld_insert_compressed_relocs inserts relocs in a compressed format known
+from Fargo. For more information on inserting and processing relocs, see
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A>.
+<BR><BR>
+In the following format description, <I>offset</I> refers to the difference
+in words (half of the difference in bytes) between the start of this reloc
+and the end of the previous reloc. If there is no previous reloc (i.e. for
+the first reloc), <I>offset</I> is the distance in words between this reloc
+and the symbol <CODE>__ld_compressed_relocs_ref</CODE>. This symbol must be
+exported to be found. If it is not found, the entry point is used instead
+(see <A HREF="$$LINK(symbols_ld_entry_point)">__ld_entry_point</A>).
+<UL>
+<LI>For each relocation entry...
+    <UL>
+    <LI>If we are inside a nibble sequence (see below):
+        <UL>
+        <LI><B>1 nibble (1/2 byte):</B> <I>offset</I></LI>
+        </UL></LI>
+    <LI>Else: Any of the following, whichever fits:
+        <UL>
+        <LI><B>1 byte:</B> <I>offset</I> + 1 (must be between 0x01 and
+            0x7F)</LI>
+        <LI><B>1 byte:</B>
+            <UL>
+            <LI>1<SUP>st</SUP> nibble: <I>nibble_count</I> / 2 + 0x6
+                (must be between 0x8 and 0xB)</LI>
+            <LI>2<SUP>nd</SUP> nibble: <I>offset</I></LI>
+            </UL>
+            A nibble sequence of <I>nibble_count</I> nibbles follows
+            (see above).
+        </LI>
+        <LI><B>2 bytes:</B> <I>offset</I> + 0xBF81 (must be between 0xC000
+            and 0xFFFE)</LI>
+        <LI>A variable-length sequence:
+            <UL>
+            <LI><B>2 bytes:</B> 0xFFFF</LI>
+            <LI>Any of the four possibilities, with <I>offset</I> decreased
+                by 0x407E</LI>
+            </UL>
+        </LI>
+        </UL></LI>
+    </UL></LI>
+<LI><B>1 byte:</B> 0</LI>
+</UL>
+<B>Note:</B> The limitations of
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A> also
+apply to this insertion.

+ 33 - 0
insert_compressed_rom_calls.hss

@@ -0,0 +1,33 @@
+[Main]
+Title=__ld_insert_compressed_rom_calls
+See Also=insert_kernel_rom_calls: __ld_insert_kernel_rom_calls
+
+[Top]
+__ld_insert_compressed_rom_calls can be used to handle
+<A HREF="$$LINK(symbols_rom_call)">ROM calls</A>. It inserts references to
+ROM calls in a compressed format known from Fargo but specifically altered for
+TIGCC:
+<UL>
+<LI>If the program uses at least one ROM call...
+    <UL>
+    <LI>For each ROM call...
+        <UL>
+        <LI>Compressed <I>index</I> of the ROM call. The index is encoded as
+            in <A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>,
+            with <I>offset</I> being the index of the ROM call for the first
+            entry, and the difference of the index of this ROM call and the
+            index of the previous one plus 1 for the following ones. The
+            compressed index is considered part of the relocation table that
+            follows, so nibble encoding can be used.</LI>
+        <LI>A compressed relocation table for this ROM call. See
+            <A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>
+            for the format used.
+            The reference symbol used if there is no previous reloc (i.e. for
+            the first reloc) is <CODE>__ld_compressed_rom_calls_ref</CODE>.
+            </LI>
+        </UL></LI>
+    <LI><B>1 byte:</B> 0</LI>
+    </UL></LI>
+</UL>
+For more information on processing ROM call relocation, see
+<A HREF="$$LINK(insert_kernel_rom_calls)">__ld_insert_kernel_rom_calls</A>.

+ 8 - 0
insert_data_var_name.hss

@@ -0,0 +1,8 @@
+[Main]
+Title=__ld_insert_data_var_name
+
+[Top]
+__ld_insert_data_var_name inserts an ANSI string containing the name of the
+data variable as specified during the invocation of the linker. A terminating
+zero byte is appended; however, the name does not automatically <I>start</I>
+with a zero byte.

+ 11 - 0
insert_fargo020_bss_refs.hss

@@ -0,0 +1,11 @@
+[Main]
+Title=__ld_insert_fargo020_bss_refs
+See Also=insert_kernel_bss_refs: __ld_insert_kernel_bss_refs
+
+[Top]
+__ld_insert_fargo020_bss_refs acts like
+<A HREF="$$LINK(insert_kernel_bss_refs)">__ld_insert_kernel_bss_refs</A>,
+except that it always outputs the two terminating zero bytes, even if no
+references into the BSS section exist.
+<BR><BR>
+Fargo support must be compiled in for this insertion to be defined.

+ 34 - 0
insert_fargo020_libs.hss

@@ -0,0 +1,34 @@
+[Main]
+Title=__ld_insert_fargo020_libs
+See Also=insert_fargo021_libs: __ld_insert_fargo021_libs, insert_kernel_libs: __ld_insert_kernel_libs
+
+[Top]
+__ld_insert_fargo020_libs can be used to handle
+<A HREF="$$LINK(symbols_lib_call)">library calls</A>. It inserts references
+to libraries in the format used by Fargo v0.2.0:
+<UL>
+<LI>For each referenced library...
+    <UL>
+    <LI><B>2 bytes:</B> program-relative location of the library name</LI>
+    <LI>For each imported function/variable...
+        <UL>
+        <LI><B>2 bytes:</B> <I>index</I> of the function/variable plus 1</LI>
+        <LI>Relocation table for this function/variable:
+            <UL>
+            <LI>For each reference...
+                <UL>
+                <LI><B>2 bytes:</B> <I>location</I> (may not be 0)</LI>
+                </UL></LI>
+            <LI><B>2 bytes:</B> 0</LI>
+            </UL></LI>
+        </UL></LI>
+    <LI><B>2 bytes:</B> 0</LI>
+    </UL></LI>
+<LI><B>2 bytes:</B> 0</LI>
+</UL>
+The libraries have to be processed using the method described in
+<A HREF="$$LINK(insert_kernel_libs)">__ld_insert_kernel_libs</A>, except that
+library versions are not implemented by this format.
+<BR><BR>
+<B>Note:</B> This insertion is available only if Fargo support is compiled
+in.

+ 23 - 0
insert_fargo021_bss_refs.hss

@@ -0,0 +1,23 @@
+[Main]
+Title=__ld_insert_fargo021_bss_refs
+See Also=insert_fargo021_relocs: __ld_insert_fargo021_relocs, insert_kernel_relocs: __ld_insert_kernel_relocs
+
+[Top]
+__ld_insert_fargo021_bss_refs inserts relocs in the compressed format used by
+Fargo 0.2.1. It acts like
+<A HREF="$$LINK(insert_compressed_bss_refs)">__ld_insert_compressed_bss_refs</A>,
+except that the size of the BSS section is automatically output (as a 2-byte
+entry) in front of the actual relocation table, and that the reference symbol
+used if there is no previous reloc (i.e. for the first reloc) is
+<CODE>__ld_fargo021_bss_refs_ref</CODE>. It is expected by Fargo to be at a
+fixed position: the position of the format flag in the Fargo header. This is
+currently handled by the definition of the Fargo header.
+<BR><BR>
+For more information on inserting and processing relocs, see
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A>.
+<BR><BR>
+Fargo support must be compiled in for this insertion to be defined.
+<BR><BR>
+<B>Note:</B> The limitations of
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A> also
+apply to this insertion.

+ 47 - 0
insert_fargo021_libs.hss

@@ -0,0 +1,47 @@
+[Main]
+Title=__ld_insert_fargo021_libs
+See Also=insert_fargo020_libs: __ld_insert_fargo020_libs, insert_kernel_libs: __ld_insert_kernel_libs
+
+[Top]
+__ld_insert_fargo021_libs can be used to handle
+<A HREF="$$LINK(symbols_lib_call)">library calls</A>. It inserts references
+to libraries in the format used by Fargo v0.2.1:
+<UL>
+<LI><B>2 bytes:</B> number of referenced libraries</LI>
+<LI><B>2 bytes:</B> program-relative location of the null-separated
+    null-terminated library name list</LI>
+<LI>For each referenced library...
+    <UL>
+    <LI>For each imported function/variable...
+        <UL>
+        <LI>Compressed <I>index</I> of the function/variable. The format is
+            <I>not</I> the same as for the relocation table. It is encoded
+            using <I>one</I> of the following formats:
+            <UL>
+            <LI><B>1 byte:</B> <I>offset</I> (must be between 0x01 and
+                0x7F)</LI>
+            <LI><B>2 bytes:</B> <I>offset</I> + 0x8000 (must be between
+                0x8000 and 0xFFFF)</LI>
+            </UL>
+            where <I>offset</I> is the index plus 1 for the first index, and
+            the difference between the index and the previous index for the
+            following ones.</LI>
+        <LI>A compressed relocation table for this function/variable. See
+            <A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>
+            for the format used.
+            The reference symbol used if there is no previous reloc (i.e. for
+            the first reloc) is <CODE>__ld_fargo021_libs_ref</CODE>. It is
+            expected by Fargo to be at a fixed position: the position of the
+            format flag in the Fargo header. This is currently handled by the
+            definition of the Fargo header.</LI>
+        </UL></LI>
+    <LI><B>2 bytes:</B> 0</LI>
+    </UL></LI>
+<LI><B>2 bytes:</B> 0</LI>
+</UL>
+The libraries have to be processed using the method described in
+<A HREF="$$LINK(insert_kernel_libs)">__ld_insert_kernel_libs</A>, except that
+library versions are not implemented by this format.
+<BR><BR>
+<B>Note:</B> This insertion is available only if Fargo support is compiled
+in.

+ 21 - 0
insert_fargo021_relocs.hss

@@ -0,0 +1,21 @@
+[Main]
+Title=__ld_insert_fargo021_relocs
+See Also=insert_compressed_relocs: __ld_insert_compressed_relocs, insert_kernel_relocs: __ld_insert_kernel_relocs
+
+[Top]
+__ld_insert_fargo021_relocs inserts relocs in the compressed format used by
+Fargo 0.2.1. For more information on inserting and processing relocs, see
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A>.
+<BR><BR>
+This insertion is the same as
+<A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>,
+except that the the reference symbol used if there is no previous reloc (i.e.
+for the first reloc) is <CODE>__ld_fargo021_relocs_ref</CODE>. It is expected
+by Fargo to be at a fixed position: the position of the format flag in the
+Fargo header. This is currently handled by the definition of the Fargo header.
+<BR><BR>
+Fargo support must be compiled in for this insertion to be defined.
+<BR><BR>
+<B>Note:</B> The limitations of
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A> also
+apply to this insertion.

+ 26 - 0
insert_fargo_exports.hss

@@ -0,0 +1,26 @@
+[Main]
+Title=__ld_insert_fargo_exports
+See Also=insert_kernel_exports: __ld_insert_kernel_exports
+
+[Top]
+__ld_insert_fargo_exports can be used to export symbols from a library. It
+treats all symbols that are declared external and look like
+&quot;<I>libname</I>@<I>index</I>&quot; or
+&quot;<I>libname</I>__<I>index</I>&quot; as exported entries. <I>index</I> is
+a hexadecimal number which must have exactly 4 digits.
+<BR><BR>
+__ld_insert_fargo_exports inserts library exports in the format used by the
+Fargo II kernel:
+<UL>
+<LI>For each exported item...
+    <UL>
+    <LI><B>2 bytes:</B> <I>location</I> (offset from the beginning of the
+        library; may be 0 if nothing was specified)</LI>
+    </UL></LI>
+</UL>
+<B>Note:</B> Since exported entries are stored one after another, skipped
+entries will take up additional space in the export table. For example, if
+you only define one symbol called &quot;<I>libname</I>@0010&quot;, then there
+will be 16*2=32 bytes of zeroes in the export table.
+<BR><BR>
+This insertion is available only if Fargo support is compiled in.

+ 19 - 0
insert_kernel_bss_refs.hss

@@ -0,0 +1,19 @@
+[Main]
+Title=__ld_insert_kernel_bss_refs
+See Also=insert_kernel_data_refs: __ld_insert_kernel_data_refs, insert_kernel_relocs: __ld_insert_kernel_relocs, insert_compressed_bss_refs: __ld_insert_compressed_bss_refs
+
+[Top]
+__ld_insert_kernel_bss_refs outputs references to the BSS section in the
+format defined in
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A>. The
+only difference is that the <I>relocation address</I> is not the entry point
+of the program but the beginning of the BSS section.
+<BR><BR>
+If you insert these references, the linker assumes that the BSS section is
+handled by you; that is, you have to allocate it dynamically using
+<A HREF="$$LINK(symbols_ld_bss_size)">__ld_bss_size</A> and use a pointer to
+it as the <I>relocation address</I>.
+<BR><BR>
+<B>Note:</B> The limitations of
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A> also
+apply to this insertion.

+ 18 - 0
insert_kernel_data_refs.hss

@@ -0,0 +1,18 @@
+[Main]
+Title=__ld_insert_kernel_data_refs
+See Also=insert_kernel_bss_refs: __ld_insert_kernel_bss_refs, insert_kernel_relocs: __ld_insert_kernel_relocs, insert_compressed_data_refs: __ld_insert_compressed_data_refs
+
+[Top]
+__ld_insert_kernel_data_refs outputs references to the data section in the
+format defined in
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A>. The
+only difference is that the <I>relocation address</I> is not the entry point
+of the program but the beginning of the data section.
+<BR><BR>
+If you read the data from an external variable (see
+<A HREF="$$LINK(global_imports_auto)">__handle_data_var</A>), you have to use
+the address of the variable (or a copy) as the <I>relocation address</I>.
+<BR><BR>
+<B>Note:</B> The limitations of
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A> also
+apply to this insertion.

+ 25 - 0
insert_kernel_exports.hss

@@ -0,0 +1,25 @@
+[Main]
+Title=__ld_insert_kernel_exports
+See Also=insert_fargo_exports: __ld_insert_fargo_exports
+
+[Top]
+__ld_insert_kernel_exports can be used to export symbols from a library. It
+treats all symbols that are declared external and look like
+&quot;<I>libname</I>@<I>index</I>&quot; or
+&quot;<I>libname</I>__<I>index</I>&quot; as exported entries. <I>index</I> is
+a hexadecimal number which must have exactly 4 digits.
+<BR><BR>
+__ld_insert_kernel_exports inserts library exports in the format used by
+kernels:
+<UL>
+<LI>For each exported item...
+    <UL>
+    <LI><B>2 bytes:</B> <I>location</I> (offset from the beginning of the
+        library; may be 0 if nothing was specified)</LI>
+    </UL></LI>
+<LI><B>2 bytes:</B> 0</LI>
+</UL>
+<B>Note:</B> Since exported entries are stored one after another, skipped
+entries will take up additional space in the export table. For example, if
+you only define one symbol called &quot;<I>libname</I>@0010&quot;, then there
+will be 16*2=32 bytes of zeroes in the export table.

+ 61 - 0
insert_kernel_libs.hss

@@ -0,0 +1,61 @@
+[Main]
+Title=__ld_insert_kernel_libs
+See Also=insert_fargo020_libs: __ld_insert_fargo020_libs, insert_fargo021_libs: __ld_insert_fargo021_libs
+
+[Top]
+__ld_insert_kernel_libs can be used to handle
+<A HREF="$$LINK(symbols_lib_call)">library calls</A>. It inserts references
+to libraries in the format used by kernels:
+<UL>
+<LI>For each referenced library...
+    <UL>
+    <LI><B>8 bytes:</B> library variable name</LI>
+    <LI><B>1 byte:</B> 0</LI>
+    <LI><B>1 byte:</B> minimum version number (see
+        <A HREF="$$LINK(control_lib_min_version)">Minimum Library
+        Versions</A>)</LI>
+    </UL></LI>
+<LI>For each referenced library (again)...
+    <UL>
+    <LI><B>2 bytes:</B> number of imported functions/variables minus 1</LI>
+    <LI>For each imported function/variable...
+        <UL>
+        <LI><B>2 bytes:</B> <I>index</I> of the function/variable</LI>
+        <LI>Relocation table for this function/variable:
+            <UL>
+            <LI>For each reference...
+                <UL>
+                <LI><B>2 bytes:</B> <I>location</I> (may not be 0)</LI>
+                </UL></LI>
+            <LI><B>2 bytes:</B> 0</LI>
+            </UL></LI>
+        </UL></LI>
+    </UL></LI>
+</UL>
+If a program uses this insertion, it must process it as follows:
+<UL>
+<LI>For each library...
+    <UL>
+    <LI>Do whatever is necessary to check the version and load it into the
+        program's address space;</LI>
+    <LI>For each relocation entry...
+        <UL>
+        <LI>Get the starting address of the program (via
+            <A HREF="$$LINK(symbols_ld_entry_point)">__ld_entry_point</A>);</LI>
+        <LI>Add the <I>location</I> value;</LI>
+        <LI>Modify the 4-byte value (<I>offset</I>) at the resulting address:
+            <UL>
+            <LI>Get the address of the library function/variable indexed by
+                <I>index</I>;</LI>
+            <LI>Add the value of <I>offset</I>;</LI>
+            <LI>Write the resulting address to the 4-byte space covered by
+                <I>offset</I>.</LI>
+            </UL></LI>
+        </UL></LI>
+    </UL></LI>
+</UL>
+Before program termination, this process has to be reverted, so that it can
+be repeated the next time the program starts. Since programs and libraries
+may be moved in memory while they are not executed, they may <I>not</I>
+simply deactivate the relocation code. This would also prevent programs from
+being transferred between devices.

+ 69 - 0
insert_kernel_ram_calls.hss

@@ -0,0 +1,69 @@
+[Main]
+Title=__ld_insert_kernel_ram_calls
+
+[Top]
+__ld_insert_kernel_ram_calls can be used to handle
+<A HREF="$$LINK(symbols_ram_call)">RAM calls</A>. It inserts references to
+RAM calls in the format used by kernels:
+<UL>
+<LI>If the program uses at least one RAM call...
+    <UL>
+    <LI><B>2 bytes:</B> the number of different RAM calls minus 1</LI>
+    <LI>For each RAM call...
+        <UL>
+        <LI><B>2 bytes:</B> RAM call information:
+            <UL>
+            <LI>Bits 0 through 13: <I>index</I></LI>
+            <LI>Bit 14: <I>type</I>
+                (0: <A HREF="$$LINK(symbols_ram_call)">RAM call</A>;
+                 1: <A HREF="$$LINK(symbols_extra_ram_addr)">extra RAM
+                    address</A>)</LI>
+            <LI>Bit 15: <I>size</I> (0: 4 bytes; 1: 2 bytes)</LI>
+            </UL></LI>
+        <LI>Relocation table for this RAM call:
+            <UL>
+            <LI>For each reference...
+                <UL>
+                <LI><B>2 bytes:</B> <I>location</I> (may not be 0)</LI>
+                </UL></LI>
+            <LI><B>2 bytes:</B> 0</LI>
+            </UL></LI>
+        </UL></LI>
+    </UL></LI>
+</UL>
+If a program uses this insertion, it must process it as follows:
+<UL>
+<LI>For each RAM call...
+    <UL>
+    <LI>For each relocation entry...
+        <UL>
+        <LI>Get the starting address of the program (via
+            <A HREF="$$LINK(symbols_ld_entry_point)">__ld_entry_point</A>);</LI>
+        <LI>Add the <I>location</I> value;</LI>
+        <LI>Modify the value (<I>offset</I>) at the resulting address (2 or
+            4 bytes depending on <I>size</I>):
+            <UL>
+            <LI>If <I>type</I> indicates an extra RAM address:
+                <UL>
+                <LI>Determine the location of the extra RAM table row indexed
+                    by <I>index</I> (see
+                    <A HREF="$$LINK(symbols_extraram)">_extraram</A>);</LI>
+                <LI>Get the correct value for the current calculator from
+                    this row;</LI>
+                </UL>
+                Else:
+                <UL>
+                <LI>Get the address/value of the RAM function/variable
+                    indexed by <I>index</I>;</LI>
+                </UL></LI>
+            <LI>Add the value of <I>offset</I>;</LI>
+            <LI>Write the resulting address/value to the space covered by
+                <I>offset</I>.</LI>
+            </UL></LI>
+        </UL></LI>
+    </UL></LI>
+</UL>
+Before program termination, this process has to be reverted, so that it can
+be repeated the next time the program starts. Simply deactivating the
+relocation code would prevent programs from being transferred between
+devices.

+ 59 - 0
insert_kernel_relocs.hss

@@ -0,0 +1,59 @@
+[Main]
+Title=__ld_insert_kernel_relocs
+See Also=insert_kernel_bss_refs: __ld_insert_kernel_bss_refs, insert_kernel_data_refs: __ld_insert_kernel_data_refs, insert_compressed_relocs: __ld_insert_compressed_relocs
+
+[Top]
+Relocation entries indicate that the program needs to know some addresses
+which are only available at run time. In this case, the addresses referred
+to are locations inside the program code or data. Usually, all references to
+absolute addresses inside the program are inserted into the section if one
+of these two insertions is used; however, sections may be marked as being
+handled in another way, which prevents relocation entries to them from being
+output in this way. The data section is automatically marked as handled if
+it is externalized; the BSS section is marked as handled by referencing
+<A HREF="$$LINK(symbols_ld_kernel_bss_table)">__ld_kernel_bss_table</A>, by
+using
+<A HREF="$$LINK(insert_kernel_bss_refs)">__ld_insert_kernel_bss_refs</A>
+before inserting the relocation entries, or by reacting to the
+<A HREF="$$LINK(global_imports_auto)">__handle_bss</A> global import.
+<BR><BR>
+__ld_insert_kernel_relocs uses the kernel format for storing relocation
+entries, which is used by kernels on the TI-89, TI-92 Plus, and V200, and by
+Fargo v0.2.0:
+<UL>
+<LI>For each relocation entry...
+    <UL>
+    <LI><B>2 bytes:</B> <I>location</I> (may not be 0)</LI>
+    </UL></LI>
+<LI><B>2 bytes:</B> 0</LI>
+</UL>
+If a program uses this insertion, it must process it as follows:
+<UL>
+<LI>For each relocation entry...
+    <UL>
+    <LI>Get the starting address of the program (via
+        <A HREF="$$LINK(symbols_ld_entry_point)">__ld_entry_point</A>);</LI>
+    <LI>Add the <I>location</I> value;</LI>
+    <LI>Modify the 4-byte value (<I>offset</I>) at the resulting address:
+        <UL>
+        <LI>Get the starting address of the program (<I>relocation
+            address</I>);</LI>
+        <LI>Add the value of <I>offset</I>;</LI>
+        <LI>Write the resulting address to the 4-byte space covered by
+            <I>offset</I>.</LI>
+        </UL></LI>
+    </UL></LI>
+</UL>
+Before program termination, this process has to be reverted, so that it can
+be repeated the next time the program starts. Since programs may be moved in
+memory while they are not executed, they may <I>not</I> simply deactivate
+the relocation code. This would also prevent programs from being transferred
+between devices.
+<BR><BR>
+<B>Note:</B> Relocation entries may only be inserted at a single place in the
+program. The reason for this is that the linker may have to add new
+relocation entries after they have been written into the section. Instead of
+keeping track of which entries have already been processed, we thought it
+would be easier to remove them once they have been written into a section.
+Also, it is dangerous to use this insertion from anything other than a
+startup section.

+ 50 - 0
insert_kernel_rom_calls.hss

@@ -0,0 +1,50 @@
+[Main]
+Title=__ld_insert_kernel_rom_calls
+See Also=insert_compressed_rom_calls: __ld_insert_compressed_rom_calls
+
+[Top]
+__ld_insert_kernel_rom_calls can be used to handle
+<A HREF="$$LINK(symbols_rom_call)">ROM calls</A>. It inserts references to
+ROM calls in the format used by kernels:
+<UL>
+<LI>If the program uses at least one ROM call...
+    <UL>
+    <LI><B>2 bytes:</B> the number of different ROM calls minus 1</LI>
+    <LI>For each ROM call...
+        <UL>
+        <LI><B>2 bytes:</B> <I>index</I> of the ROM call</LI>
+        <LI>Relocation table for this ROM call:
+            <UL>
+            <LI>For each reference...
+                <UL>
+                <LI><B>2 bytes:</B> <I>location</I> (may not be 0)</LI>
+                </UL></LI>
+            <LI><B>2 bytes:</B> 0</LI>
+            </UL></LI>
+        </UL></LI>
+    </UL></LI>
+</UL>
+If a program uses this insertion, it must process it as follows:
+<UL>
+<LI>For each ROM call...
+    <UL>
+    <LI>For each relocation entry...
+        <UL>
+        <LI>Get the starting address of the program (via
+            <A HREF="$$LINK(symbols_ld_entry_point)">__ld_entry_point</A>);</LI>
+        <LI>Add the <I>location</I> value;</LI>
+        <LI>Modify the 4-byte value (<I>offset</I>) at the resulting address:
+            <UL>
+            <LI>Get the address of the ROM function/variable indexed by
+                <I>index</I>;</LI>
+            <LI>Add the value of <I>offset</I>;</LI>
+            <LI>Write the resulting address to the 4-byte space covered by
+                <I>offset</I>.</LI>
+            </UL></LI>
+        </UL></LI>
+    </UL></LI>
+</UL>
+Before program termination, this process has to be reverted, so that it can
+be repeated the next time the program starts. Simply deactivating the
+relocation code would prevent programs from being transferred between
+devices.

+ 21 - 0
insert_nostub_comments.hss

@@ -0,0 +1,21 @@
+[Main]
+Title=__ld_insert_nostub_comments
+Index=_nostub_data__????, NoStub Data Exports, NoStub Comments
+
+[Top]
+__ld_insert_nostub_comments is used to export data symbols in the NoStub
+comment header. It treats all symbols that are declared external and look
+like &quot;_nostub_data__<I>index</I>&quot; as exported entries.
+<I>index</I> is a hexadecimal number which must have exactly 4 digits.
+<BR><BR>
+__ld_insert_nostub_comments inserts data exports in the format used by
+the NoStub comment specification:
+<UL>
+<LI>For each exported item (in ascending ID order)...
+    <UL>
+    <LI><B>2 bytes:</B> <I>export ID</I> (type index of the export, as
+        specified after the double underscore)</LI>
+    <LI><B>2 bytes:</B> <I>location</I> (offset from the beginning of the
+        program)</LI>
+    </UL></LI>
+</UL>

+ 92 - 0
insert_preos_compressed_tables.hss

@@ -0,0 +1,92 @@
+[Main]
+Title=__ld_insert_preos_compressed_tables
+See Also=insert_compressed_relocs: __ld_insert_compressed_relocs, insert_compressed_rom_calls: __ld_insert_compressed_rom_calls, insert_kernel_ram_calls: __ld_insert_kernel_ram_calls, insert_compressed_bss_refs: __ld_insert_compressed_bss_refs
+
+[Top]
+__ld_insert_preos_compressed_tables is the most complex of the automatic
+insertions. It inserts all relocation-related tables in the compressed format
+expected by PreOs 0.68 or higher. PreOs expects those tables to be pointed to
+by the same pointer, so they need to be inserted all at once. The reference
+address expected by PreOs is the same for all relocation tables: 36 (0x24).
+It is defined as the end address of the smallest possible header/stub
+combination. (However, the smallest possible stub is not usable in practice
+because it does not emit <I>any</I> error messages. Therefore, the address
+does not correspond to any actual address in TIGCCLIB, so it is hard-coded in
+the linker.) The tables it inserts are, in order:
+<UL>
+<LI><B>Library import table</B>:
+    <UL>
+    <LI>For each referenced library...
+        <UL>
+        <LI><B>8 bytes:</B> library variable name</LI>
+        <LI><B>1 byte:</B> 0</LI>
+        <LI><B>1 byte:</B> minimum version number (see
+            <A HREF="$$LINK(control_lib_min_version)">Minimum Library
+            Versions</A>)</LI>
+        </UL></LI>
+    <LI>For each referenced library (again)...
+        <UL>
+        <LI><B>PreOs index</B> (see below): number of imported
+            functions/variables minus 1</LI>
+        <LI>For each imported function/variable...
+            <UL>
+            <LI><B>PreOs index</B> (see below): <I>index</I> of the
+                function/variable (relative to the previous one)</LI>
+            <LI>Relocation table for this function/variable. See
+                <A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>
+                for the format used.</LI>
+            </UL></LI>
+        </UL></LI>
+    </UL></LI>
+<LI><B>ROM call import table</B>:
+    <UL>
+    <LI><B>PreOs index</B> (see below): the number of different ROM calls
+        minus 1</LI>
+    <LI>For each ROM call...
+        <UL>
+        <LI><B>PreOs index</B> (see below): <I>index</I> of the ROM
+            call (relative to the previous one)</LI>
+        <LI>A compressed relocation table for this ROM call. See
+            <A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>
+            for the format used.</LI>
+        </UL></LI>
+    </UL></LI>
+<LI><B>RAM call import table</B>, in the same format as the ROM call import
+    table. The indices used are the indices <I>after</I> setting the
+    <I>size</I> and <I>type</I> flags described under
+    <A HREF="$$LINK(insert_kernel_ram_calls)">__ld_insert_kernel_ram_calls</A>.</LI>
+<LI><B>Relocation table</B>: See
+    <A HREF="$$LINK(insert_compressed_relocs)">__ld_insert_compressed_relocs</A>
+    for the format used.</LI>
+<LI><B>BSS relocation table</B>:
+    <UL>
+        <LI><B>2 bytes:</B> <I>BSS size</I> / 4</LI>
+        <LI>A compressed relocation table. See
+            <A HREF="$$LINK(insert_compressed_bss_refs)">__ld_insert_compressed_bss_refs</A>
+            for the format used.</LI>
+    </UL></LI>
+</UL>
+PreOs uses a special format for the indices. It is <I>not</I> the same as for
+the relocation table. Instead, a <B>PreOs index</B> is encoded using
+<I>one</I> of the following formats:
+<UL>
+<LI><B>1 byte:</B> <I>offset</I> (must be between 0x00 and 0xFD)</LI>
+<LI><B>2 bytes:</B>
+    <UL>
+    <LI><B>1 byte:</B> 0xFE</LI>
+    <LI><B>1 byte:</B> <I>offset</I> - 0xFE</LI>
+    </UL></LI>
+<LI><B>3 bytes:</B>
+    <UL>
+    <LI><B>1 byte:</B> 0xFF</LI>
+    <LI><B>2 bytes:</B> <I>index</I> (not <I>offset</I>!)</LI>
+    </UL></LI>
+</UL>
+where <I>index</I> is the actual index, and <I>offset</I> is <I>index</I> + 1
+for the first index and the difference between <I>index</I> and the previous
+index for the following ones.
+<BR><BR>
+<B>Note:</B> Since parts of this insertion are dealing with relocs, the
+limitations of
+<A HREF="$$LINK(insert_kernel_relocs)">__ld_insert_kernel_relocs</A> also
+apply to this insertion.

+ 14 - 0
invocation.hss

@@ -0,0 +1,14 @@
+[Main]
+Title=Invoking ld-tigcc and ar-tigcc
+Subsections=invocation_ld, invocation_ar
+
+[Top]
+The TIGCC linker is available in two forms: As a standalone command line
+program or as a dynamic link library (DLL). TIGCC uses the DLL version for
+improved speed and to avoid maintainance problems, but experienced
+programmers might want to use the command line version in some cases because
+it is a little more advanced.
+<BR><BR>
+In the <A HREF="$$INFOLINK(ide)">IDE</A>, linker options can be set in the
+project settings. The <CODE>tigcc</CODE> command line compiler accepts most
+of the options of <CODE>ld-tigcc</CODE> and passes them to the linker.

+ 54 - 0
invocation_ar.hss

@@ -0,0 +1,54 @@
+[Main]
+Title=ar-tigcc Command-Line Options
+
+[Top]
+The <CODE>ar-tigcc</CODE> tool can be used to create archives recognized by
+<CODE>ld-tigcc</CODE>. The output format is the format used by
+<A HREF="http://www.gnu.org/">GNU</A> <CODE>ar</CODE>, for which this tool is
+a replacement. This allows for maximum compatibility between archives and
+programs created with different versions of TIGCC.
+<BR><BR>
+In <CODE>ar-tigcc</CODE>, options and input files may appear in any order in
+the command line. Input files can have any file format; they are simply
+written into the archive in the order specified in the command line. However,
+object files whose format is recognized are searched for exported symbols, so
+that <CODE>ar-tigcc</CODE> can create a symbol table for the archive.
+<BR><BR>
+If no output file name is specified, <CODE>ar-tigcc</CODE> uses the name of
+the first input file and appends a <CODE>'.a'</CODE> extension to it. It is
+highly recommended that you specify a different name with the
+<CODE>'--output'</CODE> option.
+<BR><BR>
+<CODE>ar-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>--dump</B>
+<DD>Display a small dump of the archive file contents. This includes the
+members as well as the symbols they export.
+<BR><BR>
+<DT><B>-o <I>file</I></B>
+<BR><B>--output <I>file</I></B>
+<BR><B>-rc <I>file</I></B>
+<BR><B>-qc <I>file</I></B>
+<DD>Write the output to the file named <I>file</I>. Unlike
+<CODE>ld-tigcc</CODE>, <CODE>ar-tigcc</CODE> does not append a file extension
+to <I>file</I>. <B>'-rc'</B> and <B>'-qc'</B> are recognized for
+compatibility with GNU <CODE>ar</CODE>, so that certain command lines work
+with GNU <CODE>ar</CODE> as well as <CODE>ar-tigcc</CODE>.
+<BR><BR>
+<DT><B>--no-names</B>
+<DD>Omit the file names of the input files in the archive. The archive will
+only contain names of the form <CODE>fl<I>n</I>.o</CODE>, where <I>n</I> is
+the index of the file starting at 1. Omitting file names may be a good idea,
+especially if you use long file names, since the traditional archive format
+imposes a maximum of 15 characters on the length of file names. Otherwise, if
+a file name exceeds this maximum, it will be cut off at the 16th character.
+The IDE and the <CODE>tigcc</CODE> command line compiler always use this
+option.
+</DL>

+ 210 - 0
invocation_ld.hss

@@ -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>

+ 9 - 0
ld.hss

@@ -0,0 +1,9 @@
+[Main]
+Title=The TIGCC Linker
+Subsections=operation, invocation, modes, formats, control, startup, global_imports, symbols, insert, bincode, dump, compiling
+
+[Top]
+This is the documentation of the TIGCC linker, the tool that reads the
+compiled and assembled files and merges them into a single program. Most
+parts of this documentation only need to be read by experts; you may safely
+skip over all parts that you do not understand.

+ 18 - 0
modes.hss

@@ -0,0 +1,18 @@
+[Main]
+Title=Linking Modes of the TIGCC Linker
+Subsections=modes_native, modes_nostub, modes_nostub_dll, modes_kernel, modes_fargo, modes_flash_os
+
+[Top]
+A <U>linking mode</U> defines how the linker treats the contents of the
+program after they have been read from the object files. The TIGCC linker has
+several different modes; some of them are related to specific output file
+formats, and some of them are present only for historical reasons.
+
+[Bottom]
+The recommended mode for normal TIGCC programs is
+<A HREF="$$LINK(modes_native)">TIGCC-native mode</A>. It is the simplest
+mode; the program is basically an empty sheet of paper, which can be filled
+with code of all sorts. The default mode is actually
+<A HREF="$$LINK(modes_kernel)">kernel mode</A> unless you set the appropriate
+<A HREF="$$LINK(invocation_ld)">command-line option</A>, to make existing
+programs work without modifications.

+ 18 - 0
modes_fargo.hss

@@ -0,0 +1,18 @@
+[Main]
+Title=Fargo II Linking Mode
+
+[Top]
+This mode is used to create a program that can be run on a TI-92 with Fargo
+II installed. It can be turned on using the <B>'--fargo'</B>
+<A HREF="$$LINK(invocation_ld)">command-line option</A> or the
+<A HREF="$$LINK(control_fargo)">_fargo</A> control symbol. It uses the Fargo
+II output <A HREF="$$LINK(formats)">format</A>, which is binary data wrapped
+in an empty TI-BASIC program. It creates a
+<A HREF="$$LINK(global_imports)">global import</A> asking for the appropriate
+Fargo II header (see <A HREF="$$LINK(global_imports_auto)">Automatically
+Created Global Imports</A> for more information). And it also causes the
+value of <A HREF="$$LINK(symbols_ld_entry_point)">__ld_entry_point</A> to be
+decreased by two, to point to the two size bytes in the TIOS file format
+rather than the beginning of the program data.
+<BR><BR>
+<B>Note:</B> Fargo support must be compiled in for this mode to be available.

+ 24 - 0
modes_flash_os.hss

@@ -0,0 +1,24 @@
+[Main]
+Title=Flash OS Linking Mode
+
+[Top]
+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.) It can be turned on using the
+<B>'--flash-os'</B> <A HREF="$$LINK(invocation_ld)">command-line option</A>
+or the <A HREF="$$LINK(control_flash_os)">_flash_os</A> control symbol. It
+currently supports only the raw TIB output format, which is enabled by the
+<B>'--outputbin'</B> <A HREF="$$LINK(invocation_ld)">option</A>. Support for
+the current 89u/9xu/v2u format is planned and will be the default. It creates
+a <A HREF="$$LINK(global_imports)">global import</A> asking for the
+appropriate Flash OS header (see
+<A HREF="$$LINK(global_imports_auto)">Automatically Created Global Imports</A>
+for more information). Since Flash operating systems are composed of 2
+discontiguous parts, a small (24 KB) startup segment and a large (1944 KB for
+2 MB FlashROMs, 3992 KB for 4 MB FlashROMs) main segment,
+<A HREF="$$LINK(startup)">startup sections</A> are handled in a special way
+in this mode: Startup sections are placed into the startup segment, all other
+sections are merged into the main segment.
+<BR><BR>
+<B>Note:</B> Flash OS support must be compiled in for this mode to be
+available.

+ 9 - 0
modes_kernel.hss

@@ -0,0 +1,9 @@
+[Main]
+Title=Kernel Linking Mode
+
+[Top]
+In this mode, which is enabled by default, the linker acts the same way as in
+<A HREF="$$LINK(modes_native)">TIGCC-native mode</A>, but it creates a
+<A HREF="$$LINK(global_imports)">global import</A> asking for the appropriate
+kernel format header. See <A HREF="$$LINK(global_imports_auto)">Automatically
+Created Global Imports</A> for more information.

+ 27 - 0
modes_native.hss

@@ -0,0 +1,27 @@
+[Main]
+Title=TIGCC-Native Linking Mode
+
+[Top]
+This mode (which can be enabled using the <B>'--native'</B>
+<A HREF="$$LINK(invocation_ld)">command-line option</A> or the control symbol
+<A HREF="$$LINK(control_tigcc_native)">_tigcc_native</A>) is the
+recommended mode for all new programs. When operating in this mode, the TIGCC
+linker does not process the program in any special way, except that it
+requires the definition of at least one startup section. The idea is that
+stub code should not be handled by the linker itself but rather included
+manually by the program as needed. However, every program (regardless of the
+architecture and operating system) needs to have a prolog that either
+contains the location of the main entry point or is itself the startup code
+of the program. On the TI platforms with official assembly program support,
+execution always starts at the beginning of the program, so the prolog is
+actually the startup code.
+<BR><BR>
+Ideally, every program should be able to use this mode. However, at the
+moment, the output file format cannot be specified other than by switching to
+the appropriate mode. If you want to use a different output file format than
+the default TIOS format (i.e. Nostub DLL or Fargo II), you cannot use
+TIGCC-native mode. At the moment, adding support for explicit selection of
+the output file format does not have any particular benefit, since it does
+not permit the removal of any of the other modes. However, as soon as the
+need for another output format (e.g. raw) arises, there should be a
+command-line option to select the format.

+ 19 - 0
modes_nostub.hss

@@ -0,0 +1,19 @@
+[Main]
+Title=Nostub Linking Mode
+
+[Top]
+If this mode is activated using the
+<A HREF="$$LINK(control_nostub)">_nostub</A> control symbol, execution will
+start at the very beginning of the program. The exact entry point depends on
+the order of the object files as passed to the linker as well as the order of
+the sections inside an object file. Because of this insecurity, this mode
+should never be used in new programs. Programs written in assembly should
+define a small <A HREF="$$LINK(startup)">startup section</A> including a jump
+to the actual main function and use
+<A HREF="$$LINK(modes_native)">TIGCC-native mode</A> instead. If the main
+function follows immediately, the jump can even be optimized away by the
+linker.
+<BR><BR>
+If a startup section is defined in nostub mode, the linker emits a warning
+and switches to <A HREF="$$LINK(modes_native)">TIGCC-native mode</A>. This
+ensures that nostub mode really means that no stub is added to the program.

+ 12 - 0
modes_nostub_dll.hss

@@ -0,0 +1,12 @@
+[Main]
+Title=Nostub DLL Linking Mode
+
+[Top]
+If the linker is told to use Nostub DLL mode using the
+<A HREF="$$LINK(control_nostub_dll)">__nostub_dll</A> control symbol, it acts
+like in <A HREF="$$LINK(modes_native)">TIGCC-native mode</A>, except that it
+causes the linker to use the Nostub DLL output
+<A HREF="$$LINK(formats)">format</A> instead of the default output format.
+Since the stub for nostub DLLs is defined as conventional C code rather than
+imported as a startup section, this mode does not require the definition of a
+startup section.

+ 36 - 0
operation.hss

@@ -0,0 +1,36 @@
+[Main]
+Title=TIGCC Linker Purpose and Operation
+
+[Top]
+The purpose of a linker is to take executable code and data from different
+files and merge it into a single program. It must resolve dependencies
+between the files, and there are many architecture-dependent features linkers
+are required to support. The complicated part about linking is that binary
+code can be encapsulated in different formats; most linkers, including the
+TIGCC linker, can import code from several formats and export it to yet
+another one (see <A HREF="$$LINK(formats)">TIGCC Linker File Formats</A>).
+<BR><BR>
+The TIGCC linker can handle two kinds of files: object files and archive
+files. Object files are produced by the compiler or assembler. They contain
+the code and global variables of the program; all object files passed to the
+linker are processed and then included in the final output. Archive files,
+also known as static libraries, are collections of object files. An archive
+member is included only if this is requested by another file.
+<BR><BR>
+Files can reference each other via text strings called <U>symbols</U>. These
+symbols are usually labels in assembly code, or functions and global
+variables in C code. The most popular way of referencing symbols is to ask
+that the final address or offset of a specific symbol be inserted at or added
+to a specific location in the code. This is called <U>relocation</U>.
+<BR><BR>
+When the linker is executed, it first reads all object files passed to it and
+imports their contents into its internal data structures. Then it tries to
+resolve the references to symbols defined in another file. If a symbol cannot
+be resolved, it is looked up in the symbol tables of all archive files passed
+to the linker; if it is still not found, this is an error. Archive members
+are imported immediately if required, and they may reference symbols defined
+in other files as well. Some special actions are performed based on the
+contents of the imported files, code and data blocks (<U>sections</U>) are
+sorted and merged if required, and offsets between different locations in the
+code are inserted whereever the object files requested this. Finally, the
+program is exported to an executable file.

+ 55 - 0
startup.hss

@@ -0,0 +1,55 @@
+[Main]
+Title=Startup Sections
+Index=_st..., _stl...
+
+[Top]
+The concept of <U>startup sections</U> is unique to the TIGCC linker. It only
+makes sense in low-resource environments like calculators. The idea is that a
+file that is imported should be able to specify that it needs certain code to
+be executed at the beginning of the program. Usually, there are two
+approaches to address this situation: constructors and main function
+wrappers.
+<BR><BR>
+If constructors are used to handle this, a lot of memory is wasted: A
+constructor table needs to be created with appropriate code to handle its
+contents; every item needs to save all registers except a few, and sharing
+data between two constructors requires global variables. Moreover, using
+constructors, it is not possible to specify the order in which startup code
+is to be called; however, parts of the startup code often need to rely on
+other parts to be executed first.
+<BR><BR>
+Main function wrappers appear in almost every environment. But since these
+wrappers are fixed, they need to handle all startup code that might possibly
+be needed, instead of letting each file choose its own startup code. For
+example, such fixed startup code would need to handle exceptions even if the
+program never generates them, or fill certain global variables that are never
+read.
+<BR><BR>
+Startup sections are actually a wrapper around the main function, but they
+can achieve even more flexibility than constructors: They are numbered and
+executed in the exact order specified by the numbers, and no extra code is
+executed between two consecutive startup sections, so registers can be used
+to pass data between two sections.
+<BR><BR>
+Startup sections can be used not only to insert code at the beginning of the
+program, but also to generate the required headers for certain file formats.
+Sometimes this is easier than writing the linker code to insert the required
+headers (see <A HREF="$$LINK(formats)">TIGCC Linker File Formats</A>).
+<BR><BR>
+Since libraries may need to contain a header, some stub code that is called
+when the user tries to execute the library, and possibly some startup code,
+they may also have startup sections. However, it does not really make sense
+to include a startup section designed for a program in a library. Therefore,
+there are library startup sections, which may appear in both libraries and
+programs, and program startup sections, which may appear only in programs.
+Library startup sections are always included <I>before</I> program startup
+sections.
+<BR><BR>
+Startup sections are detected based on their name. To declare a program
+startup section, name the section <CODE>_st<I>n</I></CODE>, where <I>n</I> is
+a value from 1 to 99999 (higher values for <I>n</I> may be accepted if the
+object file format supports section names longer than 8 characters, but it is
+not recommended to use them). To declare a library startup section, name it
+<CODE>_stl<I>n</I></CODE>, where <I>n</I> is a value from 1 to 9999 (higher
+values are not permitted). Startup sections are included in ascending order;
+if two startup sections use the same index, their order is undefined.

File diff suppressed because it is too large
+ 2 - 0
symbols.hss


+ 13 - 0
symbols_comment.hss

@@ -0,0 +1,13 @@
+[Main]
+Title=_comment
+
+[Top]
+Usually, this symbol is not handled in a special way. However, if it does
+not exist at all, it is redirected to the entry point of the program. The
+effect is that constructs of the form
+<PRE>.word _comment-<I>entry_point</I>
+</PRE>
+resolve to 0 if the symbol is undefined.
+<BR><BR>
+The kernel headers reference this symbol as the comment string of the
+program. If it exists, it must be a zero-terminated ASCII string.

+ 14 - 0
symbols_exit.hss

@@ -0,0 +1,14 @@
+[Main]
+Title=_exit
+
+[Top]
+Usually, this symbol is not handled in a special way. However, if it does
+not exist at all, it is redirected to the entry point of the program. The
+effect is that constructs of the form
+<PRE>.word _exit-<I>entry_point</I>
+</PRE>
+resolve to 0 if the symbol is undefined.
+<BR><BR>
+The kernel headers of the standard library reference this symbol as the
+program/library destructor. For kernel programs and libraries, it is called
+whenever the program exits or the library is unloaded.

+ 20 - 0
symbols_extra_ram_addr.hss

@@ -0,0 +1,20 @@
+[Main]
+Title=_extraramaddr@..., _extraramaddr__...
+Index=_extraramaddr@..., _extraramaddr__...
+See Also=symbols_extraram: _extraram, symbols_ram_call: _RAM_CALL...
+
+[Top]
+_extraramaddr@<I>index</I> and _extraramaddr__<I>index</I> are treated as
+references to an extra RAM address with the index <I>index</I> interpreted as
+a hexadecimal value. <I>index</I> is an index into the extra RAM table
+defined by the program (using the
+<A HREF="$$LINK(symbols_extraram)">_extraram</A> symbol). The value which
+__extraramaddr... symbols are resolved to is either the TI-89 or the
+TI-92(+)/V200 value of the table row specified by <I>index</I>.
+<BR><BR>
+Internally, extra RAM addresses are stored as RAM calls and treated the same
+way.
+<A HREF="$$LINK(insert_kernel_ram_calls)">__ld_insert_kernel_ram_calls</A>
+and <A HREF="$$LINK(insert_preos_compressed_tables)">
+__ld_insert_preos_compressed_tables</A> output RAM calls and extra RAM
+addresses similarly to each other.

+ 24 - 0
symbols_extraram.hss

@@ -0,0 +1,24 @@
+[Main]
+Title=_extraram
+See Also=symbols_extra_ram_addr: Extra RAM Addresses
+
+[Top]
+Usually, this symbol is not handled in a special way. However, if it does
+not exist at all, it is redirected to the entry point of the program. The
+effect is that constructs of the form
+<PRE>.word _extraram-<I>entry_point</I>
+</PRE>
+resolve to 0 if the symbol is undefined.
+<BR><BR>
+The kernel headers of the standard library reference this symbol as an extra
+RAM table. The table is organized in pairs of 16 bit values. Of each pair,
+the first value is relevant for the TI-89, and the second value is relevant
+for the TI-92(+)/V200 calculator family. In C, you would define an extra RAM
+table like this:
+<PRE>struct {
+  short value89, value9x;
+} _extraram[] = {{v1_89, v1_9x}, {v2_89, v2_9x}, ...};
+</PRE>
+However, extra RAM tables are barely usable in C: The compiler does not
+support using external symbols as immediate values, except if you take their
+address.

+ 8 - 0
symbols_ld_bss_end.hss

@@ -0,0 +1,8 @@
+[Main]
+Title=__ld_bss_end
+See Also=symbols_ld_bss_start: __ld_bss_start, symbols_ld_bss_size: __ld_bss_size
+
+[Top]
+This built-in symbol represents the end of the BSS section. It points to the
+location behind the last item in the section. If the program does not contain
+a BSS section, an error is reported.

+ 10 - 0
symbols_ld_bss_ref_count.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=__ld_bss_ref_count
+See Also=insert_kernel_bss_refs: __ld_insert_kernel_bss_refs, insert_compressed_bss_refs: __ld_compressed_bss_refs, insert_fargo021_bss_refs: __ld_fargo021_bss_refs, insert_preos_compressed_tables: __ld_insert_preos_compressed_tables
+
+[Top]
+This built-in symbol represents the number of references to the BSS section.
+If the program does not contain a BSS section, it resolves to a value of 0.
+If the BSS section is merged with the other sections, the references counted
+by this symbol and the references counted by
+<A HREF="$$LINK(symbols_ld_reloc_count)">__ld_reloc_count</A> will overlap.

+ 7 - 0
symbols_ld_bss_size.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=__ld_bss_size
+See Also=symbols_ld_bss_start: __ld_bss_start, symbols_ld_bss_end: __ld_bss_end
+
+[Top]
+This built-in symbol represents the size of the BSS section in bytes. If the
+program does not contain a BSS section, the symbol resolves to the value 0.

+ 7 - 0
symbols_ld_bss_start.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=__ld_bss_start
+See Also=symbols_ld_bss_end: __ld_bss_end, symbols_ld_bss_size: __ld_bss_size
+
+[Top]
+This built-in symbol represents the starting address of the BSS section. If
+the program does not contain a BSS section, an error is reported.

+ 23 - 0
symbols_ld_calc_const.hss

@@ -0,0 +1,23 @@
+[Main]
+Title=__ld_calc_const_...
+
+[Top]
+__ld_calc_const_<I>constants</I>, where <I>constants</I> is an
+underscore-separated list of positive integer values in decimal or
+hexadecimal notation (prefixed with <CODE>0x</CODE>), resolves to one of the
+values in <I>constants</I>. The actual value depends on the calculator
+belonging to the file that is generated. This feature adds the possibility to
+compile a program for multiple calculators at once and still generate
+different files for each calculator.
+<BR><BR>
+The order of the calculator-specific values in <I>constants</I> is as
+follows:
+<OL>
+<LI>TI-92</LI>
+<LI>TI-89</LI>
+<LI>TI-92 Plus</LI>
+<LI>V200</LI>
+</OL>
+Values for calculators which the linker is currently not generating any
+output file for may be omitted. If a significant value is omitted, the value
+is assumed to be zero, and a warning is emitted.

+ 10 - 0
symbols_ld_constructor_count.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=__ld_constructor_count
+See Also=symbols_ld_constructors_start: __ld_constructors_start, symbols_ld_constructors_end: __ld_constructors_end, symbols_ld_constructors_size: __ld_constructors_size, symbols_ld_destructor_count: __ld_destructor_count
+
+[Top]
+This built-in symbol represents the number of constructors the program uses.
+If no constructors are used, it resolves to a value of 0. The value equals
+the value of
+<A HREF="$$LINK(symbols_ld_constructors_size)">__ld_constructors_size</A>
+divided by the size of a pointer, which is 4.

+ 9 - 0
symbols_ld_constructors_end.hss

@@ -0,0 +1,9 @@
+[Main]
+Title=__ld_constructors_end
+See Also=symbols_ld_constructors_start: __ld_constructors_start, symbols_ld_constructors_size: __ld_constructors_size, symbols_ld_constructor_count: __ld_constructor_count
+
+[Top]
+This built-in symbol represents the end of the constructor section of the
+program. A constructor section contains an array of pointers to functions,
+all of which do not take any parameters. These functions are to be executed
+at program startup. If no constructors are used, an error is reported.

+ 11 - 0
symbols_ld_constructors_size.hss

@@ -0,0 +1,11 @@
+[Main]
+Title=__ld_constructors_size
+See Also=symbols_ld_constructors_start: __ld_constructors_start, symbols_ld_constructors_end: __ld_constructors_end, symbols_ld_constructor_count: __ld_constructor_count
+
+[Top]
+This built-in symbol represents the size of the constructor section of the
+program. A constructor section contains an array of pointers to functions,
+all of which do not take any parameters. If no constructors are used, the
+symbol resolves to a value of 0. The value equals the value of
+<A HREF="$$LINK(symbols_ld_constructor_count)">__ld_constructor_count</A>
+multiplied by the size of a pointer, which is 4.

+ 10 - 0
symbols_ld_constructors_start.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=__ld_constructors_start
+See Also=symbols_ld_constructors_end: __ld_constructors_end, symbols_ld_constructors_size: __ld_constructors_size, symbols_ld_constructor_count: __ld_constructor_count, symbols_ld_destructors_start: __ld_destructors_start
+
+[Top]
+This built-in symbol represents the beginning of the constructor section of
+the program. A constructor section contains an array of pointers to
+functions, all of which do not take any parameters. These functions are to be
+executed at program startup. If no constructors are used, an error is
+reported.

+ 10 - 0
symbols_ld_data_end.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=__ld_data_end
+See Also=symbols_ld_data_start: __ld_data_start, symbols_ld_data_size: __ld_data_size
+
+[Top]
+This built-in symbol represents the end of the data section, if the program
+does not mix text and data (for example if the data is written into an
+external file). It points to the location behind the last item in the
+section. If the program does not contain an explicit data section, an error
+is reported.

+ 12 - 0
symbols_ld_data_ref_count.hss

@@ -0,0 +1,12 @@
+[Main]
+Title=__ld_data_ref_count
+See Also=insert_kernel_data_refs: __ld_insert_kernel_data_refs, insert_compressed_data_refs: __ld_insert_compressed_data_refs
+
+[Top]
+This built-in symbol represents the number of references to the data section,
+if the program does not mix text and data (for example if the data is written
+into an external file). If the program does not contain an explicit data
+section, it resolves to the value 0. If the data section is merged with the
+other sections, the references counted by this symbol and the references
+counted by <A HREF="$$LINK(symbols_ld_reloc_count)">__ld_reloc_count</A> will
+overlap.

+ 9 - 0
symbols_ld_data_size.hss

@@ -0,0 +1,9 @@
+[Main]
+Title=__ld_data_size
+See Also=symbols_ld_data_start: __ld_data_start, symbols_ld_data_end: __ld_data_end
+
+[Top]
+This built-in symbol represents the size of the data section in bytes, if the
+program does not mix text and data (for example if the data is written into
+an external file). If the program does not contain a data section, the symbol
+resolves to the value 0.

+ 10 - 0
symbols_ld_data_start.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=__ld_data_start
+See Also=symbols_ld_data_end: __ld_data_end, symbols_ld_data_size: __ld_data_size
+
+[Top]
+This built-in symbol represents the starting address of the data section, if
+the program does not mix text and data (for example if the data is written
+into an external file). It points to the location behind the last item in the
+section. If the program does not contain an explicit data section, an error
+is reported.

+ 11 - 0
symbols_ld_data_var_name_end.hss

@@ -0,0 +1,11 @@
+[Main]
+Title=__ld_data_var_name_end
+Index=__data_var_name_start
+
+[Top]
+This symbol is resolved to the address of the user-defined symbol
+<CODE>__data_var_name_start</CODE>, plus the length in bytes of the data
+variable name, plus 1 for the zero byte at the beginning. If no data variable
+is specified for the program, an error is reported. The symbol
+<CODE>__data_var_name_start</CODE> must be defined and exported by the
+program.

+ 10 - 0
symbols_ld_destructor_count.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=__ld_destructor_count
+See Also=symbols_ld_destructors_start: __ld_destructors_start, symbols_ld_destructors_end: __ld_destructors_end, symbols_ld_destructors_size: __ld_destructors_size, symbols_ld_constructor_count: __ld_constructor_count
+
+[Top]
+This built-in symbol represents the number of destructors the program uses.
+If no destructors are used, it resolves to a value of 0. The value equals
+the value of
+<A HREF="$$LINK(symbols_ld_destructors_size)">__ld_destructors_size</A>
+divided by the size of a pointer, which is 4.

+ 9 - 0
symbols_ld_destructors_end.hss

@@ -0,0 +1,9 @@
+[Main]
+Title=__ld_destructors_end
+See Also=symbols_ld_destructors_start: __ld_destructors_start, symbols_ld_destructors_size: __ld_destructors_size, symbols_ld_destructor_count: __ld_destructor_count
+
+[Top]
+This built-in symbol represents the end of the destructor section of the
+program. A destructor section contains an array of pointers to functions,
+all of which do not take any parameters. These functions are to be executed
+at program exit. If no destructors are used, an error is reported.

+ 11 - 0
symbols_ld_destructors_size.hss

@@ -0,0 +1,11 @@
+[Main]
+Title=__ld_destructors_size
+See Also=symbols_ld_destructors_start: __ld_destructors_start, symbols_ld_destructors_end: __ld_destructors_end, symbols_ld_destructor_count: __ld_destructor_count
+
+[Top]
+This built-in symbol represents the size of the destructor section of the
+program. A destructor section contains an array of pointers to functions,
+all of which do not take any parameters. If no destructors are used, the
+symbol resolves to a value of 0. The value equals the value of
+<A HREF="$$LINK(symbols_ld_destructor_count)">__ld_destructor_count</A>
+multiplied by the size of a pointer, which is 4.

+ 10 - 0
symbols_ld_destructors_start.hss

@@ -0,0 +1,10 @@
+[Main]
+Title=__ld_destructors_start
+See Also=symbols_ld_destructors_end: __ld_destructors_end, symbols_ld_destructors_size: __ld_destructors_size, symbols_ld_destructor_count: __ld_destructor_count, symbols_ld_constructors_start: __ld_constructors_start
+
+[Top]
+This built-in symbol represents the beginning of the destructor section of
+the program. A destructor section contains an array of pointers to
+functions, all of which do not take any parameters. These functions are to be
+executed at program startup. If no destructors are used, an error is
+reported.

+ 16 - 0
symbols_ld_entry_point.hss

@@ -0,0 +1,16 @@
+[Main]
+Title=__ld_entry_point
+
+[Top]
+References to this symbol are resolved to the first address of the program
+that contains executable code. If startup sections are defined, this is the
+address of the first startup section. However, the exact meaning of the
+symbol is defined by the <A HREF="$$LINK(modes)">mode</A> the linker is
+operating in, since startup sections do not necessarily need to contain code,
+and an "entry point" in the sense of this symbol does not exist in all types
+of files.
+<BR><BR>
+<B>Note:</B> In <A HREF="$$LINK(modes_fargo)">Fargo II mode</A>, all
+references to this symbol are manually shifted by two bytes in the negative
+direction, since Fargo heavily uses the program variable's address as a base
+address, instead of the address of the Fargo header.

+ 7 - 0
symbols_ld_entry_point_plus_0x8000.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=__ld_entry_point_plus_0x8000
+
+[Top]
+This symbol is the same as
+<A HREF="$$LINK(symbols_ld_entry_point)">__ld_entry_point</A> plus
+<CODE>0x8000</CODE> (32 KB).

+ 11 - 0
symbols_ld_export_count.hss

@@ -0,0 +1,11 @@
+[Main]
+Title=__ld_export_count
+See Also=insert_kernel_exports: __ld_insert_kernel_exports, symbols_lib_call: Library Calls
+
+[Top]
+This built-in symbol resolves to the number of exported items in the current
+program/library. This equals the highest export number present in the linked
+files (see <A HREF="$$LINK(symbols_lib_call)">Library Calls</A>) plus 1. For
+example, defining a single exported entry named <CODE>mylib@00FF</CODE>
+causes the export table to be 0x100 functions long, and therefore this symbol
+to be resolved to a value of 0x100.

+ 8 - 0
symbols_ld_file_version.hss

@@ -0,0 +1,8 @@
+[Main]
+Title=__ld_file_version
+See Also=control_version: _version...
+
+[Top]
+This symbol resolves to the version number of the current program, defined
+with <A HREF="$$LINK(control_version)">_version...</A>. If no version number
+has been defined, it resolves to a value of 0.

+ 6 - 0
symbols_ld_hardware_id.hss

@@ -0,0 +1,6 @@
+[Main]
+Title=__ld_hardware_id
+
+[Top]
+This built-in symbol resolves to the hardware ID of the target calculator
+type, a number used in the Flash OS stub.

+ 7 - 0
symbols_ld_has.hss

@@ -0,0 +1,7 @@
+[Main]
+Title=__ld_has_...
+
+[Top]
+The symbol __ld_has_<I>item</I>s resolves to a nonzero value if
+__ld_<I>item</I>_count is greater than zero. Currently this value is -1, but
+do not rely on this!

+ 17 - 0
symbols_ld_kernel_bss_table.hss

@@ -0,0 +1,17 @@
+[Main]
+Title=__ld_kernel_bss_table
+Index=__kernel_bss_table
+
+[Top]
+Usually, this symbol is simply resolved to a user-defined symbol named
+<CODE>__kernel_bss_table</CODE>. However, if the program does not contain a
+BSS section, it is redirected to the entry point of the program. The effect
+is that constructs of the form
+<PRE>.word __ld_kernel_bss_table-<I>entry_point</I>
+</PRE>
+resolve to 0 if no BSS section is used.
+<BR><BR>
+<B>Note:</B> If a program/library defines <CODE>__kernel_bss_table</CODE>, it
+absolutely <I>must</I> handle the BSS section. See
+<A HREF="$$LINK(insert_kernel_bss_refs)">__ld_insert_kernel_bss_refs</A> for
+a way to get information about references into the BSS section.

+ 12 - 0
symbols_ld_kernel_export_table.hss

@@ -0,0 +1,12 @@
+[Main]
+Title=__ld_kernel_export_table
+Index=__kernel_export_table
+
+[Top]
+Usually, this symbol is simply resolved to a user-defined symbol named
+<CODE>__kernel_export_table</CODE>. However, if the program does not contain
+any exported symbols, it is redirected to the entry point of the program. The
+effect is that constructs of the form
+<PRE>.word __ld_kernel_export_table-<I>entry_point</I>
+</PRE>
+resolve to 0 if no exports exist.

+ 8 - 0
symbols_ld_kernel_flags.hss

@@ -0,0 +1,8 @@
+[Main]
+Title=__ld_kernel_flags
+See Also=control_flag: _flag_...
+
+[Top]
+This symbol resolves to the value of the kernel flags. Kernel flags may be
+specified with <A HREF="$$LINK(control_flag)">_flag_...</A> and with
+<A HREF="$$LINK(control_calc)">calculator control symbols</A>.

+ 13 - 0
symbols_ld_lib_count.hss

@@ -0,0 +1,13 @@
+[Main]
+Title=__ld_lib_count
+See Also=symbols_ld_referenced_lib_count: __ld_referenced_lib_count, insert_kernel_libs: __ld_insert_kernel_libs, insert_fargo020_libs: __ld_insert_fargo020_libs, insert_fargo021_libs: __ld_insert_fargo021_libs, insert_preos_compressed_tables: __ld_insert_preos_compressed_tables, symbols_lib_call: Library Calls, control_lib_min_version: Minimum Library Versions
+
+[Top]
+This built-in symbol resolves to the number of libraries needed by this
+program/library. The libraries do not actually need to be used; it is enough
+for a file to specify a required minimum version for a specific library
+(see <A HREF="$$LINK(control_lib_min_version)">Minimum Library Versions</A>).
+The idea is that a program should be able to specify a minimum version for a
+library even if the library is only referenced indirectly via another one.
+See <A HREF="$$LINK(symbols_ld_referenced_lib_count)">__ld_referenced_lib_count</A>
+for a way to count only the libraries that are actually used.

+ 8 - 0
symbols_ld_nostub_comment_count.hss

@@ -0,0 +1,8 @@
+[Main]
+Title=__ld_nostub_comment_count
+See Also=insert_nostub_comments: __ld_insert_nostub_comments
+
+[Top]
+This built-in symbol resolves to the number of NoStub data exports in the
+current program. Unlike for library exports, skipped indices are <I>not</I>
+counted.

+ 18 - 0
symbols_ld_program_size.hss

@@ -0,0 +1,18 @@
+[Main]
+Title=__ld_program_size
+
+[Top]
+This built-in symbol represents the size of the main section after all sections
+are merged into one. If all sections are merged into a single section, this is
+the size of the final linked program (<I>without</I> any headers or footers
+required by the output format). If an external data variable is used, this
+would be the size of the main executable only (but see the note about automatic
+insertion below).<BR><BR>
+Resolving of this symbol is delayed until the last pass of the linker in order
+to ensure the size isn't changed by later range-cutting. Currently, this is the
+same pass which also does <A HREF="$$LINK(insert)">automatic insertions</A>, so
+insertions may or may not be counted.<BR><BR>
+This symbol is currently used by the Flash OS support to write the OS size into
+the header which is sent to the calculator. Flash operating systems do not use
+relocation, so the lack of support for automatic insertions is not a problem in
+this context.

+ 11 - 0
symbols_ld_ram_call_count.hss

@@ -0,0 +1,11 @@
+[Main]
+Title=__ld_ram_call_count
+See Also=insert_kernel_ram_calls: __ld_insert_kernel_ram_calls, insert_preos_compressed_tables: __ld_insert_preos_compressed_tables, symbols_ram_call: RAM Calls, symbols_extra_ram_addr: Extra RAM Addresses
+
+[Top]
+This built-in symbol resolves to the number of
+<A HREF="$$LINK(symbols_ram_call)">RAM calls</A> in this program/library. If
+the program/library does not reference any RAM exports, it resolves to a
+value of 0. <A HREF="$$LINK(symbols_extra_ram_addr)">Extra RAM address</A>
+references count as RAM calls as well. Note that RAM calls are handled purely
+by kernels, i.e. by middleware residing in the RAM.

Some files were not shown because too many files changed in this diff