diff options
Diffstat (limited to 'contrib/binutils')
37 files changed, 961 insertions, 24220 deletions
diff --git a/contrib/binutils/bfd/ChangeLog b/contrib/binutils/bfd/ChangeLog index 92698f0c16a9..e006595f969e 100644 --- a/contrib/binutils/bfd/ChangeLog +++ b/contrib/binutils/bfd/ChangeLog @@ -1,49 +1,3 @@ -2009-02-15 Alan Modra <amodra@bigpond.net.au> - - * elf64-ppc.c (struct _ppc64_elf_section_data): Delete t_symndx, - add toc.symndx and toc.add. - (ppc64_elf_check_relocs): Don't set htab->tls_get_addr here. - Set up toc.add. - (get_tls_mask): Add toc_addend param, set from toc.add. Adjust all - callers. - (ppc64_elf_tls_setup): Set htab->tls_get_addr and tls_get_addr_fd. - (branch_reloc_hash_match): New function, extracted from.. - (ppc64_elf_tls_optimize): ..here. - (ppc64_elf_relocate_section): Properly set addends when optimizing - tls sequences. Avoid unnecessary reading and writing of insns. - Only redo reloc when symbol changed. Bypass symbol checks when - using tlsld_got. - * elf32-ppc.c (ppc_elf_tls_setup): Correct comment. - (branch_reloc_hash_match): New function, extracted from.. - (ppc_elf_tls_optimize): ..here. - (ppc_elf_relocate_section): Avoid unnecessary reading of insns. - Don't clear addend on zapped __tls_get_addr reloc. - -2008-08-11 Alan Modra <amodra@bigpond.net.au> - - * elf64-ppc.c (toc_adjusting_stub_needed): Any call via the plt - needs r2 valid, not just those to external syms. - -2007-11-06 Alan Modra <amodra@bigpond.net.au> - - * elf32-ppc.c (ppc_elf_check_relocs): Don't refcount tlsld_got here.. - (ppc_elf_gc_sweep_hook): ..or here.. - (ppc_elf_tls_optimize): ..or here. Make two passes through the - relocs, ensuring that tls_get_addr calls follow gd and ld relocs. - (allocate_dynrelocs): Refcount tlsld_got here. - (ppc_elf_size_dynamic_sections): Call allocate_dynrelocs before - allocating tlsld_got. - (ppc_elf_relocate_section): Remove check that a tls_get_addr - call follows gd and ld relocs. - -2007-08-13 Alan Modra <amodra@bigpond.net.au> - - * elf64-ppc.c (ADDI_R12_R12, LD_R11_0R2, LD_R2_0R2): Define. - Update stub comments. - (build_plt_stub): Build two variants, one without "addis". - (ppc_build_one_stub): Build stubs without "addis" if possible. - (ppc_size_one_stub): Size new stubs. - 2007-07-02 Joseph Myers <joseph@codesourcery.com> * elfxx-mips.c (mips_elf_calculate_relocation): Handle diff --git a/contrib/binutils/bfd/bfd-in2.h b/contrib/binutils/bfd/bfd-in2.h index 92796f865359..8ea1cdd3b188 100644 --- a/contrib/binutils/bfd/bfd-in2.h +++ b/contrib/binutils/bfd/bfd-in2.h @@ -1380,9 +1380,6 @@ typedef struct bfd_section /* Nonzero if this section has TLS related relocations. */ unsigned int has_tls_reloc:1; - /* Nonzero if this section has a call to __tls_get_addr. */ - unsigned int has_tls_get_addr_call:1; - /* Nonzero if this section has a gp reloc. */ unsigned int has_gp_reloc:1; @@ -1643,11 +1640,11 @@ extern asection bfd_ind_section; /* segment_mark, sec_info_type, use_rela_p, has_tls_reloc, */ \ 0, 0, 0, 0, \ \ - /* has_tls_get_addr_call, has_gp_reloc, need_finalize_relax, */ \ - 0, 0, 0, \ + /* has_gp_reloc, need_finalize_relax, reloc_done, */ \ + 0, 0, 0, \ \ - /* reloc_done, vma, lma, size, rawsize */ \ - 0, 0, 0, 0, 0, \ + /* vma, lma, size, rawsize */ \ + 0, 0, 0, 0, \ \ /* output_offset, output_section, alignment_power, */ \ 0, (struct bfd_section *) &SEC, 0, \ @@ -2899,8 +2896,6 @@ in the instruction. */ /* PowerPC and PowerPC64 thread-local storage relocations. */ BFD_RELOC_PPC_TLS, - BFD_RELOC_PPC_TLSGD, - BFD_RELOC_PPC_TLSLD, BFD_RELOC_PPC_DTPMOD, BFD_RELOC_PPC_TPREL16, BFD_RELOC_PPC_TPREL16_LO, diff --git a/contrib/binutils/bfd/doc/bfdver.texi b/contrib/binutils/bfd/doc/bfdver.texi deleted file mode 100644 index eaf58f49ca72..000000000000 --- a/contrib/binutils/bfd/doc/bfdver.texi +++ /dev/null @@ -1 +0,0 @@ -@set VERSION "2.17.50 [FreeBSD] 2007-07-03" diff --git a/contrib/binutils/bfd/dwarf2.c b/contrib/binutils/bfd/dwarf2.c index 1c3d7e91b493..6554f0f80bc0 100644 --- a/contrib/binutils/bfd/dwarf2.c +++ b/contrib/binutils/bfd/dwarf2.c @@ -2382,8 +2382,7 @@ find_line (bfd *abfd, else addr += section->vma; *filename_ptr = NULL; - if (!do_line) - *functionname_ptr = NULL; + *functionname_ptr = NULL; *linenumber_ptr = 0; if (! *pinfo) diff --git a/contrib/binutils/bfd/ecoff.c b/contrib/binutils/bfd/ecoff.c index 52a9941a9156..45cdb1ddb43f 100644 --- a/contrib/binutils/bfd/ecoff.c +++ b/contrib/binutils/bfd/ecoff.c @@ -58,10 +58,10 @@ static asection bfd_debug_section = 0, 0, 1, 0, /* segment_mark, sec_info_type, use_rela_p, has_tls_reloc, */ 0, 0, 0, 0, - /* has_tls_get_addr_call, has_gp_reloc, need_finalize_relax, */ - 0, 0, 0, - /* reloc_done, vma, lma, size, rawsize, */ - 0, 0, 0, 0, 0, + /* has_gp_reloc, need_finalize_relax, reloc_done, */ + 0, 0, 0, + /* vma, lma, size, rawsize, */ + 0, 0, 0, 0, /* output_offset, output_section, alignment_power, */ 0, NULL, 0, /* relocation, orelocation, reloc_count, filepos, rel_filepos, */ diff --git a/contrib/binutils/bfd/elf-bfd.h b/contrib/binutils/bfd/elf-bfd.h index 8c30dd54248b..c80bc7673a2b 100644 --- a/contrib/binutils/bfd/elf-bfd.h +++ b/contrib/binutils/bfd/elf-bfd.h @@ -1286,7 +1286,7 @@ struct elf_find_verdep_info }; /* The maximum number of known object attributes for any target. */ -#define NUM_KNOWN_OBJ_ATTRIBUTES 71 +#define NUM_KNOWN_OBJ_ATTRIBUTES 32 /* The value of an object attribute. type & 1 indicates whether there is an integer value; type & 2 indicates whether there is a string diff --git a/contrib/binutils/bfd/elf32-arm.c b/contrib/binutils/bfd/elf32-arm.c index ca40eac0497f..83acfe564714 100644 --- a/contrib/binutils/bfd/elf32-arm.c +++ b/contrib/binutils/bfd/elf32-arm.c @@ -4960,7 +4960,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, + input_section->output_offset + rel->r_offset); - value = llabs (relocation); + value = abs (relocation); if (value >= 0x1000) return bfd_reloc_overflow; @@ -4998,7 +4998,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, + input_section->output_offset + rel->r_offset); - value = llabs (relocation); + value = abs (relocation); if (value >= 0x1000) return bfd_reloc_overflow; @@ -5984,7 +5984,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, /* Calculate the value of the relevant G_n, in encoded constant-with-rotation format. */ - g_n = calculate_group_reloc_mask (llabs (signed_value), group, + g_n = calculate_group_reloc_mask (abs (signed_value), group, &residual); /* Check for overflow if required. */ @@ -5998,7 +5998,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, (*_bfd_error_handler) (_("%B(%A+0x%lx): Overflow whilst splitting 0x%lx for group relocation %s"), input_bfd, input_section, - (long) rel->r_offset, llabs (signed_value), howto->name); + (long) rel->r_offset, abs (signed_value), howto->name); return bfd_reloc_overflow; } @@ -6077,7 +6077,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, /* Calculate the value of the relevant G_{n-1} to obtain the residual at that stage. */ - calculate_group_reloc_mask (llabs (signed_value), group - 1, &residual); + calculate_group_reloc_mask (abs (signed_value), group - 1, &residual); /* Check for overflow. */ if (residual >= 0x1000) @@ -6085,7 +6085,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, (*_bfd_error_handler) (_("%B(%A+0x%lx): Overflow whilst splitting 0x%lx for group relocation %s"), input_bfd, input_section, - (long) rel->r_offset, llabs (signed_value), howto->name); + (long) rel->r_offset, abs (signed_value), howto->name); return bfd_reloc_overflow; } @@ -6160,7 +6160,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, /* Calculate the value of the relevant G_{n-1} to obtain the residual at that stage. */ - calculate_group_reloc_mask (llabs (signed_value), group - 1, &residual); + calculate_group_reloc_mask (abs (signed_value), group - 1, &residual); /* Check for overflow. */ if (residual >= 0x100) @@ -6168,7 +6168,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, (*_bfd_error_handler) (_("%B(%A+0x%lx): Overflow whilst splitting 0x%lx for group relocation %s"), input_bfd, input_section, - (long) rel->r_offset, llabs (signed_value), howto->name); + (long) rel->r_offset, abs (signed_value), howto->name); return bfd_reloc_overflow; } @@ -6243,7 +6243,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, /* Calculate the value of the relevant G_{n-1} to obtain the residual at that stage. */ - calculate_group_reloc_mask (llabs (signed_value), group - 1, &residual); + calculate_group_reloc_mask (abs (signed_value), group - 1, &residual); /* Check for overflow. (The absolute value to go in the place must be divisible by four and, after having been divided by four, must @@ -6253,7 +6253,7 @@ elf32_arm_final_link_relocate (reloc_howto_type * howto, (*_bfd_error_handler) (_("%B(%A+0x%lx): Overflow whilst splitting 0x%lx for group relocation %s"), input_bfd, input_section, - (long) rel->r_offset, llabs (signed_value), howto->name); + (long) rel->r_offset, abs (signed_value), howto->name); return bfd_reloc_overflow; } @@ -6794,31 +6794,15 @@ elf32_arm_merge_eabi_attributes (bfd *ibfd, bfd *obfd) out_attr[Tag_ABI_VFP_args].i = in_attr[Tag_ABI_VFP_args].i; else if (in_attr[Tag_ABI_FP_number_model].i != 0) { - bfd *hasbfd, *hasnotbfd; - - if (in_attr[Tag_ABI_VFP_args].i) - { - hasbfd = ibfd; - hasnotbfd = obfd; - } - else - { - hasbfd = obfd; - hasnotbfd = ibfd; - } - _bfd_error_handler (_("ERROR: %B uses VFP register arguments, %B does not"), - hasbfd, hasnotbfd); + ibfd, obfd); return FALSE; } } for (i = 4; i < NUM_KNOWN_OBJ_ATTRIBUTES; i++) { - if (out_attr[i].type == 0) - out_attr[i].type = in_attr[i].type; - /* Merge this attribute with existing attributes. */ switch (i) { @@ -6851,8 +6835,6 @@ elf32_arm_merge_eabi_attributes (bfd *ibfd, bfd *obfd) case Tag_ABI_FP_number_model: case Tag_ABI_align8_preserved: case Tag_ABI_HardFP_use: - case Tag_CPU_unaligned_access: - case Tag_FP_HP_extension: /* Use the largest value specified. */ if (in_attr[i].i > out_attr[i].i) out_attr[i].i = in_attr[i].i; @@ -6969,9 +6951,7 @@ elf32_arm_merge_eabi_attributes (bfd *ibfd, bfd *obfd) } break; default: /* All known attributes should be explicitly covered. */ - /* XXX Not now */ - /* abort (); */ - break; + abort (); } } @@ -9375,16 +9355,6 @@ elf32_arm_post_process_headers (bfd * abfd, struct bfd_link_info * link_info ATT if (globals->byteswap_code) i_ehdrp->e_flags |= EF_ARM_BE8; } - - /* - * For EABI 5, we have to tag dynamic binaries and execs as either - * soft float or hard float. - */ - if (EF_ARM_EABI_VERSION (i_ehdrp->e_flags) == EF_ARM_EABI_VER5 && - (i_ehdrp->e_type == ET_DYN || i_ehdrp->e_type == ET_EXEC)) - i_ehdrp->e_flags |= - bfd_elf_get_obj_attr_int (abfd, OBJ_ATTR_PROC, Tag_ABI_VFP_args) ? - EF_ARM_VFP_FLOAT : EF_ARM_SOFT_FLOAT; } static enum elf_reloc_type_class diff --git a/contrib/binutils/bfd/elf32-ppc.c b/contrib/binutils/bfd/elf32-ppc.c index 0441fe2bf6b9..d7700140667a 100644 --- a/contrib/binutils/bfd/elf32-ppc.c +++ b/contrib/binutils/bfd/elf32-ppc.c @@ -746,7 +746,7 @@ static reloc_howto_type ppc_elf_howto_raw[] = { 0xffff, /* dst_mask */ FALSE), /* pcrel_offset */ - /* Marker relocs for TLS. */ + /* Marker reloc for TLS. */ HOWTO (R_PPC_TLS, 0, /* rightshift */ 2, /* size (0 = byte, 1 = short, 2 = long) */ @@ -761,34 +761,6 @@ static reloc_howto_type ppc_elf_howto_raw[] = { 0, /* dst_mask */ FALSE), /* pcrel_offset */ - HOWTO (R_PPC_TLSGD, - 0, /* rightshift */ - 2, /* size (0 = byte, 1 = short, 2 = long) */ - 32, /* bitsize */ - FALSE, /* pc_relative */ - 0, /* bitpos */ - complain_overflow_dont, /* complain_on_overflow */ - bfd_elf_generic_reloc, /* special_function */ - "R_PPC_TLSGD", /* name */ - FALSE, /* partial_inplace */ - 0, /* src_mask */ - 0, /* dst_mask */ - FALSE), /* pcrel_offset */ - - HOWTO (R_PPC_TLSLD, - 0, /* rightshift */ - 2, /* size (0 = byte, 1 = short, 2 = long) */ - 32, /* bitsize */ - FALSE, /* pc_relative */ - 0, /* bitpos */ - complain_overflow_dont, /* complain_on_overflow */ - bfd_elf_generic_reloc, /* special_function */ - "R_PPC_TLSLD", /* name */ - FALSE, /* partial_inplace */ - 0, /* src_mask */ - 0, /* dst_mask */ - FALSE), /* pcrel_offset */ - /* Computes the load module index of the load module that contains the definition of its TLS sym. */ HOWTO (R_PPC_DTPMOD32, @@ -1552,8 +1524,6 @@ ppc_elf_reloc_type_lookup (bfd *abfd ATTRIBUTE_UNUSED, case BFD_RELOC_CTOR: r = R_PPC_ADDR32; break; case BFD_RELOC_PPC_TOC16: r = R_PPC_TOC16; break; case BFD_RELOC_PPC_TLS: r = R_PPC_TLS; break; - case BFD_RELOC_PPC_TLSGD: r = R_PPC_TLSGD; break; - case BFD_RELOC_PPC_TLSLD: r = R_PPC_TLSLD; break; case BFD_RELOC_PPC_DTPMOD: r = R_PPC_DTPMOD32; break; case BFD_RELOC_PPC_TPREL16: r = R_PPC_TPREL16; break; case BFD_RELOC_PPC_TPREL16_LO: r = R_PPC_TPREL16_LO; break; @@ -2375,34 +2345,16 @@ struct plt_entry bfd_vma glink_offset; }; -/* Of those relocs that might be copied as dynamic relocs, this function +/* Of those relocs that might be copied as dynamic relocs, this macro selects those that must be copied when linking a shared library, even when the symbol is local. */ -static int -must_be_dyn_reloc (struct bfd_link_info *info, - enum elf_ppc_reloc_type r_type) -{ - switch (r_type) - { - default: - return 1; - - case R_PPC_REL24: - case R_PPC_REL14: - case R_PPC_REL14_BRTAKEN: - case R_PPC_REL14_BRNTAKEN: - case R_PPC_REL32: - return 0; - - case R_PPC_TPREL32: - case R_PPC_TPREL16: - case R_PPC_TPREL16_LO: - case R_PPC_TPREL16_HI: - case R_PPC_TPREL16_HA: - return !info->executable; - } -} +#define MUST_BE_DYN_RELOC(RTYPE) \ + ((RTYPE) != R_PPC_REL24 \ + && (RTYPE) != R_PPC_REL14 \ + && (RTYPE) != R_PPC_REL14_BRTAKEN \ + && (RTYPE) != R_PPC_REL14_BRNTAKEN \ + && (RTYPE) != R_PPC_REL32) /* If ELIMINATE_COPY_RELOCS is non-zero, the linker will try to avoid copying dynamic variables from a shared lib into an app's dynbss @@ -2469,7 +2421,7 @@ struct ppc_elf_link_hash_table /* The .got.plt section (VxWorks only)*/ asection *sgotplt; - /* Shortcut to __tls_get_addr. */ + /* Shortcut to .__tls_get_addr. */ struct elf_link_hash_entry *tls_get_addr; /* The bfd that forced an old-style PLT. */ @@ -3088,7 +3040,6 @@ ppc_elf_check_relocs (bfd *abfd, const Elf_Internal_Rela *rel; const Elf_Internal_Rela *rel_end; asection *got2, *sreloc; - struct elf_link_hash_entry *tga; if (info->relocatable) return TRUE; @@ -3112,8 +3063,6 @@ ppc_elf_check_relocs (bfd *abfd, ppc_elf_howto_init (); htab = ppc_elf_hash_table (info); - tga = elf_link_hash_lookup (&htab->elf, "__tls_get_addr", - FALSE, FALSE, TRUE); symtab_hdr = &elf_tdata (abfd)->symtab_hdr; sym_hashes = elf_sym_hashes (abfd); got2 = bfd_get_section_by_name (abfd, ".got2"); @@ -3125,7 +3074,7 @@ ppc_elf_check_relocs (bfd *abfd, unsigned long r_symndx; enum elf_ppc_reloc_type r_type; struct elf_link_hash_entry *h; - int tls_type; + int tls_type = 0; r_symndx = ELF32_R_SYM (rel->r_info); if (r_symndx < symtab_hdr->sh_info) @@ -3152,48 +3101,14 @@ ppc_elf_check_relocs (bfd *abfd, BFD_ASSERT (h == htab->elf.hgot); } - tls_type = 0; r_type = ELF32_R_TYPE (rel->r_info); - if (h != NULL && h == tga) - switch (r_type) - { - default: - break; - - case R_PPC_PLTREL24: - case R_PPC_LOCAL24PC: - case R_PPC_REL24: - case R_PPC_REL14: - case R_PPC_REL14_BRTAKEN: - case R_PPC_REL14_BRNTAKEN: - case R_PPC_ADDR24: - case R_PPC_ADDR14: - case R_PPC_ADDR14_BRTAKEN: - case R_PPC_ADDR14_BRNTAKEN: - if (rel != relocs - && (ELF32_R_TYPE (rel[-1].r_info) == R_PPC_TLSGD - || ELF32_R_TYPE (rel[-1].r_info) == R_PPC_TLSLD)) - /* We have a new-style __tls_get_addr call with a marker - reloc. */ - ; - else - /* Mark this section as having an old-style call. */ - sec->has_tls_get_addr_call = 1; - break; - } - switch (r_type) { - case R_PPC_TLSGD: - case R_PPC_TLSLD: - /* These special tls relocs tie a call to __tls_get_addr with - its parameter symbol. */ - break; - case R_PPC_GOT_TLSLD16: case R_PPC_GOT_TLSLD16_LO: case R_PPC_GOT_TLSLD16_HI: case R_PPC_GOT_TLSLD16_HA: + htab->tlsld_got.refcount += 1; tls_type = TLS_TLS | TLS_LD; goto dogottls; @@ -3208,7 +3123,7 @@ ppc_elf_check_relocs (bfd *abfd, case R_PPC_GOT_TPREL16_LO: case R_PPC_GOT_TPREL16_HI: case R_PPC_GOT_TPREL16_HA: - if (!info->executable) + if (info->shared) info->flags |= DF_STATIC_TLS; tls_type = TLS_TLS | TLS_TPREL; goto dogottls; @@ -3443,7 +3358,7 @@ ppc_elf_check_relocs (bfd *abfd, /* This refers only to functions defined in the shared library. */ case R_PPC_LOCAL24PC: - if (h != NULL && h == htab->elf.hgot && htab->plt_type == PLT_UNSET) + if (h && h == htab->elf.hgot && htab->plt_type == PLT_UNSET) { htab->plt_type = PLT_OLD; htab->old_bfd = abfd; @@ -3466,11 +3381,7 @@ ppc_elf_check_relocs (bfd *abfd, /* We shouldn't really be seeing these. */ case R_PPC_TPREL32: - case R_PPC_TPREL16: - case R_PPC_TPREL16_LO: - case R_PPC_TPREL16_HI: - case R_PPC_TPREL16_HA: - if (!info->executable) + if (info->shared) info->flags |= DF_STATIC_TLS; goto dodyn; @@ -3479,6 +3390,14 @@ ppc_elf_check_relocs (bfd *abfd, case R_PPC_DTPREL32: goto dodyn; + case R_PPC_TPREL16: + case R_PPC_TPREL16_LO: + case R_PPC_TPREL16_HI: + case R_PPC_TPREL16_HA: + if (info->shared) + info->flags |= DF_STATIC_TLS; + goto dodyn; + case R_PPC_REL32: if (h == NULL && got2 != NULL @@ -3569,7 +3488,7 @@ ppc_elf_check_relocs (bfd *abfd, dynamic library if we manage to avoid copy relocs for the symbol. */ if ((info->shared - && (must_be_dyn_reloc (info, r_type) + && (MUST_BE_DYN_RELOC (r_type) || (h != NULL && (! info->symbolic || h->root.type == bfd_link_hash_defweak @@ -3664,7 +3583,7 @@ ppc_elf_check_relocs (bfd *abfd, } p->count += 1; - if (!must_be_dyn_reloc (info, r_type)) + if (!MUST_BE_DYN_RELOC (r_type)) p->pc_count += 1; } @@ -3984,6 +3903,9 @@ ppc_elf_gc_sweep_hook (bfd *abfd, case R_PPC_GOT_TLSLD16_LO: case R_PPC_GOT_TLSLD16_HI: case R_PPC_GOT_TLSLD16_HA: + htab->tlsld_got.refcount -= 1; + /* Fall thru */ + case R_PPC_GOT_TLSGD16: case R_PPC_GOT_TLSGD16_LO: case R_PPC_GOT_TLSGD16_HI: @@ -4057,8 +3979,7 @@ ppc_elf_gc_sweep_hook (bfd *abfd, return TRUE; } -/* Set plt output section type, htab->tls_get_addr, and call the - generic ELF tls_setup function. */ +/* Set htab->tls_get_addr and call the generic ELF tls_setup function. */ asection * ppc_elf_tls_setup (bfd *obfd, struct bfd_link_info *info) @@ -4079,43 +4000,6 @@ ppc_elf_tls_setup (bfd *obfd, struct bfd_link_info *info) return _bfd_elf_tls_setup (obfd, info); } -/* Return TRUE iff REL is a branch reloc with a global symbol matching - HASH. */ - -static bfd_boolean -branch_reloc_hash_match (const bfd *ibfd, - const Elf_Internal_Rela *rel, - const struct elf_link_hash_entry *hash) -{ - Elf_Internal_Shdr *symtab_hdr = &elf_tdata (ibfd)->symtab_hdr; - enum elf_ppc_reloc_type r_type = ELF32_R_TYPE (rel->r_info); - unsigned int r_symndx = ELF32_R_SYM (rel->r_info); - - if (r_symndx >= symtab_hdr->sh_info - && (r_type == R_PPC_PLTREL24 - || r_type == R_PPC_LOCAL24PC - || r_type == R_PPC_REL14 - || r_type == R_PPC_REL14_BRTAKEN - || r_type == R_PPC_REL14_BRNTAKEN - || r_type == R_PPC_REL24 - || r_type == R_PPC_ADDR24 - || r_type == R_PPC_ADDR14 - || r_type == R_PPC_ADDR14_BRTAKEN - || r_type == R_PPC_ADDR14_BRNTAKEN)) - { - struct elf_link_hash_entry **sym_hashes = elf_sym_hashes (ibfd); - struct elf_link_hash_entry *h; - - h = sym_hashes[r_symndx - symtab_hdr->sh_info]; - while (h->root.type == bfd_link_hash_indirect - || h->root.type == bfd_link_hash_warning) - h = (struct elf_link_hash_entry *) h->root.u.i.link; - if (h == hash) - return TRUE; - } - return FALSE; -} - /* Run through all the TLS relocs looking for optimization opportunities. */ @@ -4126,204 +4010,187 @@ ppc_elf_tls_optimize (bfd *obfd ATTRIBUTE_UNUSED, bfd *ibfd; asection *sec; struct ppc_elf_link_hash_table *htab; - int pass; - if (info->relocatable || !info->executable) + if (info->relocatable || info->shared) return TRUE; htab = ppc_elf_hash_table (info); - /* Make two passes through the relocs. First time check that tls - relocs involved in setting up a tls_get_addr call are indeed - followed by such a call. If they are not, exclude them from - the optimizations done on the second pass. */ - for (pass = 0; pass < 2; ++pass) - for (ibfd = info->input_bfds; ibfd != NULL; ibfd = ibfd->link_next) - { - Elf_Internal_Sym *locsyms = NULL; - Elf_Internal_Shdr *symtab_hdr = &elf_tdata (ibfd)->symtab_hdr; - - for (sec = ibfd->sections; sec != NULL; sec = sec->next) - if (sec->has_tls_reloc && !bfd_is_abs_section (sec->output_section)) - { - Elf_Internal_Rela *relstart, *rel, *relend; + for (ibfd = info->input_bfds; ibfd != NULL; ibfd = ibfd->link_next) + { + Elf_Internal_Sym *locsyms = NULL; + Elf_Internal_Shdr *symtab_hdr = &elf_tdata (ibfd)->symtab_hdr; - /* Read the relocations. */ - relstart = _bfd_elf_link_read_relocs (ibfd, sec, NULL, NULL, - info->keep_memory); - if (relstart == NULL) - return FALSE; + for (sec = ibfd->sections; sec != NULL; sec = sec->next) + if (sec->has_tls_reloc && !bfd_is_abs_section (sec->output_section)) + { + Elf_Internal_Rela *relstart, *rel, *relend; + int expecting_tls_get_addr; - relend = relstart + sec->reloc_count; - for (rel = relstart; rel < relend; rel++) - { - enum elf_ppc_reloc_type r_type; - unsigned long r_symndx; - struct elf_link_hash_entry *h = NULL; - char *tls_mask; - char tls_set, tls_clear; - bfd_boolean is_local; - int expecting_tls_get_addr; - bfd_signed_vma *got_count; - - r_symndx = ELF32_R_SYM (rel->r_info); - if (r_symndx >= symtab_hdr->sh_info) - { - struct elf_link_hash_entry **sym_hashes; + /* Read the relocations. */ + relstart = _bfd_elf_link_read_relocs (ibfd, sec, NULL, NULL, + info->keep_memory); + if (relstart == NULL) + return FALSE; - sym_hashes = elf_sym_hashes (ibfd); - h = sym_hashes[r_symndx - symtab_hdr->sh_info]; - while (h->root.type == bfd_link_hash_indirect - || h->root.type == bfd_link_hash_warning) - h = (struct elf_link_hash_entry *) h->root.u.i.link; - } + expecting_tls_get_addr = 0; + relend = relstart + sec->reloc_count; + for (rel = relstart; rel < relend; rel++) + { + enum elf_ppc_reloc_type r_type; + unsigned long r_symndx; + struct elf_link_hash_entry *h = NULL; + char *tls_mask; + char tls_set, tls_clear; + bfd_boolean is_local; + + r_symndx = ELF32_R_SYM (rel->r_info); + if (r_symndx >= symtab_hdr->sh_info) + { + struct elf_link_hash_entry **sym_hashes; - expecting_tls_get_addr = 0; - is_local = FALSE; - if (h == NULL - || !h->def_dynamic) - is_local = TRUE; + sym_hashes = elf_sym_hashes (ibfd); + h = sym_hashes[r_symndx - symtab_hdr->sh_info]; + while (h->root.type == bfd_link_hash_indirect + || h->root.type == bfd_link_hash_warning) + h = (struct elf_link_hash_entry *) h->root.u.i.link; + } - r_type = ELF32_R_TYPE (rel->r_info); - switch (r_type) - { - case R_PPC_GOT_TLSLD16: - case R_PPC_GOT_TLSLD16_LO: - expecting_tls_get_addr = 1; - /* Fall thru */ - - case R_PPC_GOT_TLSLD16_HI: - case R_PPC_GOT_TLSLD16_HA: - /* These relocs should never be against a symbol - defined in a shared lib. Leave them alone if - that turns out to be the case. */ - if (!is_local) - continue; - - /* LD -> LE */ - tls_set = 0; - tls_clear = TLS_LD; - break; - - case R_PPC_GOT_TLSGD16: - case R_PPC_GOT_TLSGD16_LO: - expecting_tls_get_addr = 1; - /* Fall thru */ - - case R_PPC_GOT_TLSGD16_HI: - case R_PPC_GOT_TLSGD16_HA: - if (is_local) - /* GD -> LE */ - tls_set = 0; - else - /* GD -> IE */ - tls_set = TLS_TLS | TLS_TPRELGD; - tls_clear = TLS_GD; - break; - - case R_PPC_GOT_TPREL16: - case R_PPC_GOT_TPREL16_LO: - case R_PPC_GOT_TPREL16_HI: - case R_PPC_GOT_TPREL16_HA: - if (is_local) - { - /* IE -> LE */ - tls_set = 0; - tls_clear = TLS_TPREL; - break; - } - else - continue; + is_local = FALSE; + if (h == NULL + || !h->def_dynamic) + is_local = TRUE; - default: + r_type = ELF32_R_TYPE (rel->r_info); + switch (r_type) + { + case R_PPC_GOT_TLSLD16: + case R_PPC_GOT_TLSLD16_LO: + case R_PPC_GOT_TLSLD16_HI: + case R_PPC_GOT_TLSLD16_HA: + /* These relocs should never be against a symbol + defined in a shared lib. Leave them alone if + that turns out to be the case. */ + expecting_tls_get_addr = 0; + htab->tlsld_got.refcount -= 1; + if (!is_local) continue; - } - if (pass == 0) - { - if (!expecting_tls_get_addr - || !sec->has_tls_get_addr_call) - continue; - - if (rel + 1 < relend - && branch_reloc_hash_match (ibfd, rel + 1, - htab->tls_get_addr)) - continue; - - /* Uh oh, we didn't find the expected call. We - could just mark this symbol to exclude it - from tls optimization but it's safer to skip - the entire section. */ - sec->has_tls_reloc = 0; - break; - } + /* LD -> LE */ + tls_set = 0; + tls_clear = TLS_LD; + expecting_tls_get_addr = 1; + break; - if (h != NULL) - { - tls_mask = &ppc_elf_hash_entry (h)->tls_mask; - got_count = &h->got.refcount; - } - else - { - Elf_Internal_Sym *sym; - bfd_signed_vma *lgot_refs; - char *lgot_masks; + case R_PPC_GOT_TLSGD16: + case R_PPC_GOT_TLSGD16_LO: + case R_PPC_GOT_TLSGD16_HI: + case R_PPC_GOT_TLSGD16_HA: + if (is_local) + /* GD -> LE */ + tls_set = 0; + else + /* GD -> IE */ + tls_set = TLS_TLS | TLS_TPRELGD; + tls_clear = TLS_GD; + expecting_tls_get_addr = 1; + break; - if (locsyms == NULL) - { - locsyms = (Elf_Internal_Sym *) symtab_hdr->contents; - if (locsyms == NULL) - locsyms = bfd_elf_get_elf_syms (ibfd, symtab_hdr, - symtab_hdr->sh_info, - 0, NULL, NULL, NULL); - if (locsyms == NULL) - { - if (elf_section_data (sec)->relocs != relstart) - free (relstart); - return FALSE; - } - } - sym = locsyms + r_symndx; - lgot_refs = elf_local_got_refcounts (ibfd); - if (lgot_refs == NULL) - abort (); - lgot_masks = (char *) (lgot_refs + symtab_hdr->sh_info); - tls_mask = &lgot_masks[r_symndx]; - got_count = &lgot_refs[r_symndx]; - } + case R_PPC_GOT_TPREL16: + case R_PPC_GOT_TPREL16_LO: + case R_PPC_GOT_TPREL16_HI: + case R_PPC_GOT_TPREL16_HA: + expecting_tls_get_addr = 0; + if (is_local) + { + /* IE -> LE */ + tls_set = 0; + tls_clear = TLS_TPREL; + break; + } + else + continue; - if (tls_set == 0) - { - /* We managed to get rid of a got entry. */ - if (*got_count > 0) - *got_count -= 1; - } + case R_PPC_REL14: + case R_PPC_REL14_BRTAKEN: + case R_PPC_REL14_BRNTAKEN: + case R_PPC_REL24: + if (expecting_tls_get_addr + && h != NULL + && h == htab->tls_get_addr) + { + struct plt_entry *ent = find_plt_ent (h, NULL, 0); + if (ent != NULL && ent->plt.refcount > 0) + ent->plt.refcount -= 1; + } + expecting_tls_get_addr = 0; + continue; - if (expecting_tls_get_addr) - { - struct plt_entry *ent; + default: + expecting_tls_get_addr = 0; + continue; + } - ent = find_plt_ent (htab->tls_get_addr, NULL, 0); - if (ent != NULL && ent->plt.refcount > 0) - ent->plt.refcount -= 1; - } + if (h != NULL) + { + if (tls_set == 0) + { + /* We managed to get rid of a got entry. */ + if (h->got.refcount > 0) + h->got.refcount -= 1; + } + tls_mask = &ppc_elf_hash_entry (h)->tls_mask; + } + else + { + Elf_Internal_Sym *sym; + bfd_signed_vma *lgot_refs; + char *lgot_masks; - *tls_mask |= tls_set; - *tls_mask &= ~tls_clear; - } + if (locsyms == NULL) + { + locsyms = (Elf_Internal_Sym *) symtab_hdr->contents; + if (locsyms == NULL) + locsyms = bfd_elf_get_elf_syms (ibfd, symtab_hdr, + symtab_hdr->sh_info, + 0, NULL, NULL, NULL); + if (locsyms == NULL) + { + if (elf_section_data (sec)->relocs != relstart) + free (relstart); + return FALSE; + } + } + sym = locsyms + r_symndx; + lgot_refs = elf_local_got_refcounts (ibfd); + if (lgot_refs == NULL) + abort (); + if (tls_set == 0) + { + /* We managed to get rid of a got entry. */ + if (lgot_refs[r_symndx] > 0) + lgot_refs[r_symndx] -= 1; + } + lgot_masks = (char *) (lgot_refs + symtab_hdr->sh_info); + tls_mask = &lgot_masks[r_symndx]; + } - if (elf_section_data (sec)->relocs != relstart) - free (relstart); - } + *tls_mask |= tls_set; + *tls_mask &= ~tls_clear; + } - if (locsyms != NULL - && (symtab_hdr->contents != (unsigned char *) locsyms)) - { - if (!info->keep_memory) - free (locsyms); - else - symtab_hdr->contents = (unsigned char *) locsyms; + if (elf_section_data (sec)->relocs != relstart) + free (relstart); } - } + + if (locsyms != NULL + && (symtab_hdr->contents != (unsigned char *) locsyms)) + { + if (!info->keep_memory) + free (locsyms); + else + symtab_hdr->contents = (unsigned char *) locsyms; + } + } return TRUE; } @@ -4748,11 +4615,8 @@ allocate_dynrelocs (struct elf_link_hash_entry *h, void *inf) if (eh->tls_mask == (TLS_TLS | TLS_LD) && !eh->elf.def_dynamic) - { - /* If just an LD reloc, we'll just use htab->tlsld_got.offset. */ - htab->tlsld_got.refcount += 1; - eh->elf.got.offset = (bfd_vma) -1; - } + /* If just an LD reloc, we'll just use htab->tlsld_got.offset. */ + eh->elf.got.offset = (bfd_vma) -1; else { bfd_boolean dyn; @@ -4800,7 +4664,7 @@ allocate_dynrelocs (struct elf_link_hash_entry *h, void *inf) if (info->shared) { /* Relocs that use pc_count are those that appear on a call insn, - or certain REL relocs (see must_be_dyn_reloc) that can be + or certain REL relocs (see MUST_BE_DYN_RELOC) that can be generated via assembly. We want calls to protected symbols to resolve directly to the function rather than going via the plt. If people want function pointer comparisons to work as expected @@ -5027,9 +4891,6 @@ ppc_elf_size_dynamic_sections (bfd *output_bfd ATTRIBUTE_UNUSED, *local_got = (bfd_vma) -1; } - /* Allocate space for global sym dynamic relocs. */ - elf_link_hash_traverse (elf_hash_table (info), allocate_dynrelocs, info); - if (htab->tlsld_got.refcount > 0) { htab->tlsld_got.offset = allocate_got (htab, 8); @@ -5039,6 +4900,9 @@ ppc_elf_size_dynamic_sections (bfd *output_bfd ATTRIBUTE_UNUSED, else htab->tlsld_got.offset = (bfd_vma) -1; + /* Allocate space for global sym dynamic relocs. */ + elf_link_hash_traverse (elf_hash_table (info), allocate_dynrelocs, info); + if (htab->got != NULL && htab->plt_type != PLT_VXWORKS) { unsigned int g_o_t = 32768; @@ -5890,13 +5754,16 @@ ppc_elf_relocate_section (bfd *output_bfd, for the final instruction stream. */ tls_mask = 0; tls_gd = 0; - if (h != NULL) - tls_mask = ((struct ppc_elf_link_hash_entry *) h)->tls_mask; - else if (local_got_offsets != NULL) + if (IS_PPC_TLS_RELOC (r_type)) { - char *lgot_masks; - lgot_masks = (char *) (local_got_offsets + symtab_hdr->sh_info); - tls_mask = lgot_masks[r_symndx]; + if (h != NULL) + tls_mask = ((struct ppc_elf_link_hash_entry *) h)->tls_mask; + else if (local_got_offsets != NULL) + { + char *lgot_masks; + lgot_masks = (char *) (local_got_offsets + symtab_hdr->sh_info); + tls_mask = lgot_masks[r_symndx]; + } } /* Ensure reloc mapping code below stays sane. */ @@ -6003,147 +5870,85 @@ ppc_elf_relocate_section (bfd *output_bfd, case R_PPC_GOT_TLSGD16_LO: tls_gd = TLS_TPRELGD; if (tls_mask != 0 && (tls_mask & TLS_GD) == 0) - goto tls_ldgd_opt; + goto tls_get_addr_check; break; case R_PPC_GOT_TLSLD16: case R_PPC_GOT_TLSLD16_LO: if (tls_mask != 0 && (tls_mask & TLS_LD) == 0) { - unsigned int insn1, insn2; - bfd_vma offset; - - tls_ldgd_opt: - offset = (bfd_vma) -1; - /* If not using the newer R_PPC_TLSGD/LD to mark - __tls_get_addr calls, we must trust that the call - stays with its arg setup insns, ie. that the next - reloc is the __tls_get_addr call associated with - the current reloc. Edit both insns. */ - if (input_section->has_tls_get_addr_call - && rel + 1 < relend - && branch_reloc_hash_match (input_bfd, rel + 1, - htab->tls_get_addr)) - offset = rel[1].r_offset; - if ((tls_mask & tls_gd) != 0) + tls_get_addr_check: + if (rel + 1 < relend) { - /* IE */ + enum elf_ppc_reloc_type r_type2; + unsigned long r_symndx2; + struct elf_link_hash_entry *h2; + bfd_vma insn1, insn2; + bfd_vma offset; + + /* The next instruction should be a call to + __tls_get_addr. Peek at the reloc to be sure. */ + r_type2 = ELF32_R_TYPE (rel[1].r_info); + r_symndx2 = ELF32_R_SYM (rel[1].r_info); + if (r_symndx2 < symtab_hdr->sh_info + || (r_type2 != R_PPC_REL14 + && r_type2 != R_PPC_REL14_BRTAKEN + && r_type2 != R_PPC_REL14_BRNTAKEN + && r_type2 != R_PPC_REL24 + && r_type2 != R_PPC_PLTREL24)) + break; + + h2 = sym_hashes[r_symndx2 - symtab_hdr->sh_info]; + while (h2->root.type == bfd_link_hash_indirect + || h2->root.type == bfd_link_hash_warning) + h2 = (struct elf_link_hash_entry *) h2->root.u.i.link; + if (h2 == NULL || h2 != htab->tls_get_addr) + break; + + /* OK, it checks out. Replace the call. */ + offset = rel[1].r_offset; insn1 = bfd_get_32 (output_bfd, contents + rel->r_offset - d_offset); - insn1 &= (1 << 26) - 1; - insn1 |= 32 << 26; /* lwz */ - if (offset != (bfd_vma) -1) + if ((tls_mask & tls_gd) != 0) { - rel[1].r_info - = ELF32_R_INFO (ELF32_R_SYM (rel[1].r_info), - R_PPC_NONE); + /* IE */ + insn1 &= (1 << 26) - 1; + insn1 |= 32 << 26; /* lwz */ insn2 = 0x7c631214; /* add 3,3,2 */ - bfd_put_32 (output_bfd, insn2, contents + offset); + rel[1].r_info = ELF32_R_INFO (r_symndx2, R_PPC_NONE); + rel[1].r_addend = 0; + r_type = (((r_type - (R_PPC_GOT_TLSGD16 & 3)) & 3) + + R_PPC_GOT_TPREL16); + rel->r_info = ELF32_R_INFO (r_symndx, r_type); } - r_type = (((r_type - (R_PPC_GOT_TLSGD16 & 3)) & 3) - + R_PPC_GOT_TPREL16); - rel->r_info = ELF32_R_INFO (r_symndx, r_type); - } - else - { - /* LE */ - insn1 = 0x3c620000; /* addis 3,2,0 */ - if (tls_gd == 0) + else { - /* Was an LD reloc. */ - for (r_symndx = 0; - r_symndx < symtab_hdr->sh_info; - r_symndx++) - if (local_sections[r_symndx] == sec) - break; - if (r_symndx >= symtab_hdr->sh_info) - r_symndx = 0; - rel->r_addend = htab->elf.tls_sec->vma + DTP_OFFSET; - if (r_symndx != 0) - rel->r_addend -= (local_syms[r_symndx].st_value - + sec->output_offset - + sec->output_section->vma); + /* LE */ + insn1 = 0x3c620000; /* addis 3,2,0 */ + insn2 = 0x38630000; /* addi 3,3,0 */ + if (tls_gd == 0) + { + /* Was an LD reloc. */ + r_symndx = 0; + rel->r_addend = htab->elf.tls_sec->vma + DTP_OFFSET; + } + r_type = R_PPC_TPREL16_HA; + rel->r_info = ELF32_R_INFO (r_symndx, r_type); + rel[1].r_info = ELF32_R_INFO (r_symndx, + R_PPC_TPREL16_LO); + rel[1].r_offset += d_offset; + rel[1].r_addend = rel->r_addend; } - r_type = R_PPC_TPREL16_HA; - rel->r_info = ELF32_R_INFO (r_symndx, r_type); - if (offset != (bfd_vma) -1) + bfd_put_32 (output_bfd, insn1, contents + rel->r_offset - d_offset); + bfd_put_32 (output_bfd, insn2, contents + offset); + if (tls_gd == 0) { - rel[1].r_info = ELF32_R_INFO (r_symndx, R_PPC_TPREL16_LO); - rel[1].r_offset = offset + d_offset; - rel[1].r_addend = rel->r_addend; - insn2 = 0x38630000; /* addi 3,3,0 */ - bfd_put_32 (output_bfd, insn2, contents + offset); + /* We changed the symbol on an LD reloc. Start over + in order to get h, sym, sec etc. right. */ + rel--; + continue; } } - bfd_put_32 (output_bfd, insn1, - contents + rel->r_offset - d_offset); - if (tls_gd == 0) - { - /* We changed the symbol on an LD reloc. Start over - in order to get h, sym, sec etc. right. */ - rel--; - continue; - } - } - break; - - case R_PPC_TLSGD: - if (tls_mask != 0 && (tls_mask & TLS_GD) == 0) - { - unsigned int insn2; - bfd_vma offset = rel->r_offset; - - if ((tls_mask & TLS_TPRELGD) != 0) - { - /* IE */ - r_type = R_PPC_NONE; - insn2 = 0x7c631214; /* add 3,3,2 */ - } - else - { - /* LE */ - r_type = R_PPC_TPREL16_LO; - rel->r_offset += d_offset; - insn2 = 0x38630000; /* addi 3,3,0 */ - } - rel->r_info = ELF32_R_INFO (r_symndx, r_type); - bfd_put_32 (output_bfd, insn2, contents + offset); - /* Zap the reloc on the _tls_get_addr call too. */ - BFD_ASSERT (offset == rel[1].r_offset); - rel[1].r_info = ELF32_R_INFO (ELF32_R_SYM (rel[1].r_info), - R_PPC_NONE); - } - break; - - case R_PPC_TLSLD: - if (tls_mask != 0 && (tls_mask & TLS_LD) == 0) - { - unsigned int insn2; - - for (r_symndx = 0; - r_symndx < symtab_hdr->sh_info; - r_symndx++) - if (local_sections[r_symndx] == sec) - break; - if (r_symndx >= symtab_hdr->sh_info) - r_symndx = 0; - rel->r_addend = htab->elf.tls_sec->vma + DTP_OFFSET; - if (r_symndx != 0) - rel->r_addend -= (local_syms[r_symndx].st_value - + sec->output_offset - + sec->output_section->vma); - - rel->r_info = ELF32_R_INFO (r_symndx, R_PPC_TPREL16_LO); - rel->r_offset += d_offset; - insn2 = 0x38630000; /* addi 3,3,0 */ - bfd_put_32 (output_bfd, insn2, - contents + rel->r_offset - d_offset); - /* Zap the reloc on the _tls_get_addr call too. */ - BFD_ASSERT (rel->r_offset - d_offset == rel[1].r_offset); - rel[1].r_info = ELF32_R_INFO (ELF32_R_SYM (rel[1].r_info), - R_PPC_NONE); - rel--; - continue; } break; } @@ -6185,7 +5990,7 @@ ppc_elf_relocate_section (bfd *output_bfd, howto = NULL; if (r_type < R_PPC_max) howto = ppc_elf_howto_table[r_type]; - switch ((int) r_type) + switch (r_type) { default: (*_bfd_error_handler) @@ -6198,8 +6003,6 @@ ppc_elf_relocate_section (bfd *output_bfd, case R_PPC_NONE: case R_PPC_TLS: - case R_PPC_TLSGD: - case R_PPC_TLSLD: case R_PPC_EMB_MRKREF: case R_PPC_GNU_VTINHERIT: case R_PPC_GNU_VTENTRY: @@ -6241,7 +6044,6 @@ ppc_elf_relocate_section (bfd *output_bfd, case R_PPC_GOT16_LO: case R_PPC_GOT16_HI: case R_PPC_GOT16_HA: - tls_mask = 0; dogot: { /* Relocation is to the entry for this symbol in the global @@ -6540,7 +6342,7 @@ ppc_elf_relocate_section (bfd *output_bfd, && (h == NULL || ELF_ST_VISIBILITY (h->other) == STV_DEFAULT || h->root.type != bfd_link_hash_undefweak) - && (must_be_dyn_reloc (info, r_type) + && (MUST_BE_DYN_RELOC (r_type) || !SYMBOL_CALLS_LOCAL (info, h))) || (ELIMINATE_COPY_RELOCS && !info->shared @@ -6609,10 +6411,10 @@ ppc_elf_relocate_section (bfd *output_bfd, outrel.r_info = ELF32_R_INFO (0, R_PPC_RELATIVE); else { - long indx = 0; + long indx; - if (r_symndx == 0 || bfd_is_abs_section (sec)) - ; + if (bfd_is_abs_section (sec)) + indx = 0; else if (sec == NULL || sec->owner == NULL) { bfd_set_error (bfd_error_bad_value); diff --git a/contrib/binutils/bfd/elf64-ppc.c b/contrib/binutils/bfd/elf64-ppc.c index 6b2344dda440..717452d63699 100644 --- a/contrib/binutils/bfd/elf64-ppc.c +++ b/contrib/binutils/bfd/elf64-ppc.c @@ -130,25 +130,21 @@ static bfd_vma opd_entry_value /* .plt call stub instructions. The normal stub is like this, but sometimes the .plt entry crosses a 64k boundary and we need to - insert an addi to adjust r12. */ + insert an addis to adjust r12. */ #define PLT_CALL_STUB_SIZE (7*4) #define ADDIS_R12_R2 0x3d820000 /* addis %r12,%r2,xxx@ha */ #define STD_R2_40R1 0xf8410028 /* std %r2,40(%r1) */ #define LD_R11_0R12 0xe96c0000 /* ld %r11,xxx+0@l(%r12) */ -#define MTCTR_R11 0x7d6903a6 /* mtctr %r11 */ #define LD_R2_0R12 0xe84c0000 /* ld %r2,xxx+8@l(%r12) */ +#define MTCTR_R11 0x7d6903a6 /* mtctr %r11 */ /* ld %r11,xxx+16@l(%r12) */ #define BCTR 0x4e800420 /* bctr */ #define ADDIS_R12_R12 0x3d8c0000 /* addis %r12,%r12,off@ha */ -#define ADDI_R12_R12 0x398c0000 /* addi %r12,%r12,off@l */ #define ADDIS_R2_R2 0x3c420000 /* addis %r2,%r2,off@ha */ #define ADDI_R2_R2 0x38420000 /* addi %r2,%r2,off@l */ -#define LD_R11_0R2 0xe9620000 /* ld %r11,xxx+0(%r2) */ -#define LD_R2_0R2 0xe8420000 /* ld %r2,xxx+0(%r2) */ - #define LD_R2_40R1 0xe8410028 /* ld %r2,40(%r1) */ /* glink call stub instructions. We enter with the index in R0. */ @@ -1233,7 +1229,7 @@ static reloc_howto_type ppc64_elf_howto_raw[] = { 0xfffc, /* dst_mask */ FALSE), /* pcrel_offset */ - /* Marker relocs for TLS. */ + /* Marker reloc for TLS. */ HOWTO (R_PPC64_TLS, 0, /* rightshift */ 2, /* size (0 = byte, 1 = short, 2 = long) */ @@ -1248,34 +1244,6 @@ static reloc_howto_type ppc64_elf_howto_raw[] = { 0, /* dst_mask */ FALSE), /* pcrel_offset */ - HOWTO (R_PPC64_TLSGD, - 0, /* rightshift */ - 2, /* size (0 = byte, 1 = short, 2 = long) */ - 32, /* bitsize */ - FALSE, /* pc_relative */ - 0, /* bitpos */ - complain_overflow_dont, /* complain_on_overflow */ - bfd_elf_generic_reloc, /* special_function */ - "R_PPC64_TLSGD", /* name */ - FALSE, /* partial_inplace */ - 0, /* src_mask */ - 0, /* dst_mask */ - FALSE), /* pcrel_offset */ - - HOWTO (R_PPC64_TLSLD, - 0, /* rightshift */ - 2, /* size (0 = byte, 1 = short, 2 = long) */ - 32, /* bitsize */ - FALSE, /* pc_relative */ - 0, /* bitpos */ - complain_overflow_dont, /* complain_on_overflow */ - bfd_elf_generic_reloc, /* special_function */ - "R_PPC64_TLSLD", /* name */ - FALSE, /* partial_inplace */ - 0, /* src_mask */ - 0, /* dst_mask */ - FALSE), /* pcrel_offset */ - /* Computes the load module index of the load module that contains the definition of its TLS sym. */ HOWTO (R_PPC64_DTPMOD64, @@ -2057,10 +2025,6 @@ ppc64_elf_reloc_type_lookup (bfd *abfd ATTRIBUTE_UNUSED, break; case BFD_RELOC_PPC_TLS: r = R_PPC64_TLS; break; - case BFD_RELOC_PPC_TLSGD: r = R_PPC64_TLSGD; - break; - case BFD_RELOC_PPC_TLSLD: r = R_PPC64_TLSLD; - break; case BFD_RELOC_PPC_DTPMOD: r = R_PPC64_DTPMOD64; break; case BFD_RELOC_PPC_TPREL16: r = R_PPC64_TPREL16; @@ -2647,15 +2611,9 @@ struct _ppc64_elf_section_data /* After editing .opd, adjust references to opd local syms. */ long *opd_adjust; - /* An array for toc sections, indexed by offset/8. */ - struct _toc_sec_data - { - /* Specifies the relocation symbol index used at a given toc offset. */ - unsigned *symndx; - - /* And the relocation addend. */ - bfd_vma *add; - } toc; + /* An array for toc sections, indexed by offset/8. + Specifies the relocation symbol index used at a given toc offset. */ + unsigned *t_symndx; } u; enum _ppc64_sec_type sec_type:2; @@ -3198,8 +3156,7 @@ struct got_entry /* Unlike other ELF targets, we use separate GOT entries for the same symbol referenced from different input files. This is to support automatic multiple TOC/GOT sections, where the TOC base can vary - from one input file to another. FIXME: After group_sections we - ought to merge entries within the group. + from one input file to another. Point to the BFD owning this GOT entry. */ bfd *owner; @@ -3230,38 +3187,14 @@ struct plt_entry } plt; }; -/* Of those relocs that might be copied as dynamic relocs, this function +/* Of those relocs that might be copied as dynamic relocs, this macro selects those that must be copied when linking a shared library, even when the symbol is local. */ -static int -must_be_dyn_reloc (struct bfd_link_info *info, - enum elf_ppc64_reloc_type r_type) -{ - switch (r_type) - { - default: - return 1; - - case R_PPC64_REL32: - case R_PPC64_REL64: - case R_PPC64_REL30: - return 0; - - case R_PPC64_TPREL16: - case R_PPC64_TPREL16_LO: - case R_PPC64_TPREL16_HI: - case R_PPC64_TPREL16_HA: - case R_PPC64_TPREL16_DS: - case R_PPC64_TPREL16_LO_DS: - case R_PPC64_TPREL16_HIGHER: - case R_PPC64_TPREL16_HIGHERA: - case R_PPC64_TPREL16_HIGHEST: - case R_PPC64_TPREL16_HIGHESTA: - case R_PPC64_TPREL64: - return !info->executable; - } -} +#define MUST_BE_DYN_RELOC(RTYPE) \ + ((RTYPE) != R_PPC64_REL32 \ + && (RTYPE) != R_PPC64_REL64 \ + && (RTYPE) != R_PPC64_REL30) /* If ELIMINATE_COPY_RELOCS is non-zero, the linker will try to avoid copying dynamic variables from a shared lib into an app's dynbss @@ -3301,12 +3234,13 @@ must_be_dyn_reloc (struct bfd_link_info *info, ppc_stub_plt_call: Used to call a function in a shared library. If it so happens that the plt entry referenced crosses a 64k boundary, then an extra - "addi %r12,%r12,xxx@toc@l" will be inserted before the "mtctr". + "addis %r12,%r12,1" will be inserted before the load at xxx+8 or + xxx+16 as appropriate. . addis %r12,%r2,xxx@toc@ha . std %r2,40(%r1) . ld %r11,xxx+0@toc@l(%r12) - . mtctr %r11 . ld %r2,xxx+8@toc@l(%r12) + . mtctr %r11 . ld %r11,xxx+16@toc@l(%r12) . bctr @@ -3326,9 +3260,6 @@ must_be_dyn_reloc (struct bfd_link_info *info, . addi %r2,%r2,off@l . mtctr %r11 . bctr - - In cases where the "addis" instruction would add zero, the "addis" is - omitted and following instructions modified slightly in some cases. */ enum ppc_stub_type { @@ -4462,7 +4393,6 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, const Elf_Internal_Rela *rel_end; asection *sreloc; asection **opd_sym_map; - struct elf_link_hash_entry *tga, *dottga; if (info->relocatable) return TRUE; @@ -4477,10 +4407,6 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, return TRUE; htab = ppc_hash_table (info); - tga = elf_link_hash_lookup (&htab->elf, "__tls_get_addr", - FALSE, FALSE, TRUE); - dottga = elf_link_hash_lookup (&htab->elf, ".__tls_get_addr", - FALSE, FALSE, TRUE); symtab_hdr = &elf_tdata (abfd)->symtab_hdr; sym_hashes = elf_sym_hashes (abfd); @@ -4526,7 +4452,7 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, unsigned long r_symndx; struct elf_link_hash_entry *h; enum elf_ppc64_reloc_type r_type; - int tls_type; + int tls_type = 0; struct _ppc64_elf_section_data *ppc64_sec; r_symndx = ELF64_R_SYM (rel->r_info); @@ -4540,46 +4466,14 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, h = (struct elf_link_hash_entry *) h->root.u.i.link; } - tls_type = 0; r_type = ELF64_R_TYPE (rel->r_info); - if (h != NULL && (h == tga || h == dottga)) - switch (r_type) - { - default: - break; - - case R_PPC64_REL24: - case R_PPC64_REL14: - case R_PPC64_REL14_BRTAKEN: - case R_PPC64_REL14_BRNTAKEN: - case R_PPC64_ADDR24: - case R_PPC64_ADDR14: - case R_PPC64_ADDR14_BRTAKEN: - case R_PPC64_ADDR14_BRNTAKEN: - if (rel != relocs - && (ELF64_R_TYPE (rel[-1].r_info) == R_PPC64_TLSGD - || ELF64_R_TYPE (rel[-1].r_info) == R_PPC64_TLSLD)) - /* We have a new-style __tls_get_addr call with a marker - reloc. */ - ; - else - /* Mark this section as having an old-style call. */ - sec->has_tls_get_addr_call = 1; - break; - } - switch (r_type) { - case R_PPC64_TLSGD: - case R_PPC64_TLSLD: - /* These special tls relocs tie a call to __tls_get_addr with - its parameter symbol. */ - break; - case R_PPC64_GOT_TLSLD16: case R_PPC64_GOT_TLSLD16_LO: case R_PPC64_GOT_TLSLD16_HI: case R_PPC64_GOT_TLSLD16_HA: + ppc64_tlsld_got (abfd)->refcount += 1; tls_type = TLS_TLS | TLS_LD; goto dogottls; @@ -4594,7 +4488,7 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, case R_PPC64_GOT_TPREL16_LO_DS: case R_PPC64_GOT_TPREL16_HI: case R_PPC64_GOT_TPREL16_HA: - if (!info->executable) + if (info->shared) info->flags |= DF_STATIC_TLS; tls_type = TLS_TLS | TLS_TPREL; goto dogottls; @@ -4753,14 +4647,31 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, if (!update_plt_info (abfd, (struct ppc_link_hash_entry *) h, rel->r_addend)) return FALSE; - if (h == tga || h == dottga) + if (h == &htab->tls_get_addr->elf + || h == &htab->tls_get_addr_fd->elf) sec->has_tls_reloc = 1; + else if (htab->tls_get_addr == NULL + && CONST_STRNEQ (h->root.root.string, ".__tls_get_addr") + && (h->root.root.string[15] == 0 + || h->root.root.string[15] == '@')) + { + htab->tls_get_addr = (struct ppc_link_hash_entry *) h; + sec->has_tls_reloc = 1; + } + else if (htab->tls_get_addr_fd == NULL + && CONST_STRNEQ (h->root.root.string, "__tls_get_addr") + && (h->root.root.string[14] == 0 + || h->root.root.string[14] == '@')) + { + htab->tls_get_addr_fd = (struct ppc_link_hash_entry *) h; + sec->has_tls_reloc = 1; + } } break; case R_PPC64_TPREL64: tls_type = TLS_EXPLICIT | TLS_TLS | TLS_TPREL; - if (!info->executable) + if (info->shared) info->flags |= DF_STATIC_TLS; goto dotlstoc; @@ -4798,30 +4709,23 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, ppc64_sec = ppc64_elf_section_data (sec); if (ppc64_sec->sec_type != sec_toc) { - bfd_size_type amt; - /* One extra to simplify get_tls_mask. */ - amt = sec->size * sizeof (unsigned) / 8 + sizeof (unsigned); - ppc64_sec->u.toc.symndx = bfd_zalloc (abfd, amt); - if (ppc64_sec->u.toc.symndx == NULL) - return FALSE; - amt = sec->size * sizeof (bfd_vma) / 8; - ppc64_sec->u.toc.add = bfd_zalloc (abfd, amt); - if (ppc64_sec->u.toc.add == NULL) + bfd_size_type amt = sec->size * sizeof (unsigned) / 8 + 1; + ppc64_sec->u.t_symndx = bfd_zalloc (abfd, amt); + if (ppc64_sec->u.t_symndx == NULL) return FALSE; BFD_ASSERT (ppc64_sec->sec_type == sec_normal); ppc64_sec->sec_type = sec_toc; } BFD_ASSERT (rel->r_offset % 8 == 0); - ppc64_sec->u.toc.symndx[rel->r_offset / 8] = r_symndx; - ppc64_sec->u.toc.add[rel->r_offset / 8] = rel->r_addend; + ppc64_sec->u.t_symndx[rel->r_offset / 8] = r_symndx; /* Mark the second slot of a GD or LD entry. -1 to indicate GD and -2 to indicate LD. */ if (tls_type == (TLS_EXPLICIT | TLS_TLS | TLS_GD)) - ppc64_sec->u.toc.symndx[rel->r_offset / 8 + 1] = -1; + ppc64_sec->u.t_symndx[rel->r_offset / 8 + 1] = -1; else if (tls_type == (TLS_EXPLICIT | TLS_TLS | TLS_LD)) - ppc64_sec->u.toc.symndx[rel->r_offset / 8 + 1] = -2; + ppc64_sec->u.t_symndx[rel->r_offset / 8 + 1] = -2; goto dodyn; case R_PPC64_TPREL16: @@ -4836,8 +4740,7 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, case R_PPC64_TPREL16_HIGHESTA: if (info->shared) { - if (!info->executable) - info->flags |= DF_STATIC_TLS; + info->flags |= DF_STATIC_TLS; goto dodyn; } break; @@ -4923,7 +4826,7 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, symbol. */ dodyn: if ((info->shared - && (must_be_dyn_reloc (info, r_type) + && (MUST_BE_DYN_RELOC (r_type) || (h != NULL && (! info->symbolic || h->root.type == bfd_link_hash_defweak @@ -5019,7 +4922,7 @@ ppc64_elf_check_relocs (bfd *abfd, struct bfd_link_info *info, } p->count += 1; - if (!must_be_dyn_reloc (info, r_type)) + if (!MUST_BE_DYN_RELOC (r_type)) p->pc_count += 1; } break; @@ -5394,6 +5297,7 @@ ppc64_elf_gc_sweep_hook (bfd *abfd, struct bfd_link_info *info, case R_PPC64_GOT_TLSLD16_LO: case R_PPC64_GOT_TLSLD16_HI: case R_PPC64_GOT_TLSLD16_HA: + ppc64_tlsld_got (abfd)->refcount -= 1; tls_type = TLS_TLS | TLS_LD; goto dogot; @@ -5738,8 +5642,6 @@ func_desc_adjust (struct elf_link_hash_entry *h, void *inf) { fh->elf.root.type = fh->oh->elf.root.type; fh->elf.forced_local = 1; - fh->elf.def_regular = fh->oh->elf.def_regular; - fh->elf.def_dynamic = fh->oh->elf.def_dynamic; } /* If this is a function code symbol, transfer dynamic linking @@ -6183,12 +6085,9 @@ get_sym_h (struct elf_link_hash_entry **hp, type suitable for optimization, and 1 otherwise. */ static int -get_tls_mask (char **tls_maskp, - unsigned long *toc_symndx, - bfd_vma *toc_addend, +get_tls_mask (char **tls_maskp, unsigned long *toc_symndx, Elf_Internal_Sym **locsymsp, - const Elf_Internal_Rela *rel, - bfd *ibfd) + const Elf_Internal_Rela *rel, bfd *ibfd) { unsigned long r_symndx; int next_r; @@ -6216,14 +6115,12 @@ get_tls_mask (char **tls_maskp, off = sym->st_value; off += rel->r_addend; BFD_ASSERT (off % 8 == 0); - r_symndx = ppc64_elf_section_data (sec)->u.toc.symndx[off / 8]; - next_r = ppc64_elf_section_data (sec)->u.toc.symndx[off / 8 + 1]; - if (toc_symndx != NULL) - *toc_symndx = r_symndx; - if (toc_addend != NULL) - *toc_addend = ppc64_elf_section_data (sec)->u.toc.add[off / 8]; + r_symndx = ppc64_elf_section_data (sec)->u.t_symndx[off / 8]; + next_r = ppc64_elf_section_data (sec)->u.t_symndx[off / 8 + 1]; if (!get_sym_h (&h, &sym, &sec, tls_maskp, locsymsp, r_symndx, ibfd)) return 0; + if (toc_symndx != NULL) + *toc_symndx = r_symndx; if ((h == NULL || ((h->root.type == bfd_link_hash_defined || h->root.type == bfd_link_hash_defweak) @@ -6363,7 +6260,7 @@ dec_dynrel_count (bfd_vma r_info, } if ((info->shared - && (must_be_dyn_reloc (info, r_type) + && (MUST_BE_DYN_RELOC (r_type) || (h != NULL && (!info->symbolic || h->root.type == bfd_link_hash_defweak @@ -6403,7 +6300,7 @@ dec_dynrel_count (bfd_vma r_info, { if (p->sec == sec) { - if (!must_be_dyn_reloc (info, r_type)) + if (!MUST_BE_DYN_RELOC (r_type)) p->pc_count -= 1; p->count -= 1; if (p->count == 0) @@ -6840,49 +6737,36 @@ ppc64_elf_tls_setup (bfd *obfd, struct bfd_link_info *info) struct ppc_link_hash_table *htab; htab = ppc_hash_table (info); - htab->tls_get_addr = ((struct ppc_link_hash_entry *) - elf_link_hash_lookup (&htab->elf, ".__tls_get_addr", - FALSE, FALSE, TRUE)); - htab->tls_get_addr_fd = ((struct ppc_link_hash_entry *) - elf_link_hash_lookup (&htab->elf, "__tls_get_addr", - FALSE, FALSE, TRUE)); - return _bfd_elf_tls_setup (obfd, info); -} + if (htab->tls_get_addr != NULL) + { + struct ppc_link_hash_entry *h = htab->tls_get_addr; -/* Return TRUE iff REL is a branch reloc with a global symbol matching - HASH1 or HASH2. */ + while (h->elf.root.type == bfd_link_hash_indirect + || h->elf.root.type == bfd_link_hash_warning) + h = (struct ppc_link_hash_entry *) h->elf.root.u.i.link; -static bfd_boolean -branch_reloc_hash_match (const bfd *ibfd, - const Elf_Internal_Rela *rel, - const struct ppc_link_hash_entry *hash1, - const struct ppc_link_hash_entry *hash2) -{ - Elf_Internal_Shdr *symtab_hdr = &elf_tdata (ibfd)->symtab_hdr; - enum elf_ppc64_reloc_type r_type = ELF64_R_TYPE (rel->r_info); - unsigned int r_symndx = ELF64_R_SYM (rel->r_info); - - if (r_symndx >= symtab_hdr->sh_info - && (r_type == R_PPC64_REL24 - || r_type == R_PPC64_REL14 - || r_type == R_PPC64_REL14_BRTAKEN - || r_type == R_PPC64_REL14_BRNTAKEN - || r_type == R_PPC64_ADDR24 - || r_type == R_PPC64_ADDR14 - || r_type == R_PPC64_ADDR14_BRTAKEN - || r_type == R_PPC64_ADDR14_BRNTAKEN)) + htab->tls_get_addr = h; + + if (htab->tls_get_addr_fd == NULL + && h->oh != NULL + && h->oh->is_func_descriptor + && (h->oh->elf.root.type == bfd_link_hash_defined + || h->oh->elf.root.type == bfd_link_hash_defweak)) + htab->tls_get_addr_fd = h->oh; + } + + if (htab->tls_get_addr_fd != NULL) { - struct elf_link_hash_entry **sym_hashes = elf_sym_hashes (ibfd); - struct elf_link_hash_entry *h; + struct ppc_link_hash_entry *h = htab->tls_get_addr_fd; - h = sym_hashes[r_symndx - symtab_hdr->sh_info]; - while (h->root.type == bfd_link_hash_indirect - || h->root.type == bfd_link_hash_warning) - h = (struct elf_link_hash_entry *) h->root.u.i.link; - if (h == &hash1->elf || h == &hash2->elf) - return TRUE; + while (h->elf.root.type == bfd_link_hash_indirect + || h->elf.root.type == bfd_link_hash_warning) + h = (struct ppc_link_hash_entry *) h->elf.root.u.i.link; + + htab->tls_get_addr_fd = h; } - return FALSE; + + return _bfd_elf_tls_setup (obfd, info); } /* Run through all the TLS relocs looking for optimization @@ -6898,9 +6782,8 @@ ppc64_elf_tls_optimize (bfd *obfd ATTRIBUTE_UNUSED, struct bfd_link_info *info) bfd *ibfd; asection *sec; struct ppc_link_hash_table *htab; - int pass; - if (info->relocatable || !info->executable) + if (info->relocatable || info->shared) return TRUE; htab = ppc_hash_table (info); @@ -6910,358 +6793,320 @@ ppc64_elf_tls_optimize (bfd *obfd ATTRIBUTE_UNUSED, struct bfd_link_info *info) asection *toc = bfd_get_section_by_name (ibfd, ".toc"); unsigned char *toc_ref = NULL; - /* Look at all the sections for this file. Make two passes over - the relocs. On the first pass, mark toc entries involved - with tls relocs, and check that tls relocs involved in - setting up a tls_get_addr call are indeed followed by such a - call. If they are not, exclude them from the optimizations - done on the second pass. */ - for (pass = 0; pass < 2; ++pass) - for (sec = ibfd->sections; sec != NULL; sec = sec->next) - if (sec->has_tls_reloc && !bfd_is_abs_section (sec->output_section)) - { - Elf_Internal_Rela *relstart, *rel, *relend; - - /* Read the relocations. */ - relstart = _bfd_elf_link_read_relocs (ibfd, sec, NULL, NULL, - info->keep_memory); - if (relstart == NULL) - return FALSE; - - relend = relstart + sec->reloc_count; - for (rel = relstart; rel < relend; rel++) - { - enum elf_ppc64_reloc_type r_type; - unsigned long r_symndx; - struct elf_link_hash_entry *h; - Elf_Internal_Sym *sym; - asection *sym_sec; - char *tls_mask; - char tls_set, tls_clear, tls_type = 0; - bfd_vma value; - bfd_boolean ok_tprel, is_local; - long toc_ref_index = 0; - int expecting_tls_get_addr = 0; - - r_symndx = ELF64_R_SYM (rel->r_info); - if (!get_sym_h (&h, &sym, &sym_sec, &tls_mask, &locsyms, - r_symndx, ibfd)) - { - err_free_rel: - if (elf_section_data (sec)->relocs != relstart) - free (relstart); - if (toc_ref != NULL) - free (toc_ref); - if (locsyms != NULL - && (elf_tdata (ibfd)->symtab_hdr.contents - != (unsigned char *) locsyms)) - free (locsyms); - return FALSE; - } - - if (h != NULL) - { - if (h->root.type != bfd_link_hash_defined - && h->root.type != bfd_link_hash_defweak) - continue; - value = h->root.u.def.value; - } - else - /* Symbols referenced by TLS relocs must be of type - STT_TLS. So no need for .opd local sym adjust. */ - value = sym->st_value; - - ok_tprel = FALSE; - is_local = FALSE; - if (h == NULL - || !h->def_dynamic) - { - is_local = TRUE; - value += sym_sec->output_offset; - value += sym_sec->output_section->vma; - value -= htab->elf.tls_sec->vma; - ok_tprel = (value + TP_OFFSET + ((bfd_vma) 1 << 31) - < (bfd_vma) 1 << 32); - } - - r_type = ELF64_R_TYPE (rel->r_info); - switch (r_type) - { - case R_PPC64_GOT_TLSLD16: - case R_PPC64_GOT_TLSLD16_LO: - expecting_tls_get_addr = 1; - /* Fall thru */ - - case R_PPC64_GOT_TLSLD16_HI: - case R_PPC64_GOT_TLSLD16_HA: - /* These relocs should never be against a symbol - defined in a shared lib. Leave them alone if - that turns out to be the case. */ - if (!is_local) - continue; - - /* LD -> LE */ - tls_set = 0; - tls_clear = TLS_LD; - tls_type = TLS_TLS | TLS_LD; - break; + /* Look at all the sections for this file, with TOC last. */ + for (sec = (ibfd->sections == toc && toc && toc->next ? toc->next + : ibfd->sections); + sec != NULL; + sec = (sec == toc ? NULL + : sec->next == NULL ? toc + : sec->next == toc && toc->next ? toc->next + : sec->next)) + if (sec->has_tls_reloc && !bfd_is_abs_section (sec->output_section)) + { + Elf_Internal_Rela *relstart, *rel, *relend; + int expecting_tls_get_addr; + long toc_ref_index = 0; + + /* Read the relocations. */ + relstart = _bfd_elf_link_read_relocs (ibfd, sec, NULL, NULL, + info->keep_memory); + if (relstart == NULL) + return FALSE; - case R_PPC64_GOT_TLSGD16: - case R_PPC64_GOT_TLSGD16_LO: - expecting_tls_get_addr = 1; - /* Fall thru */ + expecting_tls_get_addr = 0; + relend = relstart + sec->reloc_count; + for (rel = relstart; rel < relend; rel++) + { + enum elf_ppc64_reloc_type r_type; + unsigned long r_symndx; + struct elf_link_hash_entry *h; + Elf_Internal_Sym *sym; + asection *sym_sec; + char *tls_mask; + char tls_set, tls_clear, tls_type = 0; + bfd_vma value; + bfd_boolean ok_tprel, is_local; - case R_PPC64_GOT_TLSGD16_HI: - case R_PPC64_GOT_TLSGD16_HA: - if (ok_tprel) - /* GD -> LE */ - tls_set = 0; - else - /* GD -> IE */ - tls_set = TLS_TLS | TLS_TPRELGD; - tls_clear = TLS_GD; - tls_type = TLS_TLS | TLS_GD; - break; + r_symndx = ELF64_R_SYM (rel->r_info); + if (!get_sym_h (&h, &sym, &sym_sec, &tls_mask, &locsyms, + r_symndx, ibfd)) + { + err_free_rel: + if (elf_section_data (sec)->relocs != relstart) + free (relstart); + if (toc_ref != NULL) + free (toc_ref); + if (locsyms != NULL + && (elf_tdata (ibfd)->symtab_hdr.contents + != (unsigned char *) locsyms)) + free (locsyms); + return FALSE; + } - case R_PPC64_GOT_TPREL16_DS: - case R_PPC64_GOT_TPREL16_LO_DS: - case R_PPC64_GOT_TPREL16_HI: - case R_PPC64_GOT_TPREL16_HA: - if (ok_tprel) - { - /* IE -> LE */ - tls_set = 0; - tls_clear = TLS_TPREL; - tls_type = TLS_TLS | TLS_TPREL; - break; - } + if (h != NULL) + { + if (h->root.type != bfd_link_hash_defined + && h->root.type != bfd_link_hash_defweak) continue; + value = h->root.u.def.value; + } + else + /* Symbols referenced by TLS relocs must be of type + STT_TLS. So no need for .opd local sym adjust. */ + value = sym->st_value; + + ok_tprel = FALSE; + is_local = FALSE; + if (h == NULL + || !h->def_dynamic) + { + is_local = TRUE; + value += sym_sec->output_offset; + value += sym_sec->output_section->vma; + value -= htab->elf.tls_sec->vma; + ok_tprel = (value + TP_OFFSET + ((bfd_vma) 1 << 31) + < (bfd_vma) 1 << 32); + } - case R_PPC64_TOC16: - case R_PPC64_TOC16_LO: - case R_PPC64_TLS: - case R_PPC64_TLSGD: - case R_PPC64_TLSLD: - if (sym_sec == NULL || sym_sec != toc) - continue; - - /* Mark this toc entry as referenced by a TLS - code sequence. We can do that now in the - case of R_PPC64_TLS, and after checking for - tls_get_addr for the TOC16 relocs. */ - if (toc_ref == NULL) - { - toc_ref = bfd_zmalloc (toc->size / 8); - if (toc_ref == NULL) - goto err_free_rel; - } - if (h != NULL) - value = h->root.u.def.value; - else - value = sym->st_value; - value += rel->r_addend; - BFD_ASSERT (value < toc->size && value % 8 == 0); - toc_ref_index = value / 8; - if (r_type == R_PPC64_TLS - || r_type == R_PPC64_TLSGD - || r_type == R_PPC64_TLSLD) - { - toc_ref[toc_ref_index] = 1; - continue; - } - - if (pass != 0 && toc_ref[toc_ref_index] == 0) - continue; - - tls_set = 0; - tls_clear = 0; - expecting_tls_get_addr = 2; - break; - - case R_PPC64_TPREL64: - if (pass == 0 - || sec != toc - || toc_ref == NULL - || !toc_ref[rel->r_offset / 8]) - continue; - if (ok_tprel) - { - /* IE -> LE */ - tls_set = TLS_EXPLICIT; - tls_clear = TLS_TPREL; - break; - } + r_type = ELF64_R_TYPE (rel->r_info); + switch (r_type) + { + case R_PPC64_GOT_TLSLD16: + case R_PPC64_GOT_TLSLD16_LO: + case R_PPC64_GOT_TLSLD16_HI: + case R_PPC64_GOT_TLSLD16_HA: + /* These relocs should never be against a symbol + defined in a shared lib. Leave them alone if + that turns out to be the case. */ + ppc64_tlsld_got (ibfd)->refcount -= 1; + if (!is_local) continue; - case R_PPC64_DTPMOD64: - if (pass == 0 - || sec != toc - || toc_ref == NULL - || !toc_ref[rel->r_offset / 8]) - continue; - if (rel + 1 < relend - && (rel[1].r_info - == ELF64_R_INFO (r_symndx, R_PPC64_DTPREL64)) - && rel[1].r_offset == rel->r_offset + 8) - { - if (ok_tprel) - /* GD -> LE */ - tls_set = TLS_EXPLICIT | TLS_GD; - else - /* GD -> IE */ - tls_set = TLS_EXPLICIT | TLS_GD | TLS_TPRELGD; - tls_clear = TLS_GD; - } - else - { - if (!is_local) - continue; + /* LD -> LE */ + tls_set = 0; + tls_clear = TLS_LD; + tls_type = TLS_TLS | TLS_LD; + expecting_tls_get_addr = 1; + break; - /* LD -> LE */ - tls_set = TLS_EXPLICIT; - tls_clear = TLS_LD; - } - break; + case R_PPC64_GOT_TLSGD16: + case R_PPC64_GOT_TLSGD16_LO: + case R_PPC64_GOT_TLSGD16_HI: + case R_PPC64_GOT_TLSGD16_HA: + if (ok_tprel) + /* GD -> LE */ + tls_set = 0; + else + /* GD -> IE */ + tls_set = TLS_TLS | TLS_TPRELGD; + tls_clear = TLS_GD; + tls_type = TLS_TLS | TLS_GD; + expecting_tls_get_addr = 1; + break; - default: + case R_PPC64_GOT_TPREL16_DS: + case R_PPC64_GOT_TPREL16_LO_DS: + case R_PPC64_GOT_TPREL16_HI: + case R_PPC64_GOT_TPREL16_HA: + expecting_tls_get_addr = 0; + if (ok_tprel) + { + /* IE -> LE */ + tls_set = 0; + tls_clear = TLS_TPREL; + tls_type = TLS_TLS | TLS_TPREL; + break; + } + else continue; - } - - if (pass == 0) - { - if (!expecting_tls_get_addr - || !sec->has_tls_get_addr_call) - continue; - - if (rel + 1 < relend - && branch_reloc_hash_match (ibfd, rel + 1, - htab->tls_get_addr, - htab->tls_get_addr_fd)) - { - if (expecting_tls_get_addr == 2) - { - /* Check for toc tls entries. */ - char *toc_tls; - int retval; - - retval = get_tls_mask (&toc_tls, NULL, NULL, - &locsyms, - rel, ibfd); - if (retval == 0) - goto err_free_rel; - if (retval > 1 && toc_tls != NULL) - toc_ref[toc_ref_index] = 1; - } - continue; - } - if (expecting_tls_get_addr != 1) - continue; - - /* Uh oh, we didn't find the expected call. We - could just mark this symbol to exclude it - from tls optimization but it's safer to skip - the entire section. */ - sec->has_tls_reloc = 0; - break; - } - - if (expecting_tls_get_addr) - { - struct plt_entry *ent; - for (ent = htab->tls_get_addr->elf.plt.plist; - ent != NULL; - ent = ent->next) - if (ent->addend == 0) + case R_PPC64_REL14: + case R_PPC64_REL14_BRTAKEN: + case R_PPC64_REL14_BRNTAKEN: + case R_PPC64_REL24: + if (h != NULL + && (h == &htab->tls_get_addr->elf + || h == &htab->tls_get_addr_fd->elf)) + { + if (!expecting_tls_get_addr + && rel != relstart + && ((ELF64_R_TYPE (rel[-1].r_info) + == R_PPC64_TOC16) + || (ELF64_R_TYPE (rel[-1].r_info) + == R_PPC64_TOC16_LO))) { - if (ent->plt.refcount > 0) + /* Check for toc tls entries. */ + char *toc_tls; + int retval; + + retval = get_tls_mask (&toc_tls, NULL, &locsyms, + rel - 1, ibfd); + if (retval == 0) + goto err_free_rel; + if (retval > 1 && toc_tls != NULL) { - ent->plt.refcount -= 1; - expecting_tls_get_addr = 0; + expecting_tls_get_addr = 1; + if (toc_ref != NULL) + toc_ref[toc_ref_index] = 1; } - break; } - } - if (expecting_tls_get_addr) - { - struct plt_entry *ent; - for (ent = htab->tls_get_addr_fd->elf.plt.plist; - ent != NULL; - ent = ent->next) - if (ent->addend == 0) + if (expecting_tls_get_addr) { - if (ent->plt.refcount > 0) - ent->plt.refcount -= 1; - break; + struct plt_entry *ent; + for (ent = h->plt.plist; ent; ent = ent->next) + if (ent->addend == 0) + { + if (ent->plt.refcount > 0) + ent->plt.refcount -= 1; + break; + } } - } + } + expecting_tls_get_addr = 0; + continue; - if (tls_clear == 0) + case R_PPC64_TOC16: + case R_PPC64_TOC16_LO: + case R_PPC64_TLS: + expecting_tls_get_addr = 0; + if (sym_sec == toc && toc != NULL) + { + /* Mark this toc entry as referenced by a TLS + code sequence. We can do that now in the + case of R_PPC64_TLS, and after checking for + tls_get_addr for the TOC16 relocs. */ + if (toc_ref == NULL) + { + toc_ref = bfd_zmalloc (toc->size / 8); + if (toc_ref == NULL) + goto err_free_rel; + } + if (h != NULL) + value = h->root.u.def.value; + else + value = sym->st_value; + value += rel->r_addend; + BFD_ASSERT (value < toc->size && value % 8 == 0); + toc_ref_index = value / 8; + if (r_type == R_PPC64_TLS) + toc_ref[toc_ref_index] = 1; + } continue; - if ((tls_set & TLS_EXPLICIT) == 0) - { - struct got_entry *ent; + case R_PPC64_TPREL64: + expecting_tls_get_addr = 0; + if (sec != toc + || toc_ref == NULL + || !toc_ref[rel->r_offset / 8]) + continue; + if (ok_tprel) + { + /* IE -> LE */ + tls_set = TLS_EXPLICIT; + tls_clear = TLS_TPREL; + break; + } + else + continue; - /* Adjust got entry for this reloc. */ - if (h != NULL) - ent = h->got.glist; - else - ent = elf_local_got_ents (ibfd)[r_symndx]; + case R_PPC64_DTPMOD64: + expecting_tls_get_addr = 0; + if (sec != toc + || toc_ref == NULL + || !toc_ref[rel->r_offset / 8]) + continue; + if (rel + 1 < relend + && (rel[1].r_info + == ELF64_R_INFO (r_symndx, R_PPC64_DTPREL64)) + && rel[1].r_offset == rel->r_offset + 8) + { + if (ok_tprel) + /* GD -> LE */ + tls_set = TLS_EXPLICIT | TLS_GD; + else + /* GD -> IE */ + tls_set = TLS_EXPLICIT | TLS_GD | TLS_TPRELGD; + tls_clear = TLS_GD; + } + else + { + if (!is_local) + continue; - for (; ent != NULL; ent = ent->next) - if (ent->addend == rel->r_addend - && ent->owner == ibfd - && ent->tls_type == tls_type) - break; - if (ent == NULL) - abort (); + /* LD -> LE */ + tls_set = TLS_EXPLICIT; + tls_clear = TLS_LD; + } + break; - if (tls_set == 0) - { - /* We managed to get rid of a got entry. */ - if (ent->got.refcount > 0) - ent->got.refcount -= 1; - } - } - else - { - /* If we got rid of a DTPMOD/DTPREL reloc pair then - we'll lose one or two dyn relocs. */ - if (!dec_dynrel_count (rel->r_info, sec, info, - NULL, h, sym_sec)) - return FALSE; + default: + expecting_tls_get_addr = 0; + continue; + } - if (tls_set == (TLS_EXPLICIT | TLS_GD)) - { - if (!dec_dynrel_count ((rel + 1)->r_info, sec, info, - NULL, h, sym_sec)) - return FALSE; - } - } + if ((tls_set & TLS_EXPLICIT) == 0) + { + struct got_entry *ent; - *tls_mask |= tls_set; - *tls_mask &= ~tls_clear; - } + /* Adjust got entry for this reloc. */ + if (h != NULL) + ent = h->got.glist; + else + ent = elf_local_got_ents (ibfd)[r_symndx]; - if (elf_section_data (sec)->relocs != relstart) - free (relstart); - } + for (; ent != NULL; ent = ent->next) + if (ent->addend == rel->r_addend + && ent->owner == ibfd + && ent->tls_type == tls_type) + break; + if (ent == NULL) + abort (); + + if (tls_set == 0) + { + /* We managed to get rid of a got entry. */ + if (ent->got.refcount > 0) + ent->got.refcount -= 1; + } + } + else + { + /* If we got rid of a DTPMOD/DTPREL reloc pair then + we'll lose one or two dyn relocs. */ + if (!dec_dynrel_count (rel->r_info, sec, info, + NULL, h, sym_sec)) + return FALSE; + + if (tls_set == (TLS_EXPLICIT | TLS_GD)) + { + if (!dec_dynrel_count ((rel + 1)->r_info, sec, info, + NULL, h, sym_sec)) + return FALSE; + } + } - if (toc_ref != NULL) - free (toc_ref); + *tls_mask |= tls_set; + *tls_mask &= ~tls_clear; + } - if (locsyms != NULL - && (elf_tdata (ibfd)->symtab_hdr.contents - != (unsigned char *) locsyms)) - { - if (!info->keep_memory) - free (locsyms); - else - elf_tdata (ibfd)->symtab_hdr.contents = (unsigned char *) locsyms; + if (elf_section_data (sec)->relocs != relstart) + free (relstart); } - } + + if (toc_ref != NULL) + free (toc_ref); + + if (locsyms != NULL + && (elf_tdata (ibfd)->symtab_hdr.contents + != (unsigned char *) locsyms)) + { + if (!info->keep_memory) + free (locsyms); + else + elf_tdata (ibfd)->symtab_hdr.contents = (unsigned char *) locsyms; + } + } return TRUE; } @@ -7835,8 +7680,7 @@ allocate_dynrelocs (struct elf_link_hash_entry *h, void *inf) if ((gent->tls_type & TLS_LD) != 0 && !h->def_dynamic) { - ppc64_tlsld_got (gent->owner)->refcount += 1; - gent->got.offset = (bfd_vma) -1; + gent->got.offset = ppc64_tlsld_got (gent->owner)->offset; continue; } @@ -7869,7 +7713,7 @@ allocate_dynrelocs (struct elf_link_hash_entry *h, void *inf) if (info->shared) { /* Relocs that use pc_count are those that appear on a call insn, - or certain REL relocs (see must_be_dyn_reloc) that can be + or certain REL relocs (see MUST_BE_DYN_RELOC) that can be generated via assembly. We want calls to protected symbols to resolve directly to the function rather than going via the plt. If people want function pointer comparisons to work as expected @@ -8020,6 +7864,20 @@ ppc64_elf_size_dynamic_sections (bfd *output_bfd ATTRIBUTE_UNUSED, if (!is_ppc64_elf_target (ibfd->xvec)) continue; + if (ppc64_tlsld_got (ibfd)->refcount > 0) + { + s = ppc64_elf_tdata (ibfd)->got; + ppc64_tlsld_got (ibfd)->offset = s->size; + s->size += 16; + if (info->shared) + { + srel = ppc64_elf_tdata (ibfd)->relgot; + srel->size += sizeof (Elf64_External_Rela); + } + } + else + ppc64_tlsld_got (ibfd)->offset = (bfd_vma) -1; + for (s = ibfd->sections; s != NULL; s = s->next) { struct ppc_dyn_relocs *p; @@ -8063,8 +7921,14 @@ ppc64_elf_size_dynamic_sections (bfd *output_bfd ATTRIBUTE_UNUSED, { if ((ent->tls_type & *lgot_masks & TLS_LD) != 0) { - ppc64_tlsld_got (ibfd)->refcount += 1; - ent->got.offset = (bfd_vma) -1; + if (ppc64_tlsld_got (ibfd)->offset == (bfd_vma) -1) + { + ppc64_tlsld_got (ibfd)->offset = s->size; + s->size += 16; + if (info->shared) + srel->size += sizeof (Elf64_External_Rela); + } + ent->got.offset = ppc64_tlsld_got (ibfd)->offset; } else { @@ -8092,26 +7956,6 @@ ppc64_elf_size_dynamic_sections (bfd *output_bfd ATTRIBUTE_UNUSED, sym dynamic relocs. */ elf_link_hash_traverse (&htab->elf, allocate_dynrelocs, info); - for (ibfd = info->input_bfds; ibfd != NULL; ibfd = ibfd->link_next) - { - if (!is_ppc64_elf_target (ibfd->xvec)) - continue; - - if (ppc64_tlsld_got (ibfd)->refcount > 0) - { - s = ppc64_elf_tdata (ibfd)->got; - ppc64_tlsld_got (ibfd)->offset = s->size; - s->size += 16; - if (info->shared) - { - asection *srel = ppc64_elf_tdata (ibfd)->relgot; - srel->size += sizeof (Elf64_External_Rela); - } - } - else - ppc64_tlsld_got (ibfd)->offset = (bfd_vma) -1; - } - /* We now have determined the sizes of the various dynamic sections. Allocate memory for them. */ relocs = FALSE; @@ -8346,35 +8190,19 @@ build_plt_stub (bfd *obfd, bfd_byte *p, int offset) #define PPC_HI(v) (((v) >> 16) & 0xffff) #define PPC_HA(v) PPC_HI ((v) + 0x8000) - if (PPC_HA (offset) != 0) - { - bfd_put_32 (obfd, ADDIS_R12_R2 | PPC_HA (offset), p), p += 4; - bfd_put_32 (obfd, STD_R2_40R1, p), p += 4; - bfd_put_32 (obfd, LD_R11_0R12 | PPC_LO (offset), p), p += 4; - if (PPC_HA (offset + 16) != PPC_HA (offset)) - { - bfd_put_32 (obfd, ADDI_R12_R12 | PPC_LO (offset), p), p += 4; - offset = 0; - } - bfd_put_32 (obfd, MTCTR_R11, p), p += 4; - bfd_put_32 (obfd, LD_R2_0R12 | PPC_LO (offset + 8), p), p += 4; - bfd_put_32 (obfd, LD_R11_0R12 | PPC_LO (offset + 16), p), p += 4; - bfd_put_32 (obfd, BCTR, p), p += 4; - } - else - { - bfd_put_32 (obfd, STD_R2_40R1, p), p += 4; - bfd_put_32 (obfd, LD_R11_0R2 | PPC_LO (offset), p), p += 4; - if (PPC_HA (offset + 16) != PPC_HA (offset)) - { - bfd_put_32 (obfd, ADDI_R2_R2 | PPC_LO (offset), p), p += 4; - offset = 0; - } - bfd_put_32 (obfd, MTCTR_R11, p), p += 4; - bfd_put_32 (obfd, LD_R11_0R2 | PPC_LO (offset + 16), p), p += 4; - bfd_put_32 (obfd, LD_R2_0R2 | PPC_LO (offset + 8), p), p += 4; - bfd_put_32 (obfd, BCTR, p), p += 4; - } + bfd_put_32 (obfd, ADDIS_R12_R2 | PPC_HA (offset), p), p += 4; + bfd_put_32 (obfd, STD_R2_40R1, p), p += 4; + bfd_put_32 (obfd, LD_R11_0R12 | PPC_LO (offset), p), p += 4; + if (PPC_HA (offset + 8) != PPC_HA (offset)) + bfd_put_32 (obfd, ADDIS_R12_R12 | 1, p), p += 4; + offset += 8; + bfd_put_32 (obfd, LD_R2_0R12 | PPC_LO (offset), p), p += 4; + if (PPC_HA (offset + 8) != PPC_HA (offset)) + bfd_put_32 (obfd, ADDIS_R12_R12 | 1, p), p += 4; + offset += 8; + bfd_put_32 (obfd, MTCTR_R11, p), p += 4; + bfd_put_32 (obfd, LD_R11_0R12 | PPC_LO (offset), p), p += 4; + bfd_put_32 (obfd, BCTR, p), p += 4; return p; } @@ -8417,8 +8245,9 @@ ppc_build_one_stub (struct bfd_hash_entry *gen_entry, void *in_arg) + stub_entry->stub_sec->output_offset + stub_entry->stub_sec->output_section->vma); - size = 4; - if (stub_entry->stub_type == ppc_stub_long_branch_r2off) + if (stub_entry->stub_type != ppc_stub_long_branch_r2off) + size = 4; + else { bfd_vma r2off; @@ -8426,16 +8255,12 @@ ppc_build_one_stub (struct bfd_hash_entry *gen_entry, void *in_arg) - htab->stub_group[stub_entry->id_sec->id].toc_off); bfd_put_32 (htab->stub_bfd, STD_R2_40R1, loc); loc += 4; - size = 12; - if (PPC_HA (r2off) != 0) - { - size = 16; - bfd_put_32 (htab->stub_bfd, ADDIS_R2_R2 | PPC_HA (r2off), loc); - loc += 4; - } + bfd_put_32 (htab->stub_bfd, ADDIS_R2_R2 | PPC_HA (r2off), loc); + loc += 4; bfd_put_32 (htab->stub_bfd, ADDI_R2_R2 | PPC_LO (r2off), loc); loc += 4; - off -= size - 4; + off -= 12; + size = 16; } bfd_put_32 (htab->stub_bfd, B_DOT | (off & 0x3fffffc), loc); @@ -8592,18 +8417,10 @@ ppc_build_one_stub (struct bfd_hash_entry *gen_entry, void *in_arg) indx = off; if (stub_entry->stub_type != ppc_stub_plt_branch_r2off) { - if (PPC_HA (indx) != 0) - { - size = 16; - bfd_put_32 (htab->stub_bfd, ADDIS_R12_R2 | PPC_HA (indx), loc); - loc += 4; - bfd_put_32 (htab->stub_bfd, LD_R11_0R12 | PPC_LO (indx), loc); - } - else - { - size = 12; - bfd_put_32 (htab->stub_bfd, LD_R11_0R2 | PPC_LO (indx), loc); - } + bfd_put_32 (htab->stub_bfd, ADDIS_R12_R2 | PPC_HA (indx), loc); + loc += 4; + bfd_put_32 (htab->stub_bfd, LD_R11_0R12 | PPC_LO (indx), loc); + size = 16; } else { @@ -8613,28 +8430,14 @@ ppc_build_one_stub (struct bfd_hash_entry *gen_entry, void *in_arg) - htab->stub_group[stub_entry->id_sec->id].toc_off); bfd_put_32 (htab->stub_bfd, STD_R2_40R1, loc); loc += 4; - size = 20; - if (PPC_HA (indx) != 0) - { - size += 4; - bfd_put_32 (htab->stub_bfd, ADDIS_R12_R2 | PPC_HA (indx), loc); - loc += 4; - bfd_put_32 (htab->stub_bfd, LD_R11_0R12 | PPC_LO (indx), loc); - loc += 4; - } - else - { - bfd_put_32 (htab->stub_bfd, LD_R11_0R2 | PPC_LO (indx), loc); - loc += 4; - } - - if (PPC_HA (r2off) != 0) - { - size += 4; - bfd_put_32 (htab->stub_bfd, ADDIS_R2_R2 | PPC_HA (r2off), loc); - loc += 4; - } + bfd_put_32 (htab->stub_bfd, ADDIS_R12_R2 | PPC_HA (indx), loc); + loc += 4; + bfd_put_32 (htab->stub_bfd, LD_R11_0R12 | PPC_LO (indx), loc); + loc += 4; + bfd_put_32 (htab->stub_bfd, ADDIS_R2_R2 | PPC_HA (r2off), loc); + loc += 4; bfd_put_32 (htab->stub_bfd, ADDI_R2_R2 | PPC_LO (r2off), loc); + size = 28; } loc += 4; bfd_put_32 (htab->stub_bfd, MTCTR_R11, loc); @@ -8773,8 +8576,6 @@ ppc_size_one_stub (struct bfd_hash_entry *gen_entry, void *in_arg) - htab->stub_group[stub_entry->id_sec->id].toc_off); size = PLT_CALL_STUB_SIZE; - if (PPC_HA (off) == 0) - size -= 4; if (PPC_HA (off + 16) != PPC_HA (off)) size += 4; } @@ -8782,8 +8583,6 @@ ppc_size_one_stub (struct bfd_hash_entry *gen_entry, void *in_arg) { /* ppc_stub_long_branch or ppc_stub_plt_branch, or their r2off variants. */ - bfd_vma r2off = 0; - off = (stub_entry->target_value + stub_entry->target_section->output_offset + stub_entry->target_section->output_section->vma); @@ -8799,19 +8598,14 @@ ppc_size_one_stub (struct bfd_hash_entry *gen_entry, void *in_arg) size = 4; if (stub_entry->stub_type == ppc_stub_long_branch_r2off) { - r2off = (htab->stub_group[stub_entry->target_section->id].toc_off - - htab->stub_group[stub_entry->id_sec->id].toc_off); - size = 12; - if (PPC_HA (r2off) != 0) - size = 16; - off -= size - 4; + off -= 12; + size = 16; } /* If the branch offset if too big, use a ppc_stub_plt_branch. */ if (off + (1 << 25) >= (bfd_vma) (1 << 26)) { struct ppc_branch_hash_entry *br_entry; - unsigned int indx; br_entry = ppc_branch_hash_lookup (&htab->branch_hash_table, stub_entry->root.string + 9, @@ -8840,28 +8634,9 @@ ppc_size_one_stub (struct bfd_hash_entry *gen_entry, void *in_arg) } stub_entry->stub_type += ppc_stub_plt_branch - ppc_stub_long_branch; - off = (br_entry->offset - + htab->brlt->output_offset - + htab->brlt->output_section->vma - - elf_gp (htab->brlt->output_section->owner) - - htab->stub_group[stub_entry->id_sec->id].toc_off); - - indx = off; - if (stub_entry->stub_type != ppc_stub_plt_branch_r2off) - { - size = 12; - if (PPC_HA (indx) != 0) - size = 16; - } - else - { - size = 20; - if (PPC_HA (indx) != 0) - size += 4; - - if (PPC_HA (r2off) != 0) - size += 4; - } + size = 16; + if (stub_entry->stub_type != ppc_stub_plt_branch) + size = 28; } else if (info->emitrelocations) { @@ -9028,7 +8803,6 @@ toc_adjusting_stub_needed (struct bfd_link_info *info, asection *isec) enum elf_ppc64_reloc_type r_type; unsigned long r_symndx; struct elf_link_hash_entry *h; - struct ppc_link_hash_entry *eh; Elf_Internal_Sym *sym; asection *sym_sec; long *opd_adjust; @@ -9051,20 +8825,23 @@ toc_adjusting_stub_needed (struct bfd_link_info *info, asection *isec) } /* Calls to dynamic lib functions go through a plt call stub - that uses r2. */ - eh = (struct ppc_link_hash_entry *) h; - if (eh != NULL - && (eh->elf.plt.plist != NULL - || (eh->oh != NULL - && eh->oh->elf.plt.plist != NULL))) + that uses r2. Branches to undefined symbols might be a call + using old-style dot symbols that can be satisfied by a plt + call into a new-style dynamic library. */ + if (sym_sec == NULL) { - ret = 1; - break; - } + struct ppc_link_hash_entry *eh = (struct ppc_link_hash_entry *) h; + if (eh != NULL + && eh->oh != NULL + && eh->oh->elf.plt.plist != NULL) + { + ret = 1; + break; + } - if (sym_sec == NULL) - /* Ignore other undefined symbols. */ - continue; + /* Ignore other undefined symbols. */ + continue; + } /* Assume branches to other sections not included in the link need stubs too, to cover -R and absolute syms. */ @@ -9583,7 +9360,7 @@ ppc64_elf_size_stubs (bfd *output_bfd, /* Get tls info. */ char *tls_mask; - if (!get_tls_mask (&tls_mask, NULL, NULL, &local_syms, + if (!get_tls_mask (&tls_mask, NULL, &local_syms, irela - 1, input_bfd)) goto error_ret_free_internal; if (*tls_mask != 0) @@ -10061,7 +9838,6 @@ ppc64_elf_relocate_section (bfd *output_bfd, struct ppc_link_hash_entry *fdh; const char *sym_name; unsigned long r_symndx, toc_symndx; - bfd_vma toc_addend; char tls_mask, tls_gd, tls_type; char sym_type; bfd_vma relocation; @@ -10155,28 +9931,28 @@ ppc64_elf_relocate_section (bfd *output_bfd, tls_mask = 0; tls_gd = 0; toc_symndx = 0; - if (h != NULL) - tls_mask = h->tls_mask; - else if (local_got_ents != NULL) - { - char *lgot_masks; - lgot_masks = (char *) (local_got_ents + symtab_hdr->sh_info); - tls_mask = lgot_masks[r_symndx]; - } - if (tls_mask == 0 - && (r_type == R_PPC64_TLS - || r_type == R_PPC64_TLSGD - || r_type == R_PPC64_TLSLD)) + if (IS_PPC64_TLS_RELOC (r_type)) { - /* Check for toc tls entries. */ - char *toc_tls; + if (h != NULL) + tls_mask = h->tls_mask; + else if (local_got_ents != NULL) + { + char *lgot_masks; + lgot_masks = (char *) (local_got_ents + symtab_hdr->sh_info); + tls_mask = lgot_masks[r_symndx]; + } + if (tls_mask == 0 && r_type == R_PPC64_TLS) + { + /* Check for toc tls entries. */ + char *toc_tls; - if (!get_tls_mask (&toc_tls, &toc_symndx, &toc_addend, - &local_syms, rel, input_bfd)) - return FALSE; + if (!get_tls_mask (&toc_tls, &toc_symndx, &local_syms, + rel, input_bfd)) + return FALSE; - if (toc_tls) - tls_mask = *toc_tls; + if (toc_tls) + tls_mask = *toc_tls; + } } /* Check that tls relocs are used with tls syms, and non-tls @@ -10186,20 +9962,14 @@ ppc64_elf_relocate_section (bfd *output_bfd, && (h == NULL || h->elf.root.type == bfd_link_hash_defined || h->elf.root.type == bfd_link_hash_defweak) - && (IS_PPC64_TLS_RELOC (r_type) - != (sym_type == STT_TLS - || (sym_type == STT_SECTION - && (sec->flags & SEC_THREAD_LOCAL) != 0)))) + && IS_PPC64_TLS_RELOC (r_type) != (sym_type == STT_TLS)) { - if (tls_mask != 0 - && (r_type == R_PPC64_TLS - || r_type == R_PPC64_TLSGD - || r_type == R_PPC64_TLSLD)) + if (r_type == R_PPC64_TLS && tls_mask != 0) /* R_PPC64_TLS is OK against a symbol in the TOC. */ ; else (*_bfd_error_handler) - (!IS_PPC64_TLS_RELOC (r_type) + (sym_type == STT_TLS ? _("%B(%A+0x%lx): %s used with TLS symbol %s") : _("%B(%A+0x%lx): %s used with non-TLS symbol %s"), input_bfd, @@ -10236,8 +10006,8 @@ ppc64_elf_relocate_section (bfd *output_bfd, char *toc_tls; int retval; - retval = get_tls_mask (&toc_tls, &toc_symndx, &toc_addend, - &local_syms, rel, input_bfd); + retval = get_tls_mask (&toc_tls, &toc_symndx, &local_syms, + rel, input_bfd); if (retval == 0) return FALSE; @@ -10259,12 +10029,12 @@ ppc64_elf_relocate_section (bfd *output_bfd, { tls_gd = TLS_TPRELGD; if (tls_mask != 0 && (tls_mask & TLS_GD) == 0) - goto tls_ldgd_opt; + goto tls_get_addr_check; } else if (retval == 3) { if (tls_mask != 0 && (tls_mask & TLS_LD) == 0) - goto tls_ldgd_opt; + goto tls_get_addr_check; } } } @@ -10338,8 +10108,6 @@ ppc64_elf_relocate_section (bfd *output_bfd, if (toc_symndx != 0) { rel->r_info = ELF64_R_INFO (toc_symndx, r_type); - rel->r_addend = toc_addend; - rel->r_addend = toc_addend; /* We changed the symbol. Start over in order to get h, sym, sec etc. right. */ rel--; @@ -10379,199 +10147,99 @@ ppc64_elf_relocate_section (bfd *output_bfd, case R_PPC64_GOT_TLSGD16_LO: tls_gd = TLS_TPRELGD; if (tls_mask != 0 && (tls_mask & TLS_GD) == 0) - goto tls_ldgd_opt; + goto tls_get_addr_check; break; case R_PPC64_GOT_TLSLD16: case R_PPC64_GOT_TLSLD16_LO: if (tls_mask != 0 && (tls_mask & TLS_LD) == 0) { - unsigned int insn1, insn2, insn3; - bfd_vma offset; - - tls_ldgd_opt: - offset = (bfd_vma) -1; - /* If not using the newer R_PPC64_TLSGD/LD to mark - __tls_get_addr calls, we must trust that the call - stays with its arg setup insns, ie. that the next - reloc is the __tls_get_addr call associated with - the current reloc. Edit both insns. */ - if (input_section->has_tls_get_addr_call - && rel + 1 < relend - && branch_reloc_hash_match (input_bfd, rel + 1, - htab->tls_get_addr, - htab->tls_get_addr_fd)) - offset = rel[1].r_offset; - if ((tls_mask & tls_gd) != 0) + tls_get_addr_check: + if (rel + 1 < relend) { - /* IE */ + enum elf_ppc64_reloc_type r_type2; + unsigned long r_symndx2; + struct elf_link_hash_entry *h2; + bfd_vma insn1, insn2, insn3; + bfd_vma offset; + + /* The next instruction should be a call to + __tls_get_addr. Peek at the reloc to be sure. */ + r_type2 = ELF64_R_TYPE (rel[1].r_info); + r_symndx2 = ELF64_R_SYM (rel[1].r_info); + if (r_symndx2 < symtab_hdr->sh_info + || (r_type2 != R_PPC64_REL14 + && r_type2 != R_PPC64_REL14_BRTAKEN + && r_type2 != R_PPC64_REL14_BRNTAKEN + && r_type2 != R_PPC64_REL24)) + break; + + h2 = sym_hashes[r_symndx2 - symtab_hdr->sh_info]; + while (h2->root.type == bfd_link_hash_indirect + || h2->root.type == bfd_link_hash_warning) + h2 = (struct elf_link_hash_entry *) h2->root.u.i.link; + if (h2 == NULL || (h2 != &htab->tls_get_addr->elf + && h2 != &htab->tls_get_addr_fd->elf)) + break; + + /* OK, it checks out. Replace the call. */ + offset = rel[1].r_offset; insn1 = bfd_get_32 (output_bfd, contents + rel->r_offset - d_offset); - insn1 &= (1 << 26) - (1 << 2); - insn1 |= 58 << 26; /* ld */ - insn2 = 0x7c636a14; /* add 3,3,13 */ - if (offset != (bfd_vma) -1) - rel[1].r_info = ELF64_R_INFO (ELF64_R_SYM (rel[1].r_info), - R_PPC64_NONE); - if ((tls_mask & TLS_EXPLICIT) == 0) - r_type = (((r_type - (R_PPC64_GOT_TLSGD16 & 3)) & 3) - + R_PPC64_GOT_TPREL16_DS); - else - r_type += R_PPC64_TOC16_DS - R_PPC64_TOC16; - rel->r_info = ELF64_R_INFO (r_symndx, r_type); - } - else - { - /* LE */ - insn1 = 0x3c6d0000; /* addis 3,13,0 */ - insn2 = 0x38630000; /* addi 3,3,0 */ - if (tls_gd == 0) - { - /* Was an LD reloc. */ - if (toc_symndx) - sec = local_sections[toc_symndx]; - for (r_symndx = 0; - r_symndx < symtab_hdr->sh_info; - r_symndx++) - if (local_sections[r_symndx] == sec) - break; - if (r_symndx >= symtab_hdr->sh_info) - r_symndx = 0; - rel->r_addend = htab->elf.tls_sec->vma + DTP_OFFSET; - if (r_symndx != 0) - rel->r_addend -= (local_syms[r_symndx].st_value - + sec->output_offset - + sec->output_section->vma); - } - else if (toc_symndx != 0) + insn3 = bfd_get_32 (output_bfd, + contents + offset + 4); + if ((tls_mask & tls_gd) != 0) { - r_symndx = toc_symndx; - rel->r_addend = toc_addend; + /* IE */ + insn1 &= (1 << 26) - (1 << 2); + insn1 |= 58 << 26; /* ld */ + insn2 = 0x7c636a14; /* add 3,3,13 */ + rel[1].r_info = ELF64_R_INFO (r_symndx2, R_PPC64_NONE); + if ((tls_mask & TLS_EXPLICIT) == 0) + r_type = (((r_type - (R_PPC64_GOT_TLSGD16 & 3)) & 3) + + R_PPC64_GOT_TPREL16_DS); + else + r_type += R_PPC64_TOC16_DS - R_PPC64_TOC16; + rel->r_info = ELF64_R_INFO (r_symndx, r_type); } - r_type = R_PPC64_TPREL16_HA; - rel->r_info = ELF64_R_INFO (r_symndx, r_type); - if (offset != (bfd_vma) -1) + else { + /* LE */ + insn1 = 0x3c6d0000; /* addis 3,13,0 */ + insn2 = 0x38630000; /* addi 3,3,0 */ + if (tls_gd == 0) + { + /* Was an LD reloc. */ + r_symndx = 0; + rel->r_addend = htab->elf.tls_sec->vma + DTP_OFFSET; + rel[1].r_addend = htab->elf.tls_sec->vma + DTP_OFFSET; + } + else if (toc_symndx != 0) + r_symndx = toc_symndx; + r_type = R_PPC64_TPREL16_HA; + rel->r_info = ELF64_R_INFO (r_symndx, r_type); rel[1].r_info = ELF64_R_INFO (r_symndx, R_PPC64_TPREL16_LO); - rel[1].r_offset = offset + d_offset; - rel[1].r_addend = rel->r_addend; + rel[1].r_offset += d_offset; } - } - bfd_put_32 (output_bfd, insn1, - contents + rel->r_offset - d_offset); - if (offset != (bfd_vma) -1) - { - insn3 = bfd_get_32 (output_bfd, - contents + offset + 4); if (insn3 == NOP || insn3 == CROR_151515 || insn3 == CROR_313131) { - rel[1].r_offset += 4; - bfd_put_32 (output_bfd, insn2, contents + offset + 4); + insn3 = insn2; insn2 = NOP; + rel[1].r_offset += 4; } + bfd_put_32 (output_bfd, insn1, contents + rel->r_offset - d_offset); bfd_put_32 (output_bfd, insn2, contents + offset); - } - if ((tls_mask & tls_gd) == 0 - && (tls_gd == 0 || toc_symndx != 0)) - { - /* We changed the symbol. Start over in order - to get h, sym, sec etc. right. */ - rel--; - continue; - } - } - break; - - case R_PPC64_TLSGD: - if (tls_mask != 0 && (tls_mask & TLS_GD) == 0) - { - unsigned int insn2, insn3; - bfd_vma offset = rel->r_offset; - - if ((tls_mask & TLS_TPRELGD) != 0) - { - /* IE */ - r_type = R_PPC64_NONE; - insn2 = 0x7c636a14; /* add 3,3,13 */ - } - else - { - /* LE */ - if (toc_symndx != 0) + bfd_put_32 (output_bfd, insn3, contents + offset + 4); + if (tls_gd == 0 || toc_symndx != 0) { - r_symndx = toc_symndx; - rel->r_addend = toc_addend; + /* We changed the symbol. Start over in order + to get h, sym, sec etc. right. */ + rel--; + continue; } - r_type = R_PPC64_TPREL16_LO; - rel->r_offset = offset + d_offset; - insn2 = 0x38630000; /* addi 3,3,0 */ - } - rel->r_info = ELF64_R_INFO (r_symndx, r_type); - /* Zap the reloc on the _tls_get_addr call too. */ - BFD_ASSERT (offset == rel[1].r_offset); - rel[1].r_info = ELF64_R_INFO (ELF64_R_SYM (rel[1].r_info), - R_PPC64_NONE); - insn3 = bfd_get_32 (output_bfd, - contents + offset + 4); - if (insn3 == NOP - || insn3 == CROR_151515 || insn3 == CROR_313131) - { - rel->r_offset += 4; - bfd_put_32 (output_bfd, insn2, contents + offset + 4); - insn2 = NOP; - } - bfd_put_32 (output_bfd, insn2, contents + offset); - if ((tls_mask & TLS_TPRELGD) == 0 && toc_symndx != 0) - { - rel--; - continue; - } - } - break; - - case R_PPC64_TLSLD: - if (tls_mask != 0 && (tls_mask & TLS_LD) == 0) - { - unsigned int insn2, insn3; - bfd_vma offset = rel->r_offset; - - if (toc_symndx) - sec = local_sections[toc_symndx]; - for (r_symndx = 0; - r_symndx < symtab_hdr->sh_info; - r_symndx++) - if (local_sections[r_symndx] == sec) - break; - if (r_symndx >= symtab_hdr->sh_info) - r_symndx = 0; - rel->r_addend = htab->elf.tls_sec->vma + DTP_OFFSET; - if (r_symndx != 0) - rel->r_addend -= (local_syms[r_symndx].st_value - + sec->output_offset - + sec->output_section->vma); - - r_type = R_PPC64_TPREL16_LO; - rel->r_info = ELF64_R_INFO (r_symndx, r_type); - rel->r_offset = offset + d_offset; - /* Zap the reloc on the _tls_get_addr call too. */ - BFD_ASSERT (offset == rel[1].r_offset); - rel[1].r_info = ELF64_R_INFO (ELF64_R_SYM (rel[1].r_info), - R_PPC64_NONE); - insn2 = 0x38630000; /* addi 3,3,0 */ - insn3 = bfd_get_32 (output_bfd, - contents + offset + 4); - if (insn3 == NOP - || insn3 == CROR_151515 || insn3 == CROR_313131) - { - rel->r_offset += 4; - bfd_put_32 (output_bfd, insn2, contents + offset + 4); - insn2 = NOP; } - bfd_put_32 (output_bfd, insn2, contents + offset); - rel--; - continue; } break; @@ -10828,8 +10496,6 @@ ppc64_elf_relocate_section (bfd *output_bfd, case R_PPC64_NONE: case R_PPC64_TLS: - case R_PPC64_TLSGD: - case R_PPC64_TLSLD: case R_PPC64_GNU_VTINHERIT: case R_PPC64_GNU_VTENTRY: continue; @@ -10944,8 +10610,7 @@ ppc64_elf_relocate_section (bfd *output_bfd, *offp = off | 1; if ((info->shared || indx != 0) - && (offp == &ppc64_tlsld_got (input_bfd)->offset - || h == NULL + && (h == NULL || ELF_ST_VISIBILITY (h->elf.other) == STV_DEFAULT || h->elf.root.type != bfd_link_hash_undefweak)) { @@ -11189,7 +10854,7 @@ ppc64_elf_relocate_section (bfd *output_bfd, && (h == NULL || ELF_ST_VISIBILITY (h->elf.other) == STV_DEFAULT || h->elf.root.type != bfd_link_hash_undefweak) - && (must_be_dyn_reloc (info, r_type) + && (MUST_BE_DYN_RELOC (r_type) || !SYMBOL_CALLS_LOCAL (info, &h->elf))) || (ELIMINATE_COPY_RELOCS && !info->shared @@ -11274,7 +10939,7 @@ ppc64_elf_relocate_section (bfd *output_bfd, { long indx = 0; - if (r_symndx == 0 || bfd_is_abs_section (sec)) + if (bfd_is_abs_section (sec)) ; else if (sec == NULL || sec->owner == NULL) { diff --git a/contrib/binutils/bfd/elflink.c b/contrib/binutils/bfd/elflink.c index f1e50def8b52..e80f8ee3f22e 100644 --- a/contrib/binutils/bfd/elflink.c +++ b/contrib/binutils/bfd/elflink.c @@ -4356,38 +4356,9 @@ elf_link_add_object_symbols (bfd *abfd, struct bfd_link_info *info) --no-add-needed is used. */ if ((elf_dyn_lib_class (abfd) & DYN_NO_NEEDED) != 0) { - bfd_boolean looks_soish; - const char *print_name; - int print_len; - size_t len, lend = 0; - - looks_soish = FALSE; - print_name = soname; - print_len = strlen(soname); - if (strncmp(soname, "lib", 3) == 0) - { - len = print_len; - if (len > 5 && strcmp(soname + len - 2, ".a") == 0) - lend = len - 5; - else - { - while (len > 6 && (ISDIGIT(soname[len - 1]) || - soname[len - 1] == '.')) - len--; - if (strncmp(soname + len - 3, ".so", 3) == 0) - lend = len - 6; - } - if (lend != 0) - { - print_name = soname + 3; - print_len = lend; - looks_soish = TRUE; - } - } - (*_bfd_error_handler) - (_("undefined reference to symbol `%s' (try adding -l%s%.*s)"), - name, looks_soish? "" : ":", print_len, print_name); + (_("%B: invalid DSO for symbol `%s' definition"), + abfd, name); bfd_set_error (bfd_error_bad_value); goto error_free_vers; } diff --git a/contrib/binutils/bfd/libbfd.h b/contrib/binutils/bfd/libbfd.h index 6119a87e1372..4c1414f826fa 100644 --- a/contrib/binutils/bfd/libbfd.h +++ b/contrib/binutils/bfd/libbfd.h @@ -1169,8 +1169,6 @@ static const char *const bfd_reloc_code_real_names[] = { "@@uninitialized@@", "BFD_RELOC_PPC64_PLTGOT16_DS", "BFD_RELOC_PPC64_PLTGOT16_LO_DS", "BFD_RELOC_PPC_TLS", - "BFD_RELOC_PPC_TLSGD", - "BFD_RELOC_PPC_TLSLD", "BFD_RELOC_PPC_DTPMOD", "BFD_RELOC_PPC_TPREL16", "BFD_RELOC_PPC_TPREL16_LO", diff --git a/contrib/binutils/bfd/po/bfd.pot b/contrib/binutils/bfd/po/bfd.pot index e436b184f31a..e5282389a1ab 100644 --- a/contrib/binutils/bfd/po/bfd.pot +++ b/contrib/binutils/bfd/po/bfd.pot @@ -2438,9 +2438,9 @@ msgstr "" msgid "Warning: size of symbol `%s' changed from %lu in %B to %lu in %B" msgstr "" -#: elflink.c:4389 +#: elflink.c:4309 #, c-format -msgid "undefined reference to symbol `%s' (try adding -l%s%.*s)" +msgid "%B: invalid DSO for symbol `%s' definition" msgstr "" #: elflink.c:5535 diff --git a/contrib/binutils/bfd/reloc.c b/contrib/binutils/bfd/reloc.c index 5a5c7f7e85da..1e5d4bd03fa7 100644 --- a/contrib/binutils/bfd/reloc.c +++ b/contrib/binutils/bfd/reloc.c @@ -2627,10 +2627,6 @@ ENUMDOC ENUM BFD_RELOC_PPC_TLS ENUMX - BFD_RELOC_PPC_TLSGD -ENUMX - BFD_RELOC_PPC_TLSLD -ENUMX BFD_RELOC_PPC_DTPMOD ENUMX BFD_RELOC_PPC_TPREL16 diff --git a/contrib/binutils/bfd/section.c b/contrib/binutils/bfd/section.c index 0357d869be86..135f44c0780d 100644 --- a/contrib/binutils/bfd/section.c +++ b/contrib/binutils/bfd/section.c @@ -1,6 +1,6 @@ /* Object file "section" support for the BFD library. Copyright 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, - 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 + 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. Written by Cygnus Support. @@ -382,9 +382,6 @@ CODE_FRAGMENT . {* Nonzero if this section has TLS related relocations. *} . unsigned int has_tls_reloc:1; . -. {* Nonzero if this section has a call to __tls_get_addr. *} -. unsigned int has_tls_get_addr_call:1; -. . {* Nonzero if this section has a gp reloc. *} . unsigned int has_gp_reloc:1; . @@ -645,11 +642,11 @@ CODE_FRAGMENT . {* segment_mark, sec_info_type, use_rela_p, has_tls_reloc, *} \ . 0, 0, 0, 0, \ . \ -. {* has_tls_get_addr_call, has_gp_reloc, need_finalize_relax, *} \ -. 0, 0, 0, \ +. {* has_gp_reloc, need_finalize_relax, reloc_done, *} \ +. 0, 0, 0, \ . \ -. {* reloc_done, vma, lma, size, rawsize *} \ -. 0, 0, 0, 0, 0, \ +. {* vma, lma, size, rawsize *} \ +. 0, 0, 0, 0, \ . \ . {* output_offset, output_section, alignment_power, *} \ . 0, (struct bfd_section *) &SEC, 0, \ diff --git a/contrib/binutils/binutils/doc/binutils.7 b/contrib/binutils/binutils/doc/binutils.7 deleted file mode 100644 index 2c4c0e1b8f2b..000000000000 --- a/contrib/binutils/binutils/doc/binutils.7 +++ /dev/null @@ -1,4917 +0,0 @@ -.Dd 2015-03-02 -.Dt BINUTILS 7 -.Os -.Sh NAME -.Nm binutils -.Nd GNU Binary Utilities -.Sh Introduction -This brief manual contains documentation for the GNU binary utilities version "2.17.50 -[FreeBSD] 2007-07-03": -.Pp -This document is distributed under the terms of the GNU Free Documentation -License. A copy of the license is included in the section entitled "GNU Free -Documentation License". -.Pp -.Sh ar -.Bd -literal -offset indent -ar [-]p[mod [relpos] [count]] archive [member...] -ar -M [ <mri-script ] -.Ed -.Pp -The GNU -.Xr ar -program creates, modifies, and extracts from archives. An -.Em archive -is a single file holding a collection of other files in a structure that makes -it possible to retrieve the original individual files (called -.Em members -of the archive). -.Pp -The original files' contents, mode (permissions), timestamp, owner, and group -are preserved in the archive, and can be restored on extraction. -.Pp -GNU -.Xr ar -can maintain archives whose members have names of any length; however, depending -on how -.Xr ar -is configured on your system, a limit on member-name length may be imposed -for compatibility with archive formats maintained with other tools. If it -exists, the limit is often 15 characters (typical of formats related to a.out) -or 16 characters (typical of formats related to coff). -.Pp -.Xr ar -is considered a binary utility because archives of this sort are most often -used as -.Em libraries -holding commonly needed subroutines. -.Pp -.Xr ar -creates an index to the symbols defined in relocatable object modules in the -archive when you specify the modifier -.Li s . -Once created, this index is updated in the archive whenever -.Xr ar -makes a change to its contents (save for the -.Li q -update operation). An archive with such an index speeds up linking to the -library, and allows routines in the library to call each other without regard -to their placement in the archive. -.Pp -You may use -.Li nm -s -or -.Li nm --print-armap -to list this index table. If an archive lacks the table, another form of -.Xr ar -called -.Xr ranlib -can be used to add just the table. -.Pp -GNU -.Xr ar -is designed to be compatible with two different facilities. You can control -its activity using command-line options, like the different varieties of -.Xr ar -on Unix systems; or, if you specify the single command-line option -.Op -M , -you can control it with a script supplied via standard input, like the MRI -\(lqlibrarian\(rq program. -.Pp -.Ss Controlling Xr ar on the Command Line -.Bd -literal -offset indent -ar [-X32_64] [-]p[mod [relpos] [count]] archive [member...] -.Ed -.Pp -When you use -.Xr ar -in the Unix style, -.Xr ar -insists on at least two arguments to execute: one keyletter specifying the -.Em operation -(optionally accompanied by other keyletters specifying -.Em modifiers ) , -and the archive name to act on. -.Pp -Most operations can also accept further -.Va member -arguments, specifying particular files to operate on. -.Pp -GNU -.Xr ar -allows you to mix the operation code -.Va p -and modifier flags -.Va mod -in any order, within the first command-line argument. -.Pp -If you wish, you may begin the first command-line argument with a dash. -.Pp -The -.Va p -keyletter specifies what operation to execute; it may be any of the following, -but you must specify only one of them: -.Pp -.Bl -tag -width Ds -.It d -.Em Delete -modules from the archive. Specify the names of modules to be deleted as -.Va member -\&...; the archive is untouched if you specify no files to delete. -.Pp -If you specify the -.Li v -modifier, -.Xr ar -lists each module as it is deleted. -.Pp -.It m -Use this operation to -.Em move -members in an archive. -.Pp -The ordering of members in an archive can make a difference in how programs -are linked using the library, if a symbol is defined in more than one member. -.Pp -If no modifiers are used with -.Li m , -any members you name in the -.Va member -arguments are moved to the -.Em end -of the archive; you can use the -.Li a , -.Li b , -or -.Li i -modifiers to move them to a specified place instead. -.Pp -.It p -.Em Print -the specified members of the archive, to the standard output file. If the -.Li v -modifier is specified, show the member name before copying its contents to -standard output. -.Pp -If you specify no -.Va member -arguments, all the files in the archive are printed. -.Pp -.It q -.Em Quick append ; -Historically, add the files -.Va member -\&...to the end of -.Va archive , -without checking for replacement. -.Pp -The modifiers -.Li a , -.Li b , -and -.Li i -do -.Em not -affect this operation; new members are always placed at the end of the archive. -.Pp -The modifier -.Li v -makes -.Xr ar -list each file as it is appended. -.Pp -Since the point of this operation is speed, the archive's symbol table index -is not updated, even if it already existed; you can use -.Li ar s -or -.Xr ranlib -explicitly to update the symbol table index. -.Pp -However, too many different systems assume quick append rebuilds the index, -so GNU -.Xr ar -implements -.Li q -as a synonym for -.Li r . -.Pp -.It r -Insert the files -.Va member -\&...into -.Va archive -(with -.Em replacement ) . -This operation differs from -.Li q -in that any previously existing members are deleted if their names match those -being added. -.Pp -If one of the files named in -.Va member -\&...does not exist, -.Xr ar -displays an error message, and leaves undisturbed any existing members of -the archive matching that name. -.Pp -By default, new members are added at the end of the file; but you may use -one of the modifiers -.Li a , -.Li b , -or -.Li i -to request placement relative to some existing member. -.Pp -The modifier -.Li v -used with this operation elicits a line of output for each file inserted, -along with one of the letters -.Li a -or -.Li r -to indicate whether the file was appended (no old member deleted) or replaced. -.Pp -.It t -Display a -.Em table -listing the contents of -.Va archive , -or those of the files listed in -.Va member -\&...that are present in the archive. Normally only the member name is shown; if -you also want to see the modes (permissions), timestamp, owner, group, and -size, you can request that by also specifying the -.Li v -modifier. -.Pp -If you do not specify a -.Va member , -all files in the archive are listed. -.Pp -If there is more than one file with the same name (say, -.Li fie ) -in an archive (say -.Li b.a ) , -.Li ar t b.a fie -lists only the first instance; to see them all, you must ask for a complete -listing---in our example, -.Li ar t b.a . -.Pp -.It x -.Em Extract -members (named -.Va member ) -from the archive. You can use the -.Li v -modifier with this operation, to request that -.Xr ar -list each name as it extracts it. -.Pp -If you do not specify a -.Va member , -all files in the archive are extracted. -.Pp -.El -A number of modifiers ( -.Va mod ) -may immediately follow the -.Va p -keyletter, to specify variations on an operation's behavior: -.Pp -.Bl -tag -width Ds -.It a -Add new files -.Em after -an existing member of the archive. If you use the modifier -.Li a , -the name of an existing archive member must be present as the -.Va relpos -argument, before the -.Va archive -specification. -.Pp -.It b -Add new files -.Em before -an existing member of the archive. If you use the modifier -.Li b , -the name of an existing archive member must be present as the -.Va relpos -argument, before the -.Va archive -specification. (same as -.Li i ) . -.Pp -.It c -.Em Create -the archive. The specified -.Va archive -is always created if it did not exist, when you request an update. But a warning -is issued unless you specify in advance that you expect to create it, by using -this modifier. -.Pp -.It f -Truncate names in the archive. GNU -.Xr ar -will normally permit file names of any length. This will cause it to create -archives which are not compatible with the native -.Xr ar -program on some systems. If this is a concern, the -.Li f -modifier may be used to truncate file names when putting them in the archive. -.Pp -.It i -Insert new files -.Em before -an existing member of the archive. If you use the modifier -.Li i , -the name of an existing archive member must be present as the -.Va relpos -argument, before the -.Va archive -specification. (same as -.Li b ) . -.Pp -.It l -This modifier is accepted but not used. -.Pp -.It N -Uses the -.Va count -parameter. This is used if there are multiple entries in the archive with -the same name. Extract or delete instance -.Va count -of the given name from the archive. -.Pp -.It o -Preserve the -.Em original -dates of members when extracting them. If you do not specify this modifier, -files extracted from the archive are stamped with the time of extraction. -.Pp -.It P -Use the full path name when matching names in the archive. GNU -.Xr ar -can not create an archive with a full path name (such archives are not POSIX -complaint), but other archive creators can. This option will cause GNU -.Xr ar -to match file names using a complete path name, which can be convenient when -extracting a single file from an archive created by another tool. -.Pp -.It s -Write an object-file index into the archive, or update an existing one, even -if no other change is made to the archive. You may use this modifier flag -either with any operation, or alone. Running -.Li ar s -on an archive is equivalent to running -.Li ranlib -on it. -.Pp -.It S -Do not generate an archive symbol table. This can speed up building a large -library in several steps. The resulting archive can not be used with the linker. -In order to build a symbol table, you must omit the -.Li S -modifier on the last execution of -.Li ar , -or you must run -.Li ranlib -on the archive. -.Pp -.It u -Normally, -.Li ar r -\&...inserts all files listed into the archive. If you would like to insert -.Em only -those of the files you list that are newer than existing members of the same -names, use this modifier. The -.Li u -modifier is allowed only for the operation -.Li r -(replace). In particular, the combination -.Li qu -is not allowed, since checking the timestamps would lose any speed advantage -from the operation -.Li q . -.Pp -.It v -This modifier requests the -.Em verbose -version of an operation. Many operations display additional information, such -as filenames processed, when the modifier -.Li v -is appended. -.Pp -.It V -This modifier shows the version number of -.Xr ar . -.El -.Pp -.Xr ar -ignores an initial option spelt -.Li -X32_64 , -for compatibility with AIX. The behaviour produced by this option is the default -for GNU -.Xr ar . -.Xr ar -does not support any of the other -.Li -X -options; in particular, it does not support -.Op -X32 -which is the default for AIX -.Xr ar . -.Pp -.Ss Controlling Xr ar with a Script -.Bd -literal -offset indent -ar -M [ <script ] -.Ed -.Pp -If you use the single command-line option -.Li -M -with -.Xr ar , -you can control its operation with a rudimentary command language. This form -of -.Xr ar -operates interactively if standard input is coming directly from a terminal. -During interactive use, -.Xr ar -prompts for input (the prompt is -.Li AR > ) , -and continues executing even after errors. If you redirect standard input -to a script file, no prompts are issued, and -.Xr ar -abandons execution (with a nonzero exit code) on any error. -.Pp -The -.Xr ar -command language is -.Em not -designed to be equivalent to the command-line options; in fact, it provides -somewhat less control over archives. The only purpose of the command language -is to ease the transition to GNU -.Xr ar -for developers who already have scripts written for the MRI \(lqlibrarian\(rq program. -.Pp -The syntax for the -.Xr ar -command language is straightforward: -.Bl -bullet -.It -commands are recognized in upper or lower case; for example, -.Li LIST -is the same as -.Li list . -In the following descriptions, commands are shown in upper case for clarity. -.Pp -.It -a single command may appear on each line; it is the first word on the line. -.Pp -.It -empty lines are allowed, and have no effect. -.Pp -.It -comments are allowed; text after either of the characters -.Li * -or -.Li ; -is ignored. -.Pp -.It -Whenever you use a list of names as part of the argument to an -.Xr ar -command, you can separate the individual names with either commas or blanks. -Commas are shown in the explanations below, for clarity. -.Pp -.It -.Li + -is used as a line continuation character; if -.Li + -appears at the end of a line, the text on the following line is considered -part of the current command. -.El -.Pp -Here are the commands you can use in -.Xr ar -scripts, or when using -.Xr ar -interactively. Three of them have special significance: -.Pp -.Li OPEN -or -.Li CREATE -specify a -.Em current archive , -which is a temporary file required for most of the other commands. -.Pp -.Li SAVE -commits the changes so far specified by the script. Prior to -.Li SAVE , -commands affect only the temporary copy of the current archive. -.Pp -.Bl -tag -width Ds -.It ADDLIB Va archive -.It ADDLIB Va archive ( Va module, Va module, ... Va module) -Add all the contents of -.Va archive -(or, if specified, each named -.Va module -from -.Va archive ) -to the current archive. -.Pp -Requires prior use of -.Li OPEN -or -.Li CREATE . -.Pp -.It ADDMOD Va member, Va member, ... Va member -Add each named -.Va member -as a module in the current archive. -.Pp -Requires prior use of -.Li OPEN -or -.Li CREATE . -.Pp -.It CLEAR -Discard the contents of the current archive, canceling the effect of any operations -since the last -.Li SAVE . -May be executed (with no effect) even if no current archive is specified. -.Pp -.It CREATE Va archive -Creates an archive, and makes it the current archive (required for many other -commands). The new archive is created with a temporary name; it is not actually -saved as -.Va archive -until you use -.Li SAVE . -You can overwrite existing archives; similarly, the contents of any existing -file named -.Va archive -will not be destroyed until -.Li SAVE . -.Pp -.It DELETE Va module, Va module, ... Va module -Delete each listed -.Va module -from the current archive; equivalent to -.Li ar -d Va archive Va module ... Va module . -.Pp -Requires prior use of -.Li OPEN -or -.Li CREATE . -.Pp -.It DIRECTORY Va archive ( Va module, ... Va module) -.It DIRECTORY Va archive ( Va module, ... Va module) Va outputfile -List each named -.Va module -present in -.Va archive . -The separate command -.Li VERBOSE -specifies the form of the output: when verbose output is off, output is like -that of -.Li ar -t Va archive Va module... . -When verbose output is on, the listing is like -.Li ar -tv Va archive Va module... . -.Pp -Output normally goes to the standard output stream; however, if you specify -.Va outputfile -as a final argument, -.Xr ar -directs the output to that file. -.Pp -.It END -Exit from -.Xr ar , -with a -.Li 0 -exit code to indicate successful completion. This command does not save the -output file; if you have changed the current archive since the last -.Li SAVE -command, those changes are lost. -.Pp -.It EXTRACT Va module, Va module, ... Va module -Extract each named -.Va module -from the current archive, writing them into the current directory as separate -files. Equivalent to -.Li ar -x Va archive Va module... . -.Pp -Requires prior use of -.Li OPEN -or -.Li CREATE . -.Pp -.It LIST -Display full contents of the current archive, in \(lqverbose\(rq style regardless -of the state of -.Li VERBOSE . -The effect is like -.Li ar tv Va archive . -(This single command is a GNU -.Xr ar -enhancement, rather than present for MRI compatibility.) -.Pp -Requires prior use of -.Li OPEN -or -.Li CREATE . -.Pp -.It OPEN Va archive -Opens an existing archive for use as the current archive (required for many -other commands). Any changes as the result of subsequent commands will not -actually affect -.Va archive -until you next use -.Li SAVE . -.Pp -.It REPLACE Va module, Va module, ... Va module -In the current archive, replace each existing -.Va module -(named in the -.Li REPLACE -arguments) from files in the current working directory. To execute this command -without errors, both the file, and the module in the current archive, must -exist. -.Pp -Requires prior use of -.Li OPEN -or -.Li CREATE . -.Pp -.It VERBOSE -Toggle an internal flag governing the output from -.Li DIRECTORY . -When the flag is on, -.Li DIRECTORY -output matches output from -.Li ar -tv -\&...\&. -.Pp -.It SAVE -Commit your changes to the current archive, and actually save it as a file -with the name specified in the last -.Li CREATE -or -.Li OPEN -command. -.Pp -Requires prior use of -.Li OPEN -or -.Li CREATE . -.Pp -.El -.Sh nm -.Bd -literal -offset indent -nm [-a|--debug-syms] [-g|--extern-only] - [-B] [-C|--demangle[=style]] [-D|--dynamic] - [-S|--print-size] [-s|--print-armap] - [-A|-o|--print-file-name][--special-syms] - [-n|-v|--numeric-sort] [-p|--no-sort] - [-r|--reverse-sort] [--size-sort] [-u|--undefined-only] - [-t radix|--radix=radix] [-P|--portability] - [--target=bfdname] [-fformat|--format=format] - [--defined-only] [-l|--line-numbers] [--no-demangle] - [-V|--version] [-X 32_64] [--help] [objfile...] -.Ed -.Pp -GNU -.Xr nm -lists the symbols from object files -.Va objfile -\&...\&. If no object files are listed as arguments, -.Xr nm -assumes the file -.Pa a.out . -.Pp -For each symbol, -.Xr nm -shows: -.Pp -.Bl -bullet -.It -The symbol value, in the radix selected by options (see below), or hexadecimal -by default. -.Pp -.It -The symbol type. At least the following types are used; others are, as well, -depending on the object file format. If lowercase, the symbol is local; if -uppercase, the symbol is global (external). -.Pp -.Bl -tag -width Ds -.It A -The symbol's value is absolute, and will not be changed by further linking. -.Pp -.It B -The symbol is in the uninitialized data section (known as BSS). -.Pp -.It C -The symbol is common. Common symbols are uninitialized data. When linking, -multiple common symbols may appear with the same name. If the symbol is defined -anywhere, the common symbols are treated as undefined references. For more -details on common symbols, see the discussion of --warn-common in Options,,Linker -options,ld.info,The GNU linker. -.Pp -.It D -The symbol is in the initialized data section. -.Pp -.It G -The symbol is in an initialized data section for small objects. Some object -file formats permit more efficient access to small data objects, such as a -global int variable as opposed to a large global array. -.Pp -.It I -The symbol is an indirect reference to another symbol. This is a GNU extension -to the a.out object file format which is rarely used. -.Pp -.It N -The symbol is a debugging symbol. -.Pp -.It R -The symbol is in a read only data section. -.Pp -.It S -The symbol is in an uninitialized data section for small objects. -.Pp -.It T -The symbol is in the text (code) section. -.Pp -.It U -The symbol is undefined. -.Pp -.It V -The symbol is a weak object. When a weak defined symbol is linked with a normal -defined symbol, the normal defined symbol is used with no error. When a weak -undefined symbol is linked and the symbol is not defined, the value of the -weak symbol becomes zero with no error. -.Pp -.It W -The symbol is a weak symbol that has not been specifically tagged as a weak -object symbol. When a weak defined symbol is linked with a normal defined -symbol, the normal defined symbol is used with no error. When a weak undefined -symbol is linked and the symbol is not defined, the value of the symbol is -determined in a system-specific manner without error. On some systems, uppercase -indicates that a default value has been specified. -.Pp -.It - -The symbol is a stabs symbol in an a.out object file. In this case, the next -values printed are the stabs other field, the stabs desc field, and the stab -type. Stabs symbols are used to hold debugging information. For more information, -see Top,Stabs,Stabs Overview,stabs.info, The \(lqstabs\(rq debug format. -.Pp -.It ? -The symbol type is unknown, or object file format specific. -.El -.Pp -.It -The symbol name. -.El -.Pp -The long and short forms of options, shown here as alternatives, are equivalent. -.Pp -.Bl -tag -width Ds -.It -A -.It -o -.It --print-file-name -Precede each symbol by the name of the input file (or archive member) in which -it was found, rather than identifying the input file once only, before all -of its symbols. -.Pp -.It -a -.It --debug-syms -Display all symbols, even debugger-only symbols; normally these are not listed. -.Pp -.It -B -The same as -.Op --format=bsd -(for compatibility with the MIPS -.Xr nm ) . -.Pp -.It -C -.It --demangle[= Va style] -Decode ( -.Em demangle ) -low-level symbol names into user-level names. Besides removing any initial -underscore prepended by the system, this makes C++ function names readable. -Different compilers have different mangling styles. The optional demangling -style argument can be used to choose an appropriate demangling style for your -compiler.See Section -.Dq c++filt , -for more information on demangling. -.Pp -.It --no-demangle -Do not demangle low-level symbol names. This is the default. -.Pp -.It -D -.It --dynamic -Display the dynamic symbols rather than the normal symbols. This is only meaningful -for dynamic objects, such as certain types of shared libraries. -.Pp -.It -f Va format -.It --format= Va format -Use the output format -.Va format , -which can be -.Li bsd , -.Li sysv , -or -.Li posix . -The default is -.Li bsd . -Only the first character of -.Va format -is significant; it can be either upper or lower case. -.Pp -.It -g -.It --extern-only -Display only external symbols. -.Pp -.It -l -.It --line-numbers -For each symbol, use debugging information to try to find a filename and line -number. For a defined symbol, look for the line number of the address of the -symbol. For an undefined symbol, look for the line number of a relocation -entry which refers to the symbol. If line number information can be found, -print it after the other symbol information. -.Pp -.It -n -.It -v -.It --numeric-sort -Sort symbols numerically by their addresses, rather than alphabetically by -their names. -.Pp -.It -p -.It --no-sort -Do not bother to sort the symbols in any order; print them in the order encountered. -.Pp -.It -P -.It --portability -Use the POSIX.2 standard output format instead of the default format. Equivalent -to -.Li -f posix . -.Pp -.It -S -.It --print-size -Print size, not the value, of defined symbols for the -.Li bsd -output format. -.Pp -.It -s -.It --print-armap -When listing symbols from archive members, include the index: a mapping (stored -in the archive by -.Xr ar -or -.Xr ranlib ) -of which modules contain definitions for which names. -.Pp -.It -r -.It --reverse-sort -Reverse the order of the sort (whether numeric or alphabetic); let the last -come first. -.Pp -.It --size-sort -Sort symbols by size. The size is computed as the difference between the value -of the symbol and the value of the symbol with the next higher value. If the -.Li bsd -output format is used the size of the symbol is printed, rather than the value, -and -.Li -S -must be used in order both size and value to be printed. -.Pp -.It --special-syms -Display symbols which have a target-specific special meaning. These symbols -are usually used by the target for some special processing and are not normally -helpful when included included in the normal symbol lists. For example for -ARM targets this option would skip the mapping symbols used to mark transitions -between ARM code, THUMB code and data. -.Pp -.It -t Va radix -.It --radix= Va radix -Use -.Va radix -as the radix for printing the symbol values. It must be -.Li d -for decimal, -.Li o -for octal, or -.Li x -for hexadecimal. -.Pp -.It --target= Va bfdname -Specify an object code format other than your system's default format.See Section -.Dq Target Selection , -for more information. -.Pp -.It -u -.It --undefined-only -Display only undefined symbols (those external to each object file). -.Pp -.It --defined-only -Display only defined symbols for each object file. -.Pp -.It -V -.It --version -Show the version number of -.Xr nm -and exit. -.Pp -.It -X -This option is ignored for compatibility with the AIX version of -.Xr nm . -It takes one parameter which must be the string -.Op 32_64 . -The default mode of AIX -.Xr nm -corresponds to -.Op -X 32 , -which is not supported by GNU -.Xr nm . -.Pp -.It --help -Show a summary of the options to -.Xr nm -and exit. -.El -.Pp -.Sh objcopy -.Bd -literal -offset indent -objcopy [-F bfdname|--target=bfdname] - [-I bfdname|--input-target=bfdname] - [-O bfdname|--output-target=bfdname] - [-B bfdarch|--binary-architecture=bfdarch] - [-S|--strip-all] - [-g|--strip-debug] - [-K symbolname|--keep-symbol=symbolname] - [-N symbolname|--strip-symbol=symbolname] - [--strip-unneeded-symbol=symbolname] - [-G symbolname|--keep-global-symbol=symbolname] - [--localize-hidden] - [-L symbolname|--localize-symbol=symbolname] - [--globalize-symbol=symbolname] - [-W symbolname|--weaken-symbol=symbolname] - [-w|--wildcard] - [-x|--discard-all] - [-X|--discard-locals] - [-b byte|--byte=byte] - [-i interleave|--interleave=interleave] - [-j sectionname|--only-section=sectionname] - [-R sectionname|--remove-section=sectionname] - [-p|--preserve-dates] - [--debugging] - [--gap-fill=val] - [--pad-to=address] - [--set-start=val] - [--adjust-start=incr] - [--change-addresses=incr] - [--change-section-address section{=,+,-}val] - [--change-section-lma section{=,+,-}val] - [--change-section-vma section{=,+,-}val] - [--change-warnings] [--no-change-warnings] - [--set-section-flags section=flags] - [--add-section sectionname=filename] - [--rename-section oldname=newname[,flags]] - [--change-leading-char] [--remove-leading-char] - [--reverse-bytes=num] - [--srec-len=ival] [--srec-forceS3] - [--redefine-sym old=new] - [--redefine-syms=filename] - [--weaken] - [--keep-symbols=filename] - [--strip-symbols=filename] - [--strip-unneeded-symbols=filename] - [--keep-global-symbols=filename] - [--localize-symbols=filename] - [--globalize-symbols=filename] - [--weaken-symbols=filename] - [--alt-machine-code=index] - [--prefix-symbols=string] - [--prefix-sections=string] - [--prefix-alloc-sections=string] - [--add-GNU-debuglink=path-to-file] - [--keep-file-symbols] - [--only-keep-debug] - [--extract-symbol] - [--writable-text] - [--readonly-text] - [--pure] - [--impure] - [-v|--verbose] - [-V|--version] - [--help] [--info] - infile [outfile] -.Ed -.Pp -The GNU -.Xr objcopy -utility copies the contents of an object file to another. -.Xr objcopy -uses the GNU bfd Library to read and write the object files. It can write -the destination object file in a format different from that of the source -object file. The exact behavior of -.Xr objcopy -is controlled by command-line options. Note that -.Xr objcopy -should be able to copy a fully linked file between any two formats. However, -copying a relocatable object file between any two formats may not work as -expected. -.Pp -.Xr objcopy -creates temporary files to do its translations and deletes them afterward. -.Xr objcopy -uses bfd to do all its translation work; it has access to all the formats -described in bfd and thus is able to recognize most formats without being -told explicitly.See Section -.Dq BFD . -.Pp -.Xr objcopy -can be used to generate S-records by using an output target of -.Li srec -(e.g., use -.Li -O srec ) . -.Pp -.Xr objcopy -can be used to generate a raw binary file by using an output target of -.Li binary -(e.g., use -.Op -O binary ) . -When -.Xr objcopy -generates a raw binary file, it will essentially produce a memory dump of -the contents of the input object file. All symbols and relocation information -will be discarded. The memory dump will start at the load address of the lowest -section copied into the output file. -.Pp -When generating an S-record or a raw binary file, it may be helpful to use -.Op -S -to remove sections containing debugging information. In some cases -.Op -R -will be useful to remove sections which contain information that is not needed -by the binary file. -.Pp -Note--- -.Xr objcopy -is not able to change the endianness of its input files. If the input format -has an endianness (some formats do not), -.Xr objcopy -can only copy the inputs into file formats that have the same endianness or -which have no endianness (e.g., -.Li srec ) . -(However, see the -.Op --reverse-bytes -option.) -.Pp -.Bl -tag -width Ds -.It Va infile -.It Va outfile -The input and output files, respectively. If you do not specify -.Va outfile , -.Xr objcopy -creates a temporary file and destructively renames the result with the name -of -.Va infile . -.Pp -.It -I Va bfdname -.It --input-target= Va bfdname -Consider the source file's object format to be -.Va bfdname , -rather than attempting to deduce it.See Section -.Dq Target Selection , -for more information. -.Pp -.It -O Va bfdname -.It --output-target= Va bfdname -Write the output file using the object format -.Va bfdname . -See Section.Dq Target Selection , -for more information. -.Pp -.It -F Va bfdname -.It --target= Va bfdname -Use -.Va bfdname -as the object format for both the input and the output file; i.e., simply -transfer data from source to destination with no translation.See Section -.Dq Target Selection , -for more information. -.Pp -.It -B Va bfdarch -.It --binary-architecture= Va bfdarch -Useful when transforming a raw binary input file into an object file. In this -case the output architecture can be set to -.Va bfdarch . -This option will be ignored if the input file has a known -.Va bfdarch . -You can access this binary data inside a program by referencing the special -symbols that are created by the conversion process. These symbols are called -_binary_ -.Va objfile -_start, _binary_ -.Va objfile -_end and _binary_ -.Va objfile -_size. e.g. you can transform a picture file into an object file and then -access it in your code using these symbols. -.Pp -.It -j Va sectionname -.It --only-section= Va sectionname -Copy only the named section from the input file to the output file. This option -may be given more than once. Note that using this option inappropriately may -make the output file unusable. -.Pp -.It -R Va sectionname -.It --remove-section= Va sectionname -Remove any section named -.Va sectionname -from the output file. This option may be given more than once. Note that using -this option inappropriately may make the output file unusable. -.Pp -.It -S -.It --strip-all -Do not copy relocation and symbol information from the source file. -.Pp -.It -g -.It --strip-debug -Do not copy debugging symbols or sections from the source file. -.Pp -.It --strip-unneeded -Strip all symbols that are not needed for relocation processing. -.Pp -.It -K Va symbolname -.It --keep-symbol= Va symbolname -When stripping symbols, keep symbol -.Va symbolname -even if it would normally be stripped. This option may be given more than -once. -.Pp -.It -N Va symbolname -.It --strip-symbol= Va symbolname -Do not copy symbol -.Va symbolname -from the source file. This option may be given more than once. -.Pp -.It --strip-unneeded-symbol= Va symbolname -Do not copy symbol -.Va symbolname -from the source file unless it is needed by a relocation. This option may -be given more than once. -.Pp -.It -G Va symbolname -.It --keep-global-symbol= Va symbolname -Keep only symbol -.Va symbolname -global. Make all other symbols local to the file, so that they are not visible -externally. This option may be given more than once. -.Pp -.It --localize-hidden -In an ELF object, mark all symbols that have hidden or internal visibility -as local. This option applies on top of symbol-specific localization options -such as -.Op -L . -.Pp -.It -L Va symbolname -.It --localize-symbol= Va symbolname -Make symbol -.Va symbolname -local to the file, so that it is not visible externally. This option may be -given more than once. -.Pp -.It -W Va symbolname -.It --weaken-symbol= Va symbolname -Make symbol -.Va symbolname -weak. This option may be given more than once. -.Pp -.It --globalize-symbol= Va symbolname -Give symbol -.Va symbolname -global scoping so that it is visible outside of the file in which it is defined. -This option may be given more than once. -.Pp -.It -w -.It --wildcard -Permit regular expressions in -.Va symbolname -s used in other command line options. The question mark (?), asterisk (*), -backslash (\e) and square brackets ([]) operators can be used anywhere in the -symbol name. If the first character of the symbol name is the exclamation -point (!) then the sense of the switch is reversed for that symbol. For example: -.Pp -.Bd -literal -offset indent - -w -W !foo -W fo* -.Ed -.Pp -would cause objcopy to weaken all symbols that start with \(lqfo\(rq except for the -symbol \(lqfoo\(rq. -.Pp -.It -x -.It --discard-all -Do not copy non-global symbols from the source file. -.Pp -.It -X -.It --discard-locals -Do not copy compiler-generated local symbols. (These usually start with -.Li L -or -.Li . . ) -.Pp -.It -b Va byte -.It --byte= Va byte -Keep only every -.Va byte -th byte of the input file (header data is not affected). -.Va byte -can be in the range from 0 to -.Va interleave --1, where -.Va interleave -is given by the -.Op -i -or -.Op --interleave -option, or the default of 4. This option is useful for creating files to program -rom. It is typically used with an -.Li srec -output target. -.Pp -.It -i Va interleave -.It --interleave= Va interleave -Only copy one out of every -.Va interleave -bytes. Select which byte to copy with the -.Op -b -or -.Op --byte -option. The default is 4. -.Xr objcopy -ignores this option if you do not specify either -.Op -b -or -.Op --byte . -.Pp -.It -p -.It --preserve-dates -Set the access and modification dates of the output file to be the same as -those of the input file. -.Pp -.It --debugging -Convert debugging information, if possible. This is not the default because -only certain debugging formats are supported, and the conversion process can -be time consuming. -.Pp -.It --gap-fill Va val -Fill gaps between sections with -.Va val . -This operation applies to the -.Em load address -(LMA) of the sections. It is done by increasing the size of the section with -the lower address, and filling in the extra space created with -.Va val . -.Pp -.It --pad-to Va address -Pad the output file up to the load address -.Va address . -This is done by increasing the size of the last section. The extra space is -filled in with the value specified by -.Op --gap-fill -(default zero). -.Pp -.It --set-start Va val -Set the start address of the new file to -.Va val . -Not all object file formats support setting the start address. -.Pp -.It --change-start Va incr -.It --adjust-start Va incr -Change the start address by adding -.Va incr . -Not all object file formats support setting the start address. -.Pp -.It --change-addresses Va incr -.It --adjust-vma Va incr -Change the VMA and LMA addresses of all sections, as well as the start address, -by adding -.Va incr . -Some object file formats do not permit section addresses to be changed arbitrarily. -Note that this does not relocate the sections; if the program expects sections -to be loaded at a certain address, and this option is used to change the sections -such that they are loaded at a different address, the program may fail. -.Pp -.It --change-section-address Va section{=,+,-} Va val -.It --adjust-section-vma Va section{=,+,-} Va val -Set or change both the VMA address and the LMA address of the named -.Va section . -If -.Li = -is used, the section address is set to -.Va val . -Otherwise, -.Va val -is added to or subtracted from the section address. See the comments under -.Op --change-addresses , -above. If -.Va section -does not exist in the input file, a warning will be issued, unless -.Op --no-change-warnings -is used. -.Pp -.It --change-section-lma Va section{=,+,-} Va val -Set or change the LMA address of the named -.Va section . -The LMA address is the address where the section will be loaded into memory -at program load time. Normally this is the same as the VMA address, which -is the address of the section at program run time, but on some systems, especially -those where a program is held in ROM, the two can be different. If -.Li = -is used, the section address is set to -.Va val . -Otherwise, -.Va val -is added to or subtracted from the section address. See the comments under -.Op --change-addresses , -above. If -.Va section -does not exist in the input file, a warning will be issued, unless -.Op --no-change-warnings -is used. -.Pp -.It --change-section-vma Va section{=,+,-} Va val -Set or change the VMA address of the named -.Va section . -The VMA address is the address where the section will be located once the -program has started executing. Normally this is the same as the LMA address, -which is the address where the section will be loaded into memory, but on -some systems, especially those where a program is held in ROM, the two can -be different. If -.Li = -is used, the section address is set to -.Va val . -Otherwise, -.Va val -is added to or subtracted from the section address. See the comments under -.Op --change-addresses , -above. If -.Va section -does not exist in the input file, a warning will be issued, unless -.Op --no-change-warnings -is used. -.Pp -.It --change-warnings -.It --adjust-warnings -If -.Op --change-section-address -or -.Op --change-section-lma -or -.Op --change-section-vma -is used, and the named section does not exist, issue a warning. This is the -default. -.Pp -.It --no-change-warnings -.It --no-adjust-warnings -Do not issue a warning if -.Op --change-section-address -or -.Op --adjust-section-lma -or -.Op --adjust-section-vma -is used, even if the named section does not exist. -.Pp -.It --set-section-flags Va section= Va flags -Set the flags for the named section. The -.Va flags -argument is a comma separated string of flag names. The recognized names are -.Li alloc , -.Li contents , -.Li load , -.Li noload , -.Li readonly , -.Li code , -.Li data , -.Li rom , -.Li share , -and -.Li debug . -You can set the -.Li contents -flag for a section which does not have contents, but it is not meaningful -to clear the -.Li contents -flag of a section which does have contents--just remove the section instead. -Not all flags are meaningful for all object file formats. -.Pp -.It --add-section Va sectionname= Va filename -Add a new section named -.Va sectionname -while copying the file. The contents of the new section are taken from the -file -.Va filename . -The size of the section will be the size of the file. This option only works -on file formats which can support sections with arbitrary names. -.Pp -.It --rename-section Va oldname= Va newname[, Va flags] -Rename a section from -.Va oldname -to -.Va newname , -optionally changing the section's flags to -.Va flags -in the process. This has the advantage over usng a linker script to perform -the rename in that the output stays as an object file and does not become -a linked executable. -.Pp -This option is particularly helpful when the input format is binary, since -this will always create a section called .data. If for example, you wanted -instead to create a section called .rodata containing binary data you could -use the following command line to achieve it: -.Pp -.Bd -literal -offset indent - objcopy -I binary -O <output_format> -B <architecture> \e - --rename-section .data=.rodata,alloc,load,readonly,data,contents \e - <input_binary_file> <output_object_file> -.Ed -.Pp -.It --change-leading-char -Some object file formats use special characters at the start of symbols. The -most common such character is underscore, which compilers often add before -every symbol. This option tells -.Xr objcopy -to change the leading character of every symbol when it converts between object -file formats. If the object file formats use the same leading character, this -option has no effect. Otherwise, it will add a character, or remove a character, -or change a character, as appropriate. -.Pp -.It --remove-leading-char -If the first character of a global symbol is a special symbol leading character -used by the object file format, remove the character. The most common symbol -leading character is underscore. This option will remove a leading underscore -from all global symbols. This can be useful if you want to link together objects -of different file formats with different conventions for symbol names. This -is different from -.Op --change-leading-char -because it always changes the symbol name when appropriate, regardless of -the object file format of the output file. -.Pp -.It --reverse-bytes= Va num -Reverse the bytes in a section with output contents. A section length must -be evenly divisible by the value given in order for the swap to be able to -take place. Reversing takes place before the interleaving is performed. -.Pp -This option is used typically in generating ROM images for problematic target -systems. For example, on some target boards, the 32-bit words fetched from -8-bit ROMs are re-assembled in little-endian byte order regardless of the -CPU byte order. Depending on the programming model, the endianness of the -ROM may need to be modified. -.Pp -Consider a simple file with a section containing the following eight bytes: -.Li 12345678 . -.Pp -Using -.Li --reverse-bytes=2 -for the above example, the bytes in the output file would be ordered -.Li 21436587 . -.Pp -Using -.Li --reverse-bytes=4 -for the above example, the bytes in the output file would be ordered -.Li 43218765 . -.Pp -By using -.Li --reverse-bytes=2 -for the above example, followed by -.Li --reverse-bytes=4 -on the output file, the bytes in the second output file would be ordered -.Li 34127856 . -.Pp -.It --srec-len= Va ival -Meaningful only for srec output. Set the maximum length of the Srecords being -produced to -.Va ival . -This length covers both address, data and crc fields. -.Pp -.It --srec-forceS3 -Meaningful only for srec output. Avoid generation of S1/S2 records, creating -S3-only record format. -.Pp -.It --redefine-sym Va old= Va new -Change the name of a symbol -.Va old , -to -.Va new . -This can be useful when one is trying link two things together for which you -have no source, and there are name collisions. -.Pp -.It --redefine-syms= Va filename -Apply -.Op --redefine-sym -to each symbol pair " -.Va old -.Va new " -listed in the file -.Va filename . -.Va filename -is simply a flat file, with one symbol pair per line. Line comments may be -introduced by the hash character. This option may be given more than once. -.Pp -.It --weaken -Change all global symbols in the file to be weak. This can be useful when -building an object which will be linked against other objects using the -.Op -R -option to the linker. This option is only effective when using an object file -format which supports weak symbols. -.Pp -.It --keep-symbols= Va filename -Apply -.Op --keep-symbol -option to each symbol listed in the file -.Va filename . -.Va filename -is simply a flat file, with one symbol name per line. Line comments may be -introduced by the hash character. This option may be given more than once. -.Pp -.It --strip-symbols= Va filename -Apply -.Op --strip-symbol -option to each symbol listed in the file -.Va filename . -.Va filename -is simply a flat file, with one symbol name per line. Line comments may be -introduced by the hash character. This option may be given more than once. -.Pp -.It --strip-unneeded-symbols= Va filename -Apply -.Op --strip-unneeded-symbol -option to each symbol listed in the file -.Va filename . -.Va filename -is simply a flat file, with one symbol name per line. Line comments may be -introduced by the hash character. This option may be given more than once. -.Pp -.It --keep-global-symbols= Va filename -Apply -.Op --keep-global-symbol -option to each symbol listed in the file -.Va filename . -.Va filename -is simply a flat file, with one symbol name per line. Line comments may be -introduced by the hash character. This option may be given more than once. -.Pp -.It --localize-symbols= Va filename -Apply -.Op --localize-symbol -option to each symbol listed in the file -.Va filename . -.Va filename -is simply a flat file, with one symbol name per line. Line comments may be -introduced by the hash character. This option may be given more than once. -.Pp -.It --globalize-symbols= Va filename -Apply -.Op --globalize-symbol -option to each symbol listed in the file -.Va filename . -.Va filename -is simply a flat file, with one symbol name per line. Line comments may be -introduced by the hash character. This option may be given more than once. -.Pp -.It --weaken-symbols= Va filename -Apply -.Op --weaken-symbol -option to each symbol listed in the file -.Va filename . -.Va filename -is simply a flat file, with one symbol name per line. Line comments may be -introduced by the hash character. This option may be given more than once. -.Pp -.It --alt-machine-code= Va index -If the output architecture has alternate machine codes, use the -.Va index -th code instead of the default one. This is useful in case a machine is assigned -an official code and the tool-chain adopts the new code, but other applications -still depend on the original code being used. For ELF based architectures -if the -.Va index -alternative does not exist then the value is treated as an absolute number -to be stored in the e_machine field of the ELF header. -.Pp -.It --writable-text -Mark the output text as writable. This option isn't meaningful for all object -file formats. -.Pp -.It --readonly-text -Make the output text write protected. This option isn't meaningful for all -object file formats. -.Pp -.It --pure -Mark the output file as demand paged. This option isn't meaningful for all -object file formats. -.Pp -.It --impure -Mark the output file as impure. This option isn't meaningful for all object -file formats. -.Pp -.It --prefix-symbols= Va string -Prefix all symbols in the output file with -.Va string . -.Pp -.It --prefix-sections= Va string -Prefix all section names in the output file with -.Va string . -.Pp -.It --prefix-alloc-sections= Va string -Prefix all the names of all allocated sections in the output file with -.Va string . -.Pp -.It --add-GNU-debuglink= Va path-to-file -Creates a .GNU_debuglink section which contains a reference to -.Va path-to-file -and adds it to the output file. -.Pp -.It --keep-file-symbols -When stripping a file, perhaps with -.Op --strip-debug -or -.Op --strip-unneeded , -retain any symbols specifying source file names, which would otherwise get -stripped. -.Pp -.It --only-keep-debug -Strip a file, removing contents of any sections that would not be stripped -by -.Op --strip-debug -and leaving the debugging sections intact. In ELF files, this preserves all -note sections in the output. -.Pp -The intention is that this option will be used in conjunction with -.Op --add-GNU-debuglink -to create a two part executable. One a stripped binary which will occupy less -space in RAM and in a distribution and the second a debugging information -file which is only needed if debugging abilities are required. The suggested -procedure to create these files is as follows: -.Pp -.Bl -enum -.It -Link the executable as normal. Assuming that is is called -.Li foo -then... -.It -Run -.Li objcopy --only-keep-debug foo foo.dbg -to -create a file containing the debugging info. -.It -Run -.Li objcopy --strip-debug foo -to create a -stripped executable. -.It -Run -.Li objcopy --add-GNU-debuglink=foo.dbg foo -to add a link to the debugging info into the stripped executable. -.El -.Pp -Note - the choice of -.Li .dbg -as an extension for the debug info file is arbitrary. Also the -.Li --only-keep-debug -step is optional. You could instead do this: -.Pp -.Bl -enum -.It -Link the executable as normal. -.It -Copy -.Li foo -to -.Li foo.full -.It -Run -.Li objcopy --strip-debug foo -.It -Run -.Li objcopy --add-GNU-debuglink=foo.full foo -.El -.Pp -i.e., the file pointed to by the -.Op --add-GNU-debuglink -can be the full executable. It does not have to be a file created by the -.Op --only-keep-debug -switch. -.Pp -Note - this switch is only intended for use on fully linked files. It does -not make sense to use it on object files where the debugging information may -be incomplete. Besides the GNU_debuglink feature currently only supports the -presence of one filename containing debugging information, not multiple filenames -on a one-per-object-file basis. -.Pp -.It --extract-symbol -Keep the file's section flags and symbols but remove all section data. Specifically, -the option: -.Pp -.Bl -bullet -.It -sets the virtual and load addresses of every section to zero; -.It -removes the contents of all sections; -.It -sets the size of every section to zero; and -.It -sets the file's start address to zero. -.El -.Pp -This option is used to build a -.Pa .sym -file for a VxWorks kernel. It can also be a useful way of reducing the size -of a -.Op --just-symbols -linker input file. -.Pp -.It -V -.It --version -Show the version number of -.Xr objcopy . -.Pp -.It -v -.It --verbose -Verbose output: list all object files modified. In the case of archives, -.Li objcopy -V -lists all members of the archive. -.Pp -.It --help -Show a summary of the options to -.Xr objcopy . -.Pp -.It --info -Display a list showing all architectures and object formats available. -.El -.Pp -.Sh objdump -.Bd -literal -offset indent -objdump [-a|--archive-headers] - [-b bfdname|--target=bfdname] - [-C|--demangle[=style] ] - [-d|--disassemble] - [-D|--disassemble-all] - [-z|--disassemble-zeroes] - [-EB|-EL|--endian={big | little }] - [-f|--file-headers] - [--file-start-context] - [-g|--debugging] - [-e|--debugging-tags] - [-h|--section-headers|--headers] - [-i|--info] - [-j section|--section=section] - [-l|--line-numbers] - [-S|--source] - [-m machine|--architecture=machine] - [-M options|--disassembler-options=options] - [-p|--private-headers] - [-r|--reloc] - [-R|--dynamic-reloc] - [-s|--full-contents] - [-W|--dwarf] - [-G|--stabs] - [-t|--syms] - [-T|--dynamic-syms] - [-x|--all-headers] - [-w|--wide] - [--start-address=address] - [--stop-address=address] - [--prefix-addresses] - [--[no-]show-raw-insn] - [--adjust-vma=offset] - [--special-syms] - [-V|--version] - [-H|--help] - objfile... -.Ed -.Pp -.Xr objdump -displays information about one or more object files. The options control what -particular information to display. This information is mostly useful to programmers -who are working on the compilation tools, as opposed to programmers who just -want their program to compile and work. -.Pp -.Va objfile -\&...are the object files to be examined. When you specify archives, -.Xr objdump -shows information on each of the member object files. -.Pp -The long and short forms of options, shown here as alternatives, are equivalent. -At least one option from the list -.Op -a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x -must be given. -.Pp -.Bl -tag -width Ds -.It -a -.It --archive-header -If any of the -.Va objfile -files are archives, display the archive header information (in a format similar -to -.Li ls -l ) . -Besides the information you could list with -.Li ar tv , -.Li objdump -a -shows the object file format of each archive member. -.Pp -.It --adjust-vma= Va offset -When dumping information, first add -.Va offset -to all the section addresses. This is useful if the section addresses do not -correspond to the symbol table, which can happen when putting sections at -particular addresses when using a format which can not represent section addresses, -such as a.out. -.Pp -.It -b Va bfdname -.It --target= Va bfdname -Specify that the object-code format for the object files is -.Va bfdname . -This option may not be necessary; -.Va objdump -can automatically recognize many formats. -.Pp -For example, -.Bd -literal -offset indent -objdump -b oasys -m vax -h fu.o -.Ed -displays summary information from the section headers ( -.Op -h ) -of -.Pa fu.o , -which is explicitly identified ( -.Op -m ) -as a VAX object file in the format produced by Oasys compilers. You can list -the formats available with the -.Op -i -option.See Section -.Dq Target Selection , -for more information. -.Pp -.It -C -.It --demangle[= Va style] -Decode ( -.Em demangle ) -low-level symbol names into user-level names. Besides removing any initial -underscore prepended by the system, this makes C++ function names readable. -Different compilers have different mangling styles. The optional demangling -style argument can be used to choose an appropriate demangling style for your -compiler.See Section -.Dq c++filt , -for more information on demangling. -.Pp -.It -g -.It --debugging -Display debugging information. This attempts to parse debugging information -stored in the file and print it out using a C like syntax. Only certain types -of debugging information have been implemented. Some other types are supported -by -.Xr readelf -w . -See Section.Dq readelf . -.Pp -.It -e -.It --debugging-tags -Like -.Op -g , -but the information is generated in a format compatible with ctags tool. -.Pp -.It -d -.It --disassemble -Display the assembler mnemonics for the machine instructions from -.Va objfile . -This option only disassembles those sections which are expected to contain -instructions. -.Pp -.It -D -.It --disassemble-all -Like -.Op -d , -but disassemble the contents of all sections, not just those expected to contain -instructions. -.Pp -.It --prefix-addresses -When disassembling, print the complete address on each line. This is the older -disassembly format. -.Pp -.It -EB -.It -EL -.It --endian={big|little} -Specify the endianness of the object files. This only affects disassembly. -This can be useful when disassembling a file format which does not describe -endianness information, such as S-records. -.Pp -.It -f -.It --file-headers -Display summary information from the overall header of each of the -.Va objfile -files. -.Pp -.It --file-start-context -Specify that when displaying interlisted source code/disassembly (assumes -.Op -S ) -from a file that has not yet been displayed, extend the context to the start -of the file. -.Pp -.It -h -.It --section-headers -.It --headers -Display summary information from the section headers of the object file. -.Pp -File segments may be relocated to nonstandard addresses, for example by using -the -.Op -Ttext , -.Op -Tdata , -or -.Op -Tbss -options to -.Xr ld . -However, some object file formats, such as a.out, do not store the starting -address of the file segments. In those situations, although -.Xr ld -relocates the sections correctly, using -.Li objdump -h -to list the file section headers cannot show the correct addresses. Instead, -it shows the usual addresses, which are implicit for the target. -.Pp -.It -H -.It --help -Print a summary of the options to -.Xr objdump -and exit. -.Pp -.It -i -.It --info -Display a list showing all architectures and object formats available for -specification with -.Op -b -or -.Op -m . -.Pp -.It -j Va name -.It --section= Va name -Display information only for section -.Va name . -.Pp -.It -l -.It --line-numbers -Label the display (using debugging information) with the filename and source -line numbers corresponding to the object code or relocs shown. Only useful -with -.Op -d , -.Op -D , -or -.Op -r . -.Pp -.It -m Va machine -.It --architecture= Va machine -Specify the architecture to use when disassembling object files. This can -be useful when disassembling object files which do not describe architecture -information, such as S-records. You can list the available architectures with -the -.Op -i -option. -.Pp -.It -M Va options -.It --disassembler-options= Va options -Pass target specific information to the disassembler. Only supported on some -targets. If it is necessary to specify more than one disassembler option then -multiple -.Op -M -options can be used or can be placed together into a comma separated list. -.Pp -If the target is an ARM architecture then this switch can be used to select -which register name set is used during disassembler. Specifying -.Op -M reg-names-std -(the default) will select the register names as used in ARM's instruction -set documentation, but with register 13 called 'sp', register 14 called 'lr' -and register 15 called 'pc'. Specifying -.Op -M reg-names-apcs -will select the name set used by the ARM Procedure Call Standard, whilst specifying -.Op -M reg-names-raw -will just use -.Li r -followed by the register number. -.Pp -There are also two variants on the APCS register naming scheme enabled by -.Op -M reg-names-atpcs -and -.Op -M reg-names-special-atpcs -which use the ARM/Thumb Procedure Call Standard naming conventions. (Either -with the normal register names or the special register names). -.Pp -This option can also be used for ARM architectures to force the disassembler -to interpret all instructions as Thumb instructions by using the switch -.Op --disassembler-options=force-thumb . -This can be useful when attempting to disassemble thumb code produced by other -compilers. -.Pp -For the x86, some of the options duplicate functions of the -.Op -m -switch, but allow finer grained control. Multiple selections from the following -may be specified as a comma separated string. -.Op x86-64 , -.Op i386 -and -.Op i8086 -select disassembly for the given architecture. -.Op intel -and -.Op att -select between intel syntax mode and AT&T syntax mode. -.Op addr64 , -.Op addr32 , -.Op addr16 , -.Op data32 -and -.Op data16 -specify the default address size and operand size. These four options will -be overridden if -.Op x86-64 , -.Op i386 -or -.Op i8086 -appear later in the option string. Lastly, -.Op suffix , -when in AT&T mode, instructs the disassembler to print a mnemonic suffix even -when the suffix could be inferred by the operands. -.Pp -For PPC, -.Op booke , -.Op booke32 -and -.Op booke64 -select disassembly of BookE instructions. -.Op 32 -and -.Op 64 -select PowerPC and PowerPC64 disassembly, respectively. -.Op e300 -selects disassembly for the e300 family. -.Op 440 -selects disassembly for the PowerPC 440. -.Pp -For MIPS, this option controls the printing of instruction mnemonic names -and register names in disassembled instructions. Multiple selections from -the following may be specified as a comma separated string, and invalid options -are ignored: -.Pp -.Bl -tag -width Ds -.It no-aliases -Print the 'raw' instruction mnemonic instead of some pseudo instruction mnemonic. -I.e., print 'daddu' or 'or' instead of 'move', 'sll' instead of 'nop', etc. -.Pp -.It gpr-names= Va ABI -Print GPR (general-purpose register) names as appropriate for the specified -ABI. By default, GPR names are selected according to the ABI of the binary -being disassembled. -.Pp -.It fpr-names= Va ABI -Print FPR (floating-point register) names as appropriate for the specified -ABI. By default, FPR numbers are printed rather than names. -.Pp -.It cp0-names= Va ARCH -Print CP0 (system control coprocessor; coprocessor 0) register names as appropriate -for the CPU or architecture specified by -.Va ARCH . -By default, CP0 register names are selected according to the architecture -and CPU of the binary being disassembled. -.Pp -.It hwr-names= Va ARCH -Print HWR (hardware register, used by the -.Li rdhwr -instruction) names as appropriate for the CPU or architecture specified by -.Va ARCH . -By default, HWR names are selected according to the architecture and CPU of -the binary being disassembled. -.Pp -.It reg-names= Va ABI -Print GPR and FPR names as appropriate for the selected ABI. -.Pp -.It reg-names= Va ARCH -Print CPU-specific register names (CP0 register and HWR names) as appropriate -for the selected CPU or architecture. -.El -.Pp -For any of the options listed above, -.Va ABI -or -.Va ARCH -may be specified as -.Li numeric -to have numbers printed rather than names, for the selected types of registers. -You can list the available values of -.Va ABI -and -.Va ARCH -using the -.Op --help -option. -.Pp -For VAX, you can specify function entry addresses with -.Op -M entry:0xf00ba . -You can use this multiple times to properly disassemble VAX binary files that -don't contain symbol tables (like ROM dumps). In these cases, the function -entry mask would otherwise be decoded as VAX instructions, which would probably -lead the rest of the function being wrongly disassembled. -.Pp -.It -p -.It --private-headers -Print information that is specific to the object file format. The exact information -printed depends upon the object file format. For some object file formats, -no additional information is printed. -.Pp -.It -r -.It --reloc -Print the relocation entries of the file. If used with -.Op -d -or -.Op -D , -the relocations are printed interspersed with the disassembly. -.Pp -.It -R -.It --dynamic-reloc -Print the dynamic relocation entries of the file. This is only meaningful -for dynamic objects, such as certain types of shared libraries. -.Pp -.It -s -.It --full-contents -Display the full contents of any sections requested. By default all non-empty -sections are displayed. -.Pp -.It -S -.It --source -Display source code intermixed with disassembly, if possible. Implies -.Op -d . -.Pp -.It --show-raw-insn -When disassembling instructions, print the instruction in hex as well as in -symbolic form. This is the default except when -.Op --prefix-addresses -is used. -.Pp -.It --no-show-raw-insn -When disassembling instructions, do not print the instruction bytes. This -is the default when -.Op --prefix-addresses -is used. -.Pp -.It -W -.It --dwarf -Displays the contents of the DWARF debug sections in the file, if any are -present. -.Pp -.It -G -.It --stabs -Display the full contents of any sections requested. Display the contents -of the .stab and .stab.index and .stab.excl sections from an ELF file. This -is only useful on systems (such as Solaris 2.0) in which -.Li .stab -debugging symbol-table entries are carried in an ELF section. In most other -file formats, debugging symbol-table entries are interleaved with linkage -symbols, and are visible in the -.Op --syms -output. For more information on stabs symbols, see Top,Stabs,Stabs Overview,stabs.info, -The \(lqstabs\(rq debug format. -.Pp -.It --start-address= Va address -Start displaying data at the specified address. This affects the output of -the -.Op -d , -.Op -r -and -.Op -s -options. -.Pp -.It --stop-address= Va address -Stop displaying data at the specified address. This affects the output of -the -.Op -d , -.Op -r -and -.Op -s -options. -.Pp -.It -t -.It --syms -Print the symbol table entries of the file. This is similar to the information -provided by the -.Li nm -program. -.Pp -.It -T -.It --dynamic-syms -Print the dynamic symbol table entries of the file. This is only meaningful -for dynamic objects, such as certain types of shared libraries. This is similar -to the information provided by the -.Li nm -program when given the -.Op -D -( -.Op --dynamic ) -option. -.Pp -.It --special-syms -When displaying symbols include those which the target considers to be special -in some way and which would not normally be of interest to the user. -.Pp -.It -V -.It --version -Print the version number of -.Xr objdump -and exit. -.Pp -.It -x -.It --all-headers -Display all available header information, including the symbol table and relocation -entries. Using -.Op -x -is equivalent to specifying all of -.Op -a -f -h -p -r -t . -.Pp -.It -w -.It --wide -Format some lines for output devices that have more than 80 columns. Also -do not truncate symbol names when they are displayed. -.Pp -.It -z -.It --disassemble-zeroes -Normally the disassembly output will skip blocks of zeroes. This option directs -the disassembler to disassemble those blocks, just like any other data. -.El -.Pp -.Sh ranlib -.Bd -literal -offset indent -ranlib [-vV] archive -.Ed -.Pp -.Xr ranlib -generates an index to the contents of an archive and stores it in the archive. -The index lists each symbol defined by a member of an archive that is a relocatable -object file. -.Pp -You may use -.Li nm -s -or -.Li nm --print-armap -to list this index. -.Pp -An archive with such an index speeds up linking to the library and allows -routines in the library to call each other without regard to their placement -in the archive. -.Pp -The GNU -.Xr ranlib -program is another form of GNU -.Xr ar ; -running -.Xr ranlib -is completely equivalent to executing -.Li ar -s . -See Section.Dq ar . -.Pp -.Bl -tag -width Ds -.It -v -.It -V -.It --version -Show the version number of -.Xr ranlib . -.El -.Pp -.Sh size -.Bd -literal -offset indent -size [-A|-B|--format=compatibility] - [--help] - [-d|-o|-x|--radix=number] - [-t|--totals] - [--target=bfdname] [-V|--version] - [objfile...] -.Ed -.Pp -The GNU -.Xr size -utility lists the section sizes---and the total size---for each of the object -or archive files -.Va objfile -in its argument list. By default, one line of output is generated for each -object file or each module in an archive. -.Pp -.Va objfile -\&...are the object files to be examined. If none are specified, the file -.Li a.out -will be used. -.Pp -The command line options have the following meanings: -.Pp -.Bl -tag -width Ds -.It -A -.It -B -.It --format= Va compatibility -Using one of these options, you can choose whether the output from GNU -.Xr size -resembles output from System V -.Xr size -(using -.Op -A , -or -.Op --format=sysv ) , -or Berkeley -.Xr size -(using -.Op -B , -or -.Op --format=berkeley ) . -The default is the one-line format similar to Berkeley's. -.Pp -Here is an example of the Berkeley (default) format of output from -.Xr size : -.Bd -literal -offset indent -$ size --format=Berkeley ranlib size -text data bss dec hex filename -294880 81920 11592 388392 5ed28 ranlib -294880 81920 11888 388688 5ee50 size -.Ed -.Pp -This is the same data, but displayed closer to System V conventions: -.Pp -.Bd -literal -offset indent -$ size --format=SysV ranlib size -ranlib : -section size addr -\&.text 294880 8192 -\&.data 81920 303104 -\&.bss 11592 385024 -Total 388392 - - -size : -section size addr -\&.text 294880 8192 -\&.data 81920 303104 -\&.bss 11888 385024 -Total 388688 -.Ed -.Pp -.It --help -Show a summary of acceptable arguments and options. -.Pp -.It -d -.It -o -.It -x -.It --radix= Va number -Using one of these options, you can control whether the size of each section -is given in decimal ( -.Op -d , -or -.Op --radix=10 ) ; -octal ( -.Op -o , -or -.Op --radix=8 ) ; -or hexadecimal ( -.Op -x , -or -.Op --radix=16 ) . -In -.Op --radix= Va number , -only the three values (8, 10, 16) are supported. The total size is always -given in two radices; decimal and hexadecimal for -.Op -d -or -.Op -x -output, or octal and hexadecimal if you're using -.Op -o . -.Pp -.It -t -.It --totals -Show totals of all objects listed (Berkeley format listing mode only). -.Pp -.It --target= Va bfdname -Specify that the object-code format for -.Va objfile -is -.Va bfdname . -This option may not be necessary; -.Xr size -can automatically recognize many formats.See Section -.Dq Target Selection , -for more information. -.Pp -.It -V -.It --version -Display the version number of -.Xr size . -.El -.Pp -.Sh strings -.Bd -literal -offset indent -strings [-afov] [-min-len] - [-n min-len] [--bytes=min-len] - [-t radix] [--radix=radix] - [-e encoding] [--encoding=encoding] - [-] [--all] [--print-file-name] - [-T bfdname] [--target=bfdname] - [--help] [--version] file... -.Ed -.Pp -For each -.Va file -given, GNU -.Xr strings -prints the printable character sequences that are at least 4 characters long -(or the number given with the options below) and are followed by an unprintable -character. By default, it only prints the strings from the initialized and -loaded sections of object files; for other types of files, it prints the strings -from the whole file. -.Pp -.Xr strings -is mainly useful for determining the contents of non-text files. -.Pp -.Bl -tag -width Ds -.It -a -.It --all -.It - -Do not scan only the initialized and loaded sections of object files; scan -the whole files. -.Pp -.It -f -.It --print-file-name -Print the name of the file before each string. -.Pp -.It --help -Print a summary of the program usage on the standard output and exit. -.Pp -.It - Va min-len -.It -n Va min-len -.It --bytes= Va min-len -Print sequences of characters that are at least -.Va min-len -characters long, instead of the default 4. -.Pp -.It -o -Like -.Li -t o . -Some other versions of -.Xr strings -have -.Op -o -act like -.Li -t d -instead. Since we can not be compatible with both ways, we simply chose one. -.Pp -.It -t Va radix -.It --radix= Va radix -Print the offset within the file before each string. The single character -argument specifies the radix of the offset--- -.Li o -for octal, -.Li x -for hexadecimal, or -.Li d -for decimal. -.Pp -.It -e Va encoding -.It --encoding= Va encoding -Select the character encoding of the strings that are to be found. Possible -values for -.Va encoding -are: -.Li s -= single-7-bit-byte characters (ASCII, ISO 8859, etc., default), -.Li S -= single-8-bit-byte characters, -.Li b -= 16-bit bigendian, -.Li l -= 16-bit littleendian, -.Li B -= 32-bit bigendian, -.Li L -= 32-bit littleendian. Useful for finding wide character strings. -.Pp -.It -T Va bfdname -.It --target= Va bfdname -Specify an object code format other than your system's default format.See Section -.Dq Target Selection , -for more information. -.Pp -.It -v -.It --version -Print the program version number on the standard output and exit. -.El -.Pp -.Sh strip -.Bd -literal -offset indent -strip [-F bfdname |--target=bfdname] - [-I bfdname |--input-target=bfdname] - [-O bfdname |--output-target=bfdname] - [-s|--strip-all] - [-S|-g|-d|--strip-debug] - [-K symbolname |--keep-symbol=symbolname] - [-N symbolname |--strip-symbol=symbolname] - [-w|--wildcard] - [-x|--discard-all] [-X |--discard-locals] - [-R sectionname |--remove-section=sectionname] - [-o file] [-p|--preserve-dates] - [--keep-file-symbols] - [--only-keep-debug] - [-v |--verbose] [-V|--version] - [--help] [--info] - objfile... -.Ed -.Pp -GNU -.Xr strip -discards all symbols from object files -.Va objfile . -The list of object files may include archives. At least one object file must -be given. -.Pp -.Xr strip -modifies the files named in its argument, rather than writing modified copies -under different names. -.Pp -.Bl -tag -width Ds -.It -F Va bfdname -.It --target= Va bfdname -Treat the original -.Va objfile -as a file with the object code format -.Va bfdname , -and rewrite it in the same format.See Section -.Dq Target Selection , -for more information. -.Pp -.It --help -Show a summary of the options to -.Xr strip -and exit. -.Pp -.It --info -Display a list showing all architectures and object formats available. -.Pp -.It -I Va bfdname -.It --input-target= Va bfdname -Treat the original -.Va objfile -as a file with the object code format -.Va bfdname . -See Section.Dq Target Selection , -for more information. -.Pp -.It -O Va bfdname -.It --output-target= Va bfdname -Replace -.Va objfile -with a file in the output format -.Va bfdname . -See Section.Dq Target Selection , -for more information. -.Pp -.It -R Va sectionname -.It --remove-section= Va sectionname -Remove any section named -.Va sectionname -from the output file. This option may be given more than once. Note that using -this option inappropriately may make the output file unusable. -.Pp -.It -s -.It --strip-all -Remove all symbols. -.Pp -.It -g -.It -S -.It -d -.It --strip-debug -Remove debugging symbols only. -.Pp -.It --strip-unneeded -Remove all symbols that are not needed for relocation processing. -.Pp -.It -K Va symbolname -.It --keep-symbol= Va symbolname -When stripping symbols, keep symbol -.Va symbolname -even if it would normally be stripped. This option may be given more than -once. -.Pp -.It -N Va symbolname -.It --strip-symbol= Va symbolname -Remove symbol -.Va symbolname -from the source file. This option may be given more than once, and may be -combined with strip options other than -.Op -K . -.Pp -.It -o Va file -Put the stripped output in -.Va file , -rather than replacing the existing file. When this argument is used, only -one -.Va objfile -argument may be specified. -.Pp -.It -p -.It --preserve-dates -Preserve the access and modification dates of the file. -.Pp -.It -w -.It --wildcard -Permit regular expressions in -.Va symbolname -s used in other command line options. The question mark (?), asterisk (*), -backslash (\e) and square brackets ([]) operators can be used anywhere in the -symbol name. If the first character of the symbol name is the exclamation -point (!) then the sense of the switch is reversed for that symbol. For example: -.Pp -.Bd -literal -offset indent - -w -K !foo -K fo* -.Ed -.Pp -would cause strip to only keep symbols that start with the letters \(lqfo\(rq, but -to discard the symbol \(lqfoo\(rq. -.Pp -.It -x -.It --discard-all -Remove non-global symbols. -.Pp -.It -X -.It --discard-locals -Remove compiler-generated local symbols. (These usually start with -.Li L -or -.Li . . ) -.Pp -.It --keep-file-symbols -When stripping a file, perhaps with -.Op --strip-debug -or -.Op --strip-unneeded , -retain any symbols specifying source file names, which would otherwise get -stripped. -.Pp -.It --only-keep-debug -Strip a file, removing contents of any sections that would not be stripped -by -.Op --strip-debug -and leaving the debugging sections intact. In ELF files, this preserves all -note sections in the output. -.Pp -The intention is that this option will be used in conjunction with -.Op --add-GNU-debuglink -to create a two part executable. One a stripped binary which will occupy less -space in RAM and in a distribution and the second a debugging information -file which is only needed if debugging abilities are required. The suggested -procedure to create these files is as follows: -.Pp -.Bl -enum -.It -Link the executable as normal. Assuming that is is called -.Li foo -then... -.It -Run -.Li objcopy --only-keep-debug foo foo.dbg -to -create a file containing the debugging info. -.It -Run -.Li objcopy --strip-debug foo -to create a -stripped executable. -.It -Run -.Li objcopy --add-GNU-debuglink=foo.dbg foo -to add a link to the debugging info into the stripped executable. -.El -.Pp -Note - the choice of -.Li .dbg -as an extension for the debug info file is arbitrary. Also the -.Li --only-keep-debug -step is optional. You could instead do this: -.Pp -.Bl -enum -.It -Link the executable as normal. -.It -Copy -.Li foo -to -.Li foo.full -.It -Run -.Li strip --strip-debug foo -.It -Run -.Li objcopy --add-GNU-debuglink=foo.full foo -.El -.Pp -ie the file pointed to by the -.Op --add-GNU-debuglink -can be the full executable. It does not have to be a file created by the -.Op --only-keep-debug -switch. -.Pp -Note - this switch is only intended for use on fully linked files. It does -not make sense to use it on object files where the debugging information may -be incomplete. Besides the GNU_debuglink feature currently only supports the -presence of one filename containing debugging information, not multiple filenames -on a one-per-object-file basis. -.Pp -.It -V -.It --version -Show the version number for -.Xr strip . -.Pp -.It -v -.It --verbose -Verbose output: list all object files modified. In the case of archives, -.Li strip -v -lists all members of the archive. -.El -.Pp -.Sh c++filt -.Bd -literal -offset indent -c++filt [-_|--strip-underscores] - [-n|--no-strip-underscores] - [-p|--no-params] - [-t|--types] - [-i|--no-verbose] - [-s format|--format=format] - [--help] [--version] [symbol...] -.Ed -.Pp -The C++ and Java languages provide function overloading, which means that -you can write many functions with the same name, providing that each function -takes parameters of different types. In order to be able to distinguish these -similarly named functions C++ and Java encode them into a low-level assembler -name which uniquely identifies each different version. This process is known -as -.Em mangling . -The -.Xr c++filt -program does the inverse mapping: it decodes ( -.Em demangles ) -low-level names into user-level names so that they can be read. -.Pp -Every alphanumeric word (consisting of letters, digits, underscores, dollars, -or periods) seen in the input is a potential mangled name. If the name decodes -into a C++ name, the C++ name replaces the low-level name in the output, otherwise -the original word is output. In this way you can pass an entire assembler -source file, containing mangled names, through -.Xr c++filt -and see the same source file containing demangled names. -.Pp -You can also use -.Xr c++filt -to decipher individual symbols by passing them on the command line: -.Pp -.Bd -literal -offset indent -c++filt symbol -.Ed -.Pp -If no -.Va symbol -arguments are given, -.Xr c++filt -reads symbol names from the standard input instead. All the results are printed -on the standard output. The difference between reading names from the command -line versus reading names from the standard input is that command line arguments -are expected to be just mangled names and no checking is performed to separate -them from surrounding text. Thus for example: -.Pp -.Bd -literal -offset indent -c++filt -n _Z1fv -.Ed -.Pp -will work and demangle the name to \(lqf()\(rq whereas: -.Pp -.Bd -literal -offset indent -c++filt -n _Z1fv, -.Ed -.Pp -will not work. (Note the extra comma at the end of the mangled name which -makes it invalid). This command however will work: -.Pp -.Bd -literal -offset indent -echo _Z1fv, | c++filt -n -.Ed -.Pp -and will display \(lqf(),\(rq ie the demangled name followed by a trailing comma. -This behaviour is because when the names are read from the standard input -it is expected that they might be part of an assembler source file where there -might be extra, extraneous characters trailing after a mangled name. eg: -.Pp -.Bd -literal -offset indent - .type _Z1fv, @function -.Ed -.Pp -.Bl -tag -width Ds -.It -_ -.It --strip-underscores -On some systems, both the C and C++ compilers put an underscore in front of -every name. For example, the C name -.Li foo -gets the low-level name -.Li _foo . -This option removes the initial underscore. Whether -.Xr c++filt -removes the underscore by default is target dependent. -.Pp -.It -j -.It --java -Prints demangled names using Java syntax. The default is to use C++ syntax. -.Pp -.It -n -.It --no-strip-underscores -Do not remove the initial underscore. -.Pp -.It -p -.It --no-params -When demangling the name of a function, do not display the types of the function's -parameters. -.Pp -.It -t -.It --types -Attempt to demangle types as well as function names. This is disabled by default -since mangled types are normally only used internally in the compiler, and -they can be confused with non-mangled names. eg a function called \(lqa\(rq treated -as a mangled type name would be demangled to \(lqsigned char\(rq. -.Pp -.It -i -.It --no-verbose -Do not include implementation details (if any) in the demangled output. -.Pp -.It -s Va format -.It --format= Va format -.Xr c++filt -can decode various methods of mangling, used by different compilers. The argument -to this option selects which method it uses: -.Pp -.Bl -tag -width Ds -.It auto -Automatic selection based on executable (the default method) -.It GNU -the one used by the GNU C++ compiler (g++) -.It lucid -the one used by the Lucid compiler (lcc) -.It arm -the one specified by the C++ Annotated Reference Manual -.It hp -the one used by the HP compiler (aCC) -.It edg -the one used by the EDG compiler -.It GNU-v3 -the one used by the GNU C++ compiler (g++) with the V3 ABI. -.It java -the one used by the GNU Java compiler (gcj) -.It gnat -the one used by the GNU Ada compiler (GNAT). -.El -.Pp -.It --help -Print a summary of the options to -.Xr c++filt -and exit. -.Pp -.It --version -Print the version number of -.Xr c++filt -and exit. -.El -.Pp -.Qo -.Em Warning: -.Xr c++filt -is a new utility, and the details of its user interface are subject to change -in future releases. In particular, a command-line option may be required in -the future to decode a name passed as an argument on the command line; in -other words, -.Pp -.Bd -literal -offset indent -c++filt symbol -.Ed -.Pp -may in a future release become -.Pp -.Bd -literal -offset indent -c++filt option symbol -.Ed -.Qc -.Pp -.Sh addr2line -.Bd -literal -offset indent -addr2line [-b bfdname|--target=bfdname] - [-C|--demangle[=style]] - [-e filename|--exe=filename] - [-f|--functions] [-s|--basename] - [-i|--inlines] - [-j|--section=name] - [-H|--help] [-V|--version] - [addr addr ...] -.Ed -.Pp -.Xr addr2line -translates addresses into file names and line numbers. Given an address in -an executable or an offset in a section of a relocatable object, it uses the -debugging information to figure out which file name and line number are associated -with it. -.Pp -The executable or relocatable object to use is specified with the -.Op -e -option. The default is the file -.Pa a.out . -The section in the relocatable object to use is specified with the -.Op -j -option. -.Pp -.Xr addr2line -has two modes of operation. -.Pp -In the first, hexadecimal addresses are specified on the command line, and -.Xr addr2line -displays the file name and line number for each address. -.Pp -In the second, -.Xr addr2line -reads hexadecimal addresses from standard input, and prints the file name -and line number for each address on standard output. In this mode, -.Xr addr2line -may be used in a pipe to convert dynamically chosen addresses. -.Pp -The format of the output is -.Li FILENAME:LINENO . -The file name and line number for each address is printed on a separate line. -If the -.Xr -f -option is used, then each -.Li FILENAME:LINENO -line is preceded by a -.Li FUNCTIONNAME -line which is the name of the function containing the address. -.Pp -If the file name or function name can not be determined, -.Xr addr2line -will print two question marks in their place. If the line number can not be -determined, -.Xr addr2line -will print 0. -.Pp -The long and short forms of options, shown here as alternatives, are equivalent. -.Pp -.Bl -tag -width Ds -.It -b Va bfdname -.It --target= Va bfdname -Specify that the object-code format for the object files is -.Va bfdname . -.Pp -.It -C -.It --demangle[= Va style] -Decode ( -.Em demangle ) -low-level symbol names into user-level names. Besides removing any initial -underscore prepended by the system, this makes C++ function names readable. -Different compilers have different mangling styles. The optional demangling -style argument can be used to choose an appropriate demangling style for your -compiler.See Section -.Dq c++filt , -for more information on demangling. -.Pp -.It -e Va filename -.It --exe= Va filename -Specify the name of the executable for which addresses should be translated. -The default file is -.Pa a.out . -.Pp -.It -f -.It --functions -Display function names as well as file and line number information. -.Pp -.It -s -.It --basenames -Display only the base of each file name. -.Pp -.It -i -.It --inlines -If the address belongs to a function that was inlined, the source information -for all enclosing scopes back to the first non-inlined function will also -be printed. For example, if -.Li main -inlines -.Li callee1 -which inlines -.Li callee2 , -and address is from -.Li callee2 , -the source information for -.Li callee1 -and -.Li main -will also be printed. -.Pp -.It -j -.It --section -Read offsets relative to the specified section instead of absolute addresses. -.El -.Pp -.Sh nlmconv -.Xr nlmconv -converts a relocatable object file into a NetWare Loadable Module. -.Pp -.Qo -.Em Warning: -.Xr nlmconv -is not always built as part of the binary utilities, since it is only useful -for NLM targets. -.Qc -.Pp -.Bd -literal -offset indent -nlmconv [-I bfdname|--input-target=bfdname] - [-O bfdname|--output-target=bfdname] - [-T headerfile|--header-file=headerfile] - [-d|--debug] [-l linker|--linker=linker] - [-h|--help] [-V|--version] - infile outfile -.Ed -.Pp -.Xr nlmconv -converts the relocatable -.Li i386 -object file -.Va infile -into the NetWare Loadable Module -.Va outfile , -optionally reading -.Va headerfile -for NLM header information. For instructions on writing the NLM command file -language used in header files, see the -.Li linkers -section, -.Li NLMLINK -in particular, of the -.Em NLM Development and Tools Overview , -which is part of the NLM Software Developer's Kit (\(lqNLM SDK\(rq), available from -Novell, Inc. -.Xr nlmconv -uses the GNU Binary File Descriptor library to read -.Va infile ; -see BFD,,BFD,ld.info,Using LD, for more information. -.Pp -.Xr nlmconv -can perform a link step. In other words, you can list more than one object -file for input if you list them in the definitions file (rather than simply -specifying one input file on the command line). In this case, -.Xr nlmconv -calls the linker for you. -.Pp -.Bl -tag -width Ds -.It -I Va bfdname -.It --input-target= Va bfdname -Object format of the input file. -.Xr nlmconv -can usually determine the format of a given file (so no default is necessary).See Section -.Dq Target Selection , -for more information. -.Pp -.It -O Va bfdname -.It --output-target= Va bfdname -Object format of the output file. -.Xr nlmconv -infers the output format based on the input format, e.g. for a -.Li i386 -input file the output format is -.Li nlm32-i386 . -See Section.Dq Target Selection , -for more information. -.Pp -.It -T Va headerfile -.It --header-file= Va headerfile -Reads -.Va headerfile -for NLM header information. For instructions on writing the NLM command file -language used in header files, see see the -.Li linkers -section, of the -.Em NLM Development and Tools Overview , -which is part of the NLM Software Developer's Kit, available from Novell, -Inc. -.Pp -.It -d -.It --debug -Displays (on standard error) the linker command line used by -.Xr nlmconv . -.Pp -.It -l Va linker -.It --linker= Va linker -Use -.Va linker -for any linking. -.Va linker -can be an absolute or a relative pathname. -.Pp -.It -h -.It --help -Prints a usage summary. -.Pp -.It -V -.It --version -Prints the version number for -.Xr nlmconv . -.El -.Pp -.Sh windmc -.Xr windmc -may be used to generator Windows message resources. -.Pp -.Qo -.Em Warning: -.Xr windmc -is not always built as part of the binary utilities, since it is only useful -for Windows targets. -.Qc -.Pp -.Bd -literal -offset indent -windmc [options] input-file -.Ed -.Pp -.Xr windmc -reads message definitions from an input file (.mc) and translate them into -a set of output files. The output files may be of four kinds: -.Pp -.Bl -tag -width Ds -.It h -A C header file containing the message definitions. -.Pp -.It rc -A resource file compilable by the -.Xr windres -tool. -.Pp -.It bin -One or more binary files containing the resource data for a specific message -language. -.Pp -.It dbg -A C include file that maps message id's to their symbolic name. -.El -.Pp -The exact description of these different formats is available in documentation -from Microsoft. -.Pp -When -.Xr windmc -converts from the -.Li mc -format to the -.Li bin -format, -.Li rc , -.Li h , -and optional -.Li dbg -it is acting like the Windows Message Compiler. -.Pp -.Bl -tag -width Ds -.It -a -.It --ascii_in -Specifies that the input file specified is ANSI. This is the default behaviour. -.Pp -.It -A -.It --ascii_out -Specifies that messages in the output -.Li bin -files should be in ANSI format. -.Pp -.It -b -.It --binprefix -Specifies that -.Li bin -filenames should have to be prefixed by the basename of the source file. -.Pp -.It -c -.It --customflag -Sets the customer bit in all message id's. -.Pp -.It -C Va codepage -.It --codepage_in Va codepage -Sets the default codepage to be used to convert input file to UTF16. The default -is ocdepage 1252. -.Pp -.It -d -.It --decimal_values -Outputs the constants in the header file in decimal. Default is using hexadecimal -output. -.Pp -.It -e Va ext -.It --extension Va ext -The extension for the header file. The default is .h extension. -.Pp -.It -F Va target -.It --target Va target -Specify the BFD format to use for a bin file as output. This is a BFD target -name; you can use the -.Op --help -option to see a list of supported targets. Normally -.Xr windmc -will use the default format, which is the first one listed by the -.Op --help -option. Target Selection. -.Pp -.It -h Va path -.It --headerdir Va path -The target directory of the generated header file. The default is the current -directory. -.Pp -.It -H -.It --help -Displays a list of command line options and then exits. -.Pp -.It -m Va characters -.It --maxlength Va characters -Instructs -.Xr windmc -to generate a warning if the length of any message exceeds the number specified. -.Pp -.It -n -.It --nullterminate -Terminate message text in -.Li bin -files by zero. By default they are terminated by CR/LF. -.Pp -.It -o -.It --hresult_use -Not yet implemented. Instructs -.Li windmc -to generate an OLE2 header file, using HRESULT definitions. Status codes are -used if the flag is not specified. -.Pp -.It -O Va codepage -.It --codepage_out Va codepage -Sets the default codepage to be used to output text files. The default is -ocdepage 1252. -.Pp -.It -r Va path -.It --rcdir Va path -The target directory for the generated -.Li rc -script and the generated -.Li bin -files that the resource compiler script includes. The default is the current -directory. -.Pp -.It -u -.It --unicode_in -Specifies that the input file is UTF16. -.Pp -.It -U -.It --unicode_out -Specifies that messages in the output -.Li bin -file should be in UTF16 format. This is the default behaviour. -.Pp -.It -v -.It --verbose -Enable verbose mode. This tells you what the preprocessor is if you didn't -specify one. -.Pp -.It -V -.It --version -Prints the version number for -.Xr windres . -.Pp -.It -x Va path -.It --xdgb Va path -The path of the -.Li dbg -C include file that maps message id's to the symbolic name. No such file is -generated without specifying the switch. -.El -.Pp -.Sh windres -.Xr windres -may be used to manipulate Windows resources. -.Pp -.Qo -.Em Warning: -.Xr windres -is not always built as part of the binary utilities, since it is only useful -for Windows targets. -.Qc -.Pp -.Bd -literal -offset indent -windres [options] [input-file] [output-file] -.Ed -.Pp -.Xr windres -reads resources from an input file and copies them into an output file. Either -file may be in one of three formats: -.Pp -.Bl -tag -width Ds -.It rc -A text format read by the Resource Compiler. -.Pp -.It res -A binary format generated by the Resource Compiler. -.Pp -.It coff -A COFF object or executable. -.El -.Pp -The exact description of these different formats is available in documentation -from Microsoft. -.Pp -When -.Xr windres -converts from the -.Li rc -format to the -.Li res -format, it is acting like the Windows Resource Compiler. When -.Xr windres -converts from the -.Li res -format to the -.Li coff -format, it is acting like the Windows -.Li CVTRES -program. -.Pp -When -.Xr windres -generates an -.Li rc -file, the output is similar but not identical to the format expected for the -input. When an input -.Li rc -file refers to an external filename, an output -.Li rc -file will instead include the file contents. -.Pp -If the input or output format is not specified, -.Xr windres -will guess based on the file name, or, for the input file, the file contents. -A file with an extension of -.Pa .rc -will be treated as an -.Li rc -file, a file with an extension of -.Pa .res -will be treated as a -.Li res -file, and a file with an extension of -.Pa .o -or -.Pa .exe -will be treated as a -.Li coff -file. -.Pp -If no output file is specified, -.Xr windres -will print the resources in -.Li rc -format to standard output. -.Pp -The normal use is for you to write an -.Li rc -file, use -.Xr windres -to convert it to a COFF object file, and then link the COFF file into your -application. This will make the resources described in the -.Li rc -file available to Windows. -.Pp -.Bl -tag -width Ds -.It -i Va filename -.It --input Va filename -The name of the input file. If this option is not used, then -.Xr windres -will use the first non-option argument as the input file name. If there are -no non-option arguments, then -.Xr windres -will read from standard input. -.Xr windres -can not read a COFF file from standard input. -.Pp -.It -o Va filename -.It --output Va filename -The name of the output file. If this option is not used, then -.Xr windres -will use the first non-option argument, after any used for the input file -name, as the output file name. If there is no non-option argument, then -.Xr windres -will write to standard output. -.Xr windres -can not write a COFF file to standard output. Note, for compatibility with -.Xr rc -the option -.Op -fo -is also accepted, but its use is not recommended. -.Pp -.It -J Va format -.It --input-format Va format -The input format to read. -.Va format -may be -.Li res , -.Li rc , -or -.Li coff . -If no input format is specified, -.Xr windres -will guess, as described above. -.Pp -.It -O Va format -.It --output-format Va format -The output format to generate. -.Va format -may be -.Li res , -.Li rc , -or -.Li coff . -If no output format is specified, -.Xr windres -will guess, as described above. -.Pp -.It -F Va target -.It --target Va target -Specify the BFD format to use for a COFF file as input or output. This is -a BFD target name; you can use the -.Op --help -option to see a list of supported targets. Normally -.Xr windres -will use the default format, which is the first one listed by the -.Op --help -option. Target Selection. -.Pp -.It --preprocessor Va program -When -.Xr windres -reads an -.Li rc -file, it runs it through the C preprocessor first. This option may be used -to specify the preprocessor to use, including any leading arguments. The default -preprocessor argument is -.Li gcc -E -xc-header -DRC_INVOKED . -.Pp -.It -I Va directory -.It --include-dir Va directory -Specify an include directory to use when reading an -.Li rc -file. -.Xr windres -will pass this to the preprocessor as an -.Op -I -option. -.Xr windres -will also search this directory when looking for files named in the -.Li rc -file. If the argument passed to this command matches any of the supported -.Va formats -(as described in the -.Op -J -option), it will issue a deprecation warning, and behave just like the -.Op -J -option. New programs should not use this behaviour. If a directory happens -to match a -.Va format , -simple prefix it with -.Li ./ -to disable the backward compatibility. -.Pp -.It -D Va target -.It --define Va sym[= Va val] -Specify a -.Op -D -option to pass to the preprocessor when reading an -.Li rc -file. -.Pp -.It -U Va target -.It --undefine Va sym -Specify a -.Op -U -option to pass to the preprocessor when reading an -.Li rc -file. -.Pp -.It -r -Ignored for compatibility with rc. -.Pp -.It -v -Enable verbose mode. This tells you what the preprocessor is if you didn't -specify one. -.Pp -.It -c Va val -.It --codepage Va val -Specify the default codepage to use when reading an -.Li rc -file. -.Va val -should be a hexadecimal prefixed by -.Li 0x -or decimal codepage code. The valid range is from zero up to 0xffff, but the -validity of the codepage is host and configuration dependent. -.Pp -.It -l Va val -.It --language Va val -Specify the default language to use when reading an -.Li rc -file. -.Va val -should be a hexadecimal language code. The low eight bits are the language, -and the high eight bits are the sublanguage. -.Pp -.It --use-temp-file -Use a temporary file to instead of using popen to read the output of the preprocessor. -Use this option if the popen implementation is buggy on the host (eg., certain -non-English language versions of Windows 95 and Windows 98 are known to have -buggy popen where the output will instead go the console). -.Pp -.It --no-use-temp-file -Use popen, not a temporary file, to read the output of the preprocessor. This -is the default behaviour. -.Pp -.It -h -.It --help -Prints a usage summary. -.Pp -.It -V -.It --version -Prints the version number for -.Xr windres . -.Pp -.It --yydebug -If -.Xr windres -is compiled with -.Li YYDEBUG -defined as -.Li 1 , -this will turn on parser debugging. -.El -.Pp -.Sh dlltool -.Xr dlltool -is used to create the files needed to create dynamic link libraries (DLLs) -on systems which understand PE format image files such as Windows. A DLL contains -an export table which contains information that the runtime loader needs to -resolve references from a referencing program. -.Pp -The export table is generated by this program by reading in a -.Pa .def -file or scanning the -.Pa .a -and -.Pa .o -files which will be in the DLL. A -.Pa .o -file can contain information in special -.Li .drectve -sections with export information. -.Pp -.Qo -.Em Note: -.Xr dlltool -is not always built as part of the binary utilities, since it is only useful -for those targets which support DLLs. -.Qc -.Pp -.Bd -literal -offset indent -dlltool [-d|--input-def def-file-name] - [-b|--base-file base-file-name] - [-e|--output-exp exports-file-name] - [-z|--output-def def-file-name] - [-l|--output-lib library-file-name] - [--export-all-symbols] [--no-export-all-symbols] - [--exclude-symbols list] - [--no-default-excludes] - [-S|--as path-to-assembler] [-f|--as-flags options] - [-D|--dllname name] [-m|--machine machine] - [-a|--add-indirect] - [-U|--add-underscore] [--add-stdcall-underscore] - [-k|--kill-at] [-A|--add-stdcall-alias] - [-p|--ext-prefix-alias prefix] - [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork] - [-n|--nodelete] [-t|--temp-prefix prefix] - [-v|--verbose] - [-h|--help] [-V|--version] - [object-file ...] -.Ed -.Pp -.Xr dlltool -reads its inputs, which can come from the -.Op -d -and -.Op -b -options as well as object files specified on the command line. It then processes -these inputs and if the -.Op -e -option has been specified it creates a exports file. If the -.Op -l -option has been specified it creates a library file and if the -.Op -z -option has been specified it creates a def file. Any or all of the -.Op -e , -.Op -l -and -.Op -z -options can be present in one invocation of dlltool. -.Pp -When creating a DLL, along with the source for the DLL, it is necessary to -have three other files. -.Xr dlltool -can help with the creation of these files. -.Pp -The first file is a -.Pa .def -file which specifies which functions are exported from the DLL, which functions -the DLL imports, and so on. This is a text file and can be created by hand, -or -.Xr dlltool -can be used to create it using the -.Op -z -option. In this case -.Xr dlltool -will scan the object files specified on its command line looking for those -functions which have been specially marked as being exported and put entries -for them in the -.Pa .def -file it creates. -.Pp -In order to mark a function as being exported from a DLL, it needs to have -an -.Op -export:<name_of_function> -entry in the -.Li .drectve -section of the object file. This can be done in C by using the asm() operator: -.Pp -.Bd -literal -offset indent - asm (".section .drectve"); - asm (".ascii \e"-export:my_func\e""); - - int my_func (void) { ... } -.Ed -.Pp -The second file needed for DLL creation is an exports file. This file is linked -with the object files that make up the body of the DLL and it handles the -interface between the DLL and the outside world. This is a binary file and -it can be created by giving the -.Op -e -option to -.Xr dlltool -when it is creating or reading in a -.Pa .def -file. -.Pp -The third file needed for DLL creation is the library file that programs will -link with in order to access the functions in the DLL. This file can be created -by giving the -.Op -l -option to dlltool when it is creating or reading in a -.Pa .def -file. -.Pp -.Xr dlltool -builds the library file by hand, but it builds the exports file by creating -temporary files containing assembler statements and then assembling these. -The -.Op -S -command line option can be used to specify the path to the assembler that -dlltool will use, and the -.Op -f -option can be used to pass specific flags to that assembler. The -.Op -n -can be used to prevent dlltool from deleting these temporary assembler files -when it is done, and if -.Op -n -is specified twice then this will prevent dlltool from deleting the temporary -object files it used to build the library. -.Pp -Here is an example of creating a DLL from a source file -.Li dll.c -and also creating a program (from an object file called -.Li program.o ) -that uses that DLL: -.Pp -.Bd -literal -offset indent - gcc -c dll.c - dlltool -e exports.o -l dll.lib dll.o - gcc dll.o exports.o -o dll.dll - gcc program.o dll.lib -o program -.Ed -.Pp -The command line options have the following meanings: -.Pp -.Bl -tag -width Ds -.It -d Va filename -.It --input-def Va filename -Specifies the name of a -.Pa .def -file to be read in and processed. -.Pp -.It -b Va filename -.It --base-file Va filename -Specifies the name of a base file to be read in and processed. The contents -of this file will be added to the relocation section in the exports file generated -by dlltool. -.Pp -.It -e Va filename -.It --output-exp Va filename -Specifies the name of the export file to be created by dlltool. -.Pp -.It -z Va filename -.It --output-def Va filename -Specifies the name of the -.Pa .def -file to be created by dlltool. -.Pp -.It -l Va filename -.It --output-lib Va filename -Specifies the name of the library file to be created by dlltool. -.Pp -.It --export-all-symbols -Treat all global and weak defined symbols found in the input object files -as symbols to be exported. There is a small list of symbols which are not -exported by default; see the -.Op --no-default-excludes -option. You may add to the list of symbols to not export by using the -.Op --exclude-symbols -option. -.Pp -.It --no-export-all-symbols -Only export symbols explicitly listed in an input -.Pa .def -file or in -.Li .drectve -sections in the input object files. This is the default behaviour. The -.Li .drectve -sections are created by -.Li dllexport -attributes in the source code. -.Pp -.It --exclude-symbols Va list -Do not export the symbols in -.Va list . -This is a list of symbol names separated by comma or colon characters. The -symbol names should not contain a leading underscore. This is only meaningful -when -.Op --export-all-symbols -is used. -.Pp -.It --no-default-excludes -When -.Op --export-all-symbols -is used, it will by default avoid exporting certain special symbols. The current -list of symbols to avoid exporting is -.Li DllMain@12 , -.Li DllEntryPoint@0 , -.Li impure_ptr . -You may use the -.Op --no-default-excludes -option to go ahead and export these special symbols. This is only meaningful -when -.Op --export-all-symbols -is used. -.Pp -.It -S Va path -.It --as Va path -Specifies the path, including the filename, of the assembler to be used to -create the exports file. -.Pp -.It -f Va options -.It --as-flags Va options -Specifies any specific command line options to be passed to the assembler -when building the exports file. This option will work even if the -.Op -S -option is not used. This option only takes one argument, and if it occurs -more than once on the command line, then later occurrences will override earlier -occurrences. So if it is necessary to pass multiple options to the assembler -they should be enclosed in double quotes. -.Pp -.It -D Va name -.It --dll-name Va name -Specifies the name to be stored in the -.Pa .def -file as the name of the DLL when the -.Op -e -option is used. If this option is not present, then the filename given to -the -.Op -e -option will be used as the name of the DLL. -.Pp -.It -m Va machine -.It -machine Va machine -Specifies the type of machine for which the library file should be built. -.Xr dlltool -has a built in default type, depending upon how it was created, but this option -can be used to override that. This is normally only useful when creating DLLs -for an ARM processor, when the contents of the DLL are actually encode using -Thumb instructions. -.Pp -.It -a -.It --add-indirect -Specifies that when -.Xr dlltool -is creating the exports file it should add a section which allows the exported -functions to be referenced without using the import library. Whatever the -hell that means! -.Pp -.It -U -.It --add-underscore -Specifies that when -.Xr dlltool -is creating the exports file it should prepend an underscore to the names -of -.Em all -exported symbols. -.Pp -.It --add-stdcall-underscore -Specifies that when -.Xr dlltool -is creating the exports file it should prepend an underscore to the names -of exported -.Em stdcall -functions. Variable names and non-stdcall function names are not modified. -This option is useful when creating GNU-compatible import libs for third party -DLLs that were built with MS-Windows tools. -.Pp -.It -k -.It --kill-at -Specifies that when -.Xr dlltool -is creating the exports file it should not append the string -.Li @ <number> . -These numbers are called ordinal numbers and they represent another way of -accessing the function in a DLL, other than by name. -.Pp -.It -A -.It --add-stdcall-alias -Specifies that when -.Xr dlltool -is creating the exports file it should add aliases for stdcall symbols without -.Li @ <number> -in addition to the symbols with -.Li @ <number> . -.Pp -.It -p -.It --ext-prefix-alias Va prefix -Causes -.Xr dlltool -to create external aliases for all DLL imports with the specified prefix. -The aliases are created for both external and import symbols with no leading -underscore. -.Pp -.It -x -.It --no-idata4 -Specifies that when -.Xr dlltool -is creating the exports and library files it should omit the -.Li .idata4 -section. This is for compatibility with certain operating systems. -.Pp -.It -c -.It --no-idata5 -Specifies that when -.Xr dlltool -is creating the exports and library files it should omit the -.Li .idata5 -section. This is for compatibility with certain operating systems. -.Pp -.It -i -.It --interwork -Specifies that -.Xr dlltool -should mark the objects in the library file and exports file that it produces -as supporting interworking between ARM and Thumb code. -.Pp -.It -n -.It --nodelete -Makes -.Xr dlltool -preserve the temporary assembler files it used to create the exports file. -If this option is repeated then dlltool will also preserve the temporary object -files it uses to create the library file. -.Pp -.It -t Va prefix -.It --temp-prefix Va prefix -Makes -.Xr dlltool -use -.Va prefix -when constructing the names of temporary assembler and object files. By default, -the temp file prefix is generated from the pid. -.Pp -.It -v -.It --verbose -Make dlltool describe what it is doing. -.Pp -.It -h -.It --help -Displays a list of command line options and then exits. -.Pp -.It -V -.It --version -Displays dlltool's version number and then exits. -.Pp -.El -.Ss The format of the Xr dlltool Pa .def file -A -.Pa .def -file contains any number of the following commands: -.Pp -.Bl -tag -width Ds -.It Li NAME Va name Li [ , Va base Li ] -The result is going to be named -.Va name -.Li .exe . -.Pp -.It Li LIBRARY Va name Li [ , Va base Li ] -The result is going to be named -.Va name -.Li .dll . -.Pp -.It Li EXPORTS ( ( ( Va name1 Li [ = Va name2 Li ] ) | ( Va name1 Li = Va module-name Li . Va external-name Li ) ) -.It Li [ Va integer Li ] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) * -Declares -.Va name1 -as an exported symbol from the DLL, with optional ordinal number -.Va integer , -or declares -.Va name1 -as an alias (forward) of the function -.Va external-name -in the DLL -.Va module-name . -.Pp -.It Li IMPORTS ( ( Va internal-name Li = Va module-name Li . Va integer Li ) | [ Va internal-name Li = ] Va module-name Li . Va external-name Li ) ) * -Declares that -.Va external-name -or the exported function whose ordinal number is -.Va integer -is to be imported from the file -.Va module-name . -If -.Va internal-name -is specified then this is the name that the imported function will be referred -to in the body of the DLL. -.Pp -.It Li DESCRIPTION Va string -Puts -.Va string -into the output -.Pa .exp -file in the -.Li .rdata -section. -.Pp -.It Li STACKSIZE Va number-reserve Li [, Va number-commit Li ] -.It Li HEAPSIZE Va number-reserve Li [, Va number-commit Li ] -Generates -.Li --stack -or -.Li --heap -.Va number-reserve -, -.Va number-commit -in the output -.Li .drectve -section. The linker will see this and act upon it. -.Pp -.It Li CODE Va attr Li + -.It Li DATA Va attr Li + -.It Li SECTIONS ( Va section-name Va attr Li + ) * -Generates -.Li --attr -.Va section-name -.Va attr -in the output -.Li .drectve -section, where -.Va attr -is one of -.Li READ , -.Li WRITE , -.Li EXECUTE -or -.Li SHARED . -The linker will see this and act upon it. -.Pp -.El -.Sh readelf -.Bd -literal -offset indent -readelf [-a|--all] - [-h|--file-header] - [-l|--program-headers|--segments] - [-S|--section-headers|--sections] - [-g|--section-groups] - [-t|--section-details] - [-e|--headers] - [-s|--syms|--symbols] - [-n|--notes] - [-r|--relocs] - [-u|--unwind] - [-d|--dynamic] - [-V|--version-info] - [-A|--arch-specific] - [-D|--use-dynamic] - [-x <number or name>|--hex-dump=<number or name>] - [-w[liaprmfFsoR]| - --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]] - [-I|-histogram] - [-v|--version] - [-W|--wide] - [-H|--help] - elffile... -.Ed -.Pp -.Xr readelf -displays information about one or more ELF format object files. The options -control what particular information to display. -.Pp -.Va elffile -\&...are the object files to be examined. 32-bit and 64-bit ELF files are supported, -as are archives containing ELF files. -.Pp -This program performs a similar function to -.Xr objdump -but it goes into more detail and it exists independently of the bfd library, -so if there is a bug in bfd then readelf will not be affected. -.Pp -The long and short forms of options, shown here as alternatives, are equivalent. -At least one option besides -.Li -v -or -.Li -H -must be given. -.Pp -.Bl -tag -width Ds -.It -a -.It --all -Equivalent to specifying -.Op --file-header , -.Op --program-headers , -.Op --sections , -.Op --symbols , -.Op --relocs , -.Op --dynamic , -.Op --notes -and -.Op --version-info . -.Pp -.It -h -.It --file-header -Displays the information contained in the ELF header at the start of the file. -.Pp -.It -l -.It --program-headers -.It --segments -Displays the information contained in the file's segment headers, if it has -any. -.Pp -.It -S -.It --sections -.It --section-headers -Displays the information contained in the file's section headers, if it has -any. -.Pp -.It -g -.It --section-groups -Displays the information contained in the file's section groups, if it has -any. -.Pp -.It -t -.It --section-details -Displays the detailed section information. Implies -.Op -S . -.Pp -.It -s -.It --symbols -.It --syms -Displays the entries in symbol table section of the file, if it has one. -.Pp -.It -e -.It --headers -Display all the headers in the file. Equivalent to -.Op -h -l -S . -.Pp -.It -n -.It --notes -Displays the contents of the NOTE segments and/or sections, if any. -.Pp -.It -r -.It --relocs -Displays the contents of the file's relocation section, if it has one. -.Pp -.It -u -.It --unwind -Displays the contents of the file's unwind section, if it has one. Only the -unwind sections for IA64 ELF files are currently supported. -.Pp -.It -d -.It --dynamic -Displays the contents of the file's dynamic section, if it has one. -.Pp -.It -V -.It --version-info -Displays the contents of the version sections in the file, it they exist. -.Pp -.It -A -.It --arch-specific -Displays architecture-specific information in the file, if there is any. -.Pp -.It -D -.It --use-dynamic -When displaying symbols, this option makes -.Xr readelf -use the symbol table in the file's dynamic section, rather than the one in -the symbols section. -.Pp -.It -x <number or name> -.It --hex-dump=<number or name> -Displays the contents of the indicated section as a hexadecimal dump. A number -identifies a particular section by index in the section table; any other string -identifies all sections with that name in the object file. -.Pp -.It -w[liaprmfFsoR] -.It --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges] -Displays the contents of the debug sections in the file, if any are present. -If one of the optional letters or words follows the switch then only data -found in those specific sections will be dumped. -.Pp -.It -I -.It --histogram -Display a histogram of bucket list lengths when displaying the contents of -the symbol tables. -.Pp -.It -v -.It --version -Display the version number of readelf. -.Pp -.It -W -.It --wide -Don't break output lines to fit into 80 columns. By default -.Xr readelf -breaks section header and segment listing lines for 64-bit ELF files, so that -they fit into 80 columns. This option causes -.Xr readelf -to print each section header resp. each segment one a single line, which is -far more readable on terminals wider than 80 columns. -.Pp -.It -H -.It --help -Display the command line options understood by -.Xr readelf . -.Pp -.El -.Sh Common Options -The following command-line options are supported by all of the programs described -in this manual. -.Pp -.Bl -tag -width Ds -.It @ Va file -Read command-line options from -.Va file . -The options read are inserted in place of the original @ -.Va file -option. If -.Va file -does not exist, or cannot be read, then the option will be treated literally, -and not removed. -.Pp -Options in -.Va file -are separated by whitespace. A whitespace character may be included in an -option by surrounding the entire option in either single or double quotes. -Any character (including a backslash) may be included by prefixing the character -to be included with a backslash. The -.Va file -may itself contain additional @ -.Va file -options; any such options will be processed recursively. -.Pp -.It --help -Display the command-line options supported by the program. -.Pp -.It --version -Display the version number of the program. -.Pp -.El -.Sh Selecting the Target System -You can specify two aspects of the target system to the GNU binary file utilities, -each in several ways: -.Pp -.Bl -bullet -.It -the target -.Pp -.It -the architecture -.El -.Pp -In the following summaries, the lists of ways to specify values are in order -of decreasing precedence. The ways listed first override those listed later. -.Pp -The commands to list valid values only list the values for which the programs -you are running were configured. If they were configured with -.Op --enable-targets=all , -the commands list most of the available values, but a few are left out; not -all targets can be configured in at once because some of them can only be -configured -.Em native -(on hosts with the same type as the target system). -.Pp -.Ss Target Selection -A -.Em target -is an object file format. A given target may be supported for multiple architectures -(see Section -.Dq Architecture Selection ) . -A target selection may also have variations for different operating systems -or architectures. -.Pp -The command to list valid target values is -.Li objdump -i -(the first column of output contains the relevant information). -.Pp -Some sample values are: -.Li a.out-hp300bsd , -.Li ecoff-littlemips , -.Li a.out-sunos-big . -.Pp -You can also specify a target using a configuration triplet. This is the same -sort of name that is passed to -.Pa configure -to specify a target. When you use a configuration triplet as an argument, -it must be fully canonicalized. You can see the canonical version of a triplet -by running the shell script -.Pa config.sub -which is included with the sources. -.Pp -Some sample configuration triplets are: -.Li m68k-hp-bsd , -.Li mips-dec-ultrix , -.Li sparc-sun-sunos . -.Pp -.Em Xr objdump Target -.Pp -Ways to specify: -.Pp -.Bl -enum -.It -command line option: -.Op -b -or -.Op --target -.Pp -.It -environment variable -.Li GNUTARGET -.Pp -.It -deduced from the input file -.El -.Pp -.Em Xr objcopy and Xr strip Input Target -.Pp -Ways to specify: -.Pp -.Bl -enum -.It -command line options: -.Op -I -or -.Op --input-target , -or -.Op -F -or -.Op --target -.Pp -.It -environment variable -.Li GNUTARGET -.Pp -.It -deduced from the input file -.El -.Pp -.Em Xr objcopy and Xr strip Output Target -.Pp -Ways to specify: -.Pp -.Bl -enum -.It -command line options: -.Op -O -or -.Op --output-target , -or -.Op -F -or -.Op --target -.Pp -.It -the input target (see \(lq -.Xr objcopy -and -.Xr strip -Input Target\(rq above) -.Pp -.It -environment variable -.Li GNUTARGET -.Pp -.It -deduced from the input file -.El -.Pp -.Em Xr nm, Xr size, and Xr strings Target -.Pp -Ways to specify: -.Pp -.Bl -enum -.It -command line option: -.Op --target -.Pp -.It -environment variable -.Li GNUTARGET -.Pp -.It -deduced from the input file -.El -.Pp -.Ss Architecture Selection -An -.Em architecture -is a type of cpu on which an object file is to run. Its name may contain a -colon, separating the name of the processor family from the name of the particular -cpu. -.Pp -The command to list valid architecture values is -.Li objdump -i -(the second column contains the relevant information). -.Pp -Sample values: -.Li m68k:68020 , -.Li mips:3000 , -.Li sparc . -.Pp -.Em Xr objdump Architecture -.Pp -Ways to specify: -.Pp -.Bl -enum -.It -command line option: -.Op -m -or -.Op --architecture -.Pp -.It -deduced from the input file -.El -.Pp -.Em Xr objcopy, Xr nm, Xr size, Xr strings Architecture -.Pp -Ways to specify: -.Pp -.Bl -enum -.It -deduced from the input file -.El -.Pp -.Sh Reporting Bugs -Your bug reports play an essential role in making the binary utilities reliable. -.Pp -Reporting a bug may help you by bringing a solution to your problem, or it -may not. But in any case the principal function of a bug report is to help -the entire community by making the next version of the binary utilities work -better. Bug reports are your contribution to their maintenance. -.Pp -In order for a bug report to serve its purpose, you must include the information -that enables us to fix the bug. -.Pp -.Ss Have You Found a Bug? -If you are not sure whether you have found a bug, here are some guidelines: -.Pp -.Bl -bullet -.It -If a binary utility gets a fatal signal, for any input whatever, that is a -bug. Reliable utilities never crash. -.Pp -.It -If a binary utility produces an error message for valid input, that is a bug. -.Pp -.It -If you are an experienced user of binary utilities, your suggestions for improvement -are welcome in any case. -.El -.Pp -.Ss How to Report Bugs -A number of companies and individuals offer support for GNU products. If you -obtained the binary utilities from a support organization, we recommend you -contact that organization first. -.Pp -You can find contact information for many support companies and individuals -in the file -.Pa etc/SERVICE -in the GNU Emacs distribution. -.Pp -The fundamental principle of reporting bugs usefully is this: -.Sy report all the facts . -If you are not sure whether to state a fact or leave it out, state it! -.Pp -Often people omit facts because they think they know what causes the problem -and assume that some details do not matter. Thus, you might assume that the -name of a file you use in an example does not matter. Well, probably it does -not, but one cannot be sure. Perhaps the bug is a stray memory reference which -happens to fetch from the location where that pathname is stored in memory; -perhaps, if the pathname were different, the contents of that location would -fool the utility into doing the right thing despite the bug. Play it safe -and give a specific, complete example. That is the easiest thing for you to -do, and the most helpful. -.Pp -Keep in mind that the purpose of a bug report is to enable us to fix the bug -if it is new to us. Therefore, always write your bug reports on the assumption -that the bug has not been reported previously. -.Pp -Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq -This cannot help us fix a bug, so it is basically useless. We respond by asking -for enough details to enable us to investigate. You might as well expedite -matters by sending them to begin with. -.Pp -To enable us to fix the bug, you should include all these things: -.Pp -.Bl -bullet -.It -The version of the utility. Each utility announces it if you start it with -the -.Op --version -argument. -.Pp -Without this, we will not know whether there is any point in looking for the -bug in the current version of the binary utilities. -.Pp -.It -Any patches you may have applied to the source, including any patches made -to the -.Li BFD -library. -.Pp -.It -The type of machine you are using, and the operating system name and version -number. -.Pp -.It -What compiler (and its version) was used to compile the utilities---e.g. \(lq -.Li gcc-2.7 -\(rq\&. -.Pp -.It -The command arguments you gave the utility to observe the bug. To guarantee -you will not omit something important, list them all. A copy of the Makefile -(or the output from make) is sufficient. -.Pp -If we were to try to guess the arguments, we would probably guess wrong and -then we might not encounter the bug. -.Pp -.It -A complete input file, or set of input files, that will reproduce the bug. -If the utility is reading an object file or files, then it is generally most -helpful to send the actual object files. -.Pp -If the source files were produced exclusively using GNU programs (e.g., -.Xr gcc , -.Xr gas , -and/or the GNU -.Xr ld ) , -then it may be OK to send the source files rather than the object files. In -this case, be sure to say exactly what version of -.Xr gcc , -or whatever, was used to produce the object files. Also say how -.Xr gcc , -or whatever, was configured. -.Pp -.It -A description of what behavior you observe that you believe is incorrect. -For example, \(lqIt gets a fatal signal.\(rq -.Pp -Of course, if the bug is that the utility gets a fatal signal, then we will -certainly notice it. But if the bug is incorrect output, we might not notice -unless it is glaringly wrong. You might as well not give us a chance to make -a mistake. -.Pp -Even if the problem you experience is a fatal signal, you should still say -so explicitly. Suppose something strange is going on, such as your copy of -the utility is out of sync, or you have encountered a bug in the C library -on your system. (This has happened!) Your copy might crash and ours would -not. If you told us to expect a crash, then when ours fails to crash, we would -know that the bug was not happening for us. If you had not told us to expect -a crash, then we would not be able to draw any conclusion from our observations. -.Pp -.It -If you wish to suggest changes to the source, send us context diffs, as generated -by -.Xr diff -with the -.Op -u , -.Op -c , -or -.Op -p -option. Always send diffs from the old file to the new file. If you wish to -discuss something in the -.Xr ld -source, refer to it by context, not by line number. -.Pp -The line numbers in our development sources will not match those in your sources. -Your line numbers would convey no useful information to us. -.El -.Pp -Here are some things that are not necessary: -.Pp -.Bl -bullet -.It -A description of the envelope of the bug. -.Pp -Often people who encounter a bug spend a lot of time investigating which changes -to the input file will make the bug go away and which changes will not affect -it. -.Pp -This is often time consuming and not very useful, because the way we will -find the bug is by running a single example under the debugger with breakpoints, -not by pure deduction from a series of examples. We recommend that you save -your time for something else. -.Pp -Of course, if you can find a simpler example to report -.Em instead -of the original one, that is a convenience for us. Errors in the output will -be easier to spot, running under the debugger will take less time, and so -on. -.Pp -However, simplification is not vital; if you do not want to do this, report -the bug anyway and send us the entire test case you used. -.Pp -.It -A patch for the bug. -.Pp -A patch for the bug does help us if it is a good one. But do not omit the -necessary information, such as the test case, on the assumption that a patch -is all we need. We might see problems with your patch and decide to fix the -problem another way, or we might not understand it at all. -.Pp -Sometimes with programs as complicated as the binary utilities it is very -hard to construct an example that will make the program follow a certain path -through the code. If you do not send us the example, we will not be able to -construct one, so we will not be able to verify that the bug is fixed. -.Pp -And if we cannot understand what bug you are trying to fix, or why your patch -should be an improvement, we will not install it. A test case will help us -to understand. -.Pp -.It -A guess about what the bug is or what it depends on. -.Pp -Such guesses are usually wrong. Even we cannot guess right about such things -without first using the debugger to find the facts. -.El -.Pp -.Sh GNU Free Documentation License -.Bd -filled -offset indent -Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, -Fifth Floor, Boston, MA 02110-1301 USA -.Pp -Everyone is permitted to copy and distribute verbatim copies of this license -document, but changing it is not allowed. -.Ed -.Pp -.Bl -enum -.It -PREAMBLE -.Pp -The purpose of this License is to make a manual, textbook, or other written -document \(lqfree\(rq 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. -.Pp -This License is a kind of \(lqcopyleft\(rq, 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. -.Pp -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. -.Pp -.It -APPLICABILITY AND DEFINITIONS -.Pp -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 \(lqDocument\(rq, below, refers to any such manual or work. Any member -of the public is a licensee, and is addressed as \(lqyou.\(rq -.Pp -A \(lqModified Version\(rq 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. -.Pp -A \(lqSecondary Section\(rq 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. -.Pp -The \(lqInvariant Sections\(rq 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. -.Pp -The \(lqCover Texts\(rq 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. -.Pp -A \(lqTransparent\(rq 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 -\(lqTransparent\(rq is called \(lqOpaque.\(rq -.Pp -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. -.Pp -The \(lqTitle Page\(rq 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, \(lqTitle Page\(rq means the text near the most prominent -appearance of the work's title, preceding the beginning of the body of the -text. -.Pp -.It -VERBATIM COPYING -.Pp -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. -.Pp -You may also lend copies, under the same conditions stated above, and you -may publicly display copies. -.Pp -.It -COPYING IN QUANTITY -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -.It -MODIFICATIONS -.Pp -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: -.Pp -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 \(lqHistory\(rq, -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 \(lqHistory\(rq 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 \(lqHistory\(rq 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 \(lqAcknowledgements\(rq or \(lqDedications\(rq, 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 \(lqEndorsements.\(rq Such a section -may not be included in the Modified Version. N. Do not retitle any existing -section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. -.Pp -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. -.Pp -You may add a section entitled \(lqEndorsements\(rq, 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. -.Pp -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. -.Pp -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. -.Pp -.It -COMBINING DOCUMENTS -.Pp -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. -.Pp -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. -.Pp -In the combination, you must combine any sections entitled \(lqHistory\(rq in the -various original documents, forming one section entitled \(lqHistory\(rq; likewise -combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled -\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq -.Pp -.It -COLLECTIONS OF DOCUMENTS -.Pp -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. -.Pp -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. -.Pp -.It -AGGREGATION WITH INDEPENDENT WORKS -.Pp -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 \(lqaggregate\(rq, 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. -.Pp -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. -.Pp -.It -TRANSLATION -.Pp -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. -.Pp -.It -TERMINATION -.Pp -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. -.Pp -.It -FUTURE REVISIONS OF THIS LICENSE -.Pp -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/. -.Pp -Each version of the License is given a distinguishing version number. If the -Document specifies that a particular numbered version of this License \(lqor any -later version\(rq 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. -.Pp -.El -.Ss 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: -.Pp -.Bd -literal -offset indent - -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." - -.Ed -.Pp -If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead -of saying which ones are invariant. If you have no Front-Cover Texts, write -\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being -.Va list -\(rq; likewise for Back-Cover Texts. -.Pp -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. -.Pp -.Sh Binutils Index diff --git a/contrib/binutils/binutils/readelf.c b/contrib/binutils/binutils/readelf.c index 09f4062a4d9f..aafd8d4502e9 100644 --- a/contrib/binutils/binutils/readelf.c +++ b/contrib/binutils/binutils/readelf.c @@ -9159,8 +9159,6 @@ get_freebsd_note_type (unsigned e_type) return _("NT_PROCSTAT_PSSTRINGS (ps_strings data)"); case NT_PROCSTAT_AUXV: return _("NT_PROCSTAT_AUXV (auxv data)"); - case NT_X86_XSTATE: - return _("NT_X86_XSTATE (x86 XSAVE extended state)"); default: return get_note_type(e_type); } diff --git a/contrib/binutils/gas/config/tc-arm.c b/contrib/binutils/gas/config/tc-arm.c index a045cc754e40..8b470c0335e0 100644 --- a/contrib/binutils/gas/config/tc-arm.c +++ b/contrib/binutils/gas/config/tc-arm.c @@ -6079,7 +6079,7 @@ parse_operands (char *str, const unsigned char *pattern) /* Functions for operand encoding. ARM, then Thumb. */ -#define rotate_left(v, n) (v << (n % 32) | v >> ((32 - n) % 32)) +#define rotate_left(v, n) (v << n | v >> (32 - n)) /* If VAL can be encoded in the immediate field of an ARM instruction, return the encoded form. Otherwise, return FAIL. */ @@ -6789,11 +6789,7 @@ do_co_reg (void) { inst.instruction |= inst.operands[0].reg << 8; inst.instruction |= inst.operands[1].imm << 21; - /* If this is a vector we are using the APSR_nzcv syntax, encode as r15 */ - if (inst.operands[2].isvec != 0) - inst.instruction |= 15 << 12; - else - inst.instruction |= inst.operands[2].reg << 12; + inst.instruction |= inst.operands[2].reg << 12; inst.instruction |= inst.operands[3].reg << 16; inst.instruction |= inst.operands[4].reg; inst.instruction |= inst.operands[5].imm << 5; @@ -15059,7 +15055,7 @@ static const struct asm_opcode insns[] = TCE(stc, c000000, ec000000, 3, (RCP, RCN, ADDRGLDC), lstc, lstc), TC3(stcl, c400000, ec400000, 3, (RCP, RCN, ADDRGLDC), lstc, lstc), TCE(mcr, e000010, ee000010, 6, (RCP, I7b, RR, RCN, RCN, oI7b), co_reg, co_reg), - TCE(mrc, e100010, ee100010, 6, (RCP, I7b, APSR_RR, RCN, RCN, oI7b), co_reg, co_reg), + TCE(mrc, e100010, ee100010, 6, (RCP, I7b, RR, RCN, RCN, oI7b), co_reg, co_reg), #undef ARM_VARIANT #define ARM_VARIANT &arm_ext_v2s /* ARM 3 - swp instructions. */ @@ -15118,7 +15114,7 @@ static const struct asm_opcode insns[] = TUF(stc2l, c400000, fc400000, 3, (RCP, RCN, ADDRGLDC), lstc, lstc), TUF(cdp2, e000000, fe000000, 6, (RCP, I15b, RCN, RCN, RCN, oI7b), cdp, cdp), TUF(mcr2, e000010, fe000010, 6, (RCP, I7b, RR, RCN, RCN, oI7b), co_reg, co_reg), - TUF(mrc2, e100010, fe100010, 6, (RCP, I7b, APSR_RR, RCN, RCN, oI7b), co_reg, co_reg), + TUF(mrc2, e100010, fe100010, 6, (RCP, I7b, RR, RCN, RCN, oI7b), co_reg, co_reg), #undef ARM_VARIANT #define ARM_VARIANT &arm_ext_v5exp /* ARM Architecture 5TExP. */ diff --git a/contrib/binutils/gas/config/tc-ppc.c b/contrib/binutils/gas/config/tc-ppc.c index 493a35315e6b..1ecd99faea5d 100644 --- a/contrib/binutils/gas/config/tc-ppc.c +++ b/contrib/binutils/gas/config/tc-ppc.c @@ -1548,7 +1548,7 @@ ppc_insert_operand (unsigned long insn, errmsg = NULL; insn = (*operand->insert) (insn, (long) val, ppc_cpu, &errmsg); if (errmsg != (const char *) NULL) - as_bad_where (file, line, "%s", errmsg); + as_bad_where (file, line, errmsg); } else insn |= ((long) val & operand->bitm) << operand->shift; @@ -2279,7 +2279,7 @@ md_assemble (char *str) { insn = (*operand->insert) (insn, 0L, ppc_cpu, &errmsg); if (errmsg != (const char *) NULL) - as_bad ("%s", errmsg); + as_bad (errmsg); continue; } @@ -2292,7 +2292,7 @@ md_assemble (char *str) { insn = (*operand->insert) (insn, 0L, ppc_cpu, &errmsg); if (errmsg != (const char *) NULL) - as_bad ("%s", errmsg); + as_bad (errmsg); } if ((operand->flags & PPC_OPERAND_NEXT) != 0) next_opindex = *opindex_ptr + 1; @@ -2509,156 +2509,108 @@ md_assemble (char *str) (char *) NULL, 0); } #ifdef OBJ_ELF - else + else if ((reloc = ppc_elf_suffix (&str, &ex)) != BFD_RELOC_UNUSED) { - if (ex.X_op == O_symbol && str[0] == '(') + /* Some TLS tweaks. */ + switch (reloc) { - const char *sym_name = S_GET_NAME (ex.X_add_symbol); - if (sym_name[0] == '.') - ++sym_name; - - if (strcasecmp (sym_name, "__tls_get_addr") == 0) - { - expressionS tls_exp; - - hold = input_line_pointer; - input_line_pointer = str + 1; - expression (&tls_exp); - if (tls_exp.X_op == O_symbol) - { - reloc = BFD_RELOC_UNUSED; - if (strncasecmp (input_line_pointer, "@tlsgd)", 7) == 0) - { - reloc = BFD_RELOC_PPC_TLSGD; - input_line_pointer += 7; - } - else if (strncasecmp (input_line_pointer, "@tlsld)", 7) == 0) - { - reloc = BFD_RELOC_PPC_TLSLD; - input_line_pointer += 7; - } - if (reloc != BFD_RELOC_UNUSED) - { - SKIP_WHITESPACE (); - str = input_line_pointer; - - if (fc >= MAX_INSN_FIXUPS) - as_fatal (_("too many fixups")); - fixups[fc].exp = tls_exp; - fixups[fc].opindex = *opindex_ptr; - fixups[fc].reloc = reloc; - ++fc; - } - } - input_line_pointer = hold; - } + default: + break; + case BFD_RELOC_PPC_TLS: + insn = ppc_insert_operand (insn, operand, ppc_obj64 ? 13 : 2, + (char *) NULL, 0); + break; + /* We'll only use the 32 (or 64) bit form of these relocations + in constants. Instructions get the 16 bit form. */ + case BFD_RELOC_PPC_DTPREL: + reloc = BFD_RELOC_PPC_DTPREL16; + break; + case BFD_RELOC_PPC_TPREL: + reloc = BFD_RELOC_PPC_TPREL16; + break; } - if ((reloc = ppc_elf_suffix (&str, &ex)) != BFD_RELOC_UNUSED) + /* For the absolute forms of branches, convert the PC + relative form back into the absolute. */ + if ((operand->flags & PPC_OPERAND_ABSOLUTE) != 0) { - /* Some TLS tweaks. */ switch (reloc) { - default: + case BFD_RELOC_PPC_B26: + reloc = BFD_RELOC_PPC_BA26; break; - - case BFD_RELOC_PPC_TLS: - insn = ppc_insert_operand (insn, operand, ppc_obj64 ? 13 : 2, - (char *) NULL, 0); + case BFD_RELOC_PPC_B16: + reloc = BFD_RELOC_PPC_BA16; break; - - /* We'll only use the 32 (or 64) bit form of these relocations - in constants. Instructions get the 16 bit form. */ - case BFD_RELOC_PPC_DTPREL: - reloc = BFD_RELOC_PPC_DTPREL16; + case BFD_RELOC_PPC_B16_BRTAKEN: + reloc = BFD_RELOC_PPC_BA16_BRTAKEN; break; - case BFD_RELOC_PPC_TPREL: - reloc = BFD_RELOC_PPC_TPREL16; + case BFD_RELOC_PPC_B16_BRNTAKEN: + reloc = BFD_RELOC_PPC_BA16_BRNTAKEN; + break; + default: break; } + } - /* For the absolute forms of branches, convert the PC - relative form back into the absolute. */ - if ((operand->flags & PPC_OPERAND_ABSOLUTE) != 0) - { - switch (reloc) - { - case BFD_RELOC_PPC_B26: - reloc = BFD_RELOC_PPC_BA26; - break; - case BFD_RELOC_PPC_B16: - reloc = BFD_RELOC_PPC_BA16; - break; - case BFD_RELOC_PPC_B16_BRTAKEN: - reloc = BFD_RELOC_PPC_BA16_BRTAKEN; - break; - case BFD_RELOC_PPC_B16_BRNTAKEN: - reloc = BFD_RELOC_PPC_BA16_BRNTAKEN; - break; - default: - break; - } - } - - if (ppc_obj64 - && (operand->flags & (PPC_OPERAND_DS | PPC_OPERAND_DQ)) != 0) + if (ppc_obj64 + && (operand->flags & (PPC_OPERAND_DS | PPC_OPERAND_DQ)) != 0) + { + switch (reloc) { - switch (reloc) - { - case BFD_RELOC_16: - reloc = BFD_RELOC_PPC64_ADDR16_DS; - break; - case BFD_RELOC_LO16: - reloc = BFD_RELOC_PPC64_ADDR16_LO_DS; - break; - case BFD_RELOC_16_GOTOFF: - reloc = BFD_RELOC_PPC64_GOT16_DS; - break; - case BFD_RELOC_LO16_GOTOFF: - reloc = BFD_RELOC_PPC64_GOT16_LO_DS; - break; - case BFD_RELOC_LO16_PLTOFF: - reloc = BFD_RELOC_PPC64_PLT16_LO_DS; - break; - case BFD_RELOC_16_BASEREL: - reloc = BFD_RELOC_PPC64_SECTOFF_DS; - break; - case BFD_RELOC_LO16_BASEREL: - reloc = BFD_RELOC_PPC64_SECTOFF_LO_DS; - break; - case BFD_RELOC_PPC_TOC16: - reloc = BFD_RELOC_PPC64_TOC16_DS; - break; - case BFD_RELOC_PPC64_TOC16_LO: - reloc = BFD_RELOC_PPC64_TOC16_LO_DS; - break; - case BFD_RELOC_PPC64_PLTGOT16: - reloc = BFD_RELOC_PPC64_PLTGOT16_DS; - break; - case BFD_RELOC_PPC64_PLTGOT16_LO: - reloc = BFD_RELOC_PPC64_PLTGOT16_LO_DS; - break; - case BFD_RELOC_PPC_DTPREL16: - reloc = BFD_RELOC_PPC64_DTPREL16_DS; - break; - case BFD_RELOC_PPC_DTPREL16_LO: - reloc = BFD_RELOC_PPC64_DTPREL16_LO_DS; - break; - case BFD_RELOC_PPC_TPREL16: - reloc = BFD_RELOC_PPC64_TPREL16_DS; - break; - case BFD_RELOC_PPC_TPREL16_LO: - reloc = BFD_RELOC_PPC64_TPREL16_LO_DS; - break; - case BFD_RELOC_PPC_GOT_DTPREL16: - case BFD_RELOC_PPC_GOT_DTPREL16_LO: - case BFD_RELOC_PPC_GOT_TPREL16: - case BFD_RELOC_PPC_GOT_TPREL16_LO: - break; - default: - as_bad (_("unsupported relocation for DS offset field")); - break; - } + case BFD_RELOC_16: + reloc = BFD_RELOC_PPC64_ADDR16_DS; + break; + case BFD_RELOC_LO16: + reloc = BFD_RELOC_PPC64_ADDR16_LO_DS; + break; + case BFD_RELOC_16_GOTOFF: + reloc = BFD_RELOC_PPC64_GOT16_DS; + break; + case BFD_RELOC_LO16_GOTOFF: + reloc = BFD_RELOC_PPC64_GOT16_LO_DS; + break; + case BFD_RELOC_LO16_PLTOFF: + reloc = BFD_RELOC_PPC64_PLT16_LO_DS; + break; + case BFD_RELOC_16_BASEREL: + reloc = BFD_RELOC_PPC64_SECTOFF_DS; + break; + case BFD_RELOC_LO16_BASEREL: + reloc = BFD_RELOC_PPC64_SECTOFF_LO_DS; + break; + case BFD_RELOC_PPC_TOC16: + reloc = BFD_RELOC_PPC64_TOC16_DS; + break; + case BFD_RELOC_PPC64_TOC16_LO: + reloc = BFD_RELOC_PPC64_TOC16_LO_DS; + break; + case BFD_RELOC_PPC64_PLTGOT16: + reloc = BFD_RELOC_PPC64_PLTGOT16_DS; + break; + case BFD_RELOC_PPC64_PLTGOT16_LO: + reloc = BFD_RELOC_PPC64_PLTGOT16_LO_DS; + break; + case BFD_RELOC_PPC_DTPREL16: + reloc = BFD_RELOC_PPC64_DTPREL16_DS; + break; + case BFD_RELOC_PPC_DTPREL16_LO: + reloc = BFD_RELOC_PPC64_DTPREL16_LO_DS; + break; + case BFD_RELOC_PPC_TPREL16: + reloc = BFD_RELOC_PPC64_TPREL16_DS; + break; + case BFD_RELOC_PPC_TPREL16_LO: + reloc = BFD_RELOC_PPC64_TPREL16_LO_DS; + break; + case BFD_RELOC_PPC_GOT_DTPREL16: + case BFD_RELOC_PPC_GOT_DTPREL16_LO: + case BFD_RELOC_PPC_GOT_TPREL16: + case BFD_RELOC_PPC_GOT_TPREL16_LO: + break; + default: + as_bad (_("unsupported relocation for DS offset field")); + break; } } @@ -2666,11 +2618,12 @@ md_assemble (char *str) if (fc >= MAX_INSN_FIXUPS) as_fatal (_("too many fixups")); fixups[fc].exp = ex; - fixups[fc].opindex = *opindex_ptr; + fixups[fc].opindex = 0; fixups[fc].reloc = reloc; ++fc; } -#else /* OBJ_ELF */ +#endif /* OBJ_ELF */ + else { /* We need to generate a fixup for this expression. */ @@ -2681,7 +2634,6 @@ md_assemble (char *str) fixups[fc].reloc = BFD_RELOC_UNUSED; ++fc; } -#endif /* OBJ_ELF */ if (need_paren) { @@ -5956,8 +5908,6 @@ md_apply_fix (fixS *fixP, valueT *valP, segT seg ATTRIBUTE_UNUSED) break; case BFD_RELOC_PPC_TLS: - case BFD_RELOC_PPC_TLSLD: - case BFD_RELOC_PPC_TLSGD: break; case BFD_RELOC_PPC_DTPMOD: diff --git a/contrib/binutils/gas/doc/as.7 b/contrib/binutils/gas/doc/as.7 deleted file mode 100644 index 4d335576d060..000000000000 --- a/contrib/binutils/gas/doc/as.7 +++ /dev/null @@ -1,8368 +0,0 @@ -.Dd 2015-03-02 -.Dt AS 7 -.Os -.Sh NAME -.Nm as -.Nd Using as (machine specific) -.Sh Using as -This file is a user guide to the GNU assembler -.Xr as -version "2.17.50 [FreeBSD] 2007-07-03". This version of the file describes -.Xr as -configured to generate code for machine specific architectures. -.Pp -This document is distributed under the terms of the GNU Free Documentation -License. A copy of the license is included in the section entitled \(lqGNU Free -Documentation License\(rq. -.Pp -.Sh Overview -Here is a brief summary of how to invoke -.Xr as . -For details, see Invoking,,Command-Line Options. -.Pp -.Bd -literal -offset indent -as [-a[cdhlns][=file]] [--alternate] [-D] - [--defsym sym=val] [-f] [-g] [--gstabs] - [--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J] - [-K] [-L] [--listing-lhs-width=NUM] - [--listing-lhs-width2=NUM] [--listing-rhs-width=NUM] - [--listing-cont-lines=NUM] [--keep-locals] [-o - objfile] [-R] [--reduce-memory-overheads] [--statistics] - [-v] [-version] [--version] [-W] [--warn] - [--fatal-warnings] [-w] [-x] [-Z] [@FILE] - [--target-help] [target-options] - [--|files ...] - -Target ARM options: - [-mcpu=processor[+extension...]] - [-march=architecture[+extension...]] - [-mfpu=floating-point-format] - [-mfloat-abi=abi] - [-meabi=ver] - [-mthumb] - [-EB|-EL] - [-mapcs-32|-mapcs-26|-mapcs-float| - -mapcs-reentrant] - [-mthumb-interwork] [-k] - - -Target i386 options: - [--32|--64] [-n] - [-march=CPU] [-mtune=CPU] - - -Target IA-64 options: - [-mconstant-gp|-mauto-pic] - [-milp32|-milp64|-mlp64|-mp64] - [-mle|mbe] - [-mtune=itanium1|-mtune=itanium2] - [-munwind-check=warning|-munwind-check=error] - [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] - [-x|-xexplicit] [-xauto] [-xdebug] - - -Target MIPS options: - [-nocpp] [-EL] [-EB] [-O[optimization level]] - [-g[debug level]] [-G num] [-KPIC] [-call_shared] - [-non_shared] [-xgot [-mvxworks-pic] - [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] - [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] - [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] - [-mips64] [-mips64r2] - [-construct-floats] [-no-construct-floats] - [-trap] [-no-break] [-break] [-no-trap] - [-mfix7000] [-mno-fix7000] - [-mips16] [-no-mips16] - [-msmartmips] [-mno-smartmips] - [-mips3d] [-no-mips3d] - [-mdmx] [-no-mdmx] - [-mdsp] [-mno-dsp] - [-mdspr2] [-mno-dspr2] - [-mmt] [-mno-mt] - [-mdebug] [-no-mdebug] - [-mpdr] [-mno-pdr] - - -Target PowerPC options: - [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| - -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| - -mbooke32|-mbooke64] - [-mcom|-many|-maltivec] [-memb] - [-mregnames|-mno-regnames] - [-mrelocatable|-mrelocatable-lib] - [-mlittle|-mlittle-endian|-mbig|-mbig-endian] - [-msolaris|-mno-solaris] - - -Target SPARC options: - [-Av6|-Av7|-Av8|-Asparclet|-Asparclite - -Av8plus|-Av8plusa|-Av9|-Av9a] - [-xarch=v8plus|-xarch=v8plusa] [-bump] - [-32|-64] - - - -.Ed -.Pp -.Bl -tag -width Ds -.It @ Va file -Read command-line options from -.Va file . -The options read are inserted in place of the original @ -.Va file -option. If -.Va file -does not exist, or cannot be read, then the option will be treated literally, -and not removed. -.Pp -Options in -.Va file -are separated by whitespace. A whitespace character may be included in an -option by surrounding the entire option in either single or double quotes. -Any character (including a backslash) may be included by prefixing the character -to be included with a backslash. The -.Va file -may itself contain additional @ -.Va file -options; any such options will be processed recursively. -.Pp -.It -a[cdhlmns] -Turn on listings, in any of a variety of ways: -.Pp -.Bl -tag -width Ds -.It -ac -omit false conditionals -.Pp -.It -ad -omit debugging directives -.Pp -.It -ah -include high-level source -.Pp -.It -al -include assembly -.Pp -.It -am -include macro expansions -.Pp -.It -an -omit forms processing -.Pp -.It -as -include symbols -.Pp -.It =file -set the name of the listing file -.El -.Pp -You may combine these options; for example, use -.Li -aln -for assembly listing without forms processing. The -.Li =file -option, if used, must be the last one. By itself, -.Li -a -defaults to -.Li -ahls . -.Pp -.It --alternate -Begin in alternate macro mode.See Section -.Dq Altmacro . -.Pp -.It -D -Ignored. This option is accepted for script compatibility with calls to other -assemblers. -.Pp -.It --defsym Va sym= Va value -Define the symbol -.Va sym -to be -.Va value -before assembling the input file. -.Va value -must be an integer constant. As in C, a leading -.Li 0x -indicates a hexadecimal value, and a leading -.Li 0 -indicates an octal value. The value of the symbol can be overridden inside -a source file via the use of a -.Li .set -pseudo-op. -.Pp -.It -f -\(lqfast\(rq---skip whitespace and comment preprocessing (assume source is compiler -output). -.Pp -.It -g -.It --gen-debug -Generate debugging information for each assembler source line using whichever -debug format is preferred by the target. This currently means either STABS, -ECOFF or DWARF2. -.Pp -.It --gstabs -Generate stabs debugging information for each assembler line. This may help -debugging assembler code, if the debugger can handle it. -.Pp -.It --gstabs+ -Generate stabs debugging information for each assembler line, with GNU extensions -that probably only gdb can handle, and that could make other debuggers crash -or refuse to read your program. This may help debugging assembler code. Currently -the only GNU extension is the location of the current working directory at -assembling time. -.Pp -.It --gdwarf-2 -Generate DWARF2 debugging information for each assembler line. This may help -debugging assembler code, if the debugger can handle it. Note---this option -is only supported by some targets, not all of them. -.Pp -.It --help -Print a summary of the command line options and exit. -.Pp -.It --target-help -Print a summary of all target specific options and exit. -.Pp -.It -I Va dir -Add directory -.Va dir -to the search list for -.Li .include -directives. -.Pp -.It -J -Don't warn about signed overflow. -.Pp -.It -K -This option is accepted but has no effect on the machine specific family. -.Pp -.It -L -.It --keep-locals -Keep (in the symbol table) local symbols. These symbols start with system-specific -local label prefixes, typically -.Li .L -for ELF systems or -.Li L -for traditional a.out systems.See Section -.Dq Symbol Names . -.Pp -.It --listing-lhs-width= Va number -Set the maximum width, in words, of the output data column for an assembler -listing to -.Va number . -.Pp -.It --listing-lhs-width2= Va number -Set the maximum width, in words, of the output data column for continuation -lines in an assembler listing to -.Va number . -.Pp -.It --listing-rhs-width= Va number -Set the maximum width of an input source line, as displayed in a listing, -to -.Va number -bytes. -.Pp -.It --listing-cont-lines= Va number -Set the maximum number of lines printed in a listing for a single line of -input to -.Va number -+ 1. -.Pp -.It -o Va objfile -Name the object-file output from -.Xr as -.Va objfile . -.Pp -.It -R -Fold the data section into the text section. -.Pp -Set the default size of GAS's hash tables to a prime number close to -.Va number . -Increasing this value can reduce the length of time it takes the assembler -to perform its tasks, at the expense of increasing the assembler's memory -requirements. Similarly reducing this value can reduce the memory requirements -at the expense of speed. -.Pp -.It --reduce-memory-overheads -This option reduces GAS's memory requirements, at the expense of making the -assembly processes slower. Currently this switch is a synonym for -.Li --hash-size=4051 , -but in the future it may have other effects as well. -.Pp -.It --statistics -Print the maximum space (in bytes) and total time (in seconds) used by assembly. -.Pp -.It --strip-local-absolute -Remove local absolute symbols from the outgoing symbol table. -.Pp -.It -v -.It -version -Print the -.Xr as -version. -.Pp -.It --version -Print the -.Xr as -version and exit. -.Pp -.It -W -.It --no-warn -Suppress warning messages. -.Pp -.It --fatal-warnings -Treat warnings as errors. -.Pp -.It --warn -Don't suppress warning messages or treat them as errors. -.Pp -.It -w -Ignored. -.Pp -.It -x -Ignored. -.Pp -.It -Z -Generate an object file even after errors. -.Pp -.It -- | Va files ... -Standard input, or source files to assemble. -.Pp -.El -The following options are available when as is configured for the ARM processor -family. -.Pp -.Bl -tag -width Ds -.It -mcpu= Va processor[+ Va extension...] -Specify which ARM processor variant is the target. -.It -march= Va architecture[+ Va extension...] -Specify which ARM architecture variant is used by the target. -.It -mfpu= Va floating-point-format -Select which Floating Point architecture is the target. -.It -mfloat-abi= Va abi -Select which floating point ABI is in use. -.It -mthumb -Enable Thumb only instruction decoding. -.It -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant -Select which procedure calling convention is in use. -.It -EB | -EL -Select either big-endian (-EB) or little-endian (-EL) output. -.It -mthumb-interwork -Specify that the code has been generated with interworking between Thumb and -ARM code in mind. -.It -k -Specify that PIC code has been generated. -.El -.Pp -The following options are available when -.Xr as -is configured for the SPARC architecture: -.Pp -.Bl -tag -width Ds -.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite -.It -Av8plus | -Av8plusa | -Av9 | -Av9a -Explicitly select a variant of the SPARC architecture. -.Pp -.Li -Av8plus -and -.Li -Av8plusa -select a 32 bit environment. -.Li -Av9 -and -.Li -Av9a -select a 64 bit environment. -.Pp -.Li -Av8plusa -and -.Li -Av9a -enable the SPARC V9 instruction set with UltraSPARC extensions. -.Pp -.It -xarch=v8plus | -xarch=v8plusa -For compatibility with the Solaris v9 assembler. These options are equivalent -to -Av8plus and -Av8plusa, respectively. -.Pp -.It -bump -Warn when the assembler switches to another architecture. -.El -.Pp -The following options are available when as is configured for a mips processor. -.Pp -.Bl -tag -width Ds -.It -G Va num -This option sets the largest size of an object that can be referenced implicitly -with the -.Li gp -register. It is only accepted for targets that use ECOFF format, such as a -DECstation running Ultrix. The default value is 8. -.Pp -.It -EB -Generate \(lqbig endian\(rq format output. -.Pp -.It -EL -Generate \(lqlittle endian\(rq format output. -.Pp -.It -mips1 -.It -mips2 -.It -mips3 -.It -mips4 -.It -mips5 -.It -mips32 -.It -mips32r2 -.It -mips64 -.It -mips64r2 -Generate code for a particular mips Instruction Set Architecture level. -.Li -mips1 -is an alias for -.Li -march=r3000 , -.Li -mips2 -is an alias for -.Li -march=r6000 , -.Li -mips3 -is an alias for -.Li -march=r4000 -and -.Li -mips4 -is an alias for -.Li -march=r8000 . -.Li -mips5 , -.Li -mips32 , -.Li -mips32r2 , -.Li -mips64 , -and -.Li -mips64r2 -correspond to generic -.Li MIPS V , -.Li MIPS32 , -.Li MIPS32 Release 2 , -.Li MIPS64 , -and -.Li MIPS64 Release 2 -ISA processors, respectively. -.Pp -.It -march= Va CPU -Generate code for a particular mips cpu. -.Pp -.It -mtune= Va cpu -Schedule and tune for a particular mips cpu. -.Pp -.It -mfix7000 -.It -mno-fix7000 -Cause nops to be inserted if the read of the destination register of an mfhi -or mflo instruction occurs in the following two instructions. -.Pp -.It -mdebug -.It -no-mdebug -Cause stabs-style debugging output to go into an ECOFF-style .mdebug section -instead of the standard ELF .stabs sections. -.Pp -.It -mpdr -.It -mno-pdr -Control generation of -.Li .pdr -sections. -.Pp -.It -mgp32 -.It -mfp32 -The register sizes are normally inferred from the ISA and ABI, but these flags -force a certain group of registers to be treated as 32 bits wide at all times. -.Li -mgp32 -controls the size of general-purpose registers and -.Li -mfp32 -controls the size of floating-point registers. -.Pp -.It -mips16 -.It -no-mips16 -Generate code for the MIPS 16 processor. This is equivalent to putting -.Li .set mips16 -at the start of the assembly file. -.Li -no-mips16 -turns off this option. -.Pp -.It -msmartmips -.It -mno-smartmips -Enables the SmartMIPS extension to the MIPS32 instruction set. This is equivalent -to putting -.Li .set smartmips -at the start of the assembly file. -.Li -mno-smartmips -turns off this option. -.Pp -.It -mips3d -.It -no-mips3d -Generate code for the MIPS-3D Application Specific Extension. This tells the -assembler to accept MIPS-3D instructions. -.Li -no-mips3d -turns off this option. -.Pp -.It -mdmx -.It -no-mdmx -Generate code for the MDMX Application Specific Extension. This tells the -assembler to accept MDMX instructions. -.Li -no-mdmx -turns off this option. -.Pp -.It -mdsp -.It -mno-dsp -Generate code for the DSP Release 1 Application Specific Extension. This tells -the assembler to accept DSP Release 1 instructions. -.Li -mno-dsp -turns off this option. -.Pp -.It -mdspr2 -.It -mno-dspr2 -Generate code for the DSP Release 2 Application Specific Extension. This option -implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. -.Li -mno-dspr2 -turns off this option. -.Pp -.It -mmt -.It -mno-mt -Generate code for the MT Application Specific Extension. This tells the assembler -to accept MT instructions. -.Li -mno-mt -turns off this option. -.Pp -.It --construct-floats -.It --no-construct-floats -The -.Li --no-construct-floats -option disables the construction of double width floating point constants -by loading the two halves of the value into the two single width floating -point registers that make up the double width register. By default -.Li --construct-floats -is selected, allowing construction of these floating point constants. -.Pp -.It --emulation= Va name -This option causes -.Xr as -to emulate -.Xr as -configured for some other target, in all respects, including output format -(choosing between ELF and ECOFF only), handling of pseudo-opcodes which may -generate debugging information or store symbol table information, and default -endianness. The available configuration names are: -.Li mipsecoff , -.Li mipself , -.Li mipslecoff , -.Li mipsbecoff , -.Li mipslelf , -.Li mipsbelf . -The first two do not alter the default endianness from that of the primary -target for which the assembler was configured; the others change the default -to little- or big-endian as indicated by the -.Li b -or -.Li l -in the name. Using -.Li -EB -or -.Li -EL -will override the endianness selection in any case. -.Pp -This option is currently supported only when the primary target -.Xr as -is configured for is a mips ELF or ECOFF target. Furthermore, the primary -target or others specified with -.Li --enable-targets=... -at configuration time must include support for the other format, if both are -to be available. For example, the Irix 5 configuration includes support for -both. -.Pp -Eventually, this option will support more configurations, with more fine-grained -control over the assembler's behavior, and will be supported for more processors. -.Pp -.It -nocpp -.Xr as -ignores this option. It is accepted for compatibility with the native tools. -.Pp -.It --trap -.It --no-trap -.It --break -.It --no-break -Control how to deal with multiplication overflow and division by zero. -.Li --trap -or -.Li --no-break -(which are synonyms) take a trap exception (and only work for Instruction -Set Architecture level 2 and higher); -.Li --break -or -.Li --no-trap -(also synonyms, and the default) take a break exception. -.Pp -.It -n -When this option is used, -.Xr as -will issue a warning every time it generates a nop instruction from a macro. -.El -.Pp -.Ss Structure of this Manual -This manual is intended to describe what you need to know to use GNU -.Xr as . -We cover the syntax expected in source files, including notation for symbols, -constants, and expressions; the directives that -.Xr as -understands; and of course how to invoke -.Xr as . -.Pp -We also cover special features in the machine specific configuration of -.Xr as , -including assembler directives. -.Pp -On the other hand, this manual is -.Em not -intended as an introduction to programming in assembly language---let alone -programming in general! In a similar vein, we make no attempt to introduce -the machine architecture; we do -.Em not -describe the instruction set, standard mnemonics, registers or addressing -modes that are standard to a particular architecture. -.Pp -.Ss The GNU Assembler -GNU -.Xr as -is really a family of assemblers. This manual describes -.Xr as , -a member of that family which is configured for the machine specific architectures. -If you use (or have used) the GNU assembler on one architecture, you should -find a fairly similar environment when you use it on another architecture. -Each version has much in common with the others, including object file formats, -most assembler directives (often called -.Em pseudo-ops ) -and assembler syntax. -.Pp -.Xr as -is primarily intended to assemble the output of the GNU C compiler -.Li gcc -for use by the linker -.Li ld . -Nevertheless, we've tried to make -.Xr as -assemble correctly everything that other assemblers for the same machine would -assemble. -.Pp -Unlike older assemblers, -.Xr as -is designed to assemble a source program in one pass of the source file. This -has a subtle impact on the -.Li .org -directive (see Section -.Dq Org ) . -.Pp -.Ss Object File Formats -The GNU assembler can be configured to produce several alternative object -file formats. For the most part, this does not affect how you write assembly -language programs; but directives for debugging symbols are typically different -in different file formats.See Section -.Dq Symbol Attributes . -For the machine specific target, -.Xr as -is configured to produce ELF format object files. -.Pp -.Ss Command Line -After the program name -.Xr as , -the command line may contain options and file names. Options may appear in -any order, and may be before, after, or between file names. The order of file -names is significant. -.Pp -.Pa -- -(two hyphens) by itself names the standard input file explicitly, as one of -the files for -.Xr as -to assemble. -.Pp -Except for -.Li -- -any command line argument that begins with a hyphen ( -.Li - ) -is an option. Each option changes the behavior of -.Xr as . -No option changes the way another option works. An option is a -.Li - -followed by one or more letters; the case of the letter is important. All -options are optional. -.Pp -Some options expect exactly one file name to follow them. The file name may -either immediately follow the option's letter (compatible with older assemblers) -or it may be the next command argument (GNU standard). These two command lines -are equivalent: -.Pp -.Bd -literal -offset indent -as -o my-object-file.o mumble.s -as -omy-object-file.o mumble.s -.Ed -.Pp -.Ss Input Files -We use the phrase -.Em source program , -abbreviated -.Em source , -to describe the program input to one run of -.Xr as . -The program may be in one or more files; how the source is partitioned into -files doesn't change the meaning of the source. -.Pp -The source program is a concatenation of the text in all the files, in the -order specified. -.Pp -Each time you run -.Xr as -it assembles exactly one source program. The source program is made up of -one or more files. (The standard input is also a file.) -.Pp -You give -.Xr as -a command line that has zero or more input file names. The input files are -read (from left file name to right). A command line argument (in any position) -that has no special meaning is taken to be an input file name. -.Pp -If you give -.Xr as -no file names it attempts to read one input file from the -.Xr as -standard input, which is normally your terminal. You may have to type ctl-D -to tell -.Xr as -there is no more program to assemble. -.Pp -Use -.Li -- -if you need to explicitly name the standard input file in your command line. -.Pp -If the source is empty, -.Xr as -produces a small, empty object file. -.Pp -.Em Filenames and Line-numbers -.Pp -There are two ways of locating a line in the input file (or files) and either -may be used in reporting error messages. One way refers to a line number in -a physical file; the other refers to a line number in a \(lqlogical\(rq file.See Section -.Dq Errors . -.Pp -.Em Physical files -are those files named in the command line given to -.Xr as . -.Pp -.Em Logical files -are simply names declared explicitly by assembler directives; they bear no -relation to physical files. Logical file names help error messages reflect -the original source file, when -.Xr as -source is itself synthesized from other files. -.Xr as -understands the -.Li # -directives emitted by the -.Li gcc -preprocessor. See also File,, -.Li .file -\&. -.Pp -.Ss Output (Object) File -Every time you run -.Xr as -it produces an output file, which is your assembly language program translated -into numbers. This file is the object file. Its default name is -.Li a.out . -You can give it another name by using the -.Op -o -option. Conventionally, object file names end with -.Pa .o . -The default name is used for historical reasons: older assemblers were capable -of assembling self-contained programs directly into a runnable program. (For -some formats, this isn't currently possible, but it can be done for the -.Li a.out -format.) -.Pp -The object file is meant for input to the linker -.Li ld . -It contains assembled program code, information to help -.Li ld -integrate the assembled program into a runnable file, and (optionally) symbolic -information for the debugger. -.Pp -.Ss Error and Warning Messages -.Xr as -may write warnings and error messages to the standard error file (usually -your terminal). This should not happen when a compiler runs -.Xr as -automatically. Warnings report an assumption made so that -.Xr as -could keep assembling a flawed program; errors report a grave problem that -stops the assembly. -.Pp -Warning messages have the format -.Pp -.Bd -literal -offset indent -file_name:NNN:Warning Message Text -.Ed -.Pp -(where -.Sy NNN -is a line number). If a logical file name has been given (see Section -.Dq File ) -it is used for the filename, otherwise the name of the current input file -is used. If a logical line number was given then it is used to calculate the -number printed, otherwise the actual line in the current source file is printed. -The message text is intended to be self explanatory (in the grand Unix tradition). -.Pp -Error messages have the format -.Bd -literal -offset indent -file_name:NNN:FATAL:Error Message Text -.Ed -The file name and line number are derived as for warning messages. The actual -message text may be rather less explanatory because many of them aren't supposed -to happen. -.Pp -.Sh Command-Line Options -This chapter describes command-line options available in -.Em all -versions of the GNU assembler; see Machine Dependencies, for options specific -to the machine specific target. -.Pp -If you are invoking -.Xr as -via the GNU C compiler, you can use the -.Li -Wa -option to pass arguments through to the assembler. The assembler arguments -must be separated from each other (and the -.Li -Wa ) -by commas. For example: -.Pp -.Bd -literal -offset indent -gcc -c -g -O -Wa,-alh,-L file.c -.Ed -.Pp -This passes two options to the assembler: -.Li -alh -(emit a listing to standard output with high-level and assembly source) and -.Li -L -(retain local symbols in the symbol table). -.Pp -Usually you do not need to use this -.Li -Wa -mechanism, since many compiler command-line options are automatically passed -to the assembler by the compiler. (You can call the GNU compiler driver with -the -.Li -v -option to see precisely what options it passes to each compilation pass, including -the assembler.) -.Pp -.Ss Enable Listings: Op -a[cdhlns] -These options enable listing output from the assembler. By itself, -.Li -a -requests high-level, assembly, and symbols listing. You can use other letters -to select specific options for the list: -.Li -ah -requests a high-level language listing, -.Li -al -requests an output-program assembly listing, and -.Li -as -requests a symbol table listing. High-level listings require that a compiler -debugging option like -.Li -g -be used, and that assembly listings ( -.Li -al ) -be requested also. -.Pp -Use the -.Li -ac -option to omit false conditionals from a listing. Any lines which are not -assembled because of a false -.Li .if -(or -.Li .ifdef , -or any other conditional), or a true -.Li .if -followed by an -.Li .else , -will be omitted from the listing. -.Pp -Use the -.Li -ad -option to omit debugging directives from the listing. -.Pp -Once you have specified one of these options, you can further control listing -output and its appearance using the directives -.Li .list , -.Li .nolist , -.Li .psize , -.Li .eject , -.Li .title , -and -.Li .sbttl . -The -.Li -an -option turns off all forms processing. If you do not request listing output -with one of the -.Li -a -options, the listing-control directives have no effect. -.Pp -The letters after -.Li -a -may be combined into one option, -.Em e.g. , -.Li -aln . -.Pp -Note if the assembler source is coming from the standard input (e.g., because -it is being created by -.Li gcc -and the -.Li -pipe -command line switch is being used) then the listing will not contain any comments -or preprocessor directives. This is because the listing code buffers input -source lines from stdin only after they have been preprocessed by the assembler. -This reduces memory usage and makes the code more efficient. -.Pp -.Ss Op --alternate -Begin in alternate macro mode, see Altmacro,, -.Li .altmacro -\&. -.Pp -.Ss Op -D -This option has no effect whatsoever, but it is accepted to make it more likely -that scripts written for other assemblers also work with -.Xr as . -.Pp -.Ss Work Faster: Op -f -.Li -f -should only be used when assembling programs written by a (trusted) compiler. -.Li -f -stops the assembler from doing whitespace and comment preprocessing on the -input file(s) before assembling them.See Section -.Dq Preprocessing . -.Pp -.Qo -.Em Warning: -if you use -.Li -f -when the files actually need to be preprocessed (if they contain comments, -for example), -.Xr as -does not work correctly. -.Qc -.Pp -.Ss Li .include Search Path: Op -I Va path -Use this option to add a -.Va path -to the list of directories -.Xr as -searches for files specified in -.Li .include -directives (see Section -.Dq Include ) . -You may use -.Op -I -as many times as necessary to include a variety of paths. The current working -directory is always searched first; after that, -.Xr as -searches any -.Li -I -directories in the same order as they were specified (left to right) on the -command line. -.Pp -.Ss Difference Tables: Op -K -On the machine specific family, this option is allowed, but has no effect. -It is permitted for compatibility with the GNU assembler on other platforms, -where it can be used to warn when the assembler alters the machine code generated -for -.Li .word -directives in difference tables. The machine specific family does not have -the addressing limitations that sometimes lead to this alteration on other -platforms. -.Pp -.Ss Include Local Symbols: Op -L -Symbols beginning with system-specific local label prefixes, typically -.Li .L -for ELF systems or -.Li L -for traditional a.out systems, are called -.Em local symbols . -See Section.Dq Symbol Names . -Normally you do not see such symbols when debugging, because they are intended -for the use of programs (like compilers) that compose assembler programs, -not for your notice. Normally both -.Xr as -and -.Li ld -discard such symbols, so you do not normally debug with them. -.Pp -This option tells -.Xr as -to retain those local symbols in the object file. Usually if you do this you -also tell the linker -.Li ld -to preserve those symbols. -.Pp -.Ss Configuring listing output: Op --listing -The listing feature of the assembler can be enabled via the command line switch -.Li -a -(see Section -.Dq a ) . -This feature combines the input source file(s) with a hex dump of the corresponding -locations in the output object file, and displays them as a listing file. -The format of this listing can be controlled by directives inside the assembler -source (i.e., -.Li .list -(see Section -.Dq List ) , -.Li .title -(see Section -.Dq Title ) , -.Li .sbttl -(see Section -.Dq Sbttl ) , -.Li .psize -(see Section -.Dq Psize ) , -and -.Li .eject -(see Section -.Dq Eject ) -and also by the following switches: -.Pp -.Bl -tag -width Ds -.It --listing-lhs-width= Li number -Sets the maximum width, in words, of the first line of the hex byte dump. -This dump appears on the left hand side of the listing output. -.Pp -.It --listing-lhs-width2= Li number -Sets the maximum width, in words, of any further lines of the hex byte dump -for a given input source line. If this value is not specified, it defaults -to being the same as the value specified for -.Li --listing-lhs-width . -If neither switch is used the default is to one. -.Pp -.It --listing-rhs-width= Li number -Sets the maximum width, in characters, of the source line that is displayed -alongside the hex dump. The default value for this parameter is 100. The source -line is displayed on the right hand side of the listing output. -.Pp -.It --listing-cont-lines= Li number -Sets the maximum number of continuation lines of hex dump that will be displayed -for a given single line of source input. The default value is 4. -.El -.Pp -.Ss Assemble in MRI Compatibility Mode: Op -M -The -.Op -M -or -.Op --mri -option selects MRI compatibility mode. This changes the syntax and pseudo-op -handling of -.Xr as -to make it compatible with the -.Li ASM68K -or the -.Li ASM960 -(depending upon the configured target) assembler from Microtec Research. The -exact nature of the MRI syntax will not be documented here; see the MRI manuals -for more information. Note in particular that the handling of macros and macro -arguments is somewhat different. The purpose of this option is to permit assembling -existing MRI assembler code using -.Xr as . -.Pp -The MRI compatibility is not complete. Certain operations of the MRI assembler -depend upon its object file format, and can not be supported using other object -file formats. Supporting these would require enhancing each object file format -individually. These are: -.Pp -.Bl -bullet -.It -global symbols in common section -.Pp -The m68k MRI assembler supports common sections which are merged by the linker. -Other object file formats do not support this. -.Xr as -handles common sections by treating them as a single common symbol. It permits -local symbols to be defined within a common section, but it can not support -global symbols, since it has no way to describe them. -.Pp -.It -complex relocations -.Pp -The MRI assemblers support relocations against a negated section address, -and relocations which combine the start addresses of two or more sections. -These are not support by other object file formats. -.Pp -.It -.Li END -pseudo-op specifying start address -.Pp -The MRI -.Li END -pseudo-op permits the specification of a start address. This is not supported -by other object file formats. The start address may instead be specified using -the -.Op -e -option to the linker, or in a linker script. -.Pp -.It -.Li IDNT , -.Li .ident -and -.Li NAME -pseudo-ops -.Pp -The MRI -.Li IDNT , -.Li .ident -and -.Li NAME -pseudo-ops assign a module name to the output file. This is not supported -by other object file formats. -.Pp -.It -.Li ORG -pseudo-op -.Pp -The m68k MRI -.Li ORG -pseudo-op begins an absolute section at a given address. This differs from -the usual -.Xr as -.Li .org -pseudo-op, which changes the location within the current section. Absolute -sections are not supported by other object file formats. The address of a -section may be assigned within a linker script. -.El -.Pp -There are some other features of the MRI assembler which are not supported -by -.Xr as , -typically either because they are difficult or because they seem of little -consequence. Some of these may be supported in future releases. -.Pp -.Bl -bullet -.It -EBCDIC strings -.Pp -EBCDIC strings are not supported. -.Pp -.It -packed binary coded decimal -.Pp -Packed binary coded decimal is not supported. This means that the -.Li DC.P -and -.Li DCB.P -pseudo-ops are not supported. -.Pp -.It -.Li FEQU -pseudo-op -.Pp -The m68k -.Li FEQU -pseudo-op is not supported. -.Pp -.It -.Li NOOBJ -pseudo-op -.Pp -The m68k -.Li NOOBJ -pseudo-op is not supported. -.Pp -.It -.Li OPT -branch control options -.Pp -The m68k -.Li OPT -branch control options--- -.Li B , -.Li BRS , -.Li BRB , -.Li BRL , -and -.Li BRW ----are ignored. -.Xr as -automatically relaxes all branches, whether forward or backward, to an appropriate -size, so these options serve no purpose. -.Pp -.It -.Li OPT -list control options -.Pp -The following m68k -.Li OPT -list control options are ignored: -.Li C , -.Li CEX , -.Li CL , -.Li CRE , -.Li E , -.Li G , -.Li I , -.Li M , -.Li MEX , -.Li MC , -.Li MD , -.Li X . -.Pp -.It -other -.Li OPT -options -.Pp -The following m68k -.Li OPT -options are ignored: -.Li NEST , -.Li O , -.Li OLD , -.Li OP , -.Li P , -.Li PCO , -.Li PCR , -.Li PCS , -.Li R . -.Pp -.It -.Li OPT -.Li D -option is default -.Pp -The m68k -.Li OPT -.Li D -option is the default, unlike the MRI assembler. -.Li OPT NOD -may be used to turn it off. -.Pp -.It -.Li XREF -pseudo-op. -.Pp -The m68k -.Li XREF -pseudo-op is ignored. -.Pp -.It -.Li .debug -pseudo-op -.Pp -The i960 -.Li .debug -pseudo-op is not supported. -.Pp -.It -.Li .extended -pseudo-op -.Pp -The i960 -.Li .extended -pseudo-op is not supported. -.Pp -.It -.Li .list -pseudo-op. -.Pp -The various options of the i960 -.Li .list -pseudo-op are not supported. -.Pp -.It -.Li .optimize -pseudo-op -.Pp -The i960 -.Li .optimize -pseudo-op is not supported. -.Pp -.It -.Li .output -pseudo-op -.Pp -The i960 -.Li .output -pseudo-op is not supported. -.Pp -.It -.Li .setreal -pseudo-op -.Pp -The i960 -.Li .setreal -pseudo-op is not supported. -.Pp -.El -.Ss Dependency Tracking: Op --MD -.Xr as -can generate a dependency file for the file it creates. This file consists -of a single rule suitable for -.Li make -describing the dependencies of the main source file. -.Pp -The rule is written to the file named in its argument. -.Pp -This feature is used in the automatic updating of makefiles. -.Pp -.Ss Name the Object File: Op -o -There is always one object file output when you run -.Xr as . -By default it has the name -.Pa a.out . -You use this option (which takes exactly one filename) to give the object -file a different name. -.Pp -Whatever the object file is called, -.Xr as -overwrites any existing file of the same name. -.Pp -.Ss Join Data and Text Sections: Op -R -.Op -R -tells -.Xr as -to write the object file as if all data-section data lives in the text section. -This is only done at the very last moment: your binary data are the same, -but data section parts are relocated differently. The data section part of -your object file is zero bytes long because all its bytes are appended to -the text section. (See Section -.Dq Sections . ) -.Pp -When you specify -.Op -R -it would be possible to generate shorter address displacements (because we -do not have to cross between text and data section). We refrain from doing -this simply for compatibility with older versions of -.Xr as . -In future, -.Op -R -may work this way. -.Pp -When -.Xr as -is configured for COFF or ELF output, this option is only useful if you use -sections named -.Li .text -and -.Li .data . -.Pp -.Ss Display Assembly Statistics: Op --statistics -Use -.Li --statistics -to display two statistics about the resources used by -.Xr as : -the maximum amount of space allocated during the assembly (in bytes), and -the total execution time taken for the assembly (in cpu seconds). -.Pp -.Ss Compatible Output: Op --traditional-format -For some targets, the output of -.Xr as -is different in some ways from the output of some existing assembler. This -switch requests -.Xr as -to use the traditional format instead. -.Pp -For example, it disables the exception frame optimizations which -.Xr as -normally does by default on -.Li gcc -output. -.Pp -.Ss Announce Version: Op -v -You can find out what version of as is running by including the option -.Li -v -(which you can also spell as -.Li -version ) -on the command line. -.Pp -.Ss Control Warnings: Op -W, Op --warn, Op --no-warn, Op --fatal-warnings -.Xr as -should never give a warning or error message when assembling compiler output. -But programs written by people often cause -.Xr as -to give a warning that a particular assumption was made. All such warnings -are directed to the standard error file. -.Pp -If you use the -.Op -W -and -.Op --no-warn -options, no warnings are issued. This only affects the warning messages: it -does not change any particular of how -.Xr as -assembles your file. Errors, which stop the assembly, are still reported. -.Pp -If you use the -.Op --fatal-warnings -option, -.Xr as -considers files that generate warnings to be in error. -.Pp -You can switch these options off again by specifying -.Op --warn , -which causes warnings to be output as usual. -.Pp -.Ss Generate Object File in Spite of Errors: Op -Z -After an error message, -.Xr as -normally produces no output. If for some reason you are interested in object -file output even after -.Xr as -gives an error message on your program, use the -.Li -Z -option. If there are any errors, -.Xr as -continues anyways, and writes an object file after a final warning message -of the form -.Li Va n errors, Va m warnings, generating bad object file. -.Pp -.Sh Syntax -This chapter describes the machine-independent syntax allowed in a source -file. -.Xr as -syntax is similar to what many other assemblers use; it is inspired by the -BSD 4.2 assembler. -.Pp -.Ss Preprocessing -The -.Xr as -internal preprocessor: -.Bl -bullet -.It -adjusts and removes extra whitespace. It leaves one space or tab before the -keywords on a line, and turns any other whitespace on the line into a single -space. -.Pp -.It -removes all comments, replacing them with a single space, or an appropriate -number of newlines. -.Pp -.It -converts character constants into the appropriate numeric values. -.El -.Pp -It does not do macro processing, include file handling, or anything else you -may get from your C compiler's preprocessor. You can do include file processing -with the -.Li .include -directive (see Section -.Dq Include ) . -You can use the GNU C compiler driver to get other \(lqCPP\(rq style preprocessing -by giving the input file a -.Li .S -suffix.See Section -.Dq Overall Options . -.Pp -Excess whitespace, comments, and character constants cannot be used in the -portions of the input text that are not preprocessed. -.Pp -If the first line of an input file is -.Li #NO_APP -or if you use the -.Li -f -option, whitespace and comments are not removed from the input file. Within -an input file, you can ask for whitespace and comment removal in specific -portions of the by putting a line that says -.Li #APP -before the text that may contain whitespace or comments, and putting a line -that says -.Li #NO_APP -after this text. This feature is mainly intend to support -.Li asm -statements in compilers whose output is otherwise free of comments and whitespace. -.Pp -.Ss Whitespace -.Em Whitespace -is one or more blanks or tabs, in any order. Whitespace is used to separate -symbols, and to make programs neater for people to read. Unless within character -constants (see Section -.Dq Characters ) , -any whitespace means the same as exactly one space. -.Pp -.Ss Comments -There are two ways of rendering comments to -.Xr as . -In both cases the comment is equivalent to one space. -.Pp -Anything from -.Li /* -through the next -.Li */ -is a comment. This means you may not nest these comments. -.Pp -.Bd -literal -offset indent -/* - The only way to include a newline ('\en') in a comment - is to use this sort of comment. -*/ - -/* This sort of comment does not nest. */ -.Ed -.Pp -Anything from the -.Em line comment -character to the next newline is considered a comment and is ignored. The -line comment character is -.Li @ -on the ARM; -.Li # -on the i386 and x86-64; -.Li # -for Motorola PowerPC; -.Li ! -on the SPARC; see Machine Dependencies. -.Pp -To be compatible with past assemblers, lines that begin with -.Li # -have a special interpretation. Following the -.Li # -should be an absolute expression (see Section -.Dq Expressions ) : -the logical line number of the -.Em next -line. Then a string (see Section -.Dq Strings ) -is allowed: if present it is a new logical file name. The rest of the line, -if any, should be whitespace. -.Pp -If the first non-whitespace characters on the line are not numeric, the line -is ignored. (Just like a comment.) -.Pp -.Bd -literal -offset indent - # This is an ordinary comment. -# 42-6 "new_file_name" # New logical file name - # This is logical line # 36. -.Ed -This feature is deprecated, and may disappear from future versions of -.Xr as . -.Pp -.Ss Symbols -A -.Em symbol -is one or more characters chosen from the set of all letters (both upper and -lower case), digits and the three characters -.Li _.$ . -No symbol may begin with a digit. Case is significant. There is no length -limit: all characters are significant. Symbols are delimited by characters -not in that set, or by the beginning of a file (since the source program must -end with a newline, the end of a file is not a possible symbol delimiter).See Section -.Dq Symbols . -.Pp -.Ss Statements -A -.Em statement -ends at a newline character ( -.Li \en ) -or at a semicolon ( -.Li ; ) . -The newline or semicolon is considered part of the preceding statement. Newlines -and semicolons within character constants are an exception: they do not end -statements. -.Pp -It is an error to end any statement with end-of-file: the last character of -any input file should be a newline. -.Pp -An empty statement is allowed, and may include whitespace. It is ignored. -.Pp -A statement begins with zero or more labels, optionally followed by a key -symbol which determines what kind of statement it is. The key symbol determines -the syntax of the rest of the statement. If the symbol begins with a dot -.Li . -then the statement is an assembler directive: typically valid for any computer. -If the symbol begins with a letter the statement is an assembly language -.Em instruction : -it assembles into a machine language instruction. -.Pp -A label is a symbol immediately followed by a colon ( -.Li : ) . -Whitespace before a label or after a colon is permitted, but you may not have -whitespace between a label's symbol and its colon.See Section -.Dq Labels . -.Pp -.Bd -literal -offset indent -label: .directive followed by something -another_label: # This is an empty statement. - instruction operand_1, operand_2, ... -.Ed -.Pp -.Ss Constants -A constant is a number, written so that its value is known by inspection, -without knowing any context. Like this: -.Bd -literal -offset indent - -\&.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\eJ # All the same value. -\&.ascii "Ring the bell\e7" # A string constant. -\&.octa 0x123456789abcdef0123456789ABCDEF0 # A biGNUm. -\&.float 0f-314159265358979323846264338327\e -95028841971.693993751E-40 # - pi, a flonum. - -.Ed -.Pp -.Em Character Constants -.Pp -There are two kinds of character constants. A -.Em character -stands for one character in one byte and its value may be used in numeric -expressions. String constants (properly called string -.Em literals ) -are potentially many bytes and their values may not be used in arithmetic -expressions. -.Pp -.No Strings -.Pp -A -.Em string -is written between double-quotes. It may contain double-quotes or null characters. -The way to get special characters into a string is to -.Em escape -these characters: precede them with a backslash -.Li \e -character. For example -.Li \e\e -represents one backslash: the first -.Li \e -is an escape which tells -.Xr as -to interpret the second character literally as a backslash (which prevents -.Xr as -from recognizing the second -.Li \e -as an escape character). The complete list of escapes follows. -.Pp -.Bl -tag -width Ds -.It \eb -Mnemonic for backspace; for ASCII this is octal code 010. -.Pp -.It \ef -Mnemonic for FormFeed; for ASCII this is octal code 014. -.Pp -.It \en -Mnemonic for newline; for ASCII this is octal code 012. -.Pp -.It \er -Mnemonic for carriage-Return; for ASCII this is octal code 015. -.Pp -.It \et -Mnemonic for horizontal Tab; for ASCII this is octal code 011. -.Pp -.It \e Va digit Va digit Va digit -An octal character code. The numeric code is 3 octal digits. For compatibility -with other Unix systems, 8 and 9 are accepted as digits: for example, -.Li \e008 -has the value 010, and -.Li \e009 -the value 011. -.Pp -.It \e Li x Va hex-digits... -A hex character code. All trailing hex digits are combined. Either upper or -lower case -.Li x -works. -.Pp -.It \e\e -Represents one -.Li \e -character. -.Pp -.It \e" -Represents one -.Li " -character. Needed in strings to represent this character, because an unescaped -.Li " -would end the string. -.Pp -.It \e Va anything-else -Any other character when escaped by -.Li \e -gives a warning, but assembles as if the -.Li \e -was not present. The idea is that if you used an escape sequence you clearly -didn't want the literal interpretation of the following character. However -.Xr as -has no other interpretation, so -.Xr as -knows it is giving you the wrong code and warns you of the fact. -.El -.Pp -Which characters are escapable, and what those escapes represent, varies widely -among assemblers. The current set is what we think the BSD 4.2 assembler recognizes, -and is a subset of what most C compilers recognize. If you are in doubt, do -not use an escape sequence. -.Pp -.No Characters -.Pp -A single character may be written as a single quote immediately followed by -that character. The same escapes apply to characters as to strings. So if -you want to write the character backslash, you must write -.Li '\e\e -where the first -.Li \e -escapes the second -.Li \e . -As you can see, the quote is an acute accent, not a grave accent. A newline -(or semicolon -.Li ; ) -immediately following an acute accent is taken as a literal character and -does not count as the end of a statement. The value of a character constant -in a numeric expression is the machine's byte-wide code for that character. -.Xr as -assumes your character code is ASCII: -.Li 'A -means 65, -.Li 'B -means 66, and so on. -.Pp -.Em Number Constants -.Pp -.Xr as -distinguishes three kinds of numbers according to how they are stored in the -target machine. -.Em Integers -are numbers that would fit into an -.Li int -in the C language. -.Em BiGNUms -are integers, but they are stored in more than 32 bits. -.Em Flonums -are floating point numbers, described below. -.Pp -.No Integers -.Pp -A binary integer is -.Li 0b -or -.Li 0B -followed by zero or more of the binary digits -.Li 01 . -.Pp -An octal integer is -.Li 0 -followed by zero or more of the octal digits ( -.Li 01234567 ) . -.Pp -A decimal integer starts with a non-zero digit followed by zero or more digits -( -.Li 0123456789 ) . -.Pp -A hexadecimal integer is -.Li 0x -or -.Li 0X -followed by one or more hexadecimal digits chosen from -.Li 0123456789abcdefABCDEF . -.Pp -Integers have the usual values. To denote a negative integer, use the prefix -operator -.Li - -discussed under expressions (see Section -.Dq Prefix Ops ) . -.Pp -.No BiGNUms -.Pp -A -.Em biGNUm -has the same syntax and semantics as an integer except that the number (or -its negative) takes more than 32 bits to represent in binary. The distinction -is made because in some places integers are permitted while biGNUms are not. -.Pp -.No Flonums -.Pp -A -.Em flonum -represents a floating point number. The translation is indirect: a decimal -floating point number from the text is converted by -.Xr as -to a generic binary floating point number of more than sufficient precision. -This generic floating point number is converted to a particular computer's -floating point format (or formats) by a portion of -.Xr as -specialized to that computer. -.Pp -A flonum is written by writing (in order) -.Bl -bullet -.It -The digit -.Li 0 . -.Pp -.It -A letter, to tell -.Xr as -the rest of the number is a flonum. -.Pp -.It -An optional sign: either -.Li + -or -.Li - . -.Pp -.It -An optional -.Em integer part : -zero or more decimal digits. -.Pp -.It -An optional -.Em fractional part : -.Li . -followed by zero or more decimal digits. -.Pp -.It -An optional exponent, consisting of: -.Pp -.Bl -bullet -.It -An -.Li E -or -.Li e . -.It -Optional sign: either -.Li + -or -.Li - . -.It -One or more decimal digits. -.El -.Pp -.El -At least one of the integer part or the fractional part must be present. The -floating point number has the usual base-10 value. -.Pp -.Xr as -does all processing using integers. Flonums are computed independently of -any floating point hardware in the computer running -.Xr as . -.Pp -.Sh Sections and Relocation -.Ss Background -Roughly, a section is a range of addresses, with no gaps; all data \(lqin\(rq those -addresses is treated the same for some particular purpose. For example there -may be a \(lqread only\(rq section. -.Pp -The linker -.Li ld -reads many object files (partial programs) and combines their contents to -form a runnable program. When -.Xr as -emits an object file, the partial program is assumed to start at address 0. -.Li ld -assigns the final addresses for the partial program, so that different partial -programs do not overlap. This is actually an oversimplification, but it suffices -to explain how -.Xr as -uses sections. -.Pp -.Li ld -moves blocks of bytes of your program to their run-time addresses. These blocks -slide to their run-time addresses as rigid units; their length does not change -and neither does the order of bytes within them. Such a rigid unit is called -a -.Em section . -Assigning run-time addresses to sections is called -.Em relocation . -It includes the task of adjusting mentions of object-file addresses so they -refer to the proper run-time addresses. -.Pp -An object file written by -.Xr as -has at least three sections, any of which may be empty. These are named -.Em text , -.Em data -and -.Em bss -sections. -.Pp -.Xr as -can also generate whatever other named sections you specify using the -.Li .section -directive (see Section -.Dq Section ) . -If you do not use any directives that place output in the -.Li .text -or -.Li .data -sections, these sections still exist, but are empty. -.Pp -Within the object file, the text section starts at address -.Li 0 , -the data section follows, and the bss section follows the data section. -.Pp -To let -.Li ld -know which data changes when the sections are relocated, and how to change -that data, -.Xr as -also writes to the object file details of the relocation needed. To perform -relocation -.Li ld -must know, each time an address in the object file is mentioned: -.Bl -bullet -.It -Where in the object file is the beginning of this reference to an address? -.It -How long (in bytes) is this reference? -.It -Which section does the address refer to? What is the numeric value of -.Bd -filled -offset indent -( -.Va address ) -\-( -.Va start-address of section ) ? -.Ed -.It -Is the reference to an address \(lqProgram-Counter relative\(rq? -.El -.Pp -In fact, every address -.Xr as -ever uses is expressed as -.Bd -filled -offset indent -( -.Va section ) -+ ( -.Va offset into section ) -.Ed -Further, most expressions -.Xr as -computes have this section-relative nature. -.Pp -In this manual we use the notation { -.Va secname -.Va N -}to mean \(lqoffset -.Va N -into section -.Va secname -\&.\(rq -.Pp -Apart from text, data and bss sections you need to know about the -.Em absolute -section. When -.Li ld -mixes partial programs, addresses in the absolute section remain unchanged. -For example, address -.Li {absolute 0} -is \(lqrelocated\(rq to run-time address 0 by -.Li ld . -Although the linker never arranges two partial programs' data sections with -overlapping addresses after linking, -.Em by definition -their absolute sections must overlap. Address -.Li {absolute 239} -in one part of a program is always the same address when the program is running -as address -.Li {absolute 239} -in any other part of the program. -.Pp -The idea of sections is extended to the -.Em undefined -section. Any address whose section is unknown at assembly time is by definition -rendered {undefined -.Va U -}---where -.Va U -is filled in later. Since numbers are always defined, the only way to generate -an undefined address is to mention an undefined symbol. A reference to a named -common block would be such a symbol: its value is unknown at assembly time -so it has section -.Em undefined . -.Pp -By analogy the word -.Em section -is used to describe groups of sections in the linked program. -.Li ld -puts all partial programs' text sections in contiguous addresses in the linked -program. It is customary to refer to the -.Em text section -of a program, meaning all the addresses of all partial programs' text sections. -Likewise for data and bss sections. -.Pp -Some sections are manipulated by -.Li ld ; -others are invented for use of -.Xr as -and have no meaning except during assembly. -.Pp -.Ss Linker Sections -.Li ld -deals with just four kinds of sections, summarized below. -.Pp -.Bl -tag -width Ds -.It named sections -These sections hold your program. -.Xr as -and -.Li ld -treat them as separate but equal sections. Anything you can say of one section -is true of another. When the program is running, however, it is customary -for the text section to be unalterable. The text section is often shared among -processes: it contains instructions, constants and the like. The data section -of a running program is usually alterable: for example, C variables would -be stored in the data section. -.Pp -.It bss section -This section contains zeroed bytes when your program begins running. It is -used to hold uninitialized variables or common storage. The length of each -partial program's bss section is important, but because it starts out containing -zeroed bytes there is no need to store explicit zero bytes in the object file. -The bss section was invented to eliminate those explicit zeros from object -files. -.Pp -.It absolute section -Address 0 of this section is always \(lqrelocated\(rq to runtime address 0. This is -useful if you want to refer to an address that -.Li ld -must not change when relocating. In this sense we speak of absolute addresses -being \(lqunrelocatable\(rq: they do not change during relocation. -.Pp -.It undefined section -This \(lqsection\(rq is a catch-all for address references to objects not in the preceding -sections. -.El -.Pp -An idealized example of three relocatable sections follows. The example uses -the traditional section names -.Li .text -and -.Li .data . -Memory addresses are on the horizontal axis. -.Pp -.Bd -literal -offset indent - +-----+----+--+ -partial program # 1: |ttttt|dddd|00| - +-----+----+--+ - - text data bss - seg. seg. seg. - - +---+---+---+ -partial program # 2: |TTT|DDD|000| - +---+---+---+ - - +--+---+-----+--+----+---+-----+~~ -linked program: | |TTT|ttttt| |dddd|DDD|00000| - +--+---+-----+--+----+---+-----+~~ - - addresses: 0 ... -.Ed -.Pp -.Ss Assembler Internal Sections -These sections are meant only for the internal use of -.Xr as . -They have no meaning at run-time. You do not really need to know about these -sections for most purposes; but they can be mentioned in -.Xr as -warning messages, so it might be helpful to have an idea of their meanings -to -.Xr as . -These sections are used to permit the value of every expression in your assembly -language program to be a section-relative address. -.Pp -.Bl -tag -width Ds -.It ASSEMBLER-INTERNAL-LOGIC-ERROR! -An internal assembler logic error has been found. This means there is a bug -in the assembler. -.Pp -.It expr section -The assembler stores complex expression internally as combinations of symbols. -When it needs to represent an expression as a symbol, it puts it in the expr -section. -.El -.Pp -.Ss Sub-Sections -You may have separate groups of data in named sections that you want to end -up near to each other in the object file, even though they are not contiguous -in the assembler source. -.Xr as -allows you to use -.Em subsections -for this purpose. Within each section, there can be numbered subsections with -values from 0 to 8192. Objects assembled into the same subsection go into -the object file together with other objects in the same subsection. For example, -a compiler might want to store constants in the text section, but might not -want to have them interspersed with the program being assembled. In this case, -the compiler could issue a -.Li .text 0 -before each section of code being output, and a -.Li .text 1 -before each group of constants being output. -.Pp -Subsections are optional. If you do not use subsections, everything goes in -subsection number zero. -.Pp -Subsections appear in your object file in numeric order, lowest numbered to -highest. (All this to be compatible with other people's assemblers.) The object -file contains no representation of subsections; -.Li ld -and other programs that manipulate object files see no trace of them. They -just see all your text subsections as a text section, and all your data subsections -as a data section. -.Pp -To specify which subsection you want subsequent statements assembled into, -use a numeric argument to specify it, in a -.Li .text Va expression -or a -.Li .data Va expression -statement. You can also use the -.Li .subsection -directive (see Section -.Dq SubSection ) -to specify a subsection: -.Li .subsection Va expression . -.Va Expression -should be an absolute expression (see Section -.Dq Expressions ) . -If you just say -.Li .text -then -.Li .text 0 -is assumed. Likewise -.Li .data -means -.Li .data 0 . -Assembly begins in -.Li text 0 . -For instance: -.Bd -literal -offset indent -\&.text 0 # The default subsection is text 0 anyway. -\&.ascii "This lives in the first text subsection. *" -\&.text 1 -\&.ascii "But this lives in the second text subsection." -\&.data 0 -\&.ascii "This lives in the data section," -\&.ascii "in the first data subsection." -\&.text 0 -\&.ascii "This lives in the first text section," -\&.ascii "immediately following the asterisk (*)." -.Ed -.Pp -Each section has a -.Em location counter -incremented by one for every byte assembled into that section. Because subsections -are merely a convenience restricted to -.Xr as -there is no concept of a subsection location counter. There is no way to directly -manipulate a location counter---but the -.Li .align -directive changes it, and any label definition captures its current value. -The location counter of the section where statements are being assembled is -said to be the -.Em active -location counter. -.Pp -.Ss bss Section -The bss section is used for local common variable storage. You may allocate -address space in the bss section, but you may not dictate data to load into -it before your program executes. When your program starts running, all the -contents of the bss section are zeroed bytes. -.Pp -The -.Li .lcomm -pseudo-op defines a symbol in the bss section; see Lcomm,, -.Li .lcomm -\&. -.Pp -The -.Li .comm -pseudo-op may be used to declare a common symbol, which is another form of -uninitialized symbol; see Comm,, -.Li .comm -\&. -.Pp -.Sh Symbols -Symbols are a central concept: the programmer uses symbols to name things, -the linker uses symbols to link, and the debugger uses symbols to debug. -.Pp -.Qo -.Em Warning: -.Xr as -does not place symbols in the object file in the same order they were declared. -This may break some debuggers. -.Qc -.Pp -.Ss Labels -A -.Em label -is written as a symbol immediately followed by a colon -.Li : . -The symbol then represents the current value of the active location counter, -and is, for example, a suitable instruction operand. You are warned if you -use the same symbol to represent two different locations: the first definition -overrides any other definitions. -.Pp -.Ss Giving Symbols Other Values -A symbol can be given an arbitrary value by writing a symbol, followed by -an equals sign -.Li = , -followed by an expression (see Section -.Dq Expressions ) . -This is equivalent to using the -.Li .set -directive.See Section -.Dq Set . -In the same way, using a double equals sign -.Li = -.Li = -here represents an equivalent of the -.Li .eqv -directive.See Section -.Dq Eqv . -.Pp -.Ss Symbol Names -Symbol names begin with a letter or with one of -.Li ._ . -On most machines, you can also use -.Li $ -in symbol names; exceptions are noted in Machine Dependencies. That character -may be followed by any string of digits, letters, dollar signs (unless otherwise -noted for a particular target machine), and underscores. -.Pp -Case of letters is significant: -.Li foo -is a different symbol name than -.Li Foo . -.Pp -Each symbol has exactly one name. Each name in an assembly language program -refers to exactly one symbol. You may use that symbol name any number of times -in a program. -.Pp -.Em Local Symbol Names -.Pp -A local symbol is any symbol beginning with certain local label prefixes. -By default, the local label prefix is -.Li .L -for ELF systems or -.Li L -for traditional a.out systems, but each target may have its own set of local -label prefixes. -.Pp -Local symbols are defined and used within the assembler, but they are normally -not saved in object files. Thus, they are not visible when debugging. You -may use the -.Li -L -option (see Section -.Dq L ) -to retain the local symbols in the object files. -.Pp -.Em Local Labels -.Pp -Local labels help compilers and programmers use names temporarily. They create -symbols which are guaranteed to be unique over the entire scope of the input -source code and which can be referred to by a simple notation. To define a -local label, write a label of the form -.Li Sy N: -(where -.Sy N -represents any positive integer). To refer to the most recent previous definition -of that label write -.Li Sy Nb , -using the same number as when you defined the label. To refer to the next -definition of a local label, write -.Li Sy Nf ----the -.Li b -stands for \(lqbackwards\(rq and the -.Li f -stands for \(lqforwards\(rq. -.Pp -There is no restriction on how you can use these labels, and you can reuse -them too. So that it is possible to repeatedly define the same local label -(using the same number -.Li Sy N ) , -although you can only refer to the most recently defined local label of that -number (for a backwards reference) or the next definition of a specific local -label for a forward reference. It is also worth noting that the first 10 local -labels ( -.Li Sy 0: -\&....Li Sy 9: ) -are implemented in a slightly more efficient manner than the others. -.Pp -Here is an example: -.Pp -.Bd -literal -offset indent -1: branch 1f -2: branch 1b -1: branch 2f -2: branch 1b -.Ed -.Pp -Which is the equivalent of: -.Pp -.Bd -literal -offset indent -label_1: branch label_3 -label_2: branch label_1 -label_3: branch label_4 -label_4: branch label_3 -.Ed -.Pp -Local label names are only a notational device. They are immediately transformed -into more conventional symbol names before the assembler uses them. The symbol -names are stored in the symbol table, appear in error messages, and are optionally -emitted to the object file. The names are constructed using these parts: -.Pp -.Bl -tag -width Ds -.It Em local label prefix -All local symbols begin with the system-specific local label prefix. Normally -both -.Xr as -and -.Li ld -forget symbols that start with the local label prefix. These labels are used -for symbols you are never intended to see. If you use the -.Li -L -option then -.Xr as -retains these symbols in the object file. If you also instruct -.Li ld -to retain these symbols, you may use them in debugging. -.Pp -.It Va number -This is the number that was used in the local label definition. So if the -label is written -.Li 55: -then the number is -.Li 55 . -.Pp -.It Li C-B -This unusual character is included so you do not accidentally invent a symbol -of the same name. The character has ASCII value of -.Li \e002 -(control-B). -.Pp -.It Em ordinal number -This is a serial number to keep the labels distinct. The first definition -of -.Li 0: -gets the number -.Li 1 . -The 15th definition of -.Li 0: -gets the number -.Li 15 , -and so on. Likewise the first definition of -.Li 1: -gets the number -.Li 1 -and its 15th definition gets -.Li 15 -as well. -.El -.Pp -So for example, the first -.Li 1: -may be named -.Li .L1 Li C-B1 , -and the 44th -.Li 3: -may be named -.Li .L3 Li C-B44 . -.Pp -.Em Dollar Local Labels -.Pp -.Li as -also supports an even more local form of local labels called dollar labels. -These labels go out of scope (i.e., they become undefined) as soon as a non-local -label is defined. Thus they remain valid for only a small region of the input -source code. Normal local labels, by contrast, remain in scope for the entire -file, or until they are redefined by another occurrence of the same local -label. -.Pp -Dollar labels are defined in exactly the same way as ordinary local labels, -except that instead of being terminated by a colon, they are terminated by -a dollar sign, e.g., -.Li Sy 55$ . -.Pp -They can also be distinguished from ordinary local labels by their transformed -names which use ASCII character -.Li \e001 -(control-A) as the magic character to distinguish them from ordinary labels. -For example, the fifth definition of -.Li 6$ -may be named -.Li .L6 Li C-A5 . -.Pp -.Ss The Special Dot Symbol -The special symbol -.Li . -refers to the current address that -.Xr as -is assembling into. Thus, the expression -.Li melvin: .long . -defines -.Li melvin -to contain its own address. Assigning a value to -.Li . -is treated the same as a -.Li .org -directive. Thus, the expression -.Li .=.+4 -is the same as saying -.Li .space 4 . -.Pp -.Ss Symbol Attributes -Every symbol has, as well as its name, the attributes \(lqValue\(rq and \(lqType\(rq. Depending -on output format, symbols can also have auxiliary attributes. The detailed -definitions are in -.Pa a.out.h . -.Pp -If you use a symbol without defining it, -.Xr as -assumes zero for all these attributes, and probably won't warn you. This makes -the symbol an externally defined symbol, which is generally what you would -want. -.Pp -.Em Value -.Pp -The value of a symbol is (usually) 32 bits. For a symbol which labels a location -in the text, data, bss or absolute sections the value is the number of addresses -from the start of that section to the label. Naturally for text, data and -bss sections the value of a symbol changes as -.Li ld -changes section base addresses during linking. Absolute symbols' values do -not change during linking: that is why they are called absolute. -.Pp -The value of an undefined symbol is treated in a special way. If it is 0 then -the symbol is not defined in this assembler source file, and -.Li ld -tries to determine its value from other files linked into the same program. -You make this kind of symbol simply by mentioning a symbol name without defining -it. A non-zero value represents a -.Li .comm -common declaration. The value is how much common storage to reserve, in bytes -(addresses). The symbol refers to the first address of the allocated storage. -.Pp -.Em Type -.Pp -The type attribute of a symbol contains relocation (section) information, -any flag settings indicating that a symbol is external, and (optionally), -other information for linkers and debuggers. The exact format depends on the -object-code output format in use. -.Pp -.Sh Expressions -An -.Em expression -specifies an address or numeric value. Whitespace may precede and/or follow -an expression. -.Pp -The result of an expression must be an absolute number, or else an offset -into a particular section. If an expression is not absolute, and there is -not enough information when -.Xr as -sees the expression to know its section, a second pass over the source program -might be necessary to interpret the expression---but the second pass is currently -not implemented. -.Xr as -aborts with an error message in this situation. -.Pp -.Ss Empty Expressions -An empty expression has no value: it is just whitespace or null. Wherever -an absolute expression is required, you may omit the expression, and -.Xr as -assumes a value of (absolute) 0. This is compatible with other assemblers. -.Pp -.Ss Integer Expressions -An -.Em integer expression -is one or more -.Em arguments -delimited by -.Em operators . -.Pp -.Em Arguments -.Pp -.Em Arguments -are symbols, numbers or subexpressions. In other contexts arguments are sometimes -called \(lqarithmetic operands\(rq. In this manual, to avoid confusing them with the -\(lqinstruction operands\(rq of the machine language, we use the term \(lqargument\(rq to -refer to parts of expressions only, reserving the word \(lqoperand\(rq to refer only -to machine instruction operands. -.Pp -Symbols are evaluated to yield { -.Va section -.Va NNN -}where -.Va section -is one of text, data, bss, absolute, or undefined. -.Va NNN -is a signed, 2's complement 32 bit integer. -.Pp -Numbers are usually integers. -.Pp -A number can be a flonum or biGNUm. In this case, you are warned that only -the low order 32 bits are used, and -.Xr as -pretends these 32 bits are an integer. You may write integer-manipulating -instructions that act on exotic constants, compatible with other assemblers. -.Pp -Subexpressions are a left parenthesis -.Li ( -followed by an integer expression, followed by a right parenthesis -.Li ) ; -or a prefix operator followed by an argument. -.Pp -.Em Operators -.Pp -.Em Operators -are arithmetic functions, like -.Li + -or -.Li % . -Prefix operators are followed by an argument. Infix operators appear between -their arguments. Operators may be preceded and/or followed by whitespace. -.Pp -.Em Prefix Operator -.Pp -.Xr as -has the following -.Em prefix operators . -They each take one argument, which must be absolute. -.Pp -.Bl -tag -width Ds -.It - -.Em Negation . -Two's complement negation. -.It ~ -.Em Complementation . -Bitwise not. -.El -.Pp -.Em Infix Operators -.Pp -.Em Infix operators -take two arguments, one on either side. Operators have precedence, but operations -with equal precedence are performed left to right. Apart from -.Li + -or -.Op - , -both arguments must be absolute, and the result is absolute. -.Pp -.Bl -enum -.It -Highest Precedence -.Pp -.Bl -tag -width Ds -.It * -.Em Multiplication . -.Pp -.It / -.Em Division . -Truncation is the same as the C operator -.Li / -.Pp -.It % -.Em Remainder . -.Pp -.It << -.Em Shift Left . -Same as the C operator -.Li << . -.Pp -.It >> -.Em Shift Right . -Same as the C operator -.Li >> . -.El -.Pp -.It -Intermediate precedence -.Pp -.Bl -tag -width Ds -.It | -.Pp -.Em Bitwise Inclusive Or . -.Pp -.It & -.Em Bitwise And . -.Pp -.It ^ -.Em Bitwise Exclusive Or . -.Pp -.It ! -.Em Bitwise Or Not . -.El -.Pp -.It -Low Precedence -.Pp -.Bl -tag -width Ds -.It + -.Em Addition . -If either argument is absolute, the result has the section of the other argument. -You may not add together arguments from different sections. -.Pp -.It - -.Em Subtraction . -If the right argument is absolute, the result has the section of the left -argument. If both arguments are in the same section, the result is absolute. -You may not subtract arguments from different sections. -.Pp -.It == -.Em Is Equal To -.It <> -.It != -.Em Is Not Equal To -.It < -.Em Is Less Than -.It > -.Em Is Greater Than -.It >= -.Em Is Greater Than Or Equal To -.It <= -.Em Is Less Than Or Equal To -.Pp -The comparison operators can be used as infix operators. A true results has -a value of -1 whereas a false result has a value of 0. Note, these operators -perform signed comparisons. -.El -.Pp -.It -Lowest Precedence -.Pp -.Bl -tag -width Ds -.It && -.Em Logical And . -.Pp -.It || -.Em Logical Or . -.Pp -These two logical operations can be used to combine the results of sub expressions. -Note, unlike the comparison operators a true result returns a value of 1 but -a false results does still return 0. Also note that the logical or operator -has a slightly lower precedence than logical and. -.Pp -.El -.El -In short, it's only meaningful to add or subtract the -.Em offsets -in an address; you can only have a defined section in one of the two arguments. -.Pp -.Sh Assembler Directives -All assembler directives have names that begin with a period ( -.Li . ) . -The rest of the name is letters, usually in lower case. -.Pp -This chapter discusses directives that are available regardless of the target -machine configuration for the GNU assembler. -.Pp -.Ss Li .abort -This directive stops the assembly immediately. It is for compatibility with -other assemblers. The original idea was that the assembly language source -would be piped into the assembler. If the sender of the source quit, it could -use this directive tells -.Xr as -to quit also. One day -.Li .abort -will not be supported. -.Pp -.Ss Li .align Va abs-expr, Va abs-expr, Va abs-expr -Pad the location counter (in the current subsection) to a particular storage -boundary. The first expression (which must be absolute) is the alignment required, -as described below. -.Pp -The second expression (also absolute) gives the fill value to be stored in -the padding bytes. It (and the comma) may be omitted. If it is omitted, the -padding bytes are normally zero. However, on some systems, if the section -is marked as containing code and the fill value is omitted, the space is filled -with no-op instructions. -.Pp -The third expression is also absolute, and is also optional. If it is present, -it is the maximum number of bytes that should be skipped by this alignment -directive. If doing the alignment would require skipping more bytes than the -specified maximum, then the alignment is not done at all. You can omit the -fill value (the second argument) entirely by simply using two commas after -the required alignment; this can be useful if you want the alignment to be -filled with no-op instructions when appropriate. -.Pp -The way the required alignment is specified varies from system to system. -For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, s390, sparc, -tic4x, tic80 and xtensa, the first expression is the alignment request in -bytes. For example -.Li .align 8 -advances the location counter until it is a multiple of 8. If the location -counter is already a multiple of 8, no change is needed. For the tic54x, the -first expression is the alignment request in words. -.Pp -For other systems, including the i386 using a.out format, and the arm and -strongarm, it is the number of low-order zero bits the location counter must -have after advancement. For example -.Li .align 3 -advances the location counter until it a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. -.Pp -This inconsistency is due to the different behaviors of the various native -assemblers for these systems which GAS must emulate. GAS also provides -.Li .balign -and -.Li .p2align -directives, described later, which have a consistent behavior across all architectures -(but are specific to GAS). -.Pp -.Ss Li .ascii " Va string"... -.Li .ascii -expects zero or more string literals (see Section -.Dq Strings ) -separated by commas. It assembles each string (with no automatic trailing -zero byte) into consecutive addresses. -.Pp -.Ss Li .asciz " Va string"... -.Li .asciz -is just like -.Li .ascii , -but each string is followed by a zero byte. The \(lqz\(rq in -.Li .asciz -stands for \(lqzero\(rq. -.Pp -.Ss Li .balign[wl] Va abs-expr, Va abs-expr, Va abs-expr -Pad the location counter (in the current subsection) to a particular storage -boundary. The first expression (which must be absolute) is the alignment request -in bytes. For example -.Li .balign 8 -advances the location counter until it is a multiple of 8. If the location -counter is already a multiple of 8, no change is needed. -.Pp -The second expression (also absolute) gives the fill value to be stored in -the padding bytes. It (and the comma) may be omitted. If it is omitted, the -padding bytes are normally zero. However, on some systems, if the section -is marked as containing code and the fill value is omitted, the space is filled -with no-op instructions. -.Pp -The third expression is also absolute, and is also optional. If it is present, -it is the maximum number of bytes that should be skipped by this alignment -directive. If doing the alignment would require skipping more bytes than the -specified maximum, then the alignment is not done at all. You can omit the -fill value (the second argument) entirely by simply using two commas after -the required alignment; this can be useful if you want the alignment to be -filled with no-op instructions when appropriate. -.Pp -The -.Li .balignw -and -.Li .balignl -directives are variants of the -.Li .balign -directive. The -.Li .balignw -directive treats the fill pattern as a two byte word value. The -.Li .balignl -directives treats the fill pattern as a four byte longword value. For example, -.Li .balignw 4,0x368d -will align to a multiple of 4. If it skips two bytes, they will be filled -in with the value 0x368d (the exact placement of the bytes depends upon the -endianness of the processor). If it skips 1 or 3 bytes, the fill value is -undefined. -.Pp -.Ss Li .byte Va expressions -.Li .byte -expects zero or more expressions, separated by commas. Each expression is -assembled into the next byte. -.Pp -.Ss Li .comm Va symbol , Va length -.Li .comm -declares a common symbol named -.Va symbol . -When linking, a common symbol in one object file may be merged with a defined -or common symbol of the same name in another object file. If -.Li ld -does not see a definition for the symbol--just one or more common symbols--then -it will allocate -.Va length -bytes of uninitialized memory. -.Va length -must be an absolute expression. If -.Li ld -sees multiple common symbols with the same name, and they do not all have -the same size, it will allocate space using the largest size. -.Pp -When using ELF, the -.Li .comm -directive takes an optional third argument. This is the desired alignment -of the symbol, specified as a byte boundary (for example, an alignment of -16 means that the least significant 4 bits of the address should be zero). -The alignment must be an absolute expression, and it must be a power of two. -If -.Li ld -allocates uninitialized memory for the common symbol, it will use the alignment -when placing the symbol. If no alignment is specified, -.Xr as -will set the alignment to the largest power of two less than or equal to the -size of the symbol, up to a maximum of 16. -.Pp -.Ss Li .cfi_startproc [simple] -.Li .cfi_startproc -is used at the beginning of each function that should have an entry in -.Li .eh_frame . -It initializes some internal data structures. Don't forget to close the function -by -.Li .cfi_endproc . -.Pp -Unless -.Li .cfi_startproc -is used along with parameter -.Li simple -it also emits some architecture dependent initial CFI instructions. -.Ss Li .cfi_endproc -.Li .cfi_endproc -is used at the end of a function where it closes its unwind entry previously -opened by -.Li .cfi_startproc , -and emits it to -.Li .eh_frame . -.Pp -.Ss Li .cfi_personality Va encoding [, Va exp] -.Li .cfi_personality -defines personality routine and its encoding. -.Va encoding -must be a constant determining how the personality should be encoded. If it -is 255 ( -.Li DW_EH_PE_omit ) , -second argument is not present, otherwise second argument should be a constant -or a symbol name. When using indirect encodings, the symbol provided should -be the location where personality can be loaded from, not the personality -routine itself. The default after -.Li .cfi_startproc -is -.Li .cfi_personality 0xff , -no personality routine. -.Pp -.Ss Li .cfi_lsda Va encoding [, Va exp] -.Li .cfi_lsda -defines LSDA and its encoding. -.Va encoding -must be a constant determining how the LSDA should be encoded. If it is 255 -( -.Li DW_EH_PE_omit ) , -second argument is not present, otherwise second argument should be a constant -or a symbol name. The default after -.Li .cfi_startproc -is -.Li .cfi_lsda 0xff , -no LSDA. -.Pp -.Ss Li .cfi_def_cfa Va register, Va offset -.Li .cfi_def_cfa -defines a rule for computing CFA as: -.Em take address from Va register and add Va offset to it . -.Pp -.Ss Li .cfi_def_cfa_register Va register -.Li .cfi_def_cfa_register -modifies a rule for computing CFA. From now on -.Va register -will be used instead of the old one. Offset remains the same. -.Pp -.Ss Li .cfi_def_cfa_offset Va offset -.Li .cfi_def_cfa_offset -modifies a rule for computing CFA. Register remains the same, but -.Va offset -is new. Note that it is the absolute offset that will be added to a defined -register to compute CFA address. -.Pp -.Ss Li .cfi_adjust_cfa_offset Va offset -Same as -.Li .cfi_def_cfa_offset -but -.Va offset -is a relative value that is added/substracted from the previous offset. -.Pp -.Ss Li .cfi_offset Va register, Va offset -Previous value of -.Va register -is saved at offset -.Va offset -from CFA. -.Pp -.Ss Li .cfi_rel_offset Va register, Va offset -Previous value of -.Va register -is saved at offset -.Va offset -from the current CFA register. This is transformed to -.Li .cfi_offset -using the known displacement of the CFA register from the CFA. This is often -easier to use, because the number will match the code it's annotating. -.Pp -.Ss Li .cfi_register Va register1, Va register2 -Previous value of -.Va register1 -is saved in register -.Va register2 . -.Pp -.Ss Li .cfi_restore Va register -.Li .cfi_restore -says that the rule for -.Va register -is now the same as it was at the beginning of the function, after all initial -instruction added by -.Li .cfi_startproc -were executed. -.Pp -.Ss Li .cfi_undefined Va register -From now on the previous value of -.Va register -can't be restored anymore. -.Pp -.Ss Li .cfi_same_value Va register -Current value of -.Va register -is the same like in the previous frame, i.e. no restoration needed. -.Pp -.Ss Li .cfi_remember_state, -First save all current rules for all registers by -.Li .cfi_remember_state , -then totally screw them up by subsequent -.Li .cfi_* -directives and when everything is hopelessly bad, use -.Li .cfi_restore_state -to restore the previous saved state. -.Pp -.Ss Li .cfi_return_column Va register -Change return column -.Va register , -i.e. the return address is either directly in -.Va register -or can be accessed by rules for -.Va register . -.Pp -.Ss Li .cfi_signal_frame -Mark current function as signal trampoline. -.Pp -.Ss Li .cfi_window_save -SPARC register window has been saved. -.Pp -.Ss Li .cfi_escape Va expression[, ...] -Allows the user to add arbitrary bytes to the unwind info. One might use this -to add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet -support. -.Pp -.Ss Li .file Va fileno Va filename -When emitting dwarf2 line number information -.Li .file -assigns filenames to the -.Li .debug_line -file name table. The -.Va fileno -operand should be a unique positive integer to use as the index of the entry -in the table. The -.Va filename -operand is a C string literal. -.Pp -The detail of filename indices is exposed to the user because the filename -table is shared with the -.Li .debug_info -section of the dwarf2 debugging information, and thus the user must know the -exact indices that table entries will have. -.Pp -.Ss Li .loc Va fileno Va lineno [ Va column] [ Va options] -The -.Li .loc -directive will add row to the -.Li .debug_line -line number matrix corresponding to the immediately following assembly instruction. -The -.Va fileno , -.Va lineno , -and optional -.Va column -arguments will be applied to the -.Li .debug_line -state machine before the row is added. -.Pp -The -.Va options -are a sequence of the following tokens in any order: -.Pp -.Bl -tag -width Ds -.It basic_block -This option will set the -.Li basic_block -register in the -.Li .debug_line -state machine to -.Li true . -.Pp -.It prologue_end -This option will set the -.Li prologue_end -register in the -.Li .debug_line -state machine to -.Li true . -.Pp -.It epilogue_begin -This option will set the -.Li epilogue_begin -register in the -.Li .debug_line -state machine to -.Li true . -.Pp -.It is_stmt Va value -This option will set the -.Li is_stmt -register in the -.Li .debug_line -state machine to -.Li value , -which must be either 0 or 1. -.Pp -.It isa Va value -This directive will set the -.Li isa -register in the -.Li .debug_line -state machine to -.Va value , -which must be an unsigned integer. -.Pp -.El -.Ss Li .loc_mark_blocks Va enable -The -.Li .loc_mark_blocks -directive makes the assembler emit an entry to the -.Li .debug_line -line number matrix with the -.Li basic_block -register in the state machine set whenever a code label is seen. The -.Va enable -argument should be either 1 or 0, to enable or disable this function respectively. -.Pp -.Ss Li .data Va subsection -.Li .data -tells -.Xr as -to assemble the following statements onto the end of the data subsection numbered -.Va subsection -(which is an absolute expression). If -.Va subsection -is omitted, it defaults to zero. -.Pp -.Ss Li .double Va flonums -.Li .double -expects zero or more flonums, separated by commas. It assembles floating point -numbers. -.Pp -.Ss Li .eject -Force a page break at this point, when generating assembly listings. -.Pp -.Ss Li .else -.Li .else -is part of the -.Xr as -support for conditional assembly; see If,, -.Li .if -\&. It marks the beginning of a section of code to be assembled if the condition -for the preceding -.Li .if -was false. -.Pp -.Ss Li .elseif -.Li .elseif -is part of the -.Xr as -support for conditional assembly; see If,, -.Li .if -\&. It is shorthand for beginning a new -.Li .if -block that would otherwise fill the entire -.Li .else -section. -.Pp -.Ss Li .end -.Li .end -marks the end of the assembly file. -.Xr as -does not process anything in the file past the -.Li .end -directive. -.Pp -.Ss Li .endfunc -.Li .endfunc -marks the end of a function specified with -.Li .func . -.Pp -.Ss Li .endif -.Li .endif -is part of the -.Xr as -support for conditional assembly; it marks the end of a block of code that -is only assembled conditionally.See Section -.Dq If . -.Pp -.Ss Li .equ Va symbol, Va expression -This directive sets the value of -.Va symbol -to -.Va expression . -It is synonymous with -.Li .set ; -see Set,, -.Li .set -\&. -.Pp -.Ss Li .equiv Va symbol, Va expression -The -.Li .equiv -directive is like -.Li .equ -and -.Li .set , -except that the assembler will signal an error if -.Va symbol -is already defined. Note a symbol which has been referenced but not actually -defined is considered to be undefined. -.Pp -Except for the contents of the error message, this is roughly equivalent to -.Bd -literal -offset indent -\&.ifdef SYM -\&.err -\&.endif -\&.equ SYM,VAL -.Ed -plus it protects the symbol from later redefinition. -.Pp -.Ss Li .eqv Va symbol, Va expression -The -.Li .eqv -directive is like -.Li .equiv , -but no attempt is made to evaluate the expression or any part of it immediately. -Instead each time the resulting symbol is used in an expression, a snapshot -of its current value is taken. -.Pp -.Ss Li .err -If -.Xr as -assembles a -.Li .err -directive, it will print an error message and, unless the -.Op -Z -option was used, it will not generate an object file. This can be used to -signal an error in conditionally compiled code. -.Pp -.Ss Li .error " Va string" -Similarly to -.Li .err , -this directive emits an error, but you can specify a string that will be emitted -as the error message. If you don't specify the message, it defaults to -.Li ".error directive invoked in source file" . -See Section.Dq Errors . -.Pp -.Bd -literal -offset indent - .error "This code has not been assembled and tested." -.Ed -.Pp -.Ss Li .exitm -Exit early from the current macro definition.See Section -.Dq Macro . -.Pp -.Ss Li .extern -.Li .extern -is accepted in the source program---for compatibility with other assemblers---but -it is ignored. -.Xr as -treats all undefined symbols as external. -.Pp -.Ss Li .fail Va expression -Generates an error or a warning. If the value of the -.Va expression -is 500 or more, -.Xr as -will print a warning message. If the value is less than 500, -.Xr as -will print an error message. The message will include the value of -.Va expression . -This can occasionally be useful inside complex nested macros or conditional -assembly. -.Pp -.Ss Li .file Va string -.Li .file -tells -.Xr as -that we are about to start a new logical file. -.Va string -is the new file name. In general, the filename is recognized whether or not -it is surrounded by quotes -.Li " ; -but if you wish to specify an empty file name, you must give the quotes-- -.Li "" . -This statement may go away in future: it is only recognized to be compatible -with old -.Xr as -programs. -.Pp -.Ss Li .fill Va repeat , Va size , Va value -.Va repeat , -.Va size -and -.Va value -are absolute expressions. This emits -.Va repeat -copies of -.Va size -bytes. -.Va Repeat -may be zero or more. -.Va Size -may be zero or more, but if it is more than 8, then it is deemed to have the -value 8, compatible with other people's assemblers. The contents of each -.Va repeat -bytes is taken from an 8-byte number. The highest order 4 bytes are zero. -The lowest order 4 bytes are -.Va value -rendered in the byte-order of an integer on the computer -.Xr as -is assembling for. Each -.Va size -bytes in a repetition is taken from the lowest order -.Va size -bytes of this number. Again, this bizarre behavior is compatible with other -people's assemblers. -.Pp -.Va size -and -.Va value -are optional. If the second comma and -.Va value -are absent, -.Va value -is assumed zero. If the first comma and following tokens are absent, -.Va size -is assumed to be 1. -.Pp -.Ss Li .float Va flonums -This directive assembles zero or more flonums, separated by commas. It has -the same effect as -.Li .single . -.Pp -.Ss Li .func Va name[, Va label] -.Li .func -emits debugging information to denote function -.Va name , -and is ignored unless the file is assembled with debugging enabled. Only -.Li --gstabs[+] -is currently supported. -.Va label -is the entry point of the function and if omitted -.Va name -prepended with the -.Li leading char -is used. -.Li leading char -is usually -.Li _ -or nothing, depending on the target. All functions are currently defined to -have -.Li void -return type. The function must be terminated with -.Li .endfunc . -.Pp -.Ss Li .global Va symbol, Li .globl Va symbol -.Li .global -makes the symbol visible to -.Li ld . -If you define -.Va symbol -in your partial program, its value is made available to other partial programs -that are linked with it. Otherwise, -.Va symbol -takes its attributes from a symbol of the same name from another file linked -into the same program. -.Pp -Both spellings ( -.Li .globl -and -.Li .global ) -are accepted, for compatibility with other assemblers. -.Pp -.Ss Li .hidden Va names -This is one of the ELF visibility directives. The other two are -.Li .internal -(see Section -.Dq Internal ) -and -.Li .protected -(see Section -.Dq Protected ) . -.Pp -This directive overrides the named symbols default visibility (which is set -by their binding: local, global or weak). The directive sets the visibility -to -.Li hidden -which means that the symbols are not visible to other components. Such symbols -are always considered to be -.Li protected -as well. -.Pp -.Ss Li .hword Va expressions -This expects zero or more -.Va expressions , -and emits a 16 bit number for each. -.Pp -This directive is a synonym for -.Li .short . -.Pp -.Ss Li .ident -This directive is used by some assemblers to place tags in object files. The -behavior of this directive varies depending on the target. When using the -a.out object file format, -.Xr as -simply accepts the directive for source-file compatibility with existing assemblers, -but does not emit anything for it. When using COFF, comments are emitted to -the -.Li .comment -or -.Li .rdata -section, depending on the target. When using ELF, comments are emitted to -the -.Li .comment -section. -.Pp -.Ss Li .if Va absolute expression -.Li .if -marks the beginning of a section of code which is only considered part of -the source program being assembled if the argument (which must be an -.Va absolute expression ) -is non-zero. The end of the conditional section of code must be marked by -.Li .endif -(see Section -.Dq Endif ) ; -optionally, you may include code for the alternative condition, flagged by -.Li .else -(see Section -.Dq Else ) . -If you have several conditions to check, -.Li .elseif -may be used to avoid nesting blocks if/else within each subsequent -.Li .else -block. -.Pp -The following variants of -.Li .if -are also supported: -.Bl -tag -width Ds -.It .ifdef Va symbol -Assembles the following section of code if the specified -.Va symbol -has been defined. Note a symbol which has been referenced but not yet defined -is considered to be undefined. -.Pp -.It .ifb Va text -Assembles the following section of code if the operand is blank (empty). -.Pp -.It .ifc Va string1, Va string2 -Assembles the following section of code if the two strings are the same. The -strings may be optionally quoted with single quotes. If they are not quoted, -the first string stops at the first comma, and the second string stops at -the end of the line. Strings which contain whitespace should be quoted. The -string comparison is case sensitive. -.Pp -.It .ifeq Va absolute expression -Assembles the following section of code if the argument is zero. -.Pp -.It .ifeqs Va string1, Va string2 -Another form of -.Li .ifc . -The strings must be quoted using double quotes. -.Pp -.It .ifge Va absolute expression -Assembles the following section of code if the argument is greater than or -equal to zero. -.Pp -.It .ifgt Va absolute expression -Assembles the following section of code if the argument is greater than zero. -.Pp -.It .ifle Va absolute expression -Assembles the following section of code if the argument is less than or equal -to zero. -.Pp -.It .iflt Va absolute expression -Assembles the following section of code if the argument is less than zero. -.Pp -.It .ifnb Va text -Like -.Li .ifb , -but the sense of the test is reversed: this assembles the following section -of code if the operand is non-blank (non-empty). -.Pp -.It .ifnc Va string1, Va string2. -Like -.Li .ifc , -but the sense of the test is reversed: this assembles the following section -of code if the two strings are not the same. -.Pp -.It .ifndef Va symbol -.It .ifnotdef Va symbol -Assembles the following section of code if the specified -.Va symbol -has not been defined. Both spelling variants are equivalent. Note a symbol -which has been referenced but not yet defined is considered to be undefined. -.Pp -.It .ifne Va absolute expression -Assembles the following section of code if the argument is not equal to zero -(in other words, this is equivalent to -.Li .if ) . -.Pp -.It .ifnes Va string1, Va string2 -Like -.Li .ifeqs , -but the sense of the test is reversed: this assembles the following section -of code if the two strings are not the same. -.El -.Pp -.Ss Li .incbin " Va file"[, Va skip[, Va count]] -The -.Li incbin -directive includes -.Va file -verbatim at the current location. You can control the search paths used with -the -.Li -I -command-line option (see Section -.Dq Invoking ) . -Quotation marks are required around -.Va file . -.Pp -The -.Va skip -argument skips a number of bytes from the start of the -.Va file . -The -.Va count -argument indicates the maximum number of bytes to read. Note that the data -is not aligned in any way, so it is the user's responsibility to make sure -that proper alignment is provided both before and after the -.Li incbin -directive. -.Pp -.Ss Li .include " Va file" -This directive provides a way to include supporting files at specified points -in your source program. The code from -.Va file -is assembled as if it followed the point of the -.Li .include ; -when the end of the included file is reached, assembly of the original file -continues. You can control the search paths used with the -.Li -I -command-line option (see Section -.Dq Invoking ) . -Quotation marks are required around -.Va file . -.Pp -.Ss Li .int Va expressions -Expect zero or more -.Va expressions , -of any section, separated by commas. For each expression, emit a number that, -at run time, is the value of that expression. The byte order and bit size -of the number depends on what kind of target the assembly is for. -.Pp -.Ss Li .internal Va names -This is one of the ELF visibility directives. The other two are -.Li .hidden -(see Section -.Dq Hidden ) -and -.Li .protected -(see Section -.Dq Protected ) . -.Pp -This directive overrides the named symbols default visibility (which is set -by their binding: local, global or weak). The directive sets the visibility -to -.Li internal -which means that the symbols are considered to be -.Li hidden -(i.e., not visible to other components), and that some extra, processor specific -processing must also be performed upon the symbols as well. -.Pp -.Ss Li .irp Va symbol, Va values... -Evaluate a sequence of statements assigning different values to -.Va symbol . -The sequence of statements starts at the -.Li .irp -directive, and is terminated by an -.Li .endr -directive. For each -.Va value , -.Va symbol -is set to -.Va value , -and the sequence of statements is assembled. If no -.Va value -is listed, the sequence of statements is assembled once, with -.Va symbol -set to the null string. To refer to -.Va symbol -within the sequence of statements, use -.Va \esymbol . -.Pp -For example, assembling -.Pp -.Bd -literal -offset indent - .irp param,1,2,3 - move d\eparam,sp@- - .endr -.Ed -.Pp -is equivalent to assembling -.Pp -.Bd -literal -offset indent - move d1,sp@- - move d2,sp@- - move d3,sp@- -.Ed -.Pp -For some caveats with the spelling of -.Va symbol , -see also Macro. -.Pp -.Ss Li .irpc Va symbol, Va values... -Evaluate a sequence of statements assigning different values to -.Va symbol . -The sequence of statements starts at the -.Li .irpc -directive, and is terminated by an -.Li .endr -directive. For each character in -.Va value , -.Va symbol -is set to the character, and the sequence of statements is assembled. If no -.Va value -is listed, the sequence of statements is assembled once, with -.Va symbol -set to the null string. To refer to -.Va symbol -within the sequence of statements, use -.Va \esymbol . -.Pp -For example, assembling -.Pp -.Bd -literal -offset indent - .irpc param,123 - move d\eparam,sp@- - .endr -.Ed -.Pp -is equivalent to assembling -.Pp -.Bd -literal -offset indent - move d1,sp@- - move d2,sp@- - move d3,sp@- -.Ed -.Pp -For some caveats with the spelling of -.Va symbol , -see also the discussion atSee Section -.Dq Macro . -.Pp -.Ss Li .lcomm Va symbol , Va length -Reserve -.Va length -(an absolute expression) bytes for a local common denoted by -.Va symbol . -The section and value of -.Va symbol -are those of the new local common. The addresses are allocated in the bss -section, so that at run-time the bytes start off zeroed. -.Va Symbol -is not declared global (see Section -.Dq Global ) , -so is normally not visible to -.Li ld . -.Pp -.Ss Li .lflags -.Xr as -accepts this directive, for compatibility with other assemblers, but ignores -it. -.Pp -.Ss Li .line Va line-number -Even though this is a directive associated with the -.Li a.out -or -.Li b.out -object-code formats, -.Xr as -still recognizes it when producing COFF output, and treats -.Li .line -as though it were the COFF -.Li .ln -.Em if -it is found outside a -.Li .def -/ -.Li .endef -pair. -.Pp -Inside a -.Li .def , -.Li .line -is, instead, one of the directives used by compilers to generate auxiliary -symbol information for debugging. -.Pp -.Ss Li .linkonce [ Va type] -Mark the current section so that the linker only includes a single copy of -it. This may be used to include the same section in several different object -files, but ensure that the linker will only include it once in the final output -file. The -.Li .linkonce -pseudo-op must be used for each instance of the section. Duplicate sections -are detected based on the section name, so it should be unique. -.Pp -This directive is only supported by a few object file formats; as of this -writing, the only object file format which supports it is the Portable Executable -format used on Windows NT. -.Pp -The -.Va type -argument is optional. If specified, it must be one of the following strings. -For example: -.Bd -literal -offset indent -\&.linkonce same_size -.Ed -Not all types may be supported on all object file formats. -.Pp -.Bl -tag -width Ds -.It discard -Silently discard duplicate sections. This is the default. -.Pp -.It one_only -Warn if there are duplicate sections, but still keep only one copy. -.Pp -.It same_size -Warn if any of the duplicates have different sizes. -.Pp -.It same_contents -Warn if any of the duplicates do not have exactly the same contents. -.El -.Pp -.Ss Li .ln Va line-number -.Li .ln -is a synonym for -.Li .line . -.Pp -.Ss Li .mri Va val -If -.Va val -is non-zero, this tells -.Xr as -to enter MRI mode. If -.Va val -is zero, this tells -.Xr as -to exit MRI mode. This change affects code assembled until the next -.Li .mri -directive, or until the end of the file.See Section -.Dq M . -.Pp -.Ss Li .list -Control (in conjunction with the -.Li .nolist -directive) whether or not assembly listings are generated. These two directives -maintain an internal counter (which is zero initially). -.Li .list -increments the counter, and -.Li .nolist -decrements it. Assembly listings are generated whenever the counter is greater -than zero. -.Pp -By default, listings are disabled. When you enable them (with the -.Li -a -command line option;see Section -.Dq Invoking ) , -the initial value of the listing counter is one. -.Pp -.Ss Li .long Va expressions -.Li .long -is the same as -.Li .int . -See Section.Dq Int . -.Pp -.Ss Li .macro -The commands -.Li .macro -and -.Li .endm -allow you to define macros that generate assembly output. For example, this -definition specifies a macro -.Li sum -that puts a sequence of numbers into memory: -.Pp -.Bd -literal -offset indent - .macro sum from=0, to=5 - .long \efrom - .if \eto-\efrom - sum "(\efrom+1)",\eto - .endif - .endm -.Ed -.Pp -With that definition, -.Li SUM 0,5 -is equivalent to this assembly input: -.Pp -.Bd -literal -offset indent - .long 0 - .long 1 - .long 2 - .long 3 - .long 4 - .long 5 -.Ed -.Pp -.Bl -tag -width Ds -.It .macro Va macname -.It .macro Va macname Va macargs ... -Begin the definition of a macro called -.Va macname . -If your macro definition requires arguments, specify their names after the -macro name, separated by commas or spaces. You can qualify the macro argument -to indicate whether all invocations must specify a non-blank value (through -.Li : Li req ) , -or whether it takes all of the remaining arguments (through -.Li : Li vararg ) . -You can supply a default value for any macro argument by following the name -with -.Li = Va deflt . -You cannot define two macros with the same -.Va macname -unless it has been subject to the -.Li .purgem -directive (see Section -.Dq Purgem ) -between the two definitions. For example, these are all valid -.Li .macro -statements: -.Pp -.Bl -tag -width Ds -.It .macro comm -Begin the definition of a macro called -.Li comm , -which takes no arguments. -.Pp -.It .macro plus1 p, p1 -.It .macro plus1 p p1 -Either statement begins the definition of a macro called -.Li plus1 , -which takes two arguments; within the macro definition, write -.Li \ep -or -.Li \ep1 -to evaluate the arguments. -.Pp -.It .macro reserve_str p1=0 p2 -Begin the definition of a macro called -.Li reserve_str , -with two arguments. The first argument has a default value, but not the second. -After the definition is complete, you can call the macro either as -.Li reserve_str Va a, Va b -(with -.Li \ep1 -evaluating to -.Va a -and -.Li \ep2 -evaluating to -.Va b ) , -or as -.Li reserve_str , Va b -(with -.Li \ep1 -evaluating as the default, in this case -.Li 0 , -and -.Li \ep2 -evaluating to -.Va b ) . -.Pp -.It .macro m p1:req, p2=0, p3:vararg -Begin the definition of a macro called -.Li m , -with at least three arguments. The first argument must always have a value -specified, but not the second, which instead has a default value. The third -formal will get assigned all remaining arguments specified at invocation time. -.Pp -When you call a macro, you can specify the argument values either by position, -or by keyword. For example, -.Li sum 9,17 -is equivalent to -.Li sum to=17, from=9 . -.Pp -.El -Note that since each of the -.Va macargs -can be an identifier exactly as any other one permitted by the target architecture, -there may be occasional problems if the target hand-crafts special meanings -to certain characters when they occur in a special position. For example, -if the colon ( -.Li : ) -is generally permitted to be part of a symbol name, but the architecture specific -code special-cases it when occurring as the final character of a symbol (to -denote a label), then the macro parameter replacement code will have no way -of knowing that and consider the whole construct (including the colon) an -identifier, and check only this identifier for being the subject to parameter -substitution. So for example this macro definition: -.Pp -.Bd -literal -offset indent - .macro label l -\el: - .endm -.Ed -.Pp -might not work as expected. Invoking -.Li label foo -might not create a label called -.Li foo -but instead just insert the text -.Li \el: -into the assembler source, probably generating an error about an unrecognised -identifier. -.Pp -Similarly problems might occur with the period character ( -.Li . ) -which is often allowed inside opcode names (and hence identifier names). So -for example constructing a macro to build an opcode from a base name and a -length specifier like this: -.Pp -.Bd -literal -offset indent - .macro opcode base length - \ebase.\elength - .endm -.Ed -.Pp -and invoking it as -.Li opcode store l -will not create a -.Li store.l -instruction but instead generate some kind of error as the assembler tries -to interpret the text -.Li \ebase.\elength . -.Pp -There are several possible ways around this problem: -.Pp -.Bl -tag -width Ds -.It Insert white space -If it is possible to use white space characters then this is the simplest -solution. eg: -.Pp -.Bd -literal -offset indent - .macro label l -\el : - .endm -.Ed -.Pp -.It Use Li \e() -The string -.Li \e() -can be used to separate the end of a macro argument from the following text. -eg: -.Pp -.Bd -literal -offset indent - .macro opcode base length - \ebase\e().\elength - .endm -.Ed -.Pp -.It Use the alternate macro syntax mode -In the alternative macro syntax mode the ampersand character ( -.Li & ) -can be used as a separator. eg: -.Pp -.Bd -literal -offset indent - .altmacro - .macro label l -l&: - .endm -.Ed -.El -.Pp -Note: this problem of correctly identifying string parameters to pseudo ops -also applies to the identifiers used in -.Li .irp -(see Section -.Dq Irp ) -and -.Li .irpc -(see Section -.Dq Irpc ) -as well. -.Pp -.It .endm -Mark the end of a macro definition. -.Pp -.It .exitm -Exit early from the current macro definition. -.Pp -.It \e@ -.Xr as -maintains a counter of how many macros it has executed in this pseudo-variable; -you can copy that number to your output with -.Li \e@ , -but -.Em only within a macro definition . -.Pp -.It LOCAL Va name [ , ... ] -.Em Warning: Li LOCAL is only available if you select \(lqalternate macro syntax\(rq with Li --alternate or Li .altmacro. -See Section.Dq Altmacro . -.El -.Pp -.Ss Li .altmacro -Enable alternate macro mode, enabling: -.Pp -.Bl -tag -width Ds -.It LOCAL Va name [ , ... ] -One additional directive, -.Li LOCAL , -is available. It is used to generate a string replacement for each of the -.Va name -arguments, and replace any instances of -.Va name -in each macro expansion. The replacement string is unique in the assembly, -and different for each separate macro expansion. -.Li LOCAL -allows you to write macros that define symbols, without fear of conflict between -separate macro expansions. -.Pp -.It String delimiters -You can write strings delimited in these other ways besides -.Li " Va string" : -.Pp -.Bl -tag -width Ds -.It ' Va string' -You can delimit strings with single-quote characters. -.Pp -.It < Va string> -You can delimit strings with matching angle brackets. -.El -.Pp -.It single-character string escape -To include any single character literally in a string (even if the character -would otherwise have some special meaning), you can prefix the character with -.Li ! -(an exclamation mark). For example, you can write -.Li <4.3 !> 5.4!!> -to get the literal text -.Li 4.3 > 5.4! . -.Pp -.It Expression results as strings -You can write -.Li % Va expr -to evaluate the expression -.Va expr -and use the result as a string. -.El -.Pp -.Ss Li .noaltmacro -Disable alternate macro mode.See Section -.Dq Altmacro . -.Pp -.Ss Li .nolist -Control (in conjunction with the -.Li .list -directive) whether or not assembly listings are generated. These two directives -maintain an internal counter (which is zero initially). -.Li .list -increments the counter, and -.Li .nolist -decrements it. Assembly listings are generated whenever the counter is greater -than zero. -.Pp -.Ss Li .octa Va biGNUms -This directive expects zero or more biGNUms, separated by commas. For each -biGNUm, it emits a 16-byte integer. -.Pp -The term \(lqocta\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence -.Em octa --word for 16 bytes. -.Pp -.Ss Li .org Va new-lc , Va fill -Advance the location counter of the current section to -.Va new-lc . -.Va new-lc -is either an absolute expression or an expression with the same section as -the current subsection. That is, you can't use -.Li .org -to cross sections: if -.Va new-lc -has the wrong section, the -.Li .org -directive is ignored. To be compatible with former assemblers, if the section -of -.Va new-lc -is absolute, -.Xr as -issues a warning, then pretends the section of -.Va new-lc -is the same as the current subsection. -.Pp -.Li .org -may only increase the location counter, or leave it unchanged; you cannot -use -.Li .org -to move the location counter backwards. -.Pp -Because -.Xr as -tries to assemble programs in one pass, -.Va new-lc -may not be undefined. If you really detest this restriction we eagerly await -a chance to share your improved assembler. -.Pp -Beware that the origin is relative to the start of the section, not to the -start of the subsection. This is compatible with other people's assemblers. -.Pp -When the location counter (of the current subsection) is advanced, the intervening -bytes are filled with -.Va fill -which should be an absolute expression. If the comma and -.Va fill -are omitted, -.Va fill -defaults to zero. -.Pp -.Ss Li .p2align[wl] Va abs-expr, Va abs-expr, Va abs-expr -Pad the location counter (in the current subsection) to a particular storage -boundary. The first expression (which must be absolute) is the number of low-order -zero bits the location counter must have after advancement. For example -.Li .p2align 3 -advances the location counter until it a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. -.Pp -The second expression (also absolute) gives the fill value to be stored in -the padding bytes. It (and the comma) may be omitted. If it is omitted, the -padding bytes are normally zero. However, on some systems, if the section -is marked as containing code and the fill value is omitted, the space is filled -with no-op instructions. -.Pp -The third expression is also absolute, and is also optional. If it is present, -it is the maximum number of bytes that should be skipped by this alignment -directive. If doing the alignment would require skipping more bytes than the -specified maximum, then the alignment is not done at all. You can omit the -fill value (the second argument) entirely by simply using two commas after -the required alignment; this can be useful if you want the alignment to be -filled with no-op instructions when appropriate. -.Pp -The -.Li .p2alignw -and -.Li .p2alignl -directives are variants of the -.Li .p2align -directive. The -.Li .p2alignw -directive treats the fill pattern as a two byte word value. The -.Li .p2alignl -directives treats the fill pattern as a four byte longword value. For example, -.Li .p2alignw 2,0x368d -will align to a multiple of 4. If it skips two bytes, they will be filled -in with the value 0x368d (the exact placement of the bytes depends upon the -endianness of the processor). If it skips 1 or 3 bytes, the fill value is -undefined. -.Pp -.Ss Li .previous -This is one of the ELF section stack manipulation directives. The others are -.Li .section -(see Section -.Dq Section ) , -.Li .subsection -(see Section -.Dq SubSection ) , -.Li .pushsection -(see Section -.Dq PushSection ) , -and -.Li .popsection -(see Section -.Dq PopSection ) . -.Pp -This directive swaps the current section (and subsection) with most recently -referenced section (and subsection) prior to this one. Multiple -.Li .previous -directives in a row will flip between two sections (and their subsections). -.Pp -In terms of the section stack, this directive swaps the current section with -the top section on the section stack. -.Pp -.Ss Li .popsection -This is one of the ELF section stack manipulation directives. The others are -.Li .section -(see Section -.Dq Section ) , -.Li .subsection -(see Section -.Dq SubSection ) , -.Li .pushsection -(see Section -.Dq PushSection ) , -and -.Li .previous -(see Section -.Dq Previous ) . -.Pp -This directive replaces the current section (and subsection) with the top -section (and subsection) on the section stack. This section is popped off -the stack. -.Pp -.Ss Li .print Va string -.Xr as -will print -.Va string -on the standard output during assembly. You must put -.Va string -in double quotes. -.Pp -.Ss Li .protected Va names -This is one of the ELF visibility directives. The other two are -.Li .hidden -(see Section -.Dq Hidden ) -and -.Li .internal -(see Section -.Dq Internal ) . -.Pp -This directive overrides the named symbols default visibility (which is set -by their binding: local, global or weak). The directive sets the visibility -to -.Li protected -which means that any references to the symbols from within the components -that defines them must be resolved to the definition in that component, even -if a definition in another component would normally preempt this. -.Pp -.Ss Li .psize Va lines , Va columns -Use this directive to declare the number of lines---and, optionally, the number -of columns---to use for each page, when generating listings. -.Pp -If you do not use -.Li .psize , -listings use a default line-count of 60. You may omit the comma and -.Va columns -specification; the default width is 200 columns. -.Pp -.Xr as -generates formfeeds whenever the specified number of lines is exceeded (or -whenever you explicitly request one, using -.Li .eject ) . -.Pp -If you specify -.Va lines -as -.Li 0 , -no formfeeds are generated save those explicitly specified with -.Li .eject . -.Pp -.Ss Li .purgem Va name -Undefine the macro -.Va name , -so that later uses of the string will not be expanded.See Section -.Dq Macro . -.Pp -.Ss Li .pushsection Va name , Va subsection -This is one of the ELF section stack manipulation directives. The others are -.Li .section -(see Section -.Dq Section ) , -.Li .subsection -(see Section -.Dq SubSection ) , -.Li .popsection -(see Section -.Dq PopSection ) , -and -.Li .previous -(see Section -.Dq Previous ) . -.Pp -This directive pushes the current section (and subsection) onto the top of -the section stack, and then replaces the current section and subsection with -.Li name -and -.Li subsection . -.Pp -.Ss Li .quad Va biGNUms -.Li .quad -expects zero or more biGNUms, separated by commas. For each bignum, it emits -an 8-byte integer. If the biGNUm won't fit in 8 bytes, it prints a warning -message; and just takes the lowest order 8 bytes of the biGNUm. -.Pp -The term \(lqquad\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence -.Em quad --word for 8 bytes. -.Pp -.Ss Li .reloc Va offset, Va reloc_name[, Va expression] -Generate a relocation at -.Va offset -of type -.Va reloc_name -with value -.Va expression . -If -.Va offset -is a number, the relocation is generated in the current section. If -.Va offset -is an expression that resolves to a symbol plus offset, the relocation is -generated in the given symbol's section. -.Va expression , -if present, must resolve to a symbol plus addend or to an absolute value, -but note that not all targets support an addend. e.g. ELF REL targets such -as i386 store an addend in the section contents rather than in the relocation. -This low level interface does not support addends stored in the section. -.Pp -.Ss Li .rept Va count -Repeat the sequence of lines between the -.Li .rept -directive and the next -.Li .endr -directive -.Va count -times. -.Pp -For example, assembling -.Pp -.Bd -literal -offset indent - .rept 3 - .long 0 - .endr -.Ed -.Pp -is equivalent to assembling -.Pp -.Bd -literal -offset indent - .long 0 - .long 0 - .long 0 -.Ed -.Pp -.Ss Li .sbttl " Va subheading" -Use -.Va subheading -as the title (third line, immediately after the title line) when generating -assembly listings. -.Pp -This directive affects subsequent pages, as well as the current page if it -appears within ten lines of the top of a page. -.Pp -.Ss Li .section Va name -Use the -.Li .section -directive to assemble the following code into a section named -.Va name . -.Pp -This directive is only supported for targets that actually support arbitrarily -named sections; on -.Li a.out -targets, for example, it is not accepted, even with a standard -.Li a.out -section name. -.Pp -This is one of the ELF section stack manipulation directives. The others are -.Li .subsection -(see Section -.Dq SubSection ) , -.Li .pushsection -(see Section -.Dq PushSection ) , -.Li .popsection -(see Section -.Dq PopSection ) , -and -.Li .previous -(see Section -.Dq Previous ) . -.Pp -For ELF targets, the -.Li .section -directive is used like this: -.Pp -.Bd -literal -offset indent -\&.section name [, "flags"[, @type[,flag_specific_arguments]]] -.Ed -.Pp -The optional -.Va flags -argument is a quoted string which may contain any combination of the following -characters: -.Bl -tag -width Ds -.It a -section is allocatable -.It w -section is writable -.It x -section is executable -.It M -section is mergeable -.It S -section contains zero terminated strings -.It G -section is a member of a section group -.It T -section is used for thread-local-storage -.El -.Pp -The optional -.Va type -argument may contain one of the following constants: -.Bl -tag -width Ds -.It @progbits -section contains data -.It @nobits -section does not contain data (i.e., section only occupies space) -.It @note -section contains data which is used by things other than the program -.It @init_array -section contains an array of pointers to init functions -.It @fini_array -section contains an array of pointers to finish functions -.It @preinit_array -section contains an array of pointers to pre-init functions -.El -.Pp -Many targets only support the first three section types. -.Pp -Note on targets where the -.Li @ -character is the start of a comment (eg ARM) then another character is used -instead. For example the ARM port uses the -.Li % -character. -.Pp -If -.Va flags -contains the -.Li M -symbol then the -.Va type -argument must be specified as well as an extra argument--- -.Va entsize ----like this: -.Pp -.Bd -literal -offset indent -\&.section name , "flags"M, @type, entsize -.Ed -.Pp -Sections with the -.Li M -flag but not -.Li S -flag must contain fixed size constants, each -.Va entsize -octets long. Sections with both -.Li M -and -.Li S -must contain zero terminated strings where each character is -.Va entsize -bytes long. The linker may remove duplicates within sections with the same -name, same entity size and same flags. -.Va entsize -must be an absolute expression. -.Pp -If -.Va flags -contains the -.Li G -symbol then the -.Va type -argument must be present along with an additional field like this: -.Pp -.Bd -literal -offset indent -\&.section name , "flags"G, @type, GroupName[, linkage] -.Ed -.Pp -The -.Va GroupName -field specifies the name of the section group to which this particular section -belongs. The optional linkage field can contain: -.Bl -tag -width Ds -.It comdat -indicates that only one copy of this section should be retained -.It .GNU.linkonce -an alias for comdat -.El -.Pp -Note: if both the -.Va M -and -.Va G -flags are present then the fields for the Merge flag should come first, like -this: -.Pp -.Bd -literal -offset indent -\&.section name , "flags"MG, @type, entsize, GroupName[, linkage] -.Ed -.Pp -If no flags are specified, the default flags depend upon the section name. -If the section name is not recognized, the default will be for the section -to have none of the above flags: it will not be allocated in memory, nor writable, -nor executable. The section will contain data. -.Pp -For ELF targets, the assembler supports another type of -.Li .section -directive for compatibility with the Solaris assembler: -.Pp -.Bd -literal -offset indent -\&.section "name"[, flags...] -.Ed -.Pp -Note that the section name is quoted. There may be a sequence of comma separated -flags: -.Bl -tag -width Ds -.It #alloc -section is allocatable -.It #write -section is writable -.It #execinstr -section is executable -.It #tls -section is used for thread local storage -.El -.Pp -This directive replaces the current section and subsection. See the contents -of the gas testsuite directory -.Li gas/testsuite/gas/elf -for some examples of how this directive and the other section stack directives -work. -.Pp -.Ss Li .set Va symbol, Va expression -Set the value of -.Va symbol -to -.Va expression . -This changes -.Va symbol -\&'s value and type to conform to -.Va expression . -If -.Va symbol -was flagged as external, it remains flagged (see Section -.Dq Symbol Attributes ) . -.Pp -You may -.Li .set -a symbol many times in the same assembly. -.Pp -If you -.Li .set -a global symbol, the value stored in the object file is the last value stored -into it. -.Pp -.Ss Li .short Va expressions -This expects zero or more -.Va expressions , -and emits a 16 bit number for each. -.Pp -.Ss Li .single Va flonums -This directive assembles zero or more flonums, separated by commas. It has -the same effect as -.Li .float . -.Pp -.Ss Li .size -This directive is used to set the size associated with a symbol. -.Pp -For ELF targets, the -.Li .size -directive is used like this: -.Pp -.Bd -literal -offset indent -\&.size name , expression -.Ed -.Pp -This directive sets the size associated with a symbol -.Va name . -The size in bytes is computed from -.Va expression -which can make use of label arithmetic. This directive is typically used to -set the size of function symbols. -.Pp -.Ss Li .sleb128 Va expressions -.Va sleb128 -stands for \(lqsigned little endian base 128.\(rq This is a compact, variable length -representation of numbers used by the DWARF symbolic debugging format.See Section -.Dq Uleb128 . -.Pp -.Ss Li .skip Va size , Va fill -This directive emits -.Va size -bytes, each of value -.Va fill . -Both -.Va size -and -.Va fill -are absolute expressions. If the comma and -.Va fill -are omitted, -.Va fill -is assumed to be zero. This is the same as -.Li .space . -.Pp -.Ss Li .space Va size , Va fill -This directive emits -.Va size -bytes, each of value -.Va fill . -Both -.Va size -and -.Va fill -are absolute expressions. If the comma and -.Va fill -are omitted, -.Va fill -is assumed to be zero. This is the same as -.Li .skip . -.Pp -.Ss Li .stabd, .stabn, .stabs -There are three directives that begin -.Li .stab . -All emit symbols (see Section -.Dq Symbols ) , -for use by symbolic debuggers. The symbols are not entered in the -.Xr as -hash table: they cannot be referenced elsewhere in the source file. Up to -five fields are required: -.Pp -.Bl -tag -width Ds -.It string -This is the symbol's name. It may contain any character except -.Li \e000 , -so is more general than ordinary symbol names. Some debuggers used to code -arbitrarily complex structures into symbol names using this field. -.Pp -.It type -An absolute expression. The symbol's type is set to the low 8 bits of this -expression. Any bit pattern is permitted, but -.Li ld -and debuggers choke on silly bit patterns. -.Pp -.It other -An absolute expression. The symbol's \(lqother\(rq attribute is set to the low 8 bits -of this expression. -.Pp -.It desc -An absolute expression. The symbol's descriptor is set to the low 16 bits -of this expression. -.Pp -.It value -An absolute expression which becomes the symbol's value. -.El -.Pp -If a warning is detected while reading a -.Li .stabd , -.Li .stabn , -or -.Li .stabs -statement, the symbol has probably already been created; you get a half-formed -symbol in your object file. This is compatible with earlier assemblers! -.Pp -.Bl -tag -width Ds -.It .stabd Va type , Va other , Va desc -.Pp -The \(lqname\(rq of the symbol generated is not even an empty string. It is a null -pointer, for compatibility. Older assemblers used a null pointer so they didn't -waste space in object files with empty strings. -.Pp -The symbol's value is set to the location counter, relocatably. When your -program is linked, the value of this symbol is the address of the location -counter when the -.Li .stabd -was assembled. -.Pp -.It .stabn Va type , Va other , Va desc , Va value -The name of the symbol is set to the empty string -.Li "" . -.Pp -.It .stabs Va string , Va type , Va other , Va desc , Va value -All five fields are specified. -.El -.Pp -.Ss Li .string " Va str" -Copy the characters in -.Va str -to the object file. You may specify more than one string to copy, separated -by commas. Unless otherwise specified for a particular machine, the assembler -marks the end of each string with a 0 byte. You can use any of the escape -sequences described in Strings,,Strings. -.Pp -.Ss Li .struct Va expression -Switch to the absolute section, and set the section offset to -.Va expression , -which must be an absolute expression. You might use this as follows: -.Bd -literal -offset indent - .struct 0 -field1: - .struct field1 + 4 -field2: - .struct field2 + 4 -field3: -.Ed -This would define the symbol -.Li field1 -to have the value 0, the symbol -.Li field2 -to have the value 4, and the symbol -.Li field3 -to have the value 8. Assembly would be left in the absolute section, and you -would need to use a -.Li .section -directive of some sort to change to some other section before further assembly. -.Pp -.Ss Li .subsection Va name -This is one of the ELF section stack manipulation directives. The others are -.Li .section -(see Section -.Dq Section ) , -.Li .pushsection -(see Section -.Dq PushSection ) , -.Li .popsection -(see Section -.Dq PopSection ) , -and -.Li .previous -(see Section -.Dq Previous ) . -.Pp -This directive replaces the current subsection with -.Li name . -The current section is not changed. The replaced subsection is put onto the -section stack in place of the then current top of stack subsection. -.Pp -.Ss Li .symver -Use the -.Li .symver -directive to bind symbols to specific version nodes within a source file. -This is only supported on ELF platforms, and is typically used when assembling -files to be linked into a shared library. There are cases where it may make -sense to use this in objects to be bound into an application itself so as -to override a versioned symbol from a shared library. -.Pp -For ELF targets, the -.Li .symver -directive can be used like this: -.Bd -literal -offset indent -\&.symver name, name2@nodename -.Ed -If the symbol -.Va name -is defined within the file being assembled, the -.Li .symver -directive effectively creates a symbol alias with the name -.Va name2@nodename , -and in fact the main reason that we just don't try and create a regular alias -is that the -.Va @ -character isn't permitted in symbol names. The -.Va name2 -part of the name is the actual name of the symbol by which it will be externally -referenced. The name -.Va name -itself is merely a name of convenience that is used so that it is possible -to have definitions for multiple versions of a function within a single source -file, and so that the compiler can unambiguously know which version of a function -is being mentioned. The -.Va nodename -portion of the alias should be the name of a node specified in the version -script supplied to the linker when building a shared library. If you are attempting -to override a versioned symbol from a shared library, then -.Va nodename -should correspond to the nodename of the symbol you are trying to override. -.Pp -If the symbol -.Va name -is not defined within the file being assembled, all references to -.Va name -will be changed to -.Va name2@nodename . -If no reference to -.Va name -is made, -.Va name2@nodename -will be removed from the symbol table. -.Pp -Another usage of the -.Li .symver -directive is: -.Bd -literal -offset indent -\&.symver name, name2@@nodename -.Ed -In this case, the symbol -.Va name -must exist and be defined within the file being assembled. It is similar to -.Va name2@nodename . -The difference is -.Va name2@@nodename -will also be used to resolve references to -.Va name2 -by the linker. -.Pp -The third usage of the -.Li .symver -directive is: -.Bd -literal -offset indent -\&.symver name, name2@@@nodename -.Ed -When -.Va name -is not defined within the file being assembled, it is treated as -.Va name2@nodename . -When -.Va name -is defined within the file being assembled, the symbol name, -.Va name , -will be changed to -.Va name2@@nodename . -.Pp -.Ss Li .text Va subsection -Tells -.Xr as -to assemble the following statements onto the end of the text subsection numbered -.Va subsection , -which is an absolute expression. If -.Va subsection -is omitted, subsection number zero is used. -.Pp -.Ss Li .title " Va heading" -Use -.Va heading -as the title (second line, immediately after the source file name and pagenumber) -when generating assembly listings. -.Pp -This directive affects subsequent pages, as well as the current page if it -appears within ten lines of the top of a page. -.Pp -.Ss Li .type -This directive is used to set the type of a symbol. -.Pp -For ELF targets, the -.Li .type -directive is used like this: -.Pp -.Bd -literal -offset indent -\&.type name , type description -.Ed -.Pp -This sets the type of symbol -.Va name -to be either a function symbol or an object symbol. There are five different -syntaxes supported for the -.Va type description -field, in order to provide compatibility with various other assemblers. -.Pp -Because some of the characters used in these syntaxes (such as -.Li @ -and -.Li # ) -are comment characters for some architectures, some of the syntaxes below -do not work on all architectures. The first variant will be accepted by the -GNU assembler on all architectures so that variant should be used for maximum -portability, if you do not need to assemble your code with other assemblers. -.Pp -The syntaxes supported are: -.Pp -.Bd -literal -offset indent - .type <name> STT_FUNCTION - .type <name> STT_OBJECT - - .type <name>,#function - .type <name>,#object - - .type <name>,@function - .type <name>,@object - - .type <name>,%function - .type <name>,%object - - .type <name>,"function" - .type <name>,"object" -.Ed -.Pp -.Ss Li .uleb128 Va expressions -.Va uleb128 -stands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length -representation of numbers used by the DWARF symbolic debugging format.See Section -.Dq Sleb128 . -.Pp -.Ss Li .version " Va string" -This directive creates a -.Li .note -section and places into it an ELF formatted note of type NT_VERSION. The note's -name is set to -.Li string . -.Pp -.Ss Li .vtable_entry Va table, Va offset -This directive finds or creates a symbol -.Li table -and creates a -.Li VTABLE_ENTRY -relocation for it with an addend of -.Li offset . -.Pp -.Ss Li .vtable_inherit Va child, Va parent -This directive finds the symbol -.Li child -and finds or creates the symbol -.Li parent -and then creates a -.Li VTABLE_INHERIT -relocation for the parent whose addend is the value of the child symbol. As -a special case the parent name of -.Li 0 -is treated as referring to the -.Li *ABS* -section. -.Pp -.Ss Li .warning " Va string" -Similar to the directive -.Li .error -(see Section -.Dq Error ) , -but just emits a warning. -.Pp -.Ss Li .weak Va names -This directive sets the weak attribute on the comma separated list of symbol -.Li names . -If the symbols do not already exist, they will be created. -.Pp -On COFF targets other than PE, weak symbols are a GNU extension. This directive -sets the weak attribute on the comma separated list of symbol -.Li names . -If the symbols do not already exist, they will be created. -.Pp -On the PE target, weak symbols are supported natively as weak aliases. When -a weak symbol is created that is not an alias, GAS creates an alternate symbol -to hold the default value. -.Pp -.Ss Li .weakref Va alias, Va target -This directive creates an alias to the target symbol that enables the symbol -to be referenced with weak-symbol semantics, but without actually making it -weak. If direct references or definitions of the symbol are present, then -the symbol will not be weak, but if all references to it are through weak -references, the symbol will be marked as weak in the symbol table. -.Pp -The effect is equivalent to moving all references to the alias to a separate -assembly source file, renaming the alias to the symbol in it, declaring the -symbol as weak there, and running a reloadable link to merge the object files -resulting from the assembly of the new source file and the old source file -that had the references to the alias removed. -.Pp -The alias itself never makes to the symbol table, and is entirely handled -within the assembler. -.Pp -.Ss Li .word Va expressions -This directive expects zero or more -.Va expressions , -of any section, separated by commas. For each expression, -.Xr as -emits a 32-bit number. -.Pp -.Ss Deprecated Directives -One day these directives won't work. They are included for compatibility with -older assemblers. -.Bl -tag -width Ds -.It .abort -.It .line -.El -.Pp -.Sh ARM Dependent Features -.Ss Options -.Bl -tag -width Ds -.It -mcpu= Va processor[+ Va extension...] -This option specifies the target processor. The assembler will issue an error -message if an attempt is made to assemble an instruction which will not execute -on the target processor. The following processor names are recognized: -.Li arm1 , -.Li arm2 , -.Li arm250 , -.Li arm3 , -.Li arm6 , -.Li arm60 , -.Li arm600 , -.Li arm610 , -.Li arm620 , -.Li arm7 , -.Li arm7m , -.Li arm7d , -.Li arm7dm , -.Li arm7di , -.Li arm7dmi , -.Li arm70 , -.Li arm700 , -.Li arm700i , -.Li arm710 , -.Li arm710t , -.Li arm720 , -.Li arm720t , -.Li arm740t , -.Li arm710c , -.Li arm7100 , -.Li arm7500 , -.Li arm7500fe , -.Li arm7t , -.Li arm7tdmi , -.Li arm7tdmi-s , -.Li arm8 , -.Li arm810 , -.Li strongarm , -.Li strongarm1 , -.Li strongarm110 , -.Li strongarm1100 , -.Li strongarm1110 , -.Li arm9 , -.Li arm920 , -.Li arm920t , -.Li arm922t , -.Li arm940t , -.Li arm9tdmi , -.Li arm9e , -.Li arm926e , -.Li arm926ej-s , -.Li arm946e-r0 , -.Li arm946e , -.Li arm946e-s , -.Li arm966e-r0 , -.Li arm966e , -.Li arm966e-s , -.Li arm968e-s , -.Li arm10t , -.Li arm10tdmi , -.Li arm10e , -.Li arm1020 , -.Li arm1020t , -.Li arm1020e , -.Li arm1022e , -.Li arm1026ej-s , -.Li arm1136j-s , -.Li arm1136jf-s , -.Li arm1156t2-s , -.Li arm1156t2f-s , -.Li arm1176jz-s , -.Li arm1176jzf-s , -.Li mpcore , -.Li mpcorenovfp , -.Li cortex-a8 , -.Li cortex-r4 , -.Li cortex-m3 , -.Li ep9312 -(ARM920 with Cirrus Maverick coprocessor), -.Li i80200 -(Intel XScale processor) -.Li iwmmxt -(Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and -.Li xscale . -The special name -.Li all -may be used to allow the assembler to accept instructions valid for any ARM -processor. -.Pp -In addition to the basic instruction set, the assembler can be told to accept -various extension mnemonics that extend the processor using the co-processor -instruction space. For example, -.Li -mcpu=arm920+maverick -is equivalent to specifying -.Li -mcpu=ep9312 . -The following extensions are currently supported: -.Li +maverick -.Li +iwmmxt -and -.Li +xscale . -.Pp -.It -march= Va architecture[+ Va extension...] -This option specifies the target architecture. The assembler will issue an -error message if an attempt is made to assemble an instruction which will -not execute on the target architecture. The following architecture names are -recognized: -.Li armv1 , -.Li armv2 , -.Li armv2a , -.Li armv2s , -.Li armv3 , -.Li armv3m , -.Li armv4 , -.Li armv4xm , -.Li armv4t , -.Li armv4txm , -.Li armv5 , -.Li armv5t , -.Li armv5txm , -.Li armv5te , -.Li armv5texp , -.Li armv6 , -.Li armv6j , -.Li armv6k , -.Li armv6z , -.Li armv6zk , -.Li armv7 , -.Li armv7-a , -.Li armv7-r , -.Li armv7-m , -.Li iwmmxt -and -.Li xscale . -If both -.Li -mcpu -and -.Li -march -are specified, the assembler will use the setting for -.Li -mcpu . -.Pp -The architecture option can be extended with the same instruction set extension -options as the -.Li -mcpu -option. -.Pp -.It -mfpu= Va floating-point-format -.Pp -This option specifies the floating point format to assemble for. The assembler -will issue an error message if an attempt is made to assemble an instruction -which will not execute on the target floating point unit. The following format -options are recognized: -.Li softfpa , -.Li fpe , -.Li fpe2 , -.Li fpe3 , -.Li fpa , -.Li fpa10 , -.Li fpa11 , -.Li arm7500fe , -.Li softvfp , -.Li softvfp+vfp , -.Li vfp , -.Li vfp10 , -.Li vfp10-r0 , -.Li vfp9 , -.Li vfpxd , -.Li arm1020t , -.Li arm1020e , -.Li arm1136jf-s -and -.Li maverick . -.Pp -In addition to determining which instructions are assembled, this option also -affects the way in which the -.Li .double -assembler directive behaves when assembling little-endian code. -.Pp -The default is dependent on the processor selected. For Architecture 5 or -later, the default is to assembler for VFP instructions; for earlier architectures -the default is to assemble for FPA instructions. -.Pp -.It -mthumb -This option specifies that the assembler should start assembling Thumb instructions; -that is, it should behave as though the file starts with a -.Li .code 16 -directive. -.Pp -.It -mthumb-interwork -This option specifies that the output generated by the assembler should be -marked as supporting interworking. -.Pp -.It -mapcs Li [26|32] -This option specifies that the output generated by the assembler should be -marked as supporting the indicated version of the Arm Procedure. Calling Standard. -.Pp -.It -matpcs -This option specifies that the output generated by the assembler should be -marked as supporting the Arm/Thumb Procedure Calling Standard. If enabled -this option will cause the assembler to create an empty debugging section -in the object file called .arm.atpcs. Debuggers can use this to determine -the ABI being used by. -.Pp -.It -mapcs-float -This indicates the floating point variant of the APCS should be used. In this -variant floating point arguments are passed in FP registers rather than integer -registers. -.Pp -.It -mapcs-reentrant -This indicates that the reentrant variant of the APCS should be used. This -variant supports position independent code. -.Pp -.It -mfloat-abi= Va abi -This option specifies that the output generated by the assembler should be -marked as using specified floating point ABI. The following values are recognized: -.Li soft , -.Li softfp -and -.Li hard . -.Pp -.It -meabi= Va ver -This option specifies which EABI version the produced object files should -conform to. The following values are recognized: -.Li GNU , -.Li 4 -and -.Li 5 . -.Pp -.It -EB -This option specifies that the output generated by the assembler should be -marked as being encoded for a big-endian processor. -.Pp -.It -EL -This option specifies that the output generated by the assembler should be -marked as being encoded for a little-endian processor. -.Pp -.It -k -This option specifies that the output of the assembler should be marked as -position-independent code (PIC). -.Pp -.El -.Ss Syntax -.Em Special Characters -.Pp -The presence of a -.Li @ -on a line indicates the start of a comment that extends to the end of the -current line. If a -.Li # -appears as the first character of a line, the whole line is treated as a comment. -.Pp -The -.Li ; -character can be used instead of a newline to separate statements. -.Pp -Either -.Li # -or -.Li $ -can be used to indicate immediate operands. -.Pp -*TODO* Explain about /data modifier on symbols. -.Pp -.Em Register Names -.Pp -*TODO* Explain about ARM register naming, and the predefined names. -.Pp -.Em ARM relocation generation -.Pp -Specific data relocations can be generated by putting the relocation name -in parentheses after the symbol name. For example: -.Pp -.Bd -literal -offset indent - .word foo(TARGET1) -.Ed -.Pp -This will generate an -.Li R_ARM_TARGET1 -relocation against the symbol -.Va foo . -The following relocations are supported: -.Li GOT , -.Li GOTOFF , -.Li TARGET1 , -.Li TARGET2 , -.Li SBREL , -.Li TLSGD , -.Li TLSLDM , -.Li TLSLDO , -.Li GOTTPOFF -and -.Li TPOFF . -.Pp -For compatibility with older toolchains the assembler also accepts -.Li (PLT) -after branch targets. This will generate the deprecated -.Li R_ARM_PLT32 -relocation. -.Pp -Relocations for -.Li MOVW -and -.Li MOVT -instructions can be generated by prefixing the value with -.Li #:lower16: -and -.Li #:upper16 -respectively. For example to load the 32-bit address of foo into r0: -.Pp -.Bd -literal -offset indent - MOVW r0, #:lower16:foo - MOVT r0, #:upper16:foo -.Ed -.Pp -.Ss Floating Point -The ARM family uses ieee floating-point numbers. -.Pp -.Ss ARM Machine Directives -.Bl -tag -width Ds -.It .align Va expression [, Va expression] -This is the generic -.Va .align -directive. For the ARM however if the first argument is zero (ie no alignment -is needed) the assembler will behave as if the argument had been 2 (ie pad -to the next four byte boundary). This is for compatibility with ARM's own -assembler. -.Pp -.It Va name .req Va register name -This creates an alias for -.Va register name -called -.Va name . -For example: -.Pp -.Bd -literal -offset indent - foo .req r0 -.Ed -.Pp -.It .unreq Va alias-name -This undefines a register alias which was previously defined using the -.Li req , -.Li dn -or -.Li qn -directives. For example: -.Pp -.Bd -literal -offset indent - foo .req r0 - .unreq foo -.Ed -.Pp -An error occurs if the name is undefined. Note - this pseudo op can be used -to delete builtin in register name aliases (eg 'r0'). This should only be -done if it is really necessary. -.Pp -.It Va name .dn Va register name [ Va .type] [ Va [index]] -.It Va name .qn Va register name [ Va .type] [ Va [index]] -.Pp -The -.Li dn -and -.Li qn -directives are used to create typed and/or indexed register aliases for use -in Advanced SIMD Extension (Neon) instructions. The former should be used -to create aliases of double-precision registers, and the latter to create -aliases of quad-precision registers. -.Pp -If these directives are used to create typed aliases, those aliases can be -used in Neon instructions instead of writing types after the mnemonic or after -each operand. For example: -.Pp -.Bd -literal -offset indent - x .dn d2.f32 - y .dn d3.f32 - z .dn d4.f32[1] - vmul x,y,z -.Ed -.Pp -This is equivalent to writing the following: -.Pp -.Bd -literal -offset indent - vmul.f32 d2,d3,d4[1] -.Ed -.Pp -Aliases created using -.Li dn -or -.Li qn -can be destroyed using -.Li unreq . -.Pp -.It .code Li [16|32] -This directive selects the instruction set being generated. The value 16 selects -Thumb, with the value 32 selecting ARM. -.Pp -.It .thumb -This performs the same action as -.Va .code 16 . -.Pp -.It .arm -This performs the same action as -.Va .code 32 . -.Pp -.It .force_thumb -This directive forces the selection of Thumb instructions, even if the target -processor does not support those instructions -.Pp -.It .thumb_func -This directive specifies that the following symbol is the name of a Thumb -encoded function. This information is necessary in order to allow the assembler -and linker to generate correct code for interworking between Arm and Thumb -instructions and should be used even if interworking is not going to be performed. -The presence of this directive also implies -.Li .thumb -.Pp -This directive is not neccessary when generating EABI objects. On these targets -the encoding is implicit when generating Thumb code. -.Pp -.It .thumb_set -This performs the equivalent of a -.Li .set -directive in that it creates a symbol which is an alias for another symbol -(possibly not yet defined). This directive also has the added property in -that it marks the aliased symbol as being a thumb function entry point, in -the same way that the -.Li .thumb_func -directive does. -.Pp -.It .ltorg -This directive causes the current contents of the literal pool to be dumped -into the current section (which is assumed to be the .text section) at the -current location (aligned to a word boundary). -.Li GAS -maintains a separate literal pool for each section and each sub-section. The -.Li .ltorg -directive will only affect the literal pool of the current section and sub-section. -At the end of assembly all remaining, un-empty literal pools will automatically -be dumped. -.Pp -Note - older versions of -.Li GAS -would dump the current literal pool any time a section change occurred. This -is no longer done, since it prevents accurate control of the placement of -literal pools. -.Pp -.It .pool -This is a synonym for .ltorg. -.Pp -.It .unwind_fnstart -Marks the start of a function with an unwind table entry. -.Pp -.It .unwind_fnend -Marks the end of a function with an unwind table entry. The unwind index table -entry is created when this directive is processed. -.Pp -If no personality routine has been specified then standard personality routine -0 or 1 will be used, depending on the number of unwind opcodes required. -.Pp -.It .cantunwind -Prevents unwinding through the current function. No personality routine or -exception table data is required or permitted. -.Pp -.It .personality Va name -Sets the personality routine for the current function to -.Va name . -.Pp -.It .personalityindex Va index -Sets the personality routine for the current function to the EABI standard -routine number -.Va index -.Pp -.It .handlerdata -Marks the end of the current function, and the start of the exception table -entry for that function. Anything between this directive and the -.Li .fnend -directive will be added to the exception table entry. -.Pp -Must be preceded by a -.Li .personality -or -.Li .personalityindex -directive. -.Pp -.It .save Va reglist -Generate unwinder annotations to restore the registers in -.Va reglist . -The format of -.Va reglist -is the same as the corresponding store-multiple instruction. -.Pp -.Bd -literal -offset indent - .save {r4, r5, r6, lr} - stmfd sp!, {r4, r5, r6, lr} - .save f4, 2 - sfmfd f4, 2, [sp]! - .save {d8, d9, d10} - fstmdx sp!, {d8, d9, d10} - .save {wr10, wr11} - wstrd wr11, [sp, #-8]! - wstrd wr10, [sp, #-8]! -or - .save wr11 - wstrd wr11, [sp, #-8]! - .save wr10 - wstrd wr10, [sp, #-8]! -.Ed -.Pp -.It .vsave Va vfp-reglist -Generate unwinder annotations to restore the VFP registers in -.Va vfp-reglist -using FLDMD. Also works for VFPv3 registers that are to be restored using -VLDM. The format of -.Va vfp-reglist -is the same as the corresponding store-multiple instruction. -.Pp -.Bd -literal -offset indent - .vsave {d8, d9, d10} - fstmdd sp!, {d8, d9, d10} - .vsave {d15, d16, d17} - vstm sp!, {d15, d16, d17} -.Ed -.Pp -Since FLDMX and FSTMX are now deprecated, this directive should be used in -favour of -.Li .save -for saving VFP registers for ARMv6 and above. -.Pp -.It .pad # Va count -Generate unwinder annotations for a stack adjustment of -.Va count -bytes. A positive value indicates the function prologue allocated stack space -by decrementing the stack pointer. -.Pp -.It .movsp Va reg [, # Va offset] -Tell the unwinder that -.Va reg -contains an offset from the current stack pointer. If -.Va offset -is not specified then it is assumed to be zero. -.Pp -.It .setfp Va fpreg, Va spreg [, # Va offset] -Make all unwinder annotations relaive to a frame pointer. Without this the -unwinder will use offsets from the stack pointer. -.Pp -The syntax of this directive is the same as the -.Li sub -or -.Li mov -instruction used to set the frame pointer. -.Va spreg -must be either -.Li sp -or mentioned in a previous -.Li .movsp -directive. -.Pp -.Bd -literal -offset indent -\&.movsp ip -mov ip, sp -\&... -\&.setfp fp, ip, #4 -sub fp, ip, #4 -.Ed -.Pp -.It .raw Va offset, Va byte1, ... -Insert one of more arbitary unwind opcode bytes, which are known to adjust -the stack pointer by -.Va offset -bytes. -.Pp -For example -.Li .unwind_raw 4, 0xb1, 0x01 -is equivalent to -.Li .save {r0} -.Pp -.It .cpu Va name -Select the target processor. Valid values for -.Va name -are the same as for the -.Op -mcpu -commandline option. -.Pp -.It .arch Va name -Select the target architecture. Valid values for -.Va name -are the same as for the -.Op -march -commandline option. -.Pp -.It .object_arch Va name -Override the architecture recorded in the EABI object attribute section. Valid -values for -.Va name -are the same as for the -.Li .arch -directive. Typically this is useful when code uses runtime detection of CPU -features. -.Pp -.It .fpu Va name -Select the floating point unit to assemble for. Valid values for -.Va name -are the same as for the -.Op -mfpu -commandline option. -.Pp -.It .eabi_attribute Va tag, Va value -Set the EABI object attribute number -.Va tag -to -.Va value . -The value is either a -.Li number , -.Li "string" , -or -.Li number, "string" -depending on the tag. -.Pp -.El -.Ss Opcodes -.Li as -implements all the standard ARM opcodes. It also implements several pseudo -opcodes, including several synthetic load instructions. -.Pp -.Bl -tag -width Ds -.It NOP -.Bd -literal -offset indent - nop -.Ed -.Pp -This pseudo op will always evaluate to a legal ARM instruction that does nothing. -Currently it will evaluate to MOV r0, r0. -.Pp -.It LDR -.Bd -literal -offset indent - ldr <register> , = <expression> -.Ed -.Pp -If expression evaluates to a numeric constant then a MOV or MVN instruction -will be used in place of the LDR instruction, if the constant can be generated -by either of these instructions. Otherwise the constant will be placed into -the nearest literal pool (if it not already there) and a PC relative LDR instruction -will be generated. -.Pp -.It ADR -.Bd -literal -offset indent - adr <register> <label> -.Ed -.Pp -This instruction will load the address of -.Va label -into the indicated register. The instruction will evaluate to a PC relative -ADD or SUB instruction depending upon where the label is located. If the label -is out of range, or if it is not defined in the same file (and section) as -the ADR instruction, then an error will be generated. This instruction will -not make use of the literal pool. -.Pp -.It ADRL -.Bd -literal -offset indent - adrl <register> <label> -.Ed -.Pp -This instruction will load the address of -.Va label -into the indicated register. The instruction will evaluate to one or two PC -relative ADD or SUB instructions depending upon where the label is located. -If a second instruction is not needed a NOP instruction will be generated -in its place, so that this instruction is always 8 bytes long. -.Pp -If the label is out of range, or if it is not defined in the same file (and -section) as the ADRL instruction, then an error will be generated. This instruction -will not make use of the literal pool. -.Pp -.El -For information on the ARM or Thumb instruction sets, see -.Em ARM Software Development Toolkit Reference Manual , -Advanced RISC Machines Ltd. -.Pp -.Ss Mapping Symbols -The ARM ELF specification requires that special symbols be inserted into object -files to mark certain features: -.Pp -.Bl -tag -width Ds -.It $a -At the start of a region of code containing ARM instructions. -.Pp -.It $t -At the start of a region of code containing THUMB instructions. -.Pp -.It $d -At the start of a region of data. -.Pp -.El -The assembler will automatically insert these symbols for you - there is no -need to code them yourself. Support for tagging symbols ($b, $f, $p and $m) -which is also mentioned in the current ARM ELF specification is not implemented. -This is because they have been dropped from the new EABI and so tools cannot -rely upon their presence. -.Pp -.Sh 80386 Dependent Features -The i386 version -.Li as -supports both the original Intel 386 architecture in both 16 and 32-bit mode -as well as AMD x86-64 architecture extending the Intel architecture to 64-bits. -.Pp -.Ss Options -The i386 version of -.Li as -has a few machine dependent options: -.Pp -.Bl -tag -width Ds -.It --32 | --64 -Select the word size, either 32 bits or 64 bits. Selecting 32-bit implies -Intel i386 architecture, while 64-bit implies AMD x86-64 architecture. -.Pp -These options are only available with the ELF object file format, and require -that the necessary BFD support has been included (on a 32-bit platform you -have to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64 -as target platform). -.Pp -.It -n -By default, x86 GAS replaces multiple nop instructions used for alignment -within code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi. -This switch disables the optimization. -.Pp -.It --divide -On SVR4-derived platforms, the character -.Li / -is treated as a comment character, which means that it cannot be used in expressions. -The -.Li --divide -option turns -.Li / -into a normal character. This does not disable -.Li / -at the beginning of a line starting a comment, or affect using -.Li # -for starting a comment. -.Pp -.It -march= Va CPU -This option specifies an instruction set architecture for generating instructions. -The following architectures are recognized: -.Li i8086 , -.Li i186 , -.Li i286 , -.Li i386 , -.Li i486 , -.Li i586 , -.Li i686 , -.Li pentium , -.Li pentiumpro , -.Li pentiumii , -.Li pentiumiii , -.Li pentium4 , -.Li prescott , -.Li nocona , -.Li core , -.Li core2 , -.Li k6 , -.Li k6_2 , -.Li athlon , -.Li sledgehammer , -.Li opteron , -.Li k8 , -.Li generic32 -and -.Li generic64 . -.Pp -This option only affects instructions generated by the assembler. The -.Li .arch -directive will take precedent. -.Pp -.It -mtune= Va CPU -This option specifies a processor to optimize for. When used in conjunction -with the -.Op -march -option, only instructions of the processor specified by the -.Op -march -option will be generated. -.Pp -Valid -.Va CPU -values are identical to -.Op -march= Va CPU . -.Pp -.El -.Ss AT&T Syntax versus Intel Syntax -.Li as -now supports assembly using Intel assembler syntax. -.Li .intel_syntax -selects Intel mode, and -.Li .att_syntax -switches back to the usual AT&T mode for compatibility with the output of -.Li gcc . -Either of these directives may have an optional argument, -.Li prefix , -or -.Li noprefix -specifying whether registers require a -.Li % -prefix. AT&T System V/386 assembler syntax is quite different from Intel syntax. -We mention these differences because almost all 80386 documents use Intel -syntax. Notable differences between the two syntaxes are: -.Pp -.Bl -bullet -.It -AT&T immediate operands are preceded by -.Li $ ; -Intel immediate operands are undelimited (Intel -.Li push 4 -is AT&T -.Li pushl $4 ) . -AT&T register operands are preceded by -.Li % ; -Intel register operands are undelimited. AT&T absolute (as opposed to PC relative) -jump/call operands are prefixed by -.Li * ; -they are undelimited in Intel syntax. -.Pp -.It -AT&T and Intel syntax use the opposite order for source and destination operands. -Intel -.Li add eax, 4 -is -.Li addl $4, %eax . -The -.Li source, dest -convention is maintained for compatibility with previous Unix assemblers. -Note that instructions with more than one source operand, such as the -.Li enter -instruction, do -.Em not -have reversed order. i386-Bugs. -.Pp -.It -In AT&T syntax the size of memory operands is determined from the last character -of the instruction mnemonic. Mnemonic suffixes of -.Li b , -.Li w , -.Li l -and -.Li q -specify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit) -memory references. Intel syntax accomplishes this by prefixing memory operands -( -.Em not -the instruction mnemonics) with -.Li byte ptr , -.Li word ptr , -.Li dword ptr -and -.Li qword ptr . -Thus, Intel -.Li mov al, byte ptr Va foo -is -.Li movb Va foo, %al -in AT&T syntax. -.Pp -.It -Immediate form long jumps and calls are -.Li lcall/ljmp $ Va section, $ Va offset -in AT&T syntax; the Intel syntax is -.Li call/jmp far Va section: Va offset . -Also, the far return instruction is -.Li lret $ Va stack-adjust -in AT&T syntax; Intel syntax is -.Li ret far Va stack-adjust . -.Pp -.It -The AT&T assembler does not provide support for multiple section programs. -Unix style systems expect all programs to be single sections. -.El -.Pp -.Ss Instruction Naming -Instruction mnemonics are suffixed with one character modifiers which specify -the size of operands. The letters -.Li b , -.Li w , -.Li l -and -.Li q -specify byte, word, long and quadruple word operands. If no suffix is specified -by an instruction then -.Li as -tries to fill in the missing suffix based on the destination register operand -(the last one by convention). Thus, -.Li mov %ax, %bx -is equivalent to -.Li movw %ax, %bx ; -also, -.Li mov $1, %bx -is equivalent to -.Li movw $1, bx . -Note that this is incompatible with the AT&T Unix assembler which assumes -that a missing mnemonic suffix implies long operand size. (This incompatibility -does not affect compiler output since compilers always explicitly specify -the mnemonic suffix.) -.Pp -Almost all instructions have the same names in AT&T and Intel format. There -are a few exceptions. The sign extend and zero extend instructions need two -sizes to specify them. They need a size to sign/zero extend -.Em from -and a size to zero extend -.Em to . -This is accomplished by using two instruction mnemonic suffixes in AT&T syntax. -Base names for sign extend and zero extend are -.Li movs... -and -.Li movz... -in AT&T syntax ( -.Li movsx -and -.Li movzx -in Intel syntax). The instruction mnemonic suffixes are tacked on to this -base name, the -.Em from -suffix before the -.Em to -suffix. Thus, -.Li movsbl %al, %edx -is AT&T syntax for \(lqmove sign extend -.Em from -%al -.Em to -%edx.\(rq Possible suffixes, thus, are -.Li bl -(from byte to long), -.Li bw -(from byte to word), -.Li wl -(from word to long), -.Li bq -(from byte to quadruple word), -.Li wq -(from word to quadruple word), and -.Li lq -(from long to quadruple word). -.Pp -The Intel-syntax conversion instructions -.Pp -.Bl -bullet -.It -.Li cbw ---- sign-extend byte in -.Li %al -to word in -.Li %ax , -.Pp -.It -.Li cwde ---- sign-extend word in -.Li %ax -to long in -.Li %eax , -.Pp -.It -.Li cwd ---- sign-extend word in -.Li %ax -to long in -.Li %dx:%ax , -.Pp -.It -.Li cdq ---- sign-extend dword in -.Li %eax -to quad in -.Li %edx:%eax , -.Pp -.It -.Li cdqe ---- sign-extend dword in -.Li %eax -to quad in -.Li %rax -(x86-64 only), -.Pp -.It -.Li cqo ---- sign-extend quad in -.Li %rax -to octuple in -.Li %rdx:%rax -(x86-64 only), -.El -.Pp -are called -.Li cbtw , -.Li cwtl , -.Li cwtd , -.Li cltd , -.Li cltq , -and -.Li cqto -in AT&T naming. -.Li as -accepts either naming for these instructions. -.Pp -Far call/jump instructions are -.Li lcall -and -.Li ljmp -in AT&T syntax, but are -.Li call far -and -.Li jump far -in Intel convention. -.Pp -.Ss Register Naming -Register operands are always prefixed with -.Li % . -The 80386 registers consist of -.Pp -.Bl -bullet -.It -the 8 32-bit registers -.Li %eax -(the accumulator), -.Li %ebx , -.Li %ecx , -.Li %edx , -.Li %edi , -.Li %esi , -.Li %ebp -(the frame pointer), and -.Li %esp -(the stack pointer). -.Pp -.It -the 8 16-bit low-ends of these: -.Li %ax , -.Li %bx , -.Li %cx , -.Li %dx , -.Li %di , -.Li %si , -.Li %bp , -and -.Li %sp . -.Pp -.It -the 8 8-bit registers: -.Li %ah , -.Li %al , -.Li %bh , -.Li %bl , -.Li %ch , -.Li %cl , -.Li %dh , -and -.Li %dl -(These are the high-bytes and low-bytes of -.Li %ax , -.Li %bx , -.Li %cx , -and -.Li %dx ) -.Pp -.It -the 6 section registers -.Li %cs -(code section), -.Li %ds -(data section), -.Li %ss -(stack section), -.Li %es , -.Li %fs , -and -.Li %gs . -.Pp -.It -the 3 processor control registers -.Li %cr0 , -.Li %cr2 , -and -.Li %cr3 . -.Pp -.It -the 6 debug registers -.Li %db0 , -.Li %db1 , -.Li %db2 , -.Li %db3 , -.Li %db6 , -and -.Li %db7 . -.Pp -.It -the 2 test registers -.Li %tr6 -and -.Li %tr7 . -.Pp -.It -the 8 floating point register stack -.Li %st -or equivalently -.Li %st(0) , -.Li %st(1) , -.Li %st(2) , -.Li %st(3) , -.Li %st(4) , -.Li %st(5) , -.Li %st(6) , -and -.Li %st(7) . -These registers are overloaded by 8 MMX registers -.Li %mm0 , -.Li %mm1 , -.Li %mm2 , -.Li %mm3 , -.Li %mm4 , -.Li %mm5 , -.Li %mm6 -and -.Li %mm7 . -.Pp -.It -the 8 SSE registers registers -.Li %xmm0 , -.Li %xmm1 , -.Li %xmm2 , -.Li %xmm3 , -.Li %xmm4 , -.Li %xmm5 , -.Li %xmm6 -and -.Li %xmm7 . -.El -.Pp -The AMD x86-64 architecture extends the register set by: -.Pp -.Bl -bullet -.It -enhancing the 8 32-bit registers to 64-bit: -.Li %rax -(the accumulator), -.Li %rbx , -.Li %rcx , -.Li %rdx , -.Li %rdi , -.Li %rsi , -.Li %rbp -(the frame pointer), -.Li %rsp -(the stack pointer) -.Pp -.It -the 8 extended registers -.Li %r8 --- -.Li %r15 . -.Pp -.It -the 8 32-bit low ends of the extended registers: -.Li %r8d --- -.Li %r15d -.Pp -.It -the 8 16-bit low ends of the extended registers: -.Li %r8w --- -.Li %r15w -.Pp -.It -the 8 8-bit low ends of the extended registers: -.Li %r8b --- -.Li %r15b -.Pp -.It -the 4 8-bit registers: -.Li %sil , -.Li %dil , -.Li %bpl , -.Li %spl . -.Pp -.It -the 8 debug registers: -.Li %db8 --- -.Li %db15 . -.Pp -.It -the 8 SSE registers: -.Li %xmm8 --- -.Li %xmm15 . -.El -.Pp -.Ss Instruction Prefixes -Instruction prefixes are used to modify the following instruction. They are -used to repeat string instructions, to provide section overrides, to perform -bus lock operations, and to change operand and address sizes. (Most instructions -that normally operate on 32-bit operands will use 16-bit operands if the instruction -has an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the -same line as the instruction they act upon. For example, the -.Li scas -(scan string) instruction is repeated with: -.Pp -.Bd -literal -offset indent - repne scas %es:(%edi),%al -.Ed -.Pp -You may also place prefixes on the lines immediately preceding the instruction, -but this circumvents checks that -.Li as -does with prefixes, and will not work with all prefixes. -.Pp -Here is a list of instruction prefixes: -.Pp -.Bl -bullet -.It -Section override prefixes -.Li cs , -.Li ds , -.Li ss , -.Li es , -.Li fs , -.Li gs . -These are automatically added by specifying using the -.Va section -: -.Va memory-operand -form for memory references. -.Pp -.It -Operand/Address size prefixes -.Li data16 -and -.Li addr16 -change 32-bit operands/addresses into 16-bit operands/addresses, while -.Li data32 -and -.Li addr32 -change 16-bit ones (in a -.Li .code16 -section) into 32-bit operands/addresses. These prefixes -.Em must -appear on the same line of code as the instruction they modify. For example, -in a 16-bit -.Li .code16 -section, you might write: -.Pp -.Bd -literal -offset indent - addr32 jmpl *(%ebx) -.Ed -.Pp -.It -The bus lock prefix -.Li lock -inhibits interrupts during execution of the instruction it precedes. (This -is only valid with certain instructions; see a 80386 manual for details). -.Pp -.It -The wait for coprocessor prefix -.Li wait -waits for the coprocessor to complete the current instruction. This should -never be needed for the 80386/80387 combination. -.Pp -.It -The -.Li rep , -.Li repe , -and -.Li repne -prefixes are added to string instructions to make them repeat -.Li %ecx -times ( -.Li %cx -times if the current address size is 16-bits). -.It -The -.Li rex -family of prefixes is used by x86-64 to encode extensions to i386 instruction -set. The -.Li rex -prefix has four bits --- an operand size overwrite ( -.Li 64 ) -used to change operand size from 32-bit to 64-bit and X, Y and Z extensions -bits used to extend the register set. -.Pp -You may write the -.Li rex -prefixes directly. The -.Li rex64xyz -instruction emits -.Li rex -prefix with all the bits set. By omitting the -.Li 64 , -.Li x , -.Li y -or -.Li z -you may write other prefixes as well. Normally, there is no need to write -the prefixes explicitly, since gas will automatically generate them based -on the instruction operands. -.El -.Pp -.Ss Memory References -An Intel syntax indirect memory reference of the form -.Pp -.Bd -literal -offset indent -section:[base + index*scale + disp] -.Ed -.Pp -is translated into the AT&T syntax -.Pp -.Bd -literal -offset indent -section:disp(base, index, scale) -.Ed -.Pp -where -.Va base -and -.Va index -are the optional 32-bit base and index registers, -.Va disp -is the optional displacement, and -.Va scale , -taking the values 1, 2, 4, and 8, multiplies -.Va index -to calculate the address of the operand. If no -.Va scale -is specified, -.Va scale -is taken to be 1. -.Va section -specifies the optional section register for the memory operand, and may override -the default section register (see a 80386 manual for section register defaults). -Note that section overrides in AT&T syntax -.Em must -be preceded by a -.Li % . -If you specify a section override which coincides with the default section -register, -.Li as -does -.Em not -output any section register override prefixes to assemble the given instruction. -Thus, section overrides can be specified to emphasize which section register -is used for a given memory operand. -.Pp -Here are some examples of Intel and AT&T style memory references: -.Pp -.Bl -tag -width Ds -.It AT&T: Li -4(%ebp), Intel: Li [ebp - 4] -.Va base -is -.Li %ebp ; -.Va disp -is -.Li -4 . -.Va section -is missing, and the default section is used ( -.Li %ss -for addressing with -.Li %ebp -as the base register). -.Va index , -.Va scale -are both missing. -.Pp -.It AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4] -.Va index -is -.Li %eax -(scaled by a -.Va scale -4); -.Va disp -is -.Li foo . -All other fields are missing. The section register here defaults to -.Li %ds . -.Pp -.It AT&T: Li foo(,1); Intel Li [foo] -This uses the value pointed to by -.Li foo -as a memory operand. Note that -.Va base -and -.Va index -are both missing, but there is only -.Em one -.Li , . -This is a syntactic exception. -.Pp -.It AT&T: Li %gs:foo; Intel Li gs:foo -This selects the contents of the variable -.Li foo -with section register -.Va section -being -.Li %gs . -.El -.Pp -Absolute (as opposed to PC relative) call and jump operands must be prefixed -with -.Li * . -If no -.Li * -is specified, -.Li as -always chooses PC relative addressing for jump/call labels. -.Pp -Any instruction that has a memory operand, but no register operand, -.Em must -specify its size (byte, word, long, or quadruple) with an instruction mnemonic -suffix ( -.Li b , -.Li w , -.Li l -or -.Li q , -respectively). -.Pp -The x86-64 architecture adds an RIP (instruction pointer relative) addressing. -This addressing mode is specified by using -.Li rip -as a base register. Only constant offsets are valid. For example: -.Pp -.Bl -tag -width Ds -.It AT&T: Li 1234(%rip), Intel: Li [rip + 1234] -Points to the address 1234 bytes past the end of the current instruction. -.Pp -.It AT&T: Li symbol(%rip), Intel: Li [rip + symbol] -Points to the -.Li symbol -in RIP relative way, this is shorter than the default absolute addressing. -.El -.Pp -Other addressing modes remain unchanged in x86-64 architecture, except registers -used are 64-bit instead of 32-bit. -.Pp -.Ss Handling of Jump Instructions -Jump instructions are always optimized to use the smallest possible displacements. -This is accomplished by using byte (8-bit) displacement jumps whenever the -target is sufficiently close. If a byte displacement is insufficient a long -displacement is used. We do not support word (16-bit) displacement jumps in -32-bit mode (i.e. prefixing the jump instruction with the -.Li data16 -instruction prefix), since the 80386 insists upon masking -.Li %eip -to 16 bits after the word displacement is added. (See alsosee Section -.Dq i386-Arch ) -.Pp -Note that the -.Li jcxz , -.Li jecxz , -.Li loop , -.Li loopz , -.Li loope , -.Li loopnz -and -.Li loopne -instructions only come in byte displacements, so that if you use these instructions -( -.Li gcc -does not use them) you may get an error message (and incorrect code). The -AT&T 80386 assembler tries to get around this problem by expanding -.Li jcxz foo -to -.Pp -.Bd -literal -offset indent - jcxz cx_zero - jmp cx_nonzero -cx_zero: jmp foo -cx_nonzero: -.Ed -.Pp -.Ss Floating Point -All 80387 floating point types except packed BCD are supported. (BCD support -may be added without much difficulty). These data types are 16-, 32-, and -64- bit integers, and single (32-bit), double (64-bit), and extended (80-bit) -precision floating point. Each supported type has an instruction mnemonic -suffix and a constructor associated with it. Instruction mnemonic suffixes -specify the operand's data type. Constructors build these data types into -memory. -.Pp -.Bl -bullet -.It -Floating point constructors are -.Li .float -or -.Li .single , -.Li .double , -and -.Li .tfloat -for 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic -suffixes -.Li s , -.Li l , -and -.Li t . -.Li t -stands for 80-bit (ten byte) real. The 80387 only supports this format via -the -.Li fldt -(load 80-bit real to stack top) and -.Li fstpt -(store 80-bit real and pop stack) instructions. -.Pp -.It -Integer constructors are -.Li .word , -.Li .long -or -.Li .int , -and -.Li .quad -for the 16-, 32-, and 64-bit integer formats. The corresponding instruction -mnemonic suffixes are -.Li s -(single), -.Li l -(long), and -.Li q -(quad). As with the 80-bit real format, the 64-bit -.Li q -format is only present in the -.Li fildq -(load quad integer to stack top) and -.Li fistpq -(store quad integer and pop stack) instructions. -.El -.Pp -Register to register operations should not use instruction mnemonic suffixes. -.Li fstl %st, %st(1) -will give a warning, and be assembled as if you wrote -.Li fst %st, %st(1) , -since all register to register operations use 80-bit floating point operands. -(Contrast this with -.Li fstl %st, mem , -which converts -.Li %st -from 80-bit to 64-bit floating point format, then stores the result in the -4 byte location -.Li mem ) -.Pp -.Ss Intel's MMX and AMD's 3DNow! SIMD Operations -.Li as -supports Intel's MMX instruction set (SIMD instructions for integer data), -available on Intel's Pentium MMX processors and Pentium II processors, AMD's -K6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also -supports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating -point data) available on AMD's K6-2 processor and possibly others in the future. -.Pp -Currently, -.Li as -does not support Intel's floating point SIMD, Katmai (KNI). -.Pp -The eight 64-bit MMX operands, also used by 3DNow!, are called -.Li %mm0 , -.Li %mm1 , -\&... -.Li %mm7 . -They contain eight 8-bit integers, four 16-bit integers, two 32-bit integers, -one 64-bit integer, or two 32-bit floating point values. The MMX registers -cannot be used at the same time as the floating point stack. -.Pp -See Intel and AMD documentation, keeping in mind that the operand order in -instructions is reversed from the Intel syntax. -.Pp -.Ss Writing 16-bit Code -While -.Li as -normally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending -on the default configuration, it also supports writing code to run in real -mode or in 16-bit protected mode code segments. To do this, put a -.Li .code16 -or -.Li .code16gcc -directive before the assembly language instructions to be run in 16-bit mode. -You can switch -.Li as -back to writing normal 32-bit code with the -.Li .code32 -directive. -.Pp -.Li .code16gcc -provides experimental support for generating 16-bit code from gcc, and differs -from -.Li .code16 -in that -.Li call , -.Li ret , -.Li enter , -.Li leave , -.Li push , -.Li pop , -.Li pusha , -.Li popa , -.Li pushf , -and -.Li popf -instructions default to 32-bit size. This is so that the stack pointer is -manipulated in the same way over function calls, allowing access to function -parameters at the same stack offsets as in 32-bit mode. -.Li .code16gcc -also automatically adds address size prefixes where necessary to use the 32-bit -addressing modes that gcc generates. -.Pp -The code which -.Li as -generates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor. -To write code that runs on such a processor, you must refrain from using -.Em any -32-bit constructs which require -.Li as -to output address or operand size prefixes. -.Pp -Note that writing 16-bit code instructions by explicitly specifying a prefix -or an instruction mnemonic suffix within a 32-bit code section generates different -machine instructions than those generated for a 16-bit code segment. In a -32-bit code section, the following code generates the machine opcode bytes -.Li 66 6a 04 , -which pushes the value -.Li 4 -onto the stack, decrementing -.Li %esp -by 2. -.Pp -.Bd -literal -offset indent - pushw $4 -.Ed -.Pp -The same code in a 16-bit code section would generate the machine opcode bytes -.Li 6a 04 -(i.e., without the operand size prefix), which is correct since the processor -default operand size is assumed to be 16 bits in a 16-bit code section. -.Pp -.Ss AT&T Syntax bugs -The UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers, -generate floating point instructions with reversed source and destination -registers in certain cases. Unfortunately, gcc and possibly many other programs -use this reversed syntax, so we're stuck with it. -.Pp -For example -.Pp -.Bd -literal -offset indent - fsub %st,%st(3) -.Ed -results in -.Li %st(3) -being updated to -.Li %st - %st(3) -rather than the expected -.Li %st(3) - %st . -This happens with all the non-commutative arithmetic floating point operations -with two register operands where the source register is -.Li %st -and the destination register is -.Li %st(i) . -.Pp -.Ss Specifying CPU Architecture -.Li as -may be told to assemble for a particular CPU (sub-)architecture with the -.Li .arch Va cpu_type -directive. This directive enables a warning when gas detects an instruction -that is not supported on the CPU specified. The choices for -.Va cpu_type -are: -.Pp -.TS -l l l l. - -i8086 i186 i286 i386 -i486 i586 i686 pentium -pentiumpro pentiumii pentiumiii pentium4 -prescott nocona core core2 -amdfam10 -k6 athlon sledgehammer k8 -\&.mmx .sse .sse2 .sse3 -\&.ssse3 .sse4.1 .sse4.2 .sse4 -\&.sse4a .3dnow .3dnowa .padlock -\&.pacifica .svme .abm -.TE -.Pp -Apart from the warning, there are only two other effects on -.Li as -operation; Firstly, if you specify a CPU other than -.Li i486 , -then shift by one instructions such as -.Li sarl $1, %eax -will automatically use a two byte opcode sequence. The larger three byte opcode -sequence is used on the 486 (and when no architecture is specified) because -it executes faster on the 486. Note that you can explicitly request the two -byte opcode by writing -.Li sarl %eax . -Secondly, if you specify -.Li i8086 , -.Li i186 , -or -.Li i286 , -.Em and -.Li .code16 -or -.Li .code16gcc -then byte offset conditional jumps will be promoted when necessary to a two -instruction sequence consisting of a conditional jump of the opposite sense -around an unconditional jump to the target. -.Pp -Following the CPU architecture (but not a sub-architecture, which are those -starting with a dot), you may specify -.Li jumps -or -.Li nojumps -to control automatic promotion of conditional jumps. -.Li jumps -is the default, and enables jump promotion; All external jumps will be of -the long variety, and file-local jumps will be promoted as necessary. (see Section -.Dq i386-Jumps ) -.Li nojumps -leaves external conditional jumps as byte offset jumps, and warns about file-local -conditional jumps that -.Li as -promotes. Unconditional jumps are treated as for -.Li jumps . -.Pp -For example -.Pp -.Bd -literal -offset indent - .arch i8086,nojumps -.Ed -.Pp -.Ss Notes -There is some trickery concerning the -.Li mul -and -.Li imul -instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding -multiplies (base opcode -.Li 0xf6 ; -extension 4 for -.Li mul -and 5 for -.Li imul ) -can be output only in the one operand form. Thus, -.Li imul %ebx, %eax -does -.Em not -select the expanding multiply; the expanding multiply would clobber the -.Li %edx -register, and this would confuse -.Li gcc -output. Use -.Li imul %ebx -to get the 64-bit product in -.Li %edx:%eax . -.Pp -We have added a two operand form of -.Li imul -when the first operand is an immediate mode expression and the second operand -is a register. This is just a shorthand, so that, multiplying -.Li %eax -by 69, for example, can be done with -.Li imul $69, %eax -rather than -.Li imul $69, %eax, %eax . -.Pp -.Sh IA-64 Dependent Features -.Ss Options -.Bl -tag -width Ds -.It -mconstant-gp -This option instructs the assembler to mark the resulting object file as using -the \(lqconstant GP\(rq model. With this model, it is assumed that the entire program -uses a single global pointer (GP) value. Note that this option does not in -any fashion affect the machine code emitted by the assembler. All it does -is turn on the EF_IA_64_CONS_GP flag in the ELF file header. -.Pp -.It -mauto-pic -This option instructs the assembler to mark the resulting object file as using -the \(lqconstant GP without function descriptor\(rq data model. This model is like -the \(lqconstant GP\(rq model, except that it additionally does away with function -descriptors. What this means is that the address of a function refers directly -to the function's code entry-point. Normally, such an address would refer -to a function descriptor, which contains both the code entry-point and the -GP-value needed by the function. Note that this option does not in any fashion -affect the machine code emitted by the assembler. All it does is turn on the -EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header. -.Pp -.It -milp32 -.It -milp64 -.It -mlp64 -.It -mp64 -These options select the data model. The assembler defaults to -.Li -mlp64 -(LP64 data model). -.Pp -.It -mle -.It -mbe -These options select the byte order. The -.Li -mle -option selects little-endian byte order (default) and -.Li -mbe -selects big-endian byte order. Note that IA-64 machine code always uses little-endian -byte order. -.Pp -.It -mtune=itanium1 -.It -mtune=itanium2 -Tune for a particular IA-64 CPU, -.Va itanium1 -or -.Va itanium2 . -The default is -.Va itanium2 . -.Pp -.It -munwind-check=warning -.It -munwind-check=error -These options control what the assembler will do when performing consistency -checks on unwind directives. -.Li -munwind-check=warning -will make the assembler issue a warning when an unwind directive check fails. -This is the default. -.Li -munwind-check=error -will make the assembler issue an error when an unwind directive check fails. -.Pp -.It -mhint.b=ok -.It -mhint.b=warning -.It -mhint.b=error -These options control what the assembler will do when the -.Li hint.b -instruction is used. -.Li -mhint.b=ok -will make the assembler accept -.Li hint.b . -.Li -mint.b=warning -will make the assembler issue a warning when -.Li hint.b -is used. -.Li -mhint.b=error -will make the assembler treat -.Li hint.b -as an error, which is the default. -.Pp -.It -x -.It -xexplicit -These options turn on dependency violation checking. -.Pp -.It -xauto -This option instructs the assembler to automatically insert stop bits where -necessary to remove dependency violations. This is the default mode. -.Pp -.It -xnone -This option turns off dependency violation checking. -.Pp -.It -xdebug -This turns on debug output intended to help tracking down bugs in the dependency -violation checker. -.Pp -.It -xdebugn -This is a shortcut for -xnone -xdebug. -.Pp -.It -xdebugx -This is a shortcut for -xexplicit -xdebug. -.Pp -.El -.Ss Syntax -The assembler syntax closely follows the IA-64 Assembly Language Reference -Guide. -.Pp -.Em Special Characters -.Pp -.Li // -is the line comment token. -.Pp -.Li ; -can be used instead of a newline to separate statements. -.Pp -.Em Register Names -.Pp -The 128 integer registers are referred to as -.Li r Va n . -The 128 floating-point registers are referred to as -.Li f Va n . -The 128 application registers are referred to as -.Li ar Va n . -The 128 control registers are referred to as -.Li cr Va n . -The 64 one-bit predicate registers are referred to as -.Li p Va n . -The 8 branch registers are referred to as -.Li b Va n . -In addition, the assembler defines a number of aliases: -.Li gp -( -.Li r1 ) , -.Li sp -( -.Li r12 ) , -.Li rp -( -.Li b0 ) , -.Li ret0 -( -.Li r8 ) , -.Li ret1 -( -.Li r9 ) , -.Li ret2 -( -.Li r10 ) , -.Li ret3 -( -.Li r9 ) , -.Li farg Va n -( -.Li f8+ Va n ) , -and -.Li fret Va n -( -.Li f8+ Va n ) . -.Pp -For convenience, the assembler also defines aliases for all named application -and control registers. For example, -.Li ar.bsp -refers to the register backing store pointer ( -.Li ar17 ) . -Similarly, -.Li cr.eoi -refers to the end-of-interrupt register ( -.Li cr67 ) . -.Pp -.Em IA-64 Processor-Status-Register (PSR) Bit Names -.Pp -The assembler defines bit masks for each of the bits in the IA-64 processor -status register. For example, -.Li psr.ic -corresponds to a value of 0x2000. These masks are primarily intended for use -with the -.Li ssm -/ -.Li sum -and -.Li rsm -/ -.Li rum -instructions, but they can be used anywhere else where an integer constant -is expected. -.Pp -.Ss Opcodes -For detailed information on the IA-64 machine instruction set, see the -.Lk http://developer.intel.com/design/itanium/arch_spec.htm . -.Pp -.Sh MIPS Dependent Features -GNU -.Li as -for mips architectures supports several different mips processors, and MIPS -ISA levels I through V, MIPS32, and MIPS64. For information about the mips -instruction set, see -.Em MIPS RISC Architecture , -by Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions, -see \(lqAppendix D: Assembly Language Programming\(rq in the same work. -.Pp -.Ss Assembler options -The mips configurations of GNU -.Li as -support these special options: -.Pp -.Bl -tag -width Ds -.It -G Va num -This option sets the largest size of an object that can be referenced implicitly -with the -.Li gp -register. It is only accepted for targets that use ecoff format. The default -value is 8. -.Pp -.It -EB -.It -EL -Any mips configuration of -.Li as -can select big-endian or little-endian output at run time (unlike the other -GNU development tools, which must be configured for one or the other). Use -.Li -EB -to select big-endian output, and -.Li -EL -for little-endian. -.Pp -.It -KPIC -Generate SVR4-style PIC. This option tells the assembler to generate SVR4-style -position-independent macro expansions. It also tells the assembler to mark -the output file as PIC. -.Pp -.It -mvxworks-pic -Generate VxWorks PIC. This option tells the assembler to generate VxWorks-style -position-independent macro expansions. -.Pp -.It -mips1 -.It -mips2 -.It -mips3 -.It -mips4 -.It -mips5 -.It -mips32 -.It -mips32r2 -.It -mips64 -.It -mips64r2 -Generate code for a particular MIPS Instruction Set Architecture level. -.Li -mips1 -corresponds to the r2000 and r3000 processors, -.Li -mips2 -to the r6000 processor, -.Li -mips3 -to the r4000 processor, and -.Li -mips4 -to the r8000 and r10000 processors. -.Li -mips5 , -.Li -mips32 , -.Li -mips32r2 , -.Li -mips64 , -and -.Li -mips64r2 -correspond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64 -Release 2 ISA processors, respectively. You can also switch instruction sets -during the assembly; see MIPS ISA, Directives to override the ISA level. -.Pp -.It -mgp32 -.It -mfp32 -Some macros have different expansions for 32-bit and 64-bit registers. The -register sizes are normally inferred from the ISA and ABI, but these flags -force a certain group of registers to be treated as 32 bits wide at all times. -.Li -mgp32 -controls the size of general-purpose registers and -.Li -mfp32 -controls the size of floating-point registers. -.Pp -The -.Li .set gp=32 -and -.Li .set fp=32 -directives allow the size of registers to be changed for parts of an object. -The default value is restored by -.Li .set gp=default -and -.Li .set fp=default . -.Pp -On some MIPS variants there is a 32-bit mode flag; when this flag is set, -64-bit instructions generate a trap. Also, some 32-bit OSes only save the -32-bit registers on a context switch, so it is essential never to use the -64-bit registers. -.Pp -.It -mgp64 -.It -mfp64 -Assume that 64-bit registers are available. This is provided in the interests -of symmetry with -.Li -mgp32 -and -.Li -mfp32 . -.Pp -The -.Li .set gp=64 -and -.Li .set fp=64 -directives allow the size of registers to be changed for parts of an object. -The default value is restored by -.Li .set gp=default -and -.Li .set fp=default . -.Pp -.It -mips16 -.It -no-mips16 -Generate code for the MIPS 16 processor. This is equivalent to putting -.Li .set mips16 -at the start of the assembly file. -.Li -no-mips16 -turns off this option. -.Pp -.It -msmartmips -.It -mno-smartmips -Enables the SmartMIPS extensions to the MIPS32 instruction set, which provides -a number of new instructions which target smartcard and cryptographic applications. -This is equivalent to putting -.Li .set smartmips -at the start of the assembly file. -.Li -mno-smartmips -turns off this option. -.Pp -.It -mips3d -.It -no-mips3d -Generate code for the MIPS-3D Application Specific Extension. This tells the -assembler to accept MIPS-3D instructions. -.Li -no-mips3d -turns off this option. -.Pp -.It -mdmx -.It -no-mdmx -Generate code for the MDMX Application Specific Extension. This tells the -assembler to accept MDMX instructions. -.Li -no-mdmx -turns off this option. -.Pp -.It -mdsp -.It -mno-dsp -Generate code for the DSP Release 1 Application Specific Extension. This tells -the assembler to accept DSP Release 1 instructions. -.Li -mno-dsp -turns off this option. -.Pp -.It -mdspr2 -.It -mno-dspr2 -Generate code for the DSP Release 2 Application Specific Extension. This option -implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. -.Li -mno-dspr2 -turns off this option. -.Pp -.It -mmt -.It -mno-mt -Generate code for the MT Application Specific Extension. This tells the assembler -to accept MT instructions. -.Li -mno-mt -turns off this option. -.Pp -.It -mfix7000 -.It -mno-fix7000 -Cause nops to be inserted if the read of the destination register of an mfhi -or mflo instruction occurs in the following two instructions. -.Pp -.It -mfix-vr4120 -.It -no-mfix-vr4120 -Insert nops to work around certain VR4120 errata. This option is intended -to be used on GCC-generated code: it is not designed to catch all problems -in hand-written assembler code. -.Pp -.It -mfix-vr4130 -.It -no-mfix-vr4130 -Insert nops to work around the VR4130 -.Li mflo -/ -.Li mfhi -errata. -.Pp -.It -m4010 -.It -no-m4010 -Generate code for the LSI r4010 chip. This tells the assembler to accept the -r4010 specific instructions ( -.Li addciu , -.Li ffc , -etc.), and to not schedule -.Li nop -instructions around accesses to the -.Li HI -and -.Li LO -registers. -.Li -no-m4010 -turns off this option. -.Pp -.It -m4650 -.It -no-m4650 -Generate code for the MIPS r4650 chip. This tells the assembler to accept -the -.Li mad -and -.Li madu -instruction, and to not schedule -.Li nop -instructions around accesses to the -.Li HI -and -.Li LO -registers. -.Li -no-m4650 -turns off this option. -.Pp -.It -m3900 -.It -no-m3900 -.It -m4100 -.It -no-m4100 -For each option -.Li -m Va nnnn , -generate code for the MIPS r -.Va nnnn -chip. This tells the assembler to accept instructions specific to that chip, -and to schedule for that chip's hazards. -.Pp -.It -march= Va cpu -Generate code for a particular MIPS cpu. It is exactly equivalent to -.Li -m Va cpu , -except that there are more value of -.Va cpu -understood. Valid -.Va cpu -value are: -.Pp -.Qo -2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400, -4600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500, -6000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, -4kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, -34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a -.Qc -.Pp -.It -mtune= Va cpu -Schedule and tune for a particular MIPS cpu. Valid -.Va cpu -values are identical to -.Li -march= Va cpu . -.Pp -.It -mabi= Va abi -Record which ABI the source code uses. The recognized arguments are: -.Li 32 , -.Li n32 , -.Li o64 , -.Li 64 -and -.Li eabi . -.Pp -.It -msym32 -.It -mno-sym32 -Equivalent to adding -.Li .set sym32 -or -.Li .set nosym32 -to the beginning of the assembler input.See Section -.Dq MIPS symbol sizes . -.Pp -.It -nocpp -This option is ignored. It is accepted for command-line compatibility with -other assemblers, which use it to turn off C style preprocessing. With GNU -.Li as , -there is no need for -.Li -nocpp , -because the GNU assembler itself never runs the C preprocessor. -.Pp -.It --construct-floats -.It --no-construct-floats -The -.Li --no-construct-floats -option disables the construction of double width floating point constants -by loading the two halves of the value into the two single width floating -point registers that make up the double width register. This feature is useful -if the processor support the FR bit in its status register, and this bit is -known (by the programmer) to be set. This bit prevents the aliasing of the -double width register by the single width registers. -.Pp -By default -.Li --construct-floats -is selected, allowing construction of these floating point constants. -.Pp -.It --trap -.It --no-break -.Li as -automatically macro expands certain division and multiplication instructions -to check for overflow and division by zero. This option causes -.Li as -to generate code to take a trap exception rather than a break exception when -an error is detected. The trap instructions are only supported at Instruction -Set Architecture level 2 and higher. -.Pp -.It --break -.It --no-trap -Generate code to take a break exception rather than a trap exception when -an error is detected. This is the default. -.Pp -.It -mpdr -.It -mno-pdr -Control generation of -.Li .pdr -sections. Off by default on IRIX, on elsewhere. -.Pp -.It -mshared -.It -mno-shared -When generating code using the Unix calling conventions (selected by -.Li -KPIC -or -.Li -mcall_shared ) , -gas will normally generate code which can go into a shared library. The -.Li -mno-shared -option tells gas to generate code which uses the calling convention, but can -not go into a shared library. The resulting code is slightly more efficient. -This option only affects the handling of the -.Li .cpload -and -.Li .cpsetup -pseudo-ops. -.El -.Pp -.Ss MIPS ECOFF object code -Assembling for a mips ecoff target supports some additional sections besides -the usual -.Li .text , -.Li .data -and -.Li .bss . -The additional sections are -.Li .rdata , -used for read-only data, -.Li .sdata , -used for small data, and -.Li .sbss , -used for small common objects. -.Pp -When assembling for ecoff, the assembler uses the -.Li $gp -( -.Li $28 ) -register to form the address of a \(lqsmall object\(rq. Any object in the -.Li .sdata -or -.Li .sbss -sections is considered \(lqsmall\(rq in this sense. For external objects, or for objects -in the -.Li .bss -section, you can use the -.Li gcc -.Li -G -option to control the size of objects addressed via -.Li $gp ; -the default value is 8, meaning that a reference to any object eight bytes -or smaller uses -.Li $gp . -Passing -.Li -G 0 -to -.Li as -prevents it from using the -.Li $gp -register on the basis of object size (but the assembler uses -.Li $gp -for objects in -.Li .sdata -or -.Li sbss -in any case). The size of an object in the -.Li .bss -section is set by the -.Li .comm -or -.Li .lcomm -directive that defines it. The size of an external object may be set with -the -.Li .extern -directive. For example, -.Li .extern sym,4 -declares that the object at -.Li sym -is 4 bytes in length, whie leaving -.Li sym -otherwise undefined. -.Pp -Using small ecoff objects requires linker support, and assumes that the -.Li $gp -register is correctly initialized (normally done automatically by the startup -code). mips ecoff assembly code must not modify the -.Li $gp -register. -.Pp -.Ss Directives for debugging information -mips ecoff -.Li as -supports several directives used for generating debugging information which -are not support by traditional mips assemblers. These are -.Li .def , -.Li .endef , -.Li .dim , -.Li .file , -.Li .scl , -.Li .size , -.Li .tag , -.Li .type , -.Li .val , -.Li .stabd , -.Li .stabn , -and -.Li .stabs . -The debugging information generated by the three -.Li .stab -directives can only be read by gdb, not by traditional mips debuggers (this -enhancement is required to fully support C++ debugging). These directives -are primarily used by compilers, not assembly language programmers! -.Pp -.Ss Directives to override the size of symbols -The n64 ABI allows symbols to have any 64-bit value. Although this provides -a great deal of flexibility, it means that some macros have much longer expansions -than their 32-bit counterparts. For example, the non-PIC expansion of -.Li dla $4,sym -is usually: -.Pp -.Bd -literal -offset indent -lui $4,%highest(sym) -lui $1,%hi(sym) -daddiu $4,$4,%higher(sym) -daddiu $1,$1,%lo(sym) -dsll32 $4,$4,0 -daddu $4,$4,$1 -.Ed -.Pp -whereas the 32-bit expansion is simply: -.Pp -.Bd -literal -offset indent -lui $4,%hi(sym) -daddiu $4,$4,%lo(sym) -.Ed -.Pp -n64 code is sometimes constructed in such a way that all symbolic constants -are known to have 32-bit values, and in such cases, it's preferable to use -the 32-bit expansion instead of the 64-bit expansion. -.Pp -You can use the -.Li .set sym32 -directive to tell the assembler that, from this point on, all expressions -of the form -.Li Va symbol -or -.Li Va symbol + Va offset -have 32-bit values. For example: -.Pp -.Bd -literal -offset indent -\&.set sym32 -dla $4,sym -lw $4,sym+16 -sw $4,sym+0x8000($4) -.Ed -.Pp -will cause the assembler to treat -.Li sym , -.Li sym+16 -and -.Li sym+0x8000 -as 32-bit values. The handling of non-symbolic addresses is not affected. -.Pp -The directive -.Li .set nosym32 -ends a -.Li .set sym32 -block and reverts to the normal behavior. It is also possible to change the -symbol size using the command-line options -.Op -msym32 -and -.Op -mno-sym32 . -.Pp -These options and directives are always accepted, but at present, they have -no effect for anything other than n64. -.Pp -.Ss Directives to override the ISA level -GNU -.Li as -supports an additional directive to change the mips Instruction Set Architecture -level on the fly: -.Li .set mips Va n . -.Va n -should be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other -than 0 make the assembler accept instructions for the corresponding isa level, -from that point on in the assembly. -.Li .set mips Va n -affects not only which instructions are permitted, but also how certain macros -are expanded. -.Li .set mips0 -restores the isa level to its original level: either the level you selected -with command line options, or the default for your configuration. You can -use this feature to permit specific mips3 instructions while assembling in -32 bit mode. Use this directive with care! -.Pp -The -.Li .set arch= Va cpu -directive provides even finer control. It changes the effective CPU target -and allows the assembler to use instructions specific to a particular CPU. -All CPUs supported by the -.Li -march -command line option are also selectable by this directive. The original value -is restored by -.Li .set arch=default . -.Pp -The directive -.Li .set mips16 -puts the assembler into MIPS 16 mode, in which it will assemble instructions -for the MIPS 16 processor. Use -.Li .set nomips16 -to return to normal 32 bit mode. -.Pp -Traditional mips assemblers do not support this directive. -.Pp -.Ss Directives for extending MIPS 16 bit instructions -By default, MIPS 16 instructions are automatically extended to 32 bits when -necessary. The directive -.Li .set noautoextend -will turn this off. When -.Li .set noautoextend -is in effect, any 32 bit instruction must be explicitly extended with the -.Li .e -modifier (e.g., -.Li li.e $4,1000 ) . -The directive -.Li .set autoextend -may be used to once again automatically extend instructions when necessary. -.Pp -This directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers -do not support this directive. -.Pp -.Ss Directive to mark data as an instruction -The -.Li .insn -directive tells -.Li as -that the following data is actually instructions. This makes a difference -in MIPS 16 mode: when loading the address of a label which precedes instructions, -.Li as -automatically adds 1 to the value, so that jumping to the loaded address will -do the right thing. -.Pp -.Ss Directives to save and restore options -The directives -.Li .set push -and -.Li .set pop -may be used to save and restore the current settings for all the options which -are controlled by -.Li .set . -The -.Li .set push -directive saves the current settings on a stack. The -.Li .set pop -directive pops the stack and restores the settings. -.Pp -These directives can be useful inside an macro which must change an option -such as the ISA level or instruction reordering but does not want to change -the state of the code which invoked the macro. -.Pp -Traditional mips assemblers do not support these directives. -.Pp -.Ss Directives to control generation of MIPS ASE instructions -The directive -.Li .set mips3d -makes the assembler accept instructions from the MIPS-3D Application Specific -Extension from that point on in the assembly. The -.Li .set nomips3d -directive prevents MIPS-3D instructions from being accepted. -.Pp -The directive -.Li .set smartmips -makes the assembler accept instructions from the SmartMIPS Application Specific -Extension to the MIPS32 isa from that point on in the assembly. The -.Li .set nosmartmips -directive prevents SmartMIPS instructions from being accepted. -.Pp -The directive -.Li .set mdmx -makes the assembler accept instructions from the MDMX Application Specific -Extension from that point on in the assembly. The -.Li .set nomdmx -directive prevents MDMX instructions from being accepted. -.Pp -The directive -.Li .set dsp -makes the assembler accept instructions from the DSP Release 1 Application -Specific Extension from that point on in the assembly. The -.Li .set nodsp -directive prevents DSP Release 1 instructions from being accepted. -.Pp -The directive -.Li .set dspr2 -makes the assembler accept instructions from the DSP Release 2 Application -Specific Extension from that point on in the assembly. This dirctive implies -.Li .set dsp . -The -.Li .set nodspr2 -directive prevents DSP Release 2 instructions from being accepted. -.Pp -The directive -.Li .set mt -makes the assembler accept instructions from the MT Application Specific Extension -from that point on in the assembly. The -.Li .set nomt -directive prevents MT instructions from being accepted. -.Pp -Traditional mips assemblers do not support these directives. -.Pp -.Sh PowerPC Dependent Features -.Ss Options -The PowerPC chip family includes several successive levels, using the same -core instruction set, but including a few additional instructions at each -level. There are exceptions to this however. For details on what instructions -each variant supports, please see the chip's architecture reference manual. -.Pp -The following table lists all available PowerPC options. -.Pp -.Bl -tag -width Ds -.It -mpwrx | -mpwr2 -Generate code for POWER/2 (RIOS2). -.Pp -.It -mpwr -Generate code for POWER (RIOS1) -.Pp -.It -m601 -Generate code for PowerPC 601. -.Pp -.It -mppc, -mppc32, -m603, -m604 -Generate code for PowerPC 603/604. -.Pp -.It -m403, -m405 -Generate code for PowerPC 403/405. -.Pp -.It -m440 -Generate code for PowerPC 440. BookE and some 405 instructions. -.Pp -.It -m7400, -m7410, -m7450, -m7455 -Generate code for PowerPC 7400/7410/7450/7455. -.Pp -.It -mppc64, -m620 -Generate code for PowerPC 620/625/630. -.Pp -.It -me500, -me500x2 -Generate code for Motorola e500 core complex. -.Pp -.It -mspe -Generate code for Motorola SPE instructions. -.Pp -.It -mppc64bridge -Generate code for PowerPC 64, including bridge insns. -.Pp -.It -mbooke64 -Generate code for 64-bit BookE. -.Pp -.It -mbooke, mbooke32 -Generate code for 32-bit BookE. -.Pp -.It -me300 -Generate code for PowerPC e300 family. -.Pp -.It -maltivec -Generate code for processors with AltiVec instructions. -.Pp -.It -mpower4 -Generate code for Power4 architecture. -.Pp -.It -mpower5 -Generate code for Power5 architecture. -.Pp -.It -mpower6 -Generate code for Power6 architecture. -.Pp -.It -mcell -Generate code for Cell Broadband Engine architecture. -.Pp -.It -mcom -Generate code Power/PowerPC common instructions. -.Pp -.It -many -Generate code for any architecture (PWR/PWRX/PPC). -.Pp -.It -mregnames -Allow symbolic names for registers. -.Pp -.It -mno-regnames -Do not allow symbolic names for registers. -.Pp -.It -mrelocatable -Support for GCC's -mrelocatable option. -.Pp -.It -mrelocatable-lib -Support for GCC's -mrelocatable-lib option. -.Pp -.It -memb -Set PPC_EMB bit in ELF flags. -.Pp -.It -mlittle, -mlittle-endian -Generate code for a little endian machine. -.Pp -.It -mbig, -mbig-endian -Generate code for a big endian machine. -.Pp -.It -msolaris -Generate code for Solaris. -.Pp -.It -mno-solaris -Do not generate code for Solaris. -.El -.Pp -.Ss PowerPC Assembler Directives -A number of assembler directives are available for PowerPC. The following -table is far from complete. -.Pp -.Bl -tag -width Ds -.It .machine "string" -This directive allows you to change the machine for which code is generated. -.Li "string" -may be any of the -m cpu selection options (without the -m) enclosed in double -quotes, -.Li "push" , -or -.Li "pop" . -.Li .machine "push" -saves the currently selected cpu, which may be restored with -.Li .machine "pop" . -.El -.Pp -.Sh SPARC Dependent Features -.Ss Options -The SPARC chip family includes several successive levels, using the same core -instruction set, but including a few additional instructions at each level. -There are exceptions to this however. For details on what instructions each -variant supports, please see the chip's architecture reference manual. -.Pp -By default, -.Li as -assumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level -as needed: it switches to successively higher architectures as it encounters -instructions that only exist in the higher levels. -.Pp -If not configured for SPARC v9 ( -.Li sparc64-*-* ) -GAS will not bump passed sparclite by default, an option must be passed to -enable the v9 instructions. -.Pp -GAS treats sparclite as being compatible with v8, unless an architecture is -explicitly requested. SPARC v9 is always incompatible with sparclite. -.Pp -.Bl -tag -width Ds -.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite -.It -Av8plus | -Av8plusa | -Av9 | -Av9a -Use one of the -.Li -A -options to select one of the SPARC architectures explicitly. If you select -an architecture explicitly, -.Li as -reports a fatal error if it encounters an instruction or feature requiring -an incompatible or higher level. -.Pp -.Li -Av8plus -and -.Li -Av8plusa -select a 32 bit environment. -.Pp -.Li -Av9 -and -.Li -Av9a -select a 64 bit environment and are not available unless GAS is explicitly -configured with 64 bit environment support. -.Pp -.Li -Av8plusa -and -.Li -Av9a -enable the SPARC V9 instruction set with UltraSPARC extensions. -.Pp -.It -xarch=v8plus | -xarch=v8plusa -For compatibility with the Solaris v9 assembler. These options are equivalent -to -Av8plus and -Av8plusa, respectively. -.Pp -.It -bump -Warn whenever it is necessary to switch to another level. If an architecture -level is explicitly requested, GAS will not issue warnings until that level -is reached, and will then bump the level as required (except between incompatible -levels). -.Pp -.It -32 | -64 -Select the word size, either 32 bits or 64 bits. These options are only available -with the ELF object file format, and require that the necessary BFD support -has been included. -.El -.Pp -.Ss Enforcing aligned data -SPARC GAS normally permits data to be misaligned. For example, it permits -the -.Li .long -pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris -assemblers issue an error when they see misaligned data. -.Pp -You can use the -.Li --enforce-aligned-data -option to make SPARC GAS also issue an error about misaligned data, just as -the SunOS and Solaris assemblers do. -.Pp -The -.Li --enforce-aligned-data -option is not the default because gcc issues misaligned data pseudo-ops when -it initializes certain packed data structures (structures defined using the -.Li packed -attribute). You may have to assemble with GAS in order to initialize packed -data structures in your own code. -.Pp -.Ss Floating Point -The Sparc uses ieee floating-point numbers. -.Pp -.Ss Sparc Machine Directives -The Sparc version of -.Li as -supports the following additional machine directives: -.Pp -.Bl -tag -width Ds -.It .align -This must be followed by the desired alignment in bytes. -.Pp -.It .common -This must be followed by a symbol name, a positive number, and -.Li "bss" . -This behaves somewhat like -.Li .comm , -but the syntax is different. -.Pp -.It .half -This is functionally identical to -.Li .short . -.Pp -.It .nword -On the Sparc, the -.Li .nword -directive produces native word sized value, ie. if assembling with -32 it -is equivalent to -.Li .word , -if assembling with -64 it is equivalent to -.Li .xword . -.Pp -.It .proc -This directive is ignored. Any text following it on the same line is also -ignored. -.Pp -.It .register -This directive declares use of a global application or system register. It -must be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol -name for that register. If symbol name is -.Li #scratch , -it is a scratch register, if it is -.Li #ignore , -it just suppresses any errors about using undeclared global register, but -does not emit any information about it into the object file. This can be useful -e.g. if you save the register before use and restore it after. -.Pp -.It .reserve -This must be followed by a symbol name, a positive number, and -.Li "bss" . -This behaves somewhat like -.Li .lcomm , -but the syntax is different. -.Pp -.It .seg -This must be followed by -.Li "text" , -.Li "data" , -or -.Li "data1" . -It behaves like -.Li .text , -.Li .data , -or -.Li .data 1 . -.Pp -.It .skip -This is functionally identical to the -.Li .space -directive. -.Pp -.It .word -On the Sparc, the -.Li .word -directive produces 32 bit values, instead of the 16 bit values it produces -on many other machines. -.Pp -.It .xword -On the Sparc V9 processor, the -.Li .xword -directive produces 64 bit values. -.El -.Pp -.Sh Reporting Bugs -Your bug reports play an essential role in making -.Xr as -reliable. -.Pp -Reporting a bug may help you by bringing a solution to your problem, or it -may not. But in any case the principal function of a bug report is to help -the entire community by making the next version of -.Xr as -work better. Bug reports are your contribution to the maintenance of -.Xr as . -.Pp -In order for a bug report to serve its purpose, you must include the information -that enables us to fix the bug. -.Pp -.Ss Have You Found a Bug? -If you are not sure whether you have found a bug, here are some guidelines: -.Pp -.Bl -bullet -.It -If the assembler gets a fatal signal, for any input whatever, that is a -.Xr as -bug. Reliable assemblers never crash. -.Pp -.It -If -.Xr as -produces an error message for valid input, that is a bug. -.Pp -.It -If -.Xr as -does not produce an error message for invalid input, that is a bug. However, -you should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq -or \(lqsupport for traditional practice\(rq. -.Pp -.It -If you are an experienced user of assemblers, your suggestions for improvement -of -.Xr as -are welcome in any case. -.El -.Pp -.Ss How to Report Bugs -A number of companies and individuals offer support for GNU products. If you -obtained -.Xr as -from a support organization, we recommend you contact that organization first. -.Pp -You can find contact information for many support companies and individuals -in the file -.Pa etc/SERVICE -in the GNU Emacs distribution. -.Pp -The fundamental principle of reporting bugs usefully is this: -.Sy report all the facts . -If you are not sure whether to state a fact or leave it out, state it! -.Pp -Often people omit facts because they think they know what causes the problem -and assume that some details do not matter. Thus, you might assume that the -name of a symbol you use in an example does not matter. Well, probably it -does not, but one cannot be sure. Perhaps the bug is a stray memory reference -which happens to fetch from the location where that name is stored in memory; -perhaps, if the name were different, the contents of that location would fool -the assembler into doing the right thing despite the bug. Play it safe and -give a specific, complete example. That is the easiest thing for you to do, -and the most helpful. -.Pp -Keep in mind that the purpose of a bug report is to enable us to fix the bug -if it is new to us. Therefore, always write your bug reports on the assumption -that the bug has not been reported previously. -.Pp -Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq -This cannot help us fix a bug, so it is basically useless. We respond by asking -for enough details to enable us to investigate. You might as well expedite -matters by sending them to begin with. -.Pp -To enable us to fix the bug, you should include all these things: -.Pp -.Bl -bullet -.It -The version of -.Xr as . -.Xr as -announces it if you start it with the -.Li --version -argument. -.Pp -Without this, we will not know whether there is any point in looking for the -bug in the current version of -.Xr as . -.Pp -.It -Any patches you may have applied to the -.Xr as -source. -.Pp -.It -The type of machine you are using, and the operating system name and version -number. -.Pp -.It -What compiler (and its version) was used to compile -.Xr as ----e.g. \(lq -.Li gcc-2.7 -\(rq\&. -.Pp -.It -The command arguments you gave the assembler to assemble your example and -observe the bug. To guarantee you will not omit something important, list -them all. A copy of the Makefile (or the output from make) is sufficient. -.Pp -If we were to try to guess the arguments, we would probably guess wrong and -then we might not encounter the bug. -.Pp -.It -A complete input file that will reproduce the bug. If the bug is observed -when the assembler is invoked via a compiler, send the assembler source, not -the high level language source. Most compilers will produce the assembler -source when run with the -.Li -S -option. If you are using -.Li gcc , -use the options -.Li -v --save-temps ; -this will save the assembler source in a file with an extension of -.Pa .s , -and also show you exactly how -.Xr as -is being run. -.Pp -.It -A description of what behavior you observe that you believe is incorrect. -For example, \(lqIt gets a fatal signal.\(rq -.Pp -Of course, if the bug is that -.Xr as -gets a fatal signal, then we will certainly notice it. But if the bug is incorrect -output, we might not notice unless it is glaringly wrong. You might as well -not give us a chance to make a mistake. -.Pp -Even if the problem you experience is a fatal signal, you should still say -so explicitly. Suppose something strange is going on, such as, your copy of -.Xr as -is out of sync, or you have encountered a bug in the C library on your system. -(This has happened!) Your copy might crash and ours would not. If you told -us to expect a crash, then when ours fails to crash, we would know that the -bug was not happening for us. If you had not told us to expect a crash, then -we would not be able to draw any conclusion from our observations. -.Pp -.It -If you wish to suggest changes to the -.Xr as -source, send us context diffs, as generated by -.Li diff -with the -.Li -u , -.Li -c , -or -.Li -p -option. Always send diffs from the old file to the new file. If you even discuss -something in the -.Xr as -source, refer to it by context, not by line number. -.Pp -The line numbers in our development sources will not match those in your sources. -Your line numbers would convey no useful information to us. -.El -.Pp -Here are some things that are not necessary: -.Pp -.Bl -bullet -.It -A description of the envelope of the bug. -.Pp -Often people who encounter a bug spend a lot of time investigating which changes -to the input file will make the bug go away and which changes will not affect -it. -.Pp -This is often time consuming and not very useful, because the way we will -find the bug is by running a single example under the debugger with breakpoints, -not by pure deduction from a series of examples. We recommend that you save -your time for something else. -.Pp -Of course, if you can find a simpler example to report -.Em instead -of the original one, that is a convenience for us. Errors in the output will -be easier to spot, running under the debugger will take less time, and so -on. -.Pp -However, simplification is not vital; if you do not want to do this, report -the bug anyway and send us the entire test case you used. -.Pp -.It -A patch for the bug. -.Pp -A patch for the bug does help us if it is a good one. But do not omit the -necessary information, such as the test case, on the assumption that a patch -is all we need. We might see problems with your patch and decide to fix the -problem another way, or we might not understand it at all. -.Pp -Sometimes with a program as complicated as -.Xr as -it is very hard to construct an example that will make the program follow -a certain path through the code. If you do not send us the example, we will -not be able to construct one, so we will not be able to verify that the bug -is fixed. -.Pp -And if we cannot understand what bug you are trying to fix, or why your patch -should be an improvement, we will not install it. A test case will help us -to understand. -.Pp -.It -A guess about what the bug is or what it depends on. -.Pp -Such guesses are usually wrong. Even we cannot guess right about such things -without first using the debugger to find the facts. -.El -.Pp -.Sh Acknowledgements -If you have contributed to GAS and your name isn't listed here, it is not -meant as a slight. We just don't know about it. Send mail to the maintainer, -and we'll correct the situation. Currently the maintainer is Ken Raeburn (email -address -.Li raeburn@cyGNUs.com ) . -.Pp -Dean Elsner wrote the original GNU assembler for the VAX. -.Pp -Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug -information and the 68k series machines, most of the preprocessing pass, and -extensive changes in -.Pa messages.c , -.Pa input-file.c , -.Pa write.c . -.Pp -K. Richard Pixley maintained GAS for a while, adding various enhancements -and many bug fixes, including merging support for several processors, breaking -GAS up to handle multiple object file format back ends (including heavy rewrite, -testing, an integration of the coff and b.out back ends), adding configuration -including heavy testing and verification of cross assemblers and file splits -and renaming, converted GAS to strictly ANSI C including full prototypes, -added support for m680[34]0 and cpu32, did considerable work on i960 including -a COFF port (including considerable amounts of reverse engineering), a SPARC -opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated -\(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and -lint. -.Pp -Ken Raeburn wrote the high-level BFD interface code to replace most of the -code in format-specific I/O modules. -.Pp -The original VMS support was contributed by David L. Kashtan. Eric Youngdale -has done much work with it since. -.Pp -The Intel 80386 machine description was written by Eliot Dresselhaus. -.Pp -Minh Tran-Le at IntelliCorp contributed some AIX 386 support. -.Pp -The Motorola 88k machine description was contributed by Devon Bowen of Buffalo -University and Torbjorn Granlund of the Swedish Institute of Computer Science. -.Pp -Keith Knowles at the Open Software Foundation wrote the original MIPS back -end ( -.Pa tc-mips.c , -.Pa tc-mips.h ) , -and contributed Rose format support (which hasn't been merged in yet). Ralph -Campbell worked with the MIPS code to support a.out format. -.Pp -Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300), -and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain -of CyGNUs Support. Steve also modified the COFF back end to use BFD for some -low-level operations, for use with the H8/300 and AMD 29k targets. -.Pp -John Gilmore built the AMD 29000 support, added -.Li .include -support, and simplified the configuration of which versions accept which directives. -He updated the 68k machine description so that Motorola's opcodes always produced -fixed-size instructions (e.g., -.Li jsr ) , -while synthetic instructions remained shrinkable ( -.Li jbsr ) . -John fixed many bugs, including true tested cross-compilation support, and -one bug in relaxation that took a week and required the proverbial one-bit -fix. -.Pp -Ian Lance Taylor of CyGNUs Support merged the Motorola and MIT syntax for -the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO -Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 -and PowerPC assembler, and made a few other minor patches. -.Pp -Steve Chamberlain made GAS able to generate listings. -.Pp -Hewlett-Packard contributed support for the HP9000/300. -.Pp -Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) -along with a fairly extensive HPPA testsuite (for both SOM and ELF object -formats). This work was supported by both the Center for Software Science -at the University of Utah and CyGNUs Support. -.Pp -Support for ELF format files has been worked on by Mark Eichin of CyGNUs Support -(original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff -Law at the University of Utah (HPPA mainly), Michael Meissner of the Open -Software Foundation (i386 mainly), and Ken Raeburn of CyGNUs Support (sparc, -and some initial 64-bit support). -.Pp -Linas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture. -.Pp -Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and -BFD support for openVMS/Alpha. -.Pp -Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* -flavors. -.Pp -David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, -Inc. added support for Xtensa processors. -.Pp -Several engineers at CyGNUs Support have also provided many small bug fixes -and configuration enhancements. -.Pp -Many others have contributed large or small bugfixes and enhancements. If -you have contributed significant work and are not mentioned on this list, -and want to be, let us know. Some of the history has been lost; we are not -intentionally leaving anyone out. -.Pp -.Sh GNU Free Documentation License -.Bd -filled -offset indent -Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, -Fifth Floor, Boston, MA 02110-1301 USA -.Pp -Everyone is permitted to copy and distribute verbatim copies of this license -document, but changing it is not allowed. -.Ed -.Pp -.Bl -enum -.It -PREAMBLE -.Pp -The purpose of this License is to make a manual, textbook, or other written -document \(lqfree\(rq 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. -.Pp -This License is a kind of \(lqcopyleft\(rq, 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. -.Pp -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. -.Pp -.It -APPLICABILITY AND DEFINITIONS -.Pp -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 \(lqDocument\(rq, below, refers to any such manual or work. Any member -of the public is a licensee, and is addressed as \(lqyou.\(rq -.Pp -A \(lqModified Version\(rq 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. -.Pp -A \(lqSecondary Section\(rq 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. -.Pp -The \(lqInvariant Sections\(rq 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. -.Pp -The \(lqCover Texts\(rq 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. -.Pp -A \(lqTransparent\(rq 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 -\(lqTransparent\(rq is called \(lqOpaque.\(rq -.Pp -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. -.Pp -The \(lqTitle Page\(rq 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, \(lqTitle Page\(rq means the text near the most prominent -appearance of the work's title, preceding the beginning of the body of the -text. -.Pp -.It -VERBATIM COPYING -.Pp -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. -.Pp -You may also lend copies, under the same conditions stated above, and you -may publicly display copies. -.Pp -.It -COPYING IN QUANTITY -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -.It -MODIFICATIONS -.Pp -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: -.Pp -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 \(lqHistory\(rq, -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 \(lqHistory\(rq 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 \(lqHistory\(rq 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 \(lqAcknowledgements\(rq or \(lqDedications\(rq, 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 \(lqEndorsements.\(rq Such a section -may not be included in the Modified Version. N. Do not retitle any existing -section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. -.Pp -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. -.Pp -You may add a section entitled \(lqEndorsements\(rq, 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. -.Pp -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. -.Pp -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. -.Pp -.It -COMBINING DOCUMENTS -.Pp -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. -.Pp -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. -.Pp -In the combination, you must combine any sections entitled \(lqHistory\(rq in the -various original documents, forming one section entitled \(lqHistory\(rq; likewise -combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled -\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq -.Pp -.It -COLLECTIONS OF DOCUMENTS -.Pp -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. -.Pp -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. -.Pp -.It -AGGREGATION WITH INDEPENDENT WORKS -.Pp -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 \(lqaggregate\(rq, 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. -.Pp -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. -.Pp -.It -TRANSLATION -.Pp -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. -.Pp -.It -TERMINATION -.Pp -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. -.Pp -.It -FUTURE REVISIONS OF THIS LICENSE -.Pp -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/. -.Pp -Each version of the License is given a distinguishing version number. If the -Document specifies that a particular numbered version of this License \(lqor any -later version\(rq 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. -.Pp -.El -.Ss 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: -.Pp -.Bd -literal -offset indent - -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." - -.Ed -.Pp -If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead -of saying which ones are invariant. If you have no Front-Cover Texts, write -\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being -.Va list -\(rq; likewise for Back-Cover Texts. -.Pp -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. -.Pp -.Sh AS Index diff --git a/contrib/binutils/gas/doc/asconfig.texi b/contrib/binutils/gas/doc/asconfig.texi deleted file mode 100644 index 95f4a5b36b5e..000000000000 --- a/contrib/binutils/gas/doc/asconfig.texi +++ /dev/null @@ -1,90 +0,0 @@ -@c $FreeBSD: stable/10/gnu/usr.bin/binutils/doc/asconfig.texi 218822 2011-02-18 20:54:12Z dim $ -@c Copyright 1992, 1993, 1994, 1996, 1997, 1999, 2000, 2001, 2002, -@c 2003, 2005 -@c Free Software Foundation, Inc. -@c This file is part of the documentation for the GAS manual - -@c Configuration settings for all-inclusive version of manual - -@c switches:------------------------------------------------------------ -@c Properties of the manual -@c ======================== -@c Discuss all architectures? -@clear ALL-ARCH -@c A generic form of manual (not tailored to specific target)? -@clear GENERIC -@c Include text on assembler internals? -@set INTERNALS -@c Many object formats supported in this config? -@clear MULTI-OBJ - -@c Object formats of interest -@c ========================== -@clear AOUT -@clear COFF -@set ELF -@clear SOM - -@c CPUs of interest -@c ================ -@clear ALPHA -@clear ARC -@set ARM -@clear BFIN -@clear CRIS -@clear D10V -@clear D30V -@clear H8/300 -@clear HPPA -@clear I370 -@set I80386 -@clear I860 -@clear I960 -@set IA64 -@clear IP2K -@clear M32C -@clear M32R -@clear xc16x -@clear M68HC11 -@clear M680X0 -@clear MCORE -@set MIPS -@clear MMIX -@clear MS1 -@clear MSP430 -@clear PDP11 -@clear PJ -@set PPC -@clear SH -@set SPARC -@clear TIC54X -@clear V850 -@clear VAX -@clear XTENSA -@clear Z80 -@clear Z8000 - -@c Does this version of the assembler use the difference-table kludge? -@clear DIFF-TBL-KLUGE - -@c Do all machines described use IEEE floating point? -@clear IEEEFLOAT - -@c Is a word 32 bits, or 16? -@set W32 -@clear W16 - -@c Do symbols have different characters than usual? -@clear SPECIAL-SYMS - -@c strings:------------------------------------------------------------ -@c Name of the assembler: -@set AS as -@c Name of C compiler: -@set GCC gcc -@c Name of linker: -@set LD ld -@c Text for target machine (best not used in generic case; but just in case...) -@set TARGET machine specific -@c Name of object format NOT SET in generic version -@set OBJ-NAME ELF diff --git a/contrib/binutils/gas/doc/c-arm.texi b/contrib/binutils/gas/doc/c-arm.texi index 3ad627162e31..8fc2972e5750 100644 --- a/contrib/binutils/gas/doc/c-arm.texi +++ b/contrib/binutils/gas/doc/c-arm.texi @@ -317,6 +317,13 @@ Either @samp{#} or @samp{$} can be used to indicate immediate operands. @cindex register names, ARM *TODO* Explain about ARM register naming, and the predefined names. +@node ARM Floating Point +@section Floating Point + +@cindex floating point, ARM (@sc{ieee}) +@cindex ARM floating point (@sc{ieee}) +The ARM family uses @sc{ieee} floating-point numbers. + @node ARM-Relocations @subsection ARM relocation generation @@ -358,13 +365,6 @@ respectively. For example to load the 32-bit address of foo into r0: MOVT r0, #:upper16:foo @end smallexample -@node ARM Floating Point -@section Floating Point - -@cindex floating point, ARM (@sc{ieee}) -@cindex ARM floating point (@sc{ieee}) -The ARM family uses @sc{ieee} floating-point numbers. - @node ARM Directives @section ARM Machine Directives diff --git a/contrib/binutils/gas/doc/c-mips.texi b/contrib/binutils/gas/doc/c-mips.texi index 89706bc1b8b2..f92cb0098d55 100644 --- a/contrib/binutils/gas/doc/c-mips.texi +++ b/contrib/binutils/gas/doc/c-mips.texi @@ -196,7 +196,7 @@ the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop} instructions around accesses to the @samp{HI} and @samp{LO} registers. @samp{-no-m4650} turns off this option. -@item -m3900 +@itemx -m3900 @itemx -no-m3900 @itemx -m4100 @itemx -no-m4100 diff --git a/contrib/binutils/gas/expr.c b/contrib/binutils/gas/expr.c index 3f364b51f2e4..11f2942672cf 100644 --- a/contrib/binutils/gas/expr.c +++ b/contrib/binutils/gas/expr.c @@ -1040,15 +1040,6 @@ operand (expressionS *expressionP, enum expr_mode mode) { for (i = 0; i < expressionP->X_add_number; ++i) generic_bignum[i] = ~generic_bignum[i]; - - /* Extend the bignum to at least the size of .octa. */ - if (expressionP->X_add_number < SIZE_OF_LARGE_NUMBER) - { - expressionP->X_add_number = SIZE_OF_LARGE_NUMBER; - for (; i < expressionP->X_add_number; ++i) - generic_bignum[i] = ~(LITTLENUM_TYPE) 0; - } - if (c == '-') for (i = 0; i < expressionP->X_add_number; ++i) { @@ -1059,12 +1050,14 @@ operand (expressionS *expressionP, enum expr_mode mode) } else if (c == '!') { + int nonzero = 0; for (i = 0; i < expressionP->X_add_number; ++i) - if (generic_bignum[i] != 0) - break; - expressionP->X_add_number = i >= expressionP->X_add_number; - expressionP->X_op = O_constant; - expressionP->X_unsigned = 1; + { + if (generic_bignum[i]) + nonzero = 1; + generic_bignum[i] = 0; + } + generic_bignum[0] = nonzero; } } else if (expressionP->X_op != O_illegal diff --git a/contrib/binutils/gas/input-scrub.c b/contrib/binutils/gas/input-scrub.c index 6eb01898bd94..5698a6dc22a2 100644 --- a/contrib/binutils/gas/input-scrub.c +++ b/contrib/binutils/gas/input-scrub.c @@ -335,7 +335,7 @@ input_scrub_next_buffer (char **bufp) if (partial_size) { - memmove (buffer_start + BEFORE_SIZE, partial_where, + memcpy (buffer_start + BEFORE_SIZE, partial_where, (unsigned int) partial_size); memcpy (buffer_start + BEFORE_SIZE, save_source, AFTER_SIZE); } diff --git a/contrib/binutils/gas/read.c b/contrib/binutils/gas/read.c index 5e0bdb0d54b7..0098d7691b3a 100644 --- a/contrib/binutils/gas/read.c +++ b/contrib/binutils/gas/read.c @@ -4117,32 +4117,15 @@ emit_expr (expressionS *exp, unsigned int nbytes) unsigned int size; LITTLENUM_TYPE *nums; + know (nbytes % CHARS_PER_LITTLENUM == 0); + size = exp->X_add_number * CHARS_PER_LITTLENUM; if (nbytes < size) { - int i = nbytes / CHARS_PER_LITTLENUM; - if (i != 0) - { - LITTLENUM_TYPE sign = 0; - if ((generic_bignum[--i] - & (1 << (LITTLENUM_NUMBER_OF_BITS - 1))) != 0) - sign = ~(LITTLENUM_TYPE) 0; - while (++i < exp->X_add_number) - if (generic_bignum[i] != sign) - break; - } - if (i < exp->X_add_number) - as_warn (_("bignum truncated to %d bytes"), nbytes); + as_warn (_("bignum truncated to %d bytes"), nbytes); size = nbytes; } - if (nbytes == 1) - { - md_number_to_chars (p, (valueT) generic_bignum[0], 1); - return; - } - know (nbytes % CHARS_PER_LITTLENUM == 0); - if (target_big_endian) { while (nbytes > size) diff --git a/contrib/binutils/include/elf/ChangeLog b/contrib/binutils/include/elf/ChangeLog index 67cd96b76810..ba08331c4c02 100644 --- a/contrib/binutils/include/elf/ChangeLog +++ b/contrib/binutils/include/elf/ChangeLog @@ -1,8 +1,3 @@ -2009-03-04 Alan Modra <amodra@bigpond.net.au> - - * ppc.h (R_PPC_TLSGD, R_PPC_TLSLD): Add new relocs. - * ppc64.h (R_PPC64_TLSGD, R_PPC64_TLSLD): Add new relocs. - 2007-06-29 Joseph Myers <joseph@codesourcery.com> * ppc.h (Tag_GNU_Power_ABI_FP): Define. diff --git a/contrib/binutils/include/elf/arm.h b/contrib/binutils/include/elf/arm.h index f9638179f5df..b10bb72eb643 100644 --- a/contrib/binutils/include/elf/arm.h +++ b/contrib/binutils/include/elf/arm.h @@ -271,11 +271,7 @@ enum Tag_ABI_optimization_goals, Tag_ABI_FP_optimization_goals, /* 32 is generic. */ - Tag_CPU_unaligned_access = 34, - Tag_FP_HP_extension = 36, - Tag_ABI_FP_16bit_format = 38, - Tag_MPextension_use = 42, - Tag_DIV_use = 44, + Tag_Virtualization_use = 68, }; diff --git a/contrib/binutils/include/elf/common.h b/contrib/binutils/include/elf/common.h index 157922af3f0b..d4d9d7b0cc7a 100644 --- a/contrib/binutils/include/elf/common.h +++ b/contrib/binutils/include/elf/common.h @@ -414,7 +414,6 @@ #define NT_PROCSTAT_OSREL 14 #define NT_PROCSTAT_PSSTRINGS 15 #define NT_PROCSTAT_AUXV 16 -#define NT_X86_XSTATE 0x202 /* Note segments for core files on NetBSD systems. Note name diff --git a/contrib/binutils/include/elf/ppc.h b/contrib/binutils/include/elf/ppc.h index 550f86700515..fe48814d86f2 100644 --- a/contrib/binutils/include/elf/ppc.h +++ b/contrib/binutils/include/elf/ppc.h @@ -100,8 +100,6 @@ START_RELOC_NUMBERS (elf_ppc_reloc_type) RELOC_NUMBER (R_PPC_GOT_DTPREL16_LO, 92) RELOC_NUMBER (R_PPC_GOT_DTPREL16_HI, 93) RELOC_NUMBER (R_PPC_GOT_DTPREL16_HA, 94) - RELOC_NUMBER (R_PPC_TLSGD, 95) - RELOC_NUMBER (R_PPC_TLSLD, 96) /* The remaining relocs are from the Embedded ELF ABI, and are not in the SVR4 ELF ABI. */ diff --git a/contrib/binutils/include/elf/ppc64.h b/contrib/binutils/include/elf/ppc64.h index c768180b467d..4aab2ec9446a 100644 --- a/contrib/binutils/include/elf/ppc64.h +++ b/contrib/binutils/include/elf/ppc64.h @@ -1,5 +1,5 @@ /* PPC64 ELF support for BFD. - Copyright 2003, 2005, 2009 Free Software Foundation, Inc. + Copyright 2003 Free Software Foundation, Inc. This file is part of BFD, the Binary File Descriptor library. @@ -136,8 +136,6 @@ START_RELOC_NUMBERS (elf_ppc64_reloc_type) RELOC_NUMBER (R_PPC64_DTPREL16_HIGHERA, 104) RELOC_NUMBER (R_PPC64_DTPREL16_HIGHEST, 105) RELOC_NUMBER (R_PPC64_DTPREL16_HIGHESTA, 106) - RELOC_NUMBER (R_PPC64_TLSGD, 107) - RELOC_NUMBER (R_PPC64_TLSLD, 108) /* These are GNU extensions to enable C++ vtable garbage collection. */ RELOC_NUMBER (R_PPC64_GNU_VTINHERIT, 253) diff --git a/contrib/binutils/ld/configdoc.texi b/contrib/binutils/ld/configdoc.texi deleted file mode 100644 index 03ab5583bdab..000000000000 --- a/contrib/binutils/ld/configdoc.texi +++ /dev/null @@ -1,25 +0,0 @@ -@c ------------------------------ CONFIGURATION VARS: -@c 1. Inclusiveness of this manual -@set GENERIC - -@c 2. Specific target machines -@set ARM -@set H8300 -@set HPPA -@set I960 -@set M68HC11 -@set MMIX -@set MSP430 -@set POWERPC -@set POWERPC64 -@set Renesas -@set SPU -@set TICOFF -@set WIN32 -@set XTENSA - -@c 3. Properties of this configuration -@clear SingleFormat -@set UsesEnvVars -@c ------------------------------ end CONFIGURATION VARS - diff --git a/contrib/binutils/ld/ld.7 b/contrib/binutils/ld/ld.7 deleted file mode 100644 index 8ac5573b75c2..000000000000 --- a/contrib/binutils/ld/ld.7 +++ /dev/null @@ -1,7819 +0,0 @@ -.Dd 2015-03-02 -.Dt LD 7 -.Os -.Sh NAME -.Nm ld -.Nd The GNU Linker -.Sh LD -This file documents the GNU linker ld version "2.17.50 [FreeBSD] 2007-07-03". -.Pp -This document is distributed under the terms of the GNU Free Documentation -License. A copy of the license is included in the section entitled \(lqGNU Free -Documentation License\(rq. -.Pp -.Sh Overview -.Xr ld -combines a number of object and archive files, relocates their data and ties -up symbol references. Usually the last step in compiling a program is to run -.Xr ld . -.Pp -.Xr ld -accepts Linker Command Language files written in a superset of AT&T's Link -Editor Command Language syntax, to provide explicit and total control over -the linking process. -.Pp -This version of -.Xr ld -uses the general purpose BFD libraries to operate on object files. This allows -.Xr ld -to read, combine, and write object files in many different formats---for example, -COFF or -.Li a.out . -Different formats may be linked together to produce any available kind of -object file.See Section -.Dq BFD , -for more information. -.Pp -Aside from its flexibility, the GNU linker is more helpful than other linkers -in providing diagnostic information. Many linkers abandon execution immediately -upon encountering an error; whenever possible, -.Xr ld -continues executing, allowing you to identify other errors (or, in some cases, -to get an output file in spite of the error). -.Pp -.Sh Invocation -The GNU linker -.Xr ld -is meant to cover a broad range of situations, and to be as compatible as -possible with other linkers. As a result, you have many choices to control -its behavior. -.Pp -.Ss Command Line Options -The linker supports a plethora of command-line options, but in actual practice -few of them are used in any particular context. For instance, a frequent use -of -.Xr ld -is to link standard Unix object files on a standard, supported Unix system. -On such a system, to link a file -.Li hello.o : -.Pp -.Bd -literal -offset indent -ld -o output /lib/crt0.o hello.o -lc -.Ed -.Pp -This tells -.Xr ld -to produce a file called -.Va output -as the result of linking the file -.Li /lib/crt0.o -with -.Li hello.o -and the library -.Li libc.a , -which will come from the standard search directories. (See the discussion -of the -.Li -l -option below.) -.Pp -Some of the command-line options to -.Xr ld -may be specified at any point in the command line. However, options which -refer to files, such as -.Li -l -or -.Li -T , -cause the file to be read at the point at which the option appears in the -command line, relative to the object files and other file options. Repeating -non-file options with a different argument will either have no further effect, -or override prior occurrences (those further to the left on the command line) -of that option. Options which may be meaningfully specified more than once -are noted in the descriptions below. -.Pp -Non-option arguments are object files or archives which are to be linked together. -They may follow, precede, or be mixed in with command-line options, except -that an object file argument may not be placed between an option and its argument. -.Pp -Usually the linker is invoked with at least one object file, but you can specify -other forms of binary input files using -.Li -l , -.Li -R , -and the script command language. If -.Em no -binary input files at all are specified, the linker does not produce any output, -and issues the message -.Li No input files . -.Pp -If the linker cannot recognize the format of an object file, it will assume -that it is a linker script. A script specified in this way augments the main -linker script used for the link (either the default linker script or the one -specified by using -.Li -T ) . -This feature permits the linker to link against a file which appears to be -an object or an archive, but actually merely defines some symbol values, or -uses -.Li INPUT -or -.Li GROUP -to load other objects. Note that specifying a script in this way merely augments -the main linker script; use the -.Li -T -option to replace the default linker script entirely.See Section -.Dq Scripts . -.Pp -For options whose names are a single letter, option arguments must either -follow the option letter without intervening whitespace, or be given as separate -arguments immediately following the option that requires them. -.Pp -For options whose names are multiple letters, either one dash or two can precede -the option name; for example, -.Li -trace-symbol -and -.Li --trace-symbol -are equivalent. Note---there is one exception to this rule. Multiple letter -options that start with a lower case 'o' can only be preceded by two dashes. -This is to reduce confusion with the -.Li -o -option. So for example -.Li -omagic -sets the output file name to -.Li magic -whereas -.Li --omagic -sets the NMAGIC flag on the output. -.Pp -Arguments to multiple-letter options must either be separated from the option -name by an equals sign, or be given as separate arguments immediately following -the option that requires them. For example, -.Li --trace-symbol foo -and -.Li --trace-symbol=foo -are equivalent. Unique abbreviations of the names of multiple-letter options -are accepted. -.Pp -Note---if the linker is being invoked indirectly, via a compiler driver (e.g. -.Li gcc ) -then all the linker command line options should be prefixed by -.Li -Wl, -(or whatever is appropriate for the particular compiler driver) like this: -.Pp -.Bd -literal -offset indent - gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup -.Ed -.Pp -This is important, because otherwise the compiler driver program may silently -drop the linker options, resulting in a bad link. -.Pp -Here is a table of the generic command line switches accepted by the GNU linker: -.Pp -.Bl -tag -width Ds -.It @ Va file -Read command-line options from -.Va file . -The options read are inserted in place of the original @ -.Va file -option. If -.Va file -does not exist, or cannot be read, then the option will be treated literally, -and not removed. -.Pp -Options in -.Va file -are separated by whitespace. A whitespace character may be included in an -option by surrounding the entire option in either single or double quotes. -Any character (including a backslash) may be included by prefixing the character -to be included with a backslash. The -.Va file -may itself contain additional @ -.Va file -options; any such options will be processed recursively. -.Pp -.It -a Va keyword -This option is supported for HP/UX compatibility. The -.Va keyword -argument must be one of the strings -.Li archive , -.Li shared , -or -.Li default . -.Li -aarchive -is functionally equivalent to -.Li -Bstatic , -and the other two keywords are functionally equivalent to -.Li -Bdynamic . -This option may be used any number of times. -.Pp -.It -A Va architecture -.It --architecture= Va architecture -In the current release of -.Xr ld , -this option is useful only for the Intel 960 family of architectures. In that -.Xr ld -configuration, the -.Va architecture -argument identifies the particular architecture in the 960 family, enabling -some safeguards and modifying the archive-library search path.See Section -.Dq i960 , -for details. -.Pp -Future releases of -.Xr ld -may support similar functionality for other architecture families. -.Pp -.It -b Va input-format -.It --format= Va input-format -.Xr ld -may be configured to support more than one kind of object file. If your -.Xr ld -is configured this way, you can use the -.Li -b -option to specify the binary format for input object files that follow this -option on the command line. Even when -.Xr ld -is configured to support alternative object formats, you don't usually need -to specify this, as -.Xr ld -should be configured to expect as a default input format the most usual format -on each machine. -.Va input-format -is a text string, the name of a particular format supported by the BFD libraries. -(You can list the available binary formats with -.Li objdump -i . ) -See Section.Dq BFD . -.Pp -You may want to use this option if you are linking files with an unusual binary -format. You can also use -.Li -b -to switch formats explicitly (when linking object files of different formats), -by including -.Li -b Va input-format -before each group of object files in a particular format. -.Pp -The default format is taken from the environment variable -.Li GNUTARGET . -See Section.Dq Environment . -You can also define the input format from a script, using the command -.Li TARGET ; -see Format Commands. -.Pp -.It -c Va MRI-commandfile -.It --mri-script= Va MRI-commandfile -For compatibility with linkers produced by MRI, -.Xr ld -accepts script files written in an alternate, restricted command language, -described in MRI,,MRI Compatible Script Files. Introduce MRI script files -with the option -.Li -c ; -use the -.Li -T -option to run linker scripts written in the general-purpose -.Xr ld -scripting language. If -.Va MRI-cmdfile -does not exist, -.Xr ld -looks for it in the directories specified by any -.Li -L -options. -.Pp -.It -d -.It -dc -.It -dp -These three options are equivalent; multiple forms are supported for compatibility -with other linkers. They assign space to common symbols even if a relocatable -output file is specified (with -.Li -r ) . -The script command -.Li FORCE_COMMON_ALLOCATION -has the same effect.See Section -.Dq Miscellaneous Commands . -.Pp -.It -e Va entry -.It --entry= Va entry -Use -.Va entry -as the explicit symbol for beginning execution of your program, rather than -the default entry point. If there is no symbol named -.Va entry , -the linker will try to parse -.Va entry -as a number, and use that as the entry address (the number will be interpreted -in base 10; you may use a leading -.Li 0x -for base 16, or a leading -.Li 0 -for base 8).See Section -.Dq Entry Point , -for a discussion of defaults and other ways of specifying the entry point. -.Pp -.It --exclude-libs Va lib, Va lib,... -Specifies a list of archive libraries from which symbols should not be automatically -exported. The library names may be delimited by commas or colons. Specifying -.Li --exclude-libs ALL -excludes symbols in all archive libraries from automatic export. This option -is available only for the i386 PE targeted port of the linker and for ELF -targeted ports. For i386 PE, symbols explicitly listed in a .def file are -still exported, regardless of this option. For ELF targeted ports, symbols -affected by this option will be treated as hidden. -.Pp -.It -E -.It --export-dynamic -When creating a dynamically linked executable, add all symbols to the dynamic -symbol table. The dynamic symbol table is the set of symbols which are visible -from dynamic objects at run time. -.Pp -If you do not use this option, the dynamic symbol table will normally contain -only those symbols which are referenced by some dynamic object mentioned in -the link. -.Pp -If you use -.Li dlopen -to load a dynamic object which needs to refer back to the symbols defined -by the program, rather than some other dynamic object, then you will probably -need to use this option when linking the program itself. -.Pp -You can also use the dynamic list to control what symbols should be added -to the dynamic symbol table if the output format supports it. See the description -of -.Li --dynamic-list . -.Pp -.It -EB -Link big-endian objects. This affects the default output format. -.Pp -.It -EL -Link little-endian objects. This affects the default output format. -.Pp -.It -f -.It --auxiliary Va name -When creating an ELF shared object, set the internal DT_AUXILIARY field to -the specified name. This tells the dynamic linker that the symbol table of -the shared object should be used as an auxiliary filter on the symbol table -of the shared object -.Va name . -.Pp -If you later link a program against this filter object, then, when you run -the program, the dynamic linker will see the DT_AUXILIARY field. If the dynamic -linker resolves any symbols from the filter object, it will first check whether -there is a definition in the shared object -.Va name . -If there is one, it will be used instead of the definition in the filter object. -The shared object -.Va name -need not exist. Thus the shared object -.Va name -may be used to provide an alternative implementation of certain functions, -perhaps for debugging or for machine specific performance. -.Pp -This option may be specified more than once. The DT_AUXILIARY entries will -be created in the order in which they appear on the command line. -.Pp -.It -F Va name -.It --filter Va name -When creating an ELF shared object, set the internal DT_FILTER field to the -specified name. This tells the dynamic linker that the symbol table of the -shared object which is being created should be used as a filter on the symbol -table of the shared object -.Va name . -.Pp -If you later link a program against this filter object, then, when you run -the program, the dynamic linker will see the DT_FILTER field. The dynamic -linker will resolve symbols according to the symbol table of the filter object -as usual, but it will actually link to the definitions found in the shared -object -.Va name . -Thus the filter object can be used to select a subset of the symbols provided -by the object -.Va name . -.Pp -Some older linkers used the -.Op -F -option throughout a compilation toolchain for specifying object-file format -for both input and output object files. The GNU linker uses other mechanisms -for this purpose: the -.Op -b , -.Op --format , -.Op --oformat -options, the -.Li TARGET -command in linker scripts, and the -.Li GNUTARGET -environment variable. The GNU linker will ignore the -.Op -F -option when not creating an ELF shared object. -.Pp -.It -fini Va name -When creating an ELF executable or shared object, call NAME when the executable -or shared object is unloaded, by setting DT_FINI to the address of the function. -By default, the linker uses -.Li _fini -as the function to call. -.Pp -.It -g -Ignored. Provided for compatibility with other tools. -.Pp -.It -G Va value -.It --gpsize= Va value -Set the maximum size of objects to be optimized using the GP register to -.Va size . -This is only meaningful for object file formats such as MIPS ECOFF which supports -putting large and small objects into different sections. This is ignored for -other object file formats. -.Pp -.It -h Va name -.It -soname= Va name -When creating an ELF shared object, set the internal DT_SONAME field to the -specified name. When an executable is linked with a shared object which has -a DT_SONAME field, then when the executable is run the dynamic linker will -attempt to load the shared object specified by the DT_SONAME field rather -than the using the file name given to the linker. -.Pp -.It -i -Perform an incremental link (same as option -.Li -r ) . -.Pp -.It -init Va name -When creating an ELF executable or shared object, call NAME when the executable -or shared object is loaded, by setting DT_INIT to the address of the function. -By default, the linker uses -.Li _init -as the function to call. -.Pp -.It -l Va namespec -.It --library= Va namespec -Add the archive or object file specified by -.Va namespec -to the list of files to link. This option may be used any number of times. -If -.Va namespec -is of the form -.Pa : Va filename , -.Xr ld -will search the library path for a file called -.Va filename , -otherise it will search the library path for a file called -.Pa lib Va namespec.a . -.Pp -On systems which support shared libraries, -.Xr ld -may also search for files other than -.Pa lib Va namespec.a . -Specifically, on ELF and SunOS systems, -.Xr ld -will search a directory for a library called -.Pa lib Va namespec.so -before searching for one called -.Pa lib Va namespec.a . -(By convention, a -.Li .so -extension indicates a shared library.) Note that this behavior does not apply -to -.Pa : Va filename , -which always specifies a file called -.Va filename . -.Pp -The linker will search an archive only once, at the location where it is specified -on the command line. If the archive defines a symbol which was undefined in -some object which appeared before the archive on the command line, the linker -will include the appropriate file(s) from the archive. However, an undefined -symbol in an object appearing later on the command line will not cause the -linker to search the archive again. -.Pp -See the -.Op -( -option for a way to force the linker to search archives multiple times. -.Pp -You may list the same archive multiple times on the command line. -.Pp -This type of archive searching is standard for Unix linkers. However, if you -are using -.Xr ld -on AIX, note that it is different from the behaviour of the AIX linker. -.Pp -.It -L Va searchdir -.It --library-path= Va searchdir -Add path -.Va searchdir -to the list of paths that -.Xr ld -will search for archive libraries and -.Xr ld -control scripts. You may use this option any number of times. The directories -are searched in the order in which they are specified on the command line. -Directories specified on the command line are searched before the default -directories. All -.Op -L -options apply to all -.Op -l -options, regardless of the order in which the options appear. -.Pp -If -.Va searchdir -begins with -.Li = , -then the -.Li = -will be replaced by the -.Em sysroot prefix , -a path specified when the linker is configured. -.Pp -The default set of paths searched (without being specified with -.Li -L ) -depends on which emulation mode -.Xr ld -is using, and in some cases also on how it was configured.See Section -.Dq Environment . -.Pp -The paths can also be specified in a link script with the -.Li SEARCH_DIR -command. Directories specified this way are searched at the point in which -the linker script appears in the command line. -.Pp -.It -m Va emulation -Emulate the -.Va emulation -linker. You can list the available emulations with the -.Li --verbose -or -.Li -V -options. -.Pp -If the -.Li -m -option is not used, the emulation is taken from the -.Li LDEMULATION -environment variable, if that is defined. -.Pp -Otherwise, the default emulation depends upon how the linker was configured. -.Pp -.It -M -.It --print-map -Print a link map to the standard output. A link map provides information about -the link, including the following: -.Pp -.Bl -bullet -.It -Where object files are mapped into memory. -.It -How common symbols are allocated. -.It -All archive members included in the link, with a mention of the symbol which -caused the archive member to be brought in. -.It -The values assigned to symbols. -.Pp -Note - symbols whose values are computed by an expression which involves a -reference to a previous value of the same symbol may not have correct result -displayed in the link map. This is because the linker discards intermediate -results and only retains the final value of an expression. Under such circumstances -the linker will display the final value enclosed by square brackets. Thus -for example a linker script containing: -.Pp -.Bd -literal -offset indent - foo = 1 - foo = foo * 4 - foo = foo + 8 -.Ed -.Pp -will produce the following output in the link map if the -.Op -M -option is used: -.Pp -.Bd -literal -offset indent - 0x00000001 foo = 0x1 - [0x0000000c] foo = (foo * 0x4) - [0x0000000c] foo = (foo + 0x8) -.Ed -.Pp -See Expressions for more information about expressions in linker scripts. -.El -.Pp -.It -n -.It --nmagic -Turn off page alignment of sections, and mark the output as -.Li NMAGIC -if possible. -.Pp -.It -N -.It --omagic -Set the text and data sections to be readable and writable. Also, do not page-align -the data segment, and disable linking against shared libraries. If the output -format supports Unix style magic numbers, mark the output as -.Li OMAGIC . -Note: Although a writable text section is allowed for PE-COFF targets, it -does not conform to the format specification published by Microsoft. -.Pp -.It --no-omagic -This option negates most of the effects of the -.Op -N -option. It sets the text section to be read-only, and forces the data segment -to be page-aligned. Note - this option does not enable linking against shared -libraries. Use -.Op -Bdynamic -for this. -.Pp -.It -o Va output -.It --output= Va output -Use -.Va output -as the name for the program produced by -.Xr ld ; -if this option is not specified, the name -.Pa a.out -is used by default. The script command -.Li OUTPUT -can also specify the output file name. -.Pp -.It -O Va level -If -.Va level -is a numeric values greater than zero -.Xr ld -optimizes the output. This might take significantly longer and therefore probably -should only be enabled for the final binary. -.Pp -.It -q -.It --emit-relocs -Leave relocation sections and contents in fully linked executables. Post link -analysis and optimization tools may need this information in order to perform -correct modifications of executables. This results in larger executables. -.Pp -This option is currently only supported on ELF platforms. -.Pp -.It --force-dynamic -Force the output file to have dynamic sections. This option is specific to -VxWorks targets. -.Pp -.It -r -.It --relocatable -Generate relocatable output---i.e., generate an output file that can in turn -serve as input to -.Xr ld . -This is often called -.Em partial linking . -As a side effect, in environments that support standard Unix magic numbers, -this option also sets the output file's magic number to -.Li OMAGIC . -If this option is not specified, an absolute file is produced. When linking -C++ programs, this option -.Em will not -resolve references to constructors; to do that, use -.Li -Ur . -.Pp -When an input file does not have the same format as the output file, partial -linking is only supported if that input file does not contain any relocations. -Different output formats can have further restrictions; for example some -.Li a.out --based formats do not support partial linking with input files in other formats -at all. -.Pp -This option does the same thing as -.Li -i . -.Pp -.It -R Va filename -.It --just-symbols= Va filename -Read symbol names and their addresses from -.Va filename , -but do not relocate it or include it in the output. This allows your output -file to refer symbolically to absolute locations of memory defined in other -programs. You may use this option more than once. -.Pp -For compatibility with other ELF linkers, if the -.Op -R -option is followed by a directory name, rather than a file name, it is treated -as the -.Op -rpath -option. -.Pp -.It -s -.It --strip-all -Omit all symbol information from the output file. -.Pp -.It -S -.It --strip-debug -Omit debugger symbol information (but not all symbols) from the output file. -.Pp -.It -t -.It --trace -Print the names of the input files as -.Xr ld -processes them. -.Pp -.It -T Va scriptfile -.It --script= Va scriptfile -Use -.Va scriptfile -as the linker script. This script replaces -.Xr ld -\&'s default linker script (rather than adding to it), so -.Va commandfile -must specify everything necessary to describe the output file.See Section -.Dq Scripts . -If -.Va scriptfile -does not exist in the current directory, -.Li ld -looks for it in the directories specified by any preceding -.Li -L -options. Multiple -.Li -T -options accumulate. -.Pp -.It -dT Va scriptfile -.It --default-script= Va scriptfile -Use -.Va scriptfile -as the default linker script.See Section -.Dq Scripts . -.Pp -This option is similar to the -.Op --script -option except that processing of the script is delayed until after the rest -of the command line has been processed. This allows options placed after the -.Op --default-script -option on the command line to affect the behaviour of the linker script, which -can be important when the linker command line cannot be directly controlled -by the user. (eg because the command line is being constructed by another -tool, such as -.Li gcc ) . -.Pp -.It -u Va symbol -.It --undefined= Va symbol -Force -.Va symbol -to be entered in the output file as an undefined symbol. Doing this may, for -example, trigger linking of additional modules from standard libraries. -.Li -u -may be repeated with different option arguments to enter additional undefined -symbols. This option is equivalent to the -.Li EXTERN -linker script command. -.Pp -.It -Ur -For anything other than C++ programs, this option is equivalent to -.Li -r : -it generates relocatable output---i.e., an output file that can in turn serve -as input to -.Xr ld . -When linking C++ programs, -.Li -Ur -.Em does -resolve references to constructors, unlike -.Li -r . -It does not work to use -.Li -Ur -on files that were themselves linked with -.Li -Ur ; -once the constructor table has been built, it cannot be added to. Use -.Li -Ur -only for the last partial link, and -.Li -r -for the others. -.Pp -.It --unique[= Va SECTION] -Creates a separate output section for every input section matching -.Va SECTION , -or if the optional wildcard -.Va SECTION -argument is missing, for every orphan input section. An orphan section is -one not specifically mentioned in a linker script. You may use this option -multiple times on the command line; It prevents the normal merging of input -sections with the same name, overriding output section assignments in a linker -script. -.Pp -.It -v -.It --version -.It -V -Display the version number for -.Xr ld . -The -.Op -V -option also lists the supported emulations. -.Pp -.It -x -.It --discard-all -Delete all local symbols. -.Pp -.It -X -.It --discard-locals -Delete all temporary local symbols. (These symbols start with system-specific -local label prefixes, typically -.Li .L -for ELF systems or -.Li L -for traditional a.out systems.) -.Pp -.It -y Va symbol -.It --trace-symbol= Va symbol -Print the name of each linked file in which -.Va symbol -appears. This option may be given any number of times. On many systems it -is necessary to prepend an underscore. -.Pp -This option is useful when you have an undefined symbol in your link but don't -know where the reference is coming from. -.Pp -.It -Y Va path -Add -.Va path -to the default library search path. This option exists for Solaris compatibility. -.Pp -.It -z Va keyword -The recognized keywords are: -.Bl -tag -width Ds -.It combreloc -Combines multiple reloc sections and sorts them to make dynamic symbol lookup -caching possible. -.Pp -.It defs -Disallows undefined symbols in object files. Undefined symbols in shared libraries -are still allowed. -.Pp -.It execstack -Marks the object as requiring executable stack. -.Pp -.It initfirst -This option is only meaningful when building a shared object. It marks the -object so that its runtime initialization will occur before the runtime initialization -of any other objects brought into the process at the same time. Similarly -the runtime finalization of the object will occur after the runtime finalization -of any other objects. -.Pp -.It interpose -Marks the object that its symbol table interposes before all symbols but the -primary executable. -.Pp -.It lazy -When generating an executable or shared library, mark it to tell the dynamic -linker to defer function call resolution to the point when the function is -called (lazy binding), rather than at load time. Lazy binding is the default. -.Pp -.It loadfltr -Marks the object that its filters be processed immediately at runtime. -.Pp -.It muldefs -Allows multiple definitions. -.Pp -.It nocombreloc -Disables multiple reloc sections combining. -.Pp -.It nocopyreloc -Disables production of copy relocs. -.Pp -.It nodefaultlib -Marks the object that the search for dependencies of this object will ignore -any default library search paths. -.Pp -.It nodelete -Marks the object shouldn't be unloaded at runtime. -.Pp -.It nodlopen -Marks the object not available to -.Li dlopen . -.Pp -.It nodump -Marks the object can not be dumped by -.Li dldump . -.Pp -.It noexecstack -Marks the object as not requiring executable stack. -.Pp -.It norelro -Don't create an ELF -.Li PT_GNU_RELRO -segment header in the object. -.Pp -.It now -When generating an executable or shared library, mark it to tell the dynamic -linker to resolve all symbols when the program is started, or when the shared -library is linked to using dlopen, instead of deferring function call resolution -to the point when the function is first called. -.Pp -.It origin -Marks the object may contain $ORIGIN. -.Pp -.It relro -Create an ELF -.Li PT_GNU_RELRO -segment header in the object. -.Pp -.It max-page-size= Va value -Set the emulation maximum page size to -.Va value . -.Pp -.It common-page-size= Va value -Set the emulation common page size to -.Va value . -.Pp -.El -Other keywords are ignored for Solaris compatibility. -.Pp -.It -( Va archives -) -.It --start-group Va archives --end-group -The -.Va archives -should be a list of archive files. They may be either explicit file names, -or -.Li -l -options. -.Pp -The specified archives are searched repeatedly until no new undefined references -are created. Normally, an archive is searched only once in the order that -it is specified on the command line. If a symbol in that archive is needed -to resolve an undefined symbol referred to by an object in an archive that -appears later on the command line, the linker would not be able to resolve -that reference. By grouping the archives, they all be searched repeatedly -until all possible references are resolved. -.Pp -Using this option has a significant performance cost. It is best to use it -only when there are unavoidable circular references between two or more archives. -.Pp -.It --accept-unknown-input-arch -.It --no-accept-unknown-input-arch -Tells the linker to accept input files whose architecture cannot be recognised. -The assumption is that the user knows what they are doing and deliberately -wants to link in these unknown input files. This was the default behaviour -of the linker, before release 2.14. The default behaviour from release 2.14 -onwards is to reject such input files, and so the -.Li --accept-unknown-input-arch -option has been added to restore the old behaviour. -.Pp -.It --as-needed -.It --no-as-needed -This option affects ELF DT_NEEDED tags for dynamic libraries mentioned on -the command line after the -.Op --as-needed -option. Normally, the linker will add a DT_NEEDED tag for each dynamic library -mentioned on the command line, regardless of whether the library is actually -needed. -.Op --as-needed -causes DT_NEEDED tags to only be emitted for libraries that satisfy some symbol -reference from regular objects which is undefined at the point that the library -was linked. -.Op --no-as-needed -restores the default behaviour. -.Pp -.It --add-needed -.It --no-add-needed -This option affects the treatment of dynamic libraries from ELF DT_NEEDED -tags in dynamic libraries mentioned on the command line after the -.Op --no-add-needed -option. Normally, the linker will add a DT_NEEDED tag for each dynamic library -from DT_NEEDED tags. -.Op --no-add-needed -causes DT_NEEDED tags will never be emitted for those libraries from DT_NEEDED -tags. -.Op --add-needed -restores the default behaviour. -.Pp -.It -assert Va keyword -This option is ignored for SunOS compatibility. -.Pp -.It -Bdynamic -.It -dy -.It -call_shared -Link against dynamic libraries. This is only meaningful on platforms for which -shared libraries are supported. This option is normally the default on such -platforms. The different variants of this option are for compatibility with -various systems. You may use this option multiple times on the command line: -it affects library searching for -.Op -l -options which follow it. -.Pp -.It -Bgroup -Set the -.Li DF_1_GROUP -flag in the -.Li DT_FLAGS_1 -entry in the dynamic section. This causes the runtime linker to handle lookups -in this object and its dependencies to be performed only inside the group. -.Op --unresolved-symbols=report-all -is implied. This option is only meaningful on ELF platforms which support -shared libraries. -.Pp -.It -Bstatic -.It -dn -.It -non_shared -.It -static -Do not link against shared libraries. This is only meaningful on platforms -for which shared libraries are supported. The different variants of this option -are for compatibility with various systems. You may use this option multiple -times on the command line: it affects library searching for -.Op -l -options which follow it. This option also implies -.Op --unresolved-symbols=report-all . -This option can be used with -.Op -shared . -Doing so means that a shared library is being created but that all of the -library's external references must be resolved by pulling in entries from -static libraries. -.Pp -.It -Bsymbolic -When creating a shared library, bind references to global symbols to the definition -within the shared library, if any. Normally, it is possible for a program -linked against a shared library to override the definition within the shared -library. This option is only meaningful on ELF platforms which support shared -libraries. -.Pp -.It -Bsymbolic-functions -When creating a shared library, bind references to global function symbols -to the definition within the shared library, if any. This option is only meaningful -on ELF platforms which support shared libraries. -.Pp -.It --dynamic-list= Va dynamic-list-file -Specify the name of a dynamic list file to the linker. This is typically used -when creating shared libraries to specify a list of global symbols whose references -shouldn't be bound to the definition within the shared library, or creating -dynamically linked executables to specify a list of symbols which should be -added to the symbol table in the executable. This option is only meaningful -on ELF platforms which support shared libraries. -.Pp -The format of the dynamic list is the same as the version node without scope -and node name. See VERSION for more information. -.Pp -.It --dynamic-list-data -Include all global data symbols to the dynamic list. -.Pp -.It --dynamic-list-cpp-new -Provide the builtin dynamic list for C++ operator new and delete. It is mainly -useful for building shared libstdc++. -.Pp -.It --dynamic-list-cpp-typeinfo -Provide the builtin dynamic list for C++ runtime type identification. -.Pp -.It --check-sections -.It --no-check-sections -Asks the linker -.Em not -to check section addresses after they have been assigned to see if there are -any overlaps. Normally the linker will perform this check, and if it finds -any overlaps it will produce suitable error messages. The linker does know -about, and does make allowances for sections in overlays. The default behaviour -can be restored by using the command line switch -.Op --check-sections . -.Pp -.It --cref -Output a cross reference table. If a linker map file is being generated, the -cross reference table is printed to the map file. Otherwise, it is printed -on the standard output. -.Pp -The format of the table is intentionally simple, so that it may be easily -processed by a script if necessary. The symbols are printed out, sorted by -name. For each symbol, a list of file names is given. If the symbol is defined, -the first file listed is the location of the definition. The remaining files -contain references to the symbol. -.Pp -.It --no-define-common -This option inhibits the assignment of addresses to common symbols. The script -command -.Li INHIBIT_COMMON_ALLOCATION -has the same effect.See Section -.Dq Miscellaneous Commands . -.Pp -The -.Li --no-define-common -option allows decoupling the decision to assign addresses to Common symbols -from the choice of the output file type; otherwise a non-Relocatable output -type forces assigning addresses to Common symbols. Using -.Li --no-define-common -allows Common symbols that are referenced from a shared library to be assigned -addresses only in the main program. This eliminates the unused duplicate space -in the shared library, and also prevents any possible confusion over resolving -to the wrong duplicate when there are many dynamic modules with specialized -search paths for runtime symbol resolution. -.Pp -.It --defsym Va symbol= Va expression -Create a global symbol in the output file, containing the absolute address -given by -.Va expression . -You may use this option as many times as necessary to define multiple symbols -in the command line. A limited form of arithmetic is supported for the -.Va expression -in this context: you may give a hexadecimal constant or the name of an existing -symbol, or use -.Li + -and -.Li - -to add or subtract hexadecimal constants or symbols. If you need more elaborate -expressions, consider using the linker command language from a script (see Section -.Dq Assignments ) . -.Em Note: -there should be no white space between -.Va symbol , -the equals sign (\(lq=\(rq), and -.Va expression . -.Pp -.It --demangle[= Va style] -.It --no-demangle -These options control whether to demangle symbol names in error messages and -other output. When the linker is told to demangle, it tries to present symbol -names in a readable fashion: it strips leading underscores if they are used -by the object file format, and converts C++ mangled symbol names into user -readable names. Different compilers have different mangling styles. The optional -demangling style argument can be used to choose an appropriate demangling -style for your compiler. The linker will demangle by default unless the environment -variable -.Li COLLECT_NO_DEMANGLE -is set. These options may be used to override the default. -.Pp -.It --dynamic-linker Va file -Set the name of the dynamic linker. This is only meaningful when generating -dynamically linked ELF executables. The default dynamic linker is normally -correct; don't use this unless you know what you are doing. -.Pp -.It --fatal-warnings -Treat all warnings as errors. -.Pp -.It --force-exe-suffix -Make sure that an output file has a .exe suffix. -.Pp -If a successfully built fully linked output file does not have a -.Li .exe -or -.Li .dll -suffix, this option forces the linker to copy the output file to one of the -same name with a -.Li .exe -suffix. This option is useful when using unmodified Unix makefiles on a Microsoft -Windows host, since some versions of Windows won't run an image unless it -ends in a -.Li .exe -suffix. -.Pp -.It --gc-sections -.It --no-gc-sections -Enable garbage collection of unused input sections. It is ignored on targets -that do not support this option. This option is not compatible with -.Li -r -or -.Li --emit-relocs . -The default behaviour (of not performing this garbage collection) can be restored -by specifying -.Li --no-gc-sections -on the command line. -.Pp -.It --print-gc-sections -.It --no-print-gc-sections -List all sections removed by garbage collection. The listing is printed on -stderr. This option is only effective if garbage collection has been enabled -via the -.Li --gc-sections ) -option. The default behaviour (of not listing the sections that are removed) -can be restored by specifying -.Li --no-print-gc-sections -on the command line. -.Pp -.It --help -Print a summary of the command-line options on the standard output and exit. -.Pp -.It --target-help -Print a summary of all target specific options on the standard output and -exit. -.Pp -.It -Map Va mapfile -Print a link map to the file -.Va mapfile . -See the description of the -.Op -M -option, above. -.Pp -.It --no-keep-memory -.Xr ld -normally optimizes for speed over memory usage by caching the symbol tables -of input files in memory. This option tells -.Xr ld -to instead optimize for memory usage, by rereading the symbol tables as necessary. -This may be required if -.Xr ld -runs out of memory space while linking a large executable. -.Pp -.It --no-undefined -.It -z defs -Report unresolved symbol references from regular object files. This is done -even if the linker is creating a non-symbolic shared library. The switch -.Op --[no-]allow-shlib-undefined -controls the behaviour for reporting unresolved references found in shared -libraries being linked in. -.Pp -.It --allow-multiple-definition -.It -z muldefs -Normally when a symbol is defined multiple times, the linker will report a -fatal error. These options allow multiple definitions and the first definition -will be used. -.Pp -.It --allow-shlib-undefined -.It --no-allow-shlib-undefined -Allows (the default) or disallows undefined symbols in shared libraries. This -switch is similar to -.Op --no-undefined -except that it determines the behaviour when the undefined symbols are in -a shared library rather than a regular object file. It does not affect how -undefined symbols in regular object files are handled. -.Pp -The reason that -.Op --allow-shlib-undefined -is the default is that the shared library being specified at link time may -not be the same as the one that is available at load time, so the symbols -might actually be resolvable at load time. Plus there are some systems, (eg -BeOS) where undefined symbols in shared libraries is normal. (The kernel patches -them at load time to select which function is most appropriate for the current -architecture. This is used for example to dynamically select an appropriate -memset function). Apparently it is also normal for HPPA shared libraries to -have undefined symbols. -.Pp -.It --no-undefined-version -Normally when a symbol has an undefined version, the linker will ignore it. -This option disallows symbols with undefined version and a fatal error will -be issued instead. -.Pp -.It --default-symver -Create and use a default symbol version (the soname) for unversioned exported -symbols. -.Pp -.It --default-imported-symver -Create and use a default symbol version (the soname) for unversioned imported -symbols. -.Pp -.It --no-warn-mismatch -Normally -.Xr ld -will give an error if you try to link together input files that are mismatched -for some reason, perhaps because they have been compiled for different processors -or for different endiannesses. This option tells -.Xr ld -that it should silently permit such possible errors. This option should only -be used with care, in cases when you have taken some special action that ensures -that the linker errors are inappropriate. -.Pp -.It --no-warn-search-mismatch -Normally -.Xr ld -will give a warning if it finds an incompatible library during a library search. -This option silences the warning. -.Pp -.It --no-whole-archive -Turn off the effect of the -.Op --whole-archive -option for subsequent archive files. -.Pp -.It --noinhibit-exec -Retain the executable output file whenever it is still usable. Normally, the -linker will not produce an output file if it encounters errors during the -link process; it exits without writing an output file when it issues any error -whatsoever. -.Pp -.It -nostdlib -Only search library directories explicitly specified on the command line. -Library directories specified in linker scripts (including linker scripts -specified on the command line) are ignored. -.Pp -.It --oformat Va output-format -.Xr ld -may be configured to support more than one kind of object file. If your -.Xr ld -is configured this way, you can use the -.Li --oformat -option to specify the binary format for the output object file. Even when -.Xr ld -is configured to support alternative object formats, you don't usually need -to specify this, as -.Xr ld -should be configured to produce as a default output format the most usual -format on each machine. -.Va output-format -is a text string, the name of a particular format supported by the BFD libraries. -(You can list the available binary formats with -.Li objdump -i . ) -The script command -.Li OUTPUT_FORMAT -can also specify the output format, but this option overrides it.See Section -.Dq BFD . -.Pp -.It -pie -.It --pic-executable -Create a position independent executable. This is currently only supported -on ELF platforms. Position independent executables are similar to shared libraries -in that they are relocated by the dynamic linker to the virtual address the -OS chooses for them (which can vary between invocations). Like normal dynamically -linked executables they can be executed and symbols defined in the executable -cannot be overridden by shared libraries. -.Pp -.It -qmagic -This option is ignored for Linux compatibility. -.Pp -.It -Qy -This option is ignored for SVR4 compatibility. -.Pp -.It --relax -An option with machine dependent effects. This option is only supported on -a few targets.See Section -.Dq H8/300 . -See Section.Dq i960 . -See Section.Dq Xtensa . -See Section.Dq M68HC11/68HC12 . -See Section.Dq PowerPC ELF32 . -.Pp -On some platforms, the -.Li --relax -option performs global optimizations that become possible when the linker -resolves addressing in the program, such as relaxing address modes and synthesizing -new instructions in the output object file. -.Pp -On some platforms these link time global optimizations may make symbolic debugging -of the resulting executable impossible. This is known to be the case for the -Matsushita MN10200 and MN10300 family of processors. -.Pp -On platforms where this is not supported, -.Li --relax -is accepted, but ignored. -.Pp -.It --retain-symbols-file Va filename -Retain -.Em only -the symbols listed in the file -.Va filename , -discarding all others. -.Va filename -is simply a flat file, with one symbol name per line. This option is especially -useful in environments (such as VxWorks) where a large global symbol table -is accumulated gradually, to conserve run-time memory. -.Pp -.Li --retain-symbols-file -does -.Em not -discard undefined symbols, or symbols needed for relocations. -.Pp -You may only specify -.Li --retain-symbols-file -once in the command line. It overrides -.Li -s -and -.Li -S . -.Pp -.It -rpath Va dir -Add a directory to the runtime library search path. This is used when linking -an ELF executable with shared objects. All -.Op -rpath -arguments are concatenated and passed to the runtime linker, which uses them -to locate shared objects at runtime. The -.Op -rpath -option is also used when locating shared objects which are needed by shared -objects explicitly included in the link; see the description of the -.Op -rpath-link -option. If -.Op -rpath -is not used when linking an ELF executable, the contents of the environment -variable -.Li LD_RUN_PATH -will be used if it is defined. -.Pp -The -.Op -rpath -option may also be used on SunOS. By default, on SunOS, the linker will form -a runtime search patch out of all the -.Op -L -options it is given. If a -.Op -rpath -option is used, the runtime search path will be formed exclusively using the -.Op -rpath -options, ignoring the -.Op -L -options. This can be useful when using gcc, which adds many -.Op -L -options which may be on NFS mounted file systems. -.Pp -For compatibility with other ELF linkers, if the -.Op -R -option is followed by a directory name, rather than a file name, it is treated -as the -.Op -rpath -option. -.Pp -.It -rpath-link Va DIR -When using ELF or SunOS, one shared library may require another. This happens -when an -.Li ld -shared -link includes a shared library as one of the input files. -.Pp -When the linker encounters such a dependency when doing a non-shared, non-relocatable -link, it will automatically try to locate the required shared library and -include it in the link, if it is not included explicitly. In such a case, -the -.Op -rpath-link -option specifies the first set of directories to search. The -.Op -rpath-link -option may specify a sequence of directory names either by specifying a list -of names separated by colons, or by appearing multiple times. -.Pp -This option should be used with caution as it overrides the search path that -may have been hard compiled into a shared library. In such a case it is possible -to use unintentionally a different search path than the runtime linker would -do. -.Pp -The linker uses the following search paths to locate required shared libraries: -.Bl -enum -.It -Any directories specified by -.Op -rpath-link -options. -.It -Any directories specified by -.Op -rpath -options. The difference between -.Op -rpath -and -.Op -rpath-link -is that directories specified by -.Op -rpath -options are included in the executable and used at runtime, whereas the -.Op -rpath-link -option is only effective at link time. Searching -.Op -rpath -in this way is only supported by native linkers and cross linkers which have -been configured with the -.Op --with-sysroot -option. -.It -On an ELF system, if the -.Op -rpath -and -.Li rpath-link -options were not used, search the contents of the environment variable -.Li LD_RUN_PATH . -It is for the native linker only. -.It -On SunOS, if the -.Op -rpath -option was not used, search any directories specified using -.Op -L -options. -.It -For a native linker, the contents of the environment variable -.Li LD_LIBRARY_PATH . -.It -For a native ELF linker, the directories in -.Li DT_RUNPATH -or -.Li DT_RPATH -of a shared library are searched for shared libraries needed by it. The -.Li DT_RPATH -entries are ignored if -.Li DT_RUNPATH -entries exist. -.It -The default directories, normally -.Pa /lib -and -.Pa /usr/lib . -.It -For a native linker on an ELF system, if the file -.Pa /etc/ld.so.conf -exists, the list of directories found in that file. -.El -.Pp -If the required shared library is not found, the linker will issue a warning -and continue with the link. -.Pp -.It -shared -.It -Bshareable -Create a shared library. This is currently only supported on ELF, XCOFF and -SunOS platforms. On SunOS, the linker will automatically create a shared library -if the -.Op -e -option is not used and there are undefined symbols in the link. -.Pp -.It --sort-common -This option tells -.Xr ld -to sort the common symbols by size when it places them in the appropriate -output sections. First come all the one byte symbols, then all the two byte, -then all the four byte, and then everything else. This is to prevent gaps -between symbols due to alignment constraints. -.Pp -.It --sort-section name -This option will apply -.Li SORT_BY_NAME -to all wildcard section patterns in the linker script. -.Pp -.It --sort-section alignment -This option will apply -.Li SORT_BY_ALIGNMENT -to all wildcard section patterns in the linker script. -.Pp -.It --split-by-file [ Va size] -Similar to -.Op --split-by-reloc -but creates a new output section for each input file when -.Va size -is reached. -.Va size -defaults to a size of 1 if not given. -.Pp -.It --split-by-reloc [ Va count] -Tries to creates extra sections in the output file so that no single output -section in the file contains more than -.Va count -relocations. This is useful when generating huge relocatable files for downloading -into certain real time kernels with the COFF object file format; since COFF -cannot represent more than 65535 relocations in a single section. Note that -this will fail to work with object file formats which do not support arbitrary -sections. The linker will not split up individual input sections for redistribution, -so if a single input section contains more than -.Va count -relocations one output section will contain that many relocations. -.Va count -defaults to a value of 32768. -.Pp -.It --stats -Compute and display statistics about the operation of the linker, such as -execution time and memory usage. -.Pp -.It --sysroot= Va directory -Use -.Va directory -as the location of the sysroot, overriding the configure-time default. This -option is only supported by linkers that were configured using -.Op --with-sysroot . -.Pp -.It --traditional-format -For some targets, the output of -.Xr ld -is different in some ways from the output of some existing linker. This switch -requests -.Xr ld -to use the traditional format instead. -.Pp -For example, on SunOS, -.Xr ld -combines duplicate entries in the symbol string table. This can reduce the -size of an output file with full debugging information by over 30 percent. -Unfortunately, the SunOS -.Li dbx -program can not read the resulting program ( -.Li gdb -has no trouble). The -.Li --traditional-format -switch tells -.Xr ld -to not combine duplicate entries. -.Pp -.It --section-start Va sectionname= Va org -Locate a section in the output file at the absolute address given by -.Va org . -You may use this option as many times as necessary to locate multiple sections -in the command line. -.Va org -must be a single hexadecimal integer; for compatibility with other linkers, -you may omit the leading -.Li 0x -usually associated with hexadecimal values. -.Em Note: -there should be no white space between -.Va sectionname , -the equals sign (\(lq=\(rq), and -.Va org . -.Pp -.It -Tbss Va org -.It -Tdata Va org -.It -Ttext Va org -Same as --section-start, with -.Li .bss , -.Li .data -or -.Li .text -as the -.Va sectionname . -.Pp -.It --unresolved-symbols= Va method -Determine how to handle unresolved symbols. There are four possible values -for -.Li method : -.Pp -.Bl -tag -width Ds -.It ignore-all -Do not report any unresolved symbols. -.Pp -.It report-all -Report all unresolved symbols. This is the default. -.Pp -.It ignore-in-object-files -Report unresolved symbols that are contained in shared libraries, but ignore -them if they come from regular object files. -.Pp -.It ignore-in-shared-libs -Report unresolved symbols that come from regular object files, but ignore -them if they come from shared libraries. This can be useful when creating -a dynamic binary and it is known that all the shared libraries that it should -be referencing are included on the linker's command line. -.El -.Pp -The behaviour for shared libraries on their own can also be controlled by -the -.Op --[no-]allow-shlib-undefined -option. -.Pp -Normally the linker will generate an error message for each reported unresolved -symbol but the option -.Op --warn-unresolved-symbols -can change this to a warning. -.Pp -.It --dll-verbose -.It --verbose -Display the version number for -.Xr ld -and list the linker emulations supported. Display which input files can and -cannot be opened. Display the linker script being used by the linker. -.Pp -.It --version-script= Va version-scriptfile -Specify the name of a version script to the linker. This is typically used -when creating shared libraries to specify additional information about the -version hierarchy for the library being created. This option is only meaningful -on ELF platforms which support shared libraries.See Section -.Dq VERSION . -.Pp -.It --warn-common -Warn when a common symbol is combined with another common symbol or with a -symbol definition. Unix linkers allow this somewhat sloppy practise, but linkers -on some other operating systems do not. This option allows you to find potential -problems from combining global symbols. Unfortunately, some C libraries use -this practise, so you may get some warnings about symbols in the libraries -as well as in your programs. -.Pp -There are three kinds of global symbols, illustrated here by C examples: -.Pp -.Bl -tag -width Ds -.It int i = 1; -A definition, which goes in the initialized data section of the output file. -.Pp -.It extern int i; -An undefined reference, which does not allocate space. There must be either -a definition or a common symbol for the variable somewhere. -.Pp -.It int i; -A common symbol. If there are only (one or more) common symbols for a variable, -it goes in the uninitialized data area of the output file. The linker merges -multiple common symbols for the same variable into a single symbol. If they -are of different sizes, it picks the largest size. The linker turns a common -symbol into a declaration, if there is a definition of the same variable. -.El -.Pp -The -.Li --warn-common -option can produce five kinds of warnings. Each warning consists of a pair -of lines: the first describes the symbol just encountered, and the second -describes the previous symbol encountered with the same name. One or both -of the two symbols will be a common symbol. -.Pp -.Bl -enum -.It -Turning a common symbol into a reference, because there is already a definition -for the symbol. -.Bd -literal -offset indent -file(section): warning: common of `symbol' - overridden by definition -file(section): warning: defined here -.Ed -.Pp -.It -Turning a common symbol into a reference, because a later definition for the -symbol is encountered. This is the same as the previous case, except that -the symbols are encountered in a different order. -.Bd -literal -offset indent -file(section): warning: definition of `symbol' - overriding common -file(section): warning: common is here -.Ed -.Pp -.It -Merging a common symbol with a previous same-sized common symbol. -.Bd -literal -offset indent -file(section): warning: multiple common - of `symbol' -file(section): warning: previous common is here -.Ed -.Pp -.It -Merging a common symbol with a previous larger common symbol. -.Bd -literal -offset indent -file(section): warning: common of `symbol' - overridden by larger common -file(section): warning: larger common is here -.Ed -.Pp -.It -Merging a common symbol with a previous smaller common symbol. This is the -same as the previous case, except that the symbols are encountered in a different -order. -.Bd -literal -offset indent -file(section): warning: common of `symbol' - overriding smaller common -file(section): warning: smaller common is here -.Ed -.El -.Pp -.It --warn-constructors -Warn if any global constructors are used. This is only useful for a few object -file formats. For formats like COFF or ELF, the linker can not detect the -use of global constructors. -.Pp -.It --warn-multiple-gp -Warn if multiple global pointer values are required in the output file. This -is only meaningful for certain processors, such as the Alpha. Specifically, -some processors put large-valued constants in a special section. A special -register (the global pointer) points into the middle of this section, so that -constants can be loaded efficiently via a base-register relative addressing -mode. Since the offset in base-register relative mode is fixed and relatively -small (e.g., 16 bits), this limits the maximum size of the constant pool. -Thus, in large programs, it is often necessary to use multiple global pointer -values in order to be able to address all possible constants. This option -causes a warning to be issued whenever this case occurs. -.Pp -.It --warn-once -Only warn once for each undefined symbol, rather than once per module which -refers to it. -.Pp -.It --warn-section-align -Warn if the address of an output section is changed because of alignment. -Typically, the alignment will be set by an input section. The address will -only be changed if it not explicitly specified; that is, if the -.Li SECTIONS -command does not specify a start address for the section (see Section -.Dq SECTIONS ) . -.Pp -.It --warn-shared-textrel -Warn if the linker adds a DT_TEXTREL to a shared object. -.Pp -.It --warn-unresolved-symbols -If the linker is going to report an unresolved symbol (see the option -.Op --unresolved-symbols ) -it will normally generate an error. This option makes it generate a warning -instead. -.Pp -.It --error-unresolved-symbols -This restores the linker's default behaviour of generating errors when it -is reporting unresolved symbols. -.Pp -.It --whole-archive -For each archive mentioned on the command line after the -.Op --whole-archive -option, include every object file in the archive in the link, rather than -searching the archive for the required object files. This is normally used -to turn an archive file into a shared library, forcing every object to be -included in the resulting shared library. This option may be used more than -once. -.Pp -Two notes when using this option from gcc: First, gcc doesn't know about this -option, so you have to use -.Op -Wl,-whole-archive . -Second, don't forget to use -.Op -Wl,-no-whole-archive -after your list of archives, because gcc will add its own list of archives -to your link and you may not want this flag to affect those as well. -.Pp -.It --wrap Va symbol -Use a wrapper function for -.Va symbol . -Any undefined reference to -.Va symbol -will be resolved to -.Li __wrap_ Va symbol . -Any undefined reference to -.Li __real_ Va symbol -will be resolved to -.Va symbol . -.Pp -This can be used to provide a wrapper for a system function. The wrapper function -should be called -.Li __wrap_ Va symbol . -If it wishes to call the system function, it should call -.Li __real_ Va symbol . -.Pp -Here is a trivial example: -.Pp -.Bd -literal -offset indent -void * -__wrap_malloc (size_t c) -{ - printf ("malloc called with %zu\en", c); - return __real_malloc (c); -} -.Ed -.Pp -If you link other code with this file using -.Op --wrap malloc , -then all calls to -.Li malloc -will call the function -.Li __wrap_malloc -instead. The call to -.Li __real_malloc -in -.Li __wrap_malloc -will call the real -.Li malloc -function. -.Pp -You may wish to provide a -.Li __real_malloc -function as well, so that links without the -.Op --wrap -option will succeed. If you do this, you should not put the definition of -.Li __real_malloc -in the same file as -.Li __wrap_malloc ; -if you do, the assembler may resolve the call before the linker has a chance -to wrap it to -.Li malloc . -.Pp -.It --eh-frame-hdr -Request creation of -.Li .eh_frame_hdr -section and ELF -.Li PT_GNU_EH_FRAME -segment header. -.Pp -.It --enable-new-dtags -.It --disable-new-dtags -This linker can create the new dynamic tags in ELF. But the older ELF systems -may not understand them. If you specify -.Op --enable-new-dtags , -the dynamic tags will be created as needed. If you specify -.Op --disable-new-dtags , -no new dynamic tags will be created. By default, the new dynamic tags are -not created. Note that those options are only available for ELF systems. -.Pp -.It --hash-size= Va number -Set the default size of the linker's hash tables to a prime number close to -.Va number . -Increasing this value can reduce the length of time it takes the linker to -perform its tasks, at the expense of increasing the linker's memory requirements. -Similarly reducing this value can reduce the memory requirements at the expense -of speed. -.Pp -.It --hash-style= Va style -Set the type of linker's hash table(s). -.Va style -can be either -.Li sysv -for classic ELF -.Li .hash -section, -.Li GNU -for new style GNU -.Li .GNU.hash -section or -.Li both -for both the classic ELF -.Li .hash -and new style GNU -.Li .GNU.hash -hash tables. The default is -.Li sysv . -.Pp -.It --reduce-memory-overheads -This option reduces memory requirements at ld runtime, at the expense of linking -speed. This was introduced to select the old O(n^2) algorithm for link map -file generation, rather than the new O(n) algorithm which uses about 40% more -memory for symbol storage. -.Pp -Another effect of the switch is to set the default hash table size to 1021, -which again saves memory at the cost of lengthening the linker's run time. -This is not done however if the -.Op --hash-size -switch has been used. -.Pp -The -.Op --reduce-memory-overheads -switch may be also be used to enable other tradeoffs in future versions of -the linker. -.Pp -.El -.Em Options Specific to i386 PE Targets -.Pp -The i386 PE linker supports the -.Op -shared -option, which causes the output to be a dynamically linked library (DLL) instead -of a normal executable. You should name the output -.Li *.dll -when you use this option. In addition, the linker fully supports the standard -.Li *.def -files, which may be specified on the linker command line like an object file -(in fact, it should precede archives it exports symbols from, to ensure that -they get linked in, just like a normal object file). -.Pp -In addition to the options common to all targets, the i386 PE linker support -additional command line options that are specific to the i386 PE target. Options -that take values may be separated from their values by either a space or an -equals sign. -.Pp -.Bl -tag -width Ds -.It --add-stdcall-alias -If given, symbols with a stdcall suffix (@ -.Va nn ) -will be exported as-is and also with the suffix stripped. [This option is -specific to the i386 PE targeted port of the linker] -.Pp -.It --base-file Va file -Use -.Va file -as the name of a file in which to save the base addresses of all the relocations -needed for generating DLLs with -.Pa dlltool . -[This is an i386 PE specific option] -.Pp -.It --dll -Create a DLL instead of a regular executable. You may also use -.Op -shared -or specify a -.Li LIBRARY -in a given -.Li .def -file. [This option is specific to the i386 PE targeted port of the linker] -.Pp -.It --enable-stdcall-fixup -.It --disable-stdcall-fixup -If the link finds a symbol that it cannot resolve, it will attempt to do \(lqfuzzy -linking\(rq by looking for another defined symbol that differs only in the format -of the symbol name (cdecl vs stdcall) and will resolve that symbol by linking -to the match. For example, the undefined symbol -.Li _foo -might be linked to the function -.Li _foo@12 , -or the undefined symbol -.Li _bar@16 -might be linked to the function -.Li _bar . -When the linker does this, it prints a warning, since it normally should have -failed to link, but sometimes import libraries generated from third-party -dlls may need this feature to be usable. If you specify -.Op --enable-stdcall-fixup , -this feature is fully enabled and warnings are not printed. If you specify -.Op --disable-stdcall-fixup , -this feature is disabled and such mismatches are considered to be errors. -[This option is specific to the i386 PE targeted port of the linker] -.Pp -.It --export-all-symbols -If given, all global symbols in the objects used to build a DLL will be exported -by the DLL. Note that this is the default if there otherwise wouldn't be any -exported symbols. When symbols are explicitly exported via DEF files or implicitly -exported via function attributes, the default is to not export anything else -unless this option is given. Note that the symbols -.Li DllMain@12 , -.Li DllEntryPoint@0 , -.Li DllMainCRTStartup@12 , -and -.Li impure_ptr -will not be automatically exported. Also, symbols imported from other DLLs -will not be re-exported, nor will symbols specifying the DLL's internal layout -such as those beginning with -.Li _head_ -or ending with -.Li _iname . -In addition, no symbols from -.Li libgcc , -.Li libstd++ , -.Li libmingw32 , -or -.Li crtX.o -will be exported. Symbols whose names begin with -.Li __rtti_ -or -.Li __builtin_ -will not be exported, to help with C++ DLLs. Finally, there is an extensive -list of cygwin-private symbols that are not exported (obviously, this applies -on when building DLLs for cygwin targets). These cygwin-excludes are: -.Li _cygwin_dll_entry@12 , -.Li _cygwin_crt0_common@8 , -.Li _cygwin_noncygwin_dll_entry@12 , -.Li _fmode , -.Li _impure_ptr , -.Li cygwin_attach_dll , -.Li cygwin_premain0 , -.Li cygwin_premain1 , -.Li cygwin_premain2 , -.Li cygwin_premain3 , -and -.Li environ . -[This option is specific to the i386 PE targeted port of the linker] -.Pp -.It --exclude-symbols Va symbol, Va symbol,... -Specifies a list of symbols which should not be automatically exported. The -symbol names may be delimited by commas or colons. [This option is specific -to the i386 PE targeted port of the linker] -.Pp -.It --file-alignment -Specify the file alignment. Sections in the file will always begin at file -offsets which are multiples of this number. This defaults to 512. [This option -is specific to the i386 PE targeted port of the linker] -.Pp -.It --heap Va reserve -.It --heap Va reserve, Va commit -Specify the amount of memory to reserve (and optionally commit) to be used -as heap for this program. The default is 1Mb reserved, 4K committed. [This -option is specific to the i386 PE targeted port of the linker] -.Pp -.It --image-base Va value -Use -.Va value -as the base address of your program or dll. This is the lowest memory location -that will be used when your program or dll is loaded. To reduce the need to -relocate and improve performance of your dlls, each should have a unique base -address and not overlap any other dlls. The default is 0x400000 for executables, -and 0x10000000 for dlls. [This option is specific to the i386 PE targeted -port of the linker] -.Pp -.It --kill-at -If given, the stdcall suffixes (@ -.Va nn ) -will be stripped from symbols before they are exported. [This option is specific -to the i386 PE targeted port of the linker] -.Pp -.It --large-address-aware -If given, the appropriate bit in the \(lqCharacteristics\(rq field of the COFF header -is set to indicate that this executable supports virtual addresses greater -than 2 gigabytes. This should be used in conjunction with the /3GB or /USERVA= -.Va value -megabytes switch in the \(lq[operating systems]\(rq section of the BOOT.INI. Otherwise, -this bit has no effect. [This option is specific to PE targeted ports of the -linker] -.Pp -.It --major-image-version Va value -Sets the major number of the \(lqimage version\(rq. Defaults to 1. [This option is -specific to the i386 PE targeted port of the linker] -.Pp -.It --major-os-version Va value -Sets the major number of the \(lqos version\(rq. Defaults to 4. [This option is specific -to the i386 PE targeted port of the linker] -.Pp -.It --major-subsystem-version Va value -Sets the major number of the \(lqsubsystem version\(rq. Defaults to 4. [This option -is specific to the i386 PE targeted port of the linker] -.Pp -.It --minor-image-version Va value -Sets the minor number of the \(lqimage version\(rq. Defaults to 0. [This option is -specific to the i386 PE targeted port of the linker] -.Pp -.It --minor-os-version Va value -Sets the minor number of the \(lqos version\(rq. Defaults to 0. [This option is specific -to the i386 PE targeted port of the linker] -.Pp -.It --minor-subsystem-version Va value -Sets the minor number of the \(lqsubsystem version\(rq. Defaults to 0. [This option -is specific to the i386 PE targeted port of the linker] -.Pp -.It --output-def Va file -The linker will create the file -.Va file -which will contain a DEF file corresponding to the DLL the linker is generating. -This DEF file (which should be called -.Li *.def ) -may be used to create an import library with -.Li dlltool -or may be used as a reference to automatically or implicitly exported symbols. -[This option is specific to the i386 PE targeted port of the linker] -.Pp -.It --out-implib Va file -The linker will create the file -.Va file -which will contain an import lib corresponding to the DLL the linker is generating. -This import lib (which should be called -.Li *.dll.a -or -.Li *.a -may be used to link clients against the generated DLL; this behaviour makes -it possible to skip a separate -.Li dlltool -import library creation step. [This option is specific to the i386 PE targeted -port of the linker] -.Pp -.It --enable-auto-image-base -Automatically choose the image base for DLLs, unless one is specified using -the -.Li --image-base -argument. By using a hash generated from the dllname to create unique image -bases for each DLL, in-memory collisions and relocations which can delay program -execution are avoided. [This option is specific to the i386 PE targeted port -of the linker] -.Pp -.It --disable-auto-image-base -Do not automatically generate a unique image base. If there is no user-specified -image base ( -.Li --image-base ) -then use the platform default. [This option is specific to the i386 PE targeted -port of the linker] -.Pp -.It --dll-search-prefix Va string -When linking dynamically to a dll without an import library, search for -.Li <string><basename>.dll -in preference to -.Li lib<basename>.dll . -This behaviour allows easy distinction between DLLs built for the various -"subplatforms": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically -use -.Li --dll-search-prefix=cyg . -[This option is specific to the i386 PE targeted port of the linker] -.Pp -.It --enable-auto-import -Do sophisticated linking of -.Li _symbol -to -.Li __imp__symbol -for DATA imports from DLLs, and create the necessary thunking symbols when -building the import libraries with those DATA exports. Note: Use of the 'auto-import' -extension will cause the text section of the image file to be made writable. -This does not conform to the PE-COFF format specification published by Microsoft. -.Pp -Using 'auto-import' generally will 'just work' -- but sometimes you may see -this message: -.Pp -"variable '<var>' can't be auto-imported. Please read the documentation for -ld's -.Li --enable-auto-import -for details." -.Pp -This message occurs when some (sub)expression accesses an address ultimately -given by the sum of two constants (Win32 import tables only allow one). Instances -where this may occur include accesses to member fields of struct variables -imported from a DLL, as well as using a constant index into an array variable -imported from a DLL. Any multiword variable (arrays, structs, long long, etc) -may trigger this error condition. However, regardless of the exact data type -of the offending exported variable, ld will always detect it, issue the warning, -and exit. -.Pp -There are several ways to address this difficulty, regardless of the data -type of the exported variable: -.Pp -One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task -of adjusting references in your client code for runtime environment, so this -method works only when runtime environment supports this feature. -.Pp -A second solution is to force one of the 'constants' to be a variable -- that -is, unknown and un-optimizable at compile time. For arrays, there are two -possibilities: a) make the indexee (the array's address) a variable, or b) -make the 'constant' index a variable. Thus: -.Pp -.Bd -literal -offset indent -extern type extern_array[]; -extern_array[1] --> - { volatile type *t=extern_array; t[1] } -.Ed -.Pp -or -.Pp -.Bd -literal -offset indent -extern type extern_array[]; -extern_array[1] --> - { volatile int t=1; extern_array[t] } -.Ed -.Pp -For structs (and most other multiword data types) the only option is to make -the struct itself (or the long long, or the ...) variable: -.Pp -.Bd -literal -offset indent -extern struct s extern_struct; -extern_struct.field --> - { volatile struct s *t=&extern_struct; t->field } -.Ed -.Pp -or -.Pp -.Bd -literal -offset indent -extern long long extern_ll; -extern_ll --> - { volatile long long * local_ll=&extern_ll; *local_ll } -.Ed -.Pp -A third method of dealing with this difficulty is to abandon 'auto-import' -for the offending symbol and mark it with -.Li __declspec(dllimport) . -However, in practise that requires using compile-time #defines to indicate -whether you are building a DLL, building client code that will link to the -DLL, or merely building/linking to a static library. In making the choice -between the various methods of resolving the 'direct address with constant -offset' problem, you should consider typical real-world usage: -.Pp -Original: -.Bd -literal -offset indent ---foo.h -extern int arr[]; ---foo.c -#include "foo.h" -void main(int argc, char **argv){ - printf("%d\en",arr[1]); -} -.Ed -.Pp -Solution 1: -.Bd -literal -offset indent ---foo.h -extern int arr[]; ---foo.c -#include "foo.h" -void main(int argc, char **argv){ - /* This workaround is for win32 and cygwin; do not "optimize" */ - volatile int *parr = arr; - printf("%d\en",parr[1]); -} -.Ed -.Pp -Solution 2: -.Bd -literal -offset indent ---foo.h -/* Note: auto-export is assumed (no __declspec(dllexport)) */ -#if (defined(_WIN32) || defined(__CYGWIN__)) && \e - !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) -#define FOO_IMPORT __declspec(dllimport) -#else -#define FOO_IMPORT -#endif -extern FOO_IMPORT int arr[]; ---foo.c -#include "foo.h" -void main(int argc, char **argv){ - printf("%d\en",arr[1]); -} -.Ed -.Pp -A fourth way to avoid this problem is to re-code your library to use a functional -interface rather than a data interface for the offending variables (e.g. set_foo() -and get_foo() accessor functions). [This option is specific to the i386 PE -targeted port of the linker] -.Pp -.It --disable-auto-import -Do not attempt to do sophisticated linking of -.Li _symbol -to -.Li __imp__symbol -for DATA imports from DLLs. [This option is specific to the i386 PE targeted -port of the linker] -.Pp -.It --enable-runtime-pseudo-reloc -If your code contains expressions described in --enable-auto-import section, -that is, DATA imports from DLL with non-zero offset, this switch will create -a vector of 'runtime pseudo relocations' which can be used by runtime environment -to adjust references to such data in your client code. [This option is specific -to the i386 PE targeted port of the linker] -.Pp -.It --disable-runtime-pseudo-reloc -Do not create pseudo relocations for non-zero offset DATA imports from DLLs. -This is the default. [This option is specific to the i386 PE targeted port -of the linker] -.Pp -.It --enable-extra-pe-debug -Show additional debug info related to auto-import symbol thunking. [This option -is specific to the i386 PE targeted port of the linker] -.Pp -.It --section-alignment -Sets the section alignment. Sections in memory will always begin at addresses -which are a multiple of this number. Defaults to 0x1000. [This option is specific -to the i386 PE targeted port of the linker] -.Pp -.It --stack Va reserve -.It --stack Va reserve, Va commit -Specify the amount of memory to reserve (and optionally commit) to be used -as stack for this program. The default is 2Mb reserved, 4K committed. [This -option is specific to the i386 PE targeted port of the linker] -.Pp -.It --subsystem Va which -.It --subsystem Va which: Va major -.It --subsystem Va which: Va major. Va minor -Specifies the subsystem under which your program will execute. The legal values -for -.Va which -are -.Li native , -.Li windows , -.Li console , -.Li posix , -and -.Li xbox . -You may optionally set the subsystem version also. Numeric values are also -accepted for -.Va which . -[This option is specific to the i386 PE targeted port of the linker] -.Pp -.El -.Em Options specific to Motorola 68HC11 and 68HC12 targets -.Pp -The 68HC11 and 68HC12 linkers support specific options to control the memory -bank switching mapping and trampoline code generation. -.Pp -.Bl -tag -width Ds -.It --no-trampoline -This option disables the generation of trampoline. By default a trampoline -is generated for each far function which is called using a -.Li jsr -instruction (this happens when a pointer to a far function is taken). -.Pp -.It --bank-window Va name -This option indicates to the linker the name of the memory region in the -.Li MEMORY -specification that describes the memory bank window. The definition of such -region is then used by the linker to compute paging and addresses within the -memory window. -.Pp -.El -.Ss Environment Variables -You can change the behaviour of -.Xr ld -with the environment variables -.Li GNUTARGET , -.Li LDEMULATION -and -.Li COLLECT_NO_DEMANGLE . -.Pp -.Li GNUTARGET -determines the input-file object format if you don't use -.Li -b -(or its synonym -.Li --format ) . -Its value should be one of the BFD names for an input format (see Section -.Dq BFD ) . -If there is no -.Li GNUTARGET -in the environment, -.Xr ld -uses the natural format of the target. If -.Li GNUTARGET -is set to -.Li default -then BFD attempts to discover the input format by examining binary input files; -this method often succeeds, but there are potential ambiguities, since there -is no method of ensuring that the magic number used to specify object-file -formats is unique. However, the configuration procedure for BFD on each system -places the conventional format for that system first in the search-list, so -ambiguities are resolved in favor of convention. -.Pp -.Li LDEMULATION -determines the default emulation if you don't use the -.Li -m -option. The emulation can affect various aspects of linker behaviour, particularly -the default linker script. You can list the available emulations with the -.Li --verbose -or -.Li -V -options. If the -.Li -m -option is not used, and the -.Li LDEMULATION -environment variable is not defined, the default emulation depends upon how -the linker was configured. -.Pp -Normally, the linker will default to demangling symbols. However, if -.Li COLLECT_NO_DEMANGLE -is set in the environment, then it will default to not demangling symbols. -This environment variable is used in a similar fashion by the -.Li gcc -linker wrapper program. The default may be overridden by the -.Li --demangle -and -.Li --no-demangle -options. -.Pp -.Sh Linker Scripts -Every link is controlled by a -.Em linker script . -This script is written in the linker command language. -.Pp -The main purpose of the linker script is to describe how the sections in the -input files should be mapped into the output file, and to control the memory -layout of the output file. Most linker scripts do nothing more than this. -However, when necessary, the linker script can also direct the linker to perform -many other operations, using the commands described below. -.Pp -The linker always uses a linker script. If you do not supply one yourself, -the linker will use a default script that is compiled into the linker executable. -You can use the -.Li --verbose -command line option to display the default linker script. Certain command -line options, such as -.Li -r -or -.Li -N , -will affect the default linker script. -.Pp -You may supply your own linker script by using the -.Li -T -command line option. When you do this, your linker script will replace the -default linker script. -.Pp -You may also use linker scripts implicitly by naming them as input files to -the linker, as though they were files to be linked.See Section -.Dq Implicit Linker Scripts . -.Pp -.Ss Basic Linker Script Concepts -We need to define some basic concepts and vocabulary in order to describe -the linker script language. -.Pp -The linker combines input files into a single output file. The output file -and each input file are in a special data format known as an -.Em object file format . -Each file is called an -.Em object file . -The output file is often called an -.Em executable , -but for our purposes we will also call it an object file. Each object file -has, among other things, a list of -.Em sections . -We sometimes refer to a section in an input file as an -.Em input section ; -similarly, a section in the output file is an -.Em output section . -.Pp -Each section in an object file has a name and a size. Most sections also have -an associated block of data, known as the -.Em section contents . -A section may be marked as -.Em loadable , -which mean that the contents should be loaded into memory when the output -file is run. A section with no contents may be -.Em allocatable , -which means that an area in memory should be set aside, but nothing in particular -should be loaded there (in some cases this memory must be zeroed out). A section -which is neither loadable nor allocatable typically contains some sort of -debugging information. -.Pp -Every loadable or allocatable output section has two addresses. The first -is the -.Em VMA , -or virtual memory address. This is the address the section will have when -the output file is run. The second is the -.Em LMA , -or load memory address. This is the address at which the section will be loaded. -In most cases the two addresses will be the same. An example of when they -might be different is when a data section is loaded into ROM, and then copied -into RAM when the program starts up (this technique is often used to initialize -global variables in a ROM based system). In this case the ROM address would -be the LMA, and the RAM address would be the VMA. -.Pp -You can see the sections in an object file by using the -.Li objdump -program with the -.Li -h -option. -.Pp -Every object file also has a list of -.Em symbols , -known as the -.Em symbol table . -A symbol may be defined or undefined. Each symbol has a name, and each defined -symbol has an address, among other information. If you compile a C or C++ -program into an object file, you will get a defined symbol for every defined -function and global or static variable. Every undefined function or global -variable which is referenced in the input file will become an undefined symbol. -.Pp -You can see the symbols in an object file by using the -.Li nm -program, or by using the -.Li objdump -program with the -.Li -t -option. -.Pp -.Ss Linker Script Format -Linker scripts are text files. -.Pp -You write a linker script as a series of commands. Each command is either -a keyword, possibly followed by arguments, or an assignment to a symbol. You -may separate commands using semicolons. Whitespace is generally ignored. -.Pp -Strings such as file or format names can normally be entered directly. If -the file name contains a character such as a comma which would otherwise serve -to separate file names, you may put the file name in double quotes. There -is no way to use a double quote character in a file name. -.Pp -You may include comments in linker scripts just as in C, delimited by -.Li /* -and -.Li */ . -As in C, comments are syntactically equivalent to whitespace. -.Pp -.Ss Simple Linker Script Example -Many linker scripts are fairly simple. -.Pp -The simplest possible linker script has just one command: -.Li SECTIONS . -You use the -.Li SECTIONS -command to describe the memory layout of the output file. -.Pp -The -.Li SECTIONS -command is a powerful command. Here we will describe a simple use of it. Let's -assume your program consists only of code, initialized data, and uninitialized -data. These will be in the -.Li .text , -.Li .data , -and -.Li .bss -sections, respectively. Let's assume further that these are the only sections -which appear in your input files. -.Pp -For this example, let's say that the code should be loaded at address 0x10000, -and that the data should start at address 0x8000000. Here is a linker script -which will do that: -.Bd -literal -offset indent -SECTIONS -{ - . = 0x10000; - .text : { *(.text) } - . = 0x8000000; - .data : { *(.data) } - .bss : { *(.bss) } -} -.Ed -.Pp -You write the -.Li SECTIONS -command as the keyword -.Li SECTIONS , -followed by a series of symbol assignments and output section descriptions -enclosed in curly braces. -.Pp -The first line inside the -.Li SECTIONS -command of the above example sets the value of the special symbol -.Li . , -which is the location counter. If you do not specify the address of an output -section in some other way (other ways are described later), the address is -set from the current value of the location counter. The location counter is -then incremented by the size of the output section. At the start of the -.Li SECTIONS -command, the location counter has the value -.Li 0 . -.Pp -The second line defines an output section, -.Li .text . -The colon is required syntax which may be ignored for now. Within the curly -braces after the output section name, you list the names of the input sections -which should be placed into this output section. The -.Li * -is a wildcard which matches any file name. The expression -.Li *(.text) -means all -.Li .text -input sections in all input files. -.Pp -Since the location counter is -.Li 0x10000 -when the output section -.Li .text -is defined, the linker will set the address of the -.Li .text -section in the output file to be -.Li 0x10000 . -.Pp -The remaining lines define the -.Li .data -and -.Li .bss -sections in the output file. The linker will place the -.Li .data -output section at address -.Li 0x8000000 . -After the linker places the -.Li .data -output section, the value of the location counter will be -.Li 0x8000000 -plus the size of the -.Li .data -output section. The effect is that the linker will place the -.Li .bss -output section immediately after the -.Li .data -output section in memory. -.Pp -The linker will ensure that each output section has the required alignment, -by increasing the location counter if necessary. In this example, the specified -addresses for the -.Li .text -and -.Li .data -sections will probably satisfy any alignment constraints, but the linker may -have to create a small gap between the -.Li .data -and -.Li .bss -sections. -.Pp -That's it! That's a simple and complete linker script. -.Pp -.Ss Simple Linker Script Commands -In this section we describe the simple linker script commands. -.Pp -.Em Setting the Entry Point -.Pp -The first instruction to execute in a program is called the -.Em entry point . -You can use the -.Li ENTRY -linker script command to set the entry point. The argument is a symbol name: -.Bd -literal -offset indent -ENTRY(symbol) -.Ed -.Pp -There are several ways to set the entry point. The linker will set the entry -point by trying each of the following methods in order, and stopping when -one of them succeeds: -.Bl -bullet -.It -the -.Li -e -.Va entry -command-line option; -.It -the -.Li ENTRY( Va symbol) -command in a linker script; -.It -the value of the symbol -.Li start , -if defined; -.It -the address of the first byte of the -.Li .text -section, if present; -.It -The address -.Li 0 . -.El -.Pp -.Em Commands Dealing with Files -.Pp -Several linker script commands deal with files. -.Pp -.Bl -tag -width Ds -.It INCLUDE Va filename -Include the linker script -.Va filename -at this point. The file will be searched for in the current directory, and -in any directory specified with the -.Op -L -option. You can nest calls to -.Li INCLUDE -up to 10 levels deep. -.Pp -.It INPUT( Va file, Va file, ...) -.It INPUT( Va file Va file ...) -The -.Li INPUT -command directs the linker to include the named files in the link, as though -they were named on the command line. -.Pp -For example, if you always want to include -.Pa subr.o -any time you do a link, but you can't be bothered to put it on every link -command line, then you can put -.Li INPUT (subr.o) -in your linker script. -.Pp -In fact, if you like, you can list all of your input files in the linker script, -and then invoke the linker with nothing but a -.Li -T -option. -.Pp -In case a -.Em sysroot prefix -is configured, and the filename starts with the -.Li / -character, and the script being processed was located inside the -.Em sysroot prefix , -the filename will be looked for in the -.Em sysroot prefix . -Otherwise, the linker will try to open the file in the current directory. -If it is not found, the linker will search through the archive library search -path. See the description of -.Li -L -in Options,,Command Line Options. -.Pp -If you use -.Li INPUT (-l Va file) , -.Xr ld -will transform the name to -.Li lib Va file.a , -as with the command line argument -.Li -l . -.Pp -When you use the -.Li INPUT -command in an implicit linker script, the files will be included in the link -at the point at which the linker script file is included. This can affect -archive searching. -.Pp -.It GROUP( Va file, Va file, ...) -.It GROUP( Va file Va file ...) -The -.Li GROUP -command is like -.Li INPUT , -except that the named files should all be archives, and they are searched -repeatedly until no new undefined references are created. See the description -of -.Li -( -in Options,,Command Line Options. -.Pp -.It AS_NEEDED( Va file, Va file, ...) -.It AS_NEEDED( Va file Va file ...) -This construct can appear only inside of the -.Li INPUT -or -.Li GROUP -commands, among other filenames. The files listed will be handled as if they -appear directly in the -.Li INPUT -or -.Li GROUP -commands, with the exception of ELF shared libraries, that will be added only -when they are actually needed. This construct essentially enables -.Op --as-needed -option for all the files listed inside of it and restores previous -.Op --as-needed -resp. -.Op --no-as-needed -setting afterwards. -.Pp -.It OUTPUT( Va filename) -The -.Li OUTPUT -command names the output file. Using -.Li OUTPUT( Va filename) -in the linker script is exactly like using -.Li -o Va filename -on the command line (see Section -.Dq Options ) . -If both are used, the command line option takes precedence. -.Pp -You can use the -.Li OUTPUT -command to define a default name for the output file other than the usual -default of -.Pa a.out . -.Pp -.It SEARCH_DIR( Va path) -The -.Li SEARCH_DIR -command adds -.Va path -to the list of paths where -.Xr ld -looks for archive libraries. Using -.Li SEARCH_DIR( Va path) -is exactly like using -.Li -L Va path -on the command line (see Section -.Dq Options ) . -If both are used, then the linker will search both paths. Paths specified -using the command line option are searched first. -.Pp -.It STARTUP( Va filename) -The -.Li STARTUP -command is just like the -.Li INPUT -command, except that -.Va filename -will become the first input file to be linked, as though it were specified -first on the command line. This may be useful when using a system in which -the entry point is always the start of the first file. -.El -.Pp -.Em Commands Dealing with Object File Formats -.Pp -A couple of linker script commands deal with object file formats. -.Pp -.Bl -tag -width Ds -.It OUTPUT_FORMAT( Va bfdname) -.It OUTPUT_FORMAT( Va default, Va big, Va little) -The -.Li OUTPUT_FORMAT -command names the BFD format to use for the output file (see Section -.Dq BFD ) . -Using -.Li OUTPUT_FORMAT( Va bfdname) -is exactly like using -.Li --oformat Va bfdname -on the command line (see Section -.Dq Options ) . -If both are used, the command line option takes precedence. -.Pp -You can use -.Li OUTPUT_FORMAT -with three arguments to use different formats based on the -.Li -EB -and -.Li -EL -command line options. This permits the linker script to set the output format -based on the desired endianness. -.Pp -If neither -.Li -EB -nor -.Li -EL -are used, then the output format will be the first argument, -.Va default . -If -.Li -EB -is used, the output format will be the second argument, -.Va big . -If -.Li -EL -is used, the output format will be the third argument, -.Va little . -.Pp -For example, the default linker script for the MIPS ELF target uses this command: -.Bd -literal -offset indent -OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) -.Ed -This says that the default format for the output file is -.Li elf32-bigmips , -but if the user uses the -.Li -EL -command line option, the output file will be created in the -.Li elf32-littlemips -format. -.Pp -.It TARGET( Va bfdname) -The -.Li TARGET -command names the BFD format to use when reading input files. It affects subsequent -.Li INPUT -and -.Li GROUP -commands. This command is like using -.Li -b Va bfdname -on the command line (see Section -.Dq Options ) . -If the -.Li TARGET -command is used but -.Li OUTPUT_FORMAT -is not, then the last -.Li TARGET -command is also used to set the format for the output file.See Section -.Dq BFD . -.El -.Pp -.Em Other Linker Script Commands -.Pp -There are a few other linker scripts commands. -.Pp -.Bl -tag -width Ds -.It ASSERT( Va exp, Va message) -Ensure that -.Va exp -is non-zero. If it is zero, then exit the linker with an error code, and print -.Va message . -.Pp -.It EXTERN( Va symbol Va symbol ...) -Force -.Va symbol -to be entered in the output file as an undefined symbol. Doing this may, for -example, trigger linking of additional modules from standard libraries. You -may list several -.Va symbol -s for each -.Li EXTERN , -and you may use -.Li EXTERN -multiple times. This command has the same effect as the -.Li -u -command-line option. -.Pp -.It FORCE_COMMON_ALLOCATION -This command has the same effect as the -.Li -d -command-line option: to make -.Xr ld -assign space to common symbols even if a relocatable output file is specified -( -.Li -r ) . -.Pp -.It INHIBIT_COMMON_ALLOCATION -This command has the same effect as the -.Li --no-define-common -command-line option: to make -.Li ld -omit the assignment of addresses to common symbols even for a non-relocatable -output file. -.Pp -.It NOCROSSREFS( Va section Va section ...) -This command may be used to tell -.Xr ld -to issue an error about any references among certain output sections. -.Pp -In certain types of programs, particularly on embedded systems when using -overlays, when one section is loaded into memory, another section will not -be. Any direct references between the two sections would be errors. For example, -it would be an error if code in one section called a function defined in the -other section. -.Pp -The -.Li NOCROSSREFS -command takes a list of output section names. If -.Xr ld -detects any cross references between the sections, it reports an error and -returns a non-zero exit status. Note that the -.Li NOCROSSREFS -command uses output section names, not input section names. -.Pp -.It OUTPUT_ARCH( Va bfdarch) -Specify a particular output machine architecture. The argument is one of the -names used by the BFD library (see Section -.Dq BFD ) . -You can see the architecture of an object file by using the -.Li objdump -program with the -.Li -f -option. -.El -.Pp -.Ss Assigning Values to Symbols -You may assign a value to a symbol in a linker script. This will define the -symbol and place it into the symbol table with a global scope. -.Pp -.Em Simple Assignments -.Pp -You may assign to a symbol using any of the C assignment operators: -.Pp -.Bl -tag -width Ds -.It Va symbol = Va expression ; -.It Va symbol += Va expression ; -.It Va symbol -= Va expression ; -.It Va symbol *= Va expression ; -.It Va symbol /= Va expression ; -.It Va symbol <<= Va expression ; -.It Va symbol >>= Va expression ; -.It Va symbol &= Va expression ; -.It Va symbol |= Va expression ; -.El -.Pp -The first case will define -.Va symbol -to the value of -.Va expression . -In the other cases, -.Va symbol -must already be defined, and the value will be adjusted accordingly. -.Pp -The special symbol name -.Li . -indicates the location counter. You may only use this within a -.Li SECTIONS -command.See Section -.Dq Location Counter . -.Pp -The semicolon after -.Va expression -is required. -.Pp -Expressions are defined below; see Expressions. -.Pp -You may write symbol assignments as commands in their own right, or as statements -within a -.Li SECTIONS -command, or as part of an output section description in a -.Li SECTIONS -command. -.Pp -The section of the symbol will be set from the section of the expression; -for more information, see Expression Section. -.Pp -Here is an example showing the three different places that symbol assignments -may be used: -.Pp -.Bd -literal -offset indent -floating_point = 0; -SECTIONS -{ - .text : - { - *(.text) - _etext = .; - } - _bdata = (. + 3) & ~ 3; - .data : { *(.data) } -} -.Ed -In this example, the symbol -.Li floating_point -will be defined as zero. The symbol -.Li _etext -will be defined as the address following the last -.Li .text -input section. The symbol -.Li _bdata -will be defined as the address following the -.Li .text -output section aligned upward to a 4 byte boundary. -.Pp -.Em PROVIDE -.Pp -In some cases, it is desirable for a linker script to define a symbol only -if it is referenced and is not defined by any object included in the link. -For example, traditional linkers defined the symbol -.Li etext . -However, ANSI C requires that the user be able to use -.Li etext -as a function name without encountering an error. The -.Li PROVIDE -keyword may be used to define a symbol, such as -.Li etext , -only if it is referenced but not defined. The syntax is -.Li PROVIDE( Va symbol = Va expression) . -.Pp -Here is an example of using -.Li PROVIDE -to define -.Li etext : -.Bd -literal -offset indent -SECTIONS -{ - .text : - { - *(.text) - _etext = .; - PROVIDE(etext = .); - } -} -.Ed -.Pp -In this example, if the program defines -.Li _etext -(with a leading underscore), the linker will give a multiple definition error. -If, on the other hand, the program defines -.Li etext -(with no leading underscore), the linker will silently use the definition -in the program. If the program references -.Li etext -but does not define it, the linker will use the definition in the linker script. -.Pp -.Em PROVIDE_HIDDEN -.Pp -Similar to -.Li PROVIDE . -For ELF targeted ports, the symbol will be hidden and won't be exported. -.Pp -.Em Source Code Reference -.Pp -Accessing a linker script defined variable from source code is not intuitive. -In particular a linker script symbol is not equivalent to a variable declaration -in a high level language, it is instead a symbol that does not have a value. -.Pp -Before going further, it is important to note that compilers often transform -names in the source code into different names when they are stored in the -symbol table. For example, Fortran compilers commonly prepend or append an -underscore, and C++ performs extensive -.Li name mangling . -Therefore there might be a discrepancy between the name of a variable as it -is used in source code and the name of the same variable as it is defined -in a linker script. For example in C a linker script variable might be referred -to as: -.Pp -.Bd -literal -offset indent - extern int foo; -.Ed -.Pp -But in the linker script it might be defined as: -.Pp -.Bd -literal -offset indent - _foo = 1000; -.Ed -.Pp -In the remaining examples however it is assumed that no name transformation -has taken place. -.Pp -When a symbol is declared in a high level language such as C, two things happen. -The first is that the compiler reserves enough space in the program's memory -to hold the -.Em value -of the symbol. The second is that the compiler creates an entry in the program's -symbol table which holds the symbol's -.Em address . -ie the symbol table contains the address of the block of memory holding the -symbol's value. So for example the following C declaration, at file scope: -.Pp -.Bd -literal -offset indent - int foo = 1000; -.Ed -.Pp -creates a entry called -.Li foo -in the symbol table. This entry holds the address of an -.Li int -sized block of memory where the number 1000 is initially stored. -.Pp -When a program references a symbol the compiler generates code that first -accesses the symbol table to find the address of the symbol's memory block -and then code to read the value from that memory block. So: -.Pp -.Bd -literal -offset indent - foo = 1; -.Ed -.Pp -looks up the symbol -.Li foo -in the symbol table, gets the address associated with this symbol and then -writes the value 1 into that address. Whereas: -.Pp -.Bd -literal -offset indent - int * a = & foo; -.Ed -.Pp -looks up the symbol -.Li foo -in the symbol table, gets it address and then copies this address into the -block of memory associated with the variable -.Li a . -.Pp -Linker scripts symbol declarations, by contrast, create an entry in the symbol -table but do not assign any memory to them. Thus they are an address without -a value. So for example the linker script definition: -.Pp -.Bd -literal -offset indent - foo = 1000; -.Ed -.Pp -creates an entry in the symbol table called -.Li foo -which holds the address of memory location 1000, but nothing special is stored -at address 1000. This means that you cannot access the -.Em value -of a linker script defined symbol - it has no value - all you can do is access -the -.Em address -of a linker script defined symbol. -.Pp -Hence when you are using a linker script defined symbol in source code you -should always take the address of the symbol, and never attempt to use its -value. For example suppose you want to copy the contents of a section of memory -called .ROM into a section called .FLASH and the linker script contains these -declarations: -.Pp -.Bd -literal -offset indent - - start_of_ROM = .ROM; - end_of_ROM = .ROM + sizeof (.ROM) - 1; - start_of_FLASH = .FLASH; - -.Ed -.Pp -Then the C source code to perform the copy would be: -.Pp -.Bd -literal -offset indent - - extern char start_of_ROM, end_of_ROM, start_of_FLASH; - - memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); - -.Ed -.Pp -Note the use of the -.Li & -operators. These are correct. -.Pp -.Ss SECTIONS Command -The -.Li SECTIONS -command tells the linker how to map input sections into output sections, and -how to place the output sections in memory. -.Pp -The format of the -.Li SECTIONS -command is: -.Bd -literal -offset indent -SECTIONS -{ - sections-command - sections-command - ... -} -.Ed -.Pp -Each -.Va sections-command -may of be one of the following: -.Pp -.Bl -bullet -.It -an -.Li ENTRY -command (see Section -.Dq Entry Point ) -.It -a symbol assignment (see Section -.Dq Assignments ) -.It -an output section description -.It -an overlay description -.El -.Pp -The -.Li ENTRY -command and symbol assignments are permitted inside the -.Li SECTIONS -command for convenience in using the location counter in those commands. This -can also make the linker script easier to understand because you can use those -commands at meaningful points in the layout of the output file. -.Pp -Output section descriptions and overlay descriptions are described below. -.Pp -If you do not use a -.Li SECTIONS -command in your linker script, the linker will place each input section into -an identically named output section in the order that the sections are first -encountered in the input files. If all input sections are present in the first -file, for example, the order of sections in the output file will match the -order in the first input file. The first section will be at address zero. -.Pp -.Em Output Section Description -.Pp -The full description of an output section looks like this: -.Bd -literal -offset indent - -section [address] [(type)] : - [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)] - { - output-section-command - output-section-command - ... - } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp] - -.Ed -.Pp -Most output sections do not use most of the optional section attributes. -.Pp -The whitespace around -.Va section -is required, so that the section name is unambiguous. The colon and the curly -braces are also required. The line breaks and other white space are optional. -.Pp -Each -.Va output-section-command -may be one of the following: -.Pp -.Bl -bullet -.It -a symbol assignment (see Section -.Dq Assignments ) -.It -an input section description (see Section -.Dq Input Section ) -.It -data values to include directly (see Section -.Dq Output Section Data ) -.It -a special output section keyword (see Section -.Dq Output Section Keywords ) -.El -.Pp -.Em Output Section Name -.Pp -The name of the output section is -.Va section . -.Va section -must meet the constraints of your output format. In formats which only support -a limited number of sections, such as -.Li a.out , -the name must be one of the names supported by the format ( -.Li a.out , -for example, allows only -.Li .text , -.Li .data -or -.Li .bss ) . -If the output format supports any number of sections, but with numbers and -not names (as is the case for Oasys), the name should be supplied as a quoted -numeric string. A section name may consist of any sequence of characters, -but a name which contains any unusual characters such as commas must be quoted. -.Pp -The output section name -.Li /DISCARD/ -is special; Output Section Discarding. -.Pp -.Em Output Section Address -.Pp -The -.Va address -is an expression for the VMA (the virtual memory address) of the output section. -If you do not provide -.Va address , -the linker will set it based on -.Va region -if present, or otherwise based on the current value of the location counter. -.Pp -If you provide -.Va address , -the address of the output section will be set to precisely that. If you provide -neither -.Va address -nor -.Va region , -then the address of the output section will be set to the current value of -the location counter aligned to the alignment requirements of the output section. -The alignment requirement of the output section is the strictest alignment -of any input section contained within the output section. -.Pp -For example, -.Bd -literal -offset indent -\&.text . : { *(.text) } -.Ed -and -.Bd -literal -offset indent -\&.text : { *(.text) } -.Ed -are subtly different. The first will set the address of the -.Li .text -output section to the current value of the location counter. The second will -set it to the current value of the location counter aligned to the strictest -alignment of a -.Li .text -input section. -.Pp -The -.Va address -may be an arbitrary expression; Expressions. For example, if you want to align -the section on a 0x10 byte boundary, so that the lowest four bits of the section -address are zero, you could do something like this: -.Bd -literal -offset indent -\&.text ALIGN(0x10) : { *(.text) } -.Ed -This works because -.Li ALIGN -returns the current location counter aligned upward to the specified value. -.Pp -Specifying -.Va address -for a section will change the value of the location counter. -.Pp -.Em Input Section Description -.Pp -The most common output section command is an input section description. -.Pp -The input section description is the most basic linker script operation. You -use output sections to tell the linker how to lay out your program in memory. -You use input section descriptions to tell the linker how to map the input -files into your memory layout. -.Pp -.No Input Section Basics -.Pp -An input section description consists of a file name optionally followed by -a list of section names in parentheses. -.Pp -The file name and the section name may be wildcard patterns, which we describe -further below (see Section -.Dq Input Section Wildcards ) . -.Pp -The most common input section description is to include all input sections -with a particular name in the output section. For example, to include all -input -.Li .text -sections, you would write: -.Bd -literal -offset indent -*(.text) -.Ed -Here the -.Li * -is a wildcard which matches any file name. To exclude a list of files from -matching the file name wildcard, EXCLUDE_FILE may be used to match all files -except the ones specified in the EXCLUDE_FILE list. For example: -.Bd -literal -offset indent -(*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)) -.Ed -will cause all .ctors sections from all files except -.Pa crtend.o -and -.Pa otherfile.o -to be included. -.Pp -There are two ways to include more than one section: -.Bd -literal -offset indent -*(.text .rdata) -*(.text) *(.rdata) -.Ed -The difference between these is the order in which the -.Li .text -and -.Li .rdata -input sections will appear in the output section. In the first example, they -will be intermingled, appearing in the same order as they are found in the -linker input. In the second example, all -.Li .text -input sections will appear first, followed by all -.Li .rdata -input sections. -.Pp -You can specify a file name to include sections from a particular file. You -would do this if one or more of your files contain special data that needs -to be at a particular location in memory. For example: -.Bd -literal -offset indent -data.o(.data) -.Ed -.Pp -If you use a file name without a list of sections, then all sections in the -input file will be included in the output section. This is not commonly done, -but it may by useful on occasion. For example: -.Bd -literal -offset indent -data.o -.Ed -.Pp -When you use a file name which does not contain any wild card characters, -the linker will first see if you also specified the file name on the linker -command line or in an -.Li INPUT -command. If you did not, the linker will attempt to open the file as an input -file, as though it appeared on the command line. Note that this differs from -an -.Li INPUT -command, because the linker will not search for the file in the archive search -path. -.Pp -.No Input Section Wildcard Patterns -.Pp -In an input section description, either the file name or the section name -or both may be wildcard patterns. -.Pp -The file name of -.Li * -seen in many examples is a simple wildcard pattern for the file name. -.Pp -The wildcard patterns are like those used by the Unix shell. -.Pp -.Bl -tag -width Ds -.It * -matches any number of characters -.It ? -matches any single character -.It [ Va chars] -matches a single instance of any of the -.Va chars ; -the -.Li - -character may be used to specify a range of characters, as in -.Li [a-z] -to match any lower case letter -.It \e -quotes the following character -.El -.Pp -When a file name is matched with a wildcard, the wildcard characters will -not match a -.Li / -character (used to separate directory names on Unix). A pattern consisting -of a single -.Li * -character is an exception; it will always match any file name, whether it -contains a -.Li / -or not. In a section name, the wildcard characters will match a -.Li / -character. -.Pp -File name wildcard patterns only match files which are explicitly specified -on the command line or in an -.Li INPUT -command. The linker does not search directories to expand wildcards. -.Pp -If a file name matches more than one wildcard pattern, or if a file name appears -explicitly and is also matched by a wildcard pattern, the linker will use -the first match in the linker script. For example, this sequence of input -section descriptions is probably in error, because the -.Pa data.o -rule will not be used: -.Bd -literal -offset indent -\&.data : { *(.data) } -\&.data1 : { data.o(.data) } -.Ed -.Pp -Normally, the linker will place files and sections matched by wildcards in -the order in which they are seen during the link. You can change this by using -the -.Li SORT_BY_NAME -keyword, which appears before a wildcard pattern in parentheses (e.g., -.Li SORT_BY_NAME(.text*) ) . -When the -.Li SORT_BY_NAME -keyword is used, the linker will sort the files or sections into ascending -order by name before placing them in the output file. -.Pp -.Li SORT_BY_ALIGNMENT -is very similar to -.Li SORT_BY_NAME . -The difference is -.Li SORT_BY_ALIGNMENT -will sort sections into ascending order by alignment before placing them in -the output file. -.Pp -.Li SORT -is an alias for -.Li SORT_BY_NAME . -.Pp -When there are nested section sorting commands in linker script, there can -be at most 1 level of nesting for section sorting commands. -.Pp -.Bl -enum -.It -.Li SORT_BY_NAME -( -.Li SORT_BY_ALIGNMENT -(wildcard section pattern)). It will sort the input sections by name first, -then by alignment if 2 sections have the same name. -.It -.Li SORT_BY_ALIGNMENT -( -.Li SORT_BY_NAME -(wildcard section pattern)). It will sort the input sections by alignment -first, then by name if 2 sections have the same alignment. -.It -.Li SORT_BY_NAME -( -.Li SORT_BY_NAME -(wildcard section pattern)) is treated the same as -.Li SORT_BY_NAME -(wildcard section pattern). -.It -.Li SORT_BY_ALIGNMENT -( -.Li SORT_BY_ALIGNMENT -(wildcard section pattern)) is treated the same as -.Li SORT_BY_ALIGNMENT -(wildcard section pattern). -.It -All other nested section sorting commands are invalid. -.El -.Pp -When both command line section sorting option and linker script section sorting -command are used, section sorting command always takes precedence over the -command line option. -.Pp -If the section sorting command in linker script isn't nested, the command -line option will make the section sorting command to be treated as nested -sorting command. -.Pp -.Bl -enum -.It -.Li SORT_BY_NAME -(wildcard section pattern ) with -.Op --sort-sections alignment -is equivalent to -.Li SORT_BY_NAME -( -.Li SORT_BY_ALIGNMENT -(wildcard section pattern)). -.It -.Li SORT_BY_ALIGNMENT -(wildcard section pattern) with -.Op --sort-section name -is equivalent to -.Li SORT_BY_ALIGNMENT -( -.Li SORT_BY_NAME -(wildcard section pattern)). -.El -.Pp -If the section sorting command in linker script is nested, the command line -option will be ignored. -.Pp -If you ever get confused about where input sections are going, use the -.Li -M -linker option to generate a map file. The map file shows precisely how input -sections are mapped to output sections. -.Pp -This example shows how wildcard patterns might be used to partition files. -This linker script directs the linker to place all -.Li .text -sections in -.Li .text -and all -.Li .bss -sections in -.Li .bss . -The linker will place the -.Li .data -section from all files beginning with an upper case character in -.Li .DATA ; -for all other files, the linker will place the -.Li .data -section in -.Li .data . -.Bd -literal -offset indent - -SECTIONS { - .text : { *(.text) } - .DATA : { [A-Z]*(.data) } - .data : { *(.data) } - .bss : { *(.bss) } -} - -.Ed -.Pp -.No Input Section for Common Symbols -.Pp -A special notation is needed for common symbols, because in many object file -formats common symbols do not have a particular input section. The linker -treats common symbols as though they are in an input section named -.Li COMMON . -.Pp -You may use file names with the -.Li COMMON -section just as with any other input sections. You can use this to place common -symbols from a particular input file in one section while common symbols from -other input files are placed in another section. -.Pp -In most cases, common symbols in input files will be placed in the -.Li .bss -section in the output file. For example: -.Bd -literal -offset indent -\&.bss { *(.bss) *(COMMON) } -.Ed -.Pp -Some object file formats have more than one type of common symbol. For example, -the MIPS ELF object file format distinguishes standard common symbols and -small common symbols. In this case, the linker will use a different special -section name for other types of common symbols. In the case of MIPS ELF, the -linker uses -.Li COMMON -for standard common symbols and -.Li .scommon -for small common symbols. This permits you to map the different types of common -symbols into memory at different locations. -.Pp -You will sometimes see -.Li [COMMON] -in old linker scripts. This notation is now considered obsolete. It is equivalent -to -.Li *(COMMON) . -.Pp -.No Input Section and Garbage Collection -.Pp -When link-time garbage collection is in use ( -.Li --gc-sections ) , -it is often useful to mark sections that should not be eliminated. This is -accomplished by surrounding an input section's wildcard entry with -.Li KEEP() , -as in -.Li KEEP(*(.init)) -or -.Li KEEP(SORT_BY_NAME(*)(.ctors)) . -.Pp -.No Input Section Example -.Pp -The following example is a complete linker script. It tells the linker to -read all of the sections from file -.Pa all.o -and place them at the start of output section -.Li outputa -which starts at location -.Li 0x10000 . -All of section -.Li .input1 -from file -.Pa foo.o -follows immediately, in the same output section. All of section -.Li .input2 -from -.Pa foo.o -goes into output section -.Li outputb , -followed by section -.Li .input1 -from -.Pa foo1.o . -All of the remaining -.Li .input1 -and -.Li .input2 -sections from any files are written to output section -.Li outputc . -.Pp -.Bd -literal -offset indent - -SECTIONS { - outputa 0x10000 : - { - all.o - foo.o (.input1) - } - - - outputb : - { - foo.o (.input2) - foo1.o (.input1) - } - - - outputc : - { - *(.input1) - *(.input2) - } -} - -.Ed -.Pp -.Em Output Section Data -.Pp -You can include explicit bytes of data in an output section by using -.Li BYTE , -.Li SHORT , -.Li LONG , -.Li QUAD , -or -.Li SQUAD -as an output section command. Each keyword is followed by an expression in -parentheses providing the value to store (see Section -.Dq Expressions ) . -The value of the expression is stored at the current value of the location -counter. -.Pp -The -.Li BYTE , -.Li SHORT , -.Li LONG , -and -.Li QUAD -commands store one, two, four, and eight bytes (respectively). After storing -the bytes, the location counter is incremented by the number of bytes stored. -.Pp -For example, this will store the byte 1 followed by the four byte value of -the symbol -.Li addr : -.Bd -literal -offset indent -BYTE(1) -LONG(addr) -.Ed -.Pp -When using a 64 bit host or target, -.Li QUAD -and -.Li SQUAD -are the same; they both store an 8 byte, or 64 bit, value. When both host -and target are 32 bits, an expression is computed as 32 bits. In this case -.Li QUAD -stores a 32 bit value zero extended to 64 bits, and -.Li SQUAD -stores a 32 bit value sign extended to 64 bits. -.Pp -If the object file format of the output file has an explicit endianness, which -is the normal case, the value will be stored in that endianness. When the -object file format does not have an explicit endianness, as is true of, for -example, S-records, the value will be stored in the endianness of the first -input object file. -.Pp -Note---these commands only work inside a section description and not between -them, so the following will produce an error from the linker: -.Bd -literal -offset indent -SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } -.Ed -whereas this will work: -.Bd -literal -offset indent -SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } -.Ed -.Pp -You may use the -.Li FILL -command to set the fill pattern for the current section. It is followed by -an expression in parentheses. Any otherwise unspecified regions of memory -within the section (for example, gaps left due to the required alignment of -input sections) are filled with the value of the expression, repeated as necessary. -A -.Li FILL -statement covers memory locations after the point at which it occurs in the -section definition; by including more than one -.Li FILL -statement, you can have different fill patterns in different parts of an output -section. -.Pp -This example shows how to fill unspecified regions of memory with the value -.Li 0x90 : -.Bd -literal -offset indent -FILL(0x90909090) -.Ed -.Pp -The -.Li FILL -command is similar to the -.Li = Va fillexp -output section attribute, but it only affects the part of the section following -the -.Li FILL -command, rather than the entire section. If both are used, the -.Li FILL -command takes precedence.See Section -.Dq Output Section Fill , -for details on the fill expression. -.Pp -.Em Output Section Keywords -.Pp -There are a couple of keywords which can appear as output section commands. -.Pp -.Bl -tag -width Ds -.It CREATE_OBJECT_SYMBOLS -The command tells the linker to create a symbol for each input file. The name -of each symbol will be the name of the corresponding input file. The section -of each symbol will be the output section in which the -.Li CREATE_OBJECT_SYMBOLS -command appears. -.Pp -This is conventional for the a.out object file format. It is not normally -used for any other object file format. -.Pp -.It CONSTRUCTORS -When linking using the a.out object file format, the linker uses an unusual -set construct to support C++ global constructors and destructors. When linking -object file formats which do not support arbitrary sections, such as ECOFF -and XCOFF, the linker will automatically recognize C++ global constructors -and destructors by name. For these object file formats, the -.Li CONSTRUCTORS -command tells the linker to place constructor information in the output section -where the -.Li CONSTRUCTORS -command appears. The -.Li CONSTRUCTORS -command is ignored for other object file formats. -.Pp -The symbol -.Li __CTOR_LIST__ -marks the start of the global constructors, and the symbol -.Li __CTOR_END__ -marks the end. Similarly, -.Li __DTOR_LIST__ -and -.Li __DTOR_END__ -mark the start and end of the global destructors. The first word in the list -is the number of entries, followed by the address of each constructor or destructor, -followed by a zero word. The compiler must arrange to actually run the code. -For these object file formats GNU C++ normally calls constructors from a subroutine -.Li __main ; -a call to -.Li __main -is automatically inserted into the startup code for -.Li main . -GNU C++ normally runs destructors either by using -.Li atexit , -or directly from the function -.Li exit . -.Pp -For object file formats such as -.Li COFF -or -.Li ELF -which support arbitrary section names, GNU C++ will normally arrange to put -the addresses of global constructors and destructors into the -.Li .ctors -and -.Li .dtors -sections. Placing the following sequence into your linker script will build -the sort of table which the GNU C++ runtime code expects to see. -.Pp -.Bd -literal -offset indent - __CTOR_LIST__ = .; - LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) - *(.ctors) - LONG(0) - __CTOR_END__ = .; - __DTOR_LIST__ = .; - LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) - *(.dtors) - LONG(0) - __DTOR_END__ = .; -.Ed -.Pp -If you are using the GNU C++ support for initialization priority, which provides -some control over the order in which global constructors are run, you must -sort the constructors at link time to ensure that they are executed in the -correct order. When using the -.Li CONSTRUCTORS -command, use -.Li SORT_BY_NAME(CONSTRUCTORS) -instead. When using the -.Li .ctors -and -.Li .dtors -sections, use -.Li *(SORT_BY_NAME(.ctors)) -and -.Li *(SORT_BY_NAME(.dtors)) -instead of just -.Li *(.ctors) -and -.Li *(.dtors) . -.Pp -Normally the compiler and linker will handle these issues automatically, and -you will not need to concern yourself with them. However, you may need to -consider this if you are using C++ and writing your own linker scripts. -.Pp -.El -.Em Output Section Discarding -.Pp -The linker will not create output sections with no contents. This is for convenience -when referring to input sections that may or may not be present in any of -the input files. For example: -.Bd -literal -offset indent -\&.foo : { *(.foo) } -.Ed -will only create a -.Li .foo -section in the output file if there is a -.Li .foo -section in at least one input file, and if the input sections are not all -empty. Other link script directives that allocate space in an output section -will also create the output section. -.Pp -The linker will ignore address assignments (see Section -.Dq Output Section Address ) -on discarded output sections, except when the linker script defines symbols -in the output section. In that case the linker will obey the address assignments, -possibly advancing dot even though the section is discarded. -.Pp -The special output section name -.Li /DISCARD/ -may be used to discard input sections. Any input sections which are assigned -to an output section named -.Li /DISCARD/ -are not included in the output file. -.Pp -.Em Output Section Attributes -.Pp -We showed above that the full description of an output section looked like -this: -.Bd -literal -offset indent - -section [address] [(type)] : - [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)] - { - output-section-command - output-section-command - ... - } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp] - -.Ed -We've already described -.Va section , -.Va address , -and -.Va output-section-command . -In this section we will describe the remaining section attributes. -.Pp -.No Output Section Type -.Pp -Each output section may have a type. The type is a keyword in parentheses. -The following types are defined: -.Pp -.Bl -tag -width Ds -.It NOLOAD -The section should be marked as not loadable, so that it will not be loaded -into memory when the program is run. -.It DSECT -.It COPY -.It INFO -.It OVERLAY -These type names are supported for backward compatibility, and are rarely -used. They all have the same effect: the section should be marked as not allocatable, -so that no memory is allocated for the section when the program is run. -.El -.Pp -The linker normally sets the attributes of an output section based on the -input sections which map into it. You can override this by using the section -type. For example, in the script sample below, the -.Li ROM -section is addressed at memory location -.Li 0 -and does not need to be loaded when the program is run. The contents of the -.Li ROM -section will appear in the linker output file as usual. -.Bd -literal -offset indent - -SECTIONS { - ROM 0 (NOLOAD) : { ... } - ... -} - -.Ed -.Pp -.No Output Section LMA -.Pp -Every section has a virtual address (VMA) and a load address (LMA); see Basic -Script Concepts. The address expression which may appear in an output section -description sets the VMA (see Section -.Dq Output Section Address ) . -.Pp -The expression -.Va lma -that follows the -.Li AT -keyword specifies the load address of the section. -.Pp -Alternatively, with -.Li AT> Va lma_region -expression, you may specify a memory region for the section's load address.See Section -.Dq MEMORY . -Note that if the section has not had a VMA assigned to it then the linker -will use the -.Va lma_region -as the VMA region as well. -.Pp -If neither -.Li AT -nor -.Li AT> -is specified for an allocatable section, the linker will set the LMA such -that the difference between VMA and LMA for the section is the same as the -preceding output section in the same region. If there is no preceding output -section or the section is not allocatable, the linker will set the LMA equal -to the VMA.See Section -.Dq Output Section Region . -.Pp -This feature is designed to make it easy to build a ROM image. For example, -the following linker script creates three output sections: one called -.Li .text , -which starts at -.Li 0x1000 , -one called -.Li .mdata , -which is loaded at the end of the -.Li .text -section even though its VMA is -.Li 0x2000 , -and one called -.Li .bss -to hold uninitialized data at address -.Li 0x3000 . -The symbol -.Li _data -is defined with the value -.Li 0x2000 , -which shows that the location counter holds the VMA value, not the LMA value. -.Pp -.Bd -literal -offset indent - -SECTIONS - { - .text 0x1000 : { *(.text) _etext = . ; } - .mdata 0x2000 : - AT ( ADDR (.text) + SIZEOF (.text) ) - { _data = . ; *(.data); _edata = . ; } - .bss 0x3000 : - { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;} -} - -.Ed -.Pp -The run-time initialization code for use with a program generated with this -linker script would include something like the following, to copy the initialized -data from the ROM image to its runtime address. Notice how this code takes -advantage of the symbols defined by the linker script. -.Pp -.Bd -literal -offset indent - -extern char _etext, _data, _edata, _bstart, _bend; -char *src = &_etext; -char *dst = &_data; - -/* ROM has data at end of text; copy it. */ -while (dst < &_edata) { - *dst++ = *src++; -} - -/* Zero bss */ -for (dst = &_bstart; dst< &_bend; dst++) - *dst = 0; - -.Ed -.Pp -.No Forced Output Alignment -.Pp -You can increase an output section's alignment by using ALIGN. -.Pp -.No Forced Input Alignment -.Pp -You can force input section alignment within an output section by using SUBALIGN. -The value specified overrides any alignment given by input sections, whether -larger or smaller. -.Pp -.No Output Section Region -.Pp -You can assign a section to a previously defined region of memory by using -.Li > Va region . -See Section.Dq MEMORY . -.Pp -Here is a simple example: -.Bd -literal -offset indent - -MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 } -SECTIONS { ROM : { *(.text) } >rom } - -.Ed -.Pp -.No Output Section Phdr -.Pp -You can assign a section to a previously defined program segment by using -.Li : Va phdr . -See Section.Dq PHDRS . -If a section is assigned to one or more segments, then all subsequent allocated -sections will be assigned to those segments as well, unless they use an explicitly -.Li : Va phdr -modifier. You can use -.Li :NONE -to tell the linker to not put the section in any segment at all. -.Pp -Here is a simple example: -.Bd -literal -offset indent - -PHDRS { text PT_LOAD ; } -SECTIONS { .text : { *(.text) } :text } - -.Ed -.Pp -.No Output Section Fill -.Pp -You can set the fill pattern for an entire section by using -.Li = Va fillexp . -.Va fillexp -is an expression (see Section -.Dq Expressions ) . -Any otherwise unspecified regions of memory within the output section (for -example, gaps left due to the required alignment of input sections) will be -filled with the value, repeated as necessary. If the fill expression is a -simple hex number, ie. a string of hex digit starting with -.Li 0x -and without a trailing -.Li k -or -.Li M , -then an arbitrarily long sequence of hex digits can be used to specify the -fill pattern; Leading zeros become part of the pattern too. For all other -cases, including extra parentheses or a unary -.Li + , -the fill pattern is the four least significant bytes of the value of the expression. -In all cases, the number is big-endian. -.Pp -You can also change the fill value with a -.Li FILL -command in the output section commands; (see Section -.Dq Output Section Data ) . -.Pp -Here is a simple example: -.Bd -literal -offset indent - -SECTIONS { .text : { *(.text) } =0x90909090 } - -.Ed -.Pp -.Em Overlay Description -.Pp -An overlay description provides an easy way to describe sections which are -to be loaded as part of a single memory image but are to be run at the same -memory address. At run time, some sort of overlay manager will copy the overlaid -sections in and out of the runtime memory address as required, perhaps by -simply manipulating addressing bits. This approach can be useful, for example, -when a certain region of memory is faster than another. -.Pp -Overlays are described using the -.Li OVERLAY -command. The -.Li OVERLAY -command is used within a -.Li SECTIONS -command, like an output section description. The full syntax of the -.Li OVERLAY -command is as follows: -.Bd -literal -offset indent - -OVERLAY [start] : [NOCROSSREFS] [AT ( ldaddr )] - { - secname1 - { - output-section-command - output-section-command - ... - } [:phdr...] [=fill] - secname2 - { - output-section-command - output-section-command - ... - } [:phdr...] [=fill] - ... - } [>region] [:phdr...] [=fill] - -.Ed -.Pp -Everything is optional except -.Li OVERLAY -(a keyword), and each section must have a name ( -.Va secname1 -and -.Va secname2 -above). The section definitions within the -.Li OVERLAY -construct are identical to those within the general -.Li SECTIONS -contruct (see Section -.Dq SECTIONS ) , -except that no addresses and no memory regions may be defined for sections -within an -.Li OVERLAY . -.Pp -The sections are all defined with the same starting address. The load addresses -of the sections are arranged such that they are consecutive in memory starting -at the load address used for the -.Li OVERLAY -as a whole (as with normal section definitions, the load address is optional, -and defaults to the start address; the start address is also optional, and -defaults to the current value of the location counter). -.Pp -If the -.Li NOCROSSREFS -keyword is used, and there any references among the sections, the linker will -report an error. Since the sections all run at the same address, it normally -does not make sense for one section to refer directly to another.See Section -.Dq Miscellaneous Commands . -.Pp -For each section within the -.Li OVERLAY , -the linker automatically provides two symbols. The symbol -.Li __load_start_ Va secname -is defined as the starting load address of the section. The symbol -.Li __load_stop_ Va secname -is defined as the final load address of the section. Any characters within -.Va secname -which are not legal within C identifiers are removed. C (or assembler) code -may use these symbols to move the overlaid sections around as necessary. -.Pp -At the end of the overlay, the value of the location counter is set to the -start address of the overlay plus the size of the largest section. -.Pp -Here is an example. Remember that this would appear inside a -.Li SECTIONS -construct. -.Bd -literal -offset indent - - OVERLAY 0x1000 : AT (0x4000) - { - .text0 { o1/*.o(.text) } - .text1 { o2/*.o(.text) } - } - -.Ed -This will define both -.Li .text0 -and -.Li .text1 -to start at address 0x1000. -.Li .text0 -will be loaded at address 0x4000, and -.Li .text1 -will be loaded immediately after -.Li .text0 . -The following symbols will be defined if referenced: -.Li __load_start_text0 , -.Li __load_stop_text0 , -.Li __load_start_text1 , -.Li __load_stop_text1 . -.Pp -C code to copy overlay -.Li .text1 -into the overlay area might look like the following. -.Pp -.Bd -literal -offset indent - - extern char __load_start_text1, __load_stop_text1; - memcpy ((char *) 0x1000, &__load_start_text1, - &__load_stop_text1 - &__load_start_text1); - -.Ed -.Pp -Note that the -.Li OVERLAY -command is just syntactic sugar, since everything it does can be done using -the more basic commands. The above example could have been written identically -as follows. -.Pp -.Bd -literal -offset indent - - .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } - PROVIDE (__load_start_text0 = LOADADDR (.text0)); - PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); - .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } - PROVIDE (__load_start_text1 = LOADADDR (.text1)); - PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); - . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); - -.Ed -.Pp -.Ss MEMORY Command -The linker's default configuration permits allocation of all available memory. -You can override this by using the -.Li MEMORY -command. -.Pp -The -.Li MEMORY -command describes the location and size of blocks of memory in the target. -You can use it to describe which memory regions may be used by the linker, -and which memory regions it must avoid. You can then assign sections to particular -memory regions. The linker will set section addresses based on the memory -regions, and will warn about regions that become too full. The linker will -not shuffle sections around to fit into the available regions. -.Pp -A linker script may contain at most one use of the -.Li MEMORY -command. However, you can define as many blocks of memory within it as you -wish. The syntax is: -.Bd -literal -offset indent - -MEMORY - { - name [(attr)] : ORIGIN = origin, LENGTH = len - ... - } - -.Ed -.Pp -The -.Va name -is a name used in the linker script to refer to the region. The region name -has no meaning outside of the linker script. Region names are stored in a -separate name space, and will not conflict with symbol names, file names, -or section names. Each memory region must have a distinct name. -.Pp -The -.Va attr -string is an optional list of attributes that specify whether to use a particular -memory region for an input section which is not explicitly mapped in the linker -script. As described in SECTIONS, if you do not specify an output section -for some input section, the linker will create an output section with the -same name as the input section. If you define region attributes, the linker -will use them to select the memory region for the output section that it creates. -.Pp -The -.Va attr -string must consist only of the following characters: -.Bl -tag -width Ds -.It R -Read-only section -.It W -Read/write section -.It X -Executable section -.It A -Allocatable section -.It I -Initialized section -.It L -Same as -.Li I -.It ! -Invert the sense of any of the preceding attributes -.El -.Pp -If a unmapped section matches any of the listed attributes other than -.Li ! , -it will be placed in the memory region. The -.Li ! -attribute reverses this test, so that an unmapped section will be placed in -the memory region only if it does not match any of the listed attributes. -.Pp -The -.Va origin -is an numerical expression for the start address of the memory region. The -expression must evaluate to a constant and it cannot involve any symbols. -The keyword -.Li ORIGIN -may be abbreviated to -.Li org -or -.Li o -(but not, for example, -.Li ORG ) . -.Pp -The -.Va len -is an expression for the size in bytes of the memory region. As with the -.Va origin -expression, the expression must be numerical only and must evaluate to a constant. -The keyword -.Li LENGTH -may be abbreviated to -.Li len -or -.Li l . -.Pp -In the following example, we specify that there are two memory regions available -for allocation: one starting at -.Li 0 -for 256 kilobytes, and the other starting at -.Li 0x40000000 -for four megabytes. The linker will place into the -.Li rom -memory region every section which is not explicitly mapped into a memory region, -and is either read-only or executable. The linker will place other sections -which are not explicitly mapped into a memory region into the -.Li ram -memory region. -.Pp -.Bd -literal -offset indent - -MEMORY - { - rom (rx) : ORIGIN = 0, LENGTH = 256K - ram (!rx) : org = 0x40000000, l = 4M - } - -.Ed -.Pp -Once you define a memory region, you can direct the linker to place specific -output sections into that memory region by using the -.Li > Va region -output section attribute. For example, if you have a memory region named -.Li mem , -you would use -.Li >mem -in the output section definition.See Section -.Dq Output Section Region . -If no address was specified for the output section, the linker will set the -address to the next available address within the memory region. If the combined -output sections directed to a memory region are too large for the region, -the linker will issue an error message. -.Pp -It is possible to access the origin and length of a memory in an expression -via the -.Li ORIGIN( Va memory) -and -.Li LENGTH( Va memory) -functions: -.Pp -.Bd -literal -offset indent - - _fstack = ORIGIN(ram) + LENGTH(ram) - 4; - -.Ed -.Pp -.Ss PHDRS Command -The ELF object file format uses -.Em program headers , -also knows as -.Em segments . -The program headers describe how the program should be loaded into memory. -You can print them out by using the -.Li objdump -program with the -.Li -p -option. -.Pp -When you run an ELF program on a native ELF system, the system loader reads -the program headers in order to figure out how to load the program. This will -only work if the program headers are set correctly. This manual does not describe -the details of how the system loader interprets program headers; for more -information, see the ELF ABI. -.Pp -The linker will create reasonable program headers by default. However, in -some cases, you may need to specify the program headers more precisely. You -may use the -.Li PHDRS -command for this purpose. When the linker sees the -.Li PHDRS -command in the linker script, it will not create any program headers other -than the ones specified. -.Pp -The linker only pays attention to the -.Li PHDRS -command when generating an ELF output file. In other cases, the linker will -simply ignore -.Li PHDRS . -.Pp -This is the syntax of the -.Li PHDRS -command. The words -.Li PHDRS , -.Li FILEHDR , -.Li AT , -and -.Li FLAGS -are keywords. -.Pp -.Bd -literal -offset indent - -PHDRS -{ - name type [ FILEHDR ] [ PHDRS ] [ AT ( address ) ] - [ FLAGS ( flags ) ] ; -} - -.Ed -.Pp -The -.Va name -is used only for reference in the -.Li SECTIONS -command of the linker script. It is not put into the output file. Program -header names are stored in a separate name space, and will not conflict with -symbol names, file names, or section names. Each program header must have -a distinct name. -.Pp -Certain program header types describe segments of memory which the system -loader will load from the file. In the linker script, you specify the contents -of these segments by placing allocatable output sections in the segments. -You use the -.Li : Va phdr -output section attribute to place a section in a particular segment.See Section -.Dq Output Section Phdr . -.Pp -It is normal to put certain sections in more than one segment. This merely -implies that one segment of memory contains another. You may repeat -.Li : Va phdr , -using it once for each segment which should contain the section. -.Pp -If you place a section in one or more segments using -.Li : Va phdr , -then the linker will place all subsequent allocatable sections which do not -specify -.Li : Va phdr -in the same segments. This is for convenience, since generally a whole set -of contiguous sections will be placed in a single segment. You can use -.Li :NONE -to override the default segment and tell the linker to not put the section -in any segment at all. -.Pp -You may use the -.Li FILEHDR -and -.Li PHDRS -keywords appear after the program header type to further describe the contents -of the segment. The -.Li FILEHDR -keyword means that the segment should include the ELF file header. The -.Li PHDRS -keyword means that the segment should include the ELF program headers themselves. -.Pp -The -.Va type -may be one of the following. The numbers indicate the value of the keyword. -.Pp -.Bl -tag -width Ds -.It Li PT_NULL (0) -Indicates an unused program header. -.Pp -.It Li PT_LOAD (1) -Indicates that this program header describes a segment to be loaded from the -file. -.Pp -.It Li PT_DYNAMIC (2) -Indicates a segment where dynamic linking information can be found. -.Pp -.It Li PT_INTERP (3) -Indicates a segment where the name of the program interpreter may be found. -.Pp -.It Li PT_NOTE (4) -Indicates a segment holding note information. -.Pp -.It Li PT_SHLIB (5) -A reserved program header type, defined but not specified by the ELF ABI. -.Pp -.It Li PT_PHDR (6) -Indicates a segment where the program headers may be found. -.Pp -.It Va expression -An expression giving the numeric type of the program header. This may be used -for types not defined above. -.El -.Pp -You can specify that a segment should be loaded at a particular address in -memory by using an -.Li AT -expression. This is identical to the -.Li AT -command used as an output section attribute (see Section -.Dq Output Section LMA ) . -The -.Li AT -command for a program header overrides the output section attribute. -.Pp -The linker will normally set the segment flags based on the sections which -comprise the segment. You may use the -.Li FLAGS -keyword to explicitly specify the segment flags. The value of -.Va flags -must be an integer. It is used to set the -.Li p_flags -field of the program header. -.Pp -Here is an example of -.Li PHDRS . -This shows a typical set of program headers used on a native ELF system. -.Pp -.Bd -literal -offset indent - -PHDRS -{ - headers PT_PHDR PHDRS ; - interp PT_INTERP ; - text PT_LOAD FILEHDR PHDRS ; - data PT_LOAD ; - dynamic PT_DYNAMIC ; -} - -SECTIONS -{ - . = SIZEOF_HEADERS; - .interp : { *(.interp) } :text :interp - .text : { *(.text) } :text - .rodata : { *(.rodata) } /* defaults to :text */ - ... - . = . + 0x1000; /* move to a new page in memory */ - .data : { *(.data) } :data - .dynamic : { *(.dynamic) } :data :dynamic - ... -} - -.Ed -.Pp -.Ss VERSION Command -The linker supports symbol versions when using ELF. Symbol versions are only -useful when using shared libraries. The dynamic linker can use symbol versions -to select a specific version of a function when it runs a program that may -have been linked against an earlier version of the shared library. -.Pp -You can include a version script directly in the main linker script, or you -can supply the version script as an implicit linker script. You can also use -the -.Li --version-script -linker option. -.Pp -The syntax of the -.Li VERSION -command is simply -.Bd -literal -offset indent -VERSION { version-script-commands } -.Ed -.Pp -The format of the version script commands is identical to that used by Sun's -linker in Solaris 2.5. The version script defines a tree of version nodes. -You specify the node names and interdependencies in the version script. You -can specify which symbols are bound to which version nodes, and you can reduce -a specified set of symbols to local scope so that they are not globally visible -outside of the shared library. -.Pp -The easiest way to demonstrate the version script language is with a few examples. -.Pp -.Bd -literal -offset indent -VERS_1.1 { - global: - foo1; - local: - old*; - original*; - new*; -}; - -VERS_1.2 { - foo2; -} VERS_1.1; - -VERS_2.0 { - bar1; bar2; - extern "C++" { - ns::*; - "int f(int, double)"; - } -} VERS_1.2; -.Ed -.Pp -This example version script defines three version nodes. The first version -node defined is -.Li VERS_1.1 ; -it has no other dependencies. The script binds the symbol -.Li foo1 -to -.Li VERS_1.1 . -It reduces a number of symbols to local scope so that they are not visible -outside of the shared library; this is done using wildcard patterns, so that -any symbol whose name begins with -.Li old , -.Li original , -or -.Li new -is matched. The wildcard patterns available are the same as those used in -the shell when matching filenames (also known as \(lqglobbing\(rq). However, if you -specify the symbol name inside double quotes, then the name is treated as -literal, rather than as a glob pattern. -.Pp -Next, the version script defines node -.Li VERS_1.2 . -This node depends upon -.Li VERS_1.1 . -The script binds the symbol -.Li foo2 -to the version node -.Li VERS_1.2 . -.Pp -Finally, the version script defines node -.Li VERS_2.0 . -This node depends upon -.Li VERS_1.2 . -The scripts binds the symbols -.Li bar1 -and -.Li bar2 -are bound to the version node -.Li VERS_2.0 . -.Pp -When the linker finds a symbol defined in a library which is not specifically -bound to a version node, it will effectively bind it to an unspecified base -version of the library. You can bind all otherwise unspecified symbols to -a given version node by using -.Li global: *; -somewhere in the version script. -.Pp -The names of the version nodes have no specific meaning other than what they -might suggest to the person reading them. The -.Li 2.0 -version could just as well have appeared in between -.Li 1.1 -and -.Li 1.2 . -However, this would be a confusing way to write a version script. -.Pp -Node name can be omitted, provided it is the only version node in the version -script. Such version script doesn't assign any versions to symbols, only selects -which symbols will be globally visible out and which won't. -.Pp -.Bd -literal -offset indent -{ global: foo; bar; local: *; }; -.Ed -.Pp -When you link an application against a shared library that has versioned symbols, -the application itself knows which version of each symbol it requires, and -it also knows which version nodes it needs from each shared library it is -linked against. Thus at runtime, the dynamic loader can make a quick check -to make sure that the libraries you have linked against do in fact supply -all of the version nodes that the application will need to resolve all of -the dynamic symbols. In this way it is possible for the dynamic linker to -know with certainty that all external symbols that it needs will be resolvable -without having to search for each symbol reference. -.Pp -The symbol versioning is in effect a much more sophisticated way of doing -minor version checking that SunOS does. The fundamental problem that is being -addressed here is that typically references to external functions are bound -on an as-needed basis, and are not all bound when the application starts up. -If a shared library is out of date, a required interface may be missing; when -the application tries to use that interface, it may suddenly and unexpectedly -fail. With symbol versioning, the user will get a warning when they start -their program if the libraries being used with the application are too old. -.Pp -There are several GNU extensions to Sun's versioning approach. The first of -these is the ability to bind a symbol to a version node in the source file -where the symbol is defined instead of in the versioning script. This was -done mainly to reduce the burden on the library maintainer. You can do this -by putting something like: -.Bd -literal -offset indent -__asm__(".symver original_foo,foo@VERS_1.1"); -.Ed -in the C source file. This renames the function -.Li original_foo -to be an alias for -.Li foo -bound to the version node -.Li VERS_1.1 . -The -.Li local: -directive can be used to prevent the symbol -.Li original_foo -from being exported. A -.Li .symver -directive takes precedence over a version script. -.Pp -The second GNU extension is to allow multiple versions of the same function -to appear in a given shared library. In this way you can make an incompatible -change to an interface without increasing the major version number of the -shared library, while still allowing applications linked against the old interface -to continue to function. -.Pp -To do this, you must use multiple -.Li .symver -directives in the source file. Here is an example: -.Pp -.Bd -literal -offset indent -__asm__(".symver original_foo,foo@"); -__asm__(".symver old_foo,foo@VERS_1.1"); -__asm__(".symver old_foo1,foo@VERS_1.2"); -__asm__(".symver new_foo,foo@@VERS_2.0"); -.Ed -.Pp -In this example, -.Li foo@ -represents the symbol -.Li foo -bound to the unspecified base version of the symbol. The source file that -contains this example would define 4 C functions: -.Li original_foo , -.Li old_foo , -.Li old_foo1 , -and -.Li new_foo . -.Pp -When you have multiple definitions of a given symbol, there needs to be some -way to specify a default version to which external references to this symbol -will be bound. You can do this with the -.Li foo@@VERS_2.0 -type of -.Li .symver -directive. You can only declare one version of a symbol as the default in -this manner; otherwise you would effectively have multiple definitions of -the same symbol. -.Pp -If you wish to bind a reference to a specific version of the symbol within -the shared library, you can use the aliases of convenience (i.e., -.Li old_foo ) , -or you can use the -.Li .symver -directive to specifically bind to an external version of the function in question. -.Pp -You can also specify the language in the version script: -.Pp -.Bd -literal -offset indent -VERSION extern "lang" { version-script-commands } -.Ed -.Pp -The supported -.Li lang -s are -.Li C , -.Li C++ , -and -.Li Java . -The linker will iterate over the list of symbols at the link time and demangle -them according to -.Li lang -before matching them to the patterns specified in -.Li version-script-commands . -.Pp -Demangled names may contains spaces and other special characters. As described -above, you can use a glob pattern to match demangled names, or you can use -a double-quoted string to match the string exactly. In the latter case, be -aware that minor differences (such as differing whitespace) between the version -script and the demangler output will cause a mismatch. As the exact string -generated by the demangler might change in the future, even if the mangled -name does not, you should check that all of your version directives are behaving -as you expect when you upgrade. -.Pp -.Ss Expressions in Linker Scripts -The syntax for expressions in the linker script language is identical to that -of C expressions. All expressions are evaluated as integers. All expressions -are evaluated in the same size, which is 32 bits if both the host and target -are 32 bits, and is otherwise 64 bits. -.Pp -You can use and set symbol values in expressions. -.Pp -The linker defines several special purpose builtin functions for use in expressions. -.Pp -.Em Constants -.Pp -All constants are integers. -.Pp -As in C, the linker considers an integer beginning with -.Li 0 -to be octal, and an integer beginning with -.Li 0x -or -.Li 0X -to be hexadecimal. The linker considers other integers to be decimal. -.Pp -In addition, you can use the suffixes -.Li K -and -.Li M -to scale a constant by -.Li 1024 -or -.Li 1024*1024 -respectively. For example, the following all refer to the same quantity: -.Bd -literal -offset indent -_fourk_1 = 4K; -_fourk_2 = 4096; -_fourk_3 = 0x1000; -.Ed -.Pp -.Em Symbol Names -.Pp -Unless quoted, symbol names start with a letter, underscore, or period and -may include letters, digits, underscores, periods, and hyphens. Unquoted symbol -names must not conflict with any keywords. You can specify a symbol which -contains odd characters or has the same name as a keyword by surrounding the -symbol name in double quotes: -.Bd -literal -offset indent -"SECTION" = 9; -"with a space" = "also with a space" + 10; -.Ed -.Pp -Since symbols can contain many non-alphabetic characters, it is safest to -delimit symbols with spaces. For example, -.Li A-B -is one symbol, whereas -.Li A - B -is an expression involving subtraction. -.Pp -.Em Orphan Sections -.Pp -Orphan sections are sections present in the input files which are not explicitly -placed into the output file by the linker script. The linker will still copy -these sections into the output file, but it has to guess as to where they -should be placed. The linker uses a simple heuristic to do this. It attempts -to place orphan sections after non-orphan sections of the same attribute, -such as code vs data, loadable vs non-loadable, etc. If there is not enough -room to do this then it places at the end of the file. -.Pp -For ELF targets, the attribute of the section includes section type as well -as section flag. -.Pp -.Em The Location Counter -.Pp -The special linker variable -.Em dot -.Li . -always contains the current output location counter. Since the -.Li . -always refers to a location in an output section, it may only appear in an -expression within a -.Li SECTIONS -command. The -.Li . -symbol may appear anywhere that an ordinary symbol is allowed in an expression. -.Pp -Assigning a value to -.Li . -will cause the location counter to be moved. This may be used to create holes -in the output section. The location counter may not be moved backwards inside -an output section, and may not be moved backwards outside of an output section -if so doing creates areas with overlapping LMAs. -.Pp -.Bd -literal -offset indent -SECTIONS -{ - output : - { - file1(.text) - . = . + 1000; - file2(.text) - . += 1000; - file3(.text) - } = 0x12345678; -} -.Ed -In the previous example, the -.Li .text -section from -.Pa file1 -is located at the beginning of the output section -.Li output . -It is followed by a 1000 byte gap. Then the -.Li .text -section from -.Pa file2 -appears, also with a 1000 byte gap following before the -.Li .text -section from -.Pa file3 . -The notation -.Li = 0x12345678 -specifies what data to write in the gaps (see Section -.Dq Output Section Fill ) . -.Pp -Note: -.Li . -actually refers to the byte offset from the start of the current containing -object. Normally this is the -.Li SECTIONS -statement, whose start address is 0, hence -.Li . -can be used as an absolute address. If -.Li . -is used inside a section description however, it refers to the byte offset -from the start of that section, not an absolute address. Thus in a script -like this: -.Pp -.Bd -literal -offset indent -SECTIONS -{ - . = 0x100 - .text: { - *(.text) - . = 0x200 - } - . = 0x500 - .data: { - *(.data) - . += 0x600 - } -} -.Ed -.Pp -The -.Li .text -section will be assigned a starting address of 0x100 and a size of exactly -0x200 bytes, even if there is not enough data in the -.Li .text -input sections to fill this area. (If there is too much data, an error will -be produced because this would be an attempt to move -.Li . -backwards). The -.Li .data -section will start at 0x500 and it will have an extra 0x600 bytes worth of -space after the end of the values from the -.Li .data -input sections and before the end of the -.Li .data -output section itself. -.Pp -Setting symbols to the value of the location counter outside of an output -section statement can result in unexpected values if the linker needs to place -orphan sections. For example, given the following: -.Pp -.Bd -literal -offset indent -SECTIONS -{ - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - start_of_data = . ; - .data: { *(.data) } - end_of_data = . ; -} -.Ed -.Pp -If the linker needs to place some input section, e.g. -.Li .rodata , -not mentioned in the script, it might choose to place that section between -.Li .text -and -.Li .data . -You might think the linker should place -.Li .rodata -on the blank line in the above script, but blank lines are of no particular -significance to the linker. As well, the linker doesn't associate the above -symbol names with their sections. Instead, it assumes that all assignments -or other statements belong to the previous output section, except for the -special case of an assignment to -.Li . . -I.e., the linker will place the orphan -.Li .rodata -section as if the script was written as follows: -.Pp -.Bd -literal -offset indent -SECTIONS -{ - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - start_of_data = . ; - .rodata: { *(.rodata) } - .data: { *(.data) } - end_of_data = . ; -} -.Ed -.Pp -This may or may not be the script author's intention for the value of -.Li start_of_data . -One way to influence the orphan section placement is to assign the location -counter to itself, as the linker assumes that an assignment to -.Li . -is setting the start address of a following output section and thus should -be grouped with that section. So you could write: -.Pp -.Bd -literal -offset indent -SECTIONS -{ - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - . = . ; - start_of_data = . ; - .data: { *(.data) } - end_of_data = . ; -} -.Ed -.Pp -Now, the orphan -.Li .rodata -section will be placed between -.Li end_of_text -and -.Li start_of_data . -.Pp -.Em Operators -.Pp -The linker recognizes the standard C set of arithmetic operators, with the -standard bindings and precedence levels: -.Bd -literal -offset indent -precedence associativity Operators Notes -(highest) -1 left ! - ~ (1) -2 left * / % -3 left + - -4 left >> << -5 left == != > < <= >= -6 left & -7 left | -8 left && -9 left || -10 right ? : -11 right &= += -= *= /= (2) -(lowest) -.Ed -Notes: (1) Prefix operators (2)See Section -.Dq Assignments . -.Pp -.Em Evaluation -.Pp -The linker evaluates expressions lazily. It only computes the value of an -expression when absolutely necessary. -.Pp -The linker needs some information, such as the value of the start address -of the first section, and the origins and lengths of memory regions, in order -to do any linking at all. These values are computed as soon as possible when -the linker reads in the linker script. -.Pp -However, other values (such as symbol values) are not known or needed until -after storage allocation. Such values are evaluated later, when other information -(such as the sizes of output sections) is available for use in the symbol -assignment expression. -.Pp -The sizes of sections cannot be known until after allocation, so assignments -dependent upon these are not performed until after allocation. -.Pp -Some expressions, such as those depending upon the location counter -.Li . , -must be evaluated during section allocation. -.Pp -If the result of an expression is required, but the value is not available, -then an error results. For example, a script like the following -.Bd -literal -offset indent - -SECTIONS - { - .text 9+this_isnt_constant : - { *(.text) } - } - -.Ed -will cause the error message -.Li non constant expression for initial address . -.Pp -.Em The Section of an Expression -.Pp -When the linker evaluates an expression, the result is either absolute or -relative to some section. A relative expression is expressed as a fixed offset -from the base of a section. -.Pp -The position of the expression within the linker script determines whether -it is absolute or relative. An expression which appears within an output section -definition is relative to the base of the output section. An expression which -appears elsewhere will be absolute. -.Pp -A symbol set to a relative expression will be relocatable if you request relocatable -output using the -.Li -r -option. That means that a further link operation may change the value of the -symbol. The symbol's section will be the section of the relative expression. -.Pp -A symbol set to an absolute expression will retain the same value through -any further link operation. The symbol will be absolute, and will not have -any particular associated section. -.Pp -You can use the builtin function -.Li ABSOLUTE -to force an expression to be absolute when it would otherwise be relative. -For example, to create an absolute symbol set to the address of the end of -the output section -.Li .data : -.Bd -literal -offset indent -SECTIONS - { - .data : { *(.data) _edata = ABSOLUTE(.); } - } -.Ed -If -.Li ABSOLUTE -were not used, -.Li _edata -would be relative to the -.Li .data -section. -.Pp -.Em Builtin Functions -.Pp -The linker script language includes a number of builtin functions for use -in linker script expressions. -.Pp -.Bl -tag -width Ds -.It ABSOLUTE( Va exp) -Return the absolute (non-relocatable, as opposed to non-negative) value of -the expression -.Va exp . -Primarily useful to assign an absolute value to a symbol within a section -definition, where symbol values are normally section relative.See Section -.Dq Expression Section . -.Pp -.It ADDR( Va section) -Return the absolute address (the VMA) of the named -.Va section . -Your script must previously have defined the location of that section. In -the following example, -.Li symbol_1 -and -.Li symbol_2 -are assigned identical values: -.Bd -literal -offset indent - -SECTIONS { ... - .output1 : - { - start_of_output_1 = ABSOLUTE(.); - ... - } - .output : - { - symbol_1 = ADDR(.output1); - symbol_2 = start_of_output_1; - } -\&... } - -.Ed -.Pp -.It ALIGN( Va align) -.It ALIGN( Va exp, Va align) -Return the location counter ( -.Li . ) -or arbitrary expression aligned to the next -.Va align -boundary. The single operand -.Li ALIGN -doesn't change the value of the location counter---it just does arithmetic -on it. The two operand -.Li ALIGN -allows an arbitrary expression to be aligned upwards ( -.Li ALIGN( Va align) -is equivalent to -.Li ALIGN(., Va align) ) . -.Pp -Here is an example which aligns the output -.Li .data -section to the next -.Li 0x2000 -byte boundary after the preceding section and sets a variable within the section -to the next -.Li 0x8000 -boundary after the input sections: -.Bd -literal -offset indent - -SECTIONS { ... - .data ALIGN(0x2000): { - *(.data) - variable = ALIGN(0x8000); - } -\&... } - -.Ed -The first use of -.Li ALIGN -in this example specifies the location of a section because it is used as -the optional -.Va address -attribute of a section definition (see Section -.Dq Output Section Address ) . -The second use of -.Li ALIGN -is used to defines the value of a symbol. -.Pp -The builtin function -.Li NEXT -is closely related to -.Li ALIGN . -.Pp -.It ALIGNOF( Va section) -Return the alignment in bytes of the named -.Va section , -if that section has been allocated. If the section has not been allocated -when this is evaluated, the linker will report an error. In the following -example, the alignment of the -.Li .output -section is stored as the first value in that section. -.Bd -literal -offset indent - -SECTIONS{ ... - .output { - LONG (ALIGNOF (.output)) - ... - } -\&... } - -.Ed -.Pp -.It BLOCK( Va exp) -This is a synonym for -.Li ALIGN , -for compatibility with older linker scripts. It is most often seen when setting -the address of an output section. -.Pp -.It DATA_SEGMENT_ALIGN( Va maxpagesize, Va commonpagesize) -This is equivalent to either -.Bd -literal -offset indent -(ALIGN(maxpagesize) + (. & (maxpagesize - 1))) -.Ed -or -.Bd -literal -offset indent -(ALIGN(maxpagesize) + (. & (maxpagesize - commonpagesize))) -.Ed -depending on whether the latter uses fewer -.Va commonpagesize -sized pages for the data segment (area between the result of this expression -and -.Li DATA_SEGMENT_END ) -than the former or not. If the latter form is used, it means -.Va commonpagesize -bytes of runtime memory will be saved at the expense of up to -.Va commonpagesize -wasted bytes in the on-disk file. -.Pp -This expression can only be used directly in -.Li SECTIONS -commands, not in any output section descriptions and only once in the linker -script. -.Va commonpagesize -should be less or equal to -.Va maxpagesize -and should be the system page size the object wants to be optimized for (while -still working on system page sizes up to -.Va maxpagesize ) . -.Pp -Example: -.Bd -literal -offset indent - . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); -.Ed -.Pp -.It DATA_SEGMENT_END( Va exp) -This defines the end of data segment for -.Li DATA_SEGMENT_ALIGN -evaluation purposes. -.Pp -.Bd -literal -offset indent - . = DATA_SEGMENT_END(.); -.Ed -.Pp -.It DATA_SEGMENT_RELRO_END( Va offset, Va exp) -This defines the end of the -.Li PT_GNU_RELRO -segment when -.Li -z relro -option is used. Second argument is returned. When -.Li -z relro -option is not present, -.Li DATA_SEGMENT_RELRO_END -does nothing, otherwise -.Li DATA_SEGMENT_ALIGN -is padded so that -.Va exp -+ -.Va offset -is aligned to the most commonly used page boundary for particular target. -If present in the linker script, it must always come in between -.Li DATA_SEGMENT_ALIGN -and -.Li DATA_SEGMENT_END . -.Pp -.Bd -literal -offset indent - . = DATA_SEGMENT_RELRO_END(24, .); -.Ed -.Pp -.It DEFINED( Va symbol) -Return 1 if -.Va symbol -is in the linker global symbol table and is defined before the statement using -DEFINED in the script, otherwise return 0. You can use this function to provide -default values for symbols. For example, the following script fragment shows -how to set a global symbol -.Li begin -to the first location in the -.Li .text -section---but if a symbol called -.Li begin -already existed, its value is preserved: -.Pp -.Bd -literal -offset indent - -SECTIONS { ... - .text : { - begin = DEFINED(begin) ? begin : . ; - ... - } - ... -} - -.Ed -.Pp -.It LENGTH( Va memory) -Return the length of the memory region named -.Va memory . -.Pp -.It LOADADDR( Va section) -Return the absolute LMA of the named -.Va section . -This is normally the same as -.Li ADDR , -but it may be different if the -.Li AT -attribute is used in the output section definition (see Section -.Dq Output Section LMA ) . -.Pp -.It MAX( Va exp1, Va exp2) -Returns the maximum of -.Va exp1 -and -.Va exp2 . -.Pp -.It MIN( Va exp1, Va exp2) -Returns the minimum of -.Va exp1 -and -.Va exp2 . -.Pp -.It NEXT( Va exp) -Return the next unallocated address that is a multiple of -.Va exp . -This function is closely related to -.Li ALIGN( Va exp) ; -unless you use the -.Li MEMORY -command to define discontinuous memory for the output file, the two functions -are equivalent. -.Pp -.It ORIGIN( Va memory) -Return the origin of the memory region named -.Va memory . -.Pp -.It SEGMENT_START( Va segment, Va default) -Return the base address of the named -.Va segment . -If an explicit value has been given for this segment (with a command-line -.Li -T -option) that value will be returned; otherwise the value will be -.Va default . -At present, the -.Li -T -command-line option can only be used to set the base address for the \(lqtext\(rq, -\(lqdata\(rq, and \(lqbss\(rq sections, but you use -.Li SEGMENT_START -with any segment name. -.Pp -.It SIZEOF( Va section) -Return the size in bytes of the named -.Va section , -if that section has been allocated. If the section has not been allocated -when this is evaluated, the linker will report an error. In the following -example, -.Li symbol_1 -and -.Li symbol_2 -are assigned identical values: -.Bd -literal -offset indent - -SECTIONS{ ... - .output { - .start = . ; - ... - .end = . ; - } - symbol_1 = .end - .start ; - symbol_2 = SIZEOF(.output); -\&... } - -.Ed -.Pp -.It SIZEOF_HEADERS -.It sizeof_headers -Return the size in bytes of the output file's headers. This is information -which appears at the start of the output file. You can use this number when -setting the start address of the first section, if you choose, to facilitate -paging. -.Pp -When producing an ELF output file, if the linker script uses the -.Li SIZEOF_HEADERS -builtin function, the linker must compute the number of program headers before -it has determined all the section addresses and sizes. If the linker later -discovers that it needs additional program headers, it will report an error -.Li not enough room for program headers . -To avoid this error, you must avoid using the -.Li SIZEOF_HEADERS -function, or you must rework your linker script to avoid forcing the linker -to use additional program headers, or you must define the program headers -yourself using the -.Li PHDRS -command (see Section -.Dq PHDRS ) . -.El -.Pp -.Ss Implicit Linker Scripts -If you specify a linker input file which the linker can not recognize as an -object file or an archive file, it will try to read the file as a linker script. -If the file can not be parsed as a linker script, the linker will report an -error. -.Pp -An implicit linker script will not replace the default linker script. -.Pp -Typically an implicit linker script would contain only symbol assignments, -or the -.Li INPUT , -.Li GROUP , -or -.Li VERSION -commands. -.Pp -Any input files read because of an implicit linker script will be read at -the position in the command line where the implicit linker script was read. -This can affect archive searching. -.Pp -.Sh Machine Dependent Features -.Xr ld -has additional features on some platforms; the following sections describe -them. Machines where -.Xr ld -has no additional functionality are not listed. -.Pp -.Ss Xr ld and the H8/300 -For the H8/300, -.Xr ld -can perform these global optimizations when you specify the -.Li --relax -command-line option. -.Pp -.Bl -tag -width Ds -.It relaxing address modes -.Xr ld -finds all -.Li jsr -and -.Li jmp -instructions whose targets are within eight bits, and turns them into eight-bit -program-counter relative -.Li bsr -and -.Li bra -instructions, respectively. -.Pp -.It synthesizing instructions -.Xr ld -finds all -.Li mov.b -instructions which use the sixteen-bit absolute address form, but refer to -the top page of memory, and changes them to use the eight-bit address form. -(That is: the linker turns -.Li mov.b Li @ Va aa:16 -into -.Li mov.b Li @ Va aa:8 -whenever the address -.Va aa -is in the top page of memory). -.Pp -.It bit manipulation instructions -.Xr ld -finds all bit manipulation instructions like -.Li band, bclr, biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor -which use 32 bit and 16 bit absolute address form, but refer to the top page -of memory, and changes them to use the 8 bit address form. (That is: the linker -turns -.Li bset #xx:3, Li @ Va aa:32 -into -.Li bset #xx:3, Li @ Va aa:8 -whenever the address -.Va aa -is in the top page of memory). -.Pp -.It system control instructions -.Xr ld -finds all -.Li ldc.w, stc.w -instructions which use the 32 bit absolute address form, but refer to the -top page of memory, and changes them to use 16 bit address form. (That is: -the linker turns -.Li ldc.w Li @ Va aa:32,ccr -into -.Li ldc.w Li @ Va aa:16,ccr -whenever the address -.Va aa -is in the top page of memory). -.El -.Pp -.Ss Xr ld and the Intel 960 Family -You can use the -.Li -A Va architecture -command line option to specify one of the two-letter names identifying members -of the 960 family; the option specifies the desired output target, and warns -of any incompatible instructions in the input files. It also modifies the -linker's search strategy for archive libraries, to support the use of libraries -specific to each particular architecture, by including in the search loop -names suffixed with the string identifying the architecture. -.Pp -For example, if your -.Xr ld -command line included -.Li -ACA -as well as -.Li -ltry -, the linker would look (in its built-in search paths, and in any paths you -specify with -.Li -L ) -for a library with the names -.Pp -.Bd -literal -offset indent - -try -libtry.a -tryca -libtryca.a - -.Ed -.Pp -The first two possibilities would be considered in any event; the last two -are due to the use of -.Li -ACA -\&. -.Pp -You can meaningfully use -.Li -A -more than once on a command line, since the 960 architecture family allows -combination of target architectures; each use will add another pair of name -variants to search for when -.Li -l -specifies a library. -.Pp -.Xr ld -supports the -.Li --relax -option for the i960 family. If you specify -.Li --relax , -.Xr ld -finds all -.Li balx -and -.Li calx -instructions whose targets are within 24 bits, and turns them into 24-bit -program-counter relative -.Li bal -and -.Li cal -instructions, respectively. -.Xr ld -also turns -.Li cal -instructions into -.Li bal -instructions when it determines that the target subroutine is a leaf routine -(that is, the target subroutine does not itself call any subroutines). -.Pp -.Ss Xr ld and the Motorola 68HC11 and 68HC12 families -.Em Linker Relaxation -.Pp -For the Motorola 68HC11, -.Xr ld -can perform these global optimizations when you specify the -.Li --relax -command-line option. -.Pp -.Bl -tag -width Ds -.It relaxing address modes -.Xr ld -finds all -.Li jsr -and -.Li jmp -instructions whose targets are within eight bits, and turns them into eight-bit -program-counter relative -.Li bsr -and -.Li bra -instructions, respectively. -.Pp -.Xr ld -also looks at all 16-bit extended addressing modes and transforms them in -a direct addressing mode when the address is in page 0 (between 0 and 0x0ff). -.Pp -.It relaxing gcc instruction group -When -.Xr gcc -is called with -.Op -mrelax , -it can emit group of instructions that the linker can optimize to use a 68HC11 -direct addressing mode. These instructions consists of -.Li bclr -or -.Li bset -instructions. -.Pp -.El -.Em Trampoline Generation -.Pp -For 68HC11 and 68HC12, -.Xr ld -can generate trampoline code to call a far function using a normal -.Li jsr -instruction. The linker will also change the relocation to some far function -to use the trampoline address instead of the function address. This is typically -the case when a pointer to a function is taken. The pointer will in fact point -to the function trampoline. -.Pp -The -.Li --pic-veneer -switch makes the linker use PIC sequences for ARM/Thumb interworking veneers, -even if the rest of the binary is not PIC. This avoids problems on uClinux -targets where -.Li --emit-relocs -is used to generate relocatable binaries. -.Pp -.Ss Xr ld and the ARM family -For the ARM, -.Xr ld -will generate code stubs to allow functions calls between ARM and Thumb code. -These stubs only work with code that has been compiled and assembled with -the -.Li -mthumb-interwork -command line option. If it is necessary to link with old ARM object files -or libraries, which have not been compiled with the -mthumb-interwork option -then the -.Li --support-old-code -command line switch should be given to the linker. This will make it generate -larger stub functions which will work with non-interworking aware ARM code. -Note, however, the linker does not support generating stubs for function calls -to non-interworking aware Thumb code. -.Pp -The -.Li --thumb-entry -switch is a duplicate of the generic -.Li --entry -switch, in that it sets the program's starting address. But it also sets the -bottom bit of the address, so that it can be branched to using a BX instruction, -and the program will start executing in Thumb mode straight away. -.Pp -The -.Li --be8 -switch instructs -.Xr ld -to generate BE8 format executables. This option is only valid when linking -big-endian objects. The resulting image will contain big-endian data and little-endian -code. -.Pp -The -.Li R_ARM_TARGET1 -relocation is typically used for entries in the -.Li .init_array -section. It is interpreted as either -.Li R_ARM_REL32 -or -.Li R_ARM_ABS32 , -depending on the target. The -.Li --target1-rel -and -.Li --target1-abs -switches override the default. -.Pp -The -.Li --target2=type -switch overrides the default definition of the -.Li R_ARM_TARGET2 -relocation. Valid values for -.Li type , -their meanings, and target defaults are as follows: -.Bl -tag -width Ds -.It rel -.Li R_ARM_REL32 -(arm*-*-elf, arm*-*-eabi) -.It abs -.Li R_ARM_ABS32 -(arm*-*-symbianelf) -.It got-rel -.Li R_ARM_GOT_PREL -(arm*-*-linux, arm*-*-*bsd) -.El -.Pp -The -.Li R_ARM_V4BX -relocation (defined by the ARM AAELF specification) enables objects compiled -for the ARMv4 architecture to be interworking-safe when linked with other -objects compiled for ARMv4t, but also allows pure ARMv4 binaries to be built -from the same ARMv4 objects. -.Pp -In the latter case, the switch -.Op --fix-v4bx -must be passed to the linker, which causes v4t -.Li BX rM -instructions to be rewritten as -.Li MOV PC,rM , -since v4 processors do not have a -.Li BX -instruction. -.Pp -In the former case, the switch should not be used, and -.Li R_ARM_V4BX -relocations are ignored. -.Pp -The -.Li --use-blx -switch enables the linker to use ARM/Thumb BLX instructions (available on -ARMv5t and above) in various situations. Currently it is used to perform calls -via the PLT from Thumb code using BLX rather than using BX and a mode-switching -stub before each PLT entry. This should lead to such calls executing slightly -faster. -.Pp -This option is enabled implicitly for SymbianOS, so there is no need to specify -it if you are using that target. -.Pp -The -.Li --vfp11-denorm-fix -switch enables a link-time workaround for a bug in certain VFP11 coprocessor -hardware, which sometimes allows instructions with denorm operands (which -must be handled by support code) to have those operands overwritten by subsequent -instructions before the support code can read the intended values. -.Pp -The bug may be avoided in scalar mode if you allow at least one intervening -instruction between a VFP11 instruction which uses a register and another -instruction which writes to the same register, or at least two intervening -instructions if vector mode is in use. The bug only affects full-compliance -floating-point mode: you do not need this workaround if you are using "runfast" -mode. Please contact ARM for further details. -.Pp -If you know you are using buggy VFP11 hardware, you can enable this workaround -by specifying the linker option -.Li --vfp-denorm-fix=scalar -if you are using the VFP11 scalar mode only, or -.Li --vfp-denorm-fix=vector -if you are using vector mode (the latter also works for scalar code). The -default is -.Li --vfp-denorm-fix=none . -.Pp -If the workaround is enabled, instructions are scanned for potentially-troublesome -sequences, and a veneer is created for each such sequence which may trigger -the erratum. The veneer consists of the first instruction of the sequence -and a branch back to the subsequent instruction. The original instruction -is then replaced with a branch to the veneer. The extra cycles required to -call and return from the veneer are sufficient to avoid the erratum in both -the scalar and vector cases. -.Pp -The -.Li --no-enum-size-warning -switch prevents the linker from warning when linking object files that specify -incompatible EABI enumeration size attributes. For example, with this switch -enabled, linking of an object file using 32-bit enumeration values with another -using enumeration values fitted into the smallest possible space will not -be diagnosed. -.Pp -.Ss Xr ld and HPPA 32-bit ELF Support -When generating a shared library, -.Xr ld -will by default generate import stubs suitable for use with a single sub-space -application. The -.Li --multi-subspace -switch causes -.Xr ld -to generate export stubs, and different (larger) import stubs suitable for -use with multiple sub-spaces. -.Pp -Long branch stubs and import/export stubs are placed by -.Xr ld -in stub sections located between groups of input sections. -.Li --stub-group-size -specifies the maximum size of a group of input sections handled by one stub -section. Since branch offsets are signed, a stub section may serve two groups -of input sections, one group before the stub section, and one group after -it. However, when using conditional branches that require stubs, it may be -better (for branch prediction) that stub sections only serve one group of -input sections. A negative value for -.Li N -chooses this scheme, ensuring that branches to stubs always use a negative -offset. Two special values of -.Li N -are recognized, -.Li 1 -and -.Li -1 . -These both instruct -.Xr ld -to automatically size input section groups for the branch types detected, -with the same behaviour regarding stub placement as other positive or negative -values of -.Li N -respectively. -.Pp -Note that -.Li --stub-group-size -does not split input sections. A single input section larger than the group -size specified will of course create a larger group (of one section). If input -sections are too large, it may not be possible for a branch to reach its stub. -.Pp -.Ss Li ld and MMIX -For MMIX, there is a choice of generating -.Li ELF -object files or -.Li mmo -object files when linking. The simulator -.Li mmix -understands the -.Li mmo -format. The binutils -.Li objcopy -utility can translate between the two formats. -.Pp -There is one special section, the -.Li .MMIX.reg_contents -section. Contents in this section is assumed to correspond to that of global -registers, and symbols referring to it are translated to special symbols, -equal to registers. In a final link, the start address of the -.Li .MMIX.reg_contents -section corresponds to the first allocated global register multiplied by 8. -Register -.Li $255 -is not included in this section; it is always set to the program entry, which -is at the symbol -.Li Main -for -.Li mmo -files. -.Pp -Symbols with the prefix -.Li __.MMIX.start. , -for example -.Li __.MMIX.start..text -and -.Li __.MMIX.start..data -are special; there must be only one each, even if they are local. The default -linker script uses these to set the default start address of a section. -.Pp -Initial and trailing multiples of zero-valued 32-bit words in a section, are -left out from an mmo file. -.Pp -.Ss Li ld and MSP430 -For the MSP430 it is possible to select the MPU architecture. The flag -.Li -m [mpu type] -will select an appropriate linker script for selected MPU type. (To get a -list of known MPUs just pass -.Li -m help -option to the linker). -.Pp -The linker will recognize some extra sections which are MSP430 specific: -.Pp -.Bl -tag -width Ds -.It Li .vectors -Defines a portion of ROM where interrupt vectors located. -.Pp -.It Li .bootloader -Defines the bootloader portion of the ROM (if applicable). Any code in this -section will be uploaded to the MPU. -.Pp -.It Li .infomem -Defines an information memory section (if applicable). Any code in this section -will be uploaded to the MPU. -.Pp -.It Li .infomemnobits -This is the same as the -.Li .infomem -section except that any code in this section will not be uploaded to the MPU. -.Pp -.It Li .noinit -Denotes a portion of RAM located above -.Li .bss -section. -.Pp -The last two sections are used by gcc. -.El -.Pp -.Ss Xr ld and PowerPC 32-bit ELF Support -Branches on PowerPC processors are limited to a signed 26-bit displacement, -which may result in -.Xr ld -giving -.Li relocation truncated to fit -errors with very large programs. -.Li --relax -enables the generation of trampolines that can access the entire 32-bit address -space. These trampolines are inserted at section boundaries, so may not themselves -be reachable if an input section exceeds 33M in size. -.Pp -.Bl -tag -width Ds -.It --bss-plt -Current PowerPC GCC accepts a -.Li -msecure-plt -option that generates code capable of using a newer PLT and GOT layout that -has the security advantage of no executable section ever needing to be writable -and no writable section ever being executable. PowerPC -.Xr ld -will generate this layout, including stubs to access the PLT, if all input -files (including startup and static libraries) were compiled with -.Li -msecure-plt . -.Li --bss-plt -forces the old BSS PLT (and GOT layout) which can give slightly better performance. -.Pp -.It --secure-plt -.Xr ld -will use the new PLT and GOT layout if it is linking new -.Li -fpic -or -.Li -fPIC -code, but does not do so automatically when linking non-PIC code. This option -requests the new PLT and GOT layout. A warning will be given if some object -file requires the old style BSS PLT. -.Pp -.It --sdata-got -The new secure PLT and GOT are placed differently relative to other sections -compared to older BSS PLT and GOT placement. The location of -.Li .plt -must change because the new secure PLT is an initialized section while the -old PLT is uninitialized. The reason for the -.Li .got -change is more subtle: The new placement allows -.Li .got -to be read-only in applications linked with -.Li -z relro -z now . -However, this placement means that -.Li .sdata -cannot always be used in shared libraries, because the PowerPC ABI accesses -.Li .sdata -in shared libraries from the GOT pointer. -.Li --sdata-got -forces the old GOT placement. PowerPC GCC doesn't use -.Li .sdata -in shared libraries, so this option is really only useful for other compilers -that may do so. -.Pp -.It --emit-stub-syms -This option causes -.Xr ld -to label linker stubs with a local symbol that encodes the stub type and destination. -.Pp -.It --no-tls-optimize -PowerPC -.Xr ld -normally performs some optimization of code sequences used to access Thread-Local -Storage. Use this option to disable the optimization. -.El -.Pp -.Ss Xr ld and PowerPC64 64-bit ELF Support -.Bl -tag -width Ds -.It --stub-group-size -Long branch stubs, PLT call stubs and TOC adjusting stubs are placed by -.Xr ld -in stub sections located between groups of input sections. -.Li --stub-group-size -specifies the maximum size of a group of input sections handled by one stub -section. Since branch offsets are signed, a stub section may serve two groups -of input sections, one group before the stub section, and one group after -it. However, when using conditional branches that require stubs, it may be -better (for branch prediction) that stub sections only serve one group of -input sections. A negative value for -.Li N -chooses this scheme, ensuring that branches to stubs always use a negative -offset. Two special values of -.Li N -are recognized, -.Li 1 -and -.Li -1 . -These both instruct -.Xr ld -to automatically size input section groups for the branch types detected, -with the same behaviour regarding stub placement as other positive or negative -values of -.Li N -respectively. -.Pp -Note that -.Li --stub-group-size -does not split input sections. A single input section larger than the group -size specified will of course create a larger group (of one section). If input -sections are too large, it may not be possible for a branch to reach its stub. -.Pp -.It --emit-stub-syms -This option causes -.Xr ld -to label linker stubs with a local symbol that encodes the stub type and destination. -.Pp -.It --dotsyms, --no-dotsyms -These two options control how -.Xr ld -interprets version patterns in a version script. Older PowerPC64 compilers -emitted both a function descriptor symbol with the same name as the function, -and a code entry symbol with the name prefixed by a dot ( -.Li . ) . -To properly version a function -.Li foo , -the version script thus needs to control both -.Li foo -and -.Li .foo . -The option -.Li --dotsyms , -on by default, automatically adds the required dot-prefixed patterns. Use -.Li --no-dotsyms -to disable this feature. -.Pp -.It --no-tls-optimize -PowerPC64 -.Xr ld -normally performs some optimization of code sequences used to access Thread-Local -Storage. Use this option to disable the optimization. -.Pp -.It --no-opd-optimize -PowerPC64 -.Xr ld -normally removes -.Li .opd -section entries corresponding to deleted link-once functions, or functions -removed by the action of -.Li --gc-sections -or linker scrip -.Li /DISCARD/ . -Use this option to disable -.Li .opd -optimization. -.Pp -.It --non-overlapping-opd -Some PowerPC64 compilers have an option to generate compressed -.Li .opd -entries spaced 16 bytes apart, overlapping the third word, the static chain -pointer (unused in C) with the first word of the next entry. This option expands -such entries to the full 24 bytes. -.Pp -.It --no-toc-optimize -PowerPC64 -.Xr ld -normally removes unused -.Li .toc -section entries. Such entries are detected by examining relocations that reference -the TOC in code sections. A reloc in a deleted code section marks a TOC word -as unneeded, while a reloc in a kept code section marks a TOC word as needed. -Since the TOC may reference itself, TOC relocs are also examined. TOC words -marked as both needed and unneeded will of course be kept. TOC words without -any referencing reloc are assumed to be part of a multi-word entry, and are -kept or discarded as per the nearest marked preceding word. This works reliably -for compiler generated code, but may be incorrect if assembly code is used -to insert TOC entries. Use this option to disable the optimization. -.Pp -.It --no-multi-toc -By default, PowerPC64 GCC generates code for a TOC model where TOC entries -are accessed with a 16-bit offset from r2. This limits the total TOC size -to 64K. PowerPC64 -.Xr ld -extends this limit by grouping code sections such that each group uses less -than 64K for its TOC entries, then inserts r2 adjusting stubs between inter-group -calls. -.Xr ld -does not split apart input sections, so cannot help if a single input file -has a -.Li .toc -section that exceeds 64K, most likely from linking multiple files with -.Xr ld -r . -Use this option to turn off this feature. -.El -.Pp -.Ss Xr ld and SPU ELF Support -.Bl -tag -width Ds -.It --plugin -This option marks an executable as a PIC plugin module. -.Pp -.It --no-overlays -Normally, -.Xr ld -recognizes calls to functions within overlay regions, and redirects such calls -to an overlay manager via a stub. -.Xr ld -also provides a built-in overlay manager. This option turns off all this special -overlay handling. -.Pp -.It --emit-stub-syms -This option causes -.Xr ld -to label overlay stubs with a local symbol that encodes the stub type and -destination. -.Pp -.It --extra-overlay-stubs -This option causes -.Xr ld -to add overlay call stubs on all function calls out of overlay regions. Normally -stubs are not added on calls to non-overlay regions. -.Pp -.It --local-store=lo:hi -.Xr ld -usually checks that a final executable for SPU fits in the address range 0 -to 256k. This option may be used to change the range. Disable the check entirely -with -.Op --local-store=0:0 . -.Pp -.It --stack-analysis -SPU local store space is limited. Over-allocation of stack space unnecessarily -limits space available for code and data, while under-allocation results in -runtime failures. If given this option, -.Xr ld -will provide an estimate of maximum stack usage. -.Xr ld -does this by examining symbols in code sections to determine the extents of -functions, and looking at function prologues for stack adjusting instructions. -A call-graph is created by looking for relocations on branch instructions. -The graph is then searched for the maximum stack usage path. Note that this -analysis does not find calls made via function pointers, and does not handle -recursion and other cycles in the call graph. Stack usage may be under-estimated -if your code makes such calls. Also, stack usage for dynamic allocation, e.g. -alloca, will not be detected. If a link map is requested, detailed information -about each function's stack usage and calls will be given. -.Pp -.It --emit-stack-syms -This option, if given along with -.Op --stack-analysis -will result in -.Xr ld -emitting stack sizing symbols for each function. These take the form -.Li __stack_<function_name> -for global functions, and -.Li __stack_<number>_<function_name> -for static functions. -.Li <number> -is the section id in hex. The value of such symbols is the stack requirement -for the corresponding function. The symbol size will be zero, type -.Li STT_NOTYPE , -binding -.Li STB_LOCAL , -and section -.Li SHN_ABS . -.El -.Pp -.Ss Xr ld's Support for Various TI COFF Versions -The -.Li --format -switch allows selection of one of the various TI COFF versions. The latest -of this writing is 2; versions 0 and 1 are also supported. The TI COFF versions -also vary in header byte-order format; -.Xr ld -will read any version or byte order, but the output header format depends -on the default specified by the specific target. -.Pp -.Ss Xr ld and WIN32 (cygwin/mingw) -This section describes some of the win32 specific -.Xr ld -issues. See Options,,Command Line Options for detailed description of the -command line options mentioned here. -.Pp -.Bl -tag -width Ds -.It import libraries -The standard Windows linker creates and uses so-called import libraries, which -contains information for linking to dll's. They are regular static archives -and are handled as any other static archive. The cygwin and mingw ports of -.Xr ld -have specific support for creating such libraries provided with the -.Li --out-implib -command line option. -.Pp -.It exporting DLL symbols -The cygwin/mingw -.Xr ld -has several ways to export symbols for dll's. -.Pp -.Bl -tag -width Ds -.It using auto-export functionality -By default -.Xr ld -exports symbols with the auto-export functionality, which is controlled by -the following command line options: -.Pp -.Bl -bullet -.It ---export-all-symbols [This is the default] -.It ---exclude-symbols -.It ---exclude-libs -.El -.Pp -If, however, -.Li --export-all-symbols -is not given explicitly on the command line, then the default auto-export -behavior will be -.Em disabled -if either of the following are true: -.Pp -.Bl -bullet -.It -A DEF file is used. -.It -Any symbol in any object file was marked with the __declspec(dllexport) attribute. -.El -.Pp -.It using a DEF file -Another way of exporting symbols is using a DEF file. A DEF file is an ASCII -file containing definitions of symbols which should be exported when a dll -is created. Usually it is named -.Li <dll name>.def -and is added as any other object file to the linker's command line. The file's -name must end in -.Li .def -or -.Li .DEF . -.Pp -.Bd -literal -offset indent -gcc -o <output> <objectfiles> <dll name>.def -.Ed -.Pp -Using a DEF file turns off the normal auto-export behavior, unless the -.Li --export-all-symbols -option is also used. -.Pp -Here is an example of a DEF file for a shared library called -.Li xyz.dll : -.Pp -.Bd -literal -offset indent -LIBRARY "xyz.dll" BASE=0x20000000 - -EXPORTS -foo -bar -_bar = bar -another_foo = abc.dll.afoo -var1 DATA -.Ed -.Pp -This example defines a DLL with a non-default base address and five symbols -in the export table. The third exported symbol -.Li _bar -is an alias for the second. The fourth symbol, -.Li another_foo -is resolved by "forwarding" to another module and treating it as an alias -for -.Li afoo -exported from the DLL -.Li abc.dll . -The final symbol -.Li var1 -is declared to be a data object. -.Pp -The optional -.Li LIBRARY <name> -command indicates the -.Em internal -name of the output DLL. If -.Li <name> -does not include a suffix, the default library suffix, -.Li .DLL -is appended. -.Pp -When the .DEF file is used to build an application, rather than a library, -the -.Li NAME <name> -command should be used instead of -.Li LIBRARY . -If -.Li <name> -does not include a suffix, the default executable suffix, -.Li .EXE -is appended. -.Pp -With either -.Li LIBRARY <name> -or -.Li NAME <name> -the optional specification -.Li BASE = <number> -may be used to specify a non-default base address for the image. -.Pp -If neither -.Li LIBRARY <name> -nor -.Li NAME <name> -is specified, or they specify an empty string, the internal name is the same -as the filename specified on the command line. -.Pp -The complete specification of an export symbol is: -.Pp -.Bd -literal -offset indent -EXPORTS - ( ( ( <name1> [ = <name2> ] ) - | ( <name1> = <module-name> . <external-name>)) - [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) * -.Ed -.Pp -Declares -.Li <name1> -as an exported symbol from the DLL, or declares -.Li <name1> -as an exported alias for -.Li <name2> ; -or declares -.Li <name1> -as a "forward" alias for the symbol -.Li <external-name> -in the DLL -.Li <module-name> . -Optionally, the symbol may be exported by the specified ordinal -.Li <integer> -alias. -.Pp -The optional keywords that follow the declaration indicate: -.Pp -.Li NONAME : -Do not put the symbol name in the DLL's export table. It will still be exported -by its ordinal alias (either the value specified by the .def specification -or, otherwise, the value assigned by the linker). The symbol name, however, -does remain visible in the import library (if any), unless -.Li PRIVATE -is also specified. -.Pp -.Li DATA : -The symbol is a variable or object, rather than a function. The import lib -will export only an indirect reference to -.Li foo -as the symbol -.Li _imp__foo -(ie, -.Li foo -must be resolved as -.Li *_imp__foo ) . -.Pp -.Li CONSTANT : -Like -.Li DATA , -but put the undecorated -.Li foo -as well as -.Li _imp__foo -into the import library. Both refer to the read-only import address table's -pointer to the variable, not to the variable itself. This can be dangerous. -If the user code fails to add the -.Li dllimport -attribute and also fails to explicitly add the extra indirection that the -use of the attribute enforces, the application will behave unexpectedly. -.Pp -.Li PRIVATE : -Put the symbol in the DLL's export table, but do not put it into the static -import library used to resolve imports at link time. The symbol can still -be imported using the -.Li LoadLibrary/GetProcAddress -API at runtime or by by using the GNU ld extension of linking directly to -the DLL without an import library. See ld/deffilep.y in the binutils sources -for the full specification of other DEF file statements -.Pp -While linking a shared dll, -.Xr ld -is able to create a DEF file with the -.Li --output-def <file> -command line option. -.Pp -.It Using decorations -Another way of marking symbols for export is to modify the source code itself, -so that when building the DLL each symbol to be exported is declared as: -.Pp -.Bd -literal -offset indent -__declspec(dllexport) int a_variable -__declspec(dllexport) void a_function(int with_args) -.Ed -.Pp -All such symbols will be exported from the DLL. If, however, any of the object -files in the DLL contain symbols decorated in this way, then the normal auto-export -behavior is disabled, unless the -.Li --export-all-symbols -option is also used. -.Pp -Note that object files that wish to access these symbols must -.Em not -decorate them with dllexport. Instead, they should use dllimport, instead: -.Pp -.Bd -literal -offset indent -__declspec(dllimport) int a_variable -__declspec(dllimport) void a_function(int with_args) -.Ed -.Pp -This complicates the structure of library header files, because when included -by the library itself the header must declare the variables and functions -as dllexport, but when included by client code the header must declare them -as dllimport. There are a number of idioms that are typically used to do this; -often client code can omit the __declspec() declaration completely. See -.Li --enable-auto-import -and -.Li automatic data imports -for more information. -.El -.Pp -.It automatic data imports -The standard Windows dll format supports data imports from dlls only by adding -special decorations (dllimport/dllexport), which let the compiler produce -specific assembler instructions to deal with this issue. This increases the -effort necessary to port existing Un*x code to these platforms, especially -for large c++ libraries and applications. The auto-import feature, which was -initially provided by Paul Sokolovsky, allows one to omit the decorations -to achieve a behavior that conforms to that on POSIX/Un*x platforms. This -feature is enabled with the -.Li --enable-auto-import -command-line option, although it is enabled by default on cygwin/mingw. The -.Li --enable-auto-import -option itself now serves mainly to suppress any warnings that are ordinarily -emitted when linked objects trigger the feature's use. -.Pp -auto-import of variables does not always work flawlessly without additional -assistance. Sometimes, you will see this message -.Pp -"variable '<var>' can't be auto-imported. Please read the documentation for -ld's -.Li --enable-auto-import -for details." -.Pp -The -.Li --enable-auto-import -documentation explains why this error occurs, and several methods that can -be used to overcome this difficulty. One of these methods is the -.Em runtime pseudo-relocs -feature, described below. -.Pp -For complex variables imported from DLLs (such as structs or classes), object -files typically contain a base address for the variable and an offset ( -.Em addend ) -within the variable--to specify a particular field or public member, for instance. -Unfortunately, the runtime loader used in win32 environments is incapable -of fixing these references at runtime without the additional information supplied -by dllimport/dllexport decorations. The standard auto-import feature described -above is unable to resolve these references. -.Pp -The -.Li --enable-runtime-pseudo-relocs -switch allows these references to be resolved without error, while leaving -the task of adjusting the references themselves (with their non-zero addends) -to specialized code provided by the runtime environment. Recent versions of -the cygwin and mingw environments and compilers provide this runtime support; -older versions do not. However, the support is only necessary on the developer's -platform; the compiled result will run without error on an older system. -.Pp -.Li --enable-runtime-pseudo-relocs -is not the default; it must be explicitly enabled as needed. -.Pp -.It direct linking to a dll -The cygwin/mingw ports of -.Xr ld -support the direct linking, including data symbols, to a dll without the usage -of any import libraries. This is much faster and uses much less memory than -does the traditional import library method, especially when linking large -libraries or applications. When -.Xr ld -creates an import lib, each function or variable exported from the dll is -stored in its own bfd, even though a single bfd could contain many exports. -The overhead involved in storing, loading, and processing so many bfd's is -quite large, and explains the tremendous time, memory, and storage needed -to link against particularly large or complex libraries when using import -libs. -.Pp -Linking directly to a dll uses no extra command-line switches other than -.Li -L -and -.Li -l , -because -.Xr ld -already searches for a number of names to match each library. All that is -needed from the developer's perspective is an understanding of this search, -in order to force ld to select the dll instead of an import library. -.Pp -For instance, when ld is called with the argument -.Li -lxxx -it will attempt to find, in the first directory of its search path, -.Pp -.Bd -literal -offset indent -libxxx.dll.a -xxx.dll.a -libxxx.a -xxx.lib -cygxxx.dll (*) -libxxx.dll -xxx.dll -.Ed -.Pp -before moving on to the next directory in the search path. -.Pp -(*) Actually, this is not -.Li cygxxx.dll -but in fact is -.Li <prefix>xxx.dll , -where -.Li <prefix> -is set by the -.Xr ld -option -.Li --dll-search-prefix=<prefix> . -In the case of cygwin, the standard gcc spec file includes -.Li --dll-search-prefix=cyg , -so in effect we actually search for -.Li cygxxx.dll . -.Pp -Other win32-based unix environments, such as mingw or pw32, may use other -.Li <prefix> -es, although at present only cygwin makes use of this feature. It was originally -intended to help avoid name conflicts among dll's built for the various win32/un*x -environments, so that (for example) two versions of a zlib dll could coexist -on the same machine. -.Pp -The generic cygwin/mingw path layout uses a -.Li bin -directory for applications and dll's and a -.Li lib -directory for the import libraries (using cygwin nomenclature): -.Pp -.Bd -literal -offset indent -bin/ - cygxxx.dll -lib/ - libxxx.dll.a (in case of dll's) - libxxx.a (in case of static archive) -.Ed -.Pp -Linking directly to a dll without using the import library can be done two -ways: -.Pp -1. Use the dll directly by adding the -.Li bin -path to the link line -.Bd -literal -offset indent -gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx -.Ed -.Pp -However, as the dll's often have version numbers appended to their names ( -.Li cygncurses-5.dll ) -this will often fail, unless one specifies -.Li -L../bin -lncurses-5 -to include the version. Import libs are generally not versioned, and do not -have this difficulty. -.Pp -2. Create a symbolic link from the dll to a file in the -.Li lib -directory according to the above mentioned search pattern. This should be -used to avoid unwanted changes in the tools needed for making the app/dll. -.Pp -.Bd -literal -offset indent -ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] -.Ed -.Pp -Then you can link without any make environment changes. -.Pp -.Bd -literal -offset indent -gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx -.Ed -.Pp -This technique also avoids the version number problems, because the following -is perfectly legal -.Pp -.Bd -literal -offset indent -bin/ - cygxxx-5.dll -lib/ - libxxx.dll.a -> ../bin/cygxxx-5.dll -.Ed -.Pp -Linking directly to a dll without using an import lib will work even when -auto-import features are exercised, and even when -.Li --enable-runtime-pseudo-relocs -is used. -.Pp -Given the improvements in speed and memory usage, one might justifiably wonder -why import libraries are used at all. There are three reasons: -.Pp -1. Until recently, the link-directly-to-dll functionality did -.Em not -work with auto-imported data. -.Pp -2. Sometimes it is necessary to include pure static objects within the import -library (which otherwise contains only bfd's for indirection symbols that -point to the exports of a dll). Again, the import lib for the cygwin kernel -makes use of this ability, and it is not possible to do this without an import -lib. -.Pp -3. Symbol aliases can only be resolved using an import lib. This is critical -when linking against OS-supplied dll's (eg, the win32 API) in which symbols -are usually exported as undecorated aliases of their stdcall-decorated assembly -names. -.Pp -So, import libs are not going away. But the ability to replace true import -libs with a simple symbolic link to (or a copy of) a dll, in many cases, is -a useful addition to the suite of tools binutils makes available to the win32 -developer. Given the massive improvements in memory requirements during linking, -storage requirements, and linking speed, we expect that many developers will -soon begin to use this feature whenever possible. -.Pp -.It symbol aliasing -.Bl -tag -width Ds -.It adding additional names -Sometimes, it is useful to export symbols with additional names. A symbol -.Li foo -will be exported as -.Li foo , -but it can also be exported as -.Li _foo -by using special directives in the DEF file when creating the dll. This will -affect also the optional created import library. Consider the following DEF -file: -.Pp -.Bd -literal -offset indent -LIBRARY "xyz.dll" BASE=0x61000000 - -EXPORTS -foo -_foo = foo -.Ed -.Pp -The line -.Li _foo = foo -maps the symbol -.Li foo -to -.Li _foo . -.Pp -Another method for creating a symbol alias is to create it in the source code -using the "weak" attribute: -.Pp -.Bd -literal -offset indent -void foo () { /* Do something. */; } -void _foo () __attribute__ ((weak, alias ("foo"))); -.Ed -.Pp -See the gcc manual for more information about attributes and weak symbols. -.Pp -.It renaming symbols -Sometimes it is useful to rename exports. For instance, the cygwin kernel -does this regularly. A symbol -.Li _foo -can be exported as -.Li foo -but not as -.Li _foo -by using special directives in the DEF file. (This will also affect the import -library, if it is created). In the following example: -.Pp -.Bd -literal -offset indent -LIBRARY "xyz.dll" BASE=0x61000000 - -EXPORTS -_foo = foo -.Ed -.Pp -The line -.Li _foo = foo -maps the exported symbol -.Li foo -to -.Li _foo . -.El -.Pp -Note: using a DEF file disables the default auto-export behavior, unless the -.Li --export-all-symbols -command line option is used. If, however, you are trying to rename symbols, -then you should list -.Em all -desired exports in the DEF file, including the symbols that are not being -renamed, and do -.Em not -use the -.Li --export-all-symbols -option. If you list only the renamed symbols in the DEF file, and use -.Li --export-all-symbols -to handle the other symbols, then the both the new names -.Em and -the original names for the renamed symbols will be exported. In effect, you'd -be aliasing those symbols, not renaming them, which is probably not what you -wanted. -.Pp -.It weak externals -The Windows object format, PE, specifies a form of weak symbols called weak -externals. When a weak symbol is linked and the symbol is not defined, the -weak symbol becomes an alias for some other symbol. There are three variants -of weak externals: -.Bl -bullet -.It -Definition is searched for in objects and libraries, historically -called lazy externals. -.It -Definition is searched for only in other objects, not in libraries. -This form is not presently implemented. -.It -No search; the symbol is an alias. This form is not presently -implemented. -.El -As a GNU extension, weak symbols that do not specify an alternate symbol are -supported. If the symbol is undefined when linking, the symbol uses a default -value. -.El -.Pp -.Ss Li ld and Xtensa Processors -The default -.Xr ld -behavior for Xtensa processors is to interpret -.Li SECTIONS -commands so that lists of explicitly named sections in a specification with -a wildcard file will be interleaved when necessary to keep literal pools within -the range of PC-relative load offsets. For example, with the command: -.Pp -.Bd -literal -offset indent -SECTIONS -{ - .text : { - *(.literal .text) - } -} -.Ed -.Pp -.Xr ld -may interleave some of the -.Li .literal -and -.Li .text -sections from different object files to ensure that the literal pools are -within the range of PC-relative load offsets. A valid interleaving might place -the -.Li .literal -sections from an initial group of files followed by the -.Li .text -sections of that group of files. Then, the -.Li .literal -sections from the rest of the files and the -.Li .text -sections from the rest of the files would follow. -.Pp -Relaxation is enabled by default for the Xtensa version of -.Xr ld -and provides two important link-time optimizations. The first optimization -is to combine identical literal values to reduce code size. A redundant literal -will be removed and all the -.Li L32R -instructions that use it will be changed to reference an identical literal, -as long as the location of the replacement literal is within the offset range -of all the -.Li L32R -instructions. The second optimization is to remove unnecessary overhead from -assembler-generated \(lqlongcall\(rq sequences of -.Li L32R -/ -.Li CALLX Va n -when the target functions are within range of direct -.Li CALL Va n -instructions. -.Pp -For each of these cases where an indirect call sequence can be optimized to -a direct call, the linker will change the -.Li CALLX Va n -instruction to a -.Li CALL Va n -instruction, remove the -.Li L32R -instruction, and remove the literal referenced by the -.Li L32R -instruction if it is not used for anything else. Removing the -.Li L32R -instruction always reduces code size but can potentially hurt performance -by changing the alignment of subsequent branch targets. By default, the linker -will always preserve alignments, either by switching some instructions between -24-bit encodings and the equivalent density instructions or by inserting a -no-op in place of the -.Li L32R -instruction that was removed. If code size is more important than performance, -the -.Op --size-opt -option can be used to prevent the linker from widening density instructions -or inserting no-ops, except in a few cases where no-ops are required for correctness. -.Pp -The following Xtensa-specific command-line options can be used to control -the linker: -.Pp -.Bl -tag -width Ds -.It --no-relax -Since the Xtensa version of -.Li ld -enables the -.Op --relax -option by default, the -.Op --no-relax -option is provided to disable relaxation. -.Pp -.It --size-opt -When optimizing indirect calls to direct calls, optimize for code size more -than performance. With this option, the linker will not insert no-ops or widen -density instructions to preserve branch target alignment. There may still -be some cases where no-ops are required to preserve the correctness of the -code. -.El -.Pp -.Sh BFD -The linker accesses object and archive files using the BFD libraries. These -libraries allow the linker to use the same routines to operate on object files -whatever the object file format. A different object file format can be supported -simply by creating a new BFD back end and adding it to the library. To conserve -runtime memory, however, the linker and associated tools are usually configured -to support only a subset of the object file formats available. You can use -.Li objdump -i -(see Section -.Dq objdump ) -to list all the formats available for your configuration. -.Pp -As with most implementations, BFD is a compromise between several conflicting -requirements. The major factor influencing BFD design was efficiency: any -time used converting between formats is time which would not have been spent -had BFD not been involved. This is partly offset by abstraction payback; since -BFD simplifies applications and back ends, more time and care may be spent -optimizing algorithms for a greater speed. -.Pp -One minor artifact of the BFD solution which you should bear in mind is the -potential for information loss. There are two places where useful information -can be lost using the BFD mechanism: during conversion and during output.See Section -.Dq BFD information loss . -.Pp -.Ss How It Works: An Outline of BFD -When an object file is opened, BFD subroutines automatically determine the -format of the input object file. They then build a descriptor in memory with -pointers to routines that will be used to access elements of the object file's -data structures. -.Pp -As different information from the object files is required, BFD reads from -different sections of the file and processes them. For example, a very common -operation for the linker is processing symbol tables. Each BFD back end provides -a routine for converting between the object file's representation of symbols -and an internal canonical format. When the linker asks for the symbol table -of an object file, it calls through a memory pointer to the routine from the -relevant BFD back end which reads and converts the table into a canonical -form. The linker then operates upon the canonical form. When the link is finished -and the linker writes the output file's symbol table, another BFD back end -routine is called to take the newly created symbol table and convert it into -the chosen output format. -.Pp -.Em Information Loss -.Pp -.Em Information can be lost during output. -The output formats supported by BFD do not provide identical facilities, and -information which can be described in one form has nowhere to go in another -format. One example of this is alignment information in -.Li b.out . -There is nowhere in an -.Li a.out -format file to store alignment information on the contained data, so when -a file is linked from -.Li b.out -and an -.Li a.out -image is produced, alignment information will not propagate to the output -file. (The linker will still use the alignment information internally, so -the link is performed correctly). -.Pp -Another example is COFF section names. COFF files may contain an unlimited -number of sections, each one with a textual section name. If the target of -the link is a format which does not have many sections (e.g., -.Li a.out ) -or has sections without names (e.g., the Oasys format), the link cannot be -done simply. You can circumvent this problem by describing the desired input-to-output -section mapping with the linker command language. -.Pp -.Em Information can be lost during canonicalization. -The BFD internal canonical form of the external formats is not exhaustive; -there are structures in input formats for which there is no direct representation -internally. This means that the BFD back ends cannot maintain all possible -data richness through the transformation between external to internal and -back to external formats. -.Pp -This limitation is only a problem when an application reads one format and -writes another. Each BFD back end is responsible for maintaining as much data -as possible, and the internal BFD canonical form has structures which are -opaque to the BFD core, and exported only to the back ends. When a file is -read in one format, the canonical form is generated for BFD and the application. -At the same time, the back end saves away any information which may otherwise -be lost. If the data is then written back in the same format, the back end -routine will be able to use the canonical form provided by the BFD core as -well as the information it prepared earlier. Since there is a great deal of -commonality between back ends, there is no information lost when linking or -copying big endian COFF to little endian COFF, or -.Li a.out -to -.Li b.out . -When a mixture of formats is linked, the information is only lost from the -files whose format differs from the destination. -.Pp -.Em The BFD canonical object-file format -.Pp -The greatest potential for loss of information occurs when there is the least -overlap between the information provided by the source format, that stored -by the canonical format, and that needed by the destination format. A brief -description of the canonical form may help you understand which kinds of data -you can count on preserving across conversions. -.Pp -.Bl -tag -width Ds -.It files -Information stored on a per-file basis includes target machine architecture, -particular implementation format type, a demand pageable bit, and a write -protected bit. Information like Unix magic numbers is not stored here---only -the magic numbers' meaning, so a -.Li ZMAGIC -file would have both the demand pageable bit and the write protected text -bit set. The byte order of the target is stored on a per-file basis, so that -big- and little-endian object files may be used with one another. -.Pp -.It sections -Each section in the input file contains the name of the section, the section's -original address in the object file, size and alignment information, various -flags, and pointers into other BFD data structures. -.Pp -.It symbols -Each symbol contains a pointer to the information for the object file which -originally defined it, its name, its value, and various flag bits. When a -BFD back end reads in a symbol table, it relocates all symbols to make them -relative to the base of the section where they were defined. Doing this ensures -that each symbol points to its containing section. Each symbol also has a -varying amount of hidden private data for the BFD back end. Since the symbol -points to the original file, the private data format for that symbol is accessible. -.Li ld -can operate on a collection of symbols of wildly different formats without -problems. -.Pp -Normal global and simple local symbols are maintained on output, so an output -file (no matter its format) will retain symbols pointing to functions and -to global, static, and common variables. Some symbol information is not worth -retaining; in -.Li a.out , -type information is stored in the symbol table as long symbol names. This -information would be useless to most COFF debuggers; the linker has command -line switches to allow users to throw it away. -.Pp -There is one word of type information within the symbol, so if the format -supports symbol type information within symbols (for example, COFF, IEEE, -Oasys) and the type is simple enough to fit within one word (nearly everything -but aggregates), the information will be preserved. -.Pp -.It relocation level -Each canonical BFD relocation record contains a pointer to the symbol to relocate -to, the offset of the data to relocate, the section the data is in, and a -pointer to a relocation type descriptor. Relocation is performed by passing -messages through the relocation type descriptor and the symbol pointer. Therefore, -relocations can be performed on output data using a relocation method that -is only available in one of the input formats. For instance, Oasys provides -a byte relocation format. A relocation record requesting this relocation type -would point indirectly to a routine to perform this, so the relocation may -be performed on a byte being written to a 68k COFF file, even though 68k COFF -has no such relocation type. -.Pp -.It line numbers -Object formats can contain, for debugging purposes, some form of mapping between -symbols, source line numbers, and addresses in the output file. These addresses -have to be relocated along with the symbol information. Each symbol with an -associated list of line number records points to the first record of the list. -The head of a line number list consists of a pointer to the symbol, which -allows finding out the address of the function whose line number is being -described. The rest of the list is made up of pairs: offsets into the section -and line numbers. Any format which can simply derive this information can -pass it successfully between formats (COFF, IEEE and Oasys). -.El -.Pp -.Sh Reporting Bugs -Your bug reports play an essential role in making -.Xr ld -reliable. -.Pp -Reporting a bug may help you by bringing a solution to your problem, or it -may not. But in any case the principal function of a bug report is to help -the entire community by making the next version of -.Xr ld -work better. Bug reports are your contribution to the maintenance of -.Xr ld . -.Pp -In order for a bug report to serve its purpose, you must include the information -that enables us to fix the bug. -.Pp -.Ss Have You Found a Bug? -If you are not sure whether you have found a bug, here are some guidelines: -.Pp -.Bl -bullet -.It -If the linker gets a fatal signal, for any input whatever, that is a -.Xr ld -bug. Reliable linkers never crash. -.Pp -.It -If -.Xr ld -produces an error message for valid input, that is a bug. -.Pp -.It -If -.Xr ld -does not produce an error message for invalid input, that may be a bug. In -the general case, the linker can not verify that object files are correct. -.Pp -.It -If you are an experienced user of linkers, your suggestions for improvement -of -.Xr ld -are welcome in any case. -.El -.Pp -.Ss How to Report Bugs -A number of companies and individuals offer support for GNU products. If you -obtained -.Xr ld -from a support organization, we recommend you contact that organization first. -.Pp -You can find contact information for many support companies and individuals -in the file -.Pa etc/SERVICE -in the GNU Emacs distribution. -.Pp -The fundamental principle of reporting bugs usefully is this: -.Sy report all the facts . -If you are not sure whether to state a fact or leave it out, state it! -.Pp -Often people omit facts because they think they know what causes the problem -and assume that some details do not matter. Thus, you might assume that the -name of a symbol you use in an example does not matter. Well, probably it -does not, but one cannot be sure. Perhaps the bug is a stray memory reference -which happens to fetch from the location where that name is stored in memory; -perhaps, if the name were different, the contents of that location would fool -the linker into doing the right thing despite the bug. Play it safe and give -a specific, complete example. That is the easiest thing for you to do, and -the most helpful. -.Pp -Keep in mind that the purpose of a bug report is to enable us to fix the bug -if it is new to us. Therefore, always write your bug reports on the assumption -that the bug has not been reported previously. -.Pp -Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq -This cannot help us fix a bug, so it is basically useless. We respond by asking -for enough details to enable us to investigate. You might as well expedite -matters by sending them to begin with. -.Pp -To enable us to fix the bug, you should include all these things: -.Pp -.Bl -bullet -.It -The version of -.Xr ld . -.Xr ld -announces it if you start it with the -.Li --version -argument. -.Pp -Without this, we will not know whether there is any point in looking for the -bug in the current version of -.Xr ld . -.Pp -.It -Any patches you may have applied to the -.Xr ld -source, including any patches made to the -.Li BFD -library. -.Pp -.It -The type of machine you are using, and the operating system name and version -number. -.Pp -.It -What compiler (and its version) was used to compile -.Xr ld ----e.g. \(lq -.Li gcc-2.7 -\(rq\&. -.Pp -.It -The command arguments you gave the linker to link your example and observe -the bug. To guarantee you will not omit something important, list them all. -A copy of the Makefile (or the output from make) is sufficient. -.Pp -If we were to try to guess the arguments, we would probably guess wrong and -then we might not encounter the bug. -.Pp -.It -A complete input file, or set of input files, that will reproduce the bug. -It is generally most helpful to send the actual object files provided that -they are reasonably small. Say no more than 10K. For bigger files you can -either make them available by FTP or HTTP or else state that you are willing -to send the object file(s) to whomever requests them. (Note - your email will -be going to a mailing list, so we do not want to clog it up with large attachments). -But small attachments are best. -.Pp -If the source files were assembled using -.Li gas -or compiled using -.Li gcc , -then it may be OK to send the source files rather than the object files. In -this case, be sure to say exactly what version of -.Li gas -or -.Li gcc -was used to produce the object files. Also say how -.Li gas -or -.Li gcc -were configured. -.Pp -.It -A description of what behavior you observe that you believe is incorrect. -For example, \(lqIt gets a fatal signal.\(rq -.Pp -Of course, if the bug is that -.Xr ld -gets a fatal signal, then we will certainly notice it. But if the bug is incorrect -output, we might not notice unless it is glaringly wrong. You might as well -not give us a chance to make a mistake. -.Pp -Even if the problem you experience is a fatal signal, you should still say -so explicitly. Suppose something strange is going on, such as, your copy of -.Xr ld -is out of sync, or you have encountered a bug in the C library on your system. -(This has happened!) Your copy might crash and ours would not. If you told -us to expect a crash, then when ours fails to crash, we would know that the -bug was not happening for us. If you had not told us to expect a crash, then -we would not be able to draw any conclusion from our observations. -.Pp -.It -If you wish to suggest changes to the -.Xr ld -source, send us context diffs, as generated by -.Li diff -with the -.Li -u , -.Li -c , -or -.Li -p -option. Always send diffs from the old file to the new file. If you even discuss -something in the -.Xr ld -source, refer to it by context, not by line number. -.Pp -The line numbers in our development sources will not match those in your sources. -Your line numbers would convey no useful information to us. -.El -.Pp -Here are some things that are not necessary: -.Pp -.Bl -bullet -.It -A description of the envelope of the bug. -.Pp -Often people who encounter a bug spend a lot of time investigating which changes -to the input file will make the bug go away and which changes will not affect -it. -.Pp -This is often time consuming and not very useful, because the way we will -find the bug is by running a single example under the debugger with breakpoints, -not by pure deduction from a series of examples. We recommend that you save -your time for something else. -.Pp -Of course, if you can find a simpler example to report -.Em instead -of the original one, that is a convenience for us. Errors in the output will -be easier to spot, running under the debugger will take less time, and so -on. -.Pp -However, simplification is not vital; if you do not want to do this, report -the bug anyway and send us the entire test case you used. -.Pp -.It -A patch for the bug. -.Pp -A patch for the bug does help us if it is a good one. But do not omit the -necessary information, such as the test case, on the assumption that a patch -is all we need. We might see problems with your patch and decide to fix the -problem another way, or we might not understand it at all. -.Pp -Sometimes with a program as complicated as -.Xr ld -it is very hard to construct an example that will make the program follow -a certain path through the code. If you do not send us the example, we will -not be able to construct one, so we will not be able to verify that the bug -is fixed. -.Pp -And if we cannot understand what bug you are trying to fix, or why your patch -should be an improvement, we will not install it. A test case will help us -to understand. -.Pp -.It -A guess about what the bug is or what it depends on. -.Pp -Such guesses are usually wrong. Even we cannot guess right about such things -without first using the debugger to find the facts. -.El -.Pp -.Sh MRI Compatible Script Files -To aid users making the transition to GNU -.Xr ld -from the MRI linker, -.Xr ld -can use MRI compatible linker scripts as an alternative to the more general-purpose -linker scripting language described in Scripts. MRI compatible linker scripts -have a much simpler command set than the scripting language otherwise used -with -.Xr ld . -GNU -.Xr ld -supports the most commonly used MRI linker commands; these commands are described -here. -.Pp -In general, MRI scripts aren't of much use with the -.Li a.out -object file format, since it only has three sections and MRI scripts lack -some features to make use of them. -.Pp -You can specify a file containing an MRI-compatible script using the -.Li -c -command-line option. -.Pp -Each command in an MRI-compatible script occupies its own line; each command -line starts with the keyword that identifies the command (though blank lines -are also allowed for punctuation). If a line of an MRI-compatible script begins -with an unrecognized keyword, -.Xr ld -issues a warning message, but continues processing the script. -.Pp -Lines beginning with -.Li * -are comments. -.Pp -You can write these commands using all upper-case letters, or all lower case; -for example, -.Li chip -is the same as -.Li CHIP . -The following list shows only the upper-case form of each command. -.Pp -.Bl -tag -width Ds -.It ABSOLUTE Va secname -.It ABSOLUTE Va secname, Va secname, ... Va secname -Normally, -.Xr ld -includes in the output file all sections from all the input files. However, -in an MRI-compatible script, you can use the -.Li ABSOLUTE -command to restrict the sections that will be present in your output program. -If the -.Li ABSOLUTE -command is used at all in a script, then only the sections named explicitly -in -.Li ABSOLUTE -commands will appear in the linker output. You can still use other input sections -(whatever you select on the command line, or using -.Li LOAD ) -to resolve addresses in the output file. -.Pp -.It ALIAS Va out-secname, Va in-secname -Use this command to place the data from input section -.Va in-secname -in a section called -.Va out-secname -in the linker output file. -.Pp -.Va in-secname -may be an integer. -.Pp -.It ALIGN Va secname = Va expression -Align the section called -.Va secname -to -.Va expression . -The -.Va expression -should be a power of two. -.Pp -.It BASE Va expression -Use the value of -.Va expression -as the lowest address (other than absolute addresses) in the output file. -.Pp -.It CHIP Va expression -.It CHIP Va expression, Va expression -This command does nothing; it is accepted only for compatibility. -.Pp -.It END -This command does nothing whatever; it's only accepted for compatibility. -.Pp -.It FORMAT Va output-format -Similar to the -.Li OUTPUT_FORMAT -command in the more general linker language, but restricted to one of these -output formats: -.Pp -.Bl -enum -.It -S-records, if -.Va output-format -is -.Li S -.Pp -.It -IEEE, if -.Va output-format -is -.Li IEEE -.Pp -.It -COFF (the -.Li coff-m68k -variant in BFD), if -.Va output-format -is -.Li COFF -.El -.Pp -.It LIST Va anything... -Print (to the standard output file) a link map, as produced by the -.Xr ld -command-line option -.Li -M . -.Pp -The keyword -.Li LIST -may be followed by anything on the same line, with no change in its effect. -.Pp -.It LOAD Va filename -.It LOAD Va filename, Va filename, ... Va filename -Include one or more object file -.Va filename -in the link; this has the same effect as specifying -.Va filename -directly on the -.Xr ld -command line. -.Pp -.It NAME Va output-name -.Va output-name -is the name for the program produced by -.Xr ld ; -the MRI-compatible command -.Li NAME -is equivalent to the command-line option -.Li -o -or the general script language command -.Li OUTPUT . -.Pp -.It ORDER Va secname, Va secname, ... Va secname -.It ORDER Va secname Va secname Va secname -Normally, -.Xr ld -orders the sections in its output file in the order in which they first appear -in the input files. In an MRI-compatible script, you can override this ordering -with the -.Li ORDER -command. The sections you list with -.Li ORDER -will appear first in your output file, in the order specified. -.Pp -.It PUBLIC Va name= Va expression -.It PUBLIC Va name, Va expression -.It PUBLIC Va name Va expression -Supply a value ( -.Va expression ) -for external symbol -.Va name -used in the linker input files. -.Pp -.It SECT Va secname, Va expression -.It SECT Va secname= Va expression -.It SECT Va secname Va expression -You can use any of these three forms of the -.Li SECT -command to specify the start address ( -.Va expression ) -for section -.Va secname . -If you have more than one -.Li SECT -statement for the same -.Va secname , -only the -.Em first -sets the start address. -.El -.Pp -.Sh GNU Free Documentation License -.Bd -filled -offset indent -Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, -Fifth Floor, Boston, MA 02110-1301 USA -.Pp -Everyone is permitted to copy and distribute verbatim copies of this license -document, but changing it is not allowed. -.Ed -.Pp -.Bl -enum -.It -PREAMBLE -.Pp -The purpose of this License is to make a manual, textbook, or other written -document \(lqfree\(rq 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. -.Pp -This License is a kind of \(lqcopyleft\(rq, 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. -.Pp -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. -.Pp -.It -APPLICABILITY AND DEFINITIONS -.Pp -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 \(lqDocument\(rq, below, refers to any such manual or work. Any member -of the public is a licensee, and is addressed as \(lqyou.\(rq -.Pp -A \(lqModified Version\(rq 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. -.Pp -A \(lqSecondary Section\(rq 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. -.Pp -The \(lqInvariant Sections\(rq 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. -.Pp -The \(lqCover Texts\(rq 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. -.Pp -A \(lqTransparent\(rq 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 -\(lqTransparent\(rq is called \(lqOpaque.\(rq -.Pp -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. -.Pp -The \(lqTitle Page\(rq 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, \(lqTitle Page\(rq means the text near the most prominent -appearance of the work's title, preceding the beginning of the body of the -text. -.Pp -.It -VERBATIM COPYING -.Pp -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. -.Pp -You may also lend copies, under the same conditions stated above, and you -may publicly display copies. -.Pp -.It -COPYING IN QUANTITY -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -.It -MODIFICATIONS -.Pp -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: -.Pp -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 \(lqHistory\(rq, -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 \(lqHistory\(rq 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 \(lqHistory\(rq 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 \(lqAcknowledgements\(rq or \(lqDedications\(rq, 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 \(lqEndorsements.\(rq Such a section -may not be included in the Modified Version. N. Do not retitle any existing -section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. -.Pp -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. -.Pp -You may add a section entitled \(lqEndorsements\(rq, 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. -.Pp -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. -.Pp -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. -.Pp -.It -COMBINING DOCUMENTS -.Pp -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. -.Pp -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. -.Pp -In the combination, you must combine any sections entitled \(lqHistory\(rq in the -various original documents, forming one section entitled \(lqHistory\(rq; likewise -combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled -\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq -.Pp -.It -COLLECTIONS OF DOCUMENTS -.Pp -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. -.Pp -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. -.Pp -.It -AGGREGATION WITH INDEPENDENT WORKS -.Pp -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 \(lqaggregate\(rq, 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. -.Pp -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. -.Pp -.It -TRANSLATION -.Pp -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. -.Pp -.It -TERMINATION -.Pp -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. -.Pp -.It -FUTURE REVISIONS OF THIS LICENSE -.Pp -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/. -.Pp -Each version of the License is given a distinguishing version number. If the -Document specifies that a particular numbered version of this License \(lqor any -later version\(rq 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. -.Pp -.El -.Ss 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: -.Pp -.Bd -literal -offset indent - -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." - -.Ed -.Pp -If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead -of saying which ones are invariant. If you have no Front-Cover Texts, write -\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being -.Va list -\(rq; likewise for Back-Cover Texts. -.Pp -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. -.Pp -.Sh LD Index diff --git a/contrib/binutils/ld/ld.texinfo b/contrib/binutils/ld/ld.texinfo index a5b29524f5fe..71273f4e92c4 100644 --- a/contrib/binutils/ld/ld.texinfo +++ b/contrib/binutils/ld/ld.texinfo @@ -1725,7 +1725,7 @@ the linker script being used by the linker. @kindex --version-script=@var{version-scriptfile} @cindex version script, symbol versions -@item --version-script=@var{version-scriptfile} +@itemx --version-script=@var{version-scriptfile} Specify the name of a version script to the linker. This is typically used when creating shared libraries to specify additional information about the version hierarchy for the library being created. This option diff --git a/contrib/binutils/ld/ldint.7 b/contrib/binutils/ld/ldint.7 deleted file mode 100644 index 6c17af41d8a0..000000000000 --- a/contrib/binutils/ld/ldint.7 +++ /dev/null @@ -1,1277 +0,0 @@ -.Dd 2015-03-02 -.Dt LDINT 7 -.Os -.Sh NAME -.Nm ldint -.Nd GNU Linker Internals -.Sh -This file documents the internals of the GNU linker -.Li ld . -It is a collection of miscellaneous information with little form at this point. -Mostly, it is a repository into which you can put information about GNU -.Li ld -as you discover it (or as you design changes to -.Li ld ) . -.Pp -This document is distributed under the terms of the GNU Free Documentation -License. A copy of the license is included in the section entitled "GNU Free -Documentation License". -.Pp -.Sh The Pa README File -Check the -.Pa README -file; it often has useful information that does not appear anywhere else in -the directory. -.Pp -.Sh How linker emulations are generated -Each linker target has an -.Em emulation . -The emulation includes the default linker script, and certain emulations also -modify certain types of linker behaviour. -.Pp -Emulations are created during the build process by the shell script -.Pa genscripts.sh . -.Pp -The -.Pa genscripts.sh -script starts by reading a file in the -.Pa emulparams -directory. This is a shell script which sets various shell variables used -by -.Pa genscripts.sh -and the other shell scripts it invokes. -.Pp -The -.Pa genscripts.sh -script will invoke a shell script in the -.Pa scripttempl -directory in order to create default linker scripts written in the linker -command language. The -.Pa scripttempl -script will be invoked 5 (or, in some cases, 6) times, with different assignments -to shell variables, to create different default scripts. The choice of script -is made based on the command line options. -.Pp -After creating the scripts, -.Pa genscripts.sh -will invoke yet another shell script, this time in the -.Pa emultempl -directory. That shell script will create the emulation source file, which -contains C code. This C code permits the linker emulation to override various -linker behaviours. Most targets use the generic emulation code, which is in -.Pa emultempl/generic.em . -.Pp -To summarize, -.Pa genscripts.sh -reads three shell scripts: an emulation parameters script in the -.Pa emulparams -directory, a linker script generation script in the -.Pa scripttempl -directory, and an emulation source file generation script in the -.Pa emultempl -directory. -.Pp -For example, the Sun 4 linker sets up variables in -.Pa emulparams/sun4.sh , -creates linker scripts using -.Pa scripttempl/aout.sc , -and creates the emulation code using -.Pa emultempl/sunos.em . -.Pp -Note that the linker can support several emulations simultaneously, depending -upon how it is configured. An emulation can be selected with the -.Li -m -option. The -.Li -V -option will list all supported emulations. -.Pp -.Ss Pa emulparams scripts -Each target selects a particular file in the -.Pa emulparams -directory by setting the shell variable -.Li targ_emul -in -.Pa configure.tgt . -This shell variable is used by the -.Pa configure -script to control building an emulation source file. -.Pp -Certain conventions are enforced. Suppose the -.Li targ_emul -variable is set to -.Va emul -in -.Pa configure.tgt . -The name of the emulation shell script will be -.Pa emulparams/ Va emul.sh . -The -.Pa Makefile -must have a target named -.Pa e Va emul.c ; -this target must depend upon -.Pa emulparams/ Va emul.sh , -as well as the appropriate scripts in the -.Pa scripttempl -and -.Pa emultempl -directories. The -.Pa Makefile -target must invoke -.Li GENSCRIPTS -with two arguments: -.Va emul , -and the value of the make variable -.Li tdir_ Va emul . -The value of the latter variable will be set by the -.Pa configure -script, and is used to set the default target directory to search. -.Pp -By convention, the -.Pa emulparams/ Va emul.sh -shell script should only set shell variables. It may set shell variables which -are to be interpreted by the -.Pa scripttempl -and the -.Pa emultempl -scripts. Certain shell variables are interpreted directly by the -.Pa genscripts.sh -script. -.Pp -Here is a list of shell variables interpreted by -.Pa genscripts.sh , -as well as some conventional shell variables interpreted by the -.Pa scripttempl -and -.Pa emultempl -scripts. -.Pp -.Bl -tag -width Ds -.It SCRIPT_NAME -This is the name of the -.Pa scripttempl -script to use. If -.Li SCRIPT_NAME -is set to -.Va script , -.Pa genscripts.sh -will use the script -.Pa scripttempl/ Va script.sc . -.Pp -.It TEMPLATE_NAME -This is the name of the -.Pa emultempl -script to use. If -.Li TEMPLATE_NAME -is set to -.Va template , -.Pa genscripts.sh -will use the script -.Pa emultempl/ Va template.em . -If this variable is not set, the default value is -.Li generic . -.Pp -.It GENERATE_SHLIB_SCRIPT -If this is set to a nonempty string, -.Pa genscripts.sh -will invoke the -.Pa scripttempl -script an extra time to create a shared library script. linker scripts. -.Pp -.It OUTPUT_FORMAT -This is normally set to indicate the BFD output format use (e.g., -.Li "a.out-sunos-big" . -The -.Pa scripttempl -script will normally use it in an -.Li OUTPUT_FORMAT -expression in the linker script. -.Pp -.It ARCH -This is normally set to indicate the architecture to use (e.g., -.Li sparc ) . -The -.Pa scripttempl -script will normally use it in an -.Li OUTPUT_ARCH -expression in the linker script. -.Pp -.It ENTRY -Some -.Pa scripttempl -scripts use this to set the entry address, in an -.Li ENTRY -expression in the linker script. -.Pp -.It TEXT_START_ADDR -Some -.Pa scripttempl -scripts use this to set the start address of the -.Li .text -section. -.Pp -.It NONPAGED_TEXT_START_ADDR -If this is defined, the -.Pa genscripts.sh -script sets -.Li TEXT_START_ADDR -to its value before running the -.Pa scripttempl -script for the -.Li -n -and -.Li -N -options (see Section -.Dq linker scripts ) . -.Pp -.It SEGMENT_SIZE -The -.Pa genscripts.sh -script uses this to set the default value of -.Li DATA_ALIGNMENT -when running the -.Pa scripttempl -script. -.Pp -.It TARGET_PAGE_SIZE -If -.Li SEGMENT_SIZE -is not defined, the -.Pa genscripts.sh -script uses this to define it. -.Pp -.It ALIGNMENT -Some -.Pa scripttempl -scripts set this to a number to pass to -.Li ALIGN -to set the required alignment for the -.Li end -symbol. -.El -.Pp -.Ss Pa scripttempl scripts -Each linker target uses a -.Pa scripttempl -script to generate the default linker scripts. The name of the -.Pa scripttempl -script is set by the -.Li SCRIPT_NAME -variable in the -.Pa emulparams -script. If -.Li SCRIPT_NAME -is set to -.Va script , -.Li genscripts.sh -will invoke -.Pa scripttempl/ Va script.sc . -.Pp -The -.Pa genscripts.sh -script will invoke the -.Pa scripttempl -script 5 to 8 times. Each time it will set the shell variable -.Li LD_FLAG -to a different value. When the linker is run, the options used will direct -it to select a particular script. (Script selection is controlled by the -.Li get_script -emulation entry point; this describes the conventional behaviour). -.Pp -The -.Pa scripttempl -script should just write a linker script, written in the linker command language, -to standard output. If the emulation name--the name of the -.Pa emulparams -file without the -.Pa .sc -extension--is -.Va emul , -then the output will be directed to -.Pa ldscripts/ Va emul. Va extension -in the build directory, where -.Va extension -changes each time the -.Pa scripttempl -script is invoked. -.Pp -Here is the list of values assigned to -.Li LD_FLAG . -.Pp -.Bl -tag -width Ds -.It (empty) -The script generated is used by default (when none of the following cases -apply). The output has an extension of -.Pa .x . -.It n -The script generated is used when the linker is invoked with the -.Li -n -option. The output has an extension of -.Pa .xn . -.It N -The script generated is used when the linker is invoked with the -.Li -N -option. The output has an extension of -.Pa .xbn . -.It r -The script generated is used when the linker is invoked with the -.Li -r -option. The output has an extension of -.Pa .xr . -.It u -The script generated is used when the linker is invoked with the -.Li -Ur -option. The output has an extension of -.Pa .xu . -.It shared -The -.Pa scripttempl -script is only invoked with -.Li LD_FLAG -set to this value if -.Li GENERATE_SHLIB_SCRIPT -is defined in the -.Pa emulparams -file. The -.Pa emultempl -script must arrange to use this script at the appropriate time, normally when -the linker is invoked with the -.Li -shared -option. The output has an extension of -.Pa .xs . -.It c -The -.Pa scripttempl -script is only invoked with -.Li LD_FLAG -set to this value if -.Li GENERATE_COMBRELOC_SCRIPT -is defined in the -.Pa emulparams -file or if -.Li SCRIPT_NAME -is -.Li elf . -The -.Pa emultempl -script must arrange to use this script at the appropriate time, normally when -the linker is invoked with the -.Li -z combreloc -option. The output has an extension of -.Pa .xc . -.It cshared -The -.Pa scripttempl -script is only invoked with -.Li LD_FLAG -set to this value if -.Li GENERATE_COMBRELOC_SCRIPT -is defined in the -.Pa emulparams -file or if -.Li SCRIPT_NAME -is -.Li elf -and -.Li GENERATE_SHLIB_SCRIPT -is defined in the -.Pa emulparams -file. The -.Pa emultempl -script must arrange to use this script at the appropriate time, normally when -the linker is invoked with the -.Li -shared -z combreloc -option. The output has an extension of -.Pa .xsc . -.El -.Pp -Besides the shell variables set by the -.Pa emulparams -script, and the -.Li LD_FLAG -variable, the -.Pa genscripts.sh -script will set certain variables for each run of the -.Pa scripttempl -script. -.Pp -.Bl -tag -width Ds -.It RELOCATING -This will be set to a non-empty string when the linker is doing a final relocation -(e.g., all scripts other than -.Li -r -and -.Li -Ur ) . -.Pp -.It CONSTRUCTING -This will be set to a non-empty string when the linker is building global -constructor and destructor tables (e.g., all scripts other than -.Li -r ) . -.Pp -.It DATA_ALIGNMENT -This will be set to an -.Li ALIGN -expression when the output should be page aligned, or to -.Li . -when generating the -.Li -N -script. -.Pp -.It CREATE_SHLIB -This will be set to a non-empty string when generating a -.Li -shared -script. -.Pp -.It COMBRELOC -This will be set to a non-empty string when generating -.Li -z combreloc -scripts to a temporary file name which can be used during script generation. -.El -.Pp -The conventional way to write a -.Pa scripttempl -script is to first set a few shell variables, and then write out a linker -script using -.Li cat -with a here document. The linker script will use variable substitutions, based -on the above variables and those set in the -.Pa emulparams -script, to control its behaviour. -.Pp -When there are parts of the -.Pa scripttempl -script which should only be run when doing a final relocation, they should -be enclosed within a variable substitution based on -.Li RELOCATING . -For example, on many targets special symbols such as -.Li _end -should be defined when doing a final link. Naturally, those symbols should -not be defined when doing a relocatable link using -.Li -r . -The -.Pa scripttempl -script could use a construct like this to define those symbols: -.Bd -literal -offset indent - ${RELOCATING+ _end = .;} -.Ed -This will do the symbol assignment only if the -.Li RELOCATING -variable is defined. -.Pp -The basic job of the linker script is to put the sections in the correct order, -and at the correct memory addresses. For some targets, the linker script may -have to do some other operations. -.Pp -For example, on most MIPS platforms, the linker is responsible for defining -the special symbol -.Li _gp , -used to initialize the -.Li $gp -register. It must be set to the start of the small data section plus -.Li 0x8000 . -Naturally, it should only be defined when doing a final relocation. This will -typically be done like this: -.Bd -literal -offset indent - ${RELOCATING+ _gp = ALIGN(16) + 0x8000;} -.Ed -This line would appear just before the sections which compose the small data -section ( -.Li .sdata , -.Li .sbss ) . -All those sections would be contiguous in memory. -.Pp -Many COFF systems build constructor tables in the linker script. The compiler -will arrange to output the address of each global constructor in a -.Li .ctor -section, and the address of each global destructor in a -.Li .dtor -section (this is done by defining -.Li ASM_OUTPUT_CONSTRUCTOR -and -.Li ASM_OUTPUT_DESTRUCTOR -in the -.Li gcc -configuration files). The -.Li gcc -runtime support routines expect the constructor table to be named -.Li __CTOR_LIST__ . -They expect it to be a list of words, with the first word being the count -of the number of entries. There should be a trailing zero word. (Actually, -the count may be -1 if the trailing word is present, and the trailing word -may be omitted if the count is correct, but, as the -.Li gcc -behaviour has changed slightly over the years, it is safest to provide both). -Here is a typical way that might be handled in a -.Pa scripttempl -file. -.Bd -literal -offset indent - ${CONSTRUCTING+ __CTOR_LIST__ = .;} - ${CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)} - ${CONSTRUCTING+ *(.ctors)} - ${CONSTRUCTING+ LONG(0)} - ${CONSTRUCTING+ __CTOR_END__ = .;} - ${CONSTRUCTING+ __DTOR_LIST__ = .;} - ${CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)} - ${CONSTRUCTING+ *(.dtors)} - ${CONSTRUCTING+ LONG(0)} - ${CONSTRUCTING+ __DTOR_END__ = .;} -.Ed -The use of -.Li CONSTRUCTING -ensures that these linker script commands will only appear when the linker -is supposed to be building the constructor and destructor tables. This example -is written for a target which uses 4 byte pointers. -.Pp -Embedded systems often need to set a stack address. This is normally best -done by using the -.Li PROVIDE -construct with a default stack address. This permits the user to easily override -the stack address using the -.Li --defsym -option. Here is an example: -.Bd -literal -offset indent - ${RELOCATING+ PROVIDE (__stack = 0x80000000);} -.Ed -The value of the symbol -.Li __stack -would then be used in the startup code to initialize the stack pointer. -.Pp -.Ss Pa emultempl scripts -Each linker target uses an -.Pa emultempl -script to generate the emulation code. The name of the -.Pa emultempl -script is set by the -.Li TEMPLATE_NAME -variable in the -.Pa emulparams -script. If the -.Li TEMPLATE_NAME -variable is not set, the default is -.Li generic . -If the value of -.Li TEMPLATE_NAME -is -.Va template , -.Pa genscripts.sh -will use -.Pa emultempl/ Va template.em . -.Pp -Most targets use the generic -.Pa emultempl -script, -.Pa emultempl/generic.em . -A different -.Pa emultempl -script is only needed if the linker must support unusual actions, such as -linking against shared libraries. -.Pp -The -.Pa emultempl -script is normally written as a simple invocation of -.Li cat -with a here document. The document will use a few variable substitutions. -Typically each function names uses a substitution involving -.Li EMULATION_NAME , -for ease of debugging when the linker supports multiple emulations. -.Pp -Every function and variable in the emitted file should be static. The only -globally visible object must be named -.Li ld_ Va EMULATION_NAME_emulation , -where -.Va EMULATION_NAME -is the name of the emulation set in -.Pa configure.tgt -(this is also the name of the -.Pa emulparams -file without the -.Pa .sh -extension). The -.Pa genscripts.sh -script will set the shell variable -.Li EMULATION_NAME -before invoking the -.Pa emultempl -script. -.Pp -The -.Li ld_ Va EMULATION_NAME_emulation -variable must be a -.Li struct ld_emulation_xfer_struct , -as defined in -.Pa ldemul.h . -It defines a set of function pointers which are invoked by the linker, as -well as strings for the emulation name (normally set from the shell variable -.Li EMULATION_NAME -and the default BFD target name (normally set from the shell variable -.Li OUTPUT_FORMAT -which is normally set by the -.Pa emulparams -file). -.Pp -The -.Pa genscripts.sh -script will set the shell variable -.Li COMPILE_IN -when it invokes the -.Pa emultempl -script for the default emulation. In this case, the -.Pa emultempl -script should include the linker scripts directly, and return them from the -.Li get_scripts -entry point. When the emulation is not the default, the -.Li get_scripts -entry point should just return a file name. See -.Pa emultempl/generic.em -for an example of how this is done. -.Pp -At some point, the linker emulation entry points should be documented. -.Pp -.Sh A Walkthrough of a Typical Emulation -This chapter is to help people who are new to the way emulations interact -with the linker, or who are suddenly thrust into the position of having to -work with existing emulations. It will discuss the files you need to be aware -of. It will tell you when the given "hooks" in the emulation will be called. -It will, hopefully, give you enough information about when and how things -happen that you'll be able to get by. As always, the source is the definitive -reference to this. -.Pp -The starting point for the linker is in -.Pa ldmain.c -where -.Li main -is defined. The bulk of the code that's emulation specific will initially -be in -.Li emultempl/ Va emulation.em -but will end up in -.Li e Va emulation.c -when the build is done. Most of the work to select and interface with emulations -is in -.Li ldemul.h -and -.Li ldemul.c . -Specifically, -.Li ldemul.h -defines the -.Li ld_emulation_xfer_struct -structure your emulation exports. -.Pp -Your emulation file exports a symbol -.Li ld_ Va EMULATION_NAME_emulation . -If your emulation is selected (it usually is, since usually there's only one), -.Li ldemul.c -sets the variable -.Va ld_emulation -to point to it. -.Li ldemul.c -also defines a number of API functions that interface to your emulation, like -.Li ldemul_after_parse -which simply calls your -.Li ld_ Va EMULATION_emulation.after_parse -function. For the rest of this section, the functions will be mentioned, but -you should assume the indirect reference to your emulation also. -.Pp -We will also skip or gloss over parts of the link process that don't relate -to emulations, like setting up internationalization. -.Pp -After initialization, -.Li main -selects an emulation by pre-scanning the command line arguments. It calls -.Li ldemul_choose_target -to choose a target. If you set -.Li choose_target -to -.Li ldemul_default_target , -it picks your -.Li target_name -by default. -.Pp -.Li main -calls -.Li ldemul_before_parse , -then -.Li parse_args . -.Li parse_args -calls -.Li ldemul_parse_args -for each arg, which must update the -.Li getopt -globals if it recognizes the argument. If the emulation doesn't recognize -it, then parse_args checks to see if it recognizes it. -.Pp -Now that the emulation has had access to all its command-line options, -.Li main -calls -.Li ldemul_set_symbols . -This can be used for any initialization that may be affected by options. It -is also supposed to set up any variables needed by the emulation script. -.Pp -.Li main -now calls -.Li ldemul_get_script -to get the emulation script to use (based on arguments, no doubt,see Section -.Dq Emulations ) -and runs it. While parsing, -.Li ldgram.y -may call -.Li ldemul_hll -or -.Li ldemul_syslib -to handle the -.Li HLL -or -.Li SYSLIB -commands. It may call -.Li ldemul_unrecognized_file -if you asked the linker to link a file it doesn't recognize. It will call -.Li ldemul_recognized_file -for each file it does recognize, in case the emulation wants to handle some -files specially. All the while, it's loading the files (possibly calling -.Li ldemul_open_dynamic_archive ) -and symbols and stuff. After it's done reading the script, -.Li main -calls -.Li ldemul_after_parse . -Use the after-parse hook to set up anything that depends on stuff the script -might have set up, like the entry point. -.Pp -.Li main -next calls -.Li lang_process -in -.Li ldlang.c . -This appears to be the main core of the linking itself, as far as emulation -hooks are concerned(*). It first opens the output file's BFD, calling -.Li ldemul_set_output_arch , -and calls -.Li ldemul_create_output_section_statements -in case you need to use other means to find or create object files (i.e. shared -libraries found on a path, or fake stub objects). Despite the name, nobody -creates output sections here. -.Pp -(*) In most cases, the BFD library does the bulk of the actual linking, handling -symbol tables, symbol resolution, relocations, and building the final output -file. See the BFD reference for all the details. Your emulation is usually -concerned more with managing things at the file and section level, like "put -this here, add this section", etc. -.Pp -Next, the objects to be linked are opened and BFDs created for them, and -.Li ldemul_after_open -is called. At this point, you have all the objects and symbols loaded, but -none of the data has been placed yet. -.Pp -Next comes the Big Linking Thingy (except for the parts BFD does). All input -sections are mapped to output sections according to the script. If a section -doesn't get mapped by default, -.Li ldemul_place_orphan -will get called to figure out where it goes. Next it figures out the offsets -for each section, calling -.Li ldemul_before_allocation -before and -.Li ldemul_after_allocation -after deciding where each input section ends up in the output sections. -.Pp -The last part of -.Li lang_process -is to figure out all the symbols' values. After assigning final values to -the symbols, -.Li ldemul_finish -is called, and after that, any undefined symbols are turned into fatal errors. -.Pp -OK, back to -.Li main , -which calls -.Li ldwrite -in -.Pa ldwrite.c . -.Li ldwrite -calls BFD's final_link, which does all the relocation fixups and writes the -output bfd to disk, and we're done. -.Pp -In summary, -.Pp -.Bl -bullet -.It -.Li main() -in -.Pa ldmain.c -.It -.Pa emultempl/ Va EMULATION.em -has your code -.It -.Li ldemul_choose_target -(defaults to your -.Li target_name ) -.It -.Li ldemul_before_parse -.It -Parse argv, calls -.Li ldemul_parse_args -for each -.It -.Li ldemul_set_symbols -.It -.Li ldemul_get_script -.It -parse script -.Pp -.Bl -bullet -.It -may call -.Li ldemul_hll -or -.Li ldemul_syslib -.It -may call -.Li ldemul_open_dynamic_archive -.El -.Pp -.It -.Li ldemul_after_parse -.It -.Li lang_process() -in -.Pa ldlang.c -.Pp -.Bl -bullet -.It -create -.Li output_bfd -.It -.Li ldemul_set_output_arch -.It -.Li ldemul_create_output_section_statements -.It -read objects, create input bfds - all symbols exist, but have no values -.It -may call -.Li ldemul_unrecognized_file -.It -will call -.Li ldemul_recognized_file -.It -.Li ldemul_after_open -.It -map input sections to output sections -.It -may call -.Li ldemul_place_orphan -for remaining sections -.It -.Li ldemul_before_allocation -.It -gives input sections offsets into output sections, places output sections -.It -.Li ldemul_after_allocation -- section addresses valid -.It -assigns values to symbols -.It -.Li ldemul_finish -- symbol values valid -.El -.Pp -.It -output bfd is written to disk -.Pp -.El -.Sh Some Architecture Specific Notes -This is the place for notes on the behavior of -.Li ld -on specific platforms. Currently, only Intel x86 is documented (and of that, -only the auto-import behavior for DLLs). -.Pp -.Ss Intel x86 -.Bl -tag -width Ds -.Li ld -can create DLLs that operate with various runtimes available on a common x86 -operating system. These runtimes include native (using the mingw "platform"), -cygwin, and pw. -.Pp -.It auto-import from DLLs -.Bl -enum -.It -With this feature on, DLL clients can import variables from DLL without any -concern from their side (for example, without any source code modifications). -Auto-import can be enabled using the -.Li --enable-auto-import -flag, or disabled via the -.Li --disable-auto-import -flag. Auto-import is disabled by default. -.Pp -.It -This is done completely in bounds of the PE specification (to be fair, there's -a minor violation of the spec at one point, but in practice auto-import works -on all known variants of that common x86 operating system) So, the resulting -DLL can be used with any other PE compiler/linker. -.Pp -.It -Auto-import is fully compatible with standard import method, in which variables -are decorated using attribute modifiers. Libraries of either type may be mixed -together. -.Pp -.It -Overhead (space): 8 bytes per imported symbol, plus 20 for each reference -to it; Overhead (load time): negligible; Overhead (virtual/physical memory): -should be less than effect of DLL relocation. -.El -.Pp -Motivation -.Pp -The obvious and only way to get rid of dllimport insanity is to make client -access variable directly in the DLL, bypassing the extra dereference imposed -by ordinary DLL runtime linking. I.e., whenever client contains something -like -.Pp -.Li mov dll_var,%eax, -.Pp -address of dll_var in the command should be relocated to point into loaded -DLL. The aim is to make OS loader do so, and than make ld help with that. -Import section of PE made following way: there's a vector of structures each -describing imports from particular DLL. Each such structure points to two -other parallel vectors: one holding imported names, and one which will hold -address of corresponding imported name. So, the solution is de-vectorize these -structures, making import locations be sparse and pointing directly into code. -.Pp -Implementation -.Pp -For each reference of data symbol to be imported from DLL (to set of which -belong symbols with name <sym>, if __imp_<sym> is found in implib), the import -fixup entry is generated. That entry is of type IMAGE_IMPORT_DESCRIPTOR and -stored in .idata$3 subsection. Each fixup entry contains pointer to symbol's -address within .text section (marked with __fuN_<sym> symbol, where N is integer), -pointer to DLL name (so, DLL name is referenced by multiple entries), and -pointer to symbol name thunk. Symbol name thunk is singleton vector (__nm_th_<symbol>) -pointing to IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing -imported name. Here comes that "om the edge" problem mentioned above: PE specification -rambles that name vector (OriginalFirstThunk) should run in parallel with -addresses vector (FirstThunk), i.e. that they should have same number of elements -and terminated with zero. We violate this, since FirstThunk points directly -into machine code. But in practice, OS loader implemented the sane way: it -goes thru OriginalFirstThunk and puts addresses to FirstThunk, not something -else. It once again should be noted that dll and symbol name structures are -reused across fixup entries and should be there anyway to support standard -import stuff, so sustained overhead is 20 bytes per reference. Other question -is whether having several IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. -Answer is yes, it is done even by native compiler/linker (libth32's functions -are in fact resident in windows9x kernel32.dll, so if you use it, you have -two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is whether -referencing the same PE structures several times is valid. The answer is why -not, prohibiting that (detecting violation) would require more work on behalf -of loader than not doing it. -.Pp -.El -.Sh GNU Free Documentation License -GNU Free Documentation License Version 1.1, March 2000 -.Pp -Copyright (C) 2000 Free Software Foundation, Inc. 51 Franklin Street, Fifth -Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute -verbatim copies of this license document, but changing it is not allowed. -.Pp -0. PREAMBLE -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -1. APPLICABILITY AND DEFINITIONS -.Pp -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". -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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". -.Pp -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. -.Pp -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. -.Pp -2. VERBATIM COPYING -.Pp -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. -.Pp -You may also lend copies, under the same conditions stated above, and you -may publicly display copies. -.Pp -3. COPYING IN QUANTITY -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -4. MODIFICATIONS -.Pp -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: -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -5. COMBINING DOCUMENTS -.Pp -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. -.Pp -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. -.Pp -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." -.Pp -6. COLLECTIONS OF DOCUMENTS -.Pp -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. -.Pp -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. -.Pp -7. AGGREGATION WITH INDEPENDENT WORKS -.Pp -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. -.Pp -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. -.Pp -8. TRANSLATION -.Pp -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. -.Pp -9. TERMINATION -.Pp -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. -.Pp -10. FUTURE REVISIONS OF THIS LICENSE -.Pp -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/. -.Pp -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. -.Pp -ADDENDUM: How to use this License for your documents -.Pp -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: -.Pp -.Bd -literal -offset indent - 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". -.Ed -.Pp -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. -.Pp -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. -.Pp diff --git a/contrib/binutils/ld/lexsup.c b/contrib/binutils/ld/lexsup.c index 2dfab983481d..6ef5053dedcb 100644 --- a/contrib/binutils/ld/lexsup.c +++ b/contrib/binutils/ld/lexsup.c @@ -84,7 +84,6 @@ enum option_values OPTION_NO_KEEP_MEMORY, OPTION_NO_WARN_MISMATCH, OPTION_NO_WARN_SEARCH_MISMATCH, - OPTION_NO_WARN_FATAL, OPTION_NOINHIBIT_EXEC, OPTION_NON_SHARED, OPTION_NO_WHOLE_ARCHIVE, @@ -376,9 +375,6 @@ static const struct ld_option ld_options[] = { {"fatal-warnings", no_argument, NULL, OPTION_WARN_FATAL}, '\0', NULL, N_("Treat warnings as errors"), TWO_DASHES }, - { {"no-fatal-warnings", no_argument, NULL, OPTION_NO_WARN_FATAL}, - '\0', NULL, N_("Don't treat warnings as errors"), - TWO_DASHES }, { {"fini", required_argument, NULL, OPTION_FINI}, '\0', N_("SYMBOL"), N_("Call SYMBOL at unload-time"), ONE_DASH }, { {"force-exe-suffix", no_argument, NULL, OPTION_FORCE_EXE_SUFFIX}, @@ -572,7 +568,6 @@ parse_args (unsigned argc, char **argv) struct option *really_longopts; int last_optind; enum report_method how_to_report_unresolved_symbols = RM_GENERATE_ERROR; - int no_fatal_warnings = FALSE; shortopts = xmalloc (OPTION_COUNT * 3 + 2); longopts = xmalloc (sizeof (*longopts) * (OPTION_COUNT + 1)); @@ -1322,9 +1317,6 @@ parse_args (unsigned argc, char **argv) case OPTION_WARN_FATAL: config.fatal_warnings = TRUE; break; - case OPTION_NO_WARN_FATAL: - no_fatal_warnings = TRUE; - break; case OPTION_WARN_MULTIPLE_GP: config.warn_multiple_gp = TRUE; break; @@ -1446,8 +1438,6 @@ parse_args (unsigned argc, char **argv) break; } } - if (no_fatal_warnings) - config.fatal_warnings = FALSE; if (ingroup) lang_leave_group (); diff --git a/contrib/binutils/ld/scripttempl/elf.sc b/contrib/binutils/ld/scripttempl/elf.sc index 6060c3e1502d..205d1624abc0 100644 --- a/contrib/binutils/ld/scripttempl/elf.sc +++ b/contrib/binutils/ld/scripttempl/elf.sc @@ -402,8 +402,8 @@ cat <<EOF .fini_array ${RELOCATING-0} : { ${RELOCATING+${CREATE_SHLIB-PROVIDE_HIDDEN (${USER_LABEL_PREFIX}__fini_array_start = .);}} - KEEP (*(SORT(.fini_array.*))) KEEP (*(.fini_array)) + KEEP (*(SORT(.fini_array.*))) ${RELOCATING+${CREATE_SHLIB-PROVIDE_HIDDEN (${USER_LABEL_PREFIX}__fini_array_end = .);}} } ${SMALL_DATA_CTOR-${RELOCATING+${CTOR}}} diff --git a/contrib/binutils/opcodes/ppc-opc.c b/contrib/binutils/opcodes/ppc-opc.c index cfd9d308b46f..5995f81de9ff 100644 --- a/contrib/binutils/opcodes/ppc-opc.c +++ b/contrib/binutils/opcodes/ppc-opc.c @@ -4268,11 +4268,6 @@ const struct powerpc_opcode powerpc_opcodes[] = { { "stvx", X(31, 231), X_MASK, PPCVEC, { VS, RA, RB } }, { "stvxl", X(31, 487), X_MASK, PPCVEC, { VS, RA, RB } }, -/* New VSX opcodes in POWER ISA 2.06 */ -/* XXX: only enough opcodes for FreeBSD kernel, remove and replace with real info */ -{ "stxvw4x", X(31, 908), X_MASK, PPCVEC, { FRS, RA0, RB } }, -{ "lxvw4x", X(31, 780), X_MASK, PPCVEC, { FRT, RA0, RB } }, - /* New load/store left/right index vector instructions that are in the Cell only. */ { "lvlx", X(31, 519), X_MASK, CELL, { VD, RA0, RB } }, { "lvlxl", X(31, 775), X_MASK, CELL, { VD, RA0, RB } }, |