| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- This file documents the BFD library. |
| |
| Copyright (C) 1991 - 2013 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.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "GNU General Public License" and "Funding |
| Free Software", the Front-Cover texts being (a) (see below), and with |
| the Back-Cover Texts being (b) (see below). A copy of the license is |
| included in the section entitled "GNU Free Documentation License". |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>Untitled Document: typedef arelent</title> |
| |
| <meta name="description" content="Untitled Document: typedef arelent"> |
| <meta name="keywords" content="Untitled Document: typedef arelent"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="BFD-Index.html#BFD-Index" rel="index" title="BFD Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="Relocations.html#Relocations" rel="up" title="Relocations"> |
| <link href="howto-manager.html#howto-manager" rel="next" title="howto manager"> |
| <link href="Relocations.html#Relocations" rel="prev" title="Relocations"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="typedef-arelent"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="howto-manager.html#howto-manager" accesskey="n" rel="next">howto manager</a>, Previous: <a href="Relocations.html#Relocations" accesskey="p" rel="prev">Relocations</a>, Up: <a href="Relocations.html#Relocations" accesskey="u" rel="up">Relocations</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="BFD-Index.html#BFD-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <hr> |
| <a name="typedef-arelent-1"></a> |
| <h4 class="subsection">2.10.1 typedef arelent</h4> |
| <p>This is the structure of a relocation entry: |
| </p> |
| |
| <div class="example"> |
| <pre class="example"> |
| typedef enum bfd_reloc_status |
| { |
| /* No errors detected. */ |
| bfd_reloc_ok, |
| |
| /* The relocation was performed, but there was an overflow. */ |
| bfd_reloc_overflow, |
| |
| /* The address to relocate was not within the section supplied. */ |
| bfd_reloc_outofrange, |
| |
| /* Used by special functions. */ |
| bfd_reloc_continue, |
| |
| /* Unsupported relocation size requested. */ |
| bfd_reloc_notsupported, |
| |
| /* Unused. */ |
| bfd_reloc_other, |
| |
| /* The symbol to relocate against was undefined. */ |
| bfd_reloc_undefined, |
| |
| /* The relocation was performed, but may not be ok - presently |
| generated only when linking i960 coff files with i960 b.out |
| symbols. If this type is returned, the error_message argument |
| to bfd_perform_relocation will be set. */ |
| bfd_reloc_dangerous |
| } |
| bfd_reloc_status_type; |
| |
| |
| typedef struct reloc_cache_entry |
| { |
| /* A pointer into the canonical table of pointers. */ |
| struct bfd_symbol **sym_ptr_ptr; |
| |
| /* offset in section. */ |
| bfd_size_type address; |
| |
| /* addend for relocation value. */ |
| bfd_vma addend; |
| |
| /* Pointer to how to perform the required relocation. */ |
| reloc_howto_type *howto; |
| |
| } |
| arelent; |
| |
| </pre></div> |
| <p><strong>Description</strong><br> |
| Here is a description of each of the fields within an <code>arelent</code>: |
| </p> |
| <ul> |
| <li> <code>sym_ptr_ptr</code> |
| </li></ul> |
| <p>The symbol table pointer points to a pointer to the symbol |
| associated with the relocation request. It is the pointer |
| into the table returned by the back end’s |
| <code>canonicalize_symtab</code> action. See <a href="Symbols.html#Symbols">Symbols</a>. The symbol is |
| referenced through a pointer to a pointer so that tools like |
| the linker can fix up all the symbols of the same name by |
| modifying only one pointer. The relocation routine looks in |
| the symbol and uses the base of the section the symbol is |
| attached to and the value of the symbol as the initial |
| relocation offset. If the symbol pointer is zero, then the |
| section provided is looked up. |
| </p> |
| <ul> |
| <li> <code>address</code> |
| </li></ul> |
| <p>The <code>address</code> field gives the offset in bytes from the base of |
| the section data which owns the relocation record to the first |
| byte of relocatable information. The actual data relocated |
| will be relative to this point; for example, a relocation |
| type which modifies the bottom two bytes of a four byte word |
| would not touch the first byte pointed to in a big endian |
| world. |
| </p> |
| <ul> |
| <li> <code>addend</code> |
| </li></ul> |
| <p>The <code>addend</code> is a value provided by the back end to be added (!) |
| to the relocation offset. Its interpretation is dependent upon |
| the howto. For example, on the 68k the code: |
| </p> |
| <div class="example"> |
| <pre class="example"> char foo[]; |
| main() |
| { |
| return foo[0x12345678]; |
| } |
| </pre></div> |
| |
| <p>Could be compiled into: |
| </p> |
| <div class="example"> |
| <pre class="example"> linkw fp,#-4 |
| moveb @#12345678,d0 |
| extbl d0 |
| unlk fp |
| rts |
| </pre></div> |
| |
| <p>This could create a reloc pointing to <code>foo</code>, but leave the |
| offset in the data, something like: |
| </p> |
| <div class="example"> |
| <pre class="example">RELOCATION RECORDS FOR [.text]: |
| offset type value |
| 00000006 32 _foo |
| |
| 00000000 4e56 fffc ; linkw fp,#-4 |
| 00000004 1039 1234 5678 ; moveb @#12345678,d0 |
| 0000000a 49c0 ; extbl d0 |
| 0000000c 4e5e ; unlk fp |
| 0000000e 4e75 ; rts |
| </pre></div> |
| |
| <p>Using coff and an 88k, some instructions don’t have enough |
| space in them to represent the full address range, and |
| pointers have to be loaded in two parts. So you’d get something like: |
| </p> |
| <div class="example"> |
| <pre class="example"> or.u r13,r0,hi16(_foo+0x12345678) |
| ld.b r2,r13,lo16(_foo+0x12345678) |
| jmp r1 |
| </pre></div> |
| |
| <p>This should create two relocs, both pointing to <code>_foo</code>, and with |
| 0x12340000 in their addend field. The data would consist of: |
| </p> |
| <div class="example"> |
| <pre class="example">RELOCATION RECORDS FOR [.text]: |
| offset type value |
| 00000002 HVRT16 _foo+0x12340000 |
| 00000006 LVRT16 _foo+0x12340000 |
| |
| 00000000 5da05678 ; or.u r13,r0,0x5678 |
| 00000004 1c4d5678 ; ld.b r2,r13,0x5678 |
| 00000008 f400c001 ; jmp r1 |
| </pre></div> |
| |
| <p>The relocation routine digs out the value from the data, adds |
| it to the addend to get the original offset, and then adds the |
| value of <code>_foo</code>. Note that all 32 bits have to be kept around |
| somewhere, to cope with carry from bit 15 to bit 16. |
| </p> |
| <p>One further example is the sparc and the a.out format. The |
| sparc has a similar problem to the 88k, in that some |
| instructions don’t have room for an entire offset, but on the |
| sparc the parts are created in odd sized lumps. The designers of |
| the a.out format chose to not use the data within the section |
| for storing part of the offset; all the offset is kept within |
| the reloc. Anything in the data should be ignored. |
| </p> |
| <div class="example"> |
| <pre class="example"> save %sp,-112,%sp |
| sethi %hi(_foo+0x12345678),%g2 |
| ldsb [%g2+%lo(_foo+0x12345678)],%i0 |
| ret |
| restore |
| </pre></div> |
| |
| <p>Both relocs contain a pointer to <code>foo</code>, and the offsets |
| contain junk. |
| </p> |
| <div class="example"> |
| <pre class="example">RELOCATION RECORDS FOR [.text]: |
| offset type value |
| 00000004 HI22 _foo+0x12345678 |
| 00000008 LO10 _foo+0x12345678 |
| |
| 00000000 9de3bf90 ; save %sp,-112,%sp |
| 00000004 05000000 ; sethi %hi(_foo+0),%g2 |
| 00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0 |
| 0000000c 81c7e008 ; ret |
| 00000010 81e80000 ; restore |
| </pre></div> |
| |
| <ul> |
| <li> <code>howto</code> |
| </li></ul> |
| <p>The <code>howto</code> field can be imagined as a |
| relocation instruction. It is a pointer to a structure which |
| contains information on what to do with all of the other |
| information in the reloc record and data section. A back end |
| would normally have a relocation instruction set and turn |
| relocations into pointers to the correct structure on input - |
| but it would be possible to create each howto field on demand. |
| </p> |
| <a name="enum-complain_005foverflow"></a> |
| <h4 class="subsubsection">2.10.1.1 <code>enum complain_overflow</code></h4> |
| <p>Indicates what sort of overflow checking should be done when |
| performing a relocation. |
| </p> |
| |
| <div class="example"> |
| <pre class="example"> |
| enum complain_overflow |
| { |
| /* Do not complain on overflow. */ |
| complain_overflow_dont, |
| |
| /* Complain if the value overflows when considered as a signed |
| number one bit larger than the field. ie. A bitfield of N bits |
| is allowed to represent -2**n to 2**n-1. */ |
| complain_overflow_bitfield, |
| |
| /* Complain if the value overflows when considered as a signed |
| number. */ |
| complain_overflow_signed, |
| |
| /* Complain if the value overflows when considered as an |
| unsigned number. */ |
| complain_overflow_unsigned |
| }; |
| </pre></div> |
| <a name="reloc_005fhowto_005ftype"></a> |
| <h4 class="subsubsection">2.10.1.2 <code>reloc_howto_type</code></h4> |
| <p>The <code>reloc_howto_type</code> is a structure which contains all the |
| information that libbfd needs to know to tie up a back end’s data. |
| </p> |
| |
| <div class="example"> |
| <pre class="example">struct bfd_symbol; /* Forward declaration. */ |
| |
| struct reloc_howto_struct |
| { |
| /* The type field has mainly a documentary use - the back end can |
| do what it wants with it, though normally the back end's |
| external idea of what a reloc number is stored |
| in this field. For example, a PC relative word relocation |
| in a coff environment has the type 023 - because that's |
| what the outside world calls a R_PCRWORD reloc. */ |
| unsigned int type; |
| |
| /* The value the final relocation is shifted right by. This drops |
| unwanted data from the relocation. */ |
| unsigned int rightshift; |
| |
| /* The size of the item to be relocated. This is *not* a |
| power-of-two measure. To get the number of bytes operated |
| on by a type of relocation, use bfd_get_reloc_size. */ |
| int size; |
| |
| /* The number of bits in the item to be relocated. This is used |
| when doing overflow checking. */ |
| unsigned int bitsize; |
| |
| /* The relocation is relative to the field being relocated. */ |
| bfd_boolean pc_relative; |
| |
| /* The bit position of the reloc value in the destination. |
| The relocated value is left shifted by this amount. */ |
| unsigned int bitpos; |
| |
| /* What type of overflow error should be checked for when |
| relocating. */ |
| enum complain_overflow complain_on_overflow; |
| |
| /* If this field is non null, then the supplied function is |
| called rather than the normal function. This allows really |
| strange relocation methods to be accommodated (e.g., i960 callj |
| instructions). */ |
| bfd_reloc_status_type (*special_function) |
| (bfd *, arelent *, struct bfd_symbol *, void *, asection *, |
| bfd *, char **); |
| |
| /* The textual name of the relocation type. */ |
| char *name; |
| |
| /* Some formats record a relocation addend in the section contents |
| rather than with the relocation. For ELF formats this is the |
| distinction between USE_REL and USE_RELA (though the code checks |
| for USE_REL == 1/0). The value of this field is TRUE if the |
| addend is recorded with the section contents; when performing a |
| partial link (ld -r) the section contents (the data) will be |
| modified. The value of this field is FALSE if addends are |
| recorded with the relocation (in arelent.addend); when performing |
| a partial link the relocation will be modified. |
| All relocations for all ELF USE_RELA targets should set this field |
| to FALSE (values of TRUE should be looked on with suspicion). |
| However, the converse is not true: not all relocations of all ELF |
| USE_REL targets set this field to TRUE. Why this is so is peculiar |
| to each particular target. For relocs that aren't used in partial |
| links (e.g. GOT stuff) it doesn't matter what this is set to. */ |
| bfd_boolean partial_inplace; |
| |
| /* src_mask selects the part of the instruction (or data) to be used |
| in the relocation sum. If the target relocations don't have an |
| addend in the reloc, eg. ELF USE_REL, src_mask will normally equal |
| dst_mask to extract the addend from the section contents. If |
| relocations do have an addend in the reloc, eg. ELF USE_RELA, this |
| field should be zero. Non-zero values for ELF USE_RELA targets are |
| bogus as in those cases the value in the dst_mask part of the |
| section contents should be treated as garbage. */ |
| bfd_vma src_mask; |
| |
| /* dst_mask selects which parts of the instruction (or data) are |
| replaced with a relocated value. */ |
| bfd_vma dst_mask; |
| |
| /* When some formats create PC relative instructions, they leave |
| the value of the pc of the place being relocated in the offset |
| slot of the instruction, so that a PC relative relocation can |
| be made just by adding in an ordinary offset (e.g., sun3 a.out). |
| Some formats leave the displacement part of an instruction |
| empty (e.g., m88k bcs); this flag signals the fact. */ |
| bfd_boolean pcrel_offset; |
| }; |
| |
| </pre></div> |
| <a name="index-The-HOWTO-Macro"></a> |
| <a name="The-HOWTO-Macro"></a> |
| <h4 class="subsubsection">2.10.1.3 <code>The HOWTO Macro</code></h4> |
| <p><strong>Description</strong><br> |
| The HOWTO define is horrible and will go away. |
| </p><div class="example"> |
| <pre class="example">#define HOWTO(C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \ |
| { (unsigned) C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC } |
| </pre></div> |
| |
| <p><strong>Description</strong><br> |
| And will be replaced with the totally magic way. But for the |
| moment, we are compatible, so do it this way. |
| </p><div class="example"> |
| <pre class="example">#define NEWHOWTO(FUNCTION, NAME, SIZE, REL, IN) \ |
| HOWTO (0, 0, SIZE, 0, REL, 0, complain_overflow_dont, FUNCTION, \ |
| NAME, FALSE, 0, 0, IN) |
| |
| </pre></div> |
| |
| <p><strong>Description</strong><br> |
| This is used to fill in an empty howto entry in an array. |
| </p><div class="example"> |
| <pre class="example">#define EMPTY_HOWTO(C) \ |
| HOWTO ((C), 0, 0, 0, FALSE, 0, complain_overflow_dont, NULL, \ |
| NULL, FALSE, 0, 0, FALSE) |
| |
| </pre></div> |
| |
| <p><strong>Description</strong><br> |
| Helper routine to turn a symbol into a relocation value. |
| </p><div class="example"> |
| <pre class="example">#define HOWTO_PREPARE(relocation, symbol) \ |
| { \ |
| if (symbol != NULL) \ |
| { \ |
| if (bfd_is_com_section (symbol->section)) \ |
| { \ |
| relocation = 0; \ |
| } \ |
| else \ |
| { \ |
| relocation = symbol->value; \ |
| } \ |
| } \ |
| } |
| |
| </pre></div> |
| |
| <a name="index-bfd_005fget_005freloc_005fsize"></a> |
| <a name="bfd_005fget_005freloc_005fsize"></a> |
| <h4 class="subsubsection">2.10.1.4 <code>bfd_get_reloc_size</code></h4> |
| <p><strong>Synopsis</strong> |
| </p><div class="example"> |
| <pre class="example">unsigned int bfd_get_reloc_size (reloc_howto_type *); |
| </pre></div> |
| <p><strong>Description</strong><br> |
| For a reloc_howto_type that operates on a fixed number of bytes, |
| this returns the number of bytes operated on. |
| </p> |
| <a name="index-arelent_005fchain"></a> |
| <a name="arelent_005fchain"></a> |
| <h4 class="subsubsection">2.10.1.5 <code>arelent_chain</code></h4> |
| <p><strong>Description</strong><br> |
| How relocs are tied together in an <code>asection</code>: |
| </p><div class="example"> |
| <pre class="example">typedef struct relent_chain |
| { |
| arelent relent; |
| struct relent_chain *next; |
| } |
| arelent_chain; |
| |
| </pre></div> |
| |
| <a name="index-bfd_005fcheck_005foverflow"></a> |
| <a name="bfd_005fcheck_005foverflow"></a> |
| <h4 class="subsubsection">2.10.1.6 <code>bfd_check_overflow</code></h4> |
| <p><strong>Synopsis</strong> |
| </p><div class="example"> |
| <pre class="example">bfd_reloc_status_type bfd_check_overflow |
| (enum complain_overflow how, |
| unsigned int bitsize, |
| unsigned int rightshift, |
| unsigned int addrsize, |
| bfd_vma relocation); |
| </pre></div> |
| <p><strong>Description</strong><br> |
| Perform overflow checking on <var>relocation</var> which has |
| <var>bitsize</var> significant bits and will be shifted right by |
| <var>rightshift</var> bits, on a machine with addresses containing |
| <var>addrsize</var> significant bits. The result is either of |
| <code>bfd_reloc_ok</code> or <code>bfd_reloc_overflow</code>. |
| </p> |
| <a name="index-bfd_005fperform_005frelocation"></a> |
| <a name="bfd_005fperform_005frelocation"></a> |
| <h4 class="subsubsection">2.10.1.7 <code>bfd_perform_relocation</code></h4> |
| <p><strong>Synopsis</strong> |
| </p><div class="example"> |
| <pre class="example">bfd_reloc_status_type bfd_perform_relocation |
| (bfd *abfd, |
| arelent *reloc_entry, |
| void *data, |
| asection *input_section, |
| bfd *output_bfd, |
| char **error_message); |
| </pre></div> |
| <p><strong>Description</strong><br> |
| If <var>output_bfd</var> is supplied to this function, the |
| generated image will be relocatable; the relocations are |
| copied to the output file after they have been changed to |
| reflect the new state of the world. There are two ways of |
| reflecting the results of partial linkage in an output file: |
| by modifying the output data in place, and by modifying the |
| relocation record. Some native formats (e.g., basic a.out and |
| basic coff) have no way of specifying an addend in the |
| relocation type, so the addend has to go in the output data. |
| This is no big deal since in these formats the output data |
| slot will always be big enough for the addend. Complex reloc |
| types with addends were invented to solve just this problem. |
| The <var>error_message</var> argument is set to an error message if |
| this return <code>bfd_reloc_dangerous</code>. |
| </p> |
| <a name="index-bfd_005finstall_005frelocation"></a> |
| <a name="bfd_005finstall_005frelocation"></a> |
| <h4 class="subsubsection">2.10.1.8 <code>bfd_install_relocation</code></h4> |
| <p><strong>Synopsis</strong> |
| </p><div class="example"> |
| <pre class="example">bfd_reloc_status_type bfd_install_relocation |
| (bfd *abfd, |
| arelent *reloc_entry, |
| void *data, bfd_vma data_start, |
| asection *input_section, |
| char **error_message); |
| </pre></div> |
| <p><strong>Description</strong><br> |
| This looks remarkably like <code>bfd_perform_relocation</code>, except it |
| does not expect that the section contents have been filled in. |
| I.e., it’s suitable for use when creating, rather than applying |
| a relocation. |
| </p> |
| <p>For now, this function should be considered reserved for the |
| assembler. |
| </p> |
| |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <a href="howto-manager.html#howto-manager" accesskey="n" rel="next">howto manager</a>, Previous: <a href="Relocations.html#Relocations" accesskey="p" rel="prev">Relocations</a>, Up: <a href="Relocations.html#Relocations" accesskey="u" rel="up">Relocations</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="BFD-Index.html#BFD-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| |
| |
| |
| </body> |
| </html> |
