forked from debrouxl/gcc4ti
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ld.html
2585 lines (2459 loc) · 141 KB
/
ld.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>The GCC4TI Linker</TITLE>
<STYLE TYPE="TEXT/CSS">
<!--
.IE3-DUMMY { CONT-SIZE: 100%; }
BODY { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; }
P { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H1 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H2 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H3 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H4 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H5 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H6 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
UL { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #FFFFFF; }
.NOBORDER { BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.NOBORDER TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.CODE { FONT-FAMILY: Courier New; }
-->
</STYLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#E0E0E0">
<FONT SIZE="5"><B>The GCC4TI Linker</B></FONT>
<HR>
<P>This is the documentation of the GCC4TI 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.</P>
<UL>
<LI><B><A HREF="#operation">GCC4TI Linker Purpose and Operation</A></B>
<LI><B><A HREF="#invocation">Invoking ld-tigcc and ar-tigcc</A></B>
<LI><B><A HREF="#modes">Linking Modes of the GCC4TI Linker</A></B>
<LI><B><A HREF="#formats">GCC4TI Linker File Formats</A></B>
<LI><B><A HREF="#control">Symbols to Control the Linker</A></B>
<LI><B><A HREF="#startup">Startup Sections</A></B>
<LI><B><A HREF="#global_imports">Global Imports</A></B>
<LI><B><A HREF="#symbols">Symbols Built into the GCC4TI Linker</A></B>
<LI><B><A HREF="#insert">Automatically Inserted Section Contents</A></B>
<LI><B><A HREF="#bincode">GCC4TI Linker Binary Code Fixup</A></B>
<LI><B><A HREF="#dump">ld-tigcc Program Dumps</A></B>
<LI><B><A HREF="#compiling">Recompiling ld-tigcc and ar-tigcc</A></B>
</UL>
<HR>
<H2><A NAME="operation"><U>GCC4TI Linker Purpose and Operation</U></A></H2>
<P>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
GCC4TI linker, can import code from several formats and export it to yet
another one (see <A HREF="#formats">GCC4TI Linker File Formats</A>).
<BR><BR>
The GCC4TI 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.</P>
<HR>
<H2><A NAME="invocation"><U>Invoking ld-tigcc and ar-tigcc</U></A></H2>
<P>The GCC4TI linker is available in two forms: as a standalone command line
program or as a dynamic link library (DLL). On Windows, GCC4TI uses the DLL
version for improved speed, but experienced programmers probably want to
use the command line version in some cases because it is a more advanced.
<BR><BR>
In the <A HREF="ide.html">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.</P>
<UL>
<LI><B><A HREF="#invocation_ld">ld-tigcc Command-Line Options</A></B>
<LI><B><A HREF="#invocation_ar">ar-tigcc Command-Line Options</A></B>
</UL>
<H3><A NAME="invocation_ld"><U>ld-tigcc Command-Line Options</U></A></H3>
<P>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:</P>
<DL>
<DT><P><B>-h</B>
<BR><B>--help</B></P><DD><P>Print a short description of all available options.
</P><DT><P><B>--version</B></P><DD><P>Print the version number of the tool and a short copyright notice.
</P><DT><P><B>-v</B>
<BR><B>--verbose</B></P><DD><P>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.
</P><DT><P><B>--dump</B></P><DD><P>Display all dumps of the program contents during the entire linking
process. For details about dumps, see <A HREF="#dump">ld-tigcc
Program Dumps</A>.
</P><DT><P><B>--dump<I>n</I></B></P><DD><P>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="#dump">ld-tigcc Program Dumps</A>.
</P><DT><P><B>--native</B></P><DD><P>Use GCC4TI 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="#control">Symbols to
Control the Linker</A>). For more information about modes, see
<A HREF="#modes">GCC4TI Linker Modes</A>.
</P><DT><P><B>--fargo</B></P><DD><P>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.
</P><DT><P><B>--flash-os</B></P><DD><P>Use Flash OS mode. This mode creates an unsigned Flash operating system
upgrade for the TI-89, TI-89 Titanium, TI-92+ and Voyage 200 calculators.
This option is only available if Flash OS support is compiled in.
</P><DT><P><B>--remove-unused</B></P><DD><P>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.
</P><DT><P><B>--optimize-relocs</B></P><DD><P>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.
</P><DT><P><B>--optimize-code</B></P><DD><P>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="#bincode">GCC4TI Linker Binary Code
Fixup</A>.</P>
<DL>
<DT><P><B>--optimize-nops</B></P><DD><P>Perform <A HREF="#bincode_nop">NOP instruction removal</A>.
</P><DT><P><B>--optimize-returns</B></P><DD><P>Perform <A HREF="#bincode_return">return sequence
optimization</A>.
</P><DT><P><B>--optimize-branches</B></P><DD><P>Perform <A HREF="#bincode_branch">branch optimization</A>.
</P><DT><P><B>--optimize-moves</B></P><DD><P>Perform <A HREF="#bincode_move">move/load/push optimization</A>.
</P><DT><P><B>--optimize-tests</B></P><DD><P>Perform <A HREF="#bincode_test">compare/test optimization</A>.
</P><DT><P><B>--optimize-calcs</B></P><DD><P>Perform <A HREF="#bincode_calculation">calculation
optimization</A>.</P>
</DL>
<DT><P><B>--cut-ranges</B></P><DD><P>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 GCC4TI IDE.
</P><DT><P><B>--reorder-sections</B></P><DD><P>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.</P><DT><P><B>--merge-constants</B></P><DD><P>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.</P><DT><P><B>--omit-bss-init</B></P><DD><P>Skip the initialization of the BSS section, which holds uninitialized
global variables. Old 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="comopts.html">compiler option</A>
<B>'-fno-zero-initialized-in-bss'</B>). For a safer alternative, try the
<A HREF="#control_ld_omit_bss_init">__ld_omit_bss_init</A> control
symbol.
</P><DT><P><B>--outputbin</B></P><DD><P>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.
</P><DT><P><B>-o <I>file</I></B>
<BR><B>--output <I>file</I></B></P><DD><P>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.
</P><DT><P><B>-n [<I>folder</I>\]<I>name</I></B>
<BR><B>--varname [<I>folder</I>\]<I>name</I></B></P><DD><P>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.
</P><DT><P><B>-d [<I>folder</I>\]<I>name</I></B>
<BR><B>--data-var [<I>folder</I>\]<I>name</I></B></P><DD><P>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.
</P><DT><P><B>--data-var-copy=<I>condition</I></B></P><DD><P>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.</P>
</DL>
<H3><A NAME="invocation_ar"><U>ar-tigcc Command-Line Options</U></A></H3>
<P>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 GCC4TI.
<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:</P>
<DL>
<DT><P><B>-h</B>
<BR><B>--help</B></P><DD><P>Print a short description of all available options.
</P><DT><P><B>--version</B></P><DD><P>Print the version number of the tool and a short copyright notice.
</P><DT><P><B>--dump</B></P><DD><P>Display a small dump of the archive file contents. This includes the
members as well as the symbols they export.
</P><DT><P><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></P><DD><P>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>.
</P><DT><P><B>--no-names</B></P><DD><P>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.</P>
</DL>
<HR>
<H2><A NAME="modes"><U>Linking Modes of the GCC4TI Linker</U></A></H2>
<P>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 GCC4TI 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.</P>
<UL>
<LI><B><A HREF="#modes_native">GCC4TI-Native Linking Mode</A></B>
<LI><B><A HREF="#modes_nostub">Nostub Linking Mode</A></B>
<LI><B><A HREF="#modes_nostub_dll">Nostub DLL Linking Mode</A></B>
<LI><B><A HREF="#modes_kernel">Kernel Linking Mode</A></B>
<LI><B><A HREF="#modes_fargo">Fargo II Linking Mode</A></B>
<LI><B><A HREF="#modes_flash_os">Flash OS Linking Mode</A></B>
</UL>
<P>The recommended mode for normal GCC4TI programs is
<A HREF="#modes_native">GCC4TI-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="#modes_kernel">kernel mode</A> unless you set the appropriate
<A HREF="#invocation_ld">command-line option</A>, to make old existing
programs work without modifications.</P>
<H3><A NAME="modes_native"><U>GCC4TI-Native Linking Mode</U></A></H3>
<P>This mode (which can be enabled using the <B>'--native'</B>
<A HREF="#invocation_ld">command-line option</A> or the control symbol
<A HREF="#control_tigcc_native">_tigcc_native</A>) is the
recommended mode for all new programs. When operating in this mode, the GCC4TI
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
GCC4TI-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.</P>
<H3><A NAME="modes_nostub"><U>Nostub Linking Mode</U></A></H3>
<P>If this mode is activated using the
<A HREF="#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="#startup">startup section</A> including a jump
to the actual main function and use
<A HREF="#modes_native">GCC4TI-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="#modes_native">GCC4TI-native mode</A>. This
ensures that nostub mode really means that no stub is added to the program.</P>
<H3><A NAME="modes_nostub_dll"><U>Nostub DLL Linking Mode</U></A></H3>
<P>If the linker is told to use Nostub DLL mode using the
<A HREF="#control_nostub_dll">__nostub_dll</A> control symbol, it acts
like in <A HREF="#modes_native">GCC4TI-native mode</A>, except that it
causes the linker to use the Nostub DLL output
<A HREF="#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.</P>
<H3><A NAME="modes_kernel"><U>Kernel Linking Mode</U></A></H3>
<P>In this mode, which is enabled by default, the linker acts the same way as in
<A HREF="#modes_native">GCC4TI-native mode</A>, but it creates a
<A HREF="#global_imports">global import</A> asking for the appropriate
kernel format header. See <A HREF="#global_imports_auto">Automatically
Created Global Imports</A> for more information.</P>
<H3><A NAME="modes_fargo"><U>Fargo II Linking Mode</U></A></H3>
<P>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="#invocation_ld">command-line option</A> or the
<A HREF="#control_fargo">_fargo</A> control symbol. It uses the Fargo
II output <A HREF="#formats">format</A>, which is binary data wrapped
in an empty TI-BASIC program. It creates a
<A HREF="#global_imports">global import</A> asking for the appropriate
Fargo II header (see <A HREF="#global_imports_auto">Automatically
Created Global Imports</A> for more information). And it also causes the
value of <A HREF="#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.</P>
<H3><A NAME="modes_flash_os"><U>Flash OS Linking Mode</U></A></H3>
<P>This mode creates an unsigned Flash operating system upgrade for the TI-89,
TI-89 Titanium, TI-92+ and Voyage 200 calculators. It can be turned on using
the <B>'--flash-os'</B> <A HREF="#invocation_ld">command-line
option</A> or the <A HREF="#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="#invocation_ld">option</A>. Support
for the current 89u/9xu/v2u format is planned and will be the default. It
creates a <A HREF="#global_imports">global import</A> asking for the
appropriate Flash OS header (see
<A HREF="#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="#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.</P>
<HR>
<H2><A NAME="formats"><U>GCC4TI Linker File Formats</U></A></H2>
<P>The GCC4TI 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></P>
<HR>
<H2><A NAME="control"><U>Symbols to Control the Linker</U></A></H2>
<P>In addition to options specified in the command line, the GCC4TI 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:</P>
<UL>
<LI><B><A HREF="#control_ref_all">__ref_all_...</A></B>
<LI><B><A HREF="#control_tigcc_native">_tigcc_native</A></B>
<LI><B><A HREF="#control_nostub">_nostub</A></B>
<LI><B><A HREF="#control_nostub_dll">_nostub_dll</A></B>
<LI><B><A HREF="#control_fargo">_fargo</A></B>
<LI><B><A HREF="#control_flash_os">_flash_os</A></B>
<LI><B><A HREF="#control_library">_library</A></B>
<LI><B><A HREF="#control_calc">_ti92, _ti89, _ti92plus, _v200</A></B>
<LI><B><A HREF="#control_flag">_flag_...</A></B>
<LI><B><A HREF="#control_version">_version...</A></B>
<LI><B><A HREF="#control_lib_min_version">...@version..., ...__version...</A></B>
<LI><B><A HREF="#control_ld_use_fline_jumps">__ld_use_fline_jumps</A></B>
<LI><B><A HREF="#control_ld_use_4byte_fline_jumps">__ld_use_4byte_fline_jumps</A></B>
<LI><B><A HREF="#control_ld_omit_bss_init">__ld_omit_bss_init</A></B>
<LI><B><A HREF="#control_ld_ignore_global_imports">__ld_ignore_global_imports</A></B>
</UL>
<P>Symbols can be created in a variety of ways; they can be:</P>
<UL>
<LI><P>labels;</P></LI>
<LI><P>undefined exported symbols;</P></LI>
<LI><P>imported (used but undefined) symbols;</P></LI>
<LI><P>common symbols.</P></LI>
</UL>
<P>Not all assemblers support all types of symbols; for example, the
<A HREF="a68k.html">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.</P>
<H3><A NAME="control_ref_all"><U>__ref_all_...</U></A></H3>
<P>Defining __ref_all_<I>name</I> creates a
<A HREF="#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="#global_imports_conditional">conditional reaction</A>), the
linker outputs a warning.</P>
<H3><A NAME="control_tigcc_native"><U>_tigcc_native</U></A></H3>
<P>Defining this symbol switches to <A HREF="#modes_native">GCC4TI native
mode</A>. We recommend that you define this in all new programs, and then
create or import <A HREF="#startup">startup sections</A>.</P>
<H3><A NAME="control_nostub"><U>_nostub</U></A></H3>
<P>Defining this symbol switches to <A HREF="#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.</P>
<H3><A NAME="control_nostub_dll"><U>_nostub_dll</U></A></H3>
<P>Defining this symbol switches to <A HREF="#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.</P>
<H3><A NAME="control_fargo"><U>_fargo</U></A></H3>
<P>Defining this symbol switches to <A HREF="#modes_fargo">Fargo II
mode</A>. If Fargo support is not compiled in, the symbol is not treated in a
special way.</P>
<H3><A NAME="control_flash_os"><U>_flash_os</U></A></H3>
<P>Defining this symbol switches to <A HREF="#modes_flash_os">Flash OS
mode</A>. If Flash OS support is not compiled in, the symbol is not treated in
a special way.</P>
<H3><A NAME="control_library"><U>_library</U></A></H3>
<P>Defining this symbol causes a library to be created instead of a program.
The linker will warn about program <A HREF="#startup">startup
sections</A> being included, and depending on the
<A HREF="#modes">linking mode</A> some different
<A HREF="#global_imports_auto">automatic global imports</A> will be
created.</P>
<H3><A NAME="control_calc"><U>_ti92, _ti89, _ti92plus, _v200</U></A></H3>
<P>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="#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></P>
<H3><A NAME="control_flag"><U>_flag_...</U></A></H3>
<P>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="#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.</P>
<P>See also: <A HREF="#symbols_ld_kernel_flags">__ld_kernel_flags</A></P>
<H3><A NAME="control_version"><U>_version...</U></A></H3>
<P>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>.</P>
<P>See also: <A HREF="#symbols_ld_file_version">__ld_file_version</A></P>
<H3><A NAME="control_lib_min_version"><U>...@version..., ...__version...</U></A></H3>
<P>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="#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="#control_version">_version...</A>).</P>
<P>See also: <A HREF="#symbols_lib_call">Library Calls</A></P>
<H3><A NAME="control_ld_use_fline_jumps"><U>__ld_use_fline_jumps</U></A></H3>
<P>Defining this symbol tells the linker to use relative
<A HREF="#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 GCC4TI's own emulator.</P>
<P>See also: <A HREF="#control_ld_use_4byte_fline_jumps">__ld_use_4byte_fline_jumps</A></P>
<H3><A NAME="control_ld_use_4byte_fline_jumps"><U>__ld_use_4byte_fline_jumps</U></A></H3>
<P>Defining this symbol tells the linker to use program-relative
<A HREF="#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.</P>
<P>See also: <A HREF="#control_ld_use_fline_jumps">__ld_use_fline_jumps</A></P>
<H3><A NAME="control_ld_omit_bss_init"><U>__ld_omit_bss_init</U></A></H3>
<P>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 GCC4TI), 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="a68k.html">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="comopts.html">compiler option</A>
<B>'-fno-zero-initialized-in-bss'</B>; otherwise even variables explicitly
initialized to zero will contain garbage.</P>
<H3><A NAME="control_ld_ignore_global_imports"><U>__ld_ignore_global_imports</U></A></H3>
<P>Defining this symbol in a source file tells the linker that from this file
on, defining a <A HREF="#control_ref_all">__ref_all_...</A> symbol has
no effect. This should not be used except in very special circumstances.</P>
<HR>
<H2><A NAME="startup"><U>Startup Sections</U></A></H2>
<P>The concept of <U>startup sections</U> is unique to the GCC4TI 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="#formats">GCC4TI 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.</P>
<HR>
<H2><A NAME="global_imports"><U>Global Imports</U></A></H2>
<P>Just like <A HREF="#startup">startup sections</A>, the concept of
<U>global imports</U> is unique to the GCC4TI 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="#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:</P>
<UL>
<LI><P>File 1 exports the symbols <I>A</I> and <I>B</I>.</P></LI>
<LI><P>File 2 exports the symbols <I>B</I> and <I>C</I>.</P></LI>
<LI><P>File 3 exports the symbols <I>A</I> and <I>C</I>.</P></LI>
</UL>
<P>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:</P>
<UL>
<LI><P>File 1 exports the symbol <I>A</I> and creates two global imports for <I>File4</I> and <I>File6</I>.</P></LI>
<LI><P>File 2 exports the symbol <I>B</I> and creates two global imports for <I>File4</I> and <I>File5</I>.</P></LI>
<LI><P>File 3 exports the symbol <I>C</I> and creates two global imports for <I>File5</I> and <I>File6</I>.</P></LI>
<LI><P>File 4 exports the symbol <I>File4</I>.</P></LI>
<LI><P>File 5 exports the symbol <I>File5</I>.</P></LI>
<LI><P>File 6 exports the symbol <I>File6</I>.</P></LI>
</UL>
<P>Global import can be created using the
<A HREF="#control_ref_all">__ref_all_...</A> control symbol. Some
global imports are also created automatically by the linker on certain
conditions.</P>
<UL>
<LI><B><A HREF="#global_imports_conditional">Conditional Reaction to Global Imports</A></B>
<LI><B><A HREF="#global_imports_auto">Automatically Created Global Imports</A></B>
</UL>
<H3><A NAME="global_imports_conditional"><U>Conditional Reaction to Global Imports</U></A></H3>
<P>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 GCC4TI linker defines two symbol operators for this purpose:</P>
<UL>
<LI><P>..._AND_...</P></LI>
<LI><P>NOT_...</P></LI>
</UL>
<P>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.</P>
<H3><A NAME="global_imports_auto"><U>Automatically Created Global Imports</U></A></H3>
<P>In addition to user-defined global imports, the GCC4TI linker also defines
some global imports of its own, whenever special code is needed to handle a
situation:
</P>
<DL>
<DT><P><B>__kernel_program_header</B></P><DD><P>This global import is created automatically if the linker
is operating in <A HREF="#modes_kernel">kernel mode</A>, and if the
file is not declared as a library (see the
<A HREF="#control_library">_library</A> control symbol).
</P><DT><P><B>__kernel_library_header</B></P><DD><P>This global import is created automatically if the linker
is operating in <A HREF="#modes_kernel">kernel mode</A>, and if the
file is declared as a library (see the
<A HREF="#control_library">_library</A> control symbol).
</P><DT><P><B>__fargo_program_header</B></P><DD><P>This global import is created automatically if the linker
is operating in <A HREF="#modes_fargo">Fargo II mode</A>, and if the
file is not declared as a library (see the
<A HREF="#control_library">_library</A> control symbol).
</P><DT><P><B>__fargo_library_header</B></P><DD><P>This global import is created automatically if the linker
is operating in <A HREF="#modes_fargo">Fargo II mode</A>, and if the
file is declared as a library (see the
<A HREF="#control_library">_library</A> control symbol).
</P><DT><P><B>__flash_os_header</B></P><DD><P>This global import is created automatically if the linker
is operating in <A HREF="#modes_flash_os">Flash OS mode</A>.
</P><DT><P><B>__nostub_comment_header</B></P><DD><P>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="#symbols_ld_nostub_comment_count">__ld_nostub_comment_count
</A> and
<A HREF="#insert_nostub_comments">__ld_insert_nostub_comments</A>
to insert the actual data exports into the header.
</P><DT><P><B>__handle_constructors</B></P><DD><P>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="#symbols_ld_constructors_start">__ld_constructors_start</A>,
<A HREF="#symbols_ld_constructors_end">__ld_constructors_end</A>,
<A HREF="#symbols_ld_constructors_size">__ld_constructors_size</A>,
and <A HREF="#symbols_ld_constructor_count">__ld_constructor_count</A>
symbols.
</P><DT><P><B>__handle_destructors</B></P><DD><P>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="#symbols_ld_destructors_start">__ld_destructors_start</A>,
<A HREF="#symbols_ld_destructors_end">__ld_destructors_end</A>,
<A HREF="#symbols_ld_destructors_size">__ld_destructors_size</A>,
and <A HREF="#symbols_ld_destructor_count">__ld_destructor_count</A>
symbols.
</P><DT><P><B>__handle_bss</B></P><DD><P>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="#symbols_ld_bss_size">__ld_bss_size</A>,
<A HREF="#symbols_ld_bss_ref_count">__ld_bss_ref_count</A>, and
an appropriate <A HREF="#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.
</P><DT><P><B>__initialize_bss</B></P><DD><P>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="#symbols_ld_bss_start">__ld_bss_start</A>,
<A HREF="#symbols_ld_bss_end">__ld_bss_end</A>, and
<A HREF="#symbols_ld_bss_size">__ld_bss_size</A> to query the location
and size of the BSS section.
<BR><BR>
</P><DT><P><B>__handle_relocs</B>
</P><DD><P>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="#symbols_ld_reloc_count">__ld_reloc_count</A> and an
appropriate <A HREF="#insert">insertion</A> to get information about
the necessary relocation.
</P><DT><P><B>__handle_rom_calls</B></P><DD><P>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="#symbols_ld_rom_call_count">__ld_rom_call_count</A> and an
appropriate <A HREF="#insert">insertion</A> to get information about
the ROM calls.
</P><DT><P><B>__handle_ram_calls</B></P><DD><P>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="#symbols_ld_ram_call_count">__ld_ram_call_count</A> and an
appropriate <A HREF="#insert">insertion</A> to get information about
the RAM calls.
</P><DT><P><B>__handle_libraries</B></P><DD><P>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="#symbols_ld_lib_count">__ld_lib_count</A> and an
appropriate <A HREF="#insert">insertion</A> to get information about
the libraries.
</P><DT><P><B>__handle_data_var</B></P><DD><P>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="#symbols_ld_data_var_name_end">__ld_data_var_name_end</A>,
<A HREF="#symbols_ld_data_size">__ld_data_size</A>, and an appropriate
<A HREF="#insert">insertion</A> for the relocation.
</P><DT><P><B>__data_var_create_copy</B></P><DD><P>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).
</P><DT><P><B>__data_var_copy_if_archived</B></P><DD><P>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.</P>
</DL>
<HR>
<H2><A NAME="symbols"><U>Symbols Built into the GCC4TI Linker</U></A></H2>
<P>The GCC4TI linker is capable of resolving references to certain built-in
symbols. These symbols act just like normal externally defined symbols; for
example, it is possible to specify an offset to be added to the symbol in the
reference. The symbols may resolve to numbers or addresses. The kind of
symbol should be obvious for each individual symbol; for example, it does not
make sense to jump to <A HREF="#symbols_ld_bss_size">__ld_bss_size</A>
because it resolves to a number. All numbers have to be used as immediate
values; if a symbol resolves to a number, treating it as an address and
reading the value at this address will return garbage.
<BR><BR>
The following symbol names are treated as built-in symbol names, and resolved
in a special way:</P>
<UL>
<LI><B><A HREF="#symbols_rom_call">_ROM_CALL_...</A></B>
<LI><B><A HREF="#symbols_ti_ams_api">tiamsapi_...</A></B>
<LI><B><A HREF="#symbols_ram_call">_RAM_CALL_...</A></B>
<LI><B><A HREF="#symbols_extra_ram_addr">_extraramaddr@..., _extraramaddr__...</A></B>
<LI><B><A HREF="#symbols_lib_call">...@????, ...__????</A></B>
<LI><B><A HREF="#symbols_ld_calc_const">__ld_calc_const_...</A></B>
<LI><B><A HREF="#symbols_ld_entry_point">__ld_entry_point</A></B>
<LI><B><A HREF="#symbols_ld_entry_point_plus_0x8000">__ld_entry_point_plus_0x8000</A></B>
<LI><B><A HREF="#symbols_ld_program_size">__ld_program_size</A></B>
<LI><B><A HREF="#symbols_ld_constructors_start">__ld_constructors_start</A></B>
<LI><B><A HREF="#symbols_ld_constructors_end">__ld_constructors_end</A></B>
<LI><B><A HREF="#symbols_ld_constructors_size">__ld_constructors_size</A></B>
<LI><B><A HREF="#symbols_ld_constructor_count">__ld_constructor_count</A></B>
<LI><B><A HREF="#symbols_ld_destructors_start">__ld_destructors_start</A></B>
<LI><B><A HREF="#symbols_ld_destructors_end">__ld_destructors_end</A></B>
<LI><B><A HREF="#symbols_ld_destructors_size">__ld_destructors_size</A></B>
<LI><B><A HREF="#symbols_ld_destructor_count">__ld_destructor_count</A></B>
<LI><B><A HREF="#symbols_ld_reloc_count">__ld_reloc_count</A></B>
<LI><B><A HREF="#symbols_ld_data_start">__ld_data_start</A></B>
<LI><B><A HREF="#symbols_ld_data_end">__ld_data_end</A></B>
<LI><B><A HREF="#symbols_ld_data_size">__ld_data_size</A></B>
<LI><B><A HREF="#symbols_ld_data_ref_count">__ld_data_ref_count</A></B>
<LI><B><A HREF="#symbols_ld_bss_start">__ld_bss_start</A></B>
<LI><B><A HREF="#symbols_ld_bss_end">__ld_bss_end</A></B>
<LI><B><A HREF="#symbols_ld_bss_even_end">__ld_bss_even_end</A></B>
<LI><B><A HREF="#symbols_ld_bss_size">__ld_bss_size</A></B>
<LI><B><A HREF="#symbols_ld_bss_ref_count">__ld_bss_ref_count</A></B>
<LI><B><A HREF="#symbols_ld_rom_call_count">__ld_rom_call_count</A></B>
<LI><B><A HREF="#symbols_ld_ram_call_count">__ld_ram_call_count</A></B>
<LI><B><A HREF="#symbols_ld_lib_count">__ld_lib_count</A></B>
<LI><B><A HREF="#symbols_ld_referenced_lib_count">__ld_referenced_lib_count</A></B>
<LI><B><A HREF="#symbols_ld_export_count">__ld_export_count</A></B>
<LI><B><A HREF="#symbols_ld_nostub_comment_count">__ld_nostub_comment_count</A></B>