| 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: coff, Next: elf, Prev: aout, Up: BFD back ends |
| |
| coff backends |
| ============= |
| |
| BFD supports a number of different flavours of coff format. The |
| major differences between formats are the sizes and alignments of |
| fields in structures on disk, and the occasional extra field. |
| |
| Coff in all its varieties is implemented with a few common files and |
| a number of implementation specific files. For example, The 88k bcs |
| coff format is implemented in the file `coff-m88k.c'. This file |
| `#include's `coff/m88k.h' which defines the external structure of the |
| coff format for the 88k, and `coff/internal.h' which defines the |
| internal structure. `coff-m88k.c' also defines the relocations used by |
| the 88k format *Note Relocations::. |
| |
| The Intel i960 processor version of coff is implemented in |
| `coff-i960.c'. This file has the same structure as `coff-m88k.c', |
| except that it includes `coff/i960.h' rather than `coff-m88k.h'. |
| |
| Porting to a new version of coff |
| -------------------------------- |
| |
| The recommended method is to select from the existing |
| implementations the version of coff which is most like the one you want |
| to use. For example, we'll say that i386 coff is the one you select, |
| and that your coff flavour is called foo. Copy `i386coff.c' to |
| `foocoff.c', copy `../include/coff/i386.h' to `../include/coff/foo.h', |
| and add the lines to `targets.c' and `Makefile.in' so that your new |
| back end is used. Alter the shapes of the structures in |
| `../include/coff/foo.h' so that they match what you need. You will |
| probably also have to add `#ifdef's to the code in `coff/internal.h' and |
| `coffcode.h' if your version of coff is too wild. |
| |
| You can verify that your new BFD backend works quite simply by |
| building `objdump' from the `binutils' directory, and making sure that |
| its version of what's going on and your host system's idea (assuming it |
| has the pretty standard coff dump utility, usually called `att-dump' or |
| just `dump') are the same. Then clean up your code, and send what |
| you've done to Cygnus. Then your stuff will be in the next release, and |
| you won't have to keep integrating it. |
| |
| How the coff backend works |
| -------------------------- |
| |
| File layout |
| ........... |
| |
| The Coff backend is split into generic routines that are applicable |
| to any Coff target and routines that are specific to a particular |
| target. The target-specific routines are further split into ones which |
| are basically the same for all Coff targets except that they use the |
| external symbol format or use different values for certain constants. |
| |
| The generic routines are in `coffgen.c'. These routines work for |
| any Coff target. They use some hooks into the target specific code; |
| the hooks are in a `bfd_coff_backend_data' structure, one of which |
| exists for each target. |
| |
| The essentially similar target-specific routines are in |
| `coffcode.h'. This header file includes executable C code. The |
| various Coff targets first include the appropriate Coff header file, |
| make any special defines that are needed, and then include `coffcode.h'. |
| |
| Some of the Coff targets then also have additional routines in the |
| target source file itself. |
| |
| For example, `coff-i960.c' includes `coff/internal.h' and |
| `coff/i960.h'. It then defines a few constants, such as `I960', and |
| includes `coffcode.h'. Since the i960 has complex relocation types, |
| `coff-i960.c' also includes some code to manipulate the i960 relocs. |
| This code is not in `coffcode.h' because it would not be used by any |
| other target. |
| |
| Bit twiddling |
| ............. |
| |
| Each flavour of coff supported in BFD has its own header file |
| describing the external layout of the structures. There is also an |
| internal description of the coff layout, in `coff/internal.h'. A major |
| function of the coff backend is swapping the bytes and twiddling the |
| bits to translate the external form of the structures into the normal |
| internal form. This is all performed in the `bfd_swap'_thing_direction |
| routines. Some elements are different sizes between different versions |
| of coff; it is the duty of the coff version specific include file to |
| override the definitions of various packing routines in `coffcode.h'. |
| E.g., the size of line number entry in coff is sometimes 16 bits, and |
| sometimes 32 bits. `#define'ing `PUT_LNSZ_LNNO' and `GET_LNSZ_LNNO' |
| will select the correct one. No doubt, some day someone will find a |
| version of coff which has a varying field size not catered to at the |
| moment. To port BFD, that person will have to add more `#defines'. |
| Three of the bit twiddling routines are exported to `gdb'; |
| `coff_swap_aux_in', `coff_swap_sym_in' and `coff_swap_lineno_in'. `GDB' |
| reads the symbol table on its own, but uses BFD to fix things up. More |
| of the bit twiddlers are exported for `gas'; `coff_swap_aux_out', |
| `coff_swap_sym_out', `coff_swap_lineno_out', `coff_swap_reloc_out', |
| `coff_swap_filehdr_out', `coff_swap_aouthdr_out', |
| `coff_swap_scnhdr_out'. `Gas' currently keeps track of all the symbol |
| table and reloc drudgery itself, thereby saving the internal BFD |
| overhead, but uses BFD to swap things on the way out, making cross |
| ports much safer. Doing so also allows BFD (and thus the linker) to |
| use the same header files as `gas', which makes one avenue to disaster |
| disappear. |
| |
| Symbol reading |
| .............. |
| |
| The simple canonical form for symbols used by BFD is not rich enough |
| to keep all the information available in a coff symbol table. The back |
| end gets around this problem by keeping the original symbol table |
| around, "behind the scenes". |
| |
| When a symbol table is requested (through a call to |
| `bfd_canonicalize_symtab'), a request gets through to |
| `coff_get_normalized_symtab'. This reads the symbol table from the coff |
| file and swaps all the structures inside into the internal form. It |
| also fixes up all the pointers in the table (represented in the file by |
| offsets from the first symbol in the table) into physical pointers to |
| elements in the new internal table. This involves some work since the |
| meanings of fields change depending upon context: a field that is a |
| pointer to another structure in the symbol table at one moment may be |
| the size in bytes of a structure at the next. Another pass is made |
| over the table. All symbols which mark file names (`C_FILE' symbols) |
| are modified so that the internal string points to the value in the |
| auxent (the real filename) rather than the normal text associated with |
| the symbol (`".file"'). |
| |
| At this time the symbol names are moved around. Coff stores all |
| symbols less than nine characters long physically within the symbol |
| table; longer strings are kept at the end of the file in the string |
| table. This pass moves all strings into memory and replaces them with |
| pointers to the strings. |
| |
| The symbol table is massaged once again, this time to create the |
| canonical table used by the BFD application. Each symbol is inspected |
| in turn, and a decision made (using the `sclass' field) about the |
| various flags to set in the `asymbol'. *Note Symbols::. The generated |
| canonical table shares strings with the hidden internal symbol table. |
| |
| Any linenumbers are read from the coff file too, and attached to the |
| symbols which own the functions the linenumbers belong to. |
| |
| Symbol writing |
| .............. |
| |
| Writing a symbol to a coff file which didn't come from a coff file |
| will lose any debugging information. The `asymbol' structure remembers |
| the BFD from which the symbol was taken, and on output the back end |
| makes sure that the same destination target as source target is present. |
| |
| When the symbols have come from a coff file then all the debugging |
| information is preserved. |
| |
| Symbol tables are provided for writing to the back end in a vector |
| of pointers to pointers. This allows applications like the linker to |
| accumulate and output large symbol tables without having to do too much |
| byte copying. |
| |
| This function runs through the provided symbol table and patches |
| each symbol marked as a file place holder (`C_FILE') to point to the |
| next file place holder in the list. It also marks each `offset' field |
| in the list with the offset from the first symbol of the current symbol. |
| |
| Another function of this procedure is to turn the canonical value |
| form of BFD into the form used by coff. Internally, BFD expects symbol |
| values to be offsets from a section base; so a symbol physically at |
| 0x120, but in a section starting at 0x100, would have the value 0x20. |
| Coff expects symbols to contain their final value, so symbols have |
| their values changed at this point to reflect their sum with their |
| owning section. This transformation uses the `output_section' field of |
| the `asymbol''s `asection' *Note Sections::. |
| |
| * `coff_mangle_symbols' |
| This routine runs though the provided symbol table and uses the |
| offsets generated by the previous pass and the pointers generated when |
| the symbol table was read in to create the structured hierachy required |
| by coff. It changes each pointer to a symbol into the index into the |
| symbol table of the asymbol. |
| |
| * `coff_write_symbols' |
| This routine runs through the symbol table and patches up the |
| symbols from their internal form into the coff way, calls the bit |
| twiddlers, and writes out the table to the file. |
| |
| `coff_symbol_type' |
| .................. |
| |
| *Description* |
| The hidden information for an `asymbol' is described in a |
| `combined_entry_type': |
| |
| |
| typedef struct coff_ptr_struct |
| { |
| |
| /* Remembers the offset from the first symbol in the file for |
| this symbol. Generated by coff_renumber_symbols. */ |
| unsigned int offset; |
| |
| /* Should the value of this symbol be renumbered. Used for |
| XCOFF C_BSTAT symbols. Set by coff_slurp_symbol_table. */ |
| unsigned int fix_value : 1; |
| |
| /* Should the tag field of this symbol be renumbered. |
| Created by coff_pointerize_aux. */ |
| unsigned int fix_tag : 1; |
| |
| /* Should the endidx field of this symbol be renumbered. |
| Created by coff_pointerize_aux. */ |
| unsigned int fix_end : 1; |
| |
| /* Should the x_csect.x_scnlen field be renumbered. |
| Created by coff_pointerize_aux. */ |
| unsigned int fix_scnlen : 1; |
| |
| /* Fix up an XCOFF C_BINCL/C_EINCL symbol. The value is the |
| index into the line number entries. Set by |
| coff_slurp_symbol_table. */ |
| unsigned int fix_line : 1; |
| |
| /* The container for the symbol structure as read and translated |
| from the file. */ |
| |
| union { |
| union internal_auxent auxent; |
| struct internal_syment syment; |
| } u; |
| } combined_entry_type; |
| |
| |
| /* Each canonical asymbol really looks like this: */ |
| |
| typedef struct coff_symbol_struct |
| { |
| /* The actual symbol which the rest of BFD works with */ |
| asymbol symbol; |
| |
| /* A pointer to the hidden information for this symbol */ |
| combined_entry_type *native; |
| |
| /* A pointer to the linenumber information for this symbol */ |
| struct lineno_cache_entry *lineno; |
| |
| /* Have the line numbers been relocated yet ? */ |
| boolean done_lineno; |
| } coff_symbol_type; |
| |
| `bfd_coff_backend_data' |
| ....................... |
| |
| /* COFF symbol classifications. */ |
| |
| enum coff_symbol_classification |
| { |
| /* Global symbol. */ |
| COFF_SYMBOL_GLOBAL, |
| /* Common symbol. */ |
| COFF_SYMBOL_COMMON, |
| /* Undefined symbol. */ |
| COFF_SYMBOL_UNDEFINED, |
| /* Local symbol. */ |
| COFF_SYMBOL_LOCAL, |
| /* PE section symbol. */ |
| COFF_SYMBOL_PE_SECTION |
| }; |
| Special entry points for gdb to swap in coff symbol table parts: |
| typedef struct |
| { |
| void (*_bfd_coff_swap_aux_in) PARAMS (( |
| bfd *abfd, |
| PTR ext, |
| int type, |
| int class, |
| int indaux, |
| int numaux, |
| PTR in)); |
| |
| void (*_bfd_coff_swap_sym_in) PARAMS (( |
| bfd *abfd , |
| PTR ext, |
| PTR in)); |
| |
| void (*_bfd_coff_swap_lineno_in) PARAMS (( |
| bfd *abfd, |
| PTR ext, |
| PTR in)); |
| Special entry points for gas to swap out coff parts: |
| unsigned int (*_bfd_coff_swap_aux_out) PARAMS (( |
| bfd *abfd, |
| PTR in, |
| int type, |
| int class, |
| int indaux, |
| int numaux, |
| PTR ext)); |
| |
| unsigned int (*_bfd_coff_swap_sym_out) PARAMS (( |
| bfd *abfd, |
| PTR in, |
| PTR ext)); |
| |
| unsigned int (*_bfd_coff_swap_lineno_out) PARAMS (( |
| bfd *abfd, |
| PTR in, |
| PTR ext)); |
| |
| unsigned int (*_bfd_coff_swap_reloc_out) PARAMS (( |
| bfd *abfd, |
| PTR src, |
| PTR dst)); |
| |
| unsigned int (*_bfd_coff_swap_filehdr_out) PARAMS (( |
| bfd *abfd, |
| PTR in, |
| PTR out)); |
| |
| unsigned int (*_bfd_coff_swap_aouthdr_out) PARAMS (( |
| bfd *abfd, |
| PTR in, |
| PTR out)); |
| |
| unsigned int (*_bfd_coff_swap_scnhdr_out) PARAMS (( |
| bfd *abfd, |
| PTR in, |
| PTR out)); |
| Special entry points for generic COFF routines to call target |
| dependent COFF routines: |
| unsigned int _bfd_filhsz; |
| unsigned int _bfd_aoutsz; |
| unsigned int _bfd_scnhsz; |
| unsigned int _bfd_symesz; |
| unsigned int _bfd_auxesz; |
| unsigned int _bfd_relsz; |
| unsigned int _bfd_linesz; |
| unsigned int _bfd_filnmlen; |
| boolean _bfd_coff_long_filenames; |
| boolean _bfd_coff_long_section_names; |
| unsigned int _bfd_coff_default_section_alignment_power; |
| boolean _bfd_coff_force_symnames_in_strings; |
| unsigned int _bfd_coff_debug_string_prefix_length; |
| void (*_bfd_coff_swap_filehdr_in) PARAMS (( |
| bfd *abfd, |
| PTR ext, |
| PTR in)); |
| void (*_bfd_coff_swap_aouthdr_in) PARAMS (( |
| bfd *abfd, |
| PTR ext, |
| PTR in)); |
| void (*_bfd_coff_swap_scnhdr_in) PARAMS (( |
| bfd *abfd, |
| PTR ext, |
| PTR in)); |
| void (*_bfd_coff_swap_reloc_in) PARAMS (( |
| bfd *abfd, |
| PTR ext, |
| PTR in)); |
| boolean (*_bfd_coff_bad_format_hook) PARAMS (( |
| bfd *abfd, |
| PTR internal_filehdr)); |
| boolean (*_bfd_coff_set_arch_mach_hook) PARAMS (( |
| bfd *abfd, |
| PTR internal_filehdr)); |
| PTR (*_bfd_coff_mkobject_hook) PARAMS (( |
| bfd *abfd, |
| PTR internal_filehdr, |
| PTR internal_aouthdr)); |
| flagword (*_bfd_styp_to_sec_flags_hook) PARAMS (( |
| bfd *abfd, |
| PTR internal_scnhdr, |
| const char *name, |
| asection *section)); |
| void (*_bfd_set_alignment_hook) PARAMS (( |
| bfd *abfd, |
| asection *sec, |
| PTR internal_scnhdr)); |
| boolean (*_bfd_coff_slurp_symbol_table) PARAMS (( |
| bfd *abfd)); |
| boolean (*_bfd_coff_symname_in_debug) PARAMS (( |
| bfd *abfd, |
| struct internal_syment *sym)); |
| boolean (*_bfd_coff_pointerize_aux_hook) PARAMS (( |
| bfd *abfd, |
| combined_entry_type *table_base, |
| combined_entry_type *symbol, |
| unsigned int indaux, |
| combined_entry_type *aux)); |
| boolean (*_bfd_coff_print_aux) PARAMS (( |
| bfd *abfd, |
| FILE *file, |
| combined_entry_type *table_base, |
| combined_entry_type *symbol, |
| combined_entry_type *aux, |
| unsigned int indaux)); |
| void (*_bfd_coff_reloc16_extra_cases) PARAMS (( |
| bfd *abfd, |
| struct bfd_link_info *link_info, |
| struct bfd_link_order *link_order, |
| arelent *reloc, |
| bfd_byte *data, |
| unsigned int *src_ptr, |
| unsigned int *dst_ptr)); |
| int (*_bfd_coff_reloc16_estimate) PARAMS (( |
| bfd *abfd, |
| asection *input_section, |
| arelent *r, |
| unsigned int shrink, |
| struct bfd_link_info *link_info)); |
| enum coff_symbol_classification (*_bfd_coff_classify_symbol) PARAMS (( |
| bfd *abfd, |
| struct internal_syment *)); |
| boolean (*_bfd_coff_compute_section_file_positions) PARAMS (( |
| bfd *abfd)); |
| boolean (*_bfd_coff_start_final_link) PARAMS (( |
| bfd *output_bfd, |
| struct bfd_link_info *info)); |
| boolean (*_bfd_coff_relocate_section) PARAMS (( |
| bfd *output_bfd, |
| struct bfd_link_info *info, |
| bfd *input_bfd, |
| asection *input_section, |
| bfd_byte *contents, |
| struct internal_reloc *relocs, |
| struct internal_syment *syms, |
| asection **sections)); |
| reloc_howto_type *(*_bfd_coff_rtype_to_howto) PARAMS (( |
| bfd *abfd, |
| asection *sec, |
| struct internal_reloc *rel, |
| struct coff_link_hash_entry *h, |
| struct internal_syment *sym, |
| bfd_vma *addendp)); |
| boolean (*_bfd_coff_adjust_symndx) PARAMS (( |
| bfd *obfd, |
| struct bfd_link_info *info, |
| bfd *ibfd, |
| asection *sec, |
| struct internal_reloc *reloc, |
| boolean *adjustedp)); |
| boolean (*_bfd_coff_link_add_one_symbol) PARAMS (( |
| struct bfd_link_info *info, |
| bfd *abfd, |
| const char *name, |
| flagword flags, |
| asection *section, |
| bfd_vma value, |
| const char *string, |
| boolean copy, |
| boolean collect, |
| struct bfd_link_hash_entry **hashp)); |
| |
| boolean (*_bfd_coff_link_output_has_begun) PARAMS (( |
| bfd * abfd, |
| struct coff_final_link_info * pfinfo)); |
| boolean (*_bfd_coff_final_link_postscript) PARAMS (( |
| bfd * abfd, |
| struct coff_final_link_info * pfinfo)); |
| |
| } bfd_coff_backend_data; |
| |
| #define coff_backend_info(abfd) ((bfd_coff_backend_data *) (abfd)->xvec->backend_data) |
| |
| #define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \ |
| ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i)) |
| |
| #define bfd_coff_swap_sym_in(a,e,i) \ |
| ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i)) |
| |
| #define bfd_coff_swap_lineno_in(a,e,i) \ |
| ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i)) |
| |
| #define bfd_coff_swap_reloc_out(abfd, i, o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o)) |
| |
| #define bfd_coff_swap_lineno_out(abfd, i, o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o)) |
| |
| #define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \ |
| ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o)) |
| |
| #define bfd_coff_swap_sym_out(abfd, i,o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o)) |
| |
| #define bfd_coff_swap_scnhdr_out(abfd, i,o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o)) |
| |
| #define bfd_coff_swap_filehdr_out(abfd, i,o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o)) |
| |
| #define bfd_coff_swap_aouthdr_out(abfd, i,o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o)) |
| |
| #define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz) |
| #define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz) |
| #define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz) |
| #define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz) |
| #define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz) |
| #define bfd_coff_relsz(abfd) (coff_backend_info (abfd)->_bfd_relsz) |
| #define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz) |
| #define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen) |
| #define bfd_coff_long_filenames(abfd) (coff_backend_info (abfd)->_bfd_coff_long_filenames) |
| #define bfd_coff_long_section_names(abfd) \ |
| (coff_backend_info (abfd)->_bfd_coff_long_section_names) |
| #define bfd_coff_default_section_alignment_power(abfd) \ |
| (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power) |
| #define bfd_coff_swap_filehdr_in(abfd, i,o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o)) |
| |
| #define bfd_coff_swap_aouthdr_in(abfd, i,o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o)) |
| |
| #define bfd_coff_swap_scnhdr_in(abfd, i,o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o)) |
| |
| #define bfd_coff_swap_reloc_in(abfd, i, o) \ |
| ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o)) |
| |
| #define bfd_coff_bad_format_hook(abfd, filehdr) \ |
| ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr)) |
| |
| #define bfd_coff_set_arch_mach_hook(abfd, filehdr)\ |
| ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr)) |
| #define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\ |
| ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook) (abfd, filehdr, aouthdr)) |
| |
| #define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section)\ |
| ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\ |
| (abfd, scnhdr, name, section)) |
| |
| #define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\ |
| ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr)) |
| |
| #define bfd_coff_slurp_symbol_table(abfd)\ |
| ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd)) |
| |
| #define bfd_coff_symname_in_debug(abfd, sym)\ |
| ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym)) |
| |
| #define bfd_coff_force_symnames_in_strings(abfd)\ |
| (coff_backend_info (abfd)->_bfd_coff_force_symnames_in_strings) |
| |
| #define bfd_coff_debug_string_prefix_length(abfd)\ |
| (coff_backend_info (abfd)->_bfd_coff_debug_string_prefix_length) |
| |
| #define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\ |
| ((coff_backend_info (abfd)->_bfd_coff_print_aux)\ |
| (abfd, file, base, symbol, aux, indaux)) |
| |
| #define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr)\ |
| ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\ |
| (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr)) |
| |
| #define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\ |
| ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\ |
| (abfd, section, reloc, shrink, link_info)) |
| |
| #define bfd_coff_classify_symbol(abfd, sym)\ |
| ((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\ |
| (abfd, sym)) |
| |
| #define bfd_coff_compute_section_file_positions(abfd)\ |
| ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\ |
| (abfd)) |
| |
| #define bfd_coff_start_final_link(obfd, info)\ |
| ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\ |
| (obfd, info)) |
| #define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\ |
| ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\ |
| (obfd, info, ibfd, o, con, rel, isyms, secs)) |
| #define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\ |
| ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\ |
| (abfd, sec, rel, h, sym, addendp)) |
| #define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\ |
| ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\ |
| (obfd, info, ibfd, sec, rel, adjustedp)) |
| #define bfd_coff_link_add_one_symbol(info,abfd,name,flags,section,value,string,cp,coll,hashp)\ |
| ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\ |
| (info, abfd, name, flags, section, value, string, cp, coll, hashp)) |
| |
| #define bfd_coff_link_output_has_begun(a,p) \ |
| ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a,p)) |
| #define bfd_coff_final_link_postscript(a,p) \ |
| ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a,p)) |
| |
| Writing relocations |
| ................... |
| |
| To write relocations, the back end steps though the canonical |
| relocation table and create an `internal_reloc'. The symbol index to |
| use is removed from the `offset' field in the symbol table supplied. |
| The address comes directly from the sum of the section base address and |
| the relocation offset; the type is dug directly from the howto field. |
| Then the `internal_reloc' is swapped into the shape of an |
| `external_reloc' and written out to disk. |
| |
| Reading linenumbers |
| ................... |
| |
| Creating the linenumber table is done by reading in the entire coff |
| linenumber table, and creating another table for internal use. |
| |
| A coff linenumber table is structured so that each function is |
| marked as having a line number of 0. Each line within the function is |
| an offset from the first line in the function. The base of the line |
| number information for the table is stored in the symbol associated |
| with the function. |
| |
| Note: The PE format uses line number 0 for a flag indicating a new |
| source file. |
| |
| The information is copied from the external to the internal table, |
| and each symbol which marks a function is marked by pointing its... |
| |
| How does this work ? |
| |
| Reading relocations |
| ................... |
| |
| Coff relocations are easily transformed into the internal BFD form |
| (`arelent'). |
| |
| Reading a coff relocation table is done in the following stages: |
| |
| * Read the entire coff relocation table into memory. |
| |
| * Process each relocation in turn; first swap it from the external |
| to the internal form. |
| |
| * Turn the symbol referenced in the relocation's symbol index into a |
| pointer into the canonical symbol table. This table is the same |
| as the one returned by a call to `bfd_canonicalize_symtab'. The |
| back end will call that routine and save the result if a |
| canonicalization hasn't been done. |
| |
| * The reloc index is turned into a pointer to a howto structure, in |
| a back end specific way. For instance, the 386 and 960 use the |
| `r_type' to directly produce an index into a howto table vector; |
| the 88k subtracts a number from the `r_type' field and creates an |
| addend field. |
| |
| |
| File: bfd.info, Node: elf, Prev: coff, Up: BFD back ends |
| |
| ELF backends |
| ============ |
| |
| BFD support for ELF formats is being worked on. Currently, the best |
| supported back ends are for sparc and i386 (running svr4 or Solaris 2). |
| |
| Documentation of the internals of the support code still needs to be |
| written. The code is changing quickly enough that we haven't bothered |
| yet. |
| |
| `bfd_elf_find_section' |
| ...................... |
| |
| *Synopsis* |
| struct elf_internal_shdr *bfd_elf_find_section (bfd *abfd, char *name); |
| *Description* |
| Helper functions for GDB to locate the string tables. Since BFD hides |
| string tables from callers, GDB needs to use an internal hook to find |
| them. Sun's .stabstr, in particular, isn't even pointed to by the |
| .stab section, so ordinary mechanisms wouldn't work to find it, even if |
| we had some. |
| |
| |
| File: bfd.info, Node: GNU Free Documentation License, Next: Index, Prev: BFD back ends, Up: Top |
| |
| GNU Free Documentation License |
| ****************************** |
| |
| GNU Free Documentation License |
| |
| Version 1.1, March 2000 |
| |
| Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple |
| Place, Suite 330, Boston, MA 02111-1307 USA |
| |
| Everyone is permitted to copy and distribute verbatim copies of |
| this license document, but changing it is not allowed. |
| |
| 0. PREAMBLE |
| |
| The purpose of this License is to make a manual, textbook, or other |
| written document "free" in the sense of freedom: to assure everyone the |
| effective freedom to copy and redistribute it, with or without |
| modifying it, either commercially or noncommercially. Secondarily, |
| this License preserves for the author and publisher a way to get credit |
| for their work, while not being considered responsible for |
| modifications made by others. |
| |
| This License is a kind of "copyleft", which means that derivative |
| works of the document must themselves be free in the same sense. It |
| complements the GNU General Public License, which is a copyleft license |
| designed for free software. |
| |
| We have designed this License in order to use it for manuals for free |
| software, because free software needs free documentation: a free |
| program should come with manuals providing the same freedoms that the |
| software does. But this License is not limited to software manuals; it |
| can be used for any textual work, regardless of subject matter or |
| whether it is published as a printed book. We recommend this License |
| principally for works whose purpose is instruction or reference. |
| |
| 1. APPLICABILITY AND DEFINITIONS |
| |
| This License applies to any manual or other work that contains a |
| notice placed by the copyright holder saying it can be distributed |
| under the terms of this License. The "Document", below, refers to any |
| such manual or work. Any member of the public is a licensee, and is |
| addressed as "you". |
| |
| A "Modified Version" of the Document means any work containing the |
| Document or a portion of it, either copied verbatim, or with |
| modifications and/or translated into another language. |
| |
| A "Secondary Section" is a named appendix or a front-matter section |
| of the Document that deals exclusively with the relationship of the |
| publishers or authors of the Document to the Document's overall subject |
| (or to related matters) and contains nothing that could fall directly |
| within that overall subject. (For example, if the Document is in part a |
| textbook of mathematics, a Secondary Section may not explain any |
| mathematics.) The relationship could be a matter of historical |
| connection with the subject or with related matters, or of legal, |
| commercial, philosophical, ethical or political position regarding them. |
| |
| The "Invariant Sections" are certain Secondary Sections whose titles |
| are designated, as being those of Invariant Sections, in the notice |
| that says that the Document is released under this License. |
| |
| The "Cover Texts" are certain short passages of text that are listed, |
| as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
| the Document is released under this License. |
| |
| A "Transparent" copy of the Document means a machine-readable copy, |
| represented in a format whose specification is available to the general |
| public, whose contents can be viewed and edited directly and |
| straightforwardly with generic text editors or (for images composed of |
| pixels) generic paint programs or (for drawings) some widely available |
| drawing editor, and that is suitable for input to text formatters or |
| for automatic translation to a variety of formats suitable for input to |
| text formatters. A copy made in an otherwise Transparent file format |
| whose markup has been designed to thwart or discourage subsequent |
| modification by readers is not Transparent. A copy that is not |
| "Transparent" is called "Opaque". |
| |
| Examples of suitable formats for Transparent copies include plain |
| ASCII without markup, Texinfo input format, LaTeX input format, SGML or |
| XML using a publicly available DTD, and standard-conforming simple HTML |
| designed for human modification. Opaque formats include PostScript, |
| PDF, proprietary formats that can be read and edited only by |
| proprietary word processors, SGML or XML for which the DTD and/or |
| processing tools are not generally available, and the machine-generated |
| HTML produced by some word processors for output purposes only. |
| |
| The "Title Page" means, for a printed book, the title page itself, |
| plus such following pages as are needed to hold, legibly, the material |
| this License requires to appear in the title page. For works in |
| formats which do not have any title page as such, "Title Page" means |
| the text near the most prominent appearance of the work's title, |
| preceding the beginning of the body of the text. |
| |
| 2. VERBATIM COPYING |
| |
| You may copy and distribute the Document in any medium, either |
| commercially or noncommercially, provided that this License, the |
| copyright notices, and the license notice saying this License applies |
| to the Document are reproduced in all copies, and that you add no other |
| conditions whatsoever to those of this License. You may not use |
| technical measures to obstruct or control the reading or further |
| copying of the copies you make or distribute. However, you may accept |
| compensation in exchange for copies. If you distribute a large enough |
| number of copies you must also follow the conditions in section 3. |
| |
| You may also lend copies, under the same conditions stated above, and |
| you may publicly display copies. |
| |
| 3. COPYING IN QUANTITY |
| |
| If you publish printed copies of the Document numbering more than |
| 100, and the Document's license notice requires Cover Texts, you must |
| enclose the copies in covers that carry, clearly and legibly, all these |
| Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts |
| on the back cover. Both covers must also clearly and legibly identify |
| you as the publisher of these copies. The front cover must present the |
| full title with all words of the title equally prominent and visible. |
| You may add other material on the covers in addition. Copying with |
| changes limited to the covers, as long as they preserve the title of |
| the Document and satisfy these conditions, can be treated as verbatim |
| copying in other respects. |
| |
| If the required texts for either cover are too voluminous to fit |
| legibly, you should put the first ones listed (as many as fit |
| reasonably) on the actual cover, and continue the rest onto adjacent |
| pages. |
| |
| If you publish or distribute Opaque copies of the Document numbering |
| more than 100, you must either include a machine-readable Transparent |
| copy along with each Opaque copy, or state in or with each Opaque copy |
| a publicly-accessible computer-network location containing a complete |
| Transparent copy of the Document, free of added material, which the |
| general network-using public has access to download anonymously at no |
| charge using public-standard network protocols. If you use the latter |
| option, you must take reasonably prudent steps, when you begin |
| distribution of Opaque copies in quantity, to ensure that this |
| Transparent copy will remain thus accessible at the stated location |
| until at least one year after the last time you distribute an Opaque |
| copy (directly or through your agents or retailers) of that edition to |
| the public. |
| |
| It is requested, but not required, that you contact the authors of |
| the Document well before redistributing any large number of copies, to |
| give them a chance to provide you with an updated version of the |
| Document. |
| |
| 4. MODIFICATIONS |
| |
| You may copy and distribute a Modified Version of the Document under |
| the conditions of sections 2 and 3 above, provided that you release the |
| Modified Version under precisely this License, with the Modified |
| Version filling the role of the Document, thus licensing distribution |
| and modification of the Modified Version to whoever possesses a copy of |
| it. In addition, you must do these things in the Modified Version: |
| |
| A. Use in the Title Page (and on the covers, if any) a title distinct |
| from that of the Document, and from those of previous versions |
| (which should, if there were any, be listed in the History section |
| of the Document). You may use the same title as a previous version |
| if the original publisher of that version gives permission. B. List on |
| the Title Page, as authors, one or more persons or entities |
| responsible for authorship of the modifications in the Modified |
| Version, together with at least five of the principal authors of the |
| Document (all of its principal authors, if it has less than five). C. |
| State on the Title page the name of the publisher of the Modified |
| Version, as the publisher. D. Preserve all the copyright notices of |
| the Document. E. Add an appropriate copyright notice for your |
| modifications adjacent to the other copyright notices. F. Include, |
| immediately after the copyright notices, a license notice giving the |
| public permission to use the Modified Version under the terms of |
| this License, in the form shown in the Addendum below. G. Preserve in |
| that license notice the full lists of Invariant Sections and |
| required Cover Texts given in the Document's license notice. H. |
| Include an unaltered copy of this License. I. Preserve the section |
| entitled "History", and its title, and add to it an item stating at |
| least the title, year, new authors, and publisher of the Modified |
| Version as given on the Title Page. If there is no section entitled |
| "History" in the Document, create one stating the title, year, |
| authors, and publisher of the Document as given on its Title Page, |
| then add an item describing the Modified Version as stated in the |
| previous sentence. J. Preserve the network location, if any, given in |
| the Document for public access to a Transparent copy of the |
| Document, and likewise the network locations given in the Document |
| for previous versions it was based on. These may be placed in the |
| "History" section. You may omit a network location for a work that |
| was published at least four years before the Document itself, or if |
| the original publisher of the version it refers to gives permission. |
| K. In any section entitled "Acknowledgements" or "Dedications", |
| preserve the section's title, and preserve in the section all the |
| substance and tone of each of the contributor acknowledgements |
| and/or dedications given therein. L. Preserve all the Invariant |
| Sections of the Document, unaltered in their text and in their |
| titles. Section numbers or the equivalent are not considered part |
| of the section titles. M. Delete any section entitled "Endorsements". |
| Such a section may not be included in the Modified Version. N. Do |
| not retitle any existing section as "Endorsements" or to conflict in |
| title with any Invariant Section. |
| |
| If the Modified Version includes new front-matter sections or |
| appendices that qualify as Secondary Sections and contain no material |
| copied from the Document, you may at your option designate some or all |
| of these sections as invariant. To do this, add their titles to the |
| list of Invariant Sections in the Modified Version's license notice. |
| These titles must be distinct from any other section titles. |
| |
| You may add a section entitled "Endorsements", provided it contains |
| nothing but endorsements of your Modified Version by various |
| parties-for example, statements of peer review or that the text has |
| been approved by an organization as the authoritative definition of a |
| standard. |
| |
| You may add a passage of up to five words as a Front-Cover Text, and |
| a passage of up to 25 words as a Back-Cover Text, to the end of the list |
| of Cover Texts in the Modified Version. Only one passage of |
| Front-Cover Text and one of Back-Cover Text may be added by (or through |
| arrangements made by) any one entity. If the Document already includes |
| a cover text for the same cover, previously added by you or by |
| arrangement made by the same entity you are acting on behalf of, you |
| may not add another; but you may replace the old one, on explicit |
| permission from the previous publisher that added the old one. |
| |
| The author(s) and publisher(s) of the Document do not by this License |
| give permission to use their names for publicity for or to assert or |
| imply endorsement of any Modified Version. |
| |
| 5. COMBINING DOCUMENTS |
| |
| You may combine the Document with other documents released under this |
| License, under the terms defined in section 4 above for modified |
| versions, provided that you include in the combination all of the |
| Invariant Sections of all of the original documents, unmodified, and |
| list them all as Invariant Sections of your combined work in its |
| license notice. |
| |
| The combined work need only contain one copy of this License, and |
| multiple identical Invariant Sections may be replaced with a single |
| copy. If there are multiple Invariant Sections with the same name but |
| different contents, make the title of each such section unique by |
| adding at the end of it, in parentheses, the name of the original |
| author or publisher of that section if known, or else a unique number. |
| Make the same adjustment to the section titles in the list of Invariant |
| Sections in the license notice of the combined work. |
| |
| In the combination, you must combine any sections entitled "History" |
| in the various original documents, forming one section entitled |
| "History"; likewise combine any sections entitled "Acknowledgements", |
| and any sections entitled "Dedications". You must delete all sections |
| entitled "Endorsements." |
| |
| 6. COLLECTIONS OF DOCUMENTS |
| |
| You may make a collection consisting of the Document and other |
| documents released under this License, and replace the individual |
| copies of this License in the various documents with a single copy that |
| is included in the collection, provided that you follow the rules of |
| this License for verbatim copying of each of the documents in all other |
| respects. |
| |
| You may extract a single document from such a collection, and |
| distribute it individually under this License, provided you insert a |
| copy of this License into the extracted document, and follow this |
| License in all other respects regarding verbatim copying of that |
| document. |
| |
| 7. AGGREGATION WITH INDEPENDENT WORKS |
| |
| A compilation of the Document or its derivatives with other separate |
| and independent documents or works, in or on a volume of a storage or |
| distribution medium, does not as a whole count as a Modified Version of |
| the Document, provided no compilation copyright is claimed for the |
| compilation. Such a compilation is called an "aggregate", and this |
| License does not apply to the other self-contained works thus compiled |
| with the Document, on account of their being thus compiled, if they are |
| not themselves derivative works of the Document. |
| |
| If the Cover Text requirement of section 3 is applicable to these |
| copies of the Document, then if the Document is less than one quarter |
| of the entire aggregate, the Document's Cover Texts may be placed on |
| covers that surround only the Document within the aggregate. Otherwise |
| they must appear on covers around the whole aggregate. |
| |
| 8. TRANSLATION |
| |
| Translation is considered a kind of modification, so you may |
| distribute translations of the Document under the terms of section 4. |
| Replacing Invariant Sections with translations requires special |
| permission from their copyright holders, but you may include |
| translations of some or all Invariant Sections in addition to the |
| original versions of these Invariant Sections. You may include a |
| translation of this License provided that you also include the original |
| English version of this License. In case of a disagreement between the |
| translation and the original English version of this License, the |
| original English version will prevail. |
| |
| 9. TERMINATION |
| |
| You may not copy, modify, sublicense, or distribute the Document |
| except as expressly provided for under this License. Any other attempt |
| to copy, modify, sublicense or distribute the Document is void, and will |
| automatically terminate your rights under this License. However, |
| parties who have received copies, or rights, from you under this |
| License will not have their licenses terminated so long as such parties |
| remain in full compliance. |
| |
| 10. FUTURE REVISIONS OF THIS LICENSE |
| |
| The Free Software Foundation may publish new, revised versions of |
| the GNU Free Documentation License from time to time. Such new |
| versions will be similar in spirit to the present version, but may |
| differ in detail to address new problems or concerns. See |
| http://www.gnu.org/copyleft/. |
| |
| Each version of the License is given a distinguishing version number. |
| If the Document specifies that a particular numbered version of this |
| License "or any later version" applies to it, you have the option of |
| following the terms and conditions either of that specified version or |
| of any later version that has been published (not as a draft) by the |
| Free Software Foundation. If the Document does not specify a version |
| number of this License, you may choose any version ever published (not |
| as a draft) by the Free Software Foundation. |
| |
| ADDENDUM: How to use this License for your documents |
| |
| To use this License in a document you have written, include a copy of |
| the License in the document and put the following copyright and license |
| notices just after the title page: |
| |
| Copyright (c) YEAR YOUR NAME. |
| 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 the Invariant Sections being LIST THEIR TITLES, with the |
| Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. |
| A copy of the license is included in the section entitled "GNU |
| Free Documentation License". |
| |
| If you have no Invariant Sections, write "with no Invariant Sections" |
| instead of saying which ones are invariant. If you have no Front-Cover |
| Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being |
| LIST"; likewise for Back-Cover Texts. |
| |
| If your document contains nontrivial examples of program code, we |
| recommend releasing these examples in parallel under your choice of |
| free software license, such as the GNU General Public License, to |
| permit their use in free software. |
| |