diff options
Diffstat (limited to 'bfd/doc/linker.texi')
| -rw-r--r-- | bfd/doc/linker.texi | 432 |
1 files changed, 432 insertions, 0 deletions
diff --git a/bfd/doc/linker.texi b/bfd/doc/linker.texi new file mode 100644 index 0000000000..eae166278b --- /dev/null +++ b/bfd/doc/linker.texi @@ -0,0 +1,432 @@ +@section Linker Functions +@cindex Linker +The linker uses three special entry points in the BFD target +vector. It is not necessary to write special routines for +these entry points when creating a new BFD back end, since +generic versions are provided. However, writing them can +speed up linking and make it use significantly less runtime +memory. + +The first routine creates a hash table used by the other +routines. The second routine adds the symbols from an object +file to the hash table. The third routine takes all the +object files and links them together to create the output +file. These routines are designed so that the linker proper +does not need to know anything about the symbols in the object +files that it is linking. The linker merely arranges the +sections as directed by the linker script and lets BFD handle +the details of symbols and relocs. + +The second routine and third routines are passed a pointer to +a @code{struct bfd_link_info} structure (defined in +@code{bfdlink.h}) which holds information relevant to the link, +including the linker hash table (which was created by the +first routine) and a set of callback functions to the linker +proper. + +The generic linker routines are in @code{linker.c}, and use the +header file @code{genlink.h}. As of this writing, the only back +ends which have implemented versions of these routines are +a.out (in @code{aoutx.h}) and ECOFF (in @code{ecoff.c}). The a.out +routines are used as examples throughout this section. + +@menu +* Creating a Linker Hash Table:: +* Adding Symbols to the Hash Table:: +* Performing the Final Link:: +@end menu + +@node Creating a Linker Hash Table, Adding Symbols to the Hash Table, Linker Functions, Linker Functions +@subsection Creating a linker hash table +@cindex _bfd_link_hash_table_create in target vector +@cindex target vector (_bfd_link_hash_table_create) +The linker routines must create a hash table, which must be +derived from @code{struct bfd_link_hash_table} described in +@code{bfdlink.c}. @xref{Hash Tables}, for information on how to +create a derived hash table. This entry point is called using +the target vector of the linker output file. + +The @code{_bfd_link_hash_table_create} entry point must allocate +and initialize an instance of the desired hash table. If the +back end does not require any additional information to be +stored with the entries in the hash table, the entry point may +simply create a @code{struct bfd_link_hash_table}. Most likely, +however, some additional information will be needed. + +For example, with each entry in the hash table the a.out +linker keeps the index the symbol has in the final output file +(this index number is used so that when doing a relocatable +link the symbol index used in the output file can be quickly +filled in when copying over a reloc). The a.out linker code +defines the required structures and functions for a hash table +derived from @code{struct bfd_link_hash_table}. The a.out linker +hash table is created by the function +@code{NAME(aout,link_hash_table_create)}; it simply allocates +space for the hash table, initializes it, and returns a +pointer to it. + +When writing the linker routines for a new back end, you will +generally not know exactly which fields will be required until +you have finished. You should simply create a new hash table +which defines no additional fields, and then simply add fields +as they become necessary. + +@node Adding Symbols to the Hash Table, Performing the Final Link, Creating a Linker Hash Table, Linker Functions +@subsection Adding symbols to the hash table +@cindex _bfd_link_add_symbols in target vector +@cindex target vector (_bfd_link_add_symbols) +The linker proper will call the @code{_bfd_link_add_symbols} +entry point for each object file or archive which is to be +linked (typically these are the files named on the command +line, but some may also come from the linker script). The +entry point is responsible for examining the file. For an +object file, BFD must add any relevant symbol information to +the hash table. For an archive, BFD must determine which +elements of the archive should be used and adding them to the +link. + +The a.out version of this entry point is +@code{NAME(aout,link_add_symbols)}. + +@menu +* Differing file formats:: +* Adding symbols from an object file:: +* Adding symbols from an archive:: +@end menu + +@node Differing file formats, Adding symbols from an object file, Adding Symbols to the Hash Table, Adding Symbols to the Hash Table +@subsubsection Differing file formats +Normally all the files involved in a link will be of the same +format, but it is also possible to link together different +format object files, and the back end must support that. The +@code{_bfd_link_add_symbols} entry point is called via the target +vector of the file to be added. This has an important +consequence: the function may not assume that the hash table +is the type created by the corresponding +@code{_bfd_link_hash_table_create} vector. All the +@code{_bfd_link_add_symbols} function can assume about the hash +table is that it is derived from @code{struct +bfd_link_hash_table}. + +Sometimes the @code{_bfd_link_add_symbols} function must store +some information in the hash table entry to be used by the +@code{_bfd_final_link} function. In such a case the output bfd +xvec must be checked to make sure that the hash table was +created by an object file of the same format. + +The @code{_bfd_final_link} routine must be prepared to handle a +hash entry without any extra information added by the +@code{_bfd_link_add_symbols} function. A hash entry without +extra information will also occur when the linker script +directs the linker to create a symbol. Note that, regardless +of how a hash table entry is added, all the fields will be +initialized to some sort of null value by the hash table entry +initialization function. + +See @code{ecoff_link_add_externals} for an example of how to +check the output bfd before saving information (in this +case, the ECOFF external symbol debugging information) in a +hash table entry. + +@node Adding symbols from an object file, Adding symbols from an archive, Differing file formats, Adding Symbols to the Hash Table +@subsubsection Adding symbols from an object file +When the @code{_bfd_link_add_symbols} routine is passed an object +file, it must add all externally visible symbols in that +object file to the hash table. The actual work of adding the +symbol to the hash table is normally handled by the function +@code{_bfd_generic_link_add_one_symbol}. The +@code{_bfd_link_add_symbols} routine is responsible for reading +all the symbols from the object file and passing the correct +information to @code{_bfd_generic_link_add_one_symbol}. + +The @code{_bfd_link_add_symbols} routine should not use +@code{bfd_canonicalize_symtab} to read the symbols. The point of +providing this routine is to avoid the overhead of converting +the symbols into generic @code{asymbol} structures. + +@findex _bfd_generic_link_add_one_symbol +@code{_bfd_generic_link_add_one_symbol} handles the details of +combining common symbols, warning about multiple definitions, +and so forth. It takes arguments which describe the symbol to +add, notably symbol flags, a section, and an offset. The +symbol flags include such things as @code{BSF_WEAK} or +@code{BSF_INDIRECT}. The section is a section in the object +file, or something like @code{bfd_und_section_ptr} for an undefined +symbol or @code{bfd_com_section_ptr} for a common symbol. + +If the @code{_bfd_final_link} routine is also going to need to +read the symbol information, the @code{_bfd_link_add_symbols} +routine should save it somewhere attached to the object file +BFD. However, the information should only be saved if the +@code{keep_memory} field of the @code{info} argument is TRUE, so +that the @code{-no-keep-memory} linker switch is effective. + +The a.out function which adds symbols from an object file is +@code{aout_link_add_object_symbols}, and most of the interesting +work is in @code{aout_link_add_symbols}. The latter saves +pointers to the hash tables entries created by +@code{_bfd_generic_link_add_one_symbol} indexed by symbol number, +so that the @code{_bfd_final_link} routine does not have to call +the hash table lookup routine to locate the entry. + +@node Adding symbols from an archive, , Adding symbols from an object file, Adding Symbols to the Hash Table +@subsubsection Adding symbols from an archive +When the @code{_bfd_link_add_symbols} routine is passed an +archive, it must look through the symbols defined by the +archive and decide which elements of the archive should be +included in the link. For each such element it must call the +@code{add_archive_element} linker callback, and it must add the +symbols from the object file to the linker hash table. (The +callback may in fact indicate that a replacement BFD should be +used, in which case the symbols from that BFD should be added +to the linker hash table instead.) + +@findex _bfd_generic_link_add_archive_symbols +In most cases the work of looking through the symbols in the +archive should be done by the +@code{_bfd_generic_link_add_archive_symbols} function. This +function builds a hash table from the archive symbol table and +looks through the list of undefined symbols to see which +elements should be included. +@code{_bfd_generic_link_add_archive_symbols} is passed a function +to call to make the final decision about adding an archive +element to the link and to do the actual work of adding the +symbols to the linker hash table. + +The function passed to +@code{_bfd_generic_link_add_archive_symbols} must read the +symbols of the archive element and decide whether the archive +element should be included in the link. If the element is to +be included, the @code{add_archive_element} linker callback +routine must be called with the element as an argument, and +the element's symbols must be added to the linker hash table +just as though the element had itself been passed to the +@code{_bfd_link_add_symbols} function. The @code{add_archive_element} +callback has the option to indicate that it would like to +replace the element archive with a substitute BFD, in which +case it is the symbols of that substitute BFD that must be +added to the linker hash table instead. + +When the a.out @code{_bfd_link_add_symbols} function receives an +archive, it calls @code{_bfd_generic_link_add_archive_symbols} +passing @code{aout_link_check_archive_element} as the function +argument. @code{aout_link_check_archive_element} calls +@code{aout_link_check_ar_symbols}. If the latter decides to add +the element (an element is only added if it provides a real, +non-common, definition for a previously undefined or common +symbol) it calls the @code{add_archive_element} callback and then +@code{aout_link_check_archive_element} calls +@code{aout_link_add_symbols} to actually add the symbols to the +linker hash table - possibly those of a substitute BFD, if the +@code{add_archive_element} callback avails itself of that option. + +The ECOFF back end is unusual in that it does not normally +call @code{_bfd_generic_link_add_archive_symbols}, because ECOFF +archives already contain a hash table of symbols. The ECOFF +back end searches the archive itself to avoid the overhead of +creating a new hash table. + +@node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions +@subsection Performing the final link +@cindex _bfd_link_final_link in target vector +@cindex target vector (_bfd_final_link) +When all the input files have been processed, the linker calls +the @code{_bfd_final_link} entry point of the output BFD. This +routine is responsible for producing the final output file, +which has several aspects. It must relocate the contents of +the input sections and copy the data into the output sections. +It must build an output symbol table including any local +symbols from the input files and the global symbols from the +hash table. When producing relocatable output, it must +modify the input relocs and write them into the output file. +There may also be object format dependent work to be done. + +The linker will also call the @code{write_object_contents} entry +point when the BFD is closed. The two entry points must work +together in order to produce the correct output file. + +The details of how this works are inevitably dependent upon +the specific object file format. The a.out +@code{_bfd_final_link} routine is @code{NAME(aout,final_link)}. + +@menu +* Information provided by the linker:: +* Relocating the section contents:: +* Writing the symbol table:: +@end menu + +@node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link +@subsubsection Information provided by the linker +Before the linker calls the @code{_bfd_final_link} entry point, +it sets up some data structures for the function to use. + +The @code{input_bfds} field of the @code{bfd_link_info} structure +will point to a list of all the input files included in the +link. These files are linked through the @code{link_next} field +of the @code{bfd} structure. + +Each section in the output file will have a list of +@code{link_order} structures attached to the @code{map_head.link_order} +field (the @code{link_order} structure is defined in +@code{bfdlink.h}). These structures describe how to create the +contents of the output section in terms of the contents of +various input sections, fill constants, and, eventually, other +types of information. They also describe relocs that must be +created by the BFD backend, but do not correspond to any input +file; this is used to support -Ur, which builds constructors +while generating a relocatable object file. + +@node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link +@subsubsection Relocating the section contents +The @code{_bfd_final_link} function should look through the +@code{link_order} structures attached to each section of the +output file. Each @code{link_order} structure should either be +handled specially, or it should be passed to the function +@code{_bfd_default_link_order} which will do the right thing +(@code{_bfd_default_link_order} is defined in @code{linker.c}). + +For efficiency, a @code{link_order} of type +@code{bfd_indirect_link_order} whose associated section belongs +to a BFD of the same format as the output BFD must be handled +specially. This type of @code{link_order} describes part of an +output section in terms of a section belonging to one of the +input files. The @code{_bfd_final_link} function should read the +contents of the section and any associated relocs, apply the +relocs to the section contents, and write out the modified +section contents. If performing a relocatable link, the +relocs themselves must also be modified and written out. + +@findex _bfd_relocate_contents +@findex _bfd_final_link_relocate +The functions @code{_bfd_relocate_contents} and +@code{_bfd_final_link_relocate} provide some general support for +performing the actual relocations, notably overflow checking. +Their arguments include information about the symbol the +relocation is against and a @code{reloc_howto_type} argument +which describes the relocation to perform. These functions +are defined in @code{reloc.c}. + +The a.out function which handles reading, relocating, and +writing section contents is @code{aout_link_input_section}. The +actual relocation is done in @code{aout_link_input_section_std} +and @code{aout_link_input_section_ext}. + +@node Writing the symbol table, , Relocating the section contents, Performing the Final Link +@subsubsection Writing the symbol table +The @code{_bfd_final_link} function must gather all the symbols +in the input files and write them out. It must also write out +all the symbols in the global hash table. This must be +controlled by the @code{strip} and @code{discard} fields of the +@code{bfd_link_info} structure. + +The local symbols of the input files will not have been +entered into the linker hash table. The @code{_bfd_final_link} +routine must consider each input file and include the symbols +in the output file. It may be convenient to do this when +looking through the @code{link_order} structures, or it may be +done by stepping through the @code{input_bfds} list. + +The @code{_bfd_final_link} routine must also traverse the global +hash table to gather all the externally visible symbols. It +is possible that most of the externally visible symbols may be +written out when considering the symbols of each input file, +but it is still necessary to traverse the hash table since the +linker script may have defined some symbols that are not in +any of the input files. + +The @code{strip} field of the @code{bfd_link_info} structure +controls which symbols are written out. The possible values +are listed in @code{bfdlink.h}. If the value is @code{strip_some}, +then the @code{keep_hash} field of the @code{bfd_link_info} +structure is a hash table of symbols to keep; each symbol +should be looked up in this hash table, and only symbols which +are present should be included in the output file. + +If the @code{strip} field of the @code{bfd_link_info} structure +permits local symbols to be written out, the @code{discard} field +is used to further controls which local symbols are included +in the output file. If the value is @code{discard_l}, then all +local symbols which begin with a certain prefix are discarded; +this is controlled by the @code{bfd_is_local_label_name} entry point. + +The a.out backend handles symbols by calling +@code{aout_link_write_symbols} on each input BFD and then +traversing the global hash table with the function +@code{aout_link_write_other_symbol}. It builds a string table +while writing out the symbols, which is written to the output +file at the end of @code{NAME(aout,final_link)}. + +@findex bfd_link_split_section +@subsubsection @code{bfd_link_split_section} +@strong{Synopsis} +@example +bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec); +@end example +@strong{Description}@* +Return nonzero if @var{sec} should be split during a +reloceatable or final link. +@example +#define bfd_link_split_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) + +@end example + +@findex bfd_section_already_linked +@subsubsection @code{bfd_section_already_linked} +@strong{Synopsis} +@example +bfd_boolean bfd_section_already_linked (bfd *abfd, + asection *sec, + struct bfd_link_info *info); +@end example +@strong{Description}@* +Check if @var{data} has been already linked during a reloceatable +or final link. Return TRUE if it has. +@example +#define bfd_section_already_linked(abfd, sec, info) \ + BFD_SEND (abfd, _section_already_linked, (abfd, sec, info)) + +@end example + +@findex bfd_generic_define_common_symbol +@subsubsection @code{bfd_generic_define_common_symbol} +@strong{Synopsis} +@example +bfd_boolean bfd_generic_define_common_symbol + (bfd *output_bfd, struct bfd_link_info *info, + struct bfd_link_hash_entry *h); +@end example +@strong{Description}@* +Convert common symbol @var{h} into a defined symbol. +Return TRUE on success and FALSE on failure. +@example +#define bfd_define_common_symbol(output_bfd, info, h) \ + BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h)) + +@end example + +@findex bfd_find_version_for_sym +@subsubsection @code{bfd_find_version_for_sym } +@strong{Synopsis} +@example +struct bfd_elf_version_tree * bfd_find_version_for_sym + (struct bfd_elf_version_tree *verdefs, + const char *sym_name, bfd_boolean *hide); +@end example +@strong{Description}@* +Search an elf version script tree for symbol versioning +info and export / don't-export status for a given symbol. +Return non-NULL on success and NULL on failure; also sets +the output @samp{hide} boolean parameter. + +@findex bfd_hide_sym_by_version +@subsubsection @code{bfd_hide_sym_by_version} +@strong{Synopsis} +@example +bfd_boolean bfd_hide_sym_by_version + (struct bfd_elf_version_tree *verdefs, const char *sym_name); +@end example +@strong{Description}@* +Search an elf version script tree for symbol versioning +info for a given symbol. Return TRUE if the symbol is hidden. + |