| This is bfd.info, produced by makeinfo version 4.0 from bfd.texinfo. |
| |
| START-INFO-DIR-ENTRY |
| * Bfd: (bfd). The Binary File Descriptor library. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the BFD library. |
| |
| Copyright (C) 1991, 2000 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.1 |
| or any later version published by the Free Software Foundation; |
| with no Invariant Sections, with no Front-Cover Texts, and with no |
| Back-Cover Texts. A copy of the license is included in the |
| section entitled "GNU Free Documentation License". |
| |
| |
| File: bfd.info, Node: Linker Functions, Next: Hash Tables, Prev: File Caching, Up: BFD front end |
| |
| Linker Functions |
| ================ |
| |
| 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 |
| `struct bfd_link_info' structure (defined in `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 `linker.c', and use the header |
| file `genlink.h'. As of this writing, the only back ends which have |
| implemented versions of these routines are a.out (in `aoutx.h') and |
| ECOFF (in `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:: |
| |
| |
| File: bfd.info, Node: Creating a Linker Hash Table, Next: Adding Symbols to the Hash Table, Prev: Linker Functions, Up: Linker Functions |
| |
| Creating a linker hash table |
| ---------------------------- |
| |
| The linker routines must create a hash table, which must be derived |
| from `struct bfd_link_hash_table' described in `bfdlink.c'. *Note 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 `_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 `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 relocateable 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 `struct bfd_link_hash_table'. |
| The a.out linker hash table is created by the function |
| `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. |
| |
| |
| File: bfd.info, Node: Adding Symbols to the Hash Table, Next: Performing the Final Link, Prev: Creating a Linker Hash Table, Up: Linker Functions |
| |
| Adding symbols to the hash table |
| -------------------------------- |
| |
| The linker proper will call the `_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 |
| `NAME(aout,link_add_symbols)'. |
| |
| * Menu: |
| |
| * Differing file formats:: |
| * Adding symbols from an object file:: |
| * Adding symbols from an archive:: |
| |
| |
| File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table |
| |
| 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 |
| `_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 `_bfd_link_hash_table_create' vector. All the |
| `_bfd_link_add_symbols' function can assume about the hash table is |
| that it is derived from `struct bfd_link_hash_table'. |
| |
| Sometimes the `_bfd_link_add_symbols' function must store some |
| information in the hash table entry to be used by the `_bfd_final_link' |
| function. In such a case the `creator' field of the hash table must be |
| checked to make sure that the hash table was created by an object file |
| of the same format. |
| |
| The `_bfd_final_link' routine must be prepared to handle a hash |
| entry without any extra information added by the |
| `_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 `ecoff_link_add_externals' for an example of how to check the |
| `creator' field before saving information (in this case, the ECOFF |
| external symbol debugging information) in a hash table entry. |
| |
| |
| File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table |
| |
| Adding symbols from an object file |
| .................................. |
| |
| When the `_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 `_bfd_generic_link_add_one_symbol'. |
| The `_bfd_link_add_symbols' routine is responsible for reading all the |
| symbols from the object file and passing the correct information to |
| `_bfd_generic_link_add_one_symbol'. |
| |
| The `_bfd_link_add_symbols' routine should not use |
| `bfd_canonicalize_symtab' to read the symbols. The point of providing |
| this routine is to avoid the overhead of converting the symbols into |
| generic `asymbol' structures. |
| |
| `_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 |
| `BSF_WEAK' or `BSF_INDIRECT'. The section is a section in the object |
| file, or something like `bfd_und_section_ptr' for an undefined symbol |
| or `bfd_com_section_ptr' for a common symbol. |
| |
| If the `_bfd_final_link' routine is also going to need to read the |
| symbol information, the `_bfd_link_add_symbols' routine should save it |
| somewhere attached to the object file BFD. However, the information |
| should only be saved if the `keep_memory' field of the `info' argument |
| is true, so that the `-no-keep-memory' linker switch is effective. |
| |
| The a.out function which adds symbols from an object file is |
| `aout_link_add_object_symbols', and most of the interesting work is in |
| `aout_link_add_symbols'. The latter saves pointers to the hash tables |
| entries created by `_bfd_generic_link_add_one_symbol' indexed by symbol |
| number, so that the `_bfd_final_link' routine does not have to call the |
| hash table lookup routine to locate the entry. |
| |
| |
| File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table |
| |
| Adding symbols from an archive |
| .............................. |
| |
| When the `_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 `add_archive_element' linker callback, and it |
| must add the symbols from the object file to the linker hash table. |
| |
| In most cases the work of looking through the symbols in the archive |
| should be done by the `_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. `_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 `_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 `add_archive_element' linker callback routine must be |
| called with the element as an argument, and the elements symbols must |
| be added to the linker hash table just as though the element had itself |
| been passed to the `_bfd_link_add_symbols' function. |
| |
| When the a.out `_bfd_link_add_symbols' function receives an archive, |
| it calls `_bfd_generic_link_add_archive_symbols' passing |
| `aout_link_check_archive_element' as the function argument. |
| `aout_link_check_archive_element' calls `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 `add_archive_element' callback and then |
| `aout_link_check_archive_element' calls `aout_link_add_symbols' to |
| actually add the symbols to the linker hash table. |
| |
| The ECOFF back end is unusual in that it does not normally call |
| `_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. |
| |
| |
| File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions |
| |
| Performing the final link |
| ------------------------- |
| |
| When all the input files have been processed, the linker calls the |
| `_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 relocateable 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 `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 `_bfd_final_link' routine is |
| `NAME(aout,final_link)'. |
| |
| * Menu: |
| |
| * Information provided by the linker:: |
| * Relocating the section contents:: |
| * Writing the symbol table:: |
| |
| |
| File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link |
| |
| Information provided by the linker |
| .................................. |
| |
| Before the linker calls the `_bfd_final_link' entry point, it sets |
| up some data structures for the function to use. |
| |
| The `input_bfds' field of the `bfd_link_info' structure will point |
| to a list of all the input files included in the link. These files are |
| linked through the `link_next' field of the `bfd' structure. |
| |
| Each section in the output file will have a list of `link_order' |
| structures attached to the `link_order_head' field (the `link_order' |
| structure is defined in `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 relocateable |
| object file. |
| |
| |
| File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link |
| |
| Relocating the section contents |
| ............................... |
| |
| The `_bfd_final_link' function should look through the `link_order' |
| structures attached to each section of the output file. Each |
| `link_order' structure should either be handled specially, or it should |
| be passed to the function `_bfd_default_link_order' which will do the |
| right thing (`_bfd_default_link_order' is defined in `linker.c'). |
| |
| For efficiency, a `link_order' of type `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 `link_order' |
| describes part of an output section in terms of a section belonging to |
| one of the input files. The `_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 relocateable link, the relocs themselves must also be |
| modified and written out. |
| |
| The functions `_bfd_relocate_contents' and |
| `_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 |
| `reloc_howto_type' argument which describes the relocation to perform. |
| These functions are defined in `reloc.c'. |
| |
| The a.out function which handles reading, relocating, and writing |
| section contents is `aout_link_input_section'. The actual relocation |
| is done in `aout_link_input_section_std' and |
| `aout_link_input_section_ext'. |
| |
| |
| File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link |
| |
| Writing the symbol table |
| ........................ |
| |
| The `_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 `strip' and |
| `discard' fields of the `bfd_link_info' structure. |
| |
| The local symbols of the input files will not have been entered into |
| the linker hash table. The `_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 `link_order' structures, |
| or it may be done by stepping through the `input_bfds' list. |
| |
| The `_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 `strip' field of the `bfd_link_info' structure controls which |
| symbols are written out. The possible values are listed in |
| `bfdlink.h'. If the value is `strip_some', then the `keep_hash' field |
| of the `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 `strip' field of the `bfd_link_info' structure permits local |
| symbols to be written out, the `discard' field is used to further |
| controls which local symbols are included in the output file. If the |
| value is `discard_l', then all local symbols which begin with a certain |
| prefix are discarded; this is controlled by the |
| `bfd_is_local_label_name' entry point. |
| |
| The a.out backend handles symbols by calling |
| `aout_link_write_symbols' on each input BFD and then traversing the |
| global hash table with the function `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 `NAME(aout,final_link)'. |
| |
| `bfd_link_split_section' |
| ........................ |
| |
| *Synopsis* |
| boolean bfd_link_split_section(bfd *abfd, asection *sec); |
| *Description* |
| Return nonzero if SEC should be split during a reloceatable or final |
| link. |
| #define bfd_link_split_section(abfd, sec) \ |
| BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) |
| |
| |
| File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end |
| |
| Hash Tables |
| =========== |
| |
| BFD provides a simple set of hash table functions. Routines are |
| provided to initialize a hash table, to free a hash table, to look up a |
| string in a hash table and optionally create an entry for it, and to |
| traverse a hash table. There is currently no routine to delete an |
| string from a hash table. |
| |
| The basic hash table does not permit any data to be stored with a |
| string. However, a hash table is designed to present a base class from |
| which other types of hash tables may be derived. These derived types |
| may store additional information with the string. Hash tables were |
| implemented in this way, rather than simply providing a data pointer in |
| a hash table entry, because they were designed for use by the linker |
| back ends. The linker may create thousands of hash table entries, and |
| the overhead of allocating private data and storing and following |
| pointers becomes noticeable. |
| |
| The basic hash table code is in `hash.c'. |
| |
| * Menu: |
| |
| * Creating and Freeing a Hash Table:: |
| * Looking Up or Entering a String:: |
| * Traversing a Hash Table:: |
| * Deriving a New Hash Table Type:: |
| |
| |
| File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables |
| |
| Creating and freeing a hash table |
| --------------------------------- |
| |
| To create a hash table, create an instance of a `struct |
| bfd_hash_table' (defined in `bfd.h') and call `bfd_hash_table_init' (if |
| you know approximately how many entries you will need, the function |
| `bfd_hash_table_init_n', which takes a SIZE argument, may be used). |
| `bfd_hash_table_init' returns `false' if some sort of error occurs. |
| |
| The function `bfd_hash_table_init' take as an argument a function to |
| use to create new entries. For a basic hash table, use the function |
| `bfd_hash_newfunc'. *Note Deriving a New Hash Table Type::, for why |
| you would want to use a different value for this argument. |
| |
| `bfd_hash_table_init' will create an objalloc which will be used to |
| allocate new entries. You may allocate memory on this objalloc using |
| `bfd_hash_allocate'. |
| |
| Use `bfd_hash_table_free' to free up all the memory that has been |
| allocated for a hash table. This will not free up the `struct |
| bfd_hash_table' itself, which you must provide. |
| |
| |
| File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables |
| |
| Looking up or entering a string |
| ------------------------------- |
| |
| The function `bfd_hash_lookup' is used both to look up a string in |
| the hash table and to create a new entry. |
| |
| If the CREATE argument is `false', `bfd_hash_lookup' will look up a |
| string. If the string is found, it will returns a pointer to a `struct |
| bfd_hash_entry'. If the string is not found in the table |
| `bfd_hash_lookup' will return `NULL'. You should not modify any of the |
| fields in the returns `struct bfd_hash_entry'. |
| |
| If the CREATE argument is `true', the string will be entered into |
| the hash table if it is not already there. Either way a pointer to a |
| `struct bfd_hash_entry' will be returned, either to the existing |
| structure or to a newly created one. In this case, a `NULL' return |
| means that an error occurred. |
| |
| If the CREATE argument is `true', and a new entry is created, the |
| COPY argument is used to decide whether to copy the string onto the |
| hash table objalloc or not. If COPY is passed as `false', you must be |
| careful not to deallocate or modify the string as long as the hash table |
| exists. |
| |
| |
| File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables |
| |
| Traversing a hash table |
| ----------------------- |
| |
| The function `bfd_hash_traverse' may be used to traverse a hash |
| table, calling a function on each element. The traversal is done in a |
| random order. |
| |
| `bfd_hash_traverse' takes as arguments a function and a generic |
| `void *' pointer. The function is called with a hash table entry (a |
| `struct bfd_hash_entry *') and the generic pointer passed to |
| `bfd_hash_traverse'. The function must return a `boolean' value, which |
| indicates whether to continue traversing the hash table. If the |
| function returns `false', `bfd_hash_traverse' will stop the traversal |
| and return immediately. |
| |
| |
| File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables |
| |
| Deriving a new hash table type |
| ------------------------------ |
| |
| Many uses of hash tables want to store additional information which |
| each entry in the hash table. Some also find it convenient to store |
| additional information with the hash table itself. This may be done |
| using a derived hash table. |
| |
| Since C is not an object oriented language, creating a derived hash |
| table requires sticking together some boilerplate routines with a few |
| differences specific to the type of hash table you want to create. |
| |
| An example of a derived hash table is the linker hash table. The |
| structures for this are defined in `bfdlink.h'. The functions are in |
| `linker.c'. |
| |
| You may also derive a hash table from an already derived hash table. |
| For example, the a.out linker backend code uses a hash table derived |
| from the linker hash table. |
| |
| * Menu: |
| |
| * Define the Derived Structures:: |
| * Write the Derived Creation Routine:: |
| * Write Other Derived Routines:: |
| |
| |
| File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type |
| |
| Define the derived structures |
| ............................. |
| |
| You must define a structure for an entry in the hash table, and a |
| structure for the hash table itself. |
| |
| The first field in the structure for an entry in the hash table must |
| be of the type used for an entry in the hash table you are deriving |
| from. If you are deriving from a basic hash table this is `struct |
| bfd_hash_entry', which is defined in `bfd.h'. The first field in the |
| structure for the hash table itself must be of the type of the hash |
| table you are deriving from itself. If you are deriving from a basic |
| hash table, this is `struct bfd_hash_table'. |
| |
| For example, the linker hash table defines `struct |
| bfd_link_hash_entry' (in `bfdlink.h'). The first field, `root', is of |
| type `struct bfd_hash_entry'. Similarly, the first field in `struct |
| bfd_link_hash_table', `table', is of type `struct bfd_hash_table'. |
| |
| |
| File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type |
| |
| Write the derived creation routine |
| .................................. |
| |
| You must write a routine which will create and initialize an entry |
| in the hash table. This routine is passed as the function argument to |
| `bfd_hash_table_init'. |
| |
| In order to permit other hash tables to be derived from the hash |
| table you are creating, this routine must be written in a standard way. |
| |
| The first argument to the creation routine is a pointer to a hash |
| table entry. This may be `NULL', in which case the routine should |
| allocate the right amount of space. Otherwise the space has already |
| been allocated by a hash table type derived from this one. |
| |
| After allocating space, the creation routine must call the creation |
| routine of the hash table type it is derived from, passing in a pointer |
| to the space it just allocated. This will initialize any fields used |
| by the base hash table. |
| |
| Finally the creation routine must initialize any local fields for |
| the new hash table type. |
| |
| Here is a boilerplate example of a creation routine. FUNCTION_NAME |
| is the name of the routine. ENTRY_TYPE is the type of an entry in the |
| hash table you are creating. BASE_NEWFUNC is the name of the creation |
| routine of the hash table type your hash table is derived from. |
| |
| struct bfd_hash_entry * |
| FUNCTION_NAME (entry, table, string) |
| struct bfd_hash_entry *entry; |
| struct bfd_hash_table *table; |
| const char *string; |
| { |
| struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry; |
| |
| /* Allocate the structure if it has not already been allocated by a |
| derived class. */ |
| if (ret == (ENTRY_TYPE *) NULL) |
| { |
| ret = ((ENTRY_TYPE *) |
| bfd_hash_allocate (table, sizeof (ENTRY_TYPE))); |
| if (ret == (ENTRY_TYPE *) NULL) |
| return NULL; |
| } |
| |
| /* Call the allocation method of the base class. */ |
| ret = ((ENTRY_TYPE *) |
| BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string)); |
| |
| /* Initialize the local fields here. */ |
| |
| return (struct bfd_hash_entry *) ret; |
| } |
| *Description* |
| The creation routine for the linker hash table, which is in `linker.c', |
| looks just like this example. FUNCTION_NAME is |
| `_bfd_link_hash_newfunc'. ENTRY_TYPE is `struct bfd_link_hash_entry'. |
| BASE_NEWFUNC is `bfd_hash_newfunc', the creation routine for a basic |
| hash table. |
| |
| `_bfd_link_hash_newfunc' also initializes the local fields in a |
| linker hash table entry: `type', `written' and `next'. |
| |
| |
| File: bfd.info, Node: Write Other Derived Routines, Prev: Write the Derived Creation Routine, Up: Deriving a New Hash Table Type |
| |
| Write other derived routines |
| ............................ |
| |
| You will want to write other routines for your new hash table, as |
| well. |
| |
| You will want an initialization routine which calls the |
| initialization routine of the hash table you are deriving from and |
| initializes any other local fields. For the linker hash table, this is |
| `_bfd_link_hash_table_init' in `linker.c'. |
| |
| You will want a lookup routine which calls the lookup routine of the |
| hash table you are deriving from and casts the result. The linker hash |
| table uses `bfd_link_hash_lookup' in `linker.c' (this actually takes an |
| additional argument which it uses to decide how to return the looked up |
| value). |
| |
| You may want a traversal routine. This should just call the |
| traversal routine of the hash table you are deriving from with |
| appropriate casts. The linker hash table uses `bfd_link_hash_traverse' |
| in `linker.c'. |
| |
| These routines may simply be defined as macros. For example, the |
| a.out backend linker hash table, which is derived from the linker hash |
| table, uses macros for the lookup and traversal routines. These are |
| `aout_link_hash_lookup' and `aout_link_hash_traverse' in aoutx.h. |
| |
| |
| File: bfd.info, Node: BFD back ends, Next: GNU Free Documentation License, Prev: BFD front end, Up: Top |
| |
| BFD back ends |
| ************* |
| |
| * Menu: |
| |
| * What to Put Where:: |
| * aout :: a.out backends |
| * coff :: coff backends |
| * elf :: elf backends |
| |
| |
| File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back ends, Up: BFD back ends |
| |
| All of BFD lives in one directory. |
| |
| |
| File: bfd.info, Node: aout, Next: coff, Prev: What to Put Where, Up: BFD back ends |
| |
| a.out backends |
| ============== |
| |
| *Description* |
| BFD supports a number of different flavours of a.out format, though the |
| major differences are only the sizes of the structures on disk, and the |
| shape of the relocation information. |
| |
| The support is split into a basic support file `aoutx.h' and other |
| files which derive functions from the base. One derivation file is |
| `aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions |
| support for sun3, sun4, 386 and 29k a.out files, to create a target |
| jump vector for a specific target. |
| |
| This information is further split out into more specific files for |
| each machine, including `sunos.c' for sun3 and sun4, `newsos3.c' for |
| the Sony NEWS, and `demo64.c' for a demonstration of a 64 bit a.out |
| format. |
| |
| The base file `aoutx.h' defines general mechanisms for reading and |
| writing records to and from disk and various other methods which BFD |
| requires. It is included by `aout32.c' and `aout64.c' to form the names |
| `aout_32_swap_exec_header_in', `aout_64_swap_exec_header_in', etc. |
| |
| As an example, this is what goes on to make the back end for a sun4, |
| from `aout32.c': |
| |
| #define ARCH_SIZE 32 |
| #include "aoutx.h" |
| |
| Which exports names: |
| |
| ... |
| aout_32_canonicalize_reloc |
| aout_32_find_nearest_line |
| aout_32_get_lineno |
| aout_32_get_reloc_upper_bound |
| ... |
| |
| from `sunos.c': |
| |
| #define TARGET_NAME "a.out-sunos-big" |
| #define VECNAME sunos_big_vec |
| #include "aoutf1.h" |
| |
| requires all the names from `aout32.c', and produces the jump vector |
| |
| sunos_big_vec |
| |
| The file `host-aout.c' is a special case. It is for a large set of |
| hosts that use "more or less standard" a.out files, and for which |
| cross-debugging is not interesting. It uses the standard 32-bit a.out |
| support routines, but determines the file offsets and addresses of the |
| text, data, and BSS sections, the machine architecture and machine |
| type, and the entry point address, in a host-dependent manner. Once |
| these values have been determined, generic code is used to handle the |
| object file. |
| |
| When porting it to run on a new system, you must supply: |
| |
| HOST_PAGE_SIZE |
| HOST_SEGMENT_SIZE |
| HOST_MACHINE_ARCH (optional) |
| HOST_MACHINE_MACHINE (optional) |
| HOST_TEXT_START_ADDR |
| HOST_STACK_END_ADDR |
| |
| in the file `../include/sys/h-XXX.h' (for your host). These values, |
| plus the structures and macros defined in `a.out.h' on your host |
| system, will produce a BFD target that will access ordinary a.out files |
| on your host. To configure a new machine to use `host-aout.c', specify: |
| |
| TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec |
| TDEPFILES= host-aout.o trad-core.o |
| |
| in the `config/XXX.mt' file, and modify `configure.in' to use the |
| `XXX.mt' file (by setting "`bfd_target=XXX'") when your configuration |
| is selected. |
| |
| Relocations |
| ----------- |
| |
| *Description* |
| The file `aoutx.h' provides for both the _standard_ and _extended_ |
| forms of a.out relocation records. |
| |
| The standard records contain only an address, a symbol index, and a |
| type field. The extended records (used on 29ks and sparcs) also have a |
| full integer for an addend. |
| |
| Internal entry points |
| --------------------- |
| |
| *Description* |
| `aoutx.h' exports several routines for accessing the contents of an |
| a.out file, which are gathered and exported in turn by various format |
| specific files (eg sunos.c). |
| |
| `aout_SIZE_swap_exec_header_in' |
| ............................... |
| |
| *Synopsis* |
| void aout_SIZE_swap_exec_header_in, |
| (bfd *abfd, |
| struct external_exec *raw_bytes, |
| struct internal_exec *execp); |
| *Description* |
| Swap the information in an executable header RAW_BYTES taken from a raw |
| byte stream memory image into the internal exec header structure EXECP. |
| |
| `aout_SIZE_swap_exec_header_out' |
| ................................ |
| |
| *Synopsis* |
| void aout_SIZE_swap_exec_header_out |
| (bfd *abfd, |
| struct internal_exec *execp, |
| struct external_exec *raw_bytes); |
| *Description* |
| Swap the information in an internal exec header structure EXECP into |
| the buffer RAW_BYTES ready for writing to disk. |
| |
| `aout_SIZE_some_aout_object_p' |
| .............................. |
| |
| *Synopsis* |
| const bfd_target *aout_SIZE_some_aout_object_p |
| (bfd *abfd, |
| const bfd_target *(*callback_to_real_object_p) ()); |
| *Description* |
| Some a.out variant thinks that the file open in ABFD checking is an |
| a.out file. Do some more checking, and set up for access if it really |
| is. Call back to the calling environment's "finish up" function just |
| before returning, to handle any last-minute setup. |
| |
| `aout_SIZE_mkobject' |
| .................... |
| |
| *Synopsis* |
| boolean aout_SIZE_mkobject, (bfd *abfd); |
| *Description* |
| Initialize BFD ABFD for use with a.out files. |
| |
| `aout_SIZE_machine_type' |
| ........................ |
| |
| *Synopsis* |
| enum machine_type aout_SIZE_machine_type |
| (enum bfd_architecture arch, |
| unsigned long machine)); |
| *Description* |
| Keep track of machine architecture and machine type for a.out's. Return |
| the `machine_type' for a particular architecture and machine, or |
| `M_UNKNOWN' if that exact architecture and machine can't be represented |
| in a.out format. |
| |
| If the architecture is understood, machine type 0 (default) is |
| always understood. |
| |
| `aout_SIZE_set_arch_mach' |
| ......................... |
| |
| *Synopsis* |
| boolean aout_SIZE_set_arch_mach, |
| (bfd *, |
| enum bfd_architecture arch, |
| unsigned long machine)); |
| *Description* |
| Set the architecture and the machine of the BFD ABFD to the values ARCH |
| and MACHINE. Verify that ABFD's format can support the architecture |
| required. |
| |
| `aout_SIZE_new_section_hook' |
| ............................ |
| |
| *Synopsis* |
| boolean aout_SIZE_new_section_hook, |
| (bfd *abfd, |
| asection *newsect)); |
| *Description* |
| Called by the BFD in response to a `bfd_make_section' request. |
| |