+++ /dev/null
-This is bfd.info, produced by makeinfo version 4.8 from bfd.texinfo.
-
-START-INFO-DIR-ENTRY
-* Bfd: (bfd). The Binary File Descriptor library.
-END-INFO-DIR-ENTRY
-
- This file documents the BFD library.
-
- Copyright (C) 1991, 2000, 2001, 2003, 2006, 2007 Free Software
-Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being "GNU General Public License" and "Funding Free
-Software", the Front-Cover texts being (a) (see below), and with the
-Back-Cover Texts being (b) (see below). A copy of the license is
-included in the section entitled "GNU Free Documentation License".
-
- (a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
- (b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.
-
-\1f
-File: bfd.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
-
- This file documents the binary file descriptor library libbfd.
-
-* Menu:
-
-* Overview:: Overview of BFD
-* BFD front end:: BFD front end
-* BFD back ends:: BFD back ends
-* GNU Free Documentation License:: GNU Free Documentation License
-* BFD Index:: BFD Index
-
-\1f
-File: bfd.info, Node: Overview, Next: BFD front end, Prev: Top, Up: Top
-
-1 Introduction
-**************
-
-BFD is a package which allows applications to use the same routines to
-operate on object files whatever the object file format. A new object
-file format can be supported simply by creating a new BFD back end and
-adding it to the library.
-
- BFD is split into two parts: the front end, and the back ends (one
-for each object file format).
- * The front end of BFD provides the interface to the user. It manages
- memory and various canonical data structures. The front end also
- decides which back end to use and when to call back end routines.
-
- * The back ends provide BFD its view of the real world. Each back
- end provides a set of calls which the BFD front end can use to
- maintain its canonical form. The back ends also may keep around
- information for their own use, for greater efficiency.
-
-* Menu:
-
-* History:: History
-* How It Works:: How It Works
-* What BFD Version 2 Can Do:: What BFD Version 2 Can Do
-
-\1f
-File: bfd.info, Node: History, Next: How It Works, Prev: Overview, Up: Overview
-
-1.1 History
-===========
-
-One spur behind BFD was the desire, on the part of the GNU 960 team at
-Intel Oregon, for interoperability of applications on their COFF and
-b.out file formats. Cygnus was providing GNU support for the team, and
-was contracted to provide the required functionality.
-
- The name came from a conversation David Wallace was having with
-Richard Stallman about the library: RMS said that it would be quite
-hard--David said "BFD". Stallman was right, but the name stuck.
-
- At the same time, Ready Systems wanted much the same thing, but for
-different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
-coff.
-
- BFD was first implemented by members of Cygnus Support; Steve
-Chamberlain (`sac@cygnus.com'), John Gilmore (`gnu@cygnus.com'), K.
-Richard Pixley (`rich@cygnus.com') and David Henkel-Wallace
-(`gumby@cygnus.com').
-
-\1f
-File: bfd.info, Node: How It Works, Next: What BFD Version 2 Can Do, Prev: History, Up: Overview
-
-1.2 How To Use BFD
-==================
-
-To use the library, include `bfd.h' and link with `libbfd.a'.
-
- BFD provides a common interface to the parts of an object file for a
-calling application.
-
- When an application successfully opens a target file (object,
-archive, or whatever), a pointer to an internal structure is returned.
-This pointer points to a structure called `bfd', described in `bfd.h'.
-Our convention is to call this pointer a BFD, and instances of it
-within code `abfd'. All operations on the target object file are
-applied as methods to the BFD. The mapping is defined within `bfd.h'
-in a set of macros, all beginning with `bfd_' to reduce namespace
-pollution.
-
- For example, this sequence does what you would probably expect:
-return the number of sections in an object file attached to a BFD
-`abfd'.
-
- #include "bfd.h"
-
- unsigned int number_of_sections (abfd)
- bfd *abfd;
- {
- return bfd_count_sections (abfd);
- }
-
- The abstraction used within BFD is that an object file has:
-
- * a header,
-
- * a number of sections containing raw data (*note Sections::),
-
- * a set of relocations (*note Relocations::), and
-
- * some symbol information (*note Symbols::).
- Also, BFDs opened for archives have the additional attribute of an
-index and contain subordinate BFDs. This approach is fine for a.out and
-coff, but loses efficiency when applied to formats such as S-records and
-IEEE-695.
-
-\1f
-File: bfd.info, Node: What BFD Version 2 Can Do, Prev: How It Works, Up: Overview
-
-1.3 What BFD Version 2 Can Do
-=============================
-
-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.
-
- 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.
-
-* Menu:
-
-* BFD information loss:: Information Loss
-* Canonical format:: The BFD canonical object-file format
-
-\1f
-File: bfd.info, Node: BFD information loss, Next: Canonical format, Up: What BFD Version 2 Can Do
-
-1.3.1 Information Loss
-----------------------
-
-_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 `b.out'. There is nowhere
-in an `a.out' format file to store alignment information on the
-contained data, so when a file is linked from `b.out' and an `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).
-
- 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., `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.
-
- _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.
-
- 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 `a.out' to
-`b.out'. When a mixture of formats is linked, the information is only
-lost from the files whose format differs from the destination.
-
-\1f
-File: bfd.info, Node: Canonical format, Prev: BFD information loss, Up: What BFD Version 2 Can Do
-
-1.3.2 The BFD canonical object-file format
-------------------------------------------
-
-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.
-
-_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 `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.
-
-_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.
-
-_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. `ld' can operate on a collection
- of symbols of wildly different formats without problems.
-
- 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 `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.
-
- 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.
-
-_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.
-
-_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).
-
-\1f
-File: bfd.info, Node: BFD front end, Next: BFD back ends, Prev: Overview, Up: Top
-
-2 BFD Front End
-***************
-
-2.1 `typedef bfd'
-=================
-
-A BFD has type `bfd'; objects of this type are the cornerstone of any
-application using BFD. Using BFD consists of making references though
-the BFD and to data in the BFD.
-
- Here is the structure that defines the type `bfd'. It contains the
-major data about the file and pointers to the rest of the data.
-
-
- struct bfd
- {
- /* A unique identifier of the BFD */
- unsigned int id;
-
- /* The filename the application opened the BFD with. */
- const char *filename;
-
- /* A pointer to the target jump table. */
- const struct bfd_target *xvec;
-
- /* The IOSTREAM, and corresponding IO vector that provide access
- to the file backing the BFD. */
- void *iostream;
- const struct bfd_iovec *iovec;
-
- /* Is the file descriptor being cached? That is, can it be closed as
- needed, and re-opened when accessed later? */
- bfd_boolean cacheable;
-
- /* Marks whether there was a default target specified when the
- BFD was opened. This is used to select which matching algorithm
- to use to choose the back end. */
- bfd_boolean target_defaulted;
-
- /* The caching routines use these to maintain a
- least-recently-used list of BFDs. */
- struct bfd *lru_prev, *lru_next;
-
- /* When a file is closed by the caching routines, BFD retains
- state information on the file here... */
- ufile_ptr where;
-
- /* ... and here: (``once'' means at least once). */
- bfd_boolean opened_once;
-
- /* Set if we have a locally maintained mtime value, rather than
- getting it from the file each time. */
- bfd_boolean mtime_set;
-
- /* File modified time, if mtime_set is TRUE. */
- long mtime;
-
- /* Reserved for an unimplemented file locking extension. */
- int ifd;
-
- /* The format which belongs to the BFD. (object, core, etc.) */
- bfd_format format;
-
- /* The direction with which the BFD was opened. */
- enum bfd_direction
- {
- no_direction = 0,
- read_direction = 1,
- write_direction = 2,
- both_direction = 3
- }
- direction;
-
- /* Format_specific flags. */
- flagword flags;
-
- /* Currently my_archive is tested before adding origin to
- anything. I believe that this can become always an add of
- origin, with origin set to 0 for non archive files. */
- ufile_ptr origin;
-
- /* Remember when output has begun, to stop strange things
- from happening. */
- bfd_boolean output_has_begun;
-
- /* A hash table for section names. */
- struct bfd_hash_table section_htab;
-
- /* Pointer to linked list of sections. */
- struct bfd_section *sections;
-
- /* The last section on the section list. */
- struct bfd_section *section_last;
-
- /* The number of sections. */
- unsigned int section_count;
-
- /* Stuff only useful for object files:
- The start address. */
- bfd_vma start_address;
-
- /* Used for input and output. */
- unsigned int symcount;
-
- /* Symbol table for output BFD (with symcount entries). */
- struct bfd_symbol **outsymbols;
-
- /* Used for slurped dynamic symbol tables. */
- unsigned int dynsymcount;
-
- /* Pointer to structure which contains architecture information. */
- const struct bfd_arch_info *arch_info;
-
- /* Flag set if symbols from this BFD should not be exported. */
- bfd_boolean no_export;
-
- /* Stuff only useful for archives. */
- void *arelt_data;
- struct bfd *my_archive; /* The containing archive BFD. */
- struct bfd *archive_next; /* The next BFD in the archive. */
- struct bfd *archive_head; /* The first BFD in the archive. */
- bfd_boolean has_armap;
-
- /* A chain of BFD structures involved in a link. */
- struct bfd *link_next;
-
- /* A field used by _bfd_generic_link_add_archive_symbols. This will
- be used only for archive elements. */
- int archive_pass;
-
- /* Used by the back end to hold private data. */
- union
- {
- struct aout_data_struct *aout_data;
- struct artdata *aout_ar_data;
- struct _oasys_data *oasys_obj_data;
- struct _oasys_ar_data *oasys_ar_data;
- struct coff_tdata *coff_obj_data;
- struct pe_tdata *pe_obj_data;
- struct xcoff_tdata *xcoff_obj_data;
- struct ecoff_tdata *ecoff_obj_data;
- struct ieee_data_struct *ieee_data;
- struct ieee_ar_data_struct *ieee_ar_data;
- struct srec_data_struct *srec_data;
- struct ihex_data_struct *ihex_data;
- struct tekhex_data_struct *tekhex_data;
- struct elf_obj_tdata *elf_obj_data;
- struct nlm_obj_tdata *nlm_obj_data;
- struct bout_data_struct *bout_data;
- struct mmo_data_struct *mmo_data;
- struct sun_core_struct *sun_core_data;
- struct sco5_core_struct *sco5_core_data;
- struct trad_core_struct *trad_core_data;
- struct som_data_struct *som_data;
- struct hpux_core_struct *hpux_core_data;
- struct hppabsd_core_struct *hppabsd_core_data;
- struct sgi_core_struct *sgi_core_data;
- struct lynx_core_struct *lynx_core_data;
- struct osf_core_struct *osf_core_data;
- struct cisco_core_struct *cisco_core_data;
- struct versados_data_struct *versados_data;
- struct netbsd_core_struct *netbsd_core_data;
- struct mach_o_data_struct *mach_o_data;
- struct mach_o_fat_data_struct *mach_o_fat_data;
- struct bfd_pef_data_struct *pef_data;
- struct bfd_pef_xlib_data_struct *pef_xlib_data;
- struct bfd_sym_data_struct *sym_data;
- void *any;
- }
- tdata;
-
- /* Used by the application to hold private data. */
- void *usrdata;
-
- /* Where all the allocated stuff under this BFD goes. This is a
- struct objalloc *, but we use void * to avoid requiring the inclusion
- of objalloc.h. */
- void *memory;
- };
-
-2.2 Error reporting
-===================
-
-Most BFD functions return nonzero on success (check their individual
-documentation for precise semantics). On an error, they call
-`bfd_set_error' to set an error condition that callers can check by
-calling `bfd_get_error'. If that returns `bfd_error_system_call', then
-check `errno'.
-
- The easiest way to report a BFD error to the user is to use
-`bfd_perror'.
-
-2.2.1 Type `bfd_error_type'
----------------------------
-
-The values returned by `bfd_get_error' are defined by the enumerated
-type `bfd_error_type'.
-
-
- typedef enum bfd_error
- {
- bfd_error_no_error = 0,
- bfd_error_system_call,
- bfd_error_invalid_target,
- bfd_error_wrong_format,
- bfd_error_wrong_object_format,
- bfd_error_invalid_operation,
- bfd_error_no_memory,
- bfd_error_no_symbols,
- bfd_error_no_armap,
- bfd_error_no_more_archived_files,
- bfd_error_malformed_archive,
- bfd_error_file_not_recognized,
- bfd_error_file_ambiguously_recognized,
- bfd_error_no_contents,
- bfd_error_nonrepresentable_section,
- bfd_error_no_debug_section,
- bfd_error_bad_value,
- bfd_error_file_truncated,
- bfd_error_file_too_big,
- bfd_error_on_input,
- bfd_error_invalid_error_code
- }
- bfd_error_type;
-
-2.2.1.1 `bfd_get_error'
-.......................
-
-*Synopsis*
- bfd_error_type bfd_get_error (void);
- *Description*
-Return the current BFD error condition.
-
-2.2.1.2 `bfd_set_error'
-.......................
-
-*Synopsis*
- void bfd_set_error (bfd_error_type error_tag, ...);
- *Description*
-Set the BFD error condition to be ERROR_TAG. If ERROR_TAG is
-bfd_error_on_input, then this function takes two more parameters, the
-input bfd where the error occurred, and the bfd_error_type error.
-
-2.2.1.3 `bfd_errmsg'
-....................
-
-*Synopsis*
- const char *bfd_errmsg (bfd_error_type error_tag);
- *Description*
-Return a string describing the error ERROR_TAG, or the system error if
-ERROR_TAG is `bfd_error_system_call'.
-
-2.2.1.4 `bfd_perror'
-....................
-
-*Synopsis*
- void bfd_perror (const char *message);
- *Description*
-Print to the standard error stream a string describing the last BFD
-error that occurred, or the last system error if the last BFD error was
-a system call failure. If MESSAGE is non-NULL and non-empty, the error
-string printed is preceded by MESSAGE, a colon, and a space. It is
-followed by a newline.
-
-2.2.2 BFD error handler
------------------------
-
-Some BFD functions want to print messages describing the problem. They
-call a BFD error handler function. This function may be overridden by
-the program.
-
- The BFD error handler acts like printf.
-
-
- typedef void (*bfd_error_handler_type) (const char *, ...);
-
-2.2.2.1 `bfd_set_error_handler'
-...............................
-
-*Synopsis*
- bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
- *Description*
-Set the BFD error handler function. Returns the previous function.
-
-2.2.2.2 `bfd_set_error_program_name'
-....................................
-
-*Synopsis*
- void bfd_set_error_program_name (const char *);
- *Description*
-Set the program name to use when printing a BFD error. This is printed
-before the error message followed by a colon and space. The string
-must not be changed after it is passed to this function.
-
-2.2.2.3 `bfd_get_error_handler'
-...............................
-
-*Synopsis*
- bfd_error_handler_type bfd_get_error_handler (void);
- *Description*
-Return the BFD error handler function.
-
-2.3 Miscellaneous
-=================
-
-2.3.1 Miscellaneous functions
------------------------------
-
-2.3.1.1 `bfd_get_reloc_upper_bound'
-...................................
-
-*Synopsis*
- long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
- *Description*
-Return the number of bytes required to store the relocation information
-associated with section SECT attached to bfd ABFD. If an error occurs,
-return -1.
-
-2.3.1.2 `bfd_canonicalize_reloc'
-................................
-
-*Synopsis*
- long bfd_canonicalize_reloc
- (bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
- *Description*
-Call the back end associated with the open BFD ABFD and translate the
-external form of the relocation information attached to SEC into the
-internal canonical form. Place the table into memory at LOC, which has
-been preallocated, usually by a call to `bfd_get_reloc_upper_bound'.
-Returns the number of relocs, or -1 on error.
-
- The SYMS table is also needed for horrible internal magic reasons.
-
-2.3.1.3 `bfd_set_reloc'
-.......................
-
-*Synopsis*
- void bfd_set_reloc
- (bfd *abfd, asection *sec, arelent **rel, unsigned int count);
- *Description*
-Set the relocation pointer and count within section SEC to the values
-REL and COUNT. The argument ABFD is ignored.
-
-2.3.1.4 `bfd_set_file_flags'
-............................
-
-*Synopsis*
- bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
- *Description*
-Set the flag word in the BFD ABFD to the value FLAGS.
-
- Possible errors are:
- * `bfd_error_wrong_format' - The target bfd was not of object format.
-
- * `bfd_error_invalid_operation' - The target bfd was open for
- reading.
-
- * `bfd_error_invalid_operation' - The flag word contained a bit
- which was not applicable to the type of file. E.g., an attempt
- was made to set the `D_PAGED' bit on a BFD format which does not
- support demand paging.
-
-2.3.1.5 `bfd_get_arch_size'
-...........................
-
-*Synopsis*
- int bfd_get_arch_size (bfd *abfd);
- *Description*
-Returns the architecture address size, in bits, as determined by the
-object file's format. For ELF, this information is included in the
-header.
-
- *Returns*
-Returns the arch size in bits if known, `-1' otherwise.
-
-2.3.1.6 `bfd_get_sign_extend_vma'
-.................................
-
-*Synopsis*
- int bfd_get_sign_extend_vma (bfd *abfd);
- *Description*
-Indicates if the target architecture "naturally" sign extends an
-address. Some architectures implicitly sign extend address values when
-they are converted to types larger than the size of an address. For
-instance, bfd_get_start_address() will return an address sign extended
-to fill a bfd_vma when this is the case.
-
- *Returns*
-Returns `1' if the target architecture is known to sign extend
-addresses, `0' if the target architecture is known to not sign extend
-addresses, and `-1' otherwise.
-
-2.3.1.7 `bfd_set_start_address'
-...............................
-
-*Synopsis*
- bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
- *Description*
-Make VMA the entry point of output BFD ABFD.
-
- *Returns*
-Returns `TRUE' on success, `FALSE' otherwise.
-
-2.3.1.8 `bfd_get_gp_size'
-.........................
-
-*Synopsis*
- unsigned int bfd_get_gp_size (bfd *abfd);
- *Description*
-Return the maximum size of objects to be optimized using the GP
-register under MIPS ECOFF. This is typically set by the `-G' argument
-to the compiler, assembler or linker.
-
-2.3.1.9 `bfd_set_gp_size'
-.........................
-
-*Synopsis*
- void bfd_set_gp_size (bfd *abfd, unsigned int i);
- *Description*
-Set the maximum size of objects to be optimized using the GP register
-under ECOFF or MIPS ELF. This is typically set by the `-G' argument to
-the compiler, assembler or linker.
-
-2.3.1.10 `bfd_scan_vma'
-.......................
-
-*Synopsis*
- bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
- *Description*
-Convert, like `strtoul', a numerical expression STRING into a `bfd_vma'
-integer, and return that integer. (Though without as many bells and
-whistles as `strtoul'.) The expression is assumed to be unsigned
-(i.e., positive). If given a BASE, it is used as the base for
-conversion. A base of 0 causes the function to interpret the string in
-hex if a leading "0x" or "0X" is found, otherwise in octal if a leading
-zero is found, otherwise in decimal.
-
- If the value would overflow, the maximum `bfd_vma' value is returned.
-
-2.3.1.11 `bfd_copy_private_header_data'
-.......................................
-
-*Synopsis*
- bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd);
- *Description*
-Copy private BFD header information from the BFD IBFD to the the BFD
-OBFD. This copies information that may require sections to exist, but
-does not require symbol tables. Return `true' on success, `false' on
-error. Possible error returns are:
-
- * `bfd_error_no_memory' - Not enough memory exists to create private
- data for OBFD.
-
- #define bfd_copy_private_header_data(ibfd, obfd) \
- BFD_SEND (obfd, _bfd_copy_private_header_data, \
- (ibfd, obfd))
-
-2.3.1.12 `bfd_copy_private_bfd_data'
-....................................
-
-*Synopsis*
- bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
- *Description*
-Copy private BFD information from the BFD IBFD to the the BFD OBFD.
-Return `TRUE' on success, `FALSE' on error. Possible error returns are:
-
- * `bfd_error_no_memory' - Not enough memory exists to create private
- data for OBFD.
-
- #define bfd_copy_private_bfd_data(ibfd, obfd) \
- BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
- (ibfd, obfd))
-
-2.3.1.13 `bfd_merge_private_bfd_data'
-.....................................
-
-*Synopsis*
- bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
- *Description*
-Merge private BFD information from the BFD IBFD to the the output file
-BFD OBFD when linking. Return `TRUE' on success, `FALSE' on error.
-Possible error returns are:
-
- * `bfd_error_no_memory' - Not enough memory exists to create private
- data for OBFD.
-
- #define bfd_merge_private_bfd_data(ibfd, obfd) \
- BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
- (ibfd, obfd))
-
-2.3.1.14 `bfd_set_private_flags'
-................................
-
-*Synopsis*
- bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
- *Description*
-Set private BFD flag information in the BFD ABFD. Return `TRUE' on
-success, `FALSE' on error. Possible error returns are:
-
- * `bfd_error_no_memory' - Not enough memory exists to create private
- data for OBFD.
-
- #define bfd_set_private_flags(abfd, flags) \
- BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
-
-2.3.1.15 `Other functions'
-..........................
-
-*Description*
-The following functions exist but have not yet been documented.
- #define bfd_sizeof_headers(abfd, info) \
- BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info))
-
- #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
- BFD_SEND (abfd, _bfd_find_nearest_line, \
- (abfd, sec, syms, off, file, func, line))
-
- #define bfd_find_line(abfd, syms, sym, file, line) \
- BFD_SEND (abfd, _bfd_find_line, \
- (abfd, syms, sym, file, line))
-
- #define bfd_find_inliner_info(abfd, file, func, line) \
- BFD_SEND (abfd, _bfd_find_inliner_info, \
- (abfd, file, func, line))
-
- #define bfd_debug_info_start(abfd) \
- BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
-
- #define bfd_debug_info_end(abfd) \
- BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
-
- #define bfd_debug_info_accumulate(abfd, section) \
- BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
-
- #define bfd_stat_arch_elt(abfd, stat) \
- BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
-
- #define bfd_update_armap_timestamp(abfd) \
- BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
-
- #define bfd_set_arch_mach(abfd, arch, mach)\
- BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
-
- #define bfd_relax_section(abfd, section, link_info, again) \
- BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
-
- #define bfd_gc_sections(abfd, link_info) \
- BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
-
- #define bfd_merge_sections(abfd, link_info) \
- BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
-
- #define bfd_is_group_section(abfd, sec) \
- BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec))
-
- #define bfd_discard_group(abfd, sec) \
- BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
-
- #define bfd_link_hash_table_create(abfd) \
- BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
-
- #define bfd_link_hash_table_free(abfd, hash) \
- BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
-
- #define bfd_link_add_symbols(abfd, info) \
- BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
-
- #define bfd_link_just_syms(abfd, sec, info) \
- BFD_SEND (abfd, _bfd_link_just_syms, (sec, info))
-
- #define bfd_final_link(abfd, info) \
- BFD_SEND (abfd, _bfd_final_link, (abfd, info))
-
- #define bfd_free_cached_info(abfd) \
- BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
-
- #define bfd_get_dynamic_symtab_upper_bound(abfd) \
- BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
-
- #define bfd_print_private_bfd_data(abfd, file)\
- BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
-
- #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
- BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
-
- #define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \
- BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \
- dyncount, dynsyms, ret))
-
- #define bfd_get_dynamic_reloc_upper_bound(abfd) \
- BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
-
- #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
- BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
-
- extern bfd_byte *bfd_get_relocated_section_contents
- (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
- bfd_boolean, asymbol **);
-
-2.3.1.16 `bfd_alt_mach_code'
-............................
-
-*Synopsis*
- bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
- *Description*
-When more than one machine code number is available for the same
-machine type, this function can be used to switch between the preferred
-one (alternative == 0) and any others. Currently, only ELF supports
-this feature, with up to two alternate machine codes.
-
- struct bfd_preserve
- {
- void *marker;
- void *tdata;
- flagword flags;
- const struct bfd_arch_info *arch_info;
- struct bfd_section *sections;
- struct bfd_section *section_last;
- unsigned int section_count;
- struct bfd_hash_table section_htab;
- };
-
-2.3.1.17 `bfd_preserve_save'
-............................
-
-*Synopsis*
- bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
- *Description*
-When testing an object for compatibility with a particular target
-back-end, the back-end object_p function needs to set up certain fields
-in the bfd on successfully recognizing the object. This typically
-happens in a piecemeal fashion, with failures possible at many points.
-On failure, the bfd is supposed to be restored to its initial state,
-which is virtually impossible. However, restoring a subset of the bfd
-state works in practice. This function stores the subset and
-reinitializes the bfd.
-
-2.3.1.18 `bfd_preserve_restore'
-...............................
-
-*Synopsis*
- void bfd_preserve_restore (bfd *, struct bfd_preserve *);
- *Description*
-This function restores bfd state saved by bfd_preserve_save. If MARKER
-is non-NULL in struct bfd_preserve then that block and all subsequently
-bfd_alloc'd memory is freed.
-
-2.3.1.19 `bfd_preserve_finish'
-..............................
-
-*Synopsis*
- void bfd_preserve_finish (bfd *, struct bfd_preserve *);
- *Description*
-This function should be called when the bfd state saved by
-bfd_preserve_save is no longer needed. ie. when the back-end object_p
-function returns with success.
-
-2.3.1.20 `bfd_emul_get_maxpagesize'
-...................................
-
-*Synopsis*
- bfd_vma bfd_emul_get_maxpagesize (const char *);
- *Description*
-Returns the maximum page size, in bytes, as determined by emulation.
-
- *Returns*
-Returns the maximum page size in bytes for ELF, abort otherwise.
-
-2.3.1.21 `bfd_emul_set_maxpagesize'
-...................................
-
-*Synopsis*
- void bfd_emul_set_maxpagesize (const char *, bfd_vma);
- *Description*
-For ELF, set the maximum page size for the emulation. It is a no-op
-for other formats.
-
-2.3.1.22 `bfd_emul_get_commonpagesize'
-......................................
-
-*Synopsis*
- bfd_vma bfd_emul_get_commonpagesize (const char *);
- *Description*
-Returns the common page size, in bytes, as determined by emulation.
-
- *Returns*
-Returns the common page size in bytes for ELF, abort otherwise.
-
-2.3.1.23 `bfd_emul_set_commonpagesize'
-......................................
-
-*Synopsis*
- void bfd_emul_set_commonpagesize (const char *, bfd_vma);
- *Description*
-For ELF, set the common page size for the emulation. It is a no-op for
-other formats.
-
-2.3.1.24 `bfd_demangle'
-.......................
-
-*Synopsis*
- char *bfd_demangle (bfd *, const char *, int);
- *Description*
-Wrapper around cplus_demangle. Strips leading underscores and other
-such chars that would otherwise confuse the demangler. If passed a g++
-v3 ABI mangled name, returns a buffer allocated with malloc holding the
-demangled name. Returns NULL otherwise and on memory alloc failure.
-
-2.3.1.25 `struct bfd_iovec'
-...........................
-
-*Description*
-The `struct bfd_iovec' contains the internal file I/O class. Each
-`BFD' has an instance of this class and all file I/O is routed through
-it (it is assumed that the instance implements all methods listed
-below).
- struct bfd_iovec
- {
- /* To avoid problems with macros, a "b" rather than "f"
- prefix is prepended to each method name. */
- /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching
- bytes starting at PTR. Return the number of bytes actually
- transfered (a read past end-of-file returns less than NBYTES),
- or -1 (setting `bfd_error') if an error occurs. */
- file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes);
- file_ptr (*bwrite) (struct bfd *abfd, const void *ptr,
- file_ptr nbytes);
- /* Return the current IOSTREAM file offset, or -1 (setting `bfd_error'
- if an error occurs. */
- file_ptr (*btell) (struct bfd *abfd);
- /* For the following, on successful completion a value of 0 is returned.
- Otherwise, a value of -1 is returned (and `bfd_error' is set). */
- int (*bseek) (struct bfd *abfd, file_ptr offset, int whence);
- int (*bclose) (struct bfd *abfd);
- int (*bflush) (struct bfd *abfd);
- int (*bstat) (struct bfd *abfd, struct stat *sb);
- };
-
-2.3.1.26 `bfd_get_mtime'
-........................
-
-*Synopsis*
- long bfd_get_mtime (bfd *abfd);
- *Description*
-Return the file modification time (as read from the file system, or
-from the archive header for archive members).
-
-2.3.1.27 `bfd_get_size'
-.......................
-
-*Synopsis*
- file_ptr bfd_get_size (bfd *abfd);
- *Description*
-Return the file size (as read from file system) for the file associated
-with BFD ABFD.
-
- The initial motivation for, and use of, this routine is not so we
-can get the exact size of the object the BFD applies to, since that
-might not be generally possible (archive members for example). It
-would be ideal if someone could eventually modify it so that such
-results were guaranteed.
-
- Instead, we want to ask questions like "is this NNN byte sized
-object I'm about to try read from file offset YYY reasonable?" As as
-example of where we might do this, some object formats use string
-tables for which the first `sizeof (long)' bytes of the table contain
-the size of the table itself, including the size bytes. If an
-application tries to read what it thinks is one of these string tables,
-without some way to validate the size, and for some reason the size is
-wrong (byte swapping error, wrong location for the string table, etc.),
-the only clue is likely to be a read error when it tries to read the
-table, or a "virtual memory exhausted" error when it tries to allocate
-15 bazillon bytes of space for the 15 bazillon byte table it is about
-to read. This function at least allows us to answer the question, "is
-the size reasonable?".
-
-* Menu:
-
-* Memory Usage::
-* Initialization::
-* Sections::
-* Symbols::
-* Archives::
-* Formats::
-* Relocations::
-* Core Files::
-* Targets::
-* Architectures::
-* Opening and Closing::
-* Internal::
-* File Caching::
-* Linker Functions::
-* Hash Tables::
-
-\1f
-File: bfd.info, Node: Memory Usage, Next: Initialization, Prev: BFD front end, Up: BFD front end
-
-2.4 Memory Usage
-================
-
-BFD keeps all of its internal structures in obstacks. There is one
-obstack per open BFD file, into which the current state is stored. When
-a BFD is closed, the obstack is deleted, and so everything which has
-been allocated by BFD for the closing file is thrown away.
-
- BFD does not free anything created by an application, but pointers
-into `bfd' structures become invalid on a `bfd_close'; for example,
-after a `bfd_close' the vector passed to `bfd_canonicalize_symtab' is
-still around, since it has been allocated by the application, but the
-data that it pointed to are lost.
-
- The general rule is to not close a BFD until all operations dependent
-upon data from the BFD have been completed, or all the data from within
-the file has been copied. To help with the management of memory, there
-is a function (`bfd_alloc_size') which returns the number of bytes in
-obstacks associated with the supplied BFD. This could be used to select
-the greediest open BFD, close it to reclaim the memory, perform some
-operation and reopen the BFD again, to get a fresh copy of the data
-structures.
-
-\1f
-File: bfd.info, Node: Initialization, Next: Sections, Prev: Memory Usage, Up: BFD front end
-
-2.5 Initialization
-==================
-
-2.5.1 Initialization functions
-------------------------------
-
-These are the functions that handle initializing a BFD.
-
-2.5.1.1 `bfd_init'
-..................
-
-*Synopsis*
- void bfd_init (void);
- *Description*
-This routine must be called before any other BFD function to initialize
-magical internal data structures.
-
-\1f
-File: bfd.info, Node: Sections, Next: Symbols, Prev: Initialization, Up: BFD front end
-
-2.6 Sections
-============
-
-The raw data contained within a BFD is maintained through the section
-abstraction. A single BFD may have any number of sections. It keeps
-hold of them by pointing to the first; each one points to the next in
-the list.
-
- Sections are supported in BFD in `section.c'.
-
-* Menu:
-
-* Section Input::
-* Section Output::
-* typedef asection::
-* section prototypes::
-
-\1f
-File: bfd.info, Node: Section Input, Next: Section Output, Prev: Sections, Up: Sections
-
-2.6.1 Section input
--------------------
-
-When a BFD is opened for reading, the section structures are created
-and attached to the BFD.
-
- Each section has a name which describes the section in the outside
-world--for example, `a.out' would contain at least three sections,
-called `.text', `.data' and `.bss'.
-
- Names need not be unique; for example a COFF file may have several
-sections named `.data'.
-
- Sometimes a BFD will contain more than the "natural" number of
-sections. A back end may attach other sections containing constructor
-data, or an application may add a section (using `bfd_make_section') to
-the sections attached to an already open BFD. For example, the linker
-creates an extra section `COMMON' for each input file's BFD to hold
-information about common storage.
-
- The raw data is not necessarily read in when the section descriptor
-is created. Some targets may leave the data in place until a
-`bfd_get_section_contents' call is made. Other back ends may read in
-all the data at once. For example, an S-record file has to be read
-once to determine the size of the data. An IEEE-695 file doesn't
-contain raw data in sections, but data and relocation expressions
-intermixed, so the data area has to be parsed to get out the data and
-relocations.
-
-\1f
-File: bfd.info, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections
-
-2.6.2 Section output
---------------------
-
-To write a new object style BFD, the various sections to be written
-have to be created. They are attached to the BFD in the same way as
-input sections; data is written to the sections using
-`bfd_set_section_contents'.
-
- Any program that creates or combines sections (e.g., the assembler
-and linker) must use the `asection' fields `output_section' and
-`output_offset' to indicate the file sections to which each section
-must be written. (If the section is being created from scratch,
-`output_section' should probably point to the section itself and
-`output_offset' should probably be zero.)
-
- The data to be written comes from input sections attached (via
-`output_section' pointers) to the output sections. The output section
-structure can be considered a filter for the input section: the output
-section determines the vma of the output data and the name, but the
-input section determines the offset into the output section of the data
-to be written.
-
- E.g., to create a section "O", starting at 0x100, 0x123 long,
-containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and
-"B" at offset 0x20 (i.e., at vma 0x120) the `asection' structures would
-look like:
-
- section name "A"
- output_offset 0x00
- size 0x20
- output_section -----------> section name "O"
- | vma 0x100
- section name "B" | size 0x123
- output_offset 0x20 |
- size 0x103 |
- output_section --------|
-
-2.6.3 Link orders
------------------
-
-The data within a section is stored in a "link_order". These are much
-like the fixups in `gas'. The link_order abstraction allows a section
-to grow and shrink within itself.
-
- A link_order knows how big it is, and which is the next link_order
-and where the raw data for it is; it also points to a list of
-relocations which apply to it.
-
- The link_order is used by the linker to perform relaxing on final
-code. The compiler creates code which is as big as necessary to make
-it work without relaxing, and the user can select whether to relax.
-Sometimes relaxing takes a lot of time. The linker runs around the
-relocations to see if any are attached to data which can be shrunk, if
-so it does it on a link_order by link_order basis.
-
-\1f
-File: bfd.info, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections
-
-2.6.4 typedef asection
-----------------------
-
-Here is the section structure:
-
-
- typedef struct bfd_section
- {
- /* The name of the section; the name isn't a copy, the pointer is
- the same as that passed to bfd_make_section. */
- const char *name;
-
- /* A unique sequence number. */
- int id;
-
- /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */
- int index;
-
- /* The next section in the list belonging to the BFD, or NULL. */
- struct bfd_section *next;
-
- /* The previous section in the list belonging to the BFD, or NULL. */
- struct bfd_section *prev;
-
- /* The field flags contains attributes of the section. Some
- flags are read in from the object file, and some are
- synthesized from other information. */
- flagword flags;
-
- #define SEC_NO_FLAGS 0x000
-
- /* Tells the OS to allocate space for this section when loading.
- This is clear for a section containing debug information only. */
- #define SEC_ALLOC 0x001
-
- /* Tells the OS to load the section from the file when loading.
- This is clear for a .bss section. */
- #define SEC_LOAD 0x002
-
- /* The section contains data still to be relocated, so there is
- some relocation information too. */
- #define SEC_RELOC 0x004
-
- /* A signal to the OS that the section contains read only data. */
- #define SEC_READONLY 0x008
-
- /* The section contains code only. */
- #define SEC_CODE 0x010
-
- /* The section contains data only. */
- #define SEC_DATA 0x020
-
- /* The section will reside in ROM. */
- #define SEC_ROM 0x040
-
- /* The section contains constructor information. This section
- type is used by the linker to create lists of constructors and
- destructors used by `g++'. When a back end sees a symbol
- which should be used in a constructor list, it creates a new
- section for the type of name (e.g., `__CTOR_LIST__'), attaches
- the symbol to it, and builds a relocation. To build the lists
- of constructors, all the linker has to do is catenate all the
- sections called `__CTOR_LIST__' and relocate the data
- contained within - exactly the operations it would peform on
- standard data. */
- #define SEC_CONSTRUCTOR 0x080
-
- /* The section has contents - a data section could be
- `SEC_ALLOC' | `SEC_HAS_CONTENTS'; a debug section could be
- `SEC_HAS_CONTENTS' */
- #define SEC_HAS_CONTENTS 0x100
-
- /* An instruction to the linker to not output the section
- even if it has information which would normally be written. */
- #define SEC_NEVER_LOAD 0x200
-
- /* The section contains thread local data. */
- #define SEC_THREAD_LOCAL 0x400
-
- /* The section has GOT references. This flag is only for the
- linker, and is currently only used by the elf32-hppa back end.
- It will be set if global offset table references were detected
- in this section, which indicate to the linker that the section
- contains PIC code, and must be handled specially when doing a
- static link. */
- #define SEC_HAS_GOT_REF 0x800
-
- /* The section contains common symbols (symbols may be defined
- multiple times, the value of a symbol is the amount of
- space it requires, and the largest symbol value is the one
- used). Most targets have exactly one of these (which we
- translate to bfd_com_section_ptr), but ECOFF has two. */
- #define SEC_IS_COMMON 0x1000
-
- /* The section contains only debugging information. For
- example, this is set for ELF .debug and .stab sections.
- strip tests this flag to see if a section can be
- discarded. */
- #define SEC_DEBUGGING 0x2000
-
- /* The contents of this section are held in memory pointed to
- by the contents field. This is checked by bfd_get_section_contents,
- and the data is retrieved from memory if appropriate. */
- #define SEC_IN_MEMORY 0x4000
-
- /* The contents of this section are to be excluded by the
- linker for executable and shared objects unless those
- objects are to be further relocated. */
- #define SEC_EXCLUDE 0x8000
-
- /* The contents of this section are to be sorted based on the sum of
- the symbol and addend values specified by the associated relocation
- entries. Entries without associated relocation entries will be
- appended to the end of the section in an unspecified order. */
- #define SEC_SORT_ENTRIES 0x10000
-
- /* When linking, duplicate sections of the same name should be
- discarded, rather than being combined into a single section as
- is usually done. This is similar to how common symbols are
- handled. See SEC_LINK_DUPLICATES below. */
- #define SEC_LINK_ONCE 0x20000
-
- /* If SEC_LINK_ONCE is set, this bitfield describes how the linker
- should handle duplicate sections. */
- #define SEC_LINK_DUPLICATES 0x40000
-
- /* This value for SEC_LINK_DUPLICATES means that duplicate
- sections with the same name should simply be discarded. */
- #define SEC_LINK_DUPLICATES_DISCARD 0x0
-
- /* This value for SEC_LINK_DUPLICATES means that the linker
- should warn if there are any duplicate sections, although
- it should still only link one copy. */
- #define SEC_LINK_DUPLICATES_ONE_ONLY 0x80000
-
- /* This value for SEC_LINK_DUPLICATES means that the linker
- should warn if any duplicate sections are a different size. */
- #define SEC_LINK_DUPLICATES_SAME_SIZE 0x100000
-
- /* This value for SEC_LINK_DUPLICATES means that the linker
- should warn if any duplicate sections contain different
- contents. */
- #define SEC_LINK_DUPLICATES_SAME_CONTENTS \
- (SEC_LINK_DUPLICATES_ONE_ONLY | SEC_LINK_DUPLICATES_SAME_SIZE)
-
- /* This section was created by the linker as part of dynamic
- relocation or other arcane processing. It is skipped when
- going through the first-pass output, trusting that someone
- else up the line will take care of it later. */
- #define SEC_LINKER_CREATED 0x200000
-
- /* This section should not be subject to garbage collection.
- Also set to inform the linker that this section should not be
- listed in the link map as discarded. */
- #define SEC_KEEP 0x400000
-
- /* This section contains "short" data, and should be placed
- "near" the GP. */
- #define SEC_SMALL_DATA 0x800000
-
- /* Attempt to merge identical entities in the section.
- Entity size is given in the entsize field. */
- #define SEC_MERGE 0x1000000
-
- /* If given with SEC_MERGE, entities to merge are zero terminated
- strings where entsize specifies character size instead of fixed
- size entries. */
- #define SEC_STRINGS 0x2000000
-
- /* This section contains data about section groups. */
- #define SEC_GROUP 0x4000000
-
- /* The section is a COFF shared library section. This flag is
- only for the linker. If this type of section appears in
- the input file, the linker must copy it to the output file
- without changing the vma or size. FIXME: Although this
- was originally intended to be general, it really is COFF
- specific (and the flag was renamed to indicate this). It
- might be cleaner to have some more general mechanism to
- allow the back end to control what the linker does with
- sections. */
- #define SEC_COFF_SHARED_LIBRARY 0x10000000
-
- /* This section contains data which may be shared with other
- executables or shared objects. This is for COFF only. */
- #define SEC_COFF_SHARED 0x20000000
-
- /* When a section with this flag is being linked, then if the size of
- the input section is less than a page, it should not cross a page
- boundary. If the size of the input section is one page or more,
- it should be aligned on a page boundary. This is for TI
- TMS320C54X only. */
- #define SEC_TIC54X_BLOCK 0x40000000
-
- /* Conditionally link this section; do not link if there are no
- references found to any symbol in the section. This is for TI
- TMS320C54X only. */
- #define SEC_TIC54X_CLINK 0x80000000
-
- /* End of section flags. */
-
- /* Some internal packed boolean fields. */
-
- /* See the vma field. */
- unsigned int user_set_vma : 1;
-
- /* A mark flag used by some of the linker backends. */
- unsigned int linker_mark : 1;
-
- /* Another mark flag used by some of the linker backends. Set for
- output sections that have an input section. */
- unsigned int linker_has_input : 1;
-
- /* Mark flags used by some linker backends for garbage collection. */
- unsigned int gc_mark : 1;
- unsigned int gc_mark_from_eh : 1;
-
- /* The following flags are used by the ELF linker. */
-
- /* Mark sections which have been allocated to segments. */
- unsigned int segment_mark : 1;
-
- /* Type of sec_info information. */
- unsigned int sec_info_type:3;
- #define ELF_INFO_TYPE_NONE 0
- #define ELF_INFO_TYPE_STABS 1
- #define ELF_INFO_TYPE_MERGE 2
- #define ELF_INFO_TYPE_EH_FRAME 3
- #define ELF_INFO_TYPE_JUST_SYMS 4
-
- /* Nonzero if this section uses RELA relocations, rather than REL. */
- unsigned int use_rela_p:1;
-
- /* Bits used by various backends. The generic code doesn't touch
- these fields. */
-
- /* Nonzero if this section has TLS related relocations. */
- unsigned int has_tls_reloc:1;
-
- /* Nonzero if this section has a gp reloc. */
- unsigned int has_gp_reloc:1;
-
- /* Nonzero if this section needs the relax finalize pass. */
- unsigned int need_finalize_relax:1;
-
- /* Whether relocations have been processed. */
- unsigned int reloc_done : 1;
-
- /* End of internal packed boolean fields. */
-
- /* The virtual memory address of the section - where it will be
- at run time. The symbols are relocated against this. The
- user_set_vma flag is maintained by bfd; if it's not set, the
- backend can assign addresses (for example, in `a.out', where
- the default address for `.data' is dependent on the specific
- target and various flags). */
- bfd_vma vma;
-
- /* The load address of the section - where it would be in a
- rom image; really only used for writing section header
- information. */
- bfd_vma lma;
-
- /* The size of the section in octets, as it will be output.
- Contains a value even if the section has no contents (e.g., the
- size of `.bss'). */
- bfd_size_type size;
-
- /* For input sections, the original size on disk of the section, in
- octets. This field is used by the linker relaxation code. It is
- currently only set for sections where the linker relaxation scheme
- doesn't cache altered section and reloc contents (stabs, eh_frame,
- SEC_MERGE, some coff relaxing targets), and thus the original size
- needs to be kept to read the section multiple times.
- For output sections, rawsize holds the section size calculated on
- a previous linker relaxation pass. */
- bfd_size_type rawsize;
-
- /* If this section is going to be output, then this value is the
- offset in *bytes* into the output section of the first byte in the
- input section (byte ==> smallest addressable unit on the
- target). In most cases, if this was going to start at the
- 100th octet (8-bit quantity) in the output section, this value
- would be 100. However, if the target byte size is 16 bits
- (bfd_octets_per_byte is "2"), this value would be 50. */
- bfd_vma output_offset;
-
- /* The output section through which to map on output. */
- struct bfd_section *output_section;
-
- /* The alignment requirement of the section, as an exponent of 2 -
- e.g., 3 aligns to 2^3 (or 8). */
- unsigned int alignment_power;
-
- /* If an input section, a pointer to a vector of relocation
- records for the data in this section. */
- struct reloc_cache_entry *relocation;
-
- /* If an output section, a pointer to a vector of pointers to
- relocation records for the data in this section. */
- struct reloc_cache_entry **orelocation;
-
- /* The number of relocation records in one of the above. */
- unsigned reloc_count;
-
- /* Information below is back end specific - and not always used
- or updated. */
-
- /* File position of section data. */
- file_ptr filepos;
-
- /* File position of relocation info. */
- file_ptr rel_filepos;
-
- /* File position of line data. */
- file_ptr line_filepos;
-
- /* Pointer to data for applications. */
- void *userdata;
-
- /* If the SEC_IN_MEMORY flag is set, this points to the actual
- contents. */
- unsigned char *contents;
-
- /* Attached line number information. */
- alent *lineno;
-
- /* Number of line number records. */
- unsigned int lineno_count;
-
- /* Entity size for merging purposes. */
- unsigned int entsize;
-
- /* Points to the kept section if this section is a link-once section,
- and is discarded. */
- struct bfd_section *kept_section;
-
- /* When a section is being output, this value changes as more
- linenumbers are written out. */
- file_ptr moving_line_filepos;
-
- /* What the section number is in the target world. */
- int target_index;
-
- void *used_by_bfd;
-
- /* If this is a constructor section then here is a list of the
- relocations created to relocate items within it. */
- struct relent_chain *constructor_chain;
-
- /* The BFD which owns the section. */
- bfd *owner;
-
- /* A symbol which points at this section only. */
- struct bfd_symbol *symbol;
- struct bfd_symbol **symbol_ptr_ptr;
-
- /* Early in the link process, map_head and map_tail are used to build
- a list of input sections attached to an output section. Later,
- output sections use these fields for a list of bfd_link_order
- structs. */
- union {
- struct bfd_link_order *link_order;
- struct bfd_section *s;
- } map_head, map_tail;
- } asection;
-
- /* These sections are global, and are managed by BFD. The application
- and target back end are not permitted to change the values in
- these sections. New code should use the section_ptr macros rather
- than referring directly to the const sections. The const sections
- may eventually vanish. */
- #define BFD_ABS_SECTION_NAME "*ABS*"
- #define BFD_UND_SECTION_NAME "*UND*"
- #define BFD_COM_SECTION_NAME "*COM*"
- #define BFD_IND_SECTION_NAME "*IND*"
-
- /* The absolute section. */
- extern asection bfd_abs_section;
- #define bfd_abs_section_ptr ((asection *) &bfd_abs_section)
- #define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr)
- /* Pointer to the undefined section. */
- extern asection bfd_und_section;
- #define bfd_und_section_ptr ((asection *) &bfd_und_section)
- #define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr)
- /* Pointer to the common section. */
- extern asection bfd_com_section;
- #define bfd_com_section_ptr ((asection *) &bfd_com_section)
- /* Pointer to the indirect section. */
- extern asection bfd_ind_section;
- #define bfd_ind_section_ptr ((asection *) &bfd_ind_section)
- #define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr)
-
- #define bfd_is_const_section(SEC) \
- ( ((SEC) == bfd_abs_section_ptr) \
- || ((SEC) == bfd_und_section_ptr) \
- || ((SEC) == bfd_com_section_ptr) \
- || ((SEC) == bfd_ind_section_ptr))
-
- /* Macros to handle insertion and deletion of a bfd's sections. These
- only handle the list pointers, ie. do not adjust section_count,
- target_index etc. */
- #define bfd_section_list_remove(ABFD, S) \
- do \
- { \
- asection *_s = S; \
- asection *_next = _s->next; \
- asection *_prev = _s->prev; \
- if (_prev) \
- _prev->next = _next; \
- else \
- (ABFD)->sections = _next; \
- if (_next) \
- _next->prev = _prev; \
- else \
- (ABFD)->section_last = _prev; \
- } \
- while (0)
- #define bfd_section_list_append(ABFD, S) \
- do \
- { \
- asection *_s = S; \
- bfd *_abfd = ABFD; \
- _s->next = NULL; \
- if (_abfd->section_last) \
- { \
- _s->prev = _abfd->section_last; \
- _abfd->section_last->next = _s; \
- } \
- else \
- { \
- _s->prev = NULL; \
- _abfd->sections = _s; \
- } \
- _abfd->section_last = _s; \
- } \
- while (0)
- #define bfd_section_list_prepend(ABFD, S) \
- do \
- { \
- asection *_s = S; \
- bfd *_abfd = ABFD; \
- _s->prev = NULL; \
- if (_abfd->sections) \
- { \
- _s->next = _abfd->sections; \
- _abfd->sections->prev = _s; \
- } \
- else \
- { \
- _s->next = NULL; \
- _abfd->section_last = _s; \
- } \
- _abfd->sections = _s; \
- } \
- while (0)
- #define bfd_section_list_insert_after(ABFD, A, S) \
- do \
- { \
- asection *_a = A; \
- asection *_s = S; \
- asection *_next = _a->next; \
- _s->next = _next; \
- _s->prev = _a; \
- _a->next = _s; \
- if (_next) \
- _next->prev = _s; \
- else \
- (ABFD)->section_last = _s; \
- } \
- while (0)
- #define bfd_section_list_insert_before(ABFD, B, S) \
- do \
- { \
- asection *_b = B; \
- asection *_s = S; \
- asection *_prev = _b->prev; \
- _s->prev = _prev; \
- _s->next = _b; \
- _b->prev = _s; \
- if (_prev) \
- _prev->next = _s; \
- else \
- (ABFD)->sections = _s; \
- } \
- while (0)
- #define bfd_section_removed_from_list(ABFD, S) \
- ((S)->next == NULL ? (ABFD)->section_last != (S) : (S)->next->prev != (S))
-
- #define BFD_FAKE_SECTION(SEC, FLAGS, SYM, NAME, IDX) \
- /* name, id, index, next, prev, flags, user_set_vma, */ \
- { NAME, IDX, 0, NULL, NULL, FLAGS, 0, \
- \
- /* linker_mark, linker_has_input, gc_mark, gc_mark_from_eh, */ \
- 0, 0, 1, 0, \
- \
- /* segment_mark, sec_info_type, use_rela_p, has_tls_reloc, */ \
- 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, (struct bfd_section *) &SEC, 0, \
- \
- /* relocation, orelocation, reloc_count, filepos, rel_filepos, */ \
- NULL, NULL, 0, 0, 0, \
- \
- /* line_filepos, userdata, contents, lineno, lineno_count, */ \
- 0, NULL, NULL, NULL, 0, \
- \
- /* entsize, kept_section, moving_line_filepos, */ \
- 0, NULL, 0, \
- \
- /* target_index, used_by_bfd, constructor_chain, owner, */ \
- 0, NULL, NULL, NULL, \
- \
- /* symbol, symbol_ptr_ptr, */ \
- (struct bfd_symbol *) SYM, &SEC.symbol, \
- \
- /* map_head, map_tail */ \
- { NULL }, { NULL } \
- }
-
-\1f
-File: bfd.info, Node: section prototypes, Prev: typedef asection, Up: Sections
-
-2.6.5 Section prototypes
-------------------------
-
-These are the functions exported by the section handling part of BFD.
-
-2.6.5.1 `bfd_section_list_clear'
-................................
-
-*Synopsis*
- void bfd_section_list_clear (bfd *);
- *Description*
-Clears the section list, and also resets the section count and hash
-table entries.
-
-2.6.5.2 `bfd_get_section_by_name'
-.................................
-
-*Synopsis*
- asection *bfd_get_section_by_name (bfd *abfd, const char *name);
- *Description*
-Run through ABFD and return the one of the `asection's whose name
-matches NAME, otherwise `NULL'. *Note Sections::, for more information.
-
- This should only be used in special cases; the normal way to process
-all sections of a given name is to use `bfd_map_over_sections' and
-`strcmp' on the name (or better yet, base it on the section flags or
-something else) for each section.
-
-2.6.5.3 `bfd_get_section_by_name_if'
-....................................
-
-*Synopsis*
- asection *bfd_get_section_by_name_if
- (bfd *abfd,
- const char *name,
- bfd_boolean (*func) (bfd *abfd, asection *sect, void *obj),
- void *obj);
- *Description*
-Call the provided function FUNC for each section attached to the BFD
-ABFD whose name matches NAME, passing OBJ as an argument. The function
-will be called as if by
-
- func (abfd, the_section, obj);
-
- It returns the first section for which FUNC returns true, otherwise
-`NULL'.
-
-2.6.5.4 `bfd_get_unique_section_name'
-.....................................
-
-*Synopsis*
- char *bfd_get_unique_section_name
- (bfd *abfd, const char *templat, int *count);
- *Description*
-Invent a section name that is unique in ABFD by tacking a dot and a
-digit suffix onto the original TEMPLAT. If COUNT is non-NULL, then it
-specifies the first number tried as a suffix to generate a unique name.
-The value pointed to by COUNT will be incremented in this case.
-
-2.6.5.5 `bfd_make_section_old_way'
-..................................
-
-*Synopsis*
- asection *bfd_make_section_old_way (bfd *abfd, const char *name);
- *Description*
-Create a new empty section called NAME and attach it to the end of the
-chain of sections for the BFD ABFD. An attempt to create a section with
-a name which is already in use returns its pointer without changing the
-section chain.
-
- It has the funny name since this is the way it used to be before it
-was rewritten....
-
- Possible errors are:
- * `bfd_error_invalid_operation' - If output has already started for
- this BFD.
-
- * `bfd_error_no_memory' - If memory allocation fails.
-
-2.6.5.6 `bfd_make_section_anyway_with_flags'
-............................................
-
-*Synopsis*
- asection *bfd_make_section_anyway_with_flags
- (bfd *abfd, const char *name, flagword flags);
- *Description*
-Create a new empty section called NAME and attach it to the end of the
-chain of sections for ABFD. Create a new section even if there is
-already a section with that name. Also set the attributes of the new
-section to the value FLAGS.
-
- Return `NULL' and set `bfd_error' on error; possible errors are:
- * `bfd_error_invalid_operation' - If output has already started for
- ABFD.
-
- * `bfd_error_no_memory' - If memory allocation fails.
-
-2.6.5.7 `bfd_make_section_anyway'
-.................................
-
-*Synopsis*
- asection *bfd_make_section_anyway (bfd *abfd, const char *name);
- *Description*
-Create a new empty section called NAME and attach it to the end of the
-chain of sections for ABFD. Create a new section even if there is
-already a section with that name.
-
- Return `NULL' and set `bfd_error' on error; possible errors are:
- * `bfd_error_invalid_operation' - If output has already started for
- ABFD.
-
- * `bfd_error_no_memory' - If memory allocation fails.
-
-2.6.5.8 `bfd_make_section_with_flags'
-.....................................
-
-*Synopsis*
- asection *bfd_make_section_with_flags
- (bfd *, const char *name, flagword flags);
- *Description*
-Like `bfd_make_section_anyway', but return `NULL' (without calling
-bfd_set_error ()) without changing the section chain if there is
-already a section named NAME. Also set the attributes of the new
-section to the value FLAGS. If there is an error, return `NULL' and set
-`bfd_error'.
-
-2.6.5.9 `bfd_make_section'
-..........................
-
-*Synopsis*
- asection *bfd_make_section (bfd *, const char *name);
- *Description*
-Like `bfd_make_section_anyway', but return `NULL' (without calling
-bfd_set_error ()) without changing the section chain if there is
-already a section named NAME. If there is an error, return `NULL' and
-set `bfd_error'.
-
-2.6.5.10 `bfd_set_section_flags'
-................................
-
-*Synopsis*
- bfd_boolean bfd_set_section_flags
- (bfd *abfd, asection *sec, flagword flags);
- *Description*
-Set the attributes of the section SEC in the BFD ABFD to the value
-FLAGS. Return `TRUE' on success, `FALSE' on error. Possible error
-returns are:
-
- * `bfd_error_invalid_operation' - The section cannot have one or
- more of the attributes requested. For example, a .bss section in
- `a.out' may not have the `SEC_HAS_CONTENTS' field set.
-
-2.6.5.11 `bfd_map_over_sections'
-................................
-
-*Synopsis*
- void bfd_map_over_sections
- (bfd *abfd,
- void (*func) (bfd *abfd, asection *sect, void *obj),
- void *obj);
- *Description*
-Call the provided function FUNC for each section attached to the BFD
-ABFD, passing OBJ as an argument. The function will be called as if by
-
- func (abfd, the_section, obj);
-
- This is the preferred method for iterating over sections; an
-alternative would be to use a loop:
-
- section *p;
- for (p = abfd->sections; p != NULL; p = p->next)
- func (abfd, p, ...)
-
-2.6.5.12 `bfd_sections_find_if'
-...............................
-
-*Synopsis*
- asection *bfd_sections_find_if
- (bfd *abfd,
- bfd_boolean (*operation) (bfd *abfd, asection *sect, void *obj),
- void *obj);
- *Description*
-Call the provided function OPERATION for each section attached to the
-BFD ABFD, passing OBJ as an argument. The function will be called as if
-by
-
- operation (abfd, the_section, obj);
-
- It returns the first section for which OPERATION returns true.
-
-2.6.5.13 `bfd_set_section_size'
-...............................
-
-*Synopsis*
- bfd_boolean bfd_set_section_size
- (bfd *abfd, asection *sec, bfd_size_type val);
- *Description*
-Set SEC to the size VAL. If the operation is ok, then `TRUE' is
-returned, else `FALSE'.
-
- Possible error returns:
- * `bfd_error_invalid_operation' - Writing has started to the BFD, so
- setting the size is invalid.
-
-2.6.5.14 `bfd_set_section_contents'
-...................................
-
-*Synopsis*
- bfd_boolean bfd_set_section_contents
- (bfd *abfd, asection *section, const void *data,
- file_ptr offset, bfd_size_type count);
- *Description*
-Sets the contents of the section SECTION in BFD ABFD to the data
-starting in memory at DATA. The data is written to the output section
-starting at offset OFFSET for COUNT octets.
-
- Normally `TRUE' is returned, else `FALSE'. Possible error returns
-are:
- * `bfd_error_no_contents' - The output section does not have the
- `SEC_HAS_CONTENTS' attribute, so nothing can be written to it.
-
- * and some more too
- This routine is front end to the back end function
-`_bfd_set_section_contents'.
-
-2.6.5.15 `bfd_get_section_contents'
-...................................
-
-*Synopsis*
- bfd_boolean bfd_get_section_contents
- (bfd *abfd, asection *section, void *location, file_ptr offset,
- bfd_size_type count);
- *Description*
-Read data from SECTION in BFD ABFD into memory starting at LOCATION.
-The data is read at an offset of OFFSET from the start of the input
-section, and is read for COUNT bytes.
-
- If the contents of a constructor with the `SEC_CONSTRUCTOR' flag set
-are requested or if the section does not have the `SEC_HAS_CONTENTS'
-flag set, then the LOCATION is filled with zeroes. If no errors occur,
-`TRUE' is returned, else `FALSE'.
-
-2.6.5.16 `bfd_malloc_and_get_section'
-.....................................
-
-*Synopsis*
- bfd_boolean bfd_malloc_and_get_section
- (bfd *abfd, asection *section, bfd_byte **buf);
- *Description*
-Read all data from SECTION in BFD ABFD into a buffer, *BUF, malloc'd by
-this function.
-
-2.6.5.17 `bfd_copy_private_section_data'
-........................................
-
-*Synopsis*
- bfd_boolean bfd_copy_private_section_data
- (bfd *ibfd, asection *isec, bfd *obfd, asection *osec);
- *Description*
-Copy private section information from ISEC in the BFD IBFD to the
-section OSEC in the BFD OBFD. Return `TRUE' on success, `FALSE' on
-error. Possible error returns are:
-
- * `bfd_error_no_memory' - Not enough memory exists to create private
- data for OSEC.
-
- #define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \
- BFD_SEND (obfd, _bfd_copy_private_section_data, \
- (ibfd, isection, obfd, osection))
-
-2.6.5.18 `bfd_generic_is_group_section'
-.......................................
-
-*Synopsis*
- bfd_boolean bfd_generic_is_group_section (bfd *, const asection *sec);
- *Description*
-Returns TRUE if SEC is a member of a group.
-
-2.6.5.19 `bfd_generic_discard_group'
-....................................
-
-*Synopsis*
- bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group);
- *Description*
-Remove all members of GROUP from the output.
-
-\1f
-File: bfd.info, Node: Symbols, Next: Archives, Prev: Sections, Up: BFD front end
-
-2.7 Symbols
-===========
-
-BFD tries to maintain as much symbol information as it can when it
-moves information from file to file. BFD passes information to
-applications though the `asymbol' structure. When the application
-requests the symbol table, BFD reads the table in the native form and
-translates parts of it into the internal format. To maintain more than
-the information passed to applications, some targets keep some
-information "behind the scenes" in a structure only the particular back
-end knows about. For example, the coff back end keeps the original
-symbol table structure as well as the canonical structure when a BFD is
-read in. On output, the coff back end can reconstruct the output symbol
-table so that no information is lost, even information unique to coff
-which BFD doesn't know or understand. If a coff symbol table were read,
-but were written through an a.out back end, all the coff specific
-information would be lost. The symbol table of a BFD is not necessarily
-read in until a canonicalize request is made. Then the BFD back end
-fills in a table provided by the application with pointers to the
-canonical information. To output symbols, the application provides BFD
-with a table of pointers to pointers to `asymbol's. This allows
-applications like the linker to output a symbol as it was read, since
-the "behind the scenes" information will be still available.
-
-* Menu:
-
-* Reading Symbols::
-* Writing Symbols::
-* Mini Symbols::
-* typedef asymbol::
-* symbol handling functions::
-
-\1f
-File: bfd.info, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols
-
-2.7.1 Reading symbols
----------------------
-
-There are two stages to reading a symbol table from a BFD: allocating
-storage, and the actual reading process. This is an excerpt from an
-application which reads the symbol table:
-
- long storage_needed;
- asymbol **symbol_table;
- long number_of_symbols;
- long i;
-
- storage_needed = bfd_get_symtab_upper_bound (abfd);
-
- if (storage_needed < 0)
- FAIL
-
- if (storage_needed == 0)
- return;
-
- symbol_table = xmalloc (storage_needed);
- ...
- number_of_symbols =
- bfd_canonicalize_symtab (abfd, symbol_table);
-
- if (number_of_symbols < 0)
- FAIL
-
- for (i = 0; i < number_of_symbols; i++)
- process_symbol (symbol_table[i]);
-
- All storage for the symbols themselves is in an objalloc connected
-to the BFD; it is freed when the BFD is closed.
-
-\1f
-File: bfd.info, Node: Writing Symbols, Next: Mini Symbols, Prev: Reading Symbols, Up: Symbols
-
-2.7.2 Writing symbols
----------------------
-
-Writing of a symbol table is automatic when a BFD open for writing is
-closed. The application attaches a vector of pointers to pointers to
-symbols to the BFD being written, and fills in the symbol count. The
-close and cleanup code reads through the table provided and performs
-all the necessary operations. The BFD output code must always be
-provided with an "owned" symbol: one which has come from another BFD,
-or one which has been created using `bfd_make_empty_symbol'. Here is an
-example showing the creation of a symbol table with only one element:
-
- #include "bfd.h"
- int main (void)
- {
- bfd *abfd;
- asymbol *ptrs[2];
- asymbol *new;
-
- abfd = bfd_openw ("foo","a.out-sunos-big");
- bfd_set_format (abfd, bfd_object);
- new = bfd_make_empty_symbol (abfd);
- new->name = "dummy_symbol";
- new->section = bfd_make_section_old_way (abfd, ".text");
- new->flags = BSF_GLOBAL;
- new->value = 0x12345;
-
- ptrs[0] = new;
- ptrs[1] = 0;
-
- bfd_set_symtab (abfd, ptrs, 1);
- bfd_close (abfd);
- return 0;
- }
-
- ./makesym
- nm foo
- 00012345 A dummy_symbol
-
- Many formats cannot represent arbitrary symbol information; for
-instance, the `a.out' object format does not allow an arbitrary number
-of sections. A symbol pointing to a section which is not one of
-`.text', `.data' or `.bss' cannot be described.
-
-\1f
-File: bfd.info, Node: Mini Symbols, Next: typedef asymbol, Prev: Writing Symbols, Up: Symbols
-
-2.7.3 Mini Symbols
-------------------
-
-Mini symbols provide read-only access to the symbol table. They use
-less memory space, but require more time to access. They can be useful
-for tools like nm or objdump, which may have to handle symbol tables of
-extremely large executables.
-
- The `bfd_read_minisymbols' function will read the symbols into
-memory in an internal form. It will return a `void *' pointer to a
-block of memory, a symbol count, and the size of each symbol. The
-pointer is allocated using `malloc', and should be freed by the caller
-when it is no longer needed.
-
- The function `bfd_minisymbol_to_symbol' will take a pointer to a
-minisymbol, and a pointer to a structure returned by
-`bfd_make_empty_symbol', and return a `asymbol' structure. The return
-value may or may not be the same as the value from
-`bfd_make_empty_symbol' which was passed in.
-
-\1f
-File: bfd.info, Node: typedef asymbol, Next: symbol handling functions, Prev: Mini Symbols, Up: Symbols
-
-2.7.4 typedef asymbol
----------------------
-
-An `asymbol' has the form:
-
-
- typedef struct bfd_symbol
- {
- /* A pointer to the BFD which owns the symbol. This information
- is necessary so that a back end can work out what additional
- information (invisible to the application writer) is carried
- with the symbol.
-
- This field is *almost* redundant, since you can use section->owner
- instead, except that some symbols point to the global sections
- bfd_{abs,com,und}_section. This could be fixed by making
- these globals be per-bfd (or per-target-flavor). FIXME. */
- struct bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */
-
- /* The text of the symbol. The name is left alone, and not copied; the
- application may not alter it. */
- const char *name;
-
- /* The value of the symbol. This really should be a union of a
- numeric value with a pointer, since some flags indicate that
- a pointer to another symbol is stored here. */
- symvalue value;
-
- /* Attributes of a symbol. */
- #define BSF_NO_FLAGS 0x00
-
- /* The symbol has local scope; `static' in `C'. The value
- is the offset into the section of the data. */
- #define BSF_LOCAL 0x01
-
- /* The symbol has global scope; initialized data in `C'. The
- value is the offset into the section of the data. */
- #define BSF_GLOBAL 0x02
-
- /* The symbol has global scope and is exported. The value is
- the offset into the section of the data. */
- #define BSF_EXPORT BSF_GLOBAL /* No real difference. */
-
- /* A normal C symbol would be one of:
- `BSF_LOCAL', `BSF_FORT_COMM', `BSF_UNDEFINED' or
- `BSF_GLOBAL'. */
-
- /* The symbol is a debugging record. The value has an arbitrary
- meaning, unless BSF_DEBUGGING_RELOC is also set. */
- #define BSF_DEBUGGING 0x08
-
- /* The symbol denotes a function entry point. Used in ELF,
- perhaps others someday. */
- #define BSF_FUNCTION 0x10
-
- /* Used by the linker. */
- #define BSF_KEEP 0x20
- #define BSF_KEEP_G 0x40
-
- /* A weak global symbol, overridable without warnings by
- a regular global symbol of the same name. */
- #define BSF_WEAK 0x80
-
- /* This symbol was created to point to a section, e.g. ELF's
- STT_SECTION symbols. */
- #define BSF_SECTION_SYM 0x100
-
- /* The symbol used to be a common symbol, but now it is
- allocated. */
- #define BSF_OLD_COMMON 0x200
-
- /* The default value for common data. */
- #define BFD_FORT_COMM_DEFAULT_VALUE 0
-
- /* In some files the type of a symbol sometimes alters its
- location in an output file - ie in coff a `ISFCN' symbol
- which is also `C_EXT' symbol appears where it was
- declared and not at the end of a section. This bit is set
- by the target BFD part to convey this information. */
- #define BSF_NOT_AT_END 0x400
-
- /* Signal that the symbol is the label of constructor section. */
- #define BSF_CONSTRUCTOR 0x800
-
- /* Signal that the symbol is a warning symbol. The name is a
- warning. The name of the next symbol is the one to warn about;
- if a reference is made to a symbol with the same name as the next
- symbol, a warning is issued by the linker. */
- #define BSF_WARNING 0x1000
-
- /* Signal that the symbol is indirect. This symbol is an indirect
- pointer to the symbol with the same name as the next symbol. */
- #define BSF_INDIRECT 0x2000
-
- /* BSF_FILE marks symbols that contain a file name. This is used
- for ELF STT_FILE symbols. */
- #define BSF_FILE 0x4000
-
- /* Symbol is from dynamic linking information. */
- #define BSF_DYNAMIC 0x8000
-
- /* The symbol denotes a data object. Used in ELF, and perhaps
- others someday. */
- #define BSF_OBJECT 0x10000
-
- /* This symbol is a debugging symbol. The value is the offset
- into the section of the data. BSF_DEBUGGING should be set
- as well. */
- #define BSF_DEBUGGING_RELOC 0x20000
-
- /* This symbol is thread local. Used in ELF. */
- #define BSF_THREAD_LOCAL 0x40000
-
- /* This symbol represents a complex relocation expression,
- with the expression tree serialized in the symbol name. */
- #define BSF_RELC 0x80000
-
- /* This symbol represents a signed complex relocation expression,
- with the expression tree serialized in the symbol name. */
- #define BSF_SRELC 0x100000
-
- flagword flags;
-
- /* A pointer to the section to which this symbol is
- relative. This will always be non NULL, there are special
- sections for undefined and absolute symbols. */
- struct bfd_section *section;
-
- /* Back end special data. */
- union
- {
- void *p;
- bfd_vma i;
- }
- udata;
- }
- asymbol;
-
-\1f
-File: bfd.info, Node: symbol handling functions, Prev: typedef asymbol, Up: Symbols
-
-2.7.5 Symbol handling functions
--------------------------------
-
-2.7.5.1 `bfd_get_symtab_upper_bound'
-....................................
-
-*Description*
-Return the number of bytes required to store a vector of pointers to
-`asymbols' for all the symbols in the BFD ABFD, including a terminal
-NULL pointer. If there are no symbols in the BFD, then return 0. If an
-error occurs, return -1.
- #define bfd_get_symtab_upper_bound(abfd) \
- BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd))
-
-2.7.5.2 `bfd_is_local_label'
-............................
-
-*Synopsis*
- bfd_boolean bfd_is_local_label (bfd *abfd, asymbol *sym);
- *Description*
-Return TRUE if the given symbol SYM in the BFD ABFD is a compiler
-generated local label, else return FALSE.
-
-2.7.5.3 `bfd_is_local_label_name'
-.................................
-
-*Synopsis*
- bfd_boolean bfd_is_local_label_name (bfd *abfd, const char *name);
- *Description*
-Return TRUE if a symbol with the name NAME in the BFD ABFD is a
-compiler generated local label, else return FALSE. This just checks
-whether the name has the form of a local label.
- #define bfd_is_local_label_name(abfd, name) \
- BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name))
-
-2.7.5.4 `bfd_is_target_special_symbol'
-......................................
-
-*Synopsis*
- bfd_boolean bfd_is_target_special_symbol (bfd *abfd, asymbol *sym);
- *Description*
-Return TRUE iff a symbol SYM in the BFD ABFD is something special to
-the particular target represented by the BFD. Such symbols should
-normally not be mentioned to the user.
- #define bfd_is_target_special_symbol(abfd, sym) \
- BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym))
-
-2.7.5.5 `bfd_canonicalize_symtab'
-.................................
-
-*Description*
-Read the symbols from the BFD ABFD, and fills in the vector LOCATION
-with pointers to the symbols and a trailing NULL. Return the actual
-number of symbol pointers, not including the NULL.
- #define bfd_canonicalize_symtab(abfd, location) \
- BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location))
-
-2.7.5.6 `bfd_set_symtab'
-........................
-
-*Synopsis*
- bfd_boolean bfd_set_symtab
- (bfd *abfd, asymbol **location, unsigned int count);
- *Description*
-Arrange that when the output BFD ABFD is closed, the table LOCATION of
-COUNT pointers to symbols will be written.
-
-2.7.5.7 `bfd_print_symbol_vandf'
-................................
-
-*Synopsis*
- void bfd_print_symbol_vandf (bfd *abfd, void *file, asymbol *symbol);
- *Description*
-Print the value and flags of the SYMBOL supplied to the stream FILE.
-
-2.7.5.8 `bfd_make_empty_symbol'
-...............................
-
-*Description*
-Create a new `asymbol' structure for the BFD ABFD and return a pointer
-to it.
-
- This routine is necessary because each back end has private
-information surrounding the `asymbol'. Building your own `asymbol' and
-pointing to it will not create the private information, and will cause
-problems later on.
- #define bfd_make_empty_symbol(abfd) \
- BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
-
-2.7.5.9 `_bfd_generic_make_empty_symbol'
-........................................
-
-*Synopsis*
- asymbol *_bfd_generic_make_empty_symbol (bfd *);
- *Description*
-Create a new `asymbol' structure for the BFD ABFD and return a pointer
-to it. Used by core file routines, binary back-end and anywhere else
-where no private info is needed.
-
-2.7.5.10 `bfd_make_debug_symbol'
-................................
-
-*Description*
-Create a new `asymbol' structure for the BFD ABFD, to be used as a
-debugging symbol. Further details of its use have yet to be worked out.
- #define bfd_make_debug_symbol(abfd,ptr,size) \
- BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size))
-
-2.7.5.11 `bfd_decode_symclass'
-..............................
-
-*Description*
-Return a character corresponding to the symbol class of SYMBOL, or '?'
-for an unknown class.
-
- *Synopsis*
- int bfd_decode_symclass (asymbol *symbol);
-
-2.7.5.12 `bfd_is_undefined_symclass'
-....................................
-
-*Description*
-Returns non-zero if the class symbol returned by bfd_decode_symclass
-represents an undefined symbol. Returns zero otherwise.
-
- *Synopsis*
- bfd_boolean bfd_is_undefined_symclass (int symclass);
-
-2.7.5.13 `bfd_symbol_info'
-..........................
-
-*Description*
-Fill in the basic info about symbol that nm needs. Additional info may
-be added by the back-ends after calling this function.
-
- *Synopsis*
- void bfd_symbol_info (asymbol *symbol, symbol_info *ret);
-
-2.7.5.14 `bfd_copy_private_symbol_data'
-.......................................
-
-*Synopsis*
- bfd_boolean bfd_copy_private_symbol_data
- (bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym);
- *Description*
-Copy private symbol information from ISYM in the BFD IBFD to the symbol
-OSYM in the BFD OBFD. Return `TRUE' on success, `FALSE' on error.
-Possible error returns are:
-
- * `bfd_error_no_memory' - Not enough memory exists to create private
- data for OSEC.
-
- #define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \
- BFD_SEND (obfd, _bfd_copy_private_symbol_data, \
- (ibfd, isymbol, obfd, osymbol))
-
-\1f
-File: bfd.info, Node: Archives, Next: Formats, Prev: Symbols, Up: BFD front end
-
-2.8 Archives
-============
-
-*Description*
-An archive (or library) is just another BFD. It has a symbol table,
-although there's not much a user program will do with it.
-
- The big difference between an archive BFD and an ordinary BFD is
-that the archive doesn't have sections. Instead it has a chain of BFDs
-that are considered its contents. These BFDs can be manipulated like
-any other. The BFDs contained in an archive opened for reading will
-all be opened for reading. You may put either input or output BFDs
-into an archive opened for output; they will be handled correctly when
-the archive is closed.
-
- Use `bfd_openr_next_archived_file' to step through the contents of
-an archive opened for input. You don't have to read the entire archive
-if you don't want to! Read it until you find what you want.
-
- Archive contents of output BFDs are chained through the `next'
-pointer in a BFD. The first one is findable through the `archive_head'
-slot of the archive. Set it with `bfd_set_archive_head' (q.v.). A
-given BFD may be in only one open output archive at a time.
-
- As expected, the BFD archive code is more general than the archive
-code of any given environment. BFD archives may contain files of
-different formats (e.g., a.out and coff) and even different
-architectures. You may even place archives recursively into archives!
-
- This can cause unexpected confusion, since some archive formats are
-more expressive than others. For instance, Intel COFF archives can
-preserve long filenames; SunOS a.out archives cannot. If you move a
-file from the first to the second format and back again, the filename
-may be truncated. Likewise, different a.out environments have different
-conventions as to how they truncate filenames, whether they preserve
-directory names in filenames, etc. When interoperating with native
-tools, be sure your files are homogeneous.
-
- Beware: most of these formats do not react well to the presence of
-spaces in filenames. We do the best we can, but can't always handle
-this case due to restrictions in the format of archives. Many Unix
-utilities are braindead in regards to spaces and such in filenames
-anyway, so this shouldn't be much of a restriction.
-
- Archives are supported in BFD in `archive.c'.
-
-2.8.1 Archive functions
------------------------
-
-2.8.1.1 `bfd_get_next_mapent'
-.............................
-
-*Synopsis*
- symindex bfd_get_next_mapent
- (bfd *abfd, symindex previous, carsym **sym);
- *Description*
-Step through archive ABFD's symbol table (if it has one). Successively
-update SYM with the next symbol's information, returning that symbol's
-(internal) index into the symbol table.
-
- Supply `BFD_NO_MORE_SYMBOLS' as the PREVIOUS entry to get the first
-one; returns `BFD_NO_MORE_SYMBOLS' when you've already got the last one.
-
- A `carsym' is a canonical archive symbol. The only user-visible
-element is its name, a null-terminated string.
-
-2.8.1.2 `bfd_set_archive_head'
-..............................
-
-*Synopsis*
- bfd_boolean bfd_set_archive_head (bfd *output, bfd *new_head);
- *Description*
-Set the head of the chain of BFDs contained in the archive OUTPUT to
-NEW_HEAD.
-
-2.8.1.3 `bfd_openr_next_archived_file'
-......................................
-
-*Synopsis*
- bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous);
- *Description*
-Provided a BFD, ARCHIVE, containing an archive and NULL, open an input
-BFD on the first contained element and returns that. Subsequent calls
-should pass the archive and the previous return value to return a
-created BFD to the next contained element. NULL is returned when there
-are no more.
-
-\1f
-File: bfd.info, Node: Formats, Next: Relocations, Prev: Archives, Up: BFD front end
-
-2.9 File formats
-================
-
-A format is a BFD concept of high level file contents type. The formats
-supported by BFD are:
-
- * `bfd_object'
- The BFD may contain data, symbols, relocations and debug info.
-
- * `bfd_archive'
- The BFD contains other BFDs and an optional index.
-
- * `bfd_core'
- The BFD contains the result of an executable core dump.
-
-2.9.1 File format functions
----------------------------
-
-2.9.1.1 `bfd_check_format'
-..........................
-
-*Synopsis*
- bfd_boolean bfd_check_format (bfd *abfd, bfd_format format);
- *Description*
-Verify if the file attached to the BFD ABFD is compatible with the
-format FORMAT (i.e., one of `bfd_object', `bfd_archive' or `bfd_core').
-
- If the BFD has been set to a specific target before the call, only
-the named target and format combination is checked. If the target has
-not been set, or has been set to `default', then all the known target
-backends is interrogated to determine a match. If the default target
-matches, it is used. If not, exactly one target must recognize the
-file, or an error results.
-
- The function returns `TRUE' on success, otherwise `FALSE' with one
-of the following error codes:
-
- * `bfd_error_invalid_operation' - if `format' is not one of
- `bfd_object', `bfd_archive' or `bfd_core'.
-
- * `bfd_error_system_call' - if an error occured during a read - even
- some file mismatches can cause bfd_error_system_calls.
-
- * `file_not_recognised' - none of the backends recognised the file
- format.
-
- * `bfd_error_file_ambiguously_recognized' - more than one backend
- recognised the file format.
-
-2.9.1.2 `bfd_check_format_matches'
-..................................
-
-*Synopsis*
- bfd_boolean bfd_check_format_matches
- (bfd *abfd, bfd_format format, char ***matching);
- *Description*
-Like `bfd_check_format', except when it returns FALSE with `bfd_errno'
-set to `bfd_error_file_ambiguously_recognized'. In that case, if
-MATCHING is not NULL, it will be filled in with a NULL-terminated list
-of the names of the formats that matched, allocated with `malloc'.
-Then the user may choose a format and try again.
-
- When done with the list that MATCHING points to, the caller should
-free it.
-
-2.9.1.3 `bfd_set_format'
-........................
-
-*Synopsis*
- bfd_boolean bfd_set_format (bfd *abfd, bfd_format format);
- *Description*
-This function sets the file format of the BFD ABFD to the format
-FORMAT. If the target set in the BFD does not support the format
-requested, the format is invalid, or the BFD is not open for writing,
-then an error occurs.
-
-2.9.1.4 `bfd_format_string'
-...........................
-
-*Synopsis*
- const char *bfd_format_string (bfd_format format);
- *Description*
-Return a pointer to a const string `invalid', `object', `archive',
-`core', or `unknown', depending upon the value of FORMAT.
-
-\1f
-File: bfd.info, Node: Relocations, Next: Core Files, Prev: Formats, Up: BFD front end
-
-2.10 Relocations
-================
-
-BFD maintains relocations in much the same way it maintains symbols:
-they are left alone until required, then read in en-masse and
-translated into an internal form. A common routine
-`bfd_perform_relocation' acts upon the canonical form to do the fixup.
-
- Relocations are maintained on a per section basis, while symbols are
-maintained on a per BFD basis.
-
- All that a back end has to do to fit the BFD interface is to create
-a `struct reloc_cache_entry' for each relocation in a particular
-section, and fill in the right bits of the structures.
-
-* Menu:
-
-* typedef arelent::
-* howto manager::
-
-\1f
-File: bfd.info, Node: typedef arelent, Next: howto manager, Prev: Relocations, Up: Relocations
-
-2.10.1 typedef arelent
-----------------------
-
-This is the structure of a relocation entry:
-
-
- typedef enum bfd_reloc_status
- {
- /* No errors detected. */
- bfd_reloc_ok,
-
- /* The relocation was performed, but there was an overflow. */
- bfd_reloc_overflow,
-
- /* The address to relocate was not within the section supplied. */
- bfd_reloc_outofrange,
-
- /* Used by special functions. */
- bfd_reloc_continue,
-
- /* Unsupported relocation size requested. */
- bfd_reloc_notsupported,
-
- /* Unused. */
- bfd_reloc_other,
-
- /* The symbol to relocate against was undefined. */
- bfd_reloc_undefined,
-
- /* The relocation was performed, but may not be ok - presently
- generated only when linking i960 coff files with i960 b.out
- symbols. If this type is returned, the error_message argument
- to bfd_perform_relocation will be set. */
- bfd_reloc_dangerous
- }
- bfd_reloc_status_type;
-
-
- typedef struct reloc_cache_entry
- {
- /* A pointer into the canonical table of pointers. */
- struct bfd_symbol **sym_ptr_ptr;
-
- /* offset in section. */
- bfd_size_type address;
-
- /* addend for relocation value. */
- bfd_vma addend;
-
- /* Pointer to how to perform the required relocation. */
- reloc_howto_type *howto;
-
- }
- arelent;
- *Description*
-Here is a description of each of the fields within an `arelent':
-
- * `sym_ptr_ptr'
- The symbol table pointer points to a pointer to the symbol
-associated with the relocation request. It is the pointer into the
-table returned by the back end's `canonicalize_symtab' action. *Note
-Symbols::. The symbol is referenced through a pointer to a pointer so
-that tools like the linker can fix up all the symbols of the same name
-by modifying only one pointer. The relocation routine looks in the
-symbol and uses the base of the section the symbol is attached to and
-the value of the symbol as the initial relocation offset. If the symbol
-pointer is zero, then the section provided is looked up.
-
- * `address'
- The `address' field gives the offset in bytes from the base of the
-section data which owns the relocation record to the first byte of
-relocatable information. The actual data relocated will be relative to
-this point; for example, a relocation type which modifies the bottom
-two bytes of a four byte word would not touch the first byte pointed to
-in a big endian world.
-
- * `addend'
- The `addend' is a value provided by the back end to be added (!) to
-the relocation offset. Its interpretation is dependent upon the howto.
-For example, on the 68k the code:
-
- char foo[];
- main()
- {
- return foo[0x12345678];
- }
-
- Could be compiled into:
-
- linkw fp,#-4
- moveb @#12345678,d0
- extbl d0
- unlk fp
- rts
-
- This could create a reloc pointing to `foo', but leave the offset in
-the data, something like:
-
- RELOCATION RECORDS FOR [.text]:
- offset type value
- 00000006 32 _foo
-
- 00000000 4e56 fffc ; linkw fp,#-4
- 00000004 1039 1234 5678 ; moveb @#12345678,d0
- 0000000a 49c0 ; extbl d0
- 0000000c 4e5e ; unlk fp
- 0000000e 4e75 ; rts
-
- Using coff and an 88k, some instructions don't have enough space in
-them to represent the full address range, and pointers have to be
-loaded in two parts. So you'd get something like:
-
- or.u r13,r0,hi16(_foo+0x12345678)
- ld.b r2,r13,lo16(_foo+0x12345678)
- jmp r1
-
- This should create two relocs, both pointing to `_foo', and with
-0x12340000 in their addend field. The data would consist of:
-
- RELOCATION RECORDS FOR [.text]:
- offset type value
- 00000002 HVRT16 _foo+0x12340000
- 00000006 LVRT16 _foo+0x12340000
-
- 00000000 5da05678 ; or.u r13,r0,0x5678
- 00000004 1c4d5678 ; ld.b r2,r13,0x5678
- 00000008 f400c001 ; jmp r1
-
- The relocation routine digs out the value from the data, adds it to
-the addend to get the original offset, and then adds the value of
-`_foo'. Note that all 32 bits have to be kept around somewhere, to cope
-with carry from bit 15 to bit 16.
-
- One further example is the sparc and the a.out format. The sparc has
-a similar problem to the 88k, in that some instructions don't have room
-for an entire offset, but on the sparc the parts are created in odd
-sized lumps. The designers of the a.out format chose to not use the
-data within the section for storing part of the offset; all the offset
-is kept within the reloc. Anything in the data should be ignored.
-
- save %sp,-112,%sp
- sethi %hi(_foo+0x12345678),%g2
- ldsb [%g2+%lo(_foo+0x12345678)],%i0
- ret
- restore
-
- Both relocs contain a pointer to `foo', and the offsets contain junk.
-
- RELOCATION RECORDS FOR [.text]:
- offset type value
- 00000004 HI22 _foo+0x12345678
- 00000008 LO10 _foo+0x12345678
-
- 00000000 9de3bf90 ; save %sp,-112,%sp
- 00000004 05000000 ; sethi %hi(_foo+0),%g2
- 00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0
- 0000000c 81c7e008 ; ret
- 00000010 81e80000 ; restore
-
- * `howto'
- The `howto' field can be imagined as a relocation instruction. It is
-a pointer to a structure which contains information on what to do with
-all of the other information in the reloc record and data section. A
-back end would normally have a relocation instruction set and turn
-relocations into pointers to the correct structure on input - but it
-would be possible to create each howto field on demand.
-
-2.10.1.1 `enum complain_overflow'
-.................................
-
-Indicates what sort of overflow checking should be done when performing
-a relocation.
-
-
- enum complain_overflow
- {
- /* Do not complain on overflow. */
- complain_overflow_dont,
-
- /* Complain if the value overflows when considered as a signed
- number one bit larger than the field. ie. A bitfield of N bits
- is allowed to represent -2**n to 2**n-1. */
- complain_overflow_bitfield,
-
- /* Complain if the value overflows when considered as a signed
- number. */
- complain_overflow_signed,
-
- /* Complain if the value overflows when considered as an
- unsigned number. */
- complain_overflow_unsigned
- };
-
-2.10.1.2 `reloc_howto_type'
-...........................
-
-The `reloc_howto_type' is a structure which contains all the
-information that libbfd needs to know to tie up a back end's data.
-
- struct bfd_symbol; /* Forward declaration. */
-
- struct reloc_howto_struct
- {
- /* The type field has mainly a documentary use - the back end can
- do what it wants with it, though normally the back end's
- external idea of what a reloc number is stored
- in this field. For example, a PC relative word relocation
- in a coff environment has the type 023 - because that's
- what the outside world calls a R_PCRWORD reloc. */
- unsigned int type;
-
- /* The value the final relocation is shifted right by. This drops
- unwanted data from the relocation. */
- unsigned int rightshift;
-
- /* The size of the item to be relocated. This is *not* a
- power-of-two measure. To get the number of bytes operated
- on by a type of relocation, use bfd_get_reloc_size. */
- int size;
-
- /* The number of bits in the item to be relocated. This is used
- when doing overflow checking. */
- unsigned int bitsize;
-
- /* Notes that the relocation is relative to the location in the
- data section of the addend. The relocation function will
- subtract from the relocation value the address of the location
- being relocated. */
- bfd_boolean pc_relative;
-
- /* The bit position of the reloc value in the destination.
- The relocated value is left shifted by this amount. */
- unsigned int bitpos;
-
- /* What type of overflow error should be checked for when
- relocating. */
- enum complain_overflow complain_on_overflow;
-
- /* If this field is non null, then the supplied function is
- called rather than the normal function. This allows really
- strange relocation methods to be accommodated (e.g., i960 callj
- instructions). */
- bfd_reloc_status_type (*special_function)
- (bfd *, arelent *, struct bfd_symbol *, void *, asection *,
- bfd *, char **);
-
- /* The textual name of the relocation type. */
- char *name;
-
- /* Some formats record a relocation addend in the section contents
- rather than with the relocation. For ELF formats this is the
- distinction between USE_REL and USE_RELA (though the code checks
- for USE_REL == 1/0). The value of this field is TRUE if the
- addend is recorded with the section contents; when performing a
- partial link (ld -r) the section contents (the data) will be
- modified. The value of this field is FALSE if addends are
- recorded with the relocation (in arelent.addend); when performing
- a partial link the relocation will be modified.
- All relocations for all ELF USE_RELA targets should set this field
- to FALSE (values of TRUE should be looked on with suspicion).
- However, the converse is not true: not all relocations of all ELF
- USE_REL targets set this field to TRUE. Why this is so is peculiar
- to each particular target. For relocs that aren't used in partial
- links (e.g. GOT stuff) it doesn't matter what this is set to. */
- bfd_boolean partial_inplace;
-
- /* src_mask selects the part of the instruction (or data) to be used
- in the relocation sum. If the target relocations don't have an
- addend in the reloc, eg. ELF USE_REL, src_mask will normally equal
- dst_mask to extract the addend from the section contents. If
- relocations do have an addend in the reloc, eg. ELF USE_RELA, this
- field should be zero. Non-zero values for ELF USE_RELA targets are
- bogus as in those cases the value in the dst_mask part of the
- section contents should be treated as garbage. */
- bfd_vma src_mask;
-
- /* dst_mask selects which parts of the instruction (or data) are
- replaced with a relocated value. */
- bfd_vma dst_mask;
-
- /* When some formats create PC relative instructions, they leave
- the value of the pc of the place being relocated in the offset
- slot of the instruction, so that a PC relative relocation can
- be made just by adding in an ordinary offset (e.g., sun3 a.out).
- Some formats leave the displacement part of an instruction
- empty (e.g., m88k bcs); this flag signals the fact. */
- bfd_boolean pcrel_offset;
- };
-
-2.10.1.3 `The HOWTO Macro'
-..........................
-
-*Description*
-The HOWTO define is horrible and will go away.
- #define HOWTO(C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
- { (unsigned) C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC }
-
- *Description*
-And will be replaced with the totally magic way. But for the moment, we
-are compatible, so do it this way.
- #define NEWHOWTO(FUNCTION, NAME, SIZE, REL, IN) \
- HOWTO (0, 0, SIZE, 0, REL, 0, complain_overflow_dont, FUNCTION, \
- NAME, FALSE, 0, 0, IN)
-
- *Description*
-This is used to fill in an empty howto entry in an array.
- #define EMPTY_HOWTO(C) \
- HOWTO ((C), 0, 0, 0, FALSE, 0, complain_overflow_dont, NULL, \
- NULL, FALSE, 0, 0, FALSE)
-
- *Description*
-Helper routine to turn a symbol into a relocation value.
- #define HOWTO_PREPARE(relocation, symbol) \
- { \
- if (symbol != NULL) \
- { \
- if (bfd_is_com_section (symbol->section)) \
- { \
- relocation = 0; \
- } \
- else \
- { \
- relocation = symbol->value; \
- } \
- } \
- }
-
-2.10.1.4 `bfd_get_reloc_size'
-.............................
-
-*Synopsis*
- unsigned int bfd_get_reloc_size (reloc_howto_type *);
- *Description*
-For a reloc_howto_type that operates on a fixed number of bytes, this
-returns the number of bytes operated on.
-
-2.10.1.5 `arelent_chain'
-........................
-
-*Description*
-How relocs are tied together in an `asection':
- typedef struct relent_chain
- {
- arelent relent;
- struct relent_chain *next;
- }
- arelent_chain;
-
-2.10.1.6 `bfd_check_overflow'
-.............................
-
-*Synopsis*
- bfd_reloc_status_type bfd_check_overflow
- (enum complain_overflow how,
- unsigned int bitsize,
- unsigned int rightshift,
- unsigned int addrsize,
- bfd_vma relocation);
- *Description*
-Perform overflow checking on RELOCATION which has BITSIZE significant
-bits and will be shifted right by RIGHTSHIFT bits, on a machine with
-addresses containing ADDRSIZE significant bits. The result is either of
-`bfd_reloc_ok' or `bfd_reloc_overflow'.
-
-2.10.1.7 `bfd_perform_relocation'
-.................................
-
-*Synopsis*
- bfd_reloc_status_type bfd_perform_relocation
- (bfd *abfd,
- arelent *reloc_entry,
- void *data,
- asection *input_section,
- bfd *output_bfd,
- char **error_message);
- *Description*
-If OUTPUT_BFD is supplied to this function, the generated image will be
-relocatable; the relocations are copied to the output file after they
-have been changed to reflect the new state of the world. There are two
-ways of reflecting the results of partial linkage in an output file: by
-modifying the output data in place, and by modifying the relocation
-record. Some native formats (e.g., basic a.out and basic coff) have no
-way of specifying an addend in the relocation type, so the addend has
-to go in the output data. This is no big deal since in these formats
-the output data slot will always be big enough for the addend. Complex
-reloc types with addends were invented to solve just this problem. The
-ERROR_MESSAGE argument is set to an error message if this return
-`bfd_reloc_dangerous'.
-
-2.10.1.8 `bfd_install_relocation'
-.................................
-
-*Synopsis*
- bfd_reloc_status_type bfd_install_relocation
- (bfd *abfd,
- arelent *reloc_entry,
- void *data, bfd_vma data_start,
- asection *input_section,
- char **error_message);
- *Description*
-This looks remarkably like `bfd_perform_relocation', except it does not
-expect that the section contents have been filled in. I.e., it's
-suitable for use when creating, rather than applying a relocation.
-
- For now, this function should be considered reserved for the
-assembler.
-
-\1f
-File: bfd.info, Node: howto manager, Prev: typedef arelent, Up: Relocations
-
-2.10.2 The howto manager
-------------------------
-
-When an application wants to create a relocation, but doesn't know what
-the target machine might call it, it can find out by using this bit of
-code.
-
-2.10.2.1 `bfd_reloc_code_type'
-..............................
-
-*Description*
-The insides of a reloc code. The idea is that, eventually, there will
-be one enumerator for every type of relocation we ever do. Pass one of
-these values to `bfd_reloc_type_lookup', and it'll return a howto
-pointer.
-
- This does mean that the application must determine the correct
-enumerator value; you can't get a howto pointer from a random set of
-attributes.
-
- Here are the possible values for `enum bfd_reloc_code_real':
-
- -- : BFD_RELOC_64
- -- : BFD_RELOC_32
- -- : BFD_RELOC_26
- -- : BFD_RELOC_24
- -- : BFD_RELOC_16
- -- : BFD_RELOC_14
- -- : BFD_RELOC_8
- Basic absolute relocations of N bits.
-
- -- : BFD_RELOC_64_PCREL
- -- : BFD_RELOC_32_PCREL
- -- : BFD_RELOC_24_PCREL
- -- : BFD_RELOC_16_PCREL
- -- : BFD_RELOC_12_PCREL
- -- : BFD_RELOC_8_PCREL
- PC-relative relocations. Sometimes these are relative to the
- address of the relocation itself; sometimes they are relative to
- the start of the section containing the relocation. It depends on
- the specific target.
-
- The 24-bit relocation is used in some Intel 960 configurations.
-
- -- : BFD_RELOC_32_SECREL
- Section relative relocations. Some targets need this for DWARF2.
-
- -- : BFD_RELOC_32_GOT_PCREL
- -- : BFD_RELOC_16_GOT_PCREL
- -- : BFD_RELOC_8_GOT_PCREL
- -- : BFD_RELOC_32_GOTOFF
- -- : BFD_RELOC_16_GOTOFF
- -- : BFD_RELOC_LO16_GOTOFF
- -- : BFD_RELOC_HI16_GOTOFF
- -- : BFD_RELOC_HI16_S_GOTOFF
- -- : BFD_RELOC_8_GOTOFF
- -- : BFD_RELOC_64_PLT_PCREL
- -- : BFD_RELOC_32_PLT_PCREL
- -- : BFD_RELOC_24_PLT_PCREL
- -- : BFD_RELOC_16_PLT_PCREL
- -- : BFD_RELOC_8_PLT_PCREL
- -- : BFD_RELOC_64_PLTOFF
- -- : BFD_RELOC_32_PLTOFF
- -- : BFD_RELOC_16_PLTOFF
- -- : BFD_RELOC_LO16_PLTOFF
- -- : BFD_RELOC_HI16_PLTOFF
- -- : BFD_RELOC_HI16_S_PLTOFF
- -- : BFD_RELOC_8_PLTOFF
- For ELF.
-
- -- : BFD_RELOC_68K_GLOB_DAT
- -- : BFD_RELOC_68K_JMP_SLOT
- -- : BFD_RELOC_68K_RELATIVE
- Relocations used by 68K ELF.
-
- -- : BFD_RELOC_32_BASEREL
- -- : BFD_RELOC_16_BASEREL
- -- : BFD_RELOC_LO16_BASEREL
- -- : BFD_RELOC_HI16_BASEREL
- -- : BFD_RELOC_HI16_S_BASEREL
- -- : BFD_RELOC_8_BASEREL
- -- : BFD_RELOC_RVA
- Linkage-table relative.
-
- -- : BFD_RELOC_8_FFnn
- Absolute 8-bit relocation, but used to form an address like 0xFFnn.
-
- -- : BFD_RELOC_32_PCREL_S2
- -- : BFD_RELOC_16_PCREL_S2
- -- : BFD_RELOC_23_PCREL_S2
- These PC-relative relocations are stored as word displacements -
- i.e., byte displacements shifted right two bits. The 30-bit word
- displacement (<<32_PCREL_S2>> - 32 bits, shifted 2) is used on the
- SPARC. (SPARC tools generally refer to this as <<WDISP30>>.) The
- signed 16-bit displacement is used on the MIPS, and the 23-bit
- displacement is used on the Alpha.
-
- -- : BFD_RELOC_HI22
- -- : BFD_RELOC_LO10
- High 22 bits and low 10 bits of 32-bit value, placed into lower
- bits of the target word. These are used on the SPARC.
-
- -- : BFD_RELOC_GPREL16
- -- : BFD_RELOC_GPREL32
- For systems that allocate a Global Pointer register, these are
- displacements off that register. These relocation types are
- handled specially, because the value the register will have is
- decided relatively late.
-
- -- : BFD_RELOC_I960_CALLJ
- Reloc types used for i960/b.out.
-
- -- : BFD_RELOC_NONE
- -- : BFD_RELOC_SPARC_WDISP22
- -- : BFD_RELOC_SPARC22
- -- : BFD_RELOC_SPARC13
- -- : BFD_RELOC_SPARC_GOT10
- -- : BFD_RELOC_SPARC_GOT13
- -- : BFD_RELOC_SPARC_GOT22
- -- : BFD_RELOC_SPARC_PC10
- -- : BFD_RELOC_SPARC_PC22
- -- : BFD_RELOC_SPARC_WPLT30
- -- : BFD_RELOC_SPARC_COPY
- -- : BFD_RELOC_SPARC_GLOB_DAT
- -- : BFD_RELOC_SPARC_JMP_SLOT
- -- : BFD_RELOC_SPARC_RELATIVE
- -- : BFD_RELOC_SPARC_UA16
- -- : BFD_RELOC_SPARC_UA32
- -- : BFD_RELOC_SPARC_UA64
- SPARC ELF relocations. There is probably some overlap with other
- relocation types already defined.
-
- -- : BFD_RELOC_SPARC_BASE13
- -- : BFD_RELOC_SPARC_BASE22
- I think these are specific to SPARC a.out (e.g., Sun 4).
-
- -- : BFD_RELOC_SPARC_64
- -- : BFD_RELOC_SPARC_10
- -- : BFD_RELOC_SPARC_11
- -- : BFD_RELOC_SPARC_OLO10
- -- : BFD_RELOC_SPARC_HH22
- -- : BFD_RELOC_SPARC_HM10
- -- : BFD_RELOC_SPARC_LM22
- -- : BFD_RELOC_SPARC_PC_HH22
- -- : BFD_RELOC_SPARC_PC_HM10
- -- : BFD_RELOC_SPARC_PC_LM22
- -- : BFD_RELOC_SPARC_WDISP16
- -- : BFD_RELOC_SPARC_WDISP19
- -- : BFD_RELOC_SPARC_7
- -- : BFD_RELOC_SPARC_6
- -- : BFD_RELOC_SPARC_5
- -- : BFD_RELOC_SPARC_DISP64
- -- : BFD_RELOC_SPARC_PLT32
- -- : BFD_RELOC_SPARC_PLT64
- -- : BFD_RELOC_SPARC_HIX22
- -- : BFD_RELOC_SPARC_LOX10
- -- : BFD_RELOC_SPARC_H44
- -- : BFD_RELOC_SPARC_M44
- -- : BFD_RELOC_SPARC_L44
- -- : BFD_RELOC_SPARC_REGISTER
- SPARC64 relocations
-
- -- : BFD_RELOC_SPARC_REV32
- SPARC little endian relocation
-
- -- : BFD_RELOC_SPARC_TLS_GD_HI22
- -- : BFD_RELOC_SPARC_TLS_GD_LO10
- -- : BFD_RELOC_SPARC_TLS_GD_ADD
- -- : BFD_RELOC_SPARC_TLS_GD_CALL
- -- : BFD_RELOC_SPARC_TLS_LDM_HI22
- -- : BFD_RELOC_SPARC_TLS_LDM_LO10
- -- : BFD_RELOC_SPARC_TLS_LDM_ADD
- -- : BFD_RELOC_SPARC_TLS_LDM_CALL
- -- : BFD_RELOC_SPARC_TLS_LDO_HIX22
- -- : BFD_RELOC_SPARC_TLS_LDO_LOX10
- -- : BFD_RELOC_SPARC_TLS_LDO_ADD
- -- : BFD_RELOC_SPARC_TLS_IE_HI22
- -- : BFD_RELOC_SPARC_TLS_IE_LO10
- -- : BFD_RELOC_SPARC_TLS_IE_LD
- -- : BFD_RELOC_SPARC_TLS_IE_LDX
- -- : BFD_RELOC_SPARC_TLS_IE_ADD
- -- : BFD_RELOC_SPARC_TLS_LE_HIX22
- -- : BFD_RELOC_SPARC_TLS_LE_LOX10
- -- : BFD_RELOC_SPARC_TLS_DTPMOD32
- -- : BFD_RELOC_SPARC_TLS_DTPMOD64
- -- : BFD_RELOC_SPARC_TLS_DTPOFF32
- -- : BFD_RELOC_SPARC_TLS_DTPOFF64
- -- : BFD_RELOC_SPARC_TLS_TPOFF32
- -- : BFD_RELOC_SPARC_TLS_TPOFF64
- SPARC TLS relocations
-
- -- : BFD_RELOC_SPU_IMM7
- -- : BFD_RELOC_SPU_IMM8
- -- : BFD_RELOC_SPU_IMM10
- -- : BFD_RELOC_SPU_IMM10W
- -- : BFD_RELOC_SPU_IMM16
- -- : BFD_RELOC_SPU_IMM16W
- -- : BFD_RELOC_SPU_IMM18
- -- : BFD_RELOC_SPU_PCREL9a
- -- : BFD_RELOC_SPU_PCREL9b
- -- : BFD_RELOC_SPU_PCREL16
- -- : BFD_RELOC_SPU_LO16
- -- : BFD_RELOC_SPU_HI16
- -- : BFD_RELOC_SPU_PPU32
- -- : BFD_RELOC_SPU_PPU64
- SPU Relocations.
-
- -- : BFD_RELOC_ALPHA_GPDISP_HI16
- Alpha ECOFF and ELF relocations. Some of these treat the symbol or
- "addend" in some special way. For GPDISP_HI16 ("gpdisp")
- relocations, the symbol is ignored when writing; when reading, it
- will be the absolute section symbol. The addend is the
- displacement in bytes of the "lda" instruction from the "ldah"
- instruction (which is at the address of this reloc).
-
- -- : BFD_RELOC_ALPHA_GPDISP_LO16
- For GPDISP_LO16 ("ignore") relocations, the symbol is handled as
- with GPDISP_HI16 relocs. The addend is ignored when writing the
- relocations out, and is filled in with the file's GP value on
- reading, for convenience.
-
- -- : BFD_RELOC_ALPHA_GPDISP
- The ELF GPDISP relocation is exactly the same as the GPDISP_HI16
- relocation except that there is no accompanying GPDISP_LO16
- relocation.
-
- -- : BFD_RELOC_ALPHA_LITERAL
- -- : BFD_RELOC_ALPHA_ELF_LITERAL
- -- : BFD_RELOC_ALPHA_LITUSE
- The Alpha LITERAL/LITUSE relocs are produced by a symbol reference;
- the assembler turns it into a LDQ instruction to load the address
- of the symbol, and then fills in a register in the real
- instruction.
-
- The LITERAL reloc, at the LDQ instruction, refers to the .lita
- section symbol. The addend is ignored when writing, but is filled
- in with the file's GP value on reading, for convenience, as with
- the GPDISP_LO16 reloc.
-
- The ELF_LITERAL reloc is somewhere between 16_GOTOFF and
- GPDISP_LO16. It should refer to the symbol to be referenced, as
- with 16_GOTOFF, but it generates output not based on the position
- within the .got section, but relative to the GP value chosen for
- the file during the final link stage.
-
- The LITUSE reloc, on the instruction using the loaded address,
- gives information to the linker that it might be able to use to
- optimize away some literal section references. The symbol is
- ignored (read as the absolute section symbol), and the "addend"
- indicates the type of instruction using the register: 1 - "memory"
- fmt insn 2 - byte-manipulation (byte offset reg) 3 - jsr (target
- of branch)
-
- -- : BFD_RELOC_ALPHA_HINT
- The HINT relocation indicates a value that should be filled into
- the "hint" field of a jmp/jsr/ret instruction, for possible branch-
- prediction logic which may be provided on some processors.
-
- -- : BFD_RELOC_ALPHA_LINKAGE
- The LINKAGE relocation outputs a linkage pair in the object file,
- which is filled by the linker.
-
- -- : BFD_RELOC_ALPHA_CODEADDR
- The CODEADDR relocation outputs a STO_CA in the object file, which
- is filled by the linker.
-
- -- : BFD_RELOC_ALPHA_GPREL_HI16
- -- : BFD_RELOC_ALPHA_GPREL_LO16
- The GPREL_HI/LO relocations together form a 32-bit offset from the
- GP register.
-
- -- : BFD_RELOC_ALPHA_BRSGP
- Like BFD_RELOC_23_PCREL_S2, except that the source and target must
- share a common GP, and the target address is adjusted for
- STO_ALPHA_STD_GPLOAD.
-
- -- : BFD_RELOC_ALPHA_TLSGD
- -- : BFD_RELOC_ALPHA_TLSLDM
- -- : BFD_RELOC_ALPHA_DTPMOD64
- -- : BFD_RELOC_ALPHA_GOTDTPREL16
- -- : BFD_RELOC_ALPHA_DTPREL64
- -- : BFD_RELOC_ALPHA_DTPREL_HI16
- -- : BFD_RELOC_ALPHA_DTPREL_LO16
- -- : BFD_RELOC_ALPHA_DTPREL16
- -- : BFD_RELOC_ALPHA_GOTTPREL16
- -- : BFD_RELOC_ALPHA_TPREL64
- -- : BFD_RELOC_ALPHA_TPREL_HI16
- -- : BFD_RELOC_ALPHA_TPREL_LO16
- -- : BFD_RELOC_ALPHA_TPREL16
- Alpha thread-local storage relocations.
-
- -- : BFD_RELOC_MIPS_JMP
- Bits 27..2 of the relocation address shifted right 2 bits; simple
- reloc otherwise.
-
- -- : BFD_RELOC_MIPS16_JMP
- The MIPS16 jump instruction.
-
- -- : BFD_RELOC_MIPS16_GPREL
- MIPS16 GP relative reloc.
-
- -- : BFD_RELOC_HI16
- High 16 bits of 32-bit value; simple reloc.
-
- -- : BFD_RELOC_HI16_S
- High 16 bits of 32-bit value but the low 16 bits will be sign
- extended and added to form the final result. If the low 16 bits
- form a negative number, we need to add one to the high value to
- compensate for the borrow when the low bits are added.
-
- -- : BFD_RELOC_LO16
- Low 16 bits.
-
- -- : BFD_RELOC_HI16_PCREL
- High 16 bits of 32-bit pc-relative value
-
- -- : BFD_RELOC_HI16_S_PCREL
- High 16 bits of 32-bit pc-relative value, adjusted
-
- -- : BFD_RELOC_LO16_PCREL
- Low 16 bits of pc-relative value
-
- -- : BFD_RELOC_MIPS16_HI16
- MIPS16 high 16 bits of 32-bit value.
-
- -- : BFD_RELOC_MIPS16_HI16_S
- MIPS16 high 16 bits of 32-bit value but the low 16 bits will be
- sign extended and added to form the final result. If the low 16
- bits form a negative number, we need to add one to the high value
- to compensate for the borrow when the low bits are added.
-
- -- : BFD_RELOC_MIPS16_LO16
- MIPS16 low 16 bits.
-
- -- : BFD_RELOC_MIPS_LITERAL
- Relocation against a MIPS literal section.
-
- -- : BFD_RELOC_MIPS_GOT16
- -- : BFD_RELOC_MIPS_CALL16
- -- : BFD_RELOC_MIPS_GOT_HI16
- -- : BFD_RELOC_MIPS_GOT_LO16
- -- : BFD_RELOC_MIPS_CALL_HI16
- -- : BFD_RELOC_MIPS_CALL_LO16
- -- : BFD_RELOC_MIPS_SUB
- -- : BFD_RELOC_MIPS_GOT_PAGE
- -- : BFD_RELOC_MIPS_GOT_OFST
- -- : BFD_RELOC_MIPS_GOT_DISP
- -- : BFD_RELOC_MIPS_SHIFT5
- -- : BFD_RELOC_MIPS_SHIFT6
- -- : BFD_RELOC_MIPS_INSERT_A
- -- : BFD_RELOC_MIPS_INSERT_B
- -- : BFD_RELOC_MIPS_DELETE
- -- : BFD_RELOC_MIPS_HIGHEST
- -- : BFD_RELOC_MIPS_HIGHER
- -- : BFD_RELOC_MIPS_SCN_DISP
- -- : BFD_RELOC_MIPS_REL16
- -- : BFD_RELOC_MIPS_RELGOT
- -- : BFD_RELOC_MIPS_JALR
- -- : BFD_RELOC_MIPS_TLS_DTPMOD32
- -- : BFD_RELOC_MIPS_TLS_DTPREL32
- -- : BFD_RELOC_MIPS_TLS_DTPMOD64
- -- : BFD_RELOC_MIPS_TLS_DTPREL64
- -- : BFD_RELOC_MIPS_TLS_GD
- -- : BFD_RELOC_MIPS_TLS_LDM
- -- : BFD_RELOC_MIPS_TLS_DTPREL_HI16
- -- : BFD_RELOC_MIPS_TLS_DTPREL_LO16
- -- : BFD_RELOC_MIPS_TLS_GOTTPREL
- -- : BFD_RELOC_MIPS_TLS_TPREL32
- -- : BFD_RELOC_MIPS_TLS_TPREL64
- -- : BFD_RELOC_MIPS_TLS_TPREL_HI16
- -- : BFD_RELOC_MIPS_TLS_TPREL_LO16
- MIPS ELF relocations.
-
- -- : BFD_RELOC_MIPS_COPY
- -- : BFD_RELOC_MIPS_JUMP_SLOT
- MIPS ELF relocations (VxWorks extensions).
-
- -- : BFD_RELOC_FRV_LABEL16
- -- : BFD_RELOC_FRV_LABEL24
- -- : BFD_RELOC_FRV_LO16
- -- : BFD_RELOC_FRV_HI16
- -- : BFD_RELOC_FRV_GPREL12
- -- : BFD_RELOC_FRV_GPRELU12
- -- : BFD_RELOC_FRV_GPREL32
- -- : BFD_RELOC_FRV_GPRELHI
- -- : BFD_RELOC_FRV_GPRELLO
- -- : BFD_RELOC_FRV_GOT12
- -- : BFD_RELOC_FRV_GOTHI
- -- : BFD_RELOC_FRV_GOTLO
- -- : BFD_RELOC_FRV_FUNCDESC
- -- : BFD_RELOC_FRV_FUNCDESC_GOT12
- -- : BFD_RELOC_FRV_FUNCDESC_GOTHI
- -- : BFD_RELOC_FRV_FUNCDESC_GOTLO
- -- : BFD_RELOC_FRV_FUNCDESC_VALUE
- -- : BFD_RELOC_FRV_FUNCDESC_GOTOFF12
- -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFHI
- -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFLO
- -- : BFD_RELOC_FRV_GOTOFF12
- -- : BFD_RELOC_FRV_GOTOFFHI
- -- : BFD_RELOC_FRV_GOTOFFLO
- -- : BFD_RELOC_FRV_GETTLSOFF
- -- : BFD_RELOC_FRV_TLSDESC_VALUE
- -- : BFD_RELOC_FRV_GOTTLSDESC12
- -- : BFD_RELOC_FRV_GOTTLSDESCHI
- -- : BFD_RELOC_FRV_GOTTLSDESCLO
- -- : BFD_RELOC_FRV_TLSMOFF12
- -- : BFD_RELOC_FRV_TLSMOFFHI
- -- : BFD_RELOC_FRV_TLSMOFFLO
- -- : BFD_RELOC_FRV_GOTTLSOFF12
- -- : BFD_RELOC_FRV_GOTTLSOFFHI
- -- : BFD_RELOC_FRV_GOTTLSOFFLO
- -- : BFD_RELOC_FRV_TLSOFF
- -- : BFD_RELOC_FRV_TLSDESC_RELAX
- -- : BFD_RELOC_FRV_GETTLSOFF_RELAX
- -- : BFD_RELOC_FRV_TLSOFF_RELAX
- -- : BFD_RELOC_FRV_TLSMOFF
- Fujitsu Frv Relocations.
-
- -- : BFD_RELOC_MN10300_GOTOFF24
- This is a 24bit GOT-relative reloc for the mn10300.
-
- -- : BFD_RELOC_MN10300_GOT32
- This is a 32bit GOT-relative reloc for the mn10300, offset by two
- bytes in the instruction.
-
- -- : BFD_RELOC_MN10300_GOT24
- This is a 24bit GOT-relative reloc for the mn10300, offset by two
- bytes in the instruction.
-
- -- : BFD_RELOC_MN10300_GOT16
- This is a 16bit GOT-relative reloc for the mn10300, offset by two
- bytes in the instruction.
-
- -- : BFD_RELOC_MN10300_COPY
- Copy symbol at runtime.
-
- -- : BFD_RELOC_MN10300_GLOB_DAT
- Create GOT entry.
-
- -- : BFD_RELOC_MN10300_JMP_SLOT
- Create PLT entry.
-
- -- : BFD_RELOC_MN10300_RELATIVE
- Adjust by program base.
-
- -- : BFD_RELOC_386_GOT32
- -- : BFD_RELOC_386_PLT32
- -- : BFD_RELOC_386_COPY
- -- : BFD_RELOC_386_GLOB_DAT
- -- : BFD_RELOC_386_JUMP_SLOT
- -- : BFD_RELOC_386_RELATIVE
- -- : BFD_RELOC_386_GOTOFF
- -- : BFD_RELOC_386_GOTPC
- -- : BFD_RELOC_386_TLS_TPOFF
- -- : BFD_RELOC_386_TLS_IE
- -- : BFD_RELOC_386_TLS_GOTIE
- -- : BFD_RELOC_386_TLS_LE
- -- : BFD_RELOC_386_TLS_GD
- -- : BFD_RELOC_386_TLS_LDM
- -- : BFD_RELOC_386_TLS_LDO_32
- -- : BFD_RELOC_386_TLS_IE_32
- -- : BFD_RELOC_386_TLS_LE_32
- -- : BFD_RELOC_386_TLS_DTPMOD32
- -- : BFD_RELOC_386_TLS_DTPOFF32
- -- : BFD_RELOC_386_TLS_TPOFF32
- -- : BFD_RELOC_386_TLS_GOTDESC
- -- : BFD_RELOC_386_TLS_DESC_CALL
- -- : BFD_RELOC_386_TLS_DESC
- i386/elf relocations
-
- -- : BFD_RELOC_X86_64_GOT32
- -- : BFD_RELOC_X86_64_PLT32
- -- : BFD_RELOC_X86_64_COPY
- -- : BFD_RELOC_X86_64_GLOB_DAT
- -- : BFD_RELOC_X86_64_JUMP_SLOT
- -- : BFD_RELOC_X86_64_RELATIVE
- -- : BFD_RELOC_X86_64_GOTPCREL
- -- : BFD_RELOC_X86_64_32S
- -- : BFD_RELOC_X86_64_DTPMOD64
- -- : BFD_RELOC_X86_64_DTPOFF64
- -- : BFD_RELOC_X86_64_TPOFF64
- -- : BFD_RELOC_X86_64_TLSGD
- -- : BFD_RELOC_X86_64_TLSLD
- -- : BFD_RELOC_X86_64_DTPOFF32
- -- : BFD_RELOC_X86_64_GOTTPOFF
- -- : BFD_RELOC_X86_64_TPOFF32
- -- : BFD_RELOC_X86_64_GOTOFF64
- -- : BFD_RELOC_X86_64_GOTPC32
- -- : BFD_RELOC_X86_64_GOT64
- -- : BFD_RELOC_X86_64_GOTPCREL64
- -- : BFD_RELOC_X86_64_GOTPC64
- -- : BFD_RELOC_X86_64_GOTPLT64
- -- : BFD_RELOC_X86_64_PLTOFF64
- -- : BFD_RELOC_X86_64_GOTPC32_TLSDESC
- -- : BFD_RELOC_X86_64_TLSDESC_CALL
- -- : BFD_RELOC_X86_64_TLSDESC
- x86-64/elf relocations
-
- -- : BFD_RELOC_NS32K_IMM_8
- -- : BFD_RELOC_NS32K_IMM_16
- -- : BFD_RELOC_NS32K_IMM_32
- -- : BFD_RELOC_NS32K_IMM_8_PCREL
- -- : BFD_RELOC_NS32K_IMM_16_PCREL
- -- : BFD_RELOC_NS32K_IMM_32_PCREL
- -- : BFD_RELOC_NS32K_DISP_8
- -- : BFD_RELOC_NS32K_DISP_16
- -- : BFD_RELOC_NS32K_DISP_32
- -- : BFD_RELOC_NS32K_DISP_8_PCREL
- -- : BFD_RELOC_NS32K_DISP_16_PCREL
- -- : BFD_RELOC_NS32K_DISP_32_PCREL
- ns32k relocations
-
- -- : BFD_RELOC_PDP11_DISP_8_PCREL
- -- : BFD_RELOC_PDP11_DISP_6_PCREL
- PDP11 relocations
-
- -- : BFD_RELOC_PJ_CODE_HI16
- -- : BFD_RELOC_PJ_CODE_LO16
- -- : BFD_RELOC_PJ_CODE_DIR16
- -- : BFD_RELOC_PJ_CODE_DIR32
- -- : BFD_RELOC_PJ_CODE_REL16
- -- : BFD_RELOC_PJ_CODE_REL32
- Picojava relocs. Not all of these appear in object files.
-
- -- : BFD_RELOC_PPC_B26
- -- : BFD_RELOC_PPC_BA26
- -- : BFD_RELOC_PPC_TOC16
- -- : BFD_RELOC_PPC_B16
- -- : BFD_RELOC_PPC_B16_BRTAKEN
- -- : BFD_RELOC_PPC_B16_BRNTAKEN
- -- : BFD_RELOC_PPC_BA16
- -- : BFD_RELOC_PPC_BA16_BRTAKEN
- -- : BFD_RELOC_PPC_BA16_BRNTAKEN
- -- : BFD_RELOC_PPC_COPY
- -- : BFD_RELOC_PPC_GLOB_DAT
- -- : BFD_RELOC_PPC_JMP_SLOT
- -- : BFD_RELOC_PPC_RELATIVE
- -- : BFD_RELOC_PPC_LOCAL24PC
- -- : BFD_RELOC_PPC_EMB_NADDR32
- -- : BFD_RELOC_PPC_EMB_NADDR16
- -- : BFD_RELOC_PPC_EMB_NADDR16_LO
- -- : BFD_RELOC_PPC_EMB_NADDR16_HI
- -- : BFD_RELOC_PPC_EMB_NADDR16_HA
- -- : BFD_RELOC_PPC_EMB_SDAI16
- -- : BFD_RELOC_PPC_EMB_SDA2I16
- -- : BFD_RELOC_PPC_EMB_SDA2REL
- -- : BFD_RELOC_PPC_EMB_SDA21
- -- : BFD_RELOC_PPC_EMB_MRKREF
- -- : BFD_RELOC_PPC_EMB_RELSEC16
- -- : BFD_RELOC_PPC_EMB_RELST_LO
- -- : BFD_RELOC_PPC_EMB_RELST_HI
- -- : BFD_RELOC_PPC_EMB_RELST_HA
- -- : BFD_RELOC_PPC_EMB_BIT_FLD
- -- : BFD_RELOC_PPC_EMB_RELSDA
- -- : BFD_RELOC_PPC64_HIGHER
- -- : BFD_RELOC_PPC64_HIGHER_S
- -- : BFD_RELOC_PPC64_HIGHEST
- -- : BFD_RELOC_PPC64_HIGHEST_S
- -- : BFD_RELOC_PPC64_TOC16_LO
- -- : BFD_RELOC_PPC64_TOC16_HI
- -- : BFD_RELOC_PPC64_TOC16_HA
- -- : BFD_RELOC_PPC64_TOC
- -- : BFD_RELOC_PPC64_PLTGOT16
- -- : BFD_RELOC_PPC64_PLTGOT16_LO
- -- : BFD_RELOC_PPC64_PLTGOT16_HI
- -- : BFD_RELOC_PPC64_PLTGOT16_HA
- -- : BFD_RELOC_PPC64_ADDR16_DS
- -- : BFD_RELOC_PPC64_ADDR16_LO_DS
- -- : BFD_RELOC_PPC64_GOT16_DS
- -- : BFD_RELOC_PPC64_GOT16_LO_DS
- -- : BFD_RELOC_PPC64_PLT16_LO_DS
- -- : BFD_RELOC_PPC64_SECTOFF_DS
- -- : BFD_RELOC_PPC64_SECTOFF_LO_DS
- -- : BFD_RELOC_PPC64_TOC16_DS
- -- : BFD_RELOC_PPC64_TOC16_LO_DS
- -- : BFD_RELOC_PPC64_PLTGOT16_DS
- -- : BFD_RELOC_PPC64_PLTGOT16_LO_DS
- Power(rs6000) and PowerPC relocations.
-
- -- : BFD_RELOC_PPC_TLS
- -- : BFD_RELOC_PPC_DTPMOD
- -- : BFD_RELOC_PPC_TPREL16
- -- : BFD_RELOC_PPC_TPREL16_LO
- -- : BFD_RELOC_PPC_TPREL16_HI
- -- : BFD_RELOC_PPC_TPREL16_HA
- -- : BFD_RELOC_PPC_TPREL
- -- : BFD_RELOC_PPC_DTPREL16
- -- : BFD_RELOC_PPC_DTPREL16_LO
- -- : BFD_RELOC_PPC_DTPREL16_HI
- -- : BFD_RELOC_PPC_DTPREL16_HA
- -- : BFD_RELOC_PPC_DTPREL
- -- : BFD_RELOC_PPC_GOT_TLSGD16
- -- : BFD_RELOC_PPC_GOT_TLSGD16_LO
- -- : BFD_RELOC_PPC_GOT_TLSGD16_HI
- -- : BFD_RELOC_PPC_GOT_TLSGD16_HA
- -- : BFD_RELOC_PPC_GOT_TLSLD16
- -- : BFD_RELOC_PPC_GOT_TLSLD16_LO
- -- : BFD_RELOC_PPC_GOT_TLSLD16_HI
- -- : BFD_RELOC_PPC_GOT_TLSLD16_HA
- -- : BFD_RELOC_PPC_GOT_TPREL16
- -- : BFD_RELOC_PPC_GOT_TPREL16_LO
- -- : BFD_RELOC_PPC_GOT_TPREL16_HI
- -- : BFD_RELOC_PPC_GOT_TPREL16_HA
- -- : BFD_RELOC_PPC_GOT_DTPREL16
- -- : BFD_RELOC_PPC_GOT_DTPREL16_LO
- -- : BFD_RELOC_PPC_GOT_DTPREL16_HI
- -- : BFD_RELOC_PPC_GOT_DTPREL16_HA
- -- : BFD_RELOC_PPC64_TPREL16_DS
- -- : BFD_RELOC_PPC64_TPREL16_LO_DS
- -- : BFD_RELOC_PPC64_TPREL16_HIGHER
- -- : BFD_RELOC_PPC64_TPREL16_HIGHERA
- -- : BFD_RELOC_PPC64_TPREL16_HIGHEST
- -- : BFD_RELOC_PPC64_TPREL16_HIGHESTA
- -- : BFD_RELOC_PPC64_DTPREL16_DS
- -- : BFD_RELOC_PPC64_DTPREL16_LO_DS
- -- : BFD_RELOC_PPC64_DTPREL16_HIGHER
- -- : BFD_RELOC_PPC64_DTPREL16_HIGHERA
- -- : BFD_RELOC_PPC64_DTPREL16_HIGHEST
- -- : BFD_RELOC_PPC64_DTPREL16_HIGHESTA
- PowerPC and PowerPC64 thread-local storage relocations.
-
- -- : BFD_RELOC_I370_D12
- IBM 370/390 relocations
-
- -- : BFD_RELOC_CTOR
- The type of reloc used to build a constructor table - at the moment
- probably a 32 bit wide absolute relocation, but the target can
- choose. It generally does map to one of the other relocation
- types.
-
- -- : BFD_RELOC_ARM_PCREL_BRANCH
- ARM 26 bit pc-relative branch. The lowest two bits must be zero
- and are not stored in the instruction.
-
- -- : BFD_RELOC_ARM_PCREL_BLX
- ARM 26 bit pc-relative branch. The lowest bit must be zero and is
- not stored in the instruction. The 2nd lowest bit comes from a 1
- bit field in the instruction.
-
- -- : BFD_RELOC_THUMB_PCREL_BLX
- Thumb 22 bit pc-relative branch. The lowest bit must be zero and
- is not stored in the instruction. The 2nd lowest bit comes from a
- 1 bit field in the instruction.
-
- -- : BFD_RELOC_ARM_PCREL_CALL
- ARM 26-bit pc-relative branch for an unconditional BL or BLX
- instruction.
-
- -- : BFD_RELOC_ARM_PCREL_JUMP
- ARM 26-bit pc-relative branch for B or conditional BL instruction.
-
- -- : BFD_RELOC_THUMB_PCREL_BRANCH7
- -- : BFD_RELOC_THUMB_PCREL_BRANCH9
- -- : BFD_RELOC_THUMB_PCREL_BRANCH12
- -- : BFD_RELOC_THUMB_PCREL_BRANCH20
- -- : BFD_RELOC_THUMB_PCREL_BRANCH23
- -- : BFD_RELOC_THUMB_PCREL_BRANCH25
- Thumb 7-, 9-, 12-, 20-, 23-, and 25-bit pc-relative branches. The
- lowest bit must be zero and is not stored in the instruction.
- Note that the corresponding ELF R_ARM_THM_JUMPnn constant has an
- "nn" one smaller in all cases. Note further that BRANCH23
- corresponds to R_ARM_THM_CALL.
-
- -- : BFD_RELOC_ARM_OFFSET_IMM
- 12-bit immediate offset, used in ARM-format ldr and str
- instructions.
-
- -- : BFD_RELOC_ARM_THUMB_OFFSET
- 5-bit immediate offset, used in Thumb-format ldr and str
- instructions.
-
- -- : BFD_RELOC_ARM_TARGET1
- Pc-relative or absolute relocation depending on target. Used for
- entries in .init_array sections.
-
- -- : BFD_RELOC_ARM_ROSEGREL32
- Read-only segment base relative address.
-
- -- : BFD_RELOC_ARM_SBREL32
- Data segment base relative address.
-
- -- : BFD_RELOC_ARM_TARGET2
- This reloc is used for references to RTTI data from exception
- handling tables. The actual definition depends on the target. It
- may be a pc-relative or some form of GOT-indirect relocation.
-
- -- : BFD_RELOC_ARM_PREL31
- 31-bit PC relative address.
-
- -- : BFD_RELOC_ARM_MOVW
- -- : BFD_RELOC_ARM_MOVT
- -- : BFD_RELOC_ARM_MOVW_PCREL
- -- : BFD_RELOC_ARM_MOVT_PCREL
- -- : BFD_RELOC_ARM_THUMB_MOVW
- -- : BFD_RELOC_ARM_THUMB_MOVT
- -- : BFD_RELOC_ARM_THUMB_MOVW_PCREL
- -- : BFD_RELOC_ARM_THUMB_MOVT_PCREL
- Low and High halfword relocations for MOVW and MOVT instructions.
-
- -- : BFD_RELOC_ARM_JUMP_SLOT
- -- : BFD_RELOC_ARM_GLOB_DAT
- -- : BFD_RELOC_ARM_GOT32
- -- : BFD_RELOC_ARM_PLT32
- -- : BFD_RELOC_ARM_RELATIVE
- -- : BFD_RELOC_ARM_GOTOFF
- -- : BFD_RELOC_ARM_GOTPC
- Relocations for setting up GOTs and PLTs for shared libraries.
-
- -- : BFD_RELOC_ARM_TLS_GD32
- -- : BFD_RELOC_ARM_TLS_LDO32
- -- : BFD_RELOC_ARM_TLS_LDM32
- -- : BFD_RELOC_ARM_TLS_DTPOFF32
- -- : BFD_RELOC_ARM_TLS_DTPMOD32
- -- : BFD_RELOC_ARM_TLS_TPOFF32
- -- : BFD_RELOC_ARM_TLS_IE32
- -- : BFD_RELOC_ARM_TLS_LE32
- ARM thread-local storage relocations.
-
- -- : BFD_RELOC_ARM_ALU_PC_G0_NC
- -- : BFD_RELOC_ARM_ALU_PC_G0
- -- : BFD_RELOC_ARM_ALU_PC_G1_NC
- -- : BFD_RELOC_ARM_ALU_PC_G1
- -- : BFD_RELOC_ARM_ALU_PC_G2
- -- : BFD_RELOC_ARM_LDR_PC_G0
- -- : BFD_RELOC_ARM_LDR_PC_G1
- -- : BFD_RELOC_ARM_LDR_PC_G2
- -- : BFD_RELOC_ARM_LDRS_PC_G0
- -- : BFD_RELOC_ARM_LDRS_PC_G1
- -- : BFD_RELOC_ARM_LDRS_PC_G2
- -- : BFD_RELOC_ARM_LDC_PC_G0
- -- : BFD_RELOC_ARM_LDC_PC_G1
- -- : BFD_RELOC_ARM_LDC_PC_G2
- -- : BFD_RELOC_ARM_ALU_SB_G0_NC
- -- : BFD_RELOC_ARM_ALU_SB_G0
- -- : BFD_RELOC_ARM_ALU_SB_G1_NC
- -- : BFD_RELOC_ARM_ALU_SB_G1
- -- : BFD_RELOC_ARM_ALU_SB_G2
- -- : BFD_RELOC_ARM_LDR_SB_G0
- -- : BFD_RELOC_ARM_LDR_SB_G1
- -- : BFD_RELOC_ARM_LDR_SB_G2
- -- : BFD_RELOC_ARM_LDRS_SB_G0
- -- : BFD_RELOC_ARM_LDRS_SB_G1
- -- : BFD_RELOC_ARM_LDRS_SB_G2
- -- : BFD_RELOC_ARM_LDC_SB_G0
- -- : BFD_RELOC_ARM_LDC_SB_G1
- -- : BFD_RELOC_ARM_LDC_SB_G2
- ARM group relocations.
-
- -- : BFD_RELOC_ARM_IMMEDIATE
- -- : BFD_RELOC_ARM_ADRL_IMMEDIATE
- -- : BFD_RELOC_ARM_T32_IMMEDIATE
- -- : BFD_RELOC_ARM_T32_ADD_IMM
- -- : BFD_RELOC_ARM_T32_IMM12
- -- : BFD_RELOC_ARM_T32_ADD_PC12
- -- : BFD_RELOC_ARM_SHIFT_IMM
- -- : BFD_RELOC_ARM_SMC
- -- : BFD_RELOC_ARM_SWI
- -- : BFD_RELOC_ARM_MULTI
- -- : BFD_RELOC_ARM_CP_OFF_IMM
- -- : BFD_RELOC_ARM_CP_OFF_IMM_S2
- -- : BFD_RELOC_ARM_T32_CP_OFF_IMM
- -- : BFD_RELOC_ARM_T32_CP_OFF_IMM_S2
- -- : BFD_RELOC_ARM_ADR_IMM
- -- : BFD_RELOC_ARM_LDR_IMM
- -- : BFD_RELOC_ARM_LITERAL
- -- : BFD_RELOC_ARM_IN_POOL
- -- : BFD_RELOC_ARM_OFFSET_IMM8
- -- : BFD_RELOC_ARM_T32_OFFSET_U8
- -- : BFD_RELOC_ARM_T32_OFFSET_IMM
- -- : BFD_RELOC_ARM_HWLITERAL
- -- : BFD_RELOC_ARM_THUMB_ADD
- -- : BFD_RELOC_ARM_THUMB_IMM
- -- : BFD_RELOC_ARM_THUMB_SHIFT
- These relocs are only used within the ARM assembler. They are not
- (at present) written to any object files.
-
- -- : BFD_RELOC_SH_PCDISP8BY2
- -- : BFD_RELOC_SH_PCDISP12BY2
- -- : BFD_RELOC_SH_IMM3
- -- : BFD_RELOC_SH_IMM3U
- -- : BFD_RELOC_SH_DISP12
- -- : BFD_RELOC_SH_DISP12BY2
- -- : BFD_RELOC_SH_DISP12BY4
- -- : BFD_RELOC_SH_DISP12BY8
- -- : BFD_RELOC_SH_DISP20
- -- : BFD_RELOC_SH_DISP20BY8
- -- : BFD_RELOC_SH_IMM4
- -- : BFD_RELOC_SH_IMM4BY2
- -- : BFD_RELOC_SH_IMM4BY4
- -- : BFD_RELOC_SH_IMM8
- -- : BFD_RELOC_SH_IMM8BY2
- -- : BFD_RELOC_SH_IMM8BY4
- -- : BFD_RELOC_SH_PCRELIMM8BY2
- -- : BFD_RELOC_SH_PCRELIMM8BY4
- -- : BFD_RELOC_SH_SWITCH16
- -- : BFD_RELOC_SH_SWITCH32
- -- : BFD_RELOC_SH_USES
- -- : BFD_RELOC_SH_COUNT
- -- : BFD_RELOC_SH_ALIGN
- -- : BFD_RELOC_SH_CODE
- -- : BFD_RELOC_SH_DATA
- -- : BFD_RELOC_SH_LABEL
- -- : BFD_RELOC_SH_LOOP_START
- -- : BFD_RELOC_SH_LOOP_END
- -- : BFD_RELOC_SH_COPY
- -- : BFD_RELOC_SH_GLOB_DAT
- -- : BFD_RELOC_SH_JMP_SLOT
- -- : BFD_RELOC_SH_RELATIVE
- -- : BFD_RELOC_SH_GOTPC
- -- : BFD_RELOC_SH_GOT_LOW16
- -- : BFD_RELOC_SH_GOT_MEDLOW16
- -- : BFD_RELOC_SH_GOT_MEDHI16
- -- : BFD_RELOC_SH_GOT_HI16
- -- : BFD_RELOC_SH_GOTPLT_LOW16
- -- : BFD_RELOC_SH_GOTPLT_MEDLOW16
- -- : BFD_RELOC_SH_GOTPLT_MEDHI16
- -- : BFD_RELOC_SH_GOTPLT_HI16
- -- : BFD_RELOC_SH_PLT_LOW16
- -- : BFD_RELOC_SH_PLT_MEDLOW16
- -- : BFD_RELOC_SH_PLT_MEDHI16
- -- : BFD_RELOC_SH_PLT_HI16
- -- : BFD_RELOC_SH_GOTOFF_LOW16
- -- : BFD_RELOC_SH_GOTOFF_MEDLOW16
- -- : BFD_RELOC_SH_GOTOFF_MEDHI16
- -- : BFD_RELOC_SH_GOTOFF_HI16
- -- : BFD_RELOC_SH_GOTPC_LOW16
- -- : BFD_RELOC_SH_GOTPC_MEDLOW16
- -- : BFD_RELOC_SH_GOTPC_MEDHI16
- -- : BFD_RELOC_SH_GOTPC_HI16
- -- : BFD_RELOC_SH_COPY64
- -- : BFD_RELOC_SH_GLOB_DAT64
- -- : BFD_RELOC_SH_JMP_SLOT64
- -- : BFD_RELOC_SH_RELATIVE64
- -- : BFD_RELOC_SH_GOT10BY4
- -- : BFD_RELOC_SH_GOT10BY8
- -- : BFD_RELOC_SH_GOTPLT10BY4
- -- : BFD_RELOC_SH_GOTPLT10BY8
- -- : BFD_RELOC_SH_GOTPLT32
- -- : BFD_RELOC_SH_SHMEDIA_CODE
- -- : BFD_RELOC_SH_IMMU5
- -- : BFD_RELOC_SH_IMMS6
- -- : BFD_RELOC_SH_IMMS6BY32
- -- : BFD_RELOC_SH_IMMU6
- -- : BFD_RELOC_SH_IMMS10
- -- : BFD_RELOC_SH_IMMS10BY2
- -- : BFD_RELOC_SH_IMMS10BY4
- -- : BFD_RELOC_SH_IMMS10BY8
- -- : BFD_RELOC_SH_IMMS16
- -- : BFD_RELOC_SH_IMMU16
- -- : BFD_RELOC_SH_IMM_LOW16
- -- : BFD_RELOC_SH_IMM_LOW16_PCREL
- -- : BFD_RELOC_SH_IMM_MEDLOW16
- -- : BFD_RELOC_SH_IMM_MEDLOW16_PCREL
- -- : BFD_RELOC_SH_IMM_MEDHI16
- -- : BFD_RELOC_SH_IMM_MEDHI16_PCREL
- -- : BFD_RELOC_SH_IMM_HI16
- -- : BFD_RELOC_SH_IMM_HI16_PCREL
- -- : BFD_RELOC_SH_PT_16
- -- : BFD_RELOC_SH_TLS_GD_32
- -- : BFD_RELOC_SH_TLS_LD_32
- -- : BFD_RELOC_SH_TLS_LDO_32
- -- : BFD_RELOC_SH_TLS_IE_32
- -- : BFD_RELOC_SH_TLS_LE_32
- -- : BFD_RELOC_SH_TLS_DTPMOD32
- -- : BFD_RELOC_SH_TLS_DTPOFF32
- -- : BFD_RELOC_SH_TLS_TPOFF32
- Renesas / SuperH SH relocs. Not all of these appear in object
- files.
-
- -- : BFD_RELOC_ARC_B22_PCREL
- ARC Cores relocs. ARC 22 bit pc-relative branch. The lowest two
- bits must be zero and are not stored in the instruction. The high
- 20 bits are installed in bits 26 through 7 of the instruction.
-
- -- : BFD_RELOC_ARC_B26
- ARC 26 bit absolute branch. The lowest two bits must be zero and
- are not stored in the instruction. The high 24 bits are installed
- in bits 23 through 0.
-
- -- : BFD_RELOC_BFIN_16_IMM
- ADI Blackfin 16 bit immediate absolute reloc.
-
- -- : BFD_RELOC_BFIN_16_HIGH
- ADI Blackfin 16 bit immediate absolute reloc higher 16 bits.
-
- -- : BFD_RELOC_BFIN_4_PCREL
- ADI Blackfin 'a' part of LSETUP.
-
- -- : BFD_RELOC_BFIN_5_PCREL
- ADI Blackfin.
-
- -- : BFD_RELOC_BFIN_16_LOW
- ADI Blackfin 16 bit immediate absolute reloc lower 16 bits.
-
- -- : BFD_RELOC_BFIN_10_PCREL
- ADI Blackfin.
-
- -- : BFD_RELOC_BFIN_11_PCREL
- ADI Blackfin 'b' part of LSETUP.
-
- -- : BFD_RELOC_BFIN_12_PCREL_JUMP
- ADI Blackfin.
-
- -- : BFD_RELOC_BFIN_12_PCREL_JUMP_S
- ADI Blackfin Short jump, pcrel.
-
- -- : BFD_RELOC_BFIN_24_PCREL_CALL_X
- ADI Blackfin Call.x not implemented.
-
- -- : BFD_RELOC_BFIN_24_PCREL_JUMP_L
- ADI Blackfin Long Jump pcrel.
-
- -- : BFD_RELOC_BFIN_GOT17M4
- -- : BFD_RELOC_BFIN_GOTHI
- -- : BFD_RELOC_BFIN_GOTLO
- -- : BFD_RELOC_BFIN_FUNCDESC
- -- : BFD_RELOC_BFIN_FUNCDESC_GOT17M4
- -- : BFD_RELOC_BFIN_FUNCDESC_GOTHI
- -- : BFD_RELOC_BFIN_FUNCDESC_GOTLO
- -- : BFD_RELOC_BFIN_FUNCDESC_VALUE
- -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4
- -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI
- -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO
- -- : BFD_RELOC_BFIN_GOTOFF17M4
- -- : BFD_RELOC_BFIN_GOTOFFHI
- -- : BFD_RELOC_BFIN_GOTOFFLO
- ADI Blackfin FD-PIC relocations.
-
- -- : BFD_RELOC_BFIN_GOT
- ADI Blackfin GOT relocation.
-
- -- : BFD_RELOC_BFIN_PLTPC
- ADI Blackfin PLTPC relocation.
-
- -- : BFD_ARELOC_BFIN_PUSH
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_CONST
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_ADD
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_SUB
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_MULT
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_DIV
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_MOD
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_LSHIFT
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_RSHIFT
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_AND
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_OR
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_XOR
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_LAND
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_LOR
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_LEN
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_NEG
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_COMP
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_PAGE
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_HWPAGE
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_ARELOC_BFIN_ADDR
- ADI Blackfin arithmetic relocation.
-
- -- : BFD_RELOC_D10V_10_PCREL_R
- Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2
- bits assumed to be 0.
-
- -- : BFD_RELOC_D10V_10_PCREL_L
- Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2
- bits assumed to be 0. This is the same as the previous reloc
- except it is in the left container, i.e., shifted left 15 bits.
-
- -- : BFD_RELOC_D10V_18
- This is an 18-bit reloc with the right 2 bits assumed to be 0.
-
- -- : BFD_RELOC_D10V_18_PCREL
- This is an 18-bit reloc with the right 2 bits assumed to be 0.
-
- -- : BFD_RELOC_D30V_6
- Mitsubishi D30V relocs. This is a 6-bit absolute reloc.
-
- -- : BFD_RELOC_D30V_9_PCREL
- This is a 6-bit pc-relative reloc with the right 3 bits assumed to
- be 0.
-
- -- : BFD_RELOC_D30V_9_PCREL_R
- This is a 6-bit pc-relative reloc with the right 3 bits assumed to
- be 0. Same as the previous reloc but on the right side of the
- container.
-
- -- : BFD_RELOC_D30V_15
- This is a 12-bit absolute reloc with the right 3 bitsassumed to be
- 0.
-
- -- : BFD_RELOC_D30V_15_PCREL
- This is a 12-bit pc-relative reloc with the right 3 bits assumed
- to be 0.
-
- -- : BFD_RELOC_D30V_15_PCREL_R
- This is a 12-bit pc-relative reloc with the right 3 bits assumed
- to be 0. Same as the previous reloc but on the right side of the
- container.
-
- -- : BFD_RELOC_D30V_21
- This is an 18-bit absolute reloc with the right 3 bits assumed to
- be 0.
-
- -- : BFD_RELOC_D30V_21_PCREL
- This is an 18-bit pc-relative reloc with the right 3 bits assumed
- to be 0.
-
- -- : BFD_RELOC_D30V_21_PCREL_R
- This is an 18-bit pc-relative reloc with the right 3 bits assumed
- to be 0. Same as the previous reloc but on the right side of the
- container.
-
- -- : BFD_RELOC_D30V_32
- This is a 32-bit absolute reloc.
-
- -- : BFD_RELOC_D30V_32_PCREL
- This is a 32-bit pc-relative reloc.
-
- -- : BFD_RELOC_DLX_HI16_S
- DLX relocs
-
- -- : BFD_RELOC_DLX_LO16
- DLX relocs
-
- -- : BFD_RELOC_DLX_JMP26
- DLX relocs
-
- -- : BFD_RELOC_M32C_HI8
- -- : BFD_RELOC_M32C_RL_JUMP
- -- : BFD_RELOC_M32C_RL_1ADDR
- -- : BFD_RELOC_M32C_RL_2ADDR
- Renesas M16C/M32C Relocations.
-
- -- : BFD_RELOC_M32R_24
- Renesas M32R (formerly Mitsubishi M32R) relocs. This is a 24 bit
- absolute address.
-
- -- : BFD_RELOC_M32R_10_PCREL
- This is a 10-bit pc-relative reloc with the right 2 bits assumed
- to be 0.
-
- -- : BFD_RELOC_M32R_18_PCREL
- This is an 18-bit reloc with the right 2 bits assumed to be 0.
-
- -- : BFD_RELOC_M32R_26_PCREL
- This is a 26-bit reloc with the right 2 bits assumed to be 0.
-
- -- : BFD_RELOC_M32R_HI16_ULO
- This is a 16-bit reloc containing the high 16 bits of an address
- used when the lower 16 bits are treated as unsigned.
-
- -- : BFD_RELOC_M32R_HI16_SLO
- This is a 16-bit reloc containing the high 16 bits of an address
- used when the lower 16 bits are treated as signed.
-
- -- : BFD_RELOC_M32R_LO16
- This is a 16-bit reloc containing the lower 16 bits of an address.
-
- -- : BFD_RELOC_M32R_SDA16
- This is a 16-bit reloc containing the small data area offset for
- use in add3, load, and store instructions.
-
- -- : BFD_RELOC_M32R_GOT24
- -- : BFD_RELOC_M32R_26_PLTREL
- -- : BFD_RELOC_M32R_COPY
- -- : BFD_RELOC_M32R_GLOB_DAT
- -- : BFD_RELOC_M32R_JMP_SLOT
- -- : BFD_RELOC_M32R_RELATIVE
- -- : BFD_RELOC_M32R_GOTOFF
- -- : BFD_RELOC_M32R_GOTOFF_HI_ULO
- -- : BFD_RELOC_M32R_GOTOFF_HI_SLO
- -- : BFD_RELOC_M32R_GOTOFF_LO
- -- : BFD_RELOC_M32R_GOTPC24
- -- : BFD_RELOC_M32R_GOT16_HI_ULO
- -- : BFD_RELOC_M32R_GOT16_HI_SLO
- -- : BFD_RELOC_M32R_GOT16_LO
- -- : BFD_RELOC_M32R_GOTPC_HI_ULO
- -- : BFD_RELOC_M32R_GOTPC_HI_SLO
- -- : BFD_RELOC_M32R_GOTPC_LO
- For PIC.
-
- -- : BFD_RELOC_V850_9_PCREL
- This is a 9-bit reloc
-
- -- : BFD_RELOC_V850_22_PCREL
- This is a 22-bit reloc
-
- -- : BFD_RELOC_V850_SDA_16_16_OFFSET
- This is a 16 bit offset from the short data area pointer.
-
- -- : BFD_RELOC_V850_SDA_15_16_OFFSET
- This is a 16 bit offset (of which only 15 bits are used) from the
- short data area pointer.
-
- -- : BFD_RELOC_V850_ZDA_16_16_OFFSET
- This is a 16 bit offset from the zero data area pointer.
-
- -- : BFD_RELOC_V850_ZDA_15_16_OFFSET
- This is a 16 bit offset (of which only 15 bits are used) from the
- zero data area pointer.
-
- -- : BFD_RELOC_V850_TDA_6_8_OFFSET
- This is an 8 bit offset (of which only 6 bits are used) from the
- tiny data area pointer.
-
- -- : BFD_RELOC_V850_TDA_7_8_OFFSET
- This is an 8bit offset (of which only 7 bits are used) from the
- tiny data area pointer.
-
- -- : BFD_RELOC_V850_TDA_7_7_OFFSET
- This is a 7 bit offset from the tiny data area pointer.
-
- -- : BFD_RELOC_V850_TDA_16_16_OFFSET
- This is a 16 bit offset from the tiny data area pointer.
-
- -- : BFD_RELOC_V850_TDA_4_5_OFFSET
- This is a 5 bit offset (of which only 4 bits are used) from the
- tiny data area pointer.
-
- -- : BFD_RELOC_V850_TDA_4_4_OFFSET
- This is a 4 bit offset from the tiny data area pointer.
-
- -- : BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET
- This is a 16 bit offset from the short data area pointer, with the
- bits placed non-contiguously in the instruction.
-
- -- : BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET
- This is a 16 bit offset from the zero data area pointer, with the
- bits placed non-contiguously in the instruction.
-
- -- : BFD_RELOC_V850_CALLT_6_7_OFFSET
- This is a 6 bit offset from the call table base pointer.
-
- -- : BFD_RELOC_V850_CALLT_16_16_OFFSET
- This is a 16 bit offset from the call table base pointer.
-
- -- : BFD_RELOC_V850_LONGCALL
- Used for relaxing indirect function calls.
-
- -- : BFD_RELOC_V850_LONGJUMP
- Used for relaxing indirect jumps.
-
- -- : BFD_RELOC_V850_ALIGN
- Used to maintain alignment whilst relaxing.
-
- -- : BFD_RELOC_V850_LO16_SPLIT_OFFSET
- This is a variation of BFD_RELOC_LO16 that can be used in v850e
- ld.bu instructions.
-
- -- : BFD_RELOC_MN10300_32_PCREL
- This is a 32bit pcrel reloc for the mn10300, offset by two bytes
- in the instruction.
-
- -- : BFD_RELOC_MN10300_16_PCREL
- This is a 16bit pcrel reloc for the mn10300, offset by two bytes
- in the instruction.
-
- -- : BFD_RELOC_TIC30_LDP
- This is a 8bit DP reloc for the tms320c30, where the most
- significant 8 bits of a 24 bit word are placed into the least
- significant 8 bits of the opcode.
-
- -- : BFD_RELOC_TIC54X_PARTLS7
- This is a 7bit reloc for the tms320c54x, where the least
- significant 7 bits of a 16 bit word are placed into the least
- significant 7 bits of the opcode.
-
- -- : BFD_RELOC_TIC54X_PARTMS9
- This is a 9bit DP reloc for the tms320c54x, where the most
- significant 9 bits of a 16 bit word are placed into the least
- significant 9 bits of the opcode.
-
- -- : BFD_RELOC_TIC54X_23
- This is an extended address 23-bit reloc for the tms320c54x.
-
- -- : BFD_RELOC_TIC54X_16_OF_23
- This is a 16-bit reloc for the tms320c54x, where the least
- significant 16 bits of a 23-bit extended address are placed into
- the opcode.
-
- -- : BFD_RELOC_TIC54X_MS7_OF_23
- This is a reloc for the tms320c54x, where the most significant 7
- bits of a 23-bit extended address are placed into the opcode.
-
- -- : BFD_RELOC_FR30_48
- This is a 48 bit reloc for the FR30 that stores 32 bits.
-
- -- : BFD_RELOC_FR30_20
- This is a 32 bit reloc for the FR30 that stores 20 bits split up
- into two sections.
-
- -- : BFD_RELOC_FR30_6_IN_4
- This is a 16 bit reloc for the FR30 that stores a 6 bit word
- offset in 4 bits.
-
- -- : BFD_RELOC_FR30_8_IN_8
- This is a 16 bit reloc for the FR30 that stores an 8 bit byte
- offset into 8 bits.
-
- -- : BFD_RELOC_FR30_9_IN_8
- This is a 16 bit reloc for the FR30 that stores a 9 bit short
- offset into 8 bits.
-
- -- : BFD_RELOC_FR30_10_IN_8
- This is a 16 bit reloc for the FR30 that stores a 10 bit word
- offset into 8 bits.
-
- -- : BFD_RELOC_FR30_9_PCREL
- This is a 16 bit reloc for the FR30 that stores a 9 bit pc relative
- short offset into 8 bits.
-
- -- : BFD_RELOC_FR30_12_PCREL
- This is a 16 bit reloc for the FR30 that stores a 12 bit pc
- relative short offset into 11 bits.
-
- -- : BFD_RELOC_MCORE_PCREL_IMM8BY4
- -- : BFD_RELOC_MCORE_PCREL_IMM11BY2
- -- : BFD_RELOC_MCORE_PCREL_IMM4BY2
- -- : BFD_RELOC_MCORE_PCREL_32
- -- : BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2
- -- : BFD_RELOC_MCORE_RVA
- Motorola Mcore relocations.
-
- -- : BFD_RELOC_MEP_8
- -- : BFD_RELOC_MEP_16
- -- : BFD_RELOC_MEP_32
- -- : BFD_RELOC_MEP_PCREL8A2
- -- : BFD_RELOC_MEP_PCREL12A2
- -- : BFD_RELOC_MEP_PCREL17A2
- -- : BFD_RELOC_MEP_PCREL24A2
- -- : BFD_RELOC_MEP_PCABS24A2
- -- : BFD_RELOC_MEP_LOW16
- -- : BFD_RELOC_MEP_HI16U
- -- : BFD_RELOC_MEP_HI16S
- -- : BFD_RELOC_MEP_GPREL
- -- : BFD_RELOC_MEP_TPREL
- -- : BFD_RELOC_MEP_TPREL7
- -- : BFD_RELOC_MEP_TPREL7A2
- -- : BFD_RELOC_MEP_TPREL7A4
- -- : BFD_RELOC_MEP_UIMM24
- -- : BFD_RELOC_MEP_ADDR24A4
- -- : BFD_RELOC_MEP_GNU_VTINHERIT
- -- : BFD_RELOC_MEP_GNU_VTENTRY
- Toshiba Media Processor Relocations.
-
- -- : BFD_RELOC_MMIX_GETA
- -- : BFD_RELOC_MMIX_GETA_1
- -- : BFD_RELOC_MMIX_GETA_2
- -- : BFD_RELOC_MMIX_GETA_3
- These are relocations for the GETA instruction.
-
- -- : BFD_RELOC_MMIX_CBRANCH
- -- : BFD_RELOC_MMIX_CBRANCH_J
- -- : BFD_RELOC_MMIX_CBRANCH_1
- -- : BFD_RELOC_MMIX_CBRANCH_2
- -- : BFD_RELOC_MMIX_CBRANCH_3
- These are relocations for a conditional branch instruction.
-
- -- : BFD_RELOC_MMIX_PUSHJ
- -- : BFD_RELOC_MMIX_PUSHJ_1
- -- : BFD_RELOC_MMIX_PUSHJ_2
- -- : BFD_RELOC_MMIX_PUSHJ_3
- -- : BFD_RELOC_MMIX_PUSHJ_STUBBABLE
- These are relocations for the PUSHJ instruction.
-
- -- : BFD_RELOC_MMIX_JMP
- -- : BFD_RELOC_MMIX_JMP_1
- -- : BFD_RELOC_MMIX_JMP_2
- -- : BFD_RELOC_MMIX_JMP_3
- These are relocations for the JMP instruction.
-
- -- : BFD_RELOC_MMIX_ADDR19
- This is a relocation for a relative address as in a GETA
- instruction or a branch.
-
- -- : BFD_RELOC_MMIX_ADDR27
- This is a relocation for a relative address as in a JMP
- instruction.
-
- -- : BFD_RELOC_MMIX_REG_OR_BYTE
- This is a relocation for an instruction field that may be a general
- register or a value 0..255.
-
- -- : BFD_RELOC_MMIX_REG
- This is a relocation for an instruction field that may be a general
- register.
-
- -- : BFD_RELOC_MMIX_BASE_PLUS_OFFSET
- This is a relocation for two instruction fields holding a register
- and an offset, the equivalent of the relocation.
-
- -- : BFD_RELOC_MMIX_LOCAL
- This relocation is an assertion that the expression is not
- allocated as a global register. It does not modify contents.
-
- -- : BFD_RELOC_AVR_7_PCREL
- This is a 16 bit reloc for the AVR that stores 8 bit pc relative
- short offset into 7 bits.
-
- -- : BFD_RELOC_AVR_13_PCREL
- This is a 16 bit reloc for the AVR that stores 13 bit pc relative
- short offset into 12 bits.
-
- -- : BFD_RELOC_AVR_16_PM
- This is a 16 bit reloc for the AVR that stores 17 bit value
- (usually program memory address) into 16 bits.
-
- -- : BFD_RELOC_AVR_LO8_LDI
- This is a 16 bit reloc for the AVR that stores 8 bit value (usually
- data memory address) into 8 bit immediate value of LDI insn.
-
- -- : BFD_RELOC_AVR_HI8_LDI
- This is a 16 bit reloc for the AVR that stores 8 bit value (high 8
- bit of data memory address) into 8 bit immediate value of LDI insn.
-
- -- : BFD_RELOC_AVR_HH8_LDI
- This is a 16 bit reloc for the AVR that stores 8 bit value (most
- high 8 bit of program memory address) into 8 bit immediate value
- of LDI insn.
-
- -- : BFD_RELOC_AVR_MS8_LDI
- This is a 16 bit reloc for the AVR that stores 8 bit value (most
- high 8 bit of 32 bit value) into 8 bit immediate value of LDI insn.
-
- -- : BFD_RELOC_AVR_LO8_LDI_NEG
- This is a 16 bit reloc for the AVR that stores negated 8 bit value
- (usually data memory address) into 8 bit immediate value of SUBI
- insn.
-
- -- : BFD_RELOC_AVR_HI8_LDI_NEG
- This is a 16 bit reloc for the AVR that stores negated 8 bit value
- (high 8 bit of data memory address) into 8 bit immediate value of
- SUBI insn.
-
- -- : BFD_RELOC_AVR_HH8_LDI_NEG
- This is a 16 bit reloc for the AVR that stores negated 8 bit value
- (most high 8 bit of program memory address) into 8 bit immediate
- value of LDI or SUBI insn.
-
- -- : BFD_RELOC_AVR_MS8_LDI_NEG
- This is a 16 bit reloc for the AVR that stores negated 8 bit value
- (msb of 32 bit value) into 8 bit immediate value of LDI insn.
-
- -- : BFD_RELOC_AVR_LO8_LDI_PM
- This is a 16 bit reloc for the AVR that stores 8 bit value (usually
- command address) into 8 bit immediate value of LDI insn.
-
- -- : BFD_RELOC_AVR_LO8_LDI_GS
- This is a 16 bit reloc for the AVR that stores 8 bit value
- (command address) into 8 bit immediate value of LDI insn. If the
- address is beyond the 128k boundary, the linker inserts a jump
- stub for this reloc in the lower 128k.
-
- -- : BFD_RELOC_AVR_HI8_LDI_PM
- This is a 16 bit reloc for the AVR that stores 8 bit value (high 8
- bit of command address) into 8 bit immediate value of LDI insn.
-
- -- : BFD_RELOC_AVR_HI8_LDI_GS
- This is a 16 bit reloc for the AVR that stores 8 bit value (high 8
- bit of command address) into 8 bit immediate value of LDI insn.
- If the address is beyond the 128k boundary, the linker inserts a
- jump stub for this reloc below 128k.
-
- -- : BFD_RELOC_AVR_HH8_LDI_PM
- This is a 16 bit reloc for the AVR that stores 8 bit value (most
- high 8 bit of command address) into 8 bit immediate value of LDI
- insn.
-
- -- : BFD_RELOC_AVR_LO8_LDI_PM_NEG
- This is a 16 bit reloc for the AVR that stores negated 8 bit value
- (usually command address) into 8 bit immediate value of SUBI insn.
-
- -- : BFD_RELOC_AVR_HI8_LDI_PM_NEG
- This is a 16 bit reloc for the AVR that stores negated 8 bit value
- (high 8 bit of 16 bit command address) into 8 bit immediate value
- of SUBI insn.
-
- -- : BFD_RELOC_AVR_HH8_LDI_PM_NEG
- This is a 16 bit reloc for the AVR that stores negated 8 bit value
- (high 6 bit of 22 bit command address) into 8 bit immediate value
- of SUBI insn.
-
- -- : BFD_RELOC_AVR_CALL
- This is a 32 bit reloc for the AVR that stores 23 bit value into
- 22 bits.
-
- -- : BFD_RELOC_AVR_LDI
- This is a 16 bit reloc for the AVR that stores all needed bits for
- absolute addressing with ldi with overflow check to linktime
-
- -- : BFD_RELOC_AVR_6
- This is a 6 bit reloc for the AVR that stores offset for ldd/std
- instructions
-
- -- : BFD_RELOC_AVR_6_ADIW
- This is a 6 bit reloc for the AVR that stores offset for adiw/sbiw
- instructions
-
- -- : BFD_RELOC_390_12
- Direct 12 bit.
-
- -- : BFD_RELOC_390_GOT12
- 12 bit GOT offset.
-
- -- : BFD_RELOC_390_PLT32
- 32 bit PC relative PLT address.
-
- -- : BFD_RELOC_390_COPY
- Copy symbol at runtime.
-
- -- : BFD_RELOC_390_GLOB_DAT
- Create GOT entry.
-
- -- : BFD_RELOC_390_JMP_SLOT
- Create PLT entry.
-
- -- : BFD_RELOC_390_RELATIVE
- Adjust by program base.
-
- -- : BFD_RELOC_390_GOTPC
- 32 bit PC relative offset to GOT.
-
- -- : BFD_RELOC_390_GOT16
- 16 bit GOT offset.
-
- -- : BFD_RELOC_390_PC16DBL
- PC relative 16 bit shifted by 1.
-
- -- : BFD_RELOC_390_PLT16DBL
- 16 bit PC rel. PLT shifted by 1.
-
- -- : BFD_RELOC_390_PC32DBL
- PC relative 32 bit shifted by 1.
-
- -- : BFD_RELOC_390_PLT32DBL
- 32 bit PC rel. PLT shifted by 1.
-
- -- : BFD_RELOC_390_GOTPCDBL
- 32 bit PC rel. GOT shifted by 1.
-
- -- : BFD_RELOC_390_GOT64
- 64 bit GOT offset.
-
- -- : BFD_RELOC_390_PLT64
- 64 bit PC relative PLT address.
-
- -- : BFD_RELOC_390_GOTENT
- 32 bit rel. offset to GOT entry.
-
- -- : BFD_RELOC_390_GOTOFF64
- 64 bit offset to GOT.
-
- -- : BFD_RELOC_390_GOTPLT12
- 12-bit offset to symbol-entry within GOT, with PLT handling.
-
- -- : BFD_RELOC_390_GOTPLT16
- 16-bit offset to symbol-entry within GOT, with PLT handling.
-
- -- : BFD_RELOC_390_GOTPLT32
- 32-bit offset to symbol-entry within GOT, with PLT handling.
-
- -- : BFD_RELOC_390_GOTPLT64
- 64-bit offset to symbol-entry within GOT, with PLT handling.
-
- -- : BFD_RELOC_390_GOTPLTENT
- 32-bit rel. offset to symbol-entry within GOT, with PLT handling.
-
- -- : BFD_RELOC_390_PLTOFF16
- 16-bit rel. offset from the GOT to a PLT entry.
-
- -- : BFD_RELOC_390_PLTOFF32
- 32-bit rel. offset from the GOT to a PLT entry.
-
- -- : BFD_RELOC_390_PLTOFF64
- 64-bit rel. offset from the GOT to a PLT entry.
-
- -- : BFD_RELOC_390_TLS_LOAD
- -- : BFD_RELOC_390_TLS_GDCALL
- -- : BFD_RELOC_390_TLS_LDCALL
- -- : BFD_RELOC_390_TLS_GD32
- -- : BFD_RELOC_390_TLS_GD64
- -- : BFD_RELOC_390_TLS_GOTIE12
- -- : BFD_RELOC_390_TLS_GOTIE32
- -- : BFD_RELOC_390_TLS_GOTIE64
- -- : BFD_RELOC_390_TLS_LDM32
- -- : BFD_RELOC_390_TLS_LDM64
- -- : BFD_RELOC_390_TLS_IE32
- -- : BFD_RELOC_390_TLS_IE64
- -- : BFD_RELOC_390_TLS_IEENT
- -- : BFD_RELOC_390_TLS_LE32
- -- : BFD_RELOC_390_TLS_LE64
- -- : BFD_RELOC_390_TLS_LDO32
- -- : BFD_RELOC_390_TLS_LDO64
- -- : BFD_RELOC_390_TLS_DTPMOD
- -- : BFD_RELOC_390_TLS_DTPOFF
- -- : BFD_RELOC_390_TLS_TPOFF
- s390 tls relocations.
-
- -- : BFD_RELOC_390_20
- -- : BFD_RELOC_390_GOT20
- -- : BFD_RELOC_390_GOTPLT20
- -- : BFD_RELOC_390_TLS_GOTIE20
- Long displacement extension.
-
- -- : BFD_RELOC_SCORE_DUMMY1
- Score relocations
-
- -- : BFD_RELOC_SCORE_GPREL15
- Low 16 bit for load/store
-
- -- : BFD_RELOC_SCORE_DUMMY2
- -- : BFD_RELOC_SCORE_JMP
- This is a 24-bit reloc with the right 1 bit assumed to be 0
-
- -- : BFD_RELOC_SCORE_BRANCH
- This is a 19-bit reloc with the right 1 bit assumed to be 0
-
- -- : BFD_RELOC_SCORE16_JMP
- This is a 11-bit reloc with the right 1 bit assumed to be 0
-
- -- : BFD_RELOC_SCORE16_BRANCH
- This is a 8-bit reloc with the right 1 bit assumed to be 0
-
- -- : BFD_RELOC_SCORE_GOT15
- -- : BFD_RELOC_SCORE_GOT_LO16
- -- : BFD_RELOC_SCORE_CALL15
- -- : BFD_RELOC_SCORE_DUMMY_HI16
- Undocumented Score relocs
-
- -- : BFD_RELOC_IP2K_FR9
- Scenix IP2K - 9-bit register number / data address
-
- -- : BFD_RELOC_IP2K_BANK
- Scenix IP2K - 4-bit register/data bank number
-
- -- : BFD_RELOC_IP2K_ADDR16CJP
- Scenix IP2K - low 13 bits of instruction word address
-
- -- : BFD_RELOC_IP2K_PAGE3
- Scenix IP2K - high 3 bits of instruction word address
-
- -- : BFD_RELOC_IP2K_LO8DATA
- -- : BFD_RELOC_IP2K_HI8DATA
- -- : BFD_RELOC_IP2K_EX8DATA
- Scenix IP2K - ext/low/high 8 bits of data address
-
- -- : BFD_RELOC_IP2K_LO8INSN
- -- : BFD_RELOC_IP2K_HI8INSN
- Scenix IP2K - low/high 8 bits of instruction word address
-
- -- : BFD_RELOC_IP2K_PC_SKIP
- Scenix IP2K - even/odd PC modifier to modify snb pcl.0
-
- -- : BFD_RELOC_IP2K_TEXT
- Scenix IP2K - 16 bit word address in text section.
-
- -- : BFD_RELOC_IP2K_FR_OFFSET
- Scenix IP2K - 7-bit sp or dp offset
-
- -- : BFD_RELOC_VPE4KMATH_DATA
- -- : BFD_RELOC_VPE4KMATH_INSN
- Scenix VPE4K coprocessor - data/insn-space addressing
-
- -- : BFD_RELOC_VTABLE_INHERIT
- -- : BFD_RELOC_VTABLE_ENTRY
- These two relocations are used by the linker to determine which of
- the entries in a C++ virtual function table are actually used.
- When the -gc-sections option is given, the linker will zero out
- the entries that are not used, so that the code for those
- functions need not be included in the output.
-
- VTABLE_INHERIT is a zero-space relocation used to describe to the
- linker the inheritance tree of a C++ virtual function table. The
- relocation's symbol should be the parent class' vtable, and the
- relocation should be located at the child vtable.
-
- VTABLE_ENTRY is a zero-space relocation that describes the use of a
- virtual function table entry. The reloc's symbol should refer to
- the table of the class mentioned in the code. Off of that base,
- an offset describes the entry that is being used. For Rela hosts,
- this offset is stored in the reloc's addend. For Rel hosts, we
- are forced to put this offset in the reloc's section offset.
-
- -- : BFD_RELOC_IA64_IMM14
- -- : BFD_RELOC_IA64_IMM22
- -- : BFD_RELOC_IA64_IMM64
- -- : BFD_RELOC_IA64_DIR32MSB
- -- : BFD_RELOC_IA64_DIR32LSB
- -- : BFD_RELOC_IA64_DIR64MSB
- -- : BFD_RELOC_IA64_DIR64LSB
- -- : BFD_RELOC_IA64_GPREL22
- -- : BFD_RELOC_IA64_GPREL64I
- -- : BFD_RELOC_IA64_GPREL32MSB
- -- : BFD_RELOC_IA64_GPREL32LSB
- -- : BFD_RELOC_IA64_GPREL64MSB
- -- : BFD_RELOC_IA64_GPREL64LSB
- -- : BFD_RELOC_IA64_LTOFF22
- -- : BFD_RELOC_IA64_LTOFF64I
- -- : BFD_RELOC_IA64_PLTOFF22
- -- : BFD_RELOC_IA64_PLTOFF64I
- -- : BFD_RELOC_IA64_PLTOFF64MSB
- -- : BFD_RELOC_IA64_PLTOFF64LSB
- -- : BFD_RELOC_IA64_FPTR64I
- -- : BFD_RELOC_IA64_FPTR32MSB
- -- : BFD_RELOC_IA64_FPTR32LSB
- -- : BFD_RELOC_IA64_FPTR64MSB
- -- : BFD_RELOC_IA64_FPTR64LSB
- -- : BFD_RELOC_IA64_PCREL21B
- -- : BFD_RELOC_IA64_PCREL21BI
- -- : BFD_RELOC_IA64_PCREL21M
- -- : BFD_RELOC_IA64_PCREL21F
- -- : BFD_RELOC_IA64_PCREL22
- -- : BFD_RELOC_IA64_PCREL60B
- -- : BFD_RELOC_IA64_PCREL64I
- -- : BFD_RELOC_IA64_PCREL32MSB
- -- : BFD_RELOC_IA64_PCREL32LSB
- -- : BFD_RELOC_IA64_PCREL64MSB
- -- : BFD_RELOC_IA64_PCREL64LSB
- -- : BFD_RELOC_IA64_LTOFF_FPTR22
- -- : BFD_RELOC_IA64_LTOFF_FPTR64I
- -- : BFD_RELOC_IA64_LTOFF_FPTR32MSB
- -- : BFD_RELOC_IA64_LTOFF_FPTR32LSB
- -- : BFD_RELOC_IA64_LTOFF_FPTR64MSB
- -- : BFD_RELOC_IA64_LTOFF_FPTR64LSB
- -- : BFD_RELOC_IA64_SEGREL32MSB
- -- : BFD_RELOC_IA64_SEGREL32LSB
- -- : BFD_RELOC_IA64_SEGREL64MSB
- -- : BFD_RELOC_IA64_SEGREL64LSB
- -- : BFD_RELOC_IA64_SECREL32MSB
- -- : BFD_RELOC_IA64_SECREL32LSB
- -- : BFD_RELOC_IA64_SECREL64MSB
- -- : BFD_RELOC_IA64_SECREL64LSB
- -- : BFD_RELOC_IA64_REL32MSB
- -- : BFD_RELOC_IA64_REL32LSB
- -- : BFD_RELOC_IA64_REL64MSB
- -- : BFD_RELOC_IA64_REL64LSB
- -- : BFD_RELOC_IA64_LTV32MSB
- -- : BFD_RELOC_IA64_LTV32LSB
- -- : BFD_RELOC_IA64_LTV64MSB
- -- : BFD_RELOC_IA64_LTV64LSB
- -- : BFD_RELOC_IA64_IPLTMSB
- -- : BFD_RELOC_IA64_IPLTLSB
- -- : BFD_RELOC_IA64_COPY
- -- : BFD_RELOC_IA64_LTOFF22X
- -- : BFD_RELOC_IA64_LDXMOV
- -- : BFD_RELOC_IA64_TPREL14
- -- : BFD_RELOC_IA64_TPREL22
- -- : BFD_RELOC_IA64_TPREL64I
- -- : BFD_RELOC_IA64_TPREL64MSB
- -- : BFD_RELOC_IA64_TPREL64LSB
- -- : BFD_RELOC_IA64_LTOFF_TPREL22
- -- : BFD_RELOC_IA64_DTPMOD64MSB
- -- : BFD_RELOC_IA64_DTPMOD64LSB
- -- : BFD_RELOC_IA64_LTOFF_DTPMOD22
- -- : BFD_RELOC_IA64_DTPREL14
- -- : BFD_RELOC_IA64_DTPREL22
- -- : BFD_RELOC_IA64_DTPREL64I
- -- : BFD_RELOC_IA64_DTPREL32MSB
- -- : BFD_RELOC_IA64_DTPREL32LSB
- -- : BFD_RELOC_IA64_DTPREL64MSB
- -- : BFD_RELOC_IA64_DTPREL64LSB
- -- : BFD_RELOC_IA64_LTOFF_DTPREL22
- Intel IA64 Relocations.
-
- -- : BFD_RELOC_M68HC11_HI8
- Motorola 68HC11 reloc. This is the 8 bit high part of an absolute
- address.
-
- -- : BFD_RELOC_M68HC11_LO8
- Motorola 68HC11 reloc. This is the 8 bit low part of an absolute
- address.
-
- -- : BFD_RELOC_M68HC11_3B
- Motorola 68HC11 reloc. This is the 3 bit of a value.
-
- -- : BFD_RELOC_M68HC11_RL_JUMP
- Motorola 68HC11 reloc. This reloc marks the beginning of a
- jump/call instruction. It is used for linker relaxation to
- correctly identify beginning of instruction and change some
- branches to use PC-relative addressing mode.
-
- -- : BFD_RELOC_M68HC11_RL_GROUP
- Motorola 68HC11 reloc. This reloc marks a group of several
- instructions that gcc generates and for which the linker
- relaxation pass can modify and/or remove some of them.
-
- -- : BFD_RELOC_M68HC11_LO16
- Motorola 68HC11 reloc. This is the 16-bit lower part of an
- address. It is used for 'call' instruction to specify the symbol
- address without any special transformation (due to memory bank
- window).
-
- -- : BFD_RELOC_M68HC11_PAGE
- Motorola 68HC11 reloc. This is a 8-bit reloc that specifies the
- page number of an address. It is used by 'call' instruction to
- specify the page number of the symbol.
-
- -- : BFD_RELOC_M68HC11_24
- Motorola 68HC11 reloc. This is a 24-bit reloc that represents the
- address with a 16-bit value and a 8-bit page number. The symbol
- address is transformed to follow the 16K memory bank of 68HC12
- (seen as mapped in the window).
-
- -- : BFD_RELOC_M68HC12_5B
- Motorola 68HC12 reloc. This is the 5 bits of a value.
-
- -- : BFD_RELOC_16C_NUM08
- -- : BFD_RELOC_16C_NUM08_C
- -- : BFD_RELOC_16C_NUM16
- -- : BFD_RELOC_16C_NUM16_C
- -- : BFD_RELOC_16C_NUM32
- -- : BFD_RELOC_16C_NUM32_C
- -- : BFD_RELOC_16C_DISP04
- -- : BFD_RELOC_16C_DISP04_C
- -- : BFD_RELOC_16C_DISP08
- -- : BFD_RELOC_16C_DISP08_C
- -- : BFD_RELOC_16C_DISP16
- -- : BFD_RELOC_16C_DISP16_C
- -- : BFD_RELOC_16C_DISP24
- -- : BFD_RELOC_16C_DISP24_C
- -- : BFD_RELOC_16C_DISP24a
- -- : BFD_RELOC_16C_DISP24a_C
- -- : BFD_RELOC_16C_REG04
- -- : BFD_RELOC_16C_REG04_C
- -- : BFD_RELOC_16C_REG04a
- -- : BFD_RELOC_16C_REG04a_C
- -- : BFD_RELOC_16C_REG14
- -- : BFD_RELOC_16C_REG14_C
- -- : BFD_RELOC_16C_REG16
- -- : BFD_RELOC_16C_REG16_C
- -- : BFD_RELOC_16C_REG20
- -- : BFD_RELOC_16C_REG20_C
- -- : BFD_RELOC_16C_ABS20
- -- : BFD_RELOC_16C_ABS20_C
- -- : BFD_RELOC_16C_ABS24
- -- : BFD_RELOC_16C_ABS24_C
- -- : BFD_RELOC_16C_IMM04
- -- : BFD_RELOC_16C_IMM04_C
- -- : BFD_RELOC_16C_IMM16
- -- : BFD_RELOC_16C_IMM16_C
- -- : BFD_RELOC_16C_IMM20
- -- : BFD_RELOC_16C_IMM20_C
- -- : BFD_RELOC_16C_IMM24
- -- : BFD_RELOC_16C_IMM24_C
- -- : BFD_RELOC_16C_IMM32
- -- : BFD_RELOC_16C_IMM32_C
- NS CR16C Relocations.
-
- -- : BFD_RELOC_CR16_NUM8
- -- : BFD_RELOC_CR16_NUM16
- -- : BFD_RELOC_CR16_NUM32
- -- : BFD_RELOC_CR16_NUM32a
- -- : BFD_RELOC_CR16_REGREL0
- -- : BFD_RELOC_CR16_REGREL4
- -- : BFD_RELOC_CR16_REGREL4a
- -- : BFD_RELOC_CR16_REGREL14
- -- : BFD_RELOC_CR16_REGREL14a
- -- : BFD_RELOC_CR16_REGREL16
- -- : BFD_RELOC_CR16_REGREL20
- -- : BFD_RELOC_CR16_REGREL20a
- -- : BFD_RELOC_CR16_ABS20
- -- : BFD_RELOC_CR16_ABS24
- -- : BFD_RELOC_CR16_IMM4
- -- : BFD_RELOC_CR16_IMM8
- -- : BFD_RELOC_CR16_IMM16
- -- : BFD_RELOC_CR16_IMM20
- -- : BFD_RELOC_CR16_IMM24
- -- : BFD_RELOC_CR16_IMM32
- -- : BFD_RELOC_CR16_IMM32a
- -- : BFD_RELOC_CR16_DISP4
- -- : BFD_RELOC_CR16_DISP8
- -- : BFD_RELOC_CR16_DISP16
- -- : BFD_RELOC_CR16_DISP20
- -- : BFD_RELOC_CR16_DISP24
- -- : BFD_RELOC_CR16_DISP24a
- NS CR16 Relocations.
-
- -- : BFD_RELOC_CRX_REL4
- -- : BFD_RELOC_CRX_REL8
- -- : BFD_RELOC_CRX_REL8_CMP
- -- : BFD_RELOC_CRX_REL16
- -- : BFD_RELOC_CRX_REL24
- -- : BFD_RELOC_CRX_REL32
- -- : BFD_RELOC_CRX_REGREL12
- -- : BFD_RELOC_CRX_REGREL22
- -- : BFD_RELOC_CRX_REGREL28
- -- : BFD_RELOC_CRX_REGREL32
- -- : BFD_RELOC_CRX_ABS16
- -- : BFD_RELOC_CRX_ABS32
- -- : BFD_RELOC_CRX_NUM8
- -- : BFD_RELOC_CRX_NUM16
- -- : BFD_RELOC_CRX_NUM32
- -- : BFD_RELOC_CRX_IMM16
- -- : BFD_RELOC_CRX_IMM32
- -- : BFD_RELOC_CRX_SWITCH8
- -- : BFD_RELOC_CRX_SWITCH16
- -- : BFD_RELOC_CRX_SWITCH32
- NS CRX Relocations.
-
- -- : BFD_RELOC_CRIS_BDISP8
- -- : BFD_RELOC_CRIS_UNSIGNED_5
- -- : BFD_RELOC_CRIS_SIGNED_6
- -- : BFD_RELOC_CRIS_UNSIGNED_6
- -- : BFD_RELOC_CRIS_SIGNED_8
- -- : BFD_RELOC_CRIS_UNSIGNED_8
- -- : BFD_RELOC_CRIS_SIGNED_16
- -- : BFD_RELOC_CRIS_UNSIGNED_16
- -- : BFD_RELOC_CRIS_LAPCQ_OFFSET
- -- : BFD_RELOC_CRIS_UNSIGNED_4
- These relocs are only used within the CRIS assembler. They are not
- (at present) written to any object files.
-
- -- : BFD_RELOC_CRIS_COPY
- -- : BFD_RELOC_CRIS_GLOB_DAT
- -- : BFD_RELOC_CRIS_JUMP_SLOT
- -- : BFD_RELOC_CRIS_RELATIVE
- Relocs used in ELF shared libraries for CRIS.
-
- -- : BFD_RELOC_CRIS_32_GOT
- 32-bit offset to symbol-entry within GOT.
-
- -- : BFD_RELOC_CRIS_16_GOT
- 16-bit offset to symbol-entry within GOT.
-
- -- : BFD_RELOC_CRIS_32_GOTPLT
- 32-bit offset to symbol-entry within GOT, with PLT handling.
-
- -- : BFD_RELOC_CRIS_16_GOTPLT
- 16-bit offset to symbol-entry within GOT, with PLT handling.
-
- -- : BFD_RELOC_CRIS_32_GOTREL
- 32-bit offset to symbol, relative to GOT.
-
- -- : BFD_RELOC_CRIS_32_PLT_GOTREL
- 32-bit offset to symbol with PLT entry, relative to GOT.
-
- -- : BFD_RELOC_CRIS_32_PLT_PCREL
- 32-bit offset to symbol with PLT entry, relative to this
- relocation.
-
- -- : BFD_RELOC_860_COPY
- -- : BFD_RELOC_860_GLOB_DAT
- -- : BFD_RELOC_860_JUMP_SLOT
- -- : BFD_RELOC_860_RELATIVE
- -- : BFD_RELOC_860_PC26
- -- : BFD_RELOC_860_PLT26
- -- : BFD_RELOC_860_PC16
- -- : BFD_RELOC_860_LOW0
- -- : BFD_RELOC_860_SPLIT0
- -- : BFD_RELOC_860_LOW1
- -- : BFD_RELOC_860_SPLIT1
- -- : BFD_RELOC_860_LOW2
- -- : BFD_RELOC_860_SPLIT2
- -- : BFD_RELOC_860_LOW3
- -- : BFD_RELOC_860_LOGOT0
- -- : BFD_RELOC_860_SPGOT0
- -- : BFD_RELOC_860_LOGOT1
- -- : BFD_RELOC_860_SPGOT1
- -- : BFD_RELOC_860_LOGOTOFF0
- -- : BFD_RELOC_860_SPGOTOFF0
- -- : BFD_RELOC_860_LOGOTOFF1
- -- : BFD_RELOC_860_SPGOTOFF1
- -- : BFD_RELOC_860_LOGOTOFF2
- -- : BFD_RELOC_860_LOGOTOFF3
- -- : BFD_RELOC_860_LOPC
- -- : BFD_RELOC_860_HIGHADJ
- -- : BFD_RELOC_860_HAGOT
- -- : BFD_RELOC_860_HAGOTOFF
- -- : BFD_RELOC_860_HAPC
- -- : BFD_RELOC_860_HIGH
- -- : BFD_RELOC_860_HIGOT
- -- : BFD_RELOC_860_HIGOTOFF
- Intel i860 Relocations.
-
- -- : BFD_RELOC_OPENRISC_ABS_26
- -- : BFD_RELOC_OPENRISC_REL_26
- OpenRISC Relocations.
-
- -- : BFD_RELOC_H8_DIR16A8
- -- : BFD_RELOC_H8_DIR16R8
- -- : BFD_RELOC_H8_DIR24A8
- -- : BFD_RELOC_H8_DIR24R8
- -- : BFD_RELOC_H8_DIR32A16
- H8 elf Relocations.
-
- -- : BFD_RELOC_XSTORMY16_REL_12
- -- : BFD_RELOC_XSTORMY16_12
- -- : BFD_RELOC_XSTORMY16_24
- -- : BFD_RELOC_XSTORMY16_FPTR16
- Sony Xstormy16 Relocations.
-
- -- : BFD_RELOC_RELC
- Self-describing complex relocations.
-
- -- : BFD_RELOC_XC16X_PAG
- -- : BFD_RELOC_XC16X_POF
- -- : BFD_RELOC_XC16X_SEG
- -- : BFD_RELOC_XC16X_SOF
- Infineon Relocations.
-
- -- : BFD_RELOC_VAX_GLOB_DAT
- -- : BFD_RELOC_VAX_JMP_SLOT
- -- : BFD_RELOC_VAX_RELATIVE
- Relocations used by VAX ELF.
-
- -- : BFD_RELOC_MT_PC16
- Morpho MT - 16 bit immediate relocation.
-
- -- : BFD_RELOC_MT_HI16
- Morpho MT - Hi 16 bits of an address.
-
- -- : BFD_RELOC_MT_LO16
- Morpho MT - Low 16 bits of an address.
-
- -- : BFD_RELOC_MT_GNU_VTINHERIT
- Morpho MT - Used to tell the linker which vtable entries are used.
-
- -- : BFD_RELOC_MT_GNU_VTENTRY
- Morpho MT - Used to tell the linker which vtable entries are used.
-
- -- : BFD_RELOC_MT_PCINSN8
- Morpho MT - 8 bit immediate relocation.
-
- -- : BFD_RELOC_MSP430_10_PCREL
- -- : BFD_RELOC_MSP430_16_PCREL
- -- : BFD_RELOC_MSP430_16
- -- : BFD_RELOC_MSP430_16_PCREL_BYTE
- -- : BFD_RELOC_MSP430_16_BYTE
- -- : BFD_RELOC_MSP430_2X_PCREL
- -- : BFD_RELOC_MSP430_RL_PCREL
- msp430 specific relocation codes
-
- -- : BFD_RELOC_IQ2000_OFFSET_16
- -- : BFD_RELOC_IQ2000_OFFSET_21
- -- : BFD_RELOC_IQ2000_UHI16
- IQ2000 Relocations.
-
- -- : BFD_RELOC_XTENSA_RTLD
- Special Xtensa relocation used only by PLT entries in ELF shared
- objects to indicate that the runtime linker should set the value
- to one of its own internal functions or data structures.
-
- -- : BFD_RELOC_XTENSA_GLOB_DAT
- -- : BFD_RELOC_XTENSA_JMP_SLOT
- -- : BFD_RELOC_XTENSA_RELATIVE
- Xtensa relocations for ELF shared objects.
-
- -- : BFD_RELOC_XTENSA_PLT
- Xtensa relocation used in ELF object files for symbols that may
- require PLT entries. Otherwise, this is just a generic 32-bit
- relocation.
-
- -- : BFD_RELOC_XTENSA_DIFF8
- -- : BFD_RELOC_XTENSA_DIFF16
- -- : BFD_RELOC_XTENSA_DIFF32
- Xtensa relocations to mark the difference of two local symbols.
- These are only needed to support linker relaxation and can be
- ignored when not relaxing. The field is set to the value of the
- difference assuming no relaxation. The relocation encodes the
- position of the first symbol so the linker can determine whether
- to adjust the field value.
-
- -- : BFD_RELOC_XTENSA_SLOT0_OP
- -- : BFD_RELOC_XTENSA_SLOT1_OP
- -- : BFD_RELOC_XTENSA_SLOT2_OP
- -- : BFD_RELOC_XTENSA_SLOT3_OP
- -- : BFD_RELOC_XTENSA_SLOT4_OP
- -- : BFD_RELOC_XTENSA_SLOT5_OP
- -- : BFD_RELOC_XTENSA_SLOT6_OP
- -- : BFD_RELOC_XTENSA_SLOT7_OP
- -- : BFD_RELOC_XTENSA_SLOT8_OP
- -- : BFD_RELOC_XTENSA_SLOT9_OP
- -- : BFD_RELOC_XTENSA_SLOT10_OP
- -- : BFD_RELOC_XTENSA_SLOT11_OP
- -- : BFD_RELOC_XTENSA_SLOT12_OP
- -- : BFD_RELOC_XTENSA_SLOT13_OP
- -- : BFD_RELOC_XTENSA_SLOT14_OP
- Generic Xtensa relocations for instruction operands. Only the slot
- number is encoded in the relocation. The relocation applies to the
- last PC-relative immediate operand, or if there are no PC-relative
- immediates, to the last immediate operand.
-
- -- : BFD_RELOC_XTENSA_SLOT0_ALT
- -- : BFD_RELOC_XTENSA_SLOT1_ALT
- -- : BFD_RELOC_XTENSA_SLOT2_ALT
- -- : BFD_RELOC_XTENSA_SLOT3_ALT
- -- : BFD_RELOC_XTENSA_SLOT4_ALT
- -- : BFD_RELOC_XTENSA_SLOT5_ALT
- -- : BFD_RELOC_XTENSA_SLOT6_ALT
- -- : BFD_RELOC_XTENSA_SLOT7_ALT
- -- : BFD_RELOC_XTENSA_SLOT8_ALT
- -- : BFD_RELOC_XTENSA_SLOT9_ALT
- -- : BFD_RELOC_XTENSA_SLOT10_ALT
- -- : BFD_RELOC_XTENSA_SLOT11_ALT
- -- : BFD_RELOC_XTENSA_SLOT12_ALT
- -- : BFD_RELOC_XTENSA_SLOT13_ALT
- -- : BFD_RELOC_XTENSA_SLOT14_ALT
- Alternate Xtensa relocations. Only the slot is encoded in the
- relocation. The meaning of these relocations is opcode-specific.
-
- -- : BFD_RELOC_XTENSA_OP0
- -- : BFD_RELOC_XTENSA_OP1
- -- : BFD_RELOC_XTENSA_OP2
- Xtensa relocations for backward compatibility. These have all been
- replaced by BFD_RELOC_XTENSA_SLOT0_OP.
-
- -- : BFD_RELOC_XTENSA_ASM_EXPAND
- Xtensa relocation to mark that the assembler expanded the
- instructions from an original target. The expansion size is
- encoded in the reloc size.
-
- -- : BFD_RELOC_XTENSA_ASM_SIMPLIFY
- Xtensa relocation to mark that the linker should simplify
- assembler-expanded instructions. This is commonly used internally
- by the linker after analysis of a BFD_RELOC_XTENSA_ASM_EXPAND.
-
- -- : BFD_RELOC_Z80_DISP8
- 8 bit signed offset in (ix+d) or (iy+d).
-
- -- : BFD_RELOC_Z8K_DISP7
- DJNZ offset.
-
- -- : BFD_RELOC_Z8K_CALLR
- CALR offset.
-
- -- : BFD_RELOC_Z8K_IMM4L
- 4 bit value.
-
-
- typedef enum bfd_reloc_code_real bfd_reloc_code_real_type;
-
-2.10.2.2 `bfd_reloc_type_lookup'
-................................
-
-*Synopsis*
- reloc_howto_type *bfd_reloc_type_lookup
- (bfd *abfd, bfd_reloc_code_real_type code);
- reloc_howto_type *bfd_reloc_name_lookup
- (bfd *abfd, const char *reloc_name);
- *Description*
-Return a pointer to a howto structure which, when invoked, will perform
-the relocation CODE on data from the architecture noted.
-
-2.10.2.3 `bfd_default_reloc_type_lookup'
-........................................
-
-*Synopsis*
- reloc_howto_type *bfd_default_reloc_type_lookup
- (bfd *abfd, bfd_reloc_code_real_type code);
- *Description*
-Provides a default relocation lookup routine for any architecture.
-
-2.10.2.4 `bfd_get_reloc_code_name'
-..................................
-
-*Synopsis*
- const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code);
- *Description*
-Provides a printable name for the supplied relocation code. Useful
-mainly for printing error messages.
-
-2.10.2.5 `bfd_generic_relax_section'
-....................................
-
-*Synopsis*
- bfd_boolean bfd_generic_relax_section
- (bfd *abfd,
- asection *section,
- struct bfd_link_info *,
- bfd_boolean *);
- *Description*
-Provides default handling for relaxing for back ends which don't do
-relaxing.
-
-2.10.2.6 `bfd_generic_gc_sections'
-..................................
-
-*Synopsis*
- bfd_boolean bfd_generic_gc_sections
- (bfd *, struct bfd_link_info *);
- *Description*
-Provides default handling for relaxing for back ends which don't do
-section gc - i.e., does nothing.
-
-2.10.2.7 `bfd_generic_merge_sections'
-.....................................
-
-*Synopsis*
- bfd_boolean bfd_generic_merge_sections
- (bfd *, struct bfd_link_info *);
- *Description*
-Provides default handling for SEC_MERGE section merging for back ends
-which don't have SEC_MERGE support - i.e., does nothing.
-
-2.10.2.8 `bfd_generic_get_relocated_section_contents'
-.....................................................
-
-*Synopsis*
- bfd_byte *bfd_generic_get_relocated_section_contents
- (bfd *abfd,
- struct bfd_link_info *link_info,
- struct bfd_link_order *link_order,
- bfd_byte *data,
- bfd_boolean relocatable,
- asymbol **symbols);
- *Description*
-Provides default handling of relocation effort for back ends which
-can't be bothered to do it efficiently.
-
-\1f
-File: bfd.info, Node: Core Files, Next: Targets, Prev: Relocations, Up: BFD front end
-
-2.11 Core files
-===============
-
-2.11.1 Core file functions
---------------------------
-
-*Description*
-These are functions pertaining to core files.
-
-2.11.1.1 `bfd_core_file_failing_command'
-........................................
-
-*Synopsis*
- const char *bfd_core_file_failing_command (bfd *abfd);
- *Description*
-Return a read-only string explaining which program was running when it
-failed and produced the core file ABFD.
-
-2.11.1.2 `bfd_core_file_failing_signal'
-.......................................
-
-*Synopsis*
- int bfd_core_file_failing_signal (bfd *abfd);
- *Description*
-Returns the signal number which caused the core dump which generated
-the file the BFD ABFD is attached to.
-
-2.11.1.3 `core_file_matches_executable_p'
-.........................................
-
-*Synopsis*
- bfd_boolean core_file_matches_executable_p
- (bfd *core_bfd, bfd *exec_bfd);
- *Description*
-Return `TRUE' if the core file attached to CORE_BFD was generated by a
-run of the executable file attached to EXEC_BFD, `FALSE' otherwise.
-
-2.11.1.4 `generic_core_file_matches_executable_p'
-.................................................
-
-*Synopsis*
- bfd_boolean generic_core_file_matches_executable_p
- (bfd *core_bfd, bfd *exec_bfd);
- *Description*
-Return TRUE if the core file attached to CORE_BFD was generated by a
-run of the executable file attached to EXEC_BFD. The match is based on
-executable basenames only.
-
- Note: When not able to determine the core file failing command or
-the executable name, we still return TRUE even though we're not sure
-that core file and executable match. This is to avoid generating a
-false warning in situations where we really don't know whether they
-match or not.
-
-\1f
-File: bfd.info, Node: Targets, Next: Architectures, Prev: Core Files, Up: BFD front end
-
-2.12 Targets
-============
-
-*Description*
-Each port of BFD to a different machine requires the creation of a
-target back end. All the back end provides to the root part of BFD is a
-structure containing pointers to functions which perform certain low
-level operations on files. BFD translates the applications's requests
-through a pointer into calls to the back end routines.
-
- When a file is opened with `bfd_openr', its format and target are
-unknown. BFD uses various mechanisms to determine how to interpret the
-file. The operations performed are:
-
- * Create a BFD by calling the internal routine `_bfd_new_bfd', then
- call `bfd_find_target' with the target string supplied to
- `bfd_openr' and the new BFD pointer.
-
- * If a null target string was provided to `bfd_find_target', look up
- the environment variable `GNUTARGET' and use that as the target
- string.
-
- * If the target string is still `NULL', or the target string is
- `default', then use the first item in the target vector as the
- target type, and set `target_defaulted' in the BFD to cause
- `bfd_check_format' to loop through all the targets. *Note
- bfd_target::. *Note Formats::.
-
- * Otherwise, inspect the elements in the target vector one by one,
- until a match on target name is found. When found, use it.
-
- * Otherwise return the error `bfd_error_invalid_target' to
- `bfd_openr'.
-
- * `bfd_openr' attempts to open the file using `bfd_open_file', and
- returns the BFD.
- Once the BFD has been opened and the target selected, the file
-format may be determined. This is done by calling `bfd_check_format' on
-the BFD with a suggested format. If `target_defaulted' has been set,
-each possible target type is tried to see if it recognizes the
-specified format. `bfd_check_format' returns `TRUE' when the caller
-guesses right.
-
-* Menu:
-
-* bfd_target::
-
-\1f
-File: bfd.info, Node: bfd_target, Prev: Targets, Up: Targets
-
-2.12.1 bfd_target
------------------
-
-*Description*
-This structure contains everything that BFD knows about a target. It
-includes things like its byte order, name, and which routines to call
-to do various operations.
-
- Every BFD points to a target structure with its `xvec' member.
-
- The macros below are used to dispatch to functions through the
-`bfd_target' vector. They are used in a number of macros further down
-in `bfd.h', and are also used when calling various routines by hand
-inside the BFD implementation. The ARGLIST argument must be
-parenthesized; it contains all the arguments to the called function.
-
- They make the documentation (more) unpleasant to read, so if someone
-wants to fix this and not break the above, please do.
- #define BFD_SEND(bfd, message, arglist) \
- ((*((bfd)->xvec->message)) arglist)
-
- #ifdef DEBUG_BFD_SEND
- #undef BFD_SEND
- #define BFD_SEND(bfd, message, arglist) \
- (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
- ((*((bfd)->xvec->message)) arglist) : \
- (bfd_assert (__FILE__,__LINE__), NULL))
- #endif
- For operations which index on the BFD format:
- #define BFD_SEND_FMT(bfd, message, arglist) \
- (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist)
-
- #ifdef DEBUG_BFD_SEND
- #undef BFD_SEND_FMT
- #define BFD_SEND_FMT(bfd, message, arglist) \
- (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
- (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \
- (bfd_assert (__FILE__,__LINE__), NULL))
- #endif
- This is the structure which defines the type of BFD this is. The
-`xvec' member of the struct `bfd' itself points here. Each module that
-implements access to a different target under BFD, defines one of these.
-
- FIXME, these names should be rationalised with the names of the
-entry points which call them. Too bad we can't have one macro to define
-them both!
- enum bfd_flavour
- {
- bfd_target_unknown_flavour,
- bfd_target_aout_flavour,
- bfd_target_coff_flavour,
- bfd_target_ecoff_flavour,
- bfd_target_xcoff_flavour,
- bfd_target_elf_flavour,
- bfd_target_ieee_flavour,
- bfd_target_nlm_flavour,
- bfd_target_oasys_flavour,
- bfd_target_tekhex_flavour,
- bfd_target_srec_flavour,
- bfd_target_ihex_flavour,
- bfd_target_som_flavour,
- bfd_target_os9k_flavour,
- bfd_target_versados_flavour,
- bfd_target_msdos_flavour,
- bfd_target_ovax_flavour,
- bfd_target_evax_flavour,
- bfd_target_mmo_flavour,
- bfd_target_mach_o_flavour,
- bfd_target_pef_flavour,
- bfd_target_pef_xlib_flavour,
- bfd_target_sym_flavour
- };
-
- enum bfd_endian { BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN };
-
- /* Forward declaration. */
- typedef struct bfd_link_info _bfd_link_info;
-
- typedef struct bfd_target
- {
- /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */
- char *name;
-
- /* The "flavour" of a back end is a general indication about
- the contents of a file. */
- enum bfd_flavour flavour;
-
- /* The order of bytes within the data area of a file. */
- enum bfd_endian byteorder;
-
- /* The order of bytes within the header parts of a file. */
- enum bfd_endian header_byteorder;
-
- /* A mask of all the flags which an executable may have set -
- from the set `BFD_NO_FLAGS', `HAS_RELOC', ...`D_PAGED'. */
- flagword object_flags;
-
- /* A mask of all the flags which a section may have set - from
- the set `SEC_NO_FLAGS', `SEC_ALLOC', ...`SET_NEVER_LOAD'. */
- flagword section_flags;
-
- /* The character normally found at the front of a symbol.
- (if any), perhaps `_'. */
- char symbol_leading_char;
-
- /* The pad character for file names within an archive header. */
- char ar_pad_char;
-
- /* The maximum number of characters in an archive header. */
- unsigned short ar_max_namelen;
-
- /* Entries for byte swapping for data. These are different from the
- other entry points, since they don't take a BFD as the first argument.
- Certain other handlers could do the same. */
- bfd_uint64_t (*bfd_getx64) (const void *);
- bfd_int64_t (*bfd_getx_signed_64) (const void *);
- void (*bfd_putx64) (bfd_uint64_t, void *);
- bfd_vma (*bfd_getx32) (const void *);
- bfd_signed_vma (*bfd_getx_signed_32) (const void *);
- void (*bfd_putx32) (bfd_vma, void *);
- bfd_vma (*bfd_getx16) (const void *);
- bfd_signed_vma (*bfd_getx_signed_16) (const void *);
- void (*bfd_putx16) (bfd_vma, void *);
-
- /* Byte swapping for the headers. */
- bfd_uint64_t (*bfd_h_getx64) (const void *);
- bfd_int64_t (*bfd_h_getx_signed_64) (const void *);
- void (*bfd_h_putx64) (bfd_uint64_t, void *);
- bfd_vma (*bfd_h_getx32) (const void *);
- bfd_signed_vma (*bfd_h_getx_signed_32) (const void *);
- void (*bfd_h_putx32) (bfd_vma, void *);
- bfd_vma (*bfd_h_getx16) (const void *);
- bfd_signed_vma (*bfd_h_getx_signed_16) (const void *);
- void (*bfd_h_putx16) (bfd_vma, void *);
-
- /* Format dependent routines: these are vectors of entry points
- within the target vector structure, one for each format to check. */
-
- /* Check the format of a file being read. Return a `bfd_target *' or zero. */
- const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *);
-
- /* Set the format of a file being written. */
- bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *);
-
- /* Write cached information into a file being written, at `bfd_close'. */
- bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *);
- The general target vector. These vectors are initialized using the
-BFD_JUMP_TABLE macros.
-
- /* Generic entry points. */
- #define BFD_JUMP_TABLE_GENERIC(NAME) \
- NAME##_close_and_cleanup, \
- NAME##_bfd_free_cached_info, \
- NAME##_new_section_hook, \
- NAME##_get_section_contents, \
- NAME##_get_section_contents_in_window
-
- /* Called when the BFD is being closed to do any necessary cleanup. */
- bfd_boolean (*_close_and_cleanup) (bfd *);
- /* Ask the BFD to free all cached information. */
- bfd_boolean (*_bfd_free_cached_info) (bfd *);
- /* Called when a new section is created. */
- bfd_boolean (*_new_section_hook) (bfd *, sec_ptr);
- /* Read the contents of a section. */
- bfd_boolean (*_bfd_get_section_contents)
- (bfd *, sec_ptr, void *, file_ptr, bfd_size_type);
- bfd_boolean (*_bfd_get_section_contents_in_window)
- (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type);
-
- /* Entry points to copy private data. */
- #define BFD_JUMP_TABLE_COPY(NAME) \
- NAME##_bfd_copy_private_bfd_data, \
- NAME##_bfd_merge_private_bfd_data, \
- _bfd_generic_init_private_section_data, \
- NAME##_bfd_copy_private_section_data, \
- NAME##_bfd_copy_private_symbol_data, \
- NAME##_bfd_copy_private_header_data, \
- NAME##_bfd_set_private_flags, \
- NAME##_bfd_print_private_bfd_data
-
- /* Called to copy BFD general private data from one object file
- to another. */
- bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *);
- /* Called to merge BFD general private data from one object file
- to a common output file when linking. */
- bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *);
- /* Called to initialize BFD private section data from one object file
- to another. */
- #define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \
- BFD_SEND (obfd, _bfd_init_private_section_data, (ibfd, isec, obfd, osec, link_info))
- bfd_boolean (*_bfd_init_private_section_data)
- (bfd *, sec_ptr, bfd *, sec_ptr, struct bfd_link_info *);
- /* Called to copy BFD private section data from one object file
- to another. */
- bfd_boolean (*_bfd_copy_private_section_data)
- (bfd *, sec_ptr, bfd *, sec_ptr);
- /* Called to copy BFD private symbol data from one symbol
- to another. */
- bfd_boolean (*_bfd_copy_private_symbol_data)
- (bfd *, asymbol *, bfd *, asymbol *);
- /* Called to copy BFD private header data from one object file
- to another. */
- bfd_boolean (*_bfd_copy_private_header_data)
- (bfd *, bfd *);
- /* Called to set private backend flags. */
- bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword);
-
- /* Called to print private BFD data. */
- bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *);
-
- /* Core file entry points. */
- #define BFD_JUMP_TABLE_CORE(NAME) \
- NAME##_core_file_failing_command, \
- NAME##_core_file_failing_signal, \
- NAME##_core_file_matches_executable_p
-
- char * (*_core_file_failing_command) (bfd *);
- int (*_core_file_failing_signal) (bfd *);
- bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *);
-
- /* Archive entry points. */
- #define BFD_JUMP_TABLE_ARCHIVE(NAME) \
- NAME##_slurp_armap, \
- NAME##_slurp_extended_name_table, \
- NAME##_construct_extended_name_table, \
- NAME##_truncate_arname, \
- NAME##_write_armap, \
- NAME##_read_ar_hdr, \
- NAME##_openr_next_archived_file, \
- NAME##_get_elt_at_index, \
- NAME##_generic_stat_arch_elt, \
- NAME##_update_armap_timestamp
-
- bfd_boolean (*_bfd_slurp_armap) (bfd *);
- bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *);
- bfd_boolean (*_bfd_construct_extended_name_table)
- (bfd *, char **, bfd_size_type *, const char **);
- void (*_bfd_truncate_arname) (bfd *, const char *, char *);
- bfd_boolean (*write_armap)
- (bfd *, unsigned int, struct orl *, unsigned int, int);
- void * (*_bfd_read_ar_hdr_fn) (bfd *);
- bfd * (*openr_next_archived_file) (bfd *, bfd *);
- #define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i))
- bfd * (*_bfd_get_elt_at_index) (bfd *, symindex);
- int (*_bfd_stat_arch_elt) (bfd *, struct stat *);
- bfd_boolean (*_bfd_update_armap_timestamp) (bfd *);
-
- /* Entry points used for symbols. */
- #define BFD_JUMP_TABLE_SYMBOLS(NAME) \
- NAME##_get_symtab_upper_bound, \
- NAME##_canonicalize_symtab, \
- NAME##_make_empty_symbol, \
- NAME##_print_symbol, \
- NAME##_get_symbol_info, \
- NAME##_bfd_is_local_label_name, \
- NAME##_bfd_is_target_special_symbol, \
- NAME##_get_lineno, \
- NAME##_find_nearest_line, \
- _bfd_generic_find_line, \
- NAME##_find_inliner_info, \
- NAME##_bfd_make_debug_symbol, \
- NAME##_read_minisymbols, \
- NAME##_minisymbol_to_symbol
-
- long (*_bfd_get_symtab_upper_bound) (bfd *);
- long (*_bfd_canonicalize_symtab)
- (bfd *, struct bfd_symbol **);
- struct bfd_symbol *
- (*_bfd_make_empty_symbol) (bfd *);
- void (*_bfd_print_symbol)
- (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type);
- #define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e))
- void (*_bfd_get_symbol_info)
- (bfd *, struct bfd_symbol *, symbol_info *);
- #define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e))
- bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *);
- bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *);
- alent * (*_get_lineno) (bfd *, struct bfd_symbol *);
- bfd_boolean (*_bfd_find_nearest_line)
- (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma,
- const char **, const char **, unsigned int *);
- bfd_boolean (*_bfd_find_line)
- (bfd *, struct bfd_symbol **, struct bfd_symbol *,
- const char **, unsigned int *);
- bfd_boolean (*_bfd_find_inliner_info)
- (bfd *, const char **, const char **, unsigned int *);
- /* Back-door to allow format-aware applications to create debug symbols
- while using BFD for everything else. Currently used by the assembler
- when creating COFF files. */
- asymbol * (*_bfd_make_debug_symbol)
- (bfd *, void *, unsigned long size);
- #define bfd_read_minisymbols(b, d, m, s) \
- BFD_SEND (b, _read_minisymbols, (b, d, m, s))
- long (*_read_minisymbols)
- (bfd *, bfd_boolean, void **, unsigned int *);
- #define bfd_minisymbol_to_symbol(b, d, m, f) \
- BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
- asymbol * (*_minisymbol_to_symbol)
- (bfd *, bfd_boolean, const void *, asymbol *);
-
- /* Routines for relocs. */
- #define BFD_JUMP_TABLE_RELOCS(NAME) \
- NAME##_get_reloc_upper_bound, \
- NAME##_canonicalize_reloc, \
- NAME##_bfd_reloc_type_lookup, \
- NAME##_bfd_reloc_name_lookup
-
- long (*_get_reloc_upper_bound) (bfd *, sec_ptr);
- long (*_bfd_canonicalize_reloc)
- (bfd *, sec_ptr, arelent **, struct bfd_symbol **);
- /* See documentation on reloc types. */
- reloc_howto_type *
- (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type);
- reloc_howto_type *
- (*reloc_name_lookup) (bfd *, const char *);
-
-
- /* Routines used when writing an object file. */
- #define BFD_JUMP_TABLE_WRITE(NAME) \
- NAME##_set_arch_mach, \
- NAME##_set_section_contents
-
- bfd_boolean (*_bfd_set_arch_mach)
- (bfd *, enum bfd_architecture, unsigned long);
- bfd_boolean (*_bfd_set_section_contents)
- (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type);
-
- /* Routines used by the linker. */
- #define BFD_JUMP_TABLE_LINK(NAME) \
- NAME##_sizeof_headers, \
- NAME##_bfd_get_relocated_section_contents, \
- NAME##_bfd_relax_section, \
- NAME##_bfd_link_hash_table_create, \
- NAME##_bfd_link_hash_table_free, \
- NAME##_bfd_link_add_symbols, \
- NAME##_bfd_link_just_syms, \
- NAME##_bfd_final_link, \
- NAME##_bfd_link_split_section, \
- NAME##_bfd_gc_sections, \
- NAME##_bfd_merge_sections, \
- NAME##_bfd_is_group_section, \
- NAME##_bfd_discard_group, \
- NAME##_section_already_linked \
-
- int (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *);
- bfd_byte * (*_bfd_get_relocated_section_contents)
- (bfd *, struct bfd_link_info *, struct bfd_link_order *,
- bfd_byte *, bfd_boolean, struct bfd_symbol **);
-
- bfd_boolean (*_bfd_relax_section)
- (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *);
-
- /* Create a hash table for the linker. Different backends store
- different information in this table. */
- struct bfd_link_hash_table *
- (*_bfd_link_hash_table_create) (bfd *);
-
- /* Release the memory associated with the linker hash table. */
- void (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *);
-
- /* Add symbols from this object file into the hash table. */
- bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *);
-
- /* Indicate that we are only retrieving symbol values from this section. */
- void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *);
-
- /* Do a link based on the link_order structures attached to each
- section of the BFD. */
- bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *);
-
- /* Should this section be split up into smaller pieces during linking. */
- bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *);
-
- /* Remove sections that are not referenced from the output. */
- bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *);
-
- /* Attempt to merge SEC_MERGE sections. */
- bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *);
-
- /* Is this section a member of a group? */
- bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *);
-
- /* Discard members of a group. */
- bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *);
-
- /* Check if SEC has been already linked during a reloceatable or
- final link. */
- void (*_section_already_linked) (bfd *, struct bfd_section *,
- struct bfd_link_info *);
-
- /* Routines to handle dynamic symbols and relocs. */
- #define BFD_JUMP_TABLE_DYNAMIC(NAME) \
- NAME##_get_dynamic_symtab_upper_bound, \
- NAME##_canonicalize_dynamic_symtab, \
- NAME##_get_synthetic_symtab, \
- NAME##_get_dynamic_reloc_upper_bound, \
- NAME##_canonicalize_dynamic_reloc
-
- /* Get the amount of memory required to hold the dynamic symbols. */
- long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *);
- /* Read in the dynamic symbols. */
- long (*_bfd_canonicalize_dynamic_symtab)
- (bfd *, struct bfd_symbol **);
- /* Create synthetized symbols. */
- long (*_bfd_get_synthetic_symtab)
- (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **,
- struct bfd_symbol **);
- /* Get the amount of memory required to hold the dynamic relocs. */
- long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *);
- /* Read in the dynamic relocs. */
- long (*_bfd_canonicalize_dynamic_reloc)
- (bfd *, arelent **, struct bfd_symbol **);
- A pointer to an alternative bfd_target in case the current one is not
-satisfactory. This can happen when the target cpu supports both big
-and little endian code, and target chosen by the linker has the wrong
-endianness. The function open_output() in ld/ldlang.c uses this field
-to find an alternative output format that is suitable.
- /* Opposite endian version of this target. */
- const struct bfd_target * alternative_target;
-
- /* Data for use by back-end routines, which isn't
- generic enough to belong in this structure. */
- const void *backend_data;
-
- } bfd_target;
-
-2.12.1.1 `bfd_set_default_target'
-.................................
-
-*Synopsis*
- bfd_boolean bfd_set_default_target (const char *name);
- *Description*
-Set the default target vector to use when recognizing a BFD. This
-takes the name of the target, which may be a BFD target name or a
-configuration triplet.
-
-2.12.1.2 `bfd_find_target'
-..........................
-
-*Synopsis*
- const bfd_target *bfd_find_target (const char *target_name, bfd *abfd);
- *Description*
-Return a pointer to the transfer vector for the object target named
-TARGET_NAME. If TARGET_NAME is `NULL', choose the one in the
-environment variable `GNUTARGET'; if that is null or not defined, then
-choose the first entry in the target list. Passing in the string
-"default" or setting the environment variable to "default" will cause
-the first entry in the target list to be returned, and
-"target_defaulted" will be set in the BFD if ABFD isn't `NULL'. This
-causes `bfd_check_format' to loop over all the targets to find the one
-that matches the file being read.
-
-2.12.1.3 `bfd_target_list'
-..........................
-
-*Synopsis*
- const char ** bfd_target_list (void);
- *Description*
-Return a freshly malloced NULL-terminated vector of the names of all
-the valid BFD targets. Do not modify the names.
-
-2.12.1.4 `bfd_seach_for_target'
-...............................
-
-*Synopsis*
- const bfd_target *bfd_search_for_target
- (int (*search_func) (const bfd_target *, void *),
- void *);
- *Description*
-Return a pointer to the first transfer vector in the list of transfer
-vectors maintained by BFD that produces a non-zero result when passed
-to the function SEARCH_FUNC. The parameter DATA is passed, unexamined,
-to the search function.
-
-\1f
-File: bfd.info, Node: Architectures, Next: Opening and Closing, Prev: Targets, Up: BFD front end
-
-2.13 Architectures
-==================
-
-BFD keeps one atom in a BFD describing the architecture of the data
-attached to the BFD: a pointer to a `bfd_arch_info_type'.
-
- Pointers to structures can be requested independently of a BFD so
-that an architecture's information can be interrogated without access
-to an open BFD.
-
- The architecture information is provided by each architecture
-package. The set of default architectures is selected by the macro
-`SELECT_ARCHITECTURES'. This is normally set up in the
-`config/TARGET.mt' file of your choice. If the name is not defined,
-then all the architectures supported are included.
-
- When BFD starts up, all the architectures are called with an
-initialize method. It is up to the architecture back end to insert as
-many items into the list of architectures as it wants to; generally
-this would be one for each machine and one for the default case (an
-item with a machine field of 0).
-
- BFD's idea of an architecture is implemented in `archures.c'.
-
-2.13.1 bfd_architecture
------------------------
-
-*Description*
-This enum gives the object file's CPU architecture, in a global
-sense--i.e., what processor family does it belong to? Another field
-indicates which processor within the family is in use. The machine
-gives a number which distinguishes different versions of the
-architecture, containing, for example, 2 and 3 for Intel i960 KA and
-i960 KB, and 68020 and 68030 for Motorola 68020 and 68030.
- enum bfd_architecture
- {
- bfd_arch_unknown, /* File arch not known. */
- bfd_arch_obscure, /* Arch known, not one of these. */
- bfd_arch_m68k, /* Motorola 68xxx */
- #define bfd_mach_m68000 1
- #define bfd_mach_m68008 2
- #define bfd_mach_m68010 3
- #define bfd_mach_m68020 4
- #define bfd_mach_m68030 5
- #define bfd_mach_m68040 6
- #define bfd_mach_m68060 7
- #define bfd_mach_cpu32 8
- #define bfd_mach_fido 9
- #define bfd_mach_mcf_isa_a_nodiv 10
- #define bfd_mach_mcf_isa_a 11
- #define bfd_mach_mcf_isa_a_mac 12
- #define bfd_mach_mcf_isa_a_emac 13
- #define bfd_mach_mcf_isa_aplus 14
- #define bfd_mach_mcf_isa_aplus_mac 15
- #define bfd_mach_mcf_isa_aplus_emac 16
- #define bfd_mach_mcf_isa_b_nousp 17
- #define bfd_mach_mcf_isa_b_nousp_mac 18
- #define bfd_mach_mcf_isa_b_nousp_emac 19
- #define bfd_mach_mcf_isa_b 20
- #define bfd_mach_mcf_isa_b_mac 21
- #define bfd_mach_mcf_isa_b_emac 22
- #define bfd_mach_mcf_isa_b_float 23
- #define bfd_mach_mcf_isa_b_float_mac 24
- #define bfd_mach_mcf_isa_b_float_emac 25
- #define bfd_mach_mcf_isa_c 26
- #define bfd_mach_mcf_isa_c_mac 27
- #define bfd_mach_mcf_isa_c_emac 28
- bfd_arch_vax, /* DEC Vax */
- bfd_arch_i960, /* Intel 960 */
- /* The order of the following is important.
- lower number indicates a machine type that
- only accepts a subset of the instructions
- available to machines with higher numbers.
- The exception is the "ca", which is
- incompatible with all other machines except
- "core". */
-
- #define bfd_mach_i960_core 1
- #define bfd_mach_i960_ka_sa 2
- #define bfd_mach_i960_kb_sb 3
- #define bfd_mach_i960_mc 4
- #define bfd_mach_i960_xa 5
- #define bfd_mach_i960_ca 6
- #define bfd_mach_i960_jx 7
- #define bfd_mach_i960_hx 8
-
- bfd_arch_or32, /* OpenRISC 32 */
-
- bfd_arch_sparc, /* SPARC */
- #define bfd_mach_sparc 1
- /* The difference between v8plus and v9 is that v9 is a true 64 bit env. */
- #define bfd_mach_sparc_sparclet 2
- #define bfd_mach_sparc_sparclite 3
- #define bfd_mach_sparc_v8plus 4
- #define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns. */
- #define bfd_mach_sparc_sparclite_le 6
- #define bfd_mach_sparc_v9 7
- #define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns. */
- #define bfd_mach_sparc_v8plusb 9 /* with cheetah add'ns. */
- #define bfd_mach_sparc_v9b 10 /* with cheetah add'ns. */
- /* Nonzero if MACH has the v9 instruction set. */
- #define bfd_mach_sparc_v9_p(mach) \
- ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \
- && (mach) != bfd_mach_sparc_sparclite_le)
- /* Nonzero if MACH is a 64 bit sparc architecture. */
- #define bfd_mach_sparc_64bit_p(mach) \
- ((mach) >= bfd_mach_sparc_v9 && (mach) != bfd_mach_sparc_v8plusb)
- bfd_arch_spu, /* PowerPC SPU */
- #define bfd_mach_spu 256
- bfd_arch_mips, /* MIPS Rxxxx */
- #define bfd_mach_mips3000 3000
- #define bfd_mach_mips3900 3900
- #define bfd_mach_mips4000 4000
- #define bfd_mach_mips4010 4010
- #define bfd_mach_mips4100 4100
- #define bfd_mach_mips4111 4111
- #define bfd_mach_mips4120 4120
- #define bfd_mach_mips4300 4300
- #define bfd_mach_mips4400 4400
- #define bfd_mach_mips4600 4600
- #define bfd_mach_mips4650 4650
- #define bfd_mach_mips5000 5000
- #define bfd_mach_mips5400 5400
- #define bfd_mach_mips5500 5500
- #define bfd_mach_mips6000 6000
- #define bfd_mach_mips7000 7000
- #define bfd_mach_mips8000 8000
- #define bfd_mach_mips9000 9000
- #define bfd_mach_mips10000 10000
- #define bfd_mach_mips12000 12000
- #define bfd_mach_mips16 16
- #define bfd_mach_mips5 5
- #define bfd_mach_mips_sb1 12310201 /* octal 'SB', 01 */
- #define bfd_mach_mipsisa32 32
- #define bfd_mach_mipsisa32r2 33
- #define bfd_mach_mipsisa64 64
- #define bfd_mach_mipsisa64r2 65
- bfd_arch_i386, /* Intel 386 */
- #define bfd_mach_i386_i386 1
- #define bfd_mach_i386_i8086 2
- #define bfd_mach_i386_i386_intel_syntax 3
- #define bfd_mach_x86_64 64
- #define bfd_mach_x86_64_intel_syntax 65
- bfd_arch_we32k, /* AT&T WE32xxx */
- bfd_arch_tahoe, /* CCI/Harris Tahoe */
- bfd_arch_i860, /* Intel 860 */
- bfd_arch_i370, /* IBM 360/370 Mainframes */
- bfd_arch_romp, /* IBM ROMP PC/RT */
- bfd_arch_convex, /* Convex */
- bfd_arch_m88k, /* Motorola 88xxx */
- bfd_arch_m98k, /* Motorola 98xxx */
- bfd_arch_pyramid, /* Pyramid Technology */
- bfd_arch_h8300, /* Renesas H8/300 (formerly Hitachi H8/300) */
- #define bfd_mach_h8300 1
- #define bfd_mach_h8300h 2
- #define bfd_mach_h8300s 3
- #define bfd_mach_h8300hn 4
- #define bfd_mach_h8300sn 5
- #define bfd_mach_h8300sx 6
- #define bfd_mach_h8300sxn 7
- bfd_arch_pdp11, /* DEC PDP-11 */
- bfd_arch_powerpc, /* PowerPC */
- #define bfd_mach_ppc 32
- #define bfd_mach_ppc64 64
- #define bfd_mach_ppc_403 403
- #define bfd_mach_ppc_403gc 4030
- #define bfd_mach_ppc_505 505
- #define bfd_mach_ppc_601 601
- #define bfd_mach_ppc_602 602
- #define bfd_mach_ppc_603 603
- #define bfd_mach_ppc_ec603e 6031
- #define bfd_mach_ppc_604 604
- #define bfd_mach_ppc_620 620
- #define bfd_mach_ppc_630 630
- #define bfd_mach_ppc_750 750
- #define bfd_mach_ppc_860 860
- #define bfd_mach_ppc_a35 35
- #define bfd_mach_ppc_rs64ii 642
- #define bfd_mach_ppc_rs64iii 643
- #define bfd_mach_ppc_7400 7400
- #define bfd_mach_ppc_e500 500
- bfd_arch_rs6000, /* IBM RS/6000 */
- #define bfd_mach_rs6k 6000
- #define bfd_mach_rs6k_rs1 6001
- #define bfd_mach_rs6k_rsc 6003
- #define bfd_mach_rs6k_rs2 6002
- bfd_arch_hppa, /* HP PA RISC */
- #define bfd_mach_hppa10 10
- #define bfd_mach_hppa11 11
- #define bfd_mach_hppa20 20
- #define bfd_mach_hppa20w 25
- bfd_arch_d10v, /* Mitsubishi D10V */
- #define bfd_mach_d10v 1
- #define bfd_mach_d10v_ts2 2
- #define bfd_mach_d10v_ts3 3
- bfd_arch_d30v, /* Mitsubishi D30V */
- bfd_arch_dlx, /* DLX */
- bfd_arch_m68hc11, /* Motorola 68HC11 */
- bfd_arch_m68hc12, /* Motorola 68HC12 */
- #define bfd_mach_m6812_default 0
- #define bfd_mach_m6812 1
- #define bfd_mach_m6812s 2
- bfd_arch_z8k, /* Zilog Z8000 */
- #define bfd_mach_z8001 1
- #define bfd_mach_z8002 2
- bfd_arch_h8500, /* Renesas H8/500 (formerly Hitachi H8/500) */
- bfd_arch_sh, /* Renesas / SuperH SH (formerly Hitachi SH) */
- #define bfd_mach_sh 1
- #define bfd_mach_sh2 0x20
- #define bfd_mach_sh_dsp 0x2d
- #define bfd_mach_sh2a 0x2a
- #define bfd_mach_sh2a_nofpu 0x2b
- #define bfd_mach_sh2a_nofpu_or_sh4_nommu_nofpu 0x2a1
- #define bfd_mach_sh2a_nofpu_or_sh3_nommu 0x2a2
- #define bfd_mach_sh2a_or_sh4 0x2a3
- #define bfd_mach_sh2a_or_sh3e 0x2a4
- #define bfd_mach_sh2e 0x2e
- #define bfd_mach_sh3 0x30
- #define bfd_mach_sh3_nommu 0x31
- #define bfd_mach_sh3_dsp 0x3d
- #define bfd_mach_sh3e 0x3e
- #define bfd_mach_sh4 0x40
- #define bfd_mach_sh4_nofpu 0x41
- #define bfd_mach_sh4_nommu_nofpu 0x42
- #define bfd_mach_sh4a 0x4a
- #define bfd_mach_sh4a_nofpu 0x4b
- #define bfd_mach_sh4al_dsp 0x4d
- #define bfd_mach_sh5 0x50
- bfd_arch_alpha, /* Dec Alpha */
- #define bfd_mach_alpha_ev4 0x10
- #define bfd_mach_alpha_ev5 0x20
- #define bfd_mach_alpha_ev6 0x30
- bfd_arch_arm, /* Advanced Risc Machines ARM. */
- #define bfd_mach_arm_unknown 0
- #define bfd_mach_arm_2 1
- #define bfd_mach_arm_2a 2
- #define bfd_mach_arm_3 3
- #define bfd_mach_arm_3M 4
- #define bfd_mach_arm_4 5
- #define bfd_mach_arm_4T 6
- #define bfd_mach_arm_5 7
- #define bfd_mach_arm_5T 8
- #define bfd_mach_arm_5TE 9
- #define bfd_mach_arm_XScale 10
- #define bfd_mach_arm_ep9312 11
- #define bfd_mach_arm_iWMMXt 12
- #define bfd_mach_arm_iWMMXt2 13
- bfd_arch_ns32k, /* National Semiconductors ns32000 */
- bfd_arch_w65, /* WDC 65816 */
- bfd_arch_tic30, /* Texas Instruments TMS320C30 */
- bfd_arch_tic4x, /* Texas Instruments TMS320C3X/4X */
- #define bfd_mach_tic3x 30
- #define bfd_mach_tic4x 40
- bfd_arch_tic54x, /* Texas Instruments TMS320C54X */
- bfd_arch_tic80, /* TI TMS320c80 (MVP) */
- bfd_arch_v850, /* NEC V850 */
- #define bfd_mach_v850 1
- #define bfd_mach_v850e 'E'
- #define bfd_mach_v850e1 '1'
- bfd_arch_arc, /* ARC Cores */
- #define bfd_mach_arc_5 5
- #define bfd_mach_arc_6 6
- #define bfd_mach_arc_7 7
- #define bfd_mach_arc_8 8
- bfd_arch_m32c, /* Renesas M16C/M32C. */
- #define bfd_mach_m16c 0x75
- #define bfd_mach_m32c 0x78
- bfd_arch_m32r, /* Renesas M32R (formerly Mitsubishi M32R/D) */
- #define bfd_mach_m32r 1 /* For backwards compatibility. */
- #define bfd_mach_m32rx 'x'
- #define bfd_mach_m32r2 '2'
- bfd_arch_mn10200, /* Matsushita MN10200 */
- bfd_arch_mn10300, /* Matsushita MN10300 */
- #define bfd_mach_mn10300 300
- #define bfd_mach_am33 330
- #define bfd_mach_am33_2 332
- bfd_arch_fr30,
- #define bfd_mach_fr30 0x46523330
- bfd_arch_frv,
- #define bfd_mach_frv 1
- #define bfd_mach_frvsimple 2
- #define bfd_mach_fr300 300
- #define bfd_mach_fr400 400
- #define bfd_mach_fr450 450
- #define bfd_mach_frvtomcat 499 /* fr500 prototype */
- #define bfd_mach_fr500 500
- #define bfd_mach_fr550 550
- bfd_arch_mcore,
- bfd_arch_mep,
- #define bfd_mach_mep 1
- #define bfd_mach_mep_h1 0x6831
- bfd_arch_ia64, /* HP/Intel ia64 */
- #define bfd_mach_ia64_elf64 64
- #define bfd_mach_ia64_elf32 32
- bfd_arch_ip2k, /* Ubicom IP2K microcontrollers. */
- #define bfd_mach_ip2022 1
- #define bfd_mach_ip2022ext 2
- bfd_arch_iq2000, /* Vitesse IQ2000. */
- #define bfd_mach_iq2000 1
- #define bfd_mach_iq10 2
- bfd_arch_mt,
- #define bfd_mach_ms1 1
- #define bfd_mach_mrisc2 2
- #define bfd_mach_ms2 3
- bfd_arch_pj,
- bfd_arch_avr, /* Atmel AVR microcontrollers. */
- #define bfd_mach_avr1 1
- #define bfd_mach_avr2 2
- #define bfd_mach_avr3 3
- #define bfd_mach_avr4 4
- #define bfd_mach_avr5 5
- #define bfd_mach_avr6 6
- bfd_arch_bfin, /* ADI Blackfin */
- #define bfd_mach_bfin 1
- bfd_arch_cr16, /* National Semiconductor CompactRISC (ie CR16). */
- #define bfd_mach_cr16 1
- bfd_arch_cr16c, /* National Semiconductor CompactRISC. */
- #define bfd_mach_cr16c 1
- bfd_arch_crx, /* National Semiconductor CRX. */
- #define bfd_mach_crx 1
- bfd_arch_cris, /* Axis CRIS */
- #define bfd_mach_cris_v0_v10 255
- #define bfd_mach_cris_v32 32
- #define bfd_mach_cris_v10_v32 1032
- bfd_arch_s390, /* IBM s390 */
- #define bfd_mach_s390_31 31
- #define bfd_mach_s390_64 64
- bfd_arch_score, /* Sunplus score */
- bfd_arch_openrisc, /* OpenRISC */
- bfd_arch_mmix, /* Donald Knuth's educational processor. */
- bfd_arch_xstormy16,
- #define bfd_mach_xstormy16 1
- bfd_arch_msp430, /* Texas Instruments MSP430 architecture. */
- #define bfd_mach_msp11 11
- #define bfd_mach_msp110 110
- #define bfd_mach_msp12 12
- #define bfd_mach_msp13 13
- #define bfd_mach_msp14 14
- #define bfd_mach_msp15 15
- #define bfd_mach_msp16 16
- #define bfd_mach_msp21 21
- #define bfd_mach_msp31 31
- #define bfd_mach_msp32 32
- #define bfd_mach_msp33 33
- #define bfd_mach_msp41 41
- #define bfd_mach_msp42 42
- #define bfd_mach_msp43 43
- #define bfd_mach_msp44 44
- bfd_arch_xc16x, /* Infineon's XC16X Series. */
- #define bfd_mach_xc16x 1
- #define bfd_mach_xc16xl 2
- #define bfd_mach_xc16xs 3
- bfd_arch_xtensa, /* Tensilica's Xtensa cores. */
- #define bfd_mach_xtensa 1
- bfd_arch_maxq, /* Dallas MAXQ 10/20 */
- #define bfd_mach_maxq10 10
- #define bfd_mach_maxq20 20
- bfd_arch_z80,
- #define bfd_mach_z80strict 1 /* No undocumented opcodes. */
- #define bfd_mach_z80 3 /* With ixl, ixh, iyl, and iyh. */
- #define bfd_mach_z80full 7 /* All undocumented instructions. */
- #define bfd_mach_r800 11 /* R800: successor with multiplication. */
- bfd_arch_last
- };
-
-2.13.2 bfd_arch_info
---------------------
-
-*Description*
-This structure contains information on architectures for use within BFD.
-
- typedef struct bfd_arch_info
- {
- int bits_per_word;
- int bits_per_address;
- int bits_per_byte;
- enum bfd_architecture arch;
- unsigned long mach;
- const char *arch_name;
- const char *printable_name;
- unsigned int section_align_power;
- /* TRUE if this is the default machine for the architecture.
- The default arch should be the first entry for an arch so that
- all the entries for that arch can be accessed via `next'. */
- bfd_boolean the_default;
- const struct bfd_arch_info * (*compatible)
- (const struct bfd_arch_info *a, const struct bfd_arch_info *b);
-
- bfd_boolean (*scan) (const struct bfd_arch_info *, const char *);
-
- const struct bfd_arch_info *next;
- }
- bfd_arch_info_type;
-
-2.13.2.1 `bfd_printable_name'
-.............................
-
-*Synopsis*
- const char *bfd_printable_name (bfd *abfd);
- *Description*
-Return a printable string representing the architecture and machine
-from the pointer to the architecture info structure.
-
-2.13.2.2 `bfd_scan_arch'
-........................
-
-*Synopsis*
- const bfd_arch_info_type *bfd_scan_arch (const char *string);
- *Description*
-Figure out if BFD supports any cpu which could be described with the
-name STRING. Return a pointer to an `arch_info' structure if a machine
-is found, otherwise NULL.
-
-2.13.2.3 `bfd_arch_list'
-........................
-
-*Synopsis*
- const char **bfd_arch_list (void);
- *Description*
-Return a freshly malloced NULL-terminated vector of the names of all
-the valid BFD architectures. Do not modify the names.
-
-2.13.2.4 `bfd_arch_get_compatible'
-..................................
-
-*Synopsis*
- const bfd_arch_info_type *bfd_arch_get_compatible
- (const bfd *abfd, const bfd *bbfd, bfd_boolean accept_unknowns);
- *Description*
-Determine whether two BFDs' architectures and machine types are
-compatible. Calculates the lowest common denominator between the two
-architectures and machine types implied by the BFDs and returns a
-pointer to an `arch_info' structure describing the compatible machine.
-
-2.13.2.5 `bfd_default_arch_struct'
-..................................
-
-*Description*
-The `bfd_default_arch_struct' is an item of `bfd_arch_info_type' which
-has been initialized to a fairly generic state. A BFD starts life by
-pointing to this structure, until the correct back end has determined
-the real architecture of the file.
- extern const bfd_arch_info_type bfd_default_arch_struct;
-
-2.13.2.6 `bfd_set_arch_info'
-............................
-
-*Synopsis*
- void bfd_set_arch_info (bfd *abfd, const bfd_arch_info_type *arg);
- *Description*
-Set the architecture info of ABFD to ARG.
-
-2.13.2.7 `bfd_default_set_arch_mach'
-....................................
-
-*Synopsis*
- bfd_boolean bfd_default_set_arch_mach
- (bfd *abfd, enum bfd_architecture arch, unsigned long mach);
- *Description*
-Set the architecture and machine type in BFD ABFD to ARCH and MACH.
-Find the correct pointer to a structure and insert it into the
-`arch_info' pointer.
-
-2.13.2.8 `bfd_get_arch'
-.......................
-
-*Synopsis*
- enum bfd_architecture bfd_get_arch (bfd *abfd);
- *Description*
-Return the enumerated type which describes the BFD ABFD's architecture.
-
-2.13.2.9 `bfd_get_mach'
-.......................
-
-*Synopsis*
- unsigned long bfd_get_mach (bfd *abfd);
- *Description*
-Return the long type which describes the BFD ABFD's machine.
-
-2.13.2.10 `bfd_arch_bits_per_byte'
-..................................
-
-*Synopsis*
- unsigned int bfd_arch_bits_per_byte (bfd *abfd);
- *Description*
-Return the number of bits in one of the BFD ABFD's architecture's bytes.
-
-2.13.2.11 `bfd_arch_bits_per_address'
-.....................................
-
-*Synopsis*
- unsigned int bfd_arch_bits_per_address (bfd *abfd);
- *Description*
-Return the number of bits in one of the BFD ABFD's architecture's
-addresses.
-
-2.13.2.12 `bfd_default_compatible'
-..................................
-
-*Synopsis*
- const bfd_arch_info_type *bfd_default_compatible
- (const bfd_arch_info_type *a, const bfd_arch_info_type *b);
- *Description*
-The default function for testing for compatibility.
-
-2.13.2.13 `bfd_default_scan'
-............................
-
-*Synopsis*
- bfd_boolean bfd_default_scan
- (const struct bfd_arch_info *info, const char *string);
- *Description*
-The default function for working out whether this is an architecture
-hit and a machine hit.
-
-2.13.2.14 `bfd_get_arch_info'
-.............................
-
-*Synopsis*
- const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd);
- *Description*
-Return the architecture info struct in ABFD.
-
-2.13.2.15 `bfd_lookup_arch'
-...........................
-
-*Synopsis*
- const bfd_arch_info_type *bfd_lookup_arch
- (enum bfd_architecture arch, unsigned long machine);
- *Description*
-Look for the architecture info structure which matches the arguments
-ARCH and MACHINE. A machine of 0 matches the machine/architecture
-structure which marks itself as the default.
-
-2.13.2.16 `bfd_printable_arch_mach'
-...................................
-
-*Synopsis*
- const char *bfd_printable_arch_mach
- (enum bfd_architecture arch, unsigned long machine);
- *Description*
-Return a printable string representing the architecture and machine
-type.
-
- This routine is depreciated.
-
-2.13.2.17 `bfd_octets_per_byte'
-...............................
-
-*Synopsis*
- unsigned int bfd_octets_per_byte (bfd *abfd);
- *Description*
-Return the number of octets (8-bit quantities) per target byte (minimum
-addressable unit). In most cases, this will be one, but some DSP
-targets have 16, 32, or even 48 bits per byte.
-
-2.13.2.18 `bfd_arch_mach_octets_per_byte'
-.........................................
-
-*Synopsis*
- unsigned int bfd_arch_mach_octets_per_byte
- (enum bfd_architecture arch, unsigned long machine);
- *Description*
-See bfd_octets_per_byte.
-
- This routine is provided for those cases where a bfd * is not
-available
-
-\1f
-File: bfd.info, Node: Opening and Closing, Next: Internal, Prev: Architectures, Up: BFD front end
-
-2.14 Opening and closing BFDs
-=============================
-
-2.14.1 Functions for opening and closing
-----------------------------------------
-
-2.14.1.1 `bfd_fopen'
-....................
-
-*Synopsis*
- bfd *bfd_fopen (const char *filename, const char *target,
- const char *mode, int fd);
- *Description*
-Open the file FILENAME with the target TARGET. Return a pointer to the
-created BFD. If FD is not -1, then `fdopen' is used to open the file;
-otherwise, `fopen' is used. MODE is passed directly to `fopen' or
-`fdopen'.
-
- Calls `bfd_find_target', so TARGET is interpreted as by that
-function.
-
- The new BFD is marked as cacheable iff FD is -1.
-
- If `NULL' is returned then an error has occured. Possible errors
-are `bfd_error_no_memory', `bfd_error_invalid_target' or `system_call'
-error.
-
-2.14.1.2 `bfd_openr'
-....................
-
-*Synopsis*
- bfd *bfd_openr (const char *filename, const char *target);
- *Description*
-Open the file FILENAME (using `fopen') with the target TARGET. Return
-a pointer to the created BFD.
-
- Calls `bfd_find_target', so TARGET is interpreted as by that
-function.
-
- If `NULL' is returned then an error has occured. Possible errors
-are `bfd_error_no_memory', `bfd_error_invalid_target' or `system_call'
-error.
-
-2.14.1.3 `bfd_fdopenr'
-......................
-
-*Synopsis*
- bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
- *Description*
-`bfd_fdopenr' is to `bfd_fopenr' much like `fdopen' is to `fopen'. It
-opens a BFD on a file already described by the FD supplied.
-
- When the file is later `bfd_close'd, the file descriptor will be
-closed. If the caller desires that this file descriptor be cached by
-BFD (opened as needed, closed as needed to free descriptors for other
-opens), with the supplied FD used as an initial file descriptor (but
-subject to closure at any time), call bfd_set_cacheable(bfd, 1) on the
-returned BFD. The default is to assume no caching; the file descriptor
-will remain open until `bfd_close', and will not be affected by BFD
-operations on other files.
-
- Possible errors are `bfd_error_no_memory',
-`bfd_error_invalid_target' and `bfd_error_system_call'.
-
-2.14.1.4 `bfd_openstreamr'
-..........................
-
-*Synopsis*
- bfd *bfd_openstreamr (const char *, const char *, void *);
- *Description*
-Open a BFD for read access on an existing stdio stream. When the BFD
-is passed to `bfd_close', the stream will be closed.
-
-2.14.1.5 `bfd_openr_iovec'
-..........................
-
-*Synopsis*
- bfd *bfd_openr_iovec (const char *filename, const char *target,
- void *(*open) (struct bfd *nbfd,
- void *open_closure),
- void *open_closure,
- file_ptr (*pread) (struct bfd *nbfd,
- void *stream,
- void *buf,
- file_ptr nbytes,
- file_ptr offset),
- int (*close) (struct bfd *nbfd,
- void *stream),
- int (*stat) (struct bfd *abfd,
- void *stream,
- struct stat *sb));
- *Description*
-Create and return a BFD backed by a read-only STREAM. The STREAM is
-created using OPEN, accessed using PREAD and destroyed using CLOSE.
-
- Calls `bfd_find_target', so TARGET is interpreted as by that
-function.
-
- Calls OPEN (which can call `bfd_zalloc' and `bfd_get_filename') to
-obtain the read-only stream backing the BFD. OPEN either succeeds
-returning the non-`NULL' STREAM, or fails returning `NULL' (setting
-`bfd_error').
-
- Calls PREAD to request NBYTES of data from STREAM starting at OFFSET
-(e.g., via a call to `bfd_read'). PREAD either succeeds returning the
-number of bytes read (which can be less than NBYTES when end-of-file),
-or fails returning -1 (setting `bfd_error').
-
- Calls CLOSE when the BFD is later closed using `bfd_close'. CLOSE
-either succeeds returning 0, or fails returning -1 (setting
-`bfd_error').
-
- Calls STAT to fill in a stat structure for bfd_stat, bfd_get_size,
-and bfd_get_mtime calls. STAT returns 0 on success, or returns -1 on
-failure (setting `bfd_error').
-
- If `bfd_openr_iovec' returns `NULL' then an error has occurred.
-Possible errors are `bfd_error_no_memory', `bfd_error_invalid_target'
-and `bfd_error_system_call'.
-
-2.14.1.6 `bfd_openw'
-....................
-
-*Synopsis*
- bfd *bfd_openw (const char *filename, const char *target);
- *Description*
-Create a BFD, associated with file FILENAME, using the file format
-TARGET, and return a pointer to it.
-
- Possible errors are `bfd_error_system_call', `bfd_error_no_memory',
-`bfd_error_invalid_target'.
-
-2.14.1.7 `bfd_close'
-....................
-
-*Synopsis*
- bfd_boolean bfd_close (bfd *abfd);
- *Description*
-Close a BFD. If the BFD was open for writing, then pending operations
-are completed and the file written out and closed. If the created file
-is executable, then `chmod' is called to mark it as such.
-
- All memory attached to the BFD is released.
-
- The file descriptor associated with the BFD is closed (even if it
-was passed in to BFD by `bfd_fdopenr').
-
- *Returns*
-`TRUE' is returned if all is ok, otherwise `FALSE'.
-
-2.14.1.8 `bfd_close_all_done'
-.............................
-
-*Synopsis*
- bfd_boolean bfd_close_all_done (bfd *);
- *Description*
-Close a BFD. Differs from `bfd_close' since it does not complete any
-pending operations. This routine would be used if the application had
-just used BFD for swapping and didn't want to use any of the writing
-code.
-
- If the created file is executable, then `chmod' is called to mark it
-as such.
-
- All memory attached to the BFD is released.
-
- *Returns*
-`TRUE' is returned if all is ok, otherwise `FALSE'.
-
-2.14.1.9 `bfd_create'
-.....................
-
-*Synopsis*
- bfd *bfd_create (const char *filename, bfd *templ);
- *Description*
-Create a new BFD in the manner of `bfd_openw', but without opening a
-file. The new BFD takes the target from the target used by TEMPLATE.
-The format is always set to `bfd_object'.
-
-2.14.1.10 `bfd_make_writable'
-.............................
-
-*Synopsis*
- bfd_boolean bfd_make_writable (bfd *abfd);
- *Description*
-Takes a BFD as created by `bfd_create' and converts it into one like as
-returned by `bfd_openw'. It does this by converting the BFD to
-BFD_IN_MEMORY. It's assumed that you will call `bfd_make_readable' on
-this bfd later.
-
- *Returns*
-`TRUE' is returned if all is ok, otherwise `FALSE'.
-
-2.14.1.11 `bfd_make_readable'
-.............................
-
-*Synopsis*
- bfd_boolean bfd_make_readable (bfd *abfd);
- *Description*
-Takes a BFD as created by `bfd_create' and `bfd_make_writable' and
-converts it into one like as returned by `bfd_openr'. It does this by
-writing the contents out to the memory buffer, then reversing the
-direction.
-
- *Returns*
-`TRUE' is returned if all is ok, otherwise `FALSE'.
-
-2.14.1.12 `bfd_alloc'
-.....................
-
-*Synopsis*
- void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
- *Description*
-Allocate a block of WANTED bytes of memory attached to `abfd' and
-return a pointer to it.
-
-2.14.1.13 `bfd_alloc2'
-......................
-
-*Synopsis*
- void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
- *Description*
-Allocate a block of NMEMB elements of SIZE bytes each of memory
-attached to `abfd' and return a pointer to it.
-
-2.14.1.14 `bfd_zalloc'
-......................
-
-*Synopsis*
- void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
- *Description*
-Allocate a block of WANTED bytes of zeroed memory attached to `abfd'
-and return a pointer to it.
-
-2.14.1.15 `bfd_zalloc2'
-.......................
-
-*Synopsis*
- void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
- *Description*
-Allocate a block of NMEMB elements of SIZE bytes each of zeroed memory
-attached to `abfd' and return a pointer to it.
-
-2.14.1.16 `bfd_calc_gnu_debuglink_crc32'
-........................................
-
-*Synopsis*
- unsigned long bfd_calc_gnu_debuglink_crc32
- (unsigned long crc, const unsigned char *buf, bfd_size_type len);
- *Description*
-Computes a CRC value as used in the .gnu_debuglink section. Advances
-the previously computed CRC value by computing and adding in the crc32
-for LEN bytes of BUF.
-
- *Returns*
-Return the updated CRC32 value.
-
-2.14.1.17 `get_debug_link_info'
-...............................
-
-*Synopsis*
- char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
- *Description*
-fetch the filename and CRC32 value for any separate debuginfo
-associated with ABFD. Return NULL if no such info found, otherwise
-return filename and update CRC32_OUT.
-
-2.14.1.18 `separate_debug_file_exists'
-......................................
-
-*Synopsis*
- bfd_boolean separate_debug_file_exists
- (char *name, unsigned long crc32);
- *Description*
-Checks to see if NAME is a file and if its contents match CRC32.
-
-2.14.1.19 `find_separate_debug_file'
-....................................
-
-*Synopsis*
- char *find_separate_debug_file (bfd *abfd);
- *Description*
-Searches ABFD for a reference to separate debugging information, scans
-various locations in the filesystem, including the file tree rooted at
-DEBUG_FILE_DIRECTORY, and returns a filename of such debugging
-information if the file is found and has matching CRC32. Returns NULL
-if no reference to debugging file exists, or file cannot be found.
-
-2.14.1.20 `bfd_follow_gnu_debuglink'
-....................................
-
-*Synopsis*
- char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
- *Description*
-Takes a BFD and searches it for a .gnu_debuglink section. If this
-section is found, it examines the section for the name and checksum of
-a '.debug' file containing auxiliary debugging information. It then
-searches the filesystem for this .debug file in some standard
-locations, including the directory tree rooted at DIR, and if found
-returns the full filename.
-
- If DIR is NULL, it will search a default path configured into libbfd
-at build time. [XXX this feature is not currently implemented].
-
- *Returns*
-`NULL' on any errors or failure to locate the .debug file, otherwise a
-pointer to a heap-allocated string containing the filename. The caller
-is responsible for freeing this string.
-
-2.14.1.21 `bfd_create_gnu_debuglink_section'
-............................................
-
-*Synopsis*
- struct bfd_section *bfd_create_gnu_debuglink_section
- (bfd *abfd, const char *filename);
- *Description*
-Takes a BFD and adds a .gnu_debuglink section to it. The section is
-sized to be big enough to contain a link to the specified FILENAME.
-
- *Returns*
-A pointer to the new section is returned if all is ok. Otherwise
-`NULL' is returned and bfd_error is set.
-
-2.14.1.22 `bfd_fill_in_gnu_debuglink_section'
-.............................................
-
-*Synopsis*
- bfd_boolean bfd_fill_in_gnu_debuglink_section
- (bfd *abfd, struct bfd_section *sect, const char *filename);
- *Description*
-Takes a BFD and containing a .gnu_debuglink section SECT and fills in
-the contents of the section to contain a link to the specified
-FILENAME. The filename should be relative to the current directory.
-
- *Returns*
-`TRUE' is returned if all is ok. Otherwise `FALSE' is returned and
-bfd_error is set.
-
-\1f
-File: bfd.info, Node: Internal, Next: File Caching, Prev: Opening and Closing, Up: BFD front end
-
-2.15 Implementation details
-===========================
-
-2.15.1 Internal functions
--------------------------
-
-*Description*
-These routines are used within BFD. They are not intended for export,
-but are documented here for completeness.
-
-2.15.1.1 `bfd_write_bigendian_4byte_int'
-........................................
-
-*Synopsis*
- bfd_boolean bfd_write_bigendian_4byte_int (bfd *, unsigned int);
- *Description*
-Write a 4 byte integer I to the output BFD ABFD, in big endian order
-regardless of what else is going on. This is useful in archives.
-
-2.15.1.2 `bfd_put_size'
-.......................
-
-2.15.1.3 `bfd_get_size'
-.......................
-
-*Description*
-These macros as used for reading and writing raw data in sections; each
-access (except for bytes) is vectored through the target format of the
-BFD and mangled accordingly. The mangling performs any necessary endian
-translations and removes alignment restrictions. Note that types
-accepted and returned by these macros are identical so they can be
-swapped around in macros--for example, `libaout.h' defines `GET_WORD'
-to either `bfd_get_32' or `bfd_get_64'.
-
- In the put routines, VAL must be a `bfd_vma'. If we are on a system
-without prototypes, the caller is responsible for making sure that is
-true, with a cast if necessary. We don't cast them in the macro
-definitions because that would prevent `lint' or `gcc -Wall' from
-detecting sins such as passing a pointer. To detect calling these with
-less than a `bfd_vma', use `gcc -Wconversion' on a host with 64 bit
-`bfd_vma''s.
-
- /* Byte swapping macros for user section data. */
-
- #define bfd_put_8(abfd, val, ptr) \
- ((void) (*((unsigned char *) (ptr)) = (val) & 0xff))
- #define bfd_put_signed_8 \
- bfd_put_8
- #define bfd_get_8(abfd, ptr) \
- (*(unsigned char *) (ptr) & 0xff)
- #define bfd_get_signed_8(abfd, ptr) \
- (((*(unsigned char *) (ptr) & 0xff) ^ 0x80) - 0x80)
-
- #define bfd_put_16(abfd, val, ptr) \
- BFD_SEND (abfd, bfd_putx16, ((val),(ptr)))
- #define bfd_put_signed_16 \
- bfd_put_16
- #define bfd_get_16(abfd, ptr) \
- BFD_SEND (abfd, bfd_getx16, (ptr))
- #define bfd_get_signed_16(abfd, ptr) \
- BFD_SEND (abfd, bfd_getx_signed_16, (ptr))
-
- #define bfd_put_32(abfd, val, ptr) \
- BFD_SEND (abfd, bfd_putx32, ((val),(ptr)))
- #define bfd_put_signed_32 \
- bfd_put_32
- #define bfd_get_32(abfd, ptr) \
- BFD_SEND (abfd, bfd_getx32, (ptr))
- #define bfd_get_signed_32(abfd, ptr) \
- BFD_SEND (abfd, bfd_getx_signed_32, (ptr))
-
- #define bfd_put_64(abfd, val, ptr) \
- BFD_SEND (abfd, bfd_putx64, ((val), (ptr)))
- #define bfd_put_signed_64 \
- bfd_put_64
- #define bfd_get_64(abfd, ptr) \
- BFD_SEND (abfd, bfd_getx64, (ptr))
- #define bfd_get_signed_64(abfd, ptr) \
- BFD_SEND (abfd, bfd_getx_signed_64, (ptr))
-
- #define bfd_get(bits, abfd, ptr) \
- ((bits) == 8 ? (bfd_vma) bfd_get_8 (abfd, ptr) \
- : (bits) == 16 ? bfd_get_16 (abfd, ptr) \
- : (bits) == 32 ? bfd_get_32 (abfd, ptr) \
- : (bits) == 64 ? bfd_get_64 (abfd, ptr) \
- : (abort (), (bfd_vma) - 1))
-
- #define bfd_put(bits, abfd, val, ptr) \
- ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \
- : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \
- : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \
- : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \
- : (abort (), (void) 0))
-
-2.15.1.4 `bfd_h_put_size'
-.........................
-
-*Description*
-These macros have the same function as their `bfd_get_x' brethren,
-except that they are used for removing information for the header
-records of object files. Believe it or not, some object files keep
-their header records in big endian order and their data in little
-endian order.
-
- /* Byte swapping macros for file header data. */
-
- #define bfd_h_put_8(abfd, val, ptr) \
- bfd_put_8 (abfd, val, ptr)
- #define bfd_h_put_signed_8(abfd, val, ptr) \
- bfd_put_8 (abfd, val, ptr)
- #define bfd_h_get_8(abfd, ptr) \
- bfd_get_8 (abfd, ptr)
- #define bfd_h_get_signed_8(abfd, ptr) \
- bfd_get_signed_8 (abfd, ptr)
-
- #define bfd_h_put_16(abfd, val, ptr) \
- BFD_SEND (abfd, bfd_h_putx16, (val, ptr))
- #define bfd_h_put_signed_16 \
- bfd_h_put_16
- #define bfd_h_get_16(abfd, ptr) \
- BFD_SEND (abfd, bfd_h_getx16, (ptr))
- #define bfd_h_get_signed_16(abfd, ptr) \
- BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr))
-
- #define bfd_h_put_32(abfd, val, ptr) \
- BFD_SEND (abfd, bfd_h_putx32, (val, ptr))
- #define bfd_h_put_signed_32 \
- bfd_h_put_32
- #define bfd_h_get_32(abfd, ptr) \
- BFD_SEND (abfd, bfd_h_getx32, (ptr))
- #define bfd_h_get_signed_32(abfd, ptr) \
- BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr))
-
- #define bfd_h_put_64(abfd, val, ptr) \
- BFD_SEND (abfd, bfd_h_putx64, (val, ptr))
- #define bfd_h_put_signed_64 \
- bfd_h_put_64
- #define bfd_h_get_64(abfd, ptr) \
- BFD_SEND (abfd, bfd_h_getx64, (ptr))
- #define bfd_h_get_signed_64(abfd, ptr) \
- BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr))
-
- /* Aliases for the above, which should eventually go away. */
-
- #define H_PUT_64 bfd_h_put_64
- #define H_PUT_32 bfd_h_put_32
- #define H_PUT_16 bfd_h_put_16
- #define H_PUT_8 bfd_h_put_8
- #define H_PUT_S64 bfd_h_put_signed_64
- #define H_PUT_S32 bfd_h_put_signed_32
- #define H_PUT_S16 bfd_h_put_signed_16
- #define H_PUT_S8 bfd_h_put_signed_8
- #define H_GET_64 bfd_h_get_64
- #define H_GET_32 bfd_h_get_32
- #define H_GET_16 bfd_h_get_16
- #define H_GET_8 bfd_h_get_8
- #define H_GET_S64 bfd_h_get_signed_64
- #define H_GET_S32 bfd_h_get_signed_32
- #define H_GET_S16 bfd_h_get_signed_16
- #define H_GET_S8 bfd_h_get_signed_8
-
-2.15.1.5 `bfd_log2'
-...................
-
-*Synopsis*
- unsigned int bfd_log2 (bfd_vma x);
- *Description*
-Return the log base 2 of the value supplied, rounded up. E.g., an X of
-1025 returns 11. A X of 0 returns 0.
-
-\1f
-File: bfd.info, Node: File Caching, Next: Linker Functions, Prev: Internal, Up: BFD front end
-
-2.16 File caching
-=================
-
-The file caching mechanism is embedded within BFD and allows the
-application to open as many BFDs as it wants without regard to the
-underlying operating system's file descriptor limit (often as low as 20
-open files). The module in `cache.c' maintains a least recently used
-list of `BFD_CACHE_MAX_OPEN' files, and exports the name
-`bfd_cache_lookup', which runs around and makes sure that the required
-BFD is open. If not, then it chooses a file to close, closes it and
-opens the one wanted, returning its file handle.
-
-2.16.1 Caching functions
-------------------------
-
-2.16.1.1 `bfd_cache_init'
-.........................
-
-*Synopsis*
- bfd_boolean bfd_cache_init (bfd *abfd);
- *Description*
-Add a newly opened BFD to the cache.
-
-2.16.1.2 `bfd_cache_close'
-..........................
-
-*Synopsis*
- bfd_boolean bfd_cache_close (bfd *abfd);
- *Description*
-Remove the BFD ABFD from the cache. If the attached file is open, then
-close it too.
-
- *Returns*
-`FALSE' is returned if closing the file fails, `TRUE' is returned if
-all is well.
-
-2.16.1.3 `bfd_cache_close_all'
-..............................
-
-*Synopsis*
- bfd_boolean bfd_cache_close_all (void);
- *Description*
-Remove all BFDs from the cache. If the attached file is open, then
-close it too.
-
- *Returns*
-`FALSE' is returned if closing one of the file fails, `TRUE' is
-returned if all is well.
-
-2.16.1.4 `bfd_open_file'
-........................
-
-*Synopsis*
- FILE* bfd_open_file (bfd *abfd);
- *Description*
-Call the OS to open a file for ABFD. Return the `FILE *' (possibly
-`NULL') that results from this operation. Set up the BFD so that
-future accesses know the file is open. If the `FILE *' returned is
-`NULL', then it won't have been put in the cache, so it won't have to
-be removed from it.
-
-\1f
-File: bfd.info, Node: Linker Functions, Next: Hash Tables, Prev: File Caching, Up: BFD front end
-
-2.17 Linker Functions
-=====================
-
-The linker uses three special entry points in the BFD target vector.
-It is not necessary to write special routines for these entry points
-when creating a new BFD back end, since generic versions are provided.
-However, writing them can speed up linking and make it use
-significantly less runtime memory.
-
- The first routine creates a hash table used by the other routines.
-The second routine adds the symbols from an object file to the hash
-table. The third routine takes all the object files and links them
-together to create the output file. These routines are designed so
-that the linker proper does not need to know anything about the symbols
-in the object files that it is linking. The linker merely arranges the
-sections as directed by the linker script and lets BFD handle the
-details of symbols and relocs.
-
- The second routine and third routines are passed a pointer to a
-`struct bfd_link_info' structure (defined in `bfdlink.h') which holds
-information relevant to the link, including the linker hash table
-(which was created by the first routine) and a set of callback
-functions to the linker proper.
-
- The generic linker routines are in `linker.c', and use the header
-file `genlink.h'. As of this writing, the only back ends which have
-implemented versions of these routines are a.out (in `aoutx.h') and
-ECOFF (in `ecoff.c'). The a.out routines are used as examples
-throughout this section.
-
-* Menu:
-
-* Creating a Linker Hash Table::
-* Adding Symbols to the Hash Table::
-* Performing the Final Link::
-
-\1f
-File: bfd.info, Node: Creating a Linker Hash Table, Next: Adding Symbols to the Hash Table, Prev: Linker Functions, Up: Linker Functions
-
-2.17.1 Creating a linker hash table
------------------------------------
-
-The linker routines must create a hash table, which must be derived
-from `struct bfd_link_hash_table' described in `bfdlink.c'. *Note Hash
-Tables::, for information on how to create a derived hash table. This
-entry point is called using the target vector of the linker output file.
-
- The `_bfd_link_hash_table_create' entry point must allocate and
-initialize an instance of the desired hash table. If the back end does
-not require any additional information to be stored with the entries in
-the hash table, the entry point may simply create a `struct
-bfd_link_hash_table'. Most likely, however, some additional
-information will be needed.
-
- For example, with each entry in the hash table the a.out linker
-keeps the index the symbol has in the final output file (this index
-number is used so that when doing a relocatable link the symbol index
-used in the output file can be quickly filled in when copying over a
-reloc). The a.out linker code defines the required structures and
-functions for a hash table derived from `struct bfd_link_hash_table'.
-The a.out linker hash table is created by the function
-`NAME(aout,link_hash_table_create)'; it simply allocates space for the
-hash table, initializes it, and returns a pointer to it.
-
- When writing the linker routines for a new back end, you will
-generally not know exactly which fields will be required until you have
-finished. You should simply create a new hash table which defines no
-additional fields, and then simply add fields as they become necessary.
-
-\1f
-File: bfd.info, Node: Adding Symbols to the Hash Table, Next: Performing the Final Link, Prev: Creating a Linker Hash Table, Up: Linker Functions
-
-2.17.2 Adding symbols to the hash table
----------------------------------------
-
-The linker proper will call the `_bfd_link_add_symbols' entry point for
-each object file or archive which is to be linked (typically these are
-the files named on the command line, but some may also come from the
-linker script). The entry point is responsible for examining the file.
-For an object file, BFD must add any relevant symbol information to
-the hash table. For an archive, BFD must determine which elements of
-the archive should be used and adding them to the link.
-
- The a.out version of this entry point is
-`NAME(aout,link_add_symbols)'.
-
-* Menu:
-
-* Differing file formats::
-* Adding symbols from an object file::
-* Adding symbols from an archive::
-
-\1f
-File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table
-
-2.17.2.1 Differing file formats
-...............................
-
-Normally all the files involved in a link will be of the same format,
-but it is also possible to link together different format object files,
-and the back end must support that. The `_bfd_link_add_symbols' entry
-point is called via the target vector of the file to be added. This
-has an important consequence: the function may not assume that the hash
-table is the type created by the corresponding
-`_bfd_link_hash_table_create' vector. All the `_bfd_link_add_symbols'
-function can assume about the hash table is that it is derived from
-`struct bfd_link_hash_table'.
-
- Sometimes the `_bfd_link_add_symbols' function must store some
-information in the hash table entry to be used by the `_bfd_final_link'
-function. In such a case the `creator' field of the hash table must be
-checked to make sure that the hash table was created by an object file
-of the same format.
-
- The `_bfd_final_link' routine must be prepared to handle a hash
-entry without any extra information added by the
-`_bfd_link_add_symbols' function. A hash entry without extra
-information will also occur when the linker script directs the linker
-to create a symbol. Note that, regardless of how a hash table entry is
-added, all the fields will be initialized to some sort of null value by
-the hash table entry initialization function.
-
- See `ecoff_link_add_externals' for an example of how to check the
-`creator' field before saving information (in this case, the ECOFF
-external symbol debugging information) in a hash table entry.
-
-\1f
-File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table
-
-2.17.2.2 Adding symbols from an object file
-...........................................
-
-When the `_bfd_link_add_symbols' routine is passed an object file, it
-must add all externally visible symbols in that object file to the hash
-table. The actual work of adding the symbol to the hash table is
-normally handled by the function `_bfd_generic_link_add_one_symbol'.
-The `_bfd_link_add_symbols' routine is responsible for reading all the
-symbols from the object file and passing the correct information to
-`_bfd_generic_link_add_one_symbol'.
-
- The `_bfd_link_add_symbols' routine should not use
-`bfd_canonicalize_symtab' to read the symbols. The point of providing
-this routine is to avoid the overhead of converting the symbols into
-generic `asymbol' structures.
-
- `_bfd_generic_link_add_one_symbol' handles the details of combining
-common symbols, warning about multiple definitions, and so forth. It
-takes arguments which describe the symbol to add, notably symbol flags,
-a section, and an offset. The symbol flags include such things as
-`BSF_WEAK' or `BSF_INDIRECT'. The section is a section in the object
-file, or something like `bfd_und_section_ptr' for an undefined symbol
-or `bfd_com_section_ptr' for a common symbol.
-
- If the `_bfd_final_link' routine is also going to need to read the
-symbol information, the `_bfd_link_add_symbols' routine should save it
-somewhere attached to the object file BFD. However, the information
-should only be saved if the `keep_memory' field of the `info' argument
-is TRUE, so that the `-no-keep-memory' linker switch is effective.
-
- The a.out function which adds symbols from an object file is
-`aout_link_add_object_symbols', and most of the interesting work is in
-`aout_link_add_symbols'. The latter saves pointers to the hash tables
-entries created by `_bfd_generic_link_add_one_symbol' indexed by symbol
-number, so that the `_bfd_final_link' routine does not have to call the
-hash table lookup routine to locate the entry.
-
-\1f
-File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table
-
-2.17.2.3 Adding symbols from an archive
-.......................................
-
-When the `_bfd_link_add_symbols' routine is passed an archive, it must
-look through the symbols defined by the archive and decide which
-elements of the archive should be included in the link. For each such
-element it must call the `add_archive_element' linker callback, and it
-must add the symbols from the object file to the linker hash table.
-
- In most cases the work of looking through the symbols in the archive
-should be done by the `_bfd_generic_link_add_archive_symbols' function.
-This function builds a hash table from the archive symbol table and
-looks through the list of undefined symbols to see which elements
-should be included. `_bfd_generic_link_add_archive_symbols' is passed
-a function to call to make the final decision about adding an archive
-element to the link and to do the actual work of adding the symbols to
-the linker hash table.
-
- The function passed to `_bfd_generic_link_add_archive_symbols' must
-read the symbols of the archive element and decide whether the archive
-element should be included in the link. If the element is to be
-included, the `add_archive_element' linker callback routine must be
-called with the element as an argument, and the elements symbols must
-be added to the linker hash table just as though the element had itself
-been passed to the `_bfd_link_add_symbols' function.
-
- When the a.out `_bfd_link_add_symbols' function receives an archive,
-it calls `_bfd_generic_link_add_archive_symbols' passing
-`aout_link_check_archive_element' as the function argument.
-`aout_link_check_archive_element' calls `aout_link_check_ar_symbols'.
-If the latter decides to add the element (an element is only added if
-it provides a real, non-common, definition for a previously undefined
-or common symbol) it calls the `add_archive_element' callback and then
-`aout_link_check_archive_element' calls `aout_link_add_symbols' to
-actually add the symbols to the linker hash table.
-
- The ECOFF back end is unusual in that it does not normally call
-`_bfd_generic_link_add_archive_symbols', because ECOFF archives already
-contain a hash table of symbols. The ECOFF back end searches the
-archive itself to avoid the overhead of creating a new hash table.
-
-\1f
-File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions
-
-2.17.3 Performing the final link
---------------------------------
-
-When all the input files have been processed, the linker calls the
-`_bfd_final_link' entry point of the output BFD. This routine is
-responsible for producing the final output file, which has several
-aspects. It must relocate the contents of the input sections and copy
-the data into the output sections. It must build an output symbol
-table including any local symbols from the input files and the global
-symbols from the hash table. When producing relocatable output, it must
-modify the input relocs and write them into the output file. There may
-also be object format dependent work to be done.
-
- The linker will also call the `write_object_contents' entry point
-when the BFD is closed. The two entry points must work together in
-order to produce the correct output file.
-
- The details of how this works are inevitably dependent upon the
-specific object file format. The a.out `_bfd_final_link' routine is
-`NAME(aout,final_link)'.
-
-* Menu:
-
-* Information provided by the linker::
-* Relocating the section contents::
-* Writing the symbol table::
-
-\1f
-File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link
-
-2.17.3.1 Information provided by the linker
-...........................................
-
-Before the linker calls the `_bfd_final_link' entry point, it sets up
-some data structures for the function to use.
-
- The `input_bfds' field of the `bfd_link_info' structure will point
-to a list of all the input files included in the link. These files are
-linked through the `link_next' field of the `bfd' structure.
-
- Each section in the output file will have a list of `link_order'
-structures attached to the `map_head.link_order' field (the
-`link_order' structure is defined in `bfdlink.h'). These structures
-describe how to create the contents of the output section in terms of
-the contents of various input sections, fill constants, and,
-eventually, other types of information. They also describe relocs that
-must be created by the BFD backend, but do not correspond to any input
-file; this is used to support -Ur, which builds constructors while
-generating a relocatable object file.
-
-\1f
-File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link
-
-2.17.3.2 Relocating the section contents
-........................................
-
-The `_bfd_final_link' function should look through the `link_order'
-structures attached to each section of the output file. Each
-`link_order' structure should either be handled specially, or it should
-be passed to the function `_bfd_default_link_order' which will do the
-right thing (`_bfd_default_link_order' is defined in `linker.c').
-
- For efficiency, a `link_order' of type `bfd_indirect_link_order'
-whose associated section belongs to a BFD of the same format as the
-output BFD must be handled specially. This type of `link_order'
-describes part of an output section in terms of a section belonging to
-one of the input files. The `_bfd_final_link' function should read the
-contents of the section and any associated relocs, apply the relocs to
-the section contents, and write out the modified section contents. If
-performing a relocatable link, the relocs themselves must also be
-modified and written out.
-
- The functions `_bfd_relocate_contents' and
-`_bfd_final_link_relocate' provide some general support for performing
-the actual relocations, notably overflow checking. Their arguments
-include information about the symbol the relocation is against and a
-`reloc_howto_type' argument which describes the relocation to perform.
-These functions are defined in `reloc.c'.
-
- The a.out function which handles reading, relocating, and writing
-section contents is `aout_link_input_section'. The actual relocation
-is done in `aout_link_input_section_std' and
-`aout_link_input_section_ext'.
-
-\1f
-File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link
-
-2.17.3.3 Writing the symbol table
-.................................
-
-The `_bfd_final_link' function must gather all the symbols in the input
-files and write them out. It must also write out all the symbols in
-the global hash table. This must be controlled by the `strip' and
-`discard' fields of the `bfd_link_info' structure.
-
- The local symbols of the input files will not have been entered into
-the linker hash table. The `_bfd_final_link' routine must consider
-each input file and include the symbols in the output file. It may be
-convenient to do this when looking through the `link_order' structures,
-or it may be done by stepping through the `input_bfds' list.
-
- The `_bfd_final_link' routine must also traverse the global hash
-table to gather all the externally visible symbols. It is possible
-that most of the externally visible symbols may be written out when
-considering the symbols of each input file, but it is still necessary
-to traverse the hash table since the linker script may have defined
-some symbols that are not in any of the input files.
-
- The `strip' field of the `bfd_link_info' structure controls which
-symbols are written out. The possible values are listed in
-`bfdlink.h'. If the value is `strip_some', then the `keep_hash' field
-of the `bfd_link_info' structure is a hash table of symbols to keep;
-each symbol should be looked up in this hash table, and only symbols
-which are present should be included in the output file.
-
- If the `strip' field of the `bfd_link_info' structure permits local
-symbols to be written out, the `discard' field is used to further
-controls which local symbols are included in the output file. If the
-value is `discard_l', then all local symbols which begin with a certain
-prefix are discarded; this is controlled by the
-`bfd_is_local_label_name' entry point.
-
- The a.out backend handles symbols by calling
-`aout_link_write_symbols' on each input BFD and then traversing the
-global hash table with the function `aout_link_write_other_symbol'. It
-builds a string table while writing out the symbols, which is written
-to the output file at the end of `NAME(aout,final_link)'.
-
-2.17.3.4 `bfd_link_split_section'
-.................................
-
-*Synopsis*
- bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec);
- *Description*
-Return nonzero if SEC should be split during a reloceatable or final
-link.
- #define bfd_link_split_section(abfd, sec) \
- BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))
-
-2.17.3.5 `bfd_section_already_linked'
-.....................................
-
-*Synopsis*
- void bfd_section_already_linked (bfd *abfd, asection *sec,
- struct bfd_link_info *info);
- *Description*
-Check if SEC has been already linked during a reloceatable or final
-link.
- #define bfd_section_already_linked(abfd, sec, info) \
- BFD_SEND (abfd, _section_already_linked, (abfd, sec, info))
-
-\1f
-File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end
-
-2.18 Hash Tables
-================
-
-BFD provides a simple set of hash table functions. Routines are
-provided to initialize a hash table, to free a hash table, to look up a
-string in a hash table and optionally create an entry for it, and to
-traverse a hash table. There is currently no routine to delete an
-string from a hash table.
-
- The basic hash table does not permit any data to be stored with a
-string. However, a hash table is designed to present a base class from
-which other types of hash tables may be derived. These derived types
-may store additional information with the string. Hash tables were
-implemented in this way, rather than simply providing a data pointer in
-a hash table entry, because they were designed for use by the linker
-back ends. The linker may create thousands of hash table entries, and
-the overhead of allocating private data and storing and following
-pointers becomes noticeable.
-
- The basic hash table code is in `hash.c'.
-
-* Menu:
-
-* Creating and Freeing a Hash Table::
-* Looking Up or Entering a String::
-* Traversing a Hash Table::
-* Deriving a New Hash Table Type::
-
-\1f
-File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables
-
-2.18.1 Creating and freeing a hash table
-----------------------------------------
-
-To create a hash table, create an instance of a `struct bfd_hash_table'
-(defined in `bfd.h') and call `bfd_hash_table_init' (if you know
-approximately how many entries you will need, the function
-`bfd_hash_table_init_n', which takes a SIZE argument, may be used).
-`bfd_hash_table_init' returns `FALSE' if some sort of error occurs.
-
- The function `bfd_hash_table_init' take as an argument a function to
-use to create new entries. For a basic hash table, use the function
-`bfd_hash_newfunc'. *Note Deriving a New Hash Table Type::, for why
-you would want to use a different value for this argument.
-
- `bfd_hash_table_init' will create an objalloc which will be used to
-allocate new entries. You may allocate memory on this objalloc using
-`bfd_hash_allocate'.
-
- Use `bfd_hash_table_free' to free up all the memory that has been
-allocated for a hash table. This will not free up the `struct
-bfd_hash_table' itself, which you must provide.
-
- Use `bfd_hash_set_default_size' to set the default size of hash
-table to use.
-
-\1f
-File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables
-
-2.18.2 Looking up or entering a string
---------------------------------------
-
-The function `bfd_hash_lookup' is used both to look up a string in the
-hash table and to create a new entry.
-
- If the CREATE argument is `FALSE', `bfd_hash_lookup' will look up a
-string. If the string is found, it will returns a pointer to a `struct
-bfd_hash_entry'. If the string is not found in the table
-`bfd_hash_lookup' will return `NULL'. You should not modify any of the
-fields in the returns `struct bfd_hash_entry'.
-
- If the CREATE argument is `TRUE', the string will be entered into
-the hash table if it is not already there. Either way a pointer to a
-`struct bfd_hash_entry' will be returned, either to the existing
-structure or to a newly created one. In this case, a `NULL' return
-means that an error occurred.
-
- If the CREATE argument is `TRUE', and a new entry is created, the
-COPY argument is used to decide whether to copy the string onto the
-hash table objalloc or not. If COPY is passed as `FALSE', you must be
-careful not to deallocate or modify the string as long as the hash table
-exists.
-
-\1f
-File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables
-
-2.18.3 Traversing a hash table
-------------------------------
-
-The function `bfd_hash_traverse' may be used to traverse a hash table,
-calling a function on each element. The traversal is done in a random
-order.
-
- `bfd_hash_traverse' takes as arguments a function and a generic
-`void *' pointer. The function is called with a hash table entry (a
-`struct bfd_hash_entry *') and the generic pointer passed to
-`bfd_hash_traverse'. The function must return a `boolean' value, which
-indicates whether to continue traversing the hash table. If the
-function returns `FALSE', `bfd_hash_traverse' will stop the traversal
-and return immediately.
-
-\1f
-File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables
-
-2.18.4 Deriving a new hash table type
--------------------------------------
-
-Many uses of hash tables want to store additional information which
-each entry in the hash table. Some also find it convenient to store
-additional information with the hash table itself. This may be done
-using a derived hash table.
-
- Since C is not an object oriented language, creating a derived hash
-table requires sticking together some boilerplate routines with a few
-differences specific to the type of hash table you want to create.
-
- An example of a derived hash table is the linker hash table. The
-structures for this are defined in `bfdlink.h'. The functions are in
-`linker.c'.
-
- You may also derive a hash table from an already derived hash table.
-For example, the a.out linker backend code uses a hash table derived
-from the linker hash table.
-
-* Menu:
-
-* Define the Derived Structures::
-* Write the Derived Creation Routine::
-* Write Other Derived Routines::
-
-\1f
-File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type
-
-2.18.4.1 Define the derived structures
-......................................
-
-You must define a structure for an entry in the hash table, and a
-structure for the hash table itself.
-
- The first field in the structure for an entry in the hash table must
-be of the type used for an entry in the hash table you are deriving
-from. If you are deriving from a basic hash table this is `struct
-bfd_hash_entry', which is defined in `bfd.h'. The first field in the
-structure for the hash table itself must be of the type of the hash
-table you are deriving from itself. If you are deriving from a basic
-hash table, this is `struct bfd_hash_table'.
-
- For example, the linker hash table defines `struct
-bfd_link_hash_entry' (in `bfdlink.h'). The first field, `root', is of
-type `struct bfd_hash_entry'. Similarly, the first field in `struct
-bfd_link_hash_table', `table', is of type `struct bfd_hash_table'.
-
-\1f
-File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type
-
-2.18.4.2 Write the derived creation routine
-...........................................
-
-You must write a routine which will create and initialize an entry in
-the hash table. This routine is passed as the function argument to
-`bfd_hash_table_init'.
-
- In order to permit other hash tables to be derived from the hash
-table you are creating, this routine must be written in a standard way.
-
- The first argument to the creation routine is a pointer to a hash
-table entry. This may be `NULL', in which case the routine should
-allocate the right amount of space. Otherwise the space has already
-been allocated by a hash table type derived from this one.
-
- After allocating space, the creation routine must call the creation
-routine of the hash table type it is derived from, passing in a pointer
-to the space it just allocated. This will initialize any fields used
-by the base hash table.
-
- Finally the creation routine must initialize any local fields for
-the new hash table type.
-
- Here is a boilerplate example of a creation routine. FUNCTION_NAME
-is the name of the routine. ENTRY_TYPE is the type of an entry in the
-hash table you are creating. BASE_NEWFUNC is the name of the creation
-routine of the hash table type your hash table is derived from.
-
- struct bfd_hash_entry *
- FUNCTION_NAME (struct bfd_hash_entry *entry,
- struct bfd_hash_table *table,
- const char *string)
- {
- struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry;
-
- /* Allocate the structure if it has not already been allocated by a
- derived class. */
- if (ret == NULL)
- {
- ret = bfd_hash_allocate (table, sizeof (* ret));
- if (ret == NULL)
- return NULL;
- }
-
- /* Call the allocation method of the base class. */
- ret = ((ENTRY_TYPE *)
- BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string));
-
- /* Initialize the local fields here. */
-
- return (struct bfd_hash_entry *) ret;
- }
- *Description*
-The creation routine for the linker hash table, which is in `linker.c',
-looks just like this example. FUNCTION_NAME is
-`_bfd_link_hash_newfunc'. ENTRY_TYPE is `struct bfd_link_hash_entry'.
-BASE_NEWFUNC is `bfd_hash_newfunc', the creation routine for a basic
-hash table.
-
- `_bfd_link_hash_newfunc' also initializes the local fields in a
-linker hash table entry: `type', `written' and `next'.
-
-\1f
-File: bfd.info, Node: Write Other Derived Routines, Prev: Write the Derived Creation Routine, Up: Deriving a New Hash Table Type
-
-2.18.4.3 Write other derived routines
-.....................................
-
-You will want to write other routines for your new hash table, as well.
-
- You will want an initialization routine which calls the
-initialization routine of the hash table you are deriving from and
-initializes any other local fields. For the linker hash table, this is
-`_bfd_link_hash_table_init' in `linker.c'.
-
- You will want a lookup routine which calls the lookup routine of the
-hash table you are deriving from and casts the result. The linker hash
-table uses `bfd_link_hash_lookup' in `linker.c' (this actually takes an
-additional argument which it uses to decide how to return the looked up
-value).
-
- You may want a traversal routine. This should just call the
-traversal routine of the hash table you are deriving from with
-appropriate casts. The linker hash table uses `bfd_link_hash_traverse'
-in `linker.c'.
-
- These routines may simply be defined as macros. For example, the
-a.out backend linker hash table, which is derived from the linker hash
-table, uses macros for the lookup and traversal routines. These are
-`aout_link_hash_lookup' and `aout_link_hash_traverse' in aoutx.h.
-
-\1f
-File: bfd.info, Node: BFD back ends, Next: GNU Free Documentation License, Prev: BFD front end, Up: Top
-
-3 BFD back ends
-***************
-
-* Menu:
-
-* What to Put Where::
-* aout :: a.out backends
-* coff :: coff backends
-* elf :: elf backends
-* mmo :: mmo backend
-
-\1f
-File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back ends, Up: BFD back ends
-
-3.1 What to Put Where
-=====================
-
-All of BFD lives in one directory.
-
-\1f
-File: bfd.info, Node: aout, Next: coff, Prev: What to Put Where, Up: BFD back ends
-
-3.2 a.out backends
-==================
-
-*Description*
-BFD supports a number of different flavours of a.out format, though the
-major differences are only the sizes of the structures on disk, and the
-shape of the relocation information.
-
- The support is split into a basic support file `aoutx.h' and other
-files which derive functions from the base. One derivation file is
-`aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions
-support for sun3, sun4, 386 and 29k a.out files, to create a target
-jump vector for a specific target.
-
- This information is further split out into more specific files for
-each machine, including `sunos.c' for sun3 and sun4, `newsos3.c' for
-the Sony NEWS, and `demo64.c' for a demonstration of a 64 bit a.out
-format.
-
- The base file `aoutx.h' defines general mechanisms for reading and
-writing records to and from disk and various other methods which BFD
-requires. It is included by `aout32.c' and `aout64.c' to form the names
-`aout_32_swap_exec_header_in', `aout_64_swap_exec_header_in', etc.
-
- As an example, this is what goes on to make the back end for a sun4,
-from `aout32.c':
-
- #define ARCH_SIZE 32
- #include "aoutx.h"
-
- Which exports names:
-
- ...
- aout_32_canonicalize_reloc
- aout_32_find_nearest_line
- aout_32_get_lineno
- aout_32_get_reloc_upper_bound
- ...
-
- from `sunos.c':
-
- #define TARGET_NAME "a.out-sunos-big"
- #define VECNAME sunos_big_vec
- #include "aoutf1.h"
-
- requires all the names from `aout32.c', and produces the jump vector
-
- sunos_big_vec
-
- The file `host-aout.c' is a special case. It is for a large set of
-hosts that use "more or less standard" a.out files, and for which
-cross-debugging is not interesting. It uses the standard 32-bit a.out
-support routines, but determines the file offsets and addresses of the
-text, data, and BSS sections, the machine architecture and machine
-type, and the entry point address, in a host-dependent manner. Once
-these values have been determined, generic code is used to handle the
-object file.
-
- When porting it to run on a new system, you must supply:
-
- HOST_PAGE_SIZE
- HOST_SEGMENT_SIZE
- HOST_MACHINE_ARCH (optional)
- HOST_MACHINE_MACHINE (optional)
- HOST_TEXT_START_ADDR
- HOST_STACK_END_ADDR
-
- in the file `../include/sys/h-XXX.h' (for your host). These values,
-plus the structures and macros defined in `a.out.h' on your host
-system, will produce a BFD target that will access ordinary a.out files
-on your host. To configure a new machine to use `host-aout.c', specify:
-
- TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
- TDEPFILES= host-aout.o trad-core.o
-
- in the `config/XXX.mt' file, and modify `configure.in' to use the
-`XXX.mt' file (by setting "`bfd_target=XXX'") when your configuration
-is selected.
-
-3.2.1 Relocations
------------------
-
-*Description*
-The file `aoutx.h' provides for both the _standard_ and _extended_
-forms of a.out relocation records.
-
- The standard records contain only an address, a symbol index, and a
-type field. The extended records (used on 29ks and sparcs) also have a
-full integer for an addend.
-
-3.2.2 Internal entry points
----------------------------
-
-*Description*
-`aoutx.h' exports several routines for accessing the contents of an
-a.out file, which are gathered and exported in turn by various format
-specific files (eg sunos.c).
-
-3.2.2.1 `aout_SIZE_swap_exec_header_in'
-.......................................
-
-*Synopsis*
- void aout_SIZE_swap_exec_header_in,
- (bfd *abfd,
- struct external_exec *bytes,
- struct internal_exec *execp);
- *Description*
-Swap the information in an executable header RAW_BYTES taken from a raw
-byte stream memory image into the internal exec header structure EXECP.
-
-3.2.2.2 `aout_SIZE_swap_exec_header_out'
-........................................
-
-*Synopsis*
- void aout_SIZE_swap_exec_header_out
- (bfd *abfd,
- struct internal_exec *execp,
- struct external_exec *raw_bytes);
- *Description*
-Swap the information in an internal exec header structure EXECP into
-the buffer RAW_BYTES ready for writing to disk.
-
-3.2.2.3 `aout_SIZE_some_aout_object_p'
-......................................
-
-*Synopsis*
- const bfd_target *aout_SIZE_some_aout_object_p
- (bfd *abfd,
- struct internal_exec *execp,
- const bfd_target *(*callback_to_real_object_p) (bfd *));
- *Description*
-Some a.out variant thinks that the file open in ABFD checking is an
-a.out file. Do some more checking, and set up for access if it really
-is. Call back to the calling environment's "finish up" function just
-before returning, to handle any last-minute setup.
-
-3.2.2.4 `aout_SIZE_mkobject'
-............................
-
-*Synopsis*
- bfd_boolean aout_SIZE_mkobject, (bfd *abfd);
- *Description*
-Initialize BFD ABFD for use with a.out files.
-
-3.2.2.5 `aout_SIZE_machine_type'
-................................
-
-*Synopsis*
- enum machine_type aout_SIZE_machine_type
- (enum bfd_architecture arch,
- unsigned long machine,
- bfd_boolean *unknown);
- *Description*
-Keep track of machine architecture and machine type for a.out's. Return
-the `machine_type' for a particular architecture and machine, or
-`M_UNKNOWN' if that exact architecture and machine can't be represented
-in a.out format.
-
- If the architecture is understood, machine type 0 (default) is
-always understood.
-
-3.2.2.6 `aout_SIZE_set_arch_mach'
-.................................
-
-*Synopsis*
- bfd_boolean aout_SIZE_set_arch_mach,
- (bfd *,
- enum bfd_architecture arch,
- unsigned long machine);
- *Description*
-Set the architecture and the machine of the BFD ABFD to the values ARCH
-and MACHINE. Verify that ABFD's format can support the architecture
-required.
-
-3.2.2.7 `aout_SIZE_new_section_hook'
-....................................
-
-*Synopsis*
- bfd_boolean aout_SIZE_new_section_hook,
- (bfd *abfd,
- asection *newsect);
- *Description*
-Called by the BFD in response to a `bfd_make_section' request.
-
-\1f
-File: bfd.info, Node: coff, Next: elf, Prev: aout, Up: BFD back ends
-
-3.3 coff backends
-=================
-
-BFD supports a number of different flavours of coff format. The major
-differences between formats are the sizes and alignments of fields in
-structures on disk, and the occasional extra field.
-
- Coff in all its varieties is implemented with a few common files and
-a number of implementation specific files. For example, The 88k bcs
-coff format is implemented in the file `coff-m88k.c'. This file
-`#include's `coff/m88k.h' which defines the external structure of the
-coff format for the 88k, and `coff/internal.h' which defines the
-internal structure. `coff-m88k.c' also defines the relocations used by
-the 88k format *Note Relocations::.
-
- The Intel i960 processor version of coff is implemented in
-`coff-i960.c'. This file has the same structure as `coff-m88k.c',
-except that it includes `coff/i960.h' rather than `coff-m88k.h'.
-
-3.3.1 Porting to a new version of coff
---------------------------------------
-
-The recommended method is to select from the existing implementations
-the version of coff which is most like the one you want to use. For
-example, we'll say that i386 coff is the one you select, and that your
-coff flavour is called foo. Copy `i386coff.c' to `foocoff.c', copy
-`../include/coff/i386.h' to `../include/coff/foo.h', and add the lines
-to `targets.c' and `Makefile.in' so that your new back end is used.
-Alter the shapes of the structures in `../include/coff/foo.h' so that
-they match what you need. You will probably also have to add `#ifdef's
-to the code in `coff/internal.h' and `coffcode.h' if your version of
-coff is too wild.
-
- You can verify that your new BFD backend works quite simply by
-building `objdump' from the `binutils' directory, and making sure that
-its version of what's going on and your host system's idea (assuming it
-has the pretty standard coff dump utility, usually called `att-dump' or
-just `dump') are the same. Then clean up your code, and send what
-you've done to Cygnus. Then your stuff will be in the next release, and
-you won't have to keep integrating it.
-
-3.3.2 How the coff backend works
---------------------------------
-
-3.3.2.1 File layout
-...................
-
-The Coff backend is split into generic routines that are applicable to
-any Coff target and routines that are specific to a particular target.
-The target-specific routines are further split into ones which are
-basically the same for all Coff targets except that they use the
-external symbol format or use different values for certain constants.
-
- The generic routines are in `coffgen.c'. These routines work for
-any Coff target. They use some hooks into the target specific code;
-the hooks are in a `bfd_coff_backend_data' structure, one of which
-exists for each target.
-
- The essentially similar target-specific routines are in
-`coffcode.h'. This header file includes executable C code. The
-various Coff targets first include the appropriate Coff header file,
-make any special defines that are needed, and then include `coffcode.h'.
-
- Some of the Coff targets then also have additional routines in the
-target source file itself.
-
- For example, `coff-i960.c' includes `coff/internal.h' and
-`coff/i960.h'. It then defines a few constants, such as `I960', and
-includes `coffcode.h'. Since the i960 has complex relocation types,
-`coff-i960.c' also includes some code to manipulate the i960 relocs.
-This code is not in `coffcode.h' because it would not be used by any
-other target.
-
-3.3.2.2 Bit twiddling
-.....................
-
-Each flavour of coff supported in BFD has its own header file
-describing the external layout of the structures. There is also an
-internal description of the coff layout, in `coff/internal.h'. A major
-function of the coff backend is swapping the bytes and twiddling the
-bits to translate the external form of the structures into the normal
-internal form. This is all performed in the `bfd_swap'_thing_direction
-routines. Some elements are different sizes between different versions
-of coff; it is the duty of the coff version specific include file to
-override the definitions of various packing routines in `coffcode.h'.
-E.g., the size of line number entry in coff is sometimes 16 bits, and
-sometimes 32 bits. `#define'ing `PUT_LNSZ_LNNO' and `GET_LNSZ_LNNO'
-will select the correct one. No doubt, some day someone will find a
-version of coff which has a varying field size not catered to at the
-moment. To port BFD, that person will have to add more `#defines'.
-Three of the bit twiddling routines are exported to `gdb';
-`coff_swap_aux_in', `coff_swap_sym_in' and `coff_swap_lineno_in'. `GDB'
-reads the symbol table on its own, but uses BFD to fix things up. More
-of the bit twiddlers are exported for `gas'; `coff_swap_aux_out',
-`coff_swap_sym_out', `coff_swap_lineno_out', `coff_swap_reloc_out',
-`coff_swap_filehdr_out', `coff_swap_aouthdr_out',
-`coff_swap_scnhdr_out'. `Gas' currently keeps track of all the symbol
-table and reloc drudgery itself, thereby saving the internal BFD
-overhead, but uses BFD to swap things on the way out, making cross
-ports much safer. Doing so also allows BFD (and thus the linker) to
-use the same header files as `gas', which makes one avenue to disaster
-disappear.
-
-3.3.2.3 Symbol reading
-......................
-
-The simple canonical form for symbols used by BFD is not rich enough to
-keep all the information available in a coff symbol table. The back end
-gets around this problem by keeping the original symbol table around,
-"behind the scenes".
-
- When a symbol table is requested (through a call to
-`bfd_canonicalize_symtab'), a request gets through to
-`coff_get_normalized_symtab'. This reads the symbol table from the coff
-file and swaps all the structures inside into the internal form. It
-also fixes up all the pointers in the table (represented in the file by
-offsets from the first symbol in the table) into physical pointers to
-elements in the new internal table. This involves some work since the
-meanings of fields change depending upon context: a field that is a
-pointer to another structure in the symbol table at one moment may be
-the size in bytes of a structure at the next. Another pass is made
-over the table. All symbols which mark file names (`C_FILE' symbols)
-are modified so that the internal string points to the value in the
-auxent (the real filename) rather than the normal text associated with
-the symbol (`".file"').
-
- At this time the symbol names are moved around. Coff stores all
-symbols less than nine characters long physically within the symbol
-table; longer strings are kept at the end of the file in the string
-table. This pass moves all strings into memory and replaces them with
-pointers to the strings.
-
- The symbol table is massaged once again, this time to create the
-canonical table used by the BFD application. Each symbol is inspected
-in turn, and a decision made (using the `sclass' field) about the
-various flags to set in the `asymbol'. *Note Symbols::. The generated
-canonical table shares strings with the hidden internal symbol table.
-
- Any linenumbers are read from the coff file too, and attached to the
-symbols which own the functions the linenumbers belong to.
-
-3.3.2.4 Symbol writing
-......................
-
-Writing a symbol to a coff file which didn't come from a coff file will
-lose any debugging information. The `asymbol' structure remembers the
-BFD from which the symbol was taken, and on output the back end makes
-sure that the same destination target as source target is present.
-
- When the symbols have come from a coff file then all the debugging
-information is preserved.
-
- Symbol tables are provided for writing to the back end in a vector
-of pointers to pointers. This allows applications like the linker to
-accumulate and output large symbol tables without having to do too much
-byte copying.
-
- This function runs through the provided symbol table and patches
-each symbol marked as a file place holder (`C_FILE') to point to the
-next file place holder in the list. It also marks each `offset' field
-in the list with the offset from the first symbol of the current symbol.
-
- Another function of this procedure is to turn the canonical value
-form of BFD into the form used by coff. Internally, BFD expects symbol
-values to be offsets from a section base; so a symbol physically at
-0x120, but in a section starting at 0x100, would have the value 0x20.
-Coff expects symbols to contain their final value, so symbols have
-their values changed at this point to reflect their sum with their
-owning section. This transformation uses the `output_section' field of
-the `asymbol''s `asection' *Note Sections::.
-
- * `coff_mangle_symbols'
- This routine runs though the provided symbol table and uses the
-offsets generated by the previous pass and the pointers generated when
-the symbol table was read in to create the structured hierarchy
-required by coff. It changes each pointer to a symbol into the index
-into the symbol table of the asymbol.
-
- * `coff_write_symbols'
- This routine runs through the symbol table and patches up the
-symbols from their internal form into the coff way, calls the bit
-twiddlers, and writes out the table to the file.
-
-3.3.2.5 `coff_symbol_type'
-..........................
-
-*Description*
-The hidden information for an `asymbol' is described in a
-`combined_entry_type':
-
-
- typedef struct coff_ptr_struct
- {
- /* Remembers the offset from the first symbol in the file for
- this symbol. Generated by coff_renumber_symbols. */
- unsigned int offset;
-
- /* Should the value of this symbol be renumbered. Used for
- XCOFF C_BSTAT symbols. Set by coff_slurp_symbol_table. */
- unsigned int fix_value : 1;
-
- /* Should the tag field of this symbol be renumbered.
- Created by coff_pointerize_aux. */
- unsigned int fix_tag : 1;
-
- /* Should the endidx field of this symbol be renumbered.
- Created by coff_pointerize_aux. */
- unsigned int fix_end : 1;
-
- /* Should the x_csect.x_scnlen field be renumbered.
- Created by coff_pointerize_aux. */
- unsigned int fix_scnlen : 1;
-
- /* Fix up an XCOFF C_BINCL/C_EINCL symbol. The value is the
- index into the line number entries. Set by coff_slurp_symbol_table. */
- unsigned int fix_line : 1;
-
- /* The container for the symbol structure as read and translated
- from the file. */
- union
- {
- union internal_auxent auxent;
- struct internal_syment syment;
- } u;
- } combined_entry_type;
-
-
- /* Each canonical asymbol really looks like this: */
-
- typedef struct coff_symbol_struct
- {
- /* The actual symbol which the rest of BFD works with */
- asymbol symbol;
-
- /* A pointer to the hidden information for this symbol */
- combined_entry_type *native;
-
- /* A pointer to the linenumber information for this symbol */
- struct lineno_cache_entry *lineno;
-
- /* Have the line numbers been relocated yet ? */
- bfd_boolean done_lineno;
- } coff_symbol_type;
-
-3.3.2.6 `bfd_coff_backend_data'
-...............................
-
- /* COFF symbol classifications. */
-
- enum coff_symbol_classification
- {
- /* Global symbol. */
- COFF_SYMBOL_GLOBAL,
- /* Common symbol. */
- COFF_SYMBOL_COMMON,
- /* Undefined symbol. */
- COFF_SYMBOL_UNDEFINED,
- /* Local symbol. */
- COFF_SYMBOL_LOCAL,
- /* PE section symbol. */
- COFF_SYMBOL_PE_SECTION
- };
-Special entry points for gdb to swap in coff symbol table parts:
- typedef struct
- {
- void (*_bfd_coff_swap_aux_in)
- (bfd *, void *, int, int, int, int, void *);
-
- void (*_bfd_coff_swap_sym_in)
- (bfd *, void *, void *);
-
- void (*_bfd_coff_swap_lineno_in)
- (bfd *, void *, void *);
-
- unsigned int (*_bfd_coff_swap_aux_out)
- (bfd *, void *, int, int, int, int, void *);
-
- unsigned int (*_bfd_coff_swap_sym_out)
- (bfd *, void *, void *);
-
- unsigned int (*_bfd_coff_swap_lineno_out)
- (bfd *, void *, void *);
-
- unsigned int (*_bfd_coff_swap_reloc_out)
- (bfd *, void *, void *);
-
- unsigned int (*_bfd_coff_swap_filehdr_out)
- (bfd *, void *, void *);
-
- unsigned int (*_bfd_coff_swap_aouthdr_out)
- (bfd *, void *, void *);
-
- unsigned int (*_bfd_coff_swap_scnhdr_out)
- (bfd *, void *, void *);
-
- unsigned int _bfd_filhsz;
- unsigned int _bfd_aoutsz;
- unsigned int _bfd_scnhsz;
- unsigned int _bfd_symesz;
- unsigned int _bfd_auxesz;
- unsigned int _bfd_relsz;
- unsigned int _bfd_linesz;
- unsigned int _bfd_filnmlen;
- bfd_boolean _bfd_coff_long_filenames;
- bfd_boolean _bfd_coff_long_section_names;
- unsigned int _bfd_coff_default_section_alignment_power;
- bfd_boolean _bfd_coff_force_symnames_in_strings;
- unsigned int _bfd_coff_debug_string_prefix_length;
-
- void (*_bfd_coff_swap_filehdr_in)
- (bfd *, void *, void *);
-
- void (*_bfd_coff_swap_aouthdr_in)
- (bfd *, void *, void *);
-
- void (*_bfd_coff_swap_scnhdr_in)
- (bfd *, void *, void *);
-
- void (*_bfd_coff_swap_reloc_in)
- (bfd *abfd, void *, void *);
-
- bfd_boolean (*_bfd_coff_bad_format_hook)
- (bfd *, void *);
-
- bfd_boolean (*_bfd_coff_set_arch_mach_hook)
- (bfd *, void *);
-
- void * (*_bfd_coff_mkobject_hook)
- (bfd *, void *, void *);
-
- bfd_boolean (*_bfd_styp_to_sec_flags_hook)
- (bfd *, void *, const char *, asection *, flagword *);
-
- void (*_bfd_set_alignment_hook)
- (bfd *, asection *, void *);
-
- bfd_boolean (*_bfd_coff_slurp_symbol_table)
- (bfd *);
-
- bfd_boolean (*_bfd_coff_symname_in_debug)
- (bfd *, struct internal_syment *);
-
- bfd_boolean (*_bfd_coff_pointerize_aux_hook)
- (bfd *, combined_entry_type *, combined_entry_type *,
- unsigned int, combined_entry_type *);
-
- bfd_boolean (*_bfd_coff_print_aux)
- (bfd *, FILE *, combined_entry_type *, combined_entry_type *,
- combined_entry_type *, unsigned int);
-
- void (*_bfd_coff_reloc16_extra_cases)
- (bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *,
- bfd_byte *, unsigned int *, unsigned int *);
-
- int (*_bfd_coff_reloc16_estimate)
- (bfd *, asection *, arelent *, unsigned int,
- struct bfd_link_info *);
-
- enum coff_symbol_classification (*_bfd_coff_classify_symbol)
- (bfd *, struct internal_syment *);
-
- bfd_boolean (*_bfd_coff_compute_section_file_positions)
- (bfd *);
-
- bfd_boolean (*_bfd_coff_start_final_link)
- (bfd *, struct bfd_link_info *);
-
- bfd_boolean (*_bfd_coff_relocate_section)
- (bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *,
- struct internal_reloc *, struct internal_syment *, asection **);
-
- reloc_howto_type *(*_bfd_coff_rtype_to_howto)
- (bfd *, asection *, struct internal_reloc *,
- struct coff_link_hash_entry *, struct internal_syment *,
- bfd_vma *);
-
- bfd_boolean (*_bfd_coff_adjust_symndx)
- (bfd *, struct bfd_link_info *, bfd *, asection *,
- struct internal_reloc *, bfd_boolean *);
-
- bfd_boolean (*_bfd_coff_link_add_one_symbol)
- (struct bfd_link_info *, bfd *, const char *, flagword,
- asection *, bfd_vma, const char *, bfd_boolean, bfd_boolean,
- struct bfd_link_hash_entry **);
-
- bfd_boolean (*_bfd_coff_link_output_has_begun)
- (bfd *, struct coff_final_link_info *);
-
- bfd_boolean (*_bfd_coff_final_link_postscript)
- (bfd *, struct coff_final_link_info *);
-
- } bfd_coff_backend_data;
-
- #define coff_backend_info(abfd) \
- ((bfd_coff_backend_data *) (abfd)->xvec->backend_data)
-
- #define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \
- ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i))
-
- #define bfd_coff_swap_sym_in(a,e,i) \
- ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i))
-
- #define bfd_coff_swap_lineno_in(a,e,i) \
- ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i))
-
- #define bfd_coff_swap_reloc_out(abfd, i, o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o))
-
- #define bfd_coff_swap_lineno_out(abfd, i, o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o))
-
- #define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \
- ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o))
-
- #define bfd_coff_swap_sym_out(abfd, i,o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o))
-
- #define bfd_coff_swap_scnhdr_out(abfd, i,o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o))
-
- #define bfd_coff_swap_filehdr_out(abfd, i,o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o))
-
- #define bfd_coff_swap_aouthdr_out(abfd, i,o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o))
-
- #define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz)
- #define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz)
- #define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz)
- #define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz)
- #define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz)
- #define bfd_coff_relsz(abfd) (coff_backend_info (abfd)->_bfd_relsz)
- #define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz)
- #define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen)
- #define bfd_coff_long_filenames(abfd) \
- (coff_backend_info (abfd)->_bfd_coff_long_filenames)
- #define bfd_coff_long_section_names(abfd) \
- (coff_backend_info (abfd)->_bfd_coff_long_section_names)
- #define bfd_coff_default_section_alignment_power(abfd) \
- (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power)
- #define bfd_coff_swap_filehdr_in(abfd, i,o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o))
-
- #define bfd_coff_swap_aouthdr_in(abfd, i,o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o))
-
- #define bfd_coff_swap_scnhdr_in(abfd, i,o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o))
-
- #define bfd_coff_swap_reloc_in(abfd, i, o) \
- ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o))
-
- #define bfd_coff_bad_format_hook(abfd, filehdr) \
- ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr))
-
- #define bfd_coff_set_arch_mach_hook(abfd, filehdr)\
- ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr))
- #define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\
- ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook)\
- (abfd, filehdr, aouthdr))
-
- #define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section, flags_ptr)\
- ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\
- (abfd, scnhdr, name, section, flags_ptr))
-
- #define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\
- ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr))
-
- #define bfd_coff_slurp_symbol_table(abfd)\
- ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd))
-
- #define bfd_coff_symname_in_debug(abfd, sym)\
- ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym))
-
- #define bfd_coff_force_symnames_in_strings(abfd)\
- (coff_backend_info (abfd)->_bfd_coff_force_symnames_in_strings)
-
- #define bfd_coff_debug_string_prefix_length(abfd)\
- (coff_backend_info (abfd)->_bfd_coff_debug_string_prefix_length)
-
- #define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\
- ((coff_backend_info (abfd)->_bfd_coff_print_aux)\
- (abfd, file, base, symbol, aux, indaux))
-
- #define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order,\
- reloc, data, src_ptr, dst_ptr)\
- ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\
- (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr))
-
- #define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\
- ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\
- (abfd, section, reloc, shrink, link_info))
-
- #define bfd_coff_classify_symbol(abfd, sym)\
- ((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\
- (abfd, sym))
-
- #define bfd_coff_compute_section_file_positions(abfd)\
- ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\
- (abfd))
-
- #define bfd_coff_start_final_link(obfd, info)\
- ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\
- (obfd, info))
- #define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\
- ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\
- (obfd, info, ibfd, o, con, rel, isyms, secs))
- #define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\
- ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\
- (abfd, sec, rel, h, sym, addendp))
- #define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\
- ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\
- (obfd, info, ibfd, sec, rel, adjustedp))
- #define bfd_coff_link_add_one_symbol(info, abfd, name, flags, section,\
- value, string, cp, coll, hashp)\
- ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\
- (info, abfd, name, flags, section, value, string, cp, coll, hashp))
-
- #define bfd_coff_link_output_has_begun(a,p) \
- ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a, p))
- #define bfd_coff_final_link_postscript(a,p) \
- ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a, p))
-
-3.3.2.7 Writing relocations
-...........................
-
-To write relocations, the back end steps though the canonical
-relocation table and create an `internal_reloc'. The symbol index to
-use is removed from the `offset' field in the symbol table supplied.
-The address comes directly from the sum of the section base address and
-the relocation offset; the type is dug directly from the howto field.
-Then the `internal_reloc' is swapped into the shape of an
-`external_reloc' and written out to disk.
-
-3.3.2.8 Reading linenumbers
-...........................
-
-Creating the linenumber table is done by reading in the entire coff
-linenumber table, and creating another table for internal use.
-
- A coff linenumber table is structured so that each function is
-marked as having a line number of 0. Each line within the function is
-an offset from the first line in the function. The base of the line
-number information for the table is stored in the symbol associated
-with the function.
-
- Note: The PE format uses line number 0 for a flag indicating a new
-source file.
-
- The information is copied from the external to the internal table,
-and each symbol which marks a function is marked by pointing its...
-
- How does this work ?
-
-3.3.2.9 Reading relocations
-...........................
-
-Coff relocations are easily transformed into the internal BFD form
-(`arelent').
-
- Reading a coff relocation table is done in the following stages:
-
- * Read the entire coff relocation table into memory.
-
- * Process each relocation in turn; first swap it from the external
- to the internal form.
-
- * Turn the symbol referenced in the relocation's symbol index into a
- pointer into the canonical symbol table. This table is the same
- as the one returned by a call to `bfd_canonicalize_symtab'. The
- back end will call that routine and save the result if a
- canonicalization hasn't been done.
-
- * The reloc index is turned into a pointer to a howto structure, in
- a back end specific way. For instance, the 386 and 960 use the
- `r_type' to directly produce an index into a howto table vector;
- the 88k subtracts a number from the `r_type' field and creates an
- addend field.
-
-\1f
-File: bfd.info, Node: elf, Next: mmo, Prev: coff, Up: BFD back ends
-
-3.4 ELF backends
-================
-
-BFD support for ELF formats is being worked on. Currently, the best
-supported back ends are for sparc and i386 (running svr4 or Solaris 2).
-
- Documentation of the internals of the support code still needs to be
-written. The code is changing quickly enough that we haven't bothered
-yet.
-
-3.4.0.1 `bfd_elf_find_section'
-..............................
-
-*Synopsis*
- struct elf_internal_shdr *bfd_elf_find_section (bfd *abfd, char *name);
- *Description*
-Helper functions for GDB to locate the string tables. Since BFD hides
-string tables from callers, GDB needs to use an internal hook to find
-them. Sun's .stabstr, in particular, isn't even pointed to by the
-.stab section, so ordinary mechanisms wouldn't work to find it, even if
-we had some.
-
-\1f
-File: bfd.info, Node: mmo, Prev: elf, Up: BFD back ends
-
-3.5 mmo backend
-===============
-
-The mmo object format is used exclusively together with Professor
-Donald E. Knuth's educational 64-bit processor MMIX. The simulator
-`mmix' which is available at
-`http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz'
-understands this format. That package also includes a combined
-assembler and linker called `mmixal'. The mmo format has no advantages
-feature-wise compared to e.g. ELF. It is a simple non-relocatable
-object format with no support for archives or debugging information,
-except for symbol value information and line numbers (which is not yet
-implemented in BFD). See
-`http://www-cs-faculty.stanford.edu/~knuth/mmix.html' for more
-information about MMIX. The ELF format is used for intermediate object
-files in the BFD implementation.
-
-* Menu:
-
-* File layout::
-* Symbol-table::
-* mmo section mapping::
-
-\1f
-File: bfd.info, Node: File layout, Next: Symbol-table, Prev: mmo, Up: mmo
-
-3.5.1 File layout
------------------
-
-The mmo file contents is not partitioned into named sections as with
-e.g. ELF. Memory areas is formed by specifying the location of the
-data that follows. Only the memory area `0x0000...00' to `0x01ff...ff'
-is executable, so it is used for code (and constants) and the area
-`0x2000...00' to `0x20ff...ff' is used for writable data. *Note mmo
-section mapping::.
-
- There is provision for specifying "special data" of 65536 different
-types. We use type 80 (decimal), arbitrarily chosen the same as the
-ELF `e_machine' number for MMIX, filling it with section information
-normally found in ELF objects. *Note mmo section mapping::.
-
- Contents is entered as 32-bit words, xor:ed over previous contents,
-always zero-initialized. A word that starts with the byte `0x98' forms
-a command called a `lopcode', where the next byte distinguished between
-the thirteen lopcodes. The two remaining bytes, called the `Y' and `Z'
-fields, or the `YZ' field (a 16-bit big-endian number), are used for
-various purposes different for each lopcode. As documented in
-`http://www-cs-faculty.stanford.edu/~knuth/mmixal-intro.ps.gz', the
-lopcodes are:
-
-`lop_quote'
- 0x98000001. The next word is contents, regardless of whether it
- starts with 0x98 or not.
-
-`lop_loc'
- 0x9801YYZZ, where `Z' is 1 or 2. This is a location directive,
- setting the location for the next data to the next 32-bit word
- (for Z = 1) or 64-bit word (for Z = 2), plus Y * 2^56. Normally
- `Y' is 0 for the text segment and 2 for the data segment.
-
-`lop_skip'
- 0x9802YYZZ. Increase the current location by `YZ' bytes.
-
-`lop_fixo'
- 0x9803YYZZ, where `Z' is 1 or 2. Store the current location as 64
- bits into the location pointed to by the next 32-bit (Z = 1) or
- 64-bit (Z = 2) word, plus Y * 2^56.
-
-`lop_fixr'
- 0x9804YYZZ. `YZ' is stored into the current location plus 2 - 4 *
- YZ.
-
-`lop_fixrx'
- 0x980500ZZ. `Z' is 16 or 24. A value `L' derived from the
- following 32-bit word are used in a manner similar to `YZ' in
- lop_fixr: it is xor:ed into the current location minus 4 * L. The
- first byte of the word is 0 or 1. If it is 1, then L = (LOWEST 24
- BITS OF WORD) - 2^Z, if 0, then L = (LOWEST 24 BITS OF WORD).
-
-`lop_file'
- 0x9806YYZZ. `Y' is the file number, `Z' is count of 32-bit words.
- Set the file number to `Y' and the line counter to 0. The next Z
- * 4 bytes contain the file name, padded with zeros if the count is
- not a multiple of four. The same `Y' may occur multiple times,
- but `Z' must be 0 for all but the first occurrence.
-
-`lop_line'
- 0x9807YYZZ. `YZ' is the line number. Together with lop_file, it
- forms the source location for the next 32-bit word. Note that for
- each non-lopcode 32-bit word, line numbers are assumed incremented
- by one.
-
-`lop_spec'
- 0x9808YYZZ. `YZ' is the type number. Data until the next lopcode
- other than lop_quote forms special data of type `YZ'. *Note mmo
- section mapping::.
-
- Other types than 80, (or type 80 with a content that does not
- parse) is stored in sections named `.MMIX.spec_data.N' where N is
- the `YZ'-type. The flags for such a sections say not to allocate
- or load the data. The vma is 0. Contents of multiple occurrences
- of special data N is concatenated to the data of the previous
- lop_spec Ns. The location in data or code at which the lop_spec
- occurred is lost.
-
-`lop_pre'
- 0x980901ZZ. The first lopcode in a file. The `Z' field forms the
- length of header information in 32-bit words, where the first word
- tells the time in seconds since `00:00:00 GMT Jan 1 1970'.
-
-`lop_post'
- 0x980a00ZZ. Z > 32. This lopcode follows after all
- content-generating lopcodes in a program. The `Z' field denotes
- the value of `rG' at the beginning of the program. The following
- 256 - Z big-endian 64-bit words are loaded into global registers
- `$G' ... `$255'.
-
-`lop_stab'
- 0x980b0000. The next-to-last lopcode in a program. Must follow
- immediately after the lop_post lopcode and its data. After this
- lopcode follows all symbols in a compressed format (*note
- Symbol-table::).
-
-`lop_end'
- 0x980cYYZZ. The last lopcode in a program. It must follow the
- lop_stab lopcode and its data. The `YZ' field contains the number
- of 32-bit words of symbol table information after the preceding
- lop_stab lopcode.
-
- Note that the lopcode "fixups"; `lop_fixr', `lop_fixrx' and
-`lop_fixo' are not generated by BFD, but are handled. They are
-generated by `mmixal'.
-
- This trivial one-label, one-instruction file:
-
- :Main TRAP 1,2,3
-
- can be represented this way in mmo:
-
- 0x98090101 - lop_pre, one 32-bit word with timestamp.
- <timestamp>
- 0x98010002 - lop_loc, text segment, using a 64-bit address.
- Note that mmixal does not emit this for the file above.
- 0x00000000 - Address, high 32 bits.
- 0x00000000 - Address, low 32 bits.
- 0x98060002 - lop_file, 2 32-bit words for file-name.
- 0x74657374 - "test"
- 0x2e730000 - ".s\0\0"
- 0x98070001 - lop_line, line 1.
- 0x00010203 - TRAP 1,2,3
- 0x980a00ff - lop_post, setting $255 to 0.
- 0x00000000
- 0x00000000
- 0x980b0000 - lop_stab for ":Main" = 0, serial 1.
- 0x203a4040 *Note Symbol-table::.
- 0x10404020
- 0x4d206120
- 0x69016e00
- 0x81000000
- 0x980c0005 - lop_end; symbol table contained five 32-bit words.
-
-\1f
-File: bfd.info, Node: Symbol-table, Next: mmo section mapping, Prev: File layout, Up: mmo
-
-3.5.2 Symbol table format
--------------------------
-
-From mmixal.w (or really, the generated mmixal.tex) in
-`http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz'):
-"Symbols are stored and retrieved by means of a `ternary search trie',
-following ideas of Bentley and Sedgewick. (See ACM-SIAM Symp. on
-Discrete Algorithms `8' (1997), 360-369; R.Sedgewick, `Algorithms in C'
-(Reading, Mass. Addison-Wesley, 1998), `15.4'.) Each trie node stores
-a character, and there are branches to subtries for the cases where a
-given character is less than, equal to, or greater than the character
-in the trie. There also is a pointer to a symbol table entry if a
-symbol ends at the current node."
-
- So it's a tree encoded as a stream of bytes. The stream of bytes
-acts on a single virtual global symbol, adding and removing characters
-and signalling complete symbol points. Here, we read the stream and
-create symbols at the completion points.
-
- First, there's a control byte `m'. If any of the listed bits in `m'
-is nonzero, we execute what stands at the right, in the listed order:
-
- (MMO3_LEFT)
- 0x40 - Traverse left trie.
- (Read a new command byte and recurse.)
-
- (MMO3_SYMBITS)
- 0x2f - Read the next byte as a character and store it in the
- current character position; increment character position.
- Test the bits of `m':
-
- (MMO3_WCHAR)
- 0x80 - The character is 16-bit (so read another byte,
- merge into current character.
-
- (MMO3_TYPEBITS)
- 0xf - We have a complete symbol; parse the type, value
- and serial number and do what should be done
- with a symbol. The type and length information
- is in j = (m & 0xf).
-
- (MMO3_REGQUAL_BITS)
- j == 0xf: A register variable. The following
- byte tells which register.
- j <= 8: An absolute symbol. Read j bytes as the
- big-endian number the symbol equals.
- A j = 2 with two zero bytes denotes an
- unknown symbol.
- j > 8: As with j <= 8, but add (0x20 << 56)
- to the value in the following j - 8
- bytes.
-
- Then comes the serial number, as a variant of
- uleb128, but better named ubeb128:
- Read bytes and shift the previous value left 7
- (multiply by 128). Add in the new byte, repeat
- until a byte has bit 7 set. The serial number
- is the computed value minus 128.
-
- (MMO3_MIDDLE)
- 0x20 - Traverse middle trie. (Read a new command byte
- and recurse.) Decrement character position.
-
- (MMO3_RIGHT)
- 0x10 - Traverse right trie. (Read a new command byte and
- recurse.)
-
- Let's look again at the `lop_stab' for the trivial file (*note File
-layout::).
-
- 0x980b0000 - lop_stab for ":Main" = 0, serial 1.
- 0x203a4040
- 0x10404020
- 0x4d206120
- 0x69016e00
- 0x81000000
-
- This forms the trivial trie (note that the path between ":" and "M"
-is redundant):
-
- 203a ":"
- 40 /
- 40 /
- 10 \
- 40 /
- 40 /
- 204d "M"
- 2061 "a"
- 2069 "i"
- 016e "n" is the last character in a full symbol, and
- with a value represented in one byte.
- 00 The value is 0.
- 81 The serial number is 1.
-
-\1f
-File: bfd.info, Node: mmo section mapping, Prev: Symbol-table, Up: mmo
-
-3.5.3 mmo section mapping
--------------------------
-
-The implementation in BFD uses special data type 80 (decimal) to
-encapsulate and describe named sections, containing e.g. debug
-information. If needed, any datum in the encapsulation will be quoted
-using lop_quote. First comes a 32-bit word holding the number of
-32-bit words containing the zero-terminated zero-padded segment name.
-After the name there's a 32-bit word holding flags describing the
-section type. Then comes a 64-bit big-endian word with the section
-length (in bytes), then another with the section start address.
-Depending on the type of section, the contents might follow,
-zero-padded to 32-bit boundary. For a loadable section (such as data
-or code), the contents might follow at some later point, not
-necessarily immediately, as a lop_loc with the same start address as in
-the section description, followed by the contents. This in effect
-forms a descriptor that must be emitted before the actual contents.
-Sections described this way must not overlap.
-
- For areas that don't have such descriptors, synthetic sections are
-formed by BFD. Consecutive contents in the two memory areas
-`0x0000...00' to `0x01ff...ff' and `0x2000...00' to `0x20ff...ff' are
-entered in sections named `.text' and `.data' respectively. If an area
-is not otherwise described, but would together with a neighboring lower
-area be less than `0x40000000' bytes long, it is joined with the lower
-area and the gap is zero-filled. For other cases, a new section is
-formed, named `.MMIX.sec.N'. Here, N is a number, a running count
-through the mmo file, starting at 0.
-
- A loadable section specified as:
-
- .section secname,"ax"
- TETRA 1,2,3,4,-1,-2009
- BYTE 80
-
- and linked to address `0x4', is represented by the sequence:
-
- 0x98080050 - lop_spec 80
- 0x00000002 - two 32-bit words for the section name
- 0x7365636e - "secn"
- 0x616d6500 - "ame\0"
- 0x00000033 - flags CODE, READONLY, LOAD, ALLOC
- 0x00000000 - high 32 bits of section length
- 0x0000001c - section length is 28 bytes; 6 * 4 + 1 + alignment to 32 bits
- 0x00000000 - high 32 bits of section address
- 0x00000004 - section address is 4
- 0x98010002 - 64 bits with address of following data
- 0x00000000 - high 32 bits of address
- 0x00000004 - low 32 bits: data starts at address 4
- 0x00000001 - 1
- 0x00000002 - 2
- 0x00000003 - 3
- 0x00000004 - 4
- 0xffffffff - -1
- 0xfffff827 - -2009
- 0x50000000 - 80 as a byte, padded with zeros.
-
- Note that the lop_spec wrapping does not include the section
-contents. Compare this to a non-loaded section specified as:
-
- .section thirdsec
- TETRA 200001,100002
- BYTE 38,40
-
- This, when linked to address `0x200000000000001c', is represented by:
-
- 0x98080050 - lop_spec 80
- 0x00000002 - two 32-bit words for the section name
- 0x7365636e - "thir"
- 0x616d6500 - "dsec"
- 0x00000010 - flag READONLY
- 0x00000000 - high 32 bits of section length
- 0x0000000c - section length is 12 bytes; 2 * 4 + 2 + alignment to 32 bits
- 0x20000000 - high 32 bits of address
- 0x0000001c - low 32 bits of address 0x200000000000001c
- 0x00030d41 - 200001
- 0x000186a2 - 100002
- 0x26280000 - 38, 40 as bytes, padded with zeros
-
- For the latter example, the section contents must not be loaded in
-memory, and is therefore specified as part of the special data. The
-address is usually unimportant but might provide information for e.g.
-the DWARF 2 debugging format.
-
-\1f
-File: bfd.info, Node: GNU Free Documentation License, Next: BFD Index, Prev: BFD back ends, Up: Top
-
-Appendix A GNU Free Documentation License
-*****************************************
-
- Version 1.1, March 2000
-
- Copyright (C) 2000, 2003 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.
-
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone
- the effective freedom to copy and redistribute it, with or without
- modifying it, either commercially or noncommercially. Secondarily,
- this License preserves for the author and publisher a way to get
- credit for their work, while not being considered responsible for
- modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to
- software manuals; it can be used for any textual work, regardless
- of subject matter or whether it is published as a printed book.
- We recommend this License principally for works whose purpose is
- instruction or reference.
-
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be distributed
- under the terms of this License. The "Document", below, refers to
- any such manual or work. Any member of the public is a licensee,
- and is addressed as "you."
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter
- section of the Document that deals exclusively with the
- relationship of the publishers or authors of the Document to the
- Document's overall subject (or to related matters) and contains
- nothing that could fall directly within that overall subject.
- (For example, if the Document is in part a textbook of
- mathematics, a Secondary Section may not explain any mathematics.)
- The relationship could be a matter of historical connection with
- the subject or with related matters, or of legal, commercial,
- philosophical, ethical or political position regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, whose contents can be viewed and edited directly
- and straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup has been designed
- to thwart or discourage subsequent modification by readers is not
- Transparent. A copy that is not "Transparent" is called "Opaque."
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human modification.
- Opaque formats include PostScript, PDF, proprietary formats that
- can be read and edited only by proprietary word processors, SGML
- or XML for which the DTD and/or processing tools are not generally
- available, and the machine-generated HTML produced by some word
- processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, "Title
- Page" means the text near the most prominent appearance of the
- work's title, preceding the beginning of the body of the text.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow
- the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more than
- 100, and the Document's license notice requires Cover Texts, you
- must enclose the copies in covers that carry, clearly and legibly,
- all these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the
- title equally prominent and visible. You may add other material
- on the covers in addition. Copying with changes limited to the
- covers, as long as they preserve the title of the Document and
- satisfy these conditions, can be treated as verbatim copying in
- other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy, or
- state in or with each Opaque copy a publicly-accessible
- computer-network location containing a complete Transparent copy
- of the Document, free of added material, which the general
- network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with
- the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version to
- whoever possesses a copy of it. In addition, you must do these
- things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title
- as a previous version if the original publisher of that version
- gives permission.
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it
- has less than five).
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page.
- If there is no section entitled "History" in the Document,
- create one stating the title, year, authors, and publisher of
- the Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in the
- "History" section. You may omit a network location for a work
- that was published at least four years before the Document
- itself, or if the original publisher of the version it refers
- to gives permission.
- K. In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
- M. Delete any section entitled "Endorsements." Such a section
- may not be included in the Modified Version.
- N. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do this,
- add their titles to the list of Invariant Sections in the Modified
- Version's license notice. These titles must be distinct from any
- other section titles.
-
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties-for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition
- of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If the
- Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same entity
- you are acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section
- entitled "History"; likewise combine any sections entitled
- "Acknowledgements", and any sections entitled "Dedications." You
- must delete all sections entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow
- this License in all other respects regarding verbatim copying of
- that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of
- a storage or distribution medium, does not as a whole count as a
- Modified Version of the Document, provided no compilation
- copyright is claimed for the compilation. Such a compilation is
- called an "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document, on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may be
- placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License provided that you also include the
- original English version of this License. In case of a
- disagreement between the translation and the original English
- version of this License, the original English version will prevail.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-====================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.1
- or any later version published by the Free Software Foundation;
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License."
-
- If you have no Invariant Sections, write "with no Invariant Sections"
-instead of saying which ones are invariant. If you have no Front-Cover
-Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
-LIST"; likewise for Back-Cover Texts.
-
- If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License, to
-permit their use in free software.
-
-\1f
-File: bfd.info, Node: BFD Index, Prev: GNU Free Documentation License, Up: Top
-
-BFD Index
-*********
-
-\0\b[index\0\b]
-* Menu:
-
-* _bfd_final_link_relocate: Relocating the section contents.
- (line 22)
-* _bfd_generic_link_add_archive_symbols: Adding symbols from an archive.
- (line 12)
-* _bfd_generic_link_add_one_symbol: Adding symbols from an object file.
- (line 19)
-* _bfd_generic_make_empty_symbol: symbol handling functions.
- (line 92)
-* _bfd_link_add_symbols in target vector: Adding Symbols to the Hash Table.
- (line 6)
-* _bfd_link_final_link in target vector: Performing the Final Link.
- (line 6)
-* _bfd_link_hash_table_create in target vector: Creating a Linker Hash Table.
- (line 6)
-* _bfd_relocate_contents: Relocating the section contents.
- (line 22)
-* aout_SIZE_machine_type: aout. (line 147)
-* aout_SIZE_mkobject: aout. (line 139)
-* aout_SIZE_new_section_hook: aout. (line 177)
-* aout_SIZE_set_arch_mach: aout. (line 164)
-* aout_SIZE_some_aout_object_p: aout. (line 125)
-* aout_SIZE_swap_exec_header_in: aout. (line 101)
-* aout_SIZE_swap_exec_header_out: aout. (line 113)
-* arelent_chain: typedef arelent. (line 339)
-* BFD: Overview. (line 6)
-* BFD canonical format: Canonical format. (line 11)
-* bfd_alloc: Opening and Closing.
- (line 210)
-* bfd_alloc2: Opening and Closing.
- (line 219)
-* bfd_alt_mach_code: BFD front end. (line 602)
-* bfd_arch_bits_per_address: Architectures. (line 490)
-* bfd_arch_bits_per_byte: Architectures. (line 482)
-* bfd_arch_get_compatible: Architectures. (line 425)
-* bfd_arch_list: Architectures. (line 416)
-* bfd_arch_mach_octets_per_byte: Architectures. (line 559)
-* BFD_ARELOC_BFIN_ADD: howto manager. (line 944)
-* BFD_ARELOC_BFIN_ADDR: howto manager. (line 995)
-* BFD_ARELOC_BFIN_AND: howto manager. (line 965)
-* BFD_ARELOC_BFIN_COMP: howto manager. (line 986)
-* BFD_ARELOC_BFIN_CONST: howto manager. (line 941)
-* BFD_ARELOC_BFIN_DIV: howto manager. (line 953)
-* BFD_ARELOC_BFIN_HWPAGE: howto manager. (line 992)
-* BFD_ARELOC_BFIN_LAND: howto manager. (line 974)
-* BFD_ARELOC_BFIN_LEN: howto manager. (line 980)
-* BFD_ARELOC_BFIN_LOR: howto manager. (line 977)
-* BFD_ARELOC_BFIN_LSHIFT: howto manager. (line 959)
-* BFD_ARELOC_BFIN_MOD: howto manager. (line 956)
-* BFD_ARELOC_BFIN_MULT: howto manager. (line 950)
-* BFD_ARELOC_BFIN_NEG: howto manager. (line 983)
-* BFD_ARELOC_BFIN_OR: howto manager. (line 968)
-* BFD_ARELOC_BFIN_PAGE: howto manager. (line 989)
-* BFD_ARELOC_BFIN_PUSH: howto manager. (line 938)
-* BFD_ARELOC_BFIN_RSHIFT: howto manager. (line 962)
-* BFD_ARELOC_BFIN_SUB: howto manager. (line 947)
-* BFD_ARELOC_BFIN_XOR: howto manager. (line 971)
-* bfd_cache_close: File Caching. (line 26)
-* bfd_cache_close_all: File Caching. (line 39)
-* bfd_cache_init: File Caching. (line 18)
-* bfd_calc_gnu_debuglink_crc32: Opening and Closing.
- (line 246)
-* bfd_canonicalize_reloc: BFD front end. (line 321)
-* bfd_canonicalize_symtab: symbol handling functions.
- (line 50)
-* bfd_check_format: Formats. (line 21)
-* bfd_check_format_matches: Formats. (line 52)
-* bfd_check_overflow: typedef arelent. (line 351)
-* bfd_close: Opening and Closing.
- (line 135)
-* bfd_close_all_done: Opening and Closing.
- (line 153)
-* bfd_coff_backend_data: coff. (line 246)
-* bfd_copy_private_bfd_data: BFD front end. (line 460)
-* bfd_copy_private_header_data: BFD front end. (line 442)
-* bfd_copy_private_section_data: section prototypes. (line 255)
-* bfd_copy_private_symbol_data: symbol handling functions.
- (line 140)
-* bfd_core_file_failing_command: Core Files. (line 12)
-* bfd_core_file_failing_signal: Core Files. (line 21)
-* bfd_create: Opening and Closing.
- (line 172)
-* bfd_create_gnu_debuglink_section: Opening and Closing.
- (line 312)
-* bfd_decode_symclass: symbol handling functions.
- (line 111)
-* bfd_default_arch_struct: Architectures. (line 437)
-* bfd_default_compatible: Architectures. (line 499)
-* bfd_default_reloc_type_lookup: howto manager. (line 2081)
-* bfd_default_scan: Architectures. (line 508)
-* bfd_default_set_arch_mach: Architectures. (line 455)
-* bfd_demangle: BFD front end. (line 700)
-* bfd_elf_find_section: elf. (line 13)
-* bfd_emul_get_commonpagesize: BFD front end. (line 680)
-* bfd_emul_get_maxpagesize: BFD front end. (line 660)
-* bfd_emul_set_commonpagesize: BFD front end. (line 691)
-* bfd_emul_set_maxpagesize: BFD front end. (line 671)
-* bfd_errmsg: BFD front end. (line 246)
-* bfd_fdopenr: Opening and Closing.
- (line 46)
-* bfd_fill_in_gnu_debuglink_section: Opening and Closing.
- (line 326)
-* bfd_find_target: bfd_target. (line 439)
-* bfd_follow_gnu_debuglink: Opening and Closing.
- (line 291)
-* bfd_fopen: Opening and Closing.
- (line 9)
-* bfd_format_string: Formats. (line 79)
-* bfd_generic_discard_group: section prototypes. (line 281)
-* bfd_generic_gc_sections: howto manager. (line 2112)
-* bfd_generic_get_relocated_section_contents: howto manager. (line 2132)
-* bfd_generic_is_group_section: section prototypes. (line 273)
-* bfd_generic_merge_sections: howto manager. (line 2122)
-* bfd_generic_relax_section: howto manager. (line 2099)
-* bfd_get_arch: Architectures. (line 466)
-* bfd_get_arch_info: Architectures. (line 518)
-* bfd_get_arch_size: BFD front end. (line 365)
-* bfd_get_error: BFD front end. (line 227)
-* bfd_get_error_handler: BFD front end. (line 297)
-* bfd_get_gp_size: BFD front end. (line 406)
-* bfd_get_mach: Architectures. (line 474)
-* bfd_get_mtime: BFD front end. (line 741)
-* bfd_get_next_mapent: Archives. (line 52)
-* bfd_get_reloc_code_name: howto manager. (line 2090)
-* bfd_get_reloc_size: typedef arelent. (line 330)
-* bfd_get_reloc_upper_bound: BFD front end. (line 311)
-* bfd_get_section_by_name: section prototypes. (line 17)
-* bfd_get_section_by_name_if: section prototypes. (line 31)
-* bfd_get_section_contents: section prototypes. (line 228)
-* bfd_get_sign_extend_vma: BFD front end. (line 378)
-* bfd_get_size <1>: Internal. (line 25)
-* bfd_get_size: BFD front end. (line 750)
-* bfd_get_symtab_upper_bound: symbol handling functions.
- (line 6)
-* bfd_get_unique_section_name: section prototypes. (line 50)
-* bfd_h_put_size: Internal. (line 97)
-* bfd_hash_allocate: Creating and Freeing a Hash Table.
- (line 17)
-* bfd_hash_lookup: Looking Up or Entering a String.
- (line 6)
-* bfd_hash_newfunc: Creating and Freeing a Hash Table.
- (line 12)
-* bfd_hash_set_default_size: Creating and Freeing a Hash Table.
- (line 25)
-* bfd_hash_table_free: Creating and Freeing a Hash Table.
- (line 21)
-* bfd_hash_table_init: Creating and Freeing a Hash Table.
- (line 6)
-* bfd_hash_table_init_n: Creating and Freeing a Hash Table.
- (line 6)
-* bfd_hash_traverse: Traversing a Hash Table.
- (line 6)
-* bfd_init: Initialization. (line 11)
-* bfd_install_relocation: typedef arelent. (line 392)
-* bfd_is_local_label: symbol handling functions.
- (line 17)
-* bfd_is_local_label_name: symbol handling functions.
- (line 26)
-* bfd_is_target_special_symbol: symbol handling functions.
- (line 38)
-* bfd_is_undefined_symclass: symbol handling functions.
- (line 120)
-* bfd_link_split_section: Writing the symbol table.
- (line 44)
-* bfd_log2: Internal. (line 164)
-* bfd_lookup_arch: Architectures. (line 526)
-* bfd_make_debug_symbol: symbol handling functions.
- (line 102)
-* bfd_make_empty_symbol: symbol handling functions.
- (line 78)
-* bfd_make_readable: Opening and Closing.
- (line 196)
-* bfd_make_section: section prototypes. (line 129)
-* bfd_make_section_anyway: section prototypes. (line 100)
-* bfd_make_section_anyway_with_flags: section prototypes. (line 82)
-* bfd_make_section_old_way: section prototypes. (line 62)
-* bfd_make_section_with_flags: section prototypes. (line 116)
-* bfd_make_writable: Opening and Closing.
- (line 182)
-* bfd_malloc_and_get_section: section prototypes. (line 245)
-* bfd_map_over_sections: section prototypes. (line 155)
-* bfd_merge_private_bfd_data: BFD front end. (line 476)
-* bfd_octets_per_byte: Architectures. (line 549)
-* bfd_open_file: File Caching. (line 52)
-* bfd_openr: Opening and Closing.
- (line 30)
-* bfd_openr_iovec: Opening and Closing.
- (line 76)
-* bfd_openr_next_archived_file: Archives. (line 78)
-* bfd_openstreamr: Opening and Closing.
- (line 67)
-* bfd_openw: Opening and Closing.
- (line 123)
-* bfd_perform_relocation: typedef arelent. (line 367)
-* bfd_perror: BFD front end. (line 255)
-* bfd_preserve_finish: BFD front end. (line 650)
-* bfd_preserve_restore: BFD front end. (line 640)
-* bfd_preserve_save: BFD front end. (line 624)
-* bfd_print_symbol_vandf: symbol handling functions.
- (line 70)
-* bfd_printable_arch_mach: Architectures. (line 537)
-* bfd_printable_name: Architectures. (line 397)
-* bfd_put_size: Internal. (line 22)
-* BFD_RELOC_12_PCREL: howto manager. (line 39)
-* BFD_RELOC_14: howto manager. (line 31)
-* BFD_RELOC_16: howto manager. (line 30)
-* BFD_RELOC_16_BASEREL: howto manager. (line 80)
-* BFD_RELOC_16_GOT_PCREL: howto manager. (line 52)
-* BFD_RELOC_16_GOTOFF: howto manager. (line 55)
-* BFD_RELOC_16_PCREL: howto manager. (line 38)
-* BFD_RELOC_16_PCREL_S2: howto manager. (line 92)
-* BFD_RELOC_16_PLT_PCREL: howto manager. (line 63)
-* BFD_RELOC_16_PLTOFF: howto manager. (line 67)
-* BFD_RELOC_16C_ABS20: howto manager. (line 1771)
-* BFD_RELOC_16C_ABS20_C: howto manager. (line 1772)
-* BFD_RELOC_16C_ABS24: howto manager. (line 1773)
-* BFD_RELOC_16C_ABS24_C: howto manager. (line 1774)
-* BFD_RELOC_16C_DISP04: howto manager. (line 1751)
-* BFD_RELOC_16C_DISP04_C: howto manager. (line 1752)
-* BFD_RELOC_16C_DISP08: howto manager. (line 1753)
-* BFD_RELOC_16C_DISP08_C: howto manager. (line 1754)
-* BFD_RELOC_16C_DISP16: howto manager. (line 1755)
-* BFD_RELOC_16C_DISP16_C: howto manager. (line 1756)
-* BFD_RELOC_16C_DISP24: howto manager. (line 1757)
-* BFD_RELOC_16C_DISP24_C: howto manager. (line 1758)
-* BFD_RELOC_16C_DISP24a: howto manager. (line 1759)
-* BFD_RELOC_16C_DISP24a_C: howto manager. (line 1760)
-* BFD_RELOC_16C_IMM04: howto manager. (line 1775)
-* BFD_RELOC_16C_IMM04_C: howto manager. (line 1776)
-* BFD_RELOC_16C_IMM16: howto manager. (line 1777)
-* BFD_RELOC_16C_IMM16_C: howto manager. (line 1778)
-* BFD_RELOC_16C_IMM20: howto manager. (line 1779)
-* BFD_RELOC_16C_IMM20_C: howto manager. (line 1780)
-* BFD_RELOC_16C_IMM24: howto manager. (line 1781)
-* BFD_RELOC_16C_IMM24_C: howto manager. (line 1782)
-* BFD_RELOC_16C_IMM32: howto manager. (line 1783)
-* BFD_RELOC_16C_IMM32_C: howto manager. (line 1784)
-* BFD_RELOC_16C_NUM08: howto manager. (line 1745)
-* BFD_RELOC_16C_NUM08_C: howto manager. (line 1746)
-* BFD_RELOC_16C_NUM16: howto manager. (line 1747)
-* BFD_RELOC_16C_NUM16_C: howto manager. (line 1748)
-* BFD_RELOC_16C_NUM32: howto manager. (line 1749)
-* BFD_RELOC_16C_NUM32_C: howto manager. (line 1750)
-* BFD_RELOC_16C_REG04: howto manager. (line 1761)
-* BFD_RELOC_16C_REG04_C: howto manager. (line 1762)
-* BFD_RELOC_16C_REG04a: howto manager. (line 1763)
-* BFD_RELOC_16C_REG04a_C: howto manager. (line 1764)
-* BFD_RELOC_16C_REG14: howto manager. (line 1765)
-* BFD_RELOC_16C_REG14_C: howto manager. (line 1766)
-* BFD_RELOC_16C_REG16: howto manager. (line 1767)
-* BFD_RELOC_16C_REG16_C: howto manager. (line 1768)
-* BFD_RELOC_16C_REG20: howto manager. (line 1769)
-* BFD_RELOC_16C_REG20_C: howto manager. (line 1770)
-* BFD_RELOC_23_PCREL_S2: howto manager. (line 93)
-* BFD_RELOC_24: howto manager. (line 29)
-* BFD_RELOC_24_PCREL: howto manager. (line 37)
-* BFD_RELOC_24_PLT_PCREL: howto manager. (line 62)
-* BFD_RELOC_26: howto manager. (line 28)
-* BFD_RELOC_32: howto manager. (line 27)
-* BFD_RELOC_32_BASEREL: howto manager. (line 79)
-* BFD_RELOC_32_GOT_PCREL: howto manager. (line 51)
-* BFD_RELOC_32_GOTOFF: howto manager. (line 54)
-* BFD_RELOC_32_PCREL: howto manager. (line 36)
-* BFD_RELOC_32_PCREL_S2: howto manager. (line 91)
-* BFD_RELOC_32_PLT_PCREL: howto manager. (line 61)
-* BFD_RELOC_32_PLTOFF: howto manager. (line 66)
-* BFD_RELOC_32_SECREL: howto manager. (line 48)
-* BFD_RELOC_386_COPY: howto manager. (line 451)
-* BFD_RELOC_386_GLOB_DAT: howto manager. (line 452)
-* BFD_RELOC_386_GOT32: howto manager. (line 449)
-* BFD_RELOC_386_GOTOFF: howto manager. (line 455)
-* BFD_RELOC_386_GOTPC: howto manager. (line 456)
-* BFD_RELOC_386_JUMP_SLOT: howto manager. (line 453)
-* BFD_RELOC_386_PLT32: howto manager. (line 450)
-* BFD_RELOC_386_RELATIVE: howto manager. (line 454)
-* BFD_RELOC_386_TLS_DESC: howto manager. (line 471)
-* BFD_RELOC_386_TLS_DESC_CALL: howto manager. (line 470)
-* BFD_RELOC_386_TLS_DTPMOD32: howto manager. (line 466)
-* BFD_RELOC_386_TLS_DTPOFF32: howto manager. (line 467)
-* BFD_RELOC_386_TLS_GD: howto manager. (line 461)
-* BFD_RELOC_386_TLS_GOTDESC: howto manager. (line 469)
-* BFD_RELOC_386_TLS_GOTIE: howto manager. (line 459)
-* BFD_RELOC_386_TLS_IE: howto manager. (line 458)
-* BFD_RELOC_386_TLS_IE_32: howto manager. (line 464)
-* BFD_RELOC_386_TLS_LDM: howto manager. (line 462)
-* BFD_RELOC_386_TLS_LDO_32: howto manager. (line 463)
-* BFD_RELOC_386_TLS_LE: howto manager. (line 460)
-* BFD_RELOC_386_TLS_LE_32: howto manager. (line 465)
-* BFD_RELOC_386_TLS_TPOFF: howto manager. (line 457)
-* BFD_RELOC_386_TLS_TPOFF32: howto manager. (line 468)
-* BFD_RELOC_390_12: howto manager. (line 1437)
-* BFD_RELOC_390_20: howto manager. (line 1537)
-* BFD_RELOC_390_COPY: howto manager. (line 1446)
-* BFD_RELOC_390_GLOB_DAT: howto manager. (line 1449)
-* BFD_RELOC_390_GOT12: howto manager. (line 1440)
-* BFD_RELOC_390_GOT16: howto manager. (line 1461)
-* BFD_RELOC_390_GOT20: howto manager. (line 1538)
-* BFD_RELOC_390_GOT64: howto manager. (line 1479)
-* BFD_RELOC_390_GOTENT: howto manager. (line 1485)
-* BFD_RELOC_390_GOTOFF64: howto manager. (line 1488)
-* BFD_RELOC_390_GOTPC: howto manager. (line 1458)
-* BFD_RELOC_390_GOTPCDBL: howto manager. (line 1476)
-* BFD_RELOC_390_GOTPLT12: howto manager. (line 1491)
-* BFD_RELOC_390_GOTPLT16: howto manager. (line 1494)
-* BFD_RELOC_390_GOTPLT20: howto manager. (line 1539)
-* BFD_RELOC_390_GOTPLT32: howto manager. (line 1497)
-* BFD_RELOC_390_GOTPLT64: howto manager. (line 1500)
-* BFD_RELOC_390_GOTPLTENT: howto manager. (line 1503)
-* BFD_RELOC_390_JMP_SLOT: howto manager. (line 1452)
-* BFD_RELOC_390_PC16DBL: howto manager. (line 1464)
-* BFD_RELOC_390_PC32DBL: howto manager. (line 1470)
-* BFD_RELOC_390_PLT16DBL: howto manager. (line 1467)
-* BFD_RELOC_390_PLT32: howto manager. (line 1443)
-* BFD_RELOC_390_PLT32DBL: howto manager. (line 1473)
-* BFD_RELOC_390_PLT64: howto manager. (line 1482)
-* BFD_RELOC_390_PLTOFF16: howto manager. (line 1506)
-* BFD_RELOC_390_PLTOFF32: howto manager. (line 1509)
-* BFD_RELOC_390_PLTOFF64: howto manager. (line 1512)
-* BFD_RELOC_390_RELATIVE: howto manager. (line 1455)
-* BFD_RELOC_390_TLS_DTPMOD: howto manager. (line 1532)
-* BFD_RELOC_390_TLS_DTPOFF: howto manager. (line 1533)
-* BFD_RELOC_390_TLS_GD32: howto manager. (line 1518)
-* BFD_RELOC_390_TLS_GD64: howto manager. (line 1519)
-* BFD_RELOC_390_TLS_GDCALL: howto manager. (line 1516)
-* BFD_RELOC_390_TLS_GOTIE12: howto manager. (line 1520)
-* BFD_RELOC_390_TLS_GOTIE20: howto manager. (line 1540)
-* BFD_RELOC_390_TLS_GOTIE32: howto manager. (line 1521)
-* BFD_RELOC_390_TLS_GOTIE64: howto manager. (line 1522)
-* BFD_RELOC_390_TLS_IE32: howto manager. (line 1525)
-* BFD_RELOC_390_TLS_IE64: howto manager. (line 1526)
-* BFD_RELOC_390_TLS_IEENT: howto manager. (line 1527)
-* BFD_RELOC_390_TLS_LDCALL: howto manager. (line 1517)
-* BFD_RELOC_390_TLS_LDM32: howto manager. (line 1523)
-* BFD_RELOC_390_TLS_LDM64: howto manager. (line 1524)
-* BFD_RELOC_390_TLS_LDO32: howto manager. (line 1530)
-* BFD_RELOC_390_TLS_LDO64: howto manager. (line 1531)
-* BFD_RELOC_390_TLS_LE32: howto manager. (line 1528)
-* BFD_RELOC_390_TLS_LE64: howto manager. (line 1529)
-* BFD_RELOC_390_TLS_LOAD: howto manager. (line 1515)
-* BFD_RELOC_390_TLS_TPOFF: howto manager. (line 1534)
-* BFD_RELOC_64: howto manager. (line 26)
-* BFD_RELOC_64_PCREL: howto manager. (line 35)
-* BFD_RELOC_64_PLT_PCREL: howto manager. (line 60)
-* BFD_RELOC_64_PLTOFF: howto manager. (line 65)
-* BFD_RELOC_68K_GLOB_DAT: howto manager. (line 74)
-* BFD_RELOC_68K_JMP_SLOT: howto manager. (line 75)
-* BFD_RELOC_68K_RELATIVE: howto manager. (line 76)
-* BFD_RELOC_8: howto manager. (line 32)
-* BFD_RELOC_860_COPY: howto manager. (line 1879)
-* BFD_RELOC_860_GLOB_DAT: howto manager. (line 1880)
-* BFD_RELOC_860_HAGOT: howto manager. (line 1905)
-* BFD_RELOC_860_HAGOTOFF: howto manager. (line 1906)
-* BFD_RELOC_860_HAPC: howto manager. (line 1907)
-* BFD_RELOC_860_HIGH: howto manager. (line 1908)
-* BFD_RELOC_860_HIGHADJ: howto manager. (line 1904)
-* BFD_RELOC_860_HIGOT: howto manager. (line 1909)
-* BFD_RELOC_860_HIGOTOFF: howto manager. (line 1910)
-* BFD_RELOC_860_JUMP_SLOT: howto manager. (line 1881)
-* BFD_RELOC_860_LOGOT0: howto manager. (line 1893)
-* BFD_RELOC_860_LOGOT1: howto manager. (line 1895)
-* BFD_RELOC_860_LOGOTOFF0: howto manager. (line 1897)
-* BFD_RELOC_860_LOGOTOFF1: howto manager. (line 1899)
-* BFD_RELOC_860_LOGOTOFF2: howto manager. (line 1901)
-* BFD_RELOC_860_LOGOTOFF3: howto manager. (line 1902)
-* BFD_RELOC_860_LOPC: howto manager. (line 1903)
-* BFD_RELOC_860_LOW0: howto manager. (line 1886)
-* BFD_RELOC_860_LOW1: howto manager. (line 1888)
-* BFD_RELOC_860_LOW2: howto manager. (line 1890)
-* BFD_RELOC_860_LOW3: howto manager. (line 1892)
-* BFD_RELOC_860_PC16: howto manager. (line 1885)
-* BFD_RELOC_860_PC26: howto manager. (line 1883)
-* BFD_RELOC_860_PLT26: howto manager. (line 1884)
-* BFD_RELOC_860_RELATIVE: howto manager. (line 1882)
-* BFD_RELOC_860_SPGOT0: howto manager. (line 1894)
-* BFD_RELOC_860_SPGOT1: howto manager. (line 1896)
-* BFD_RELOC_860_SPGOTOFF0: howto manager. (line 1898)
-* BFD_RELOC_860_SPGOTOFF1: howto manager. (line 1900)
-* BFD_RELOC_860_SPLIT0: howto manager. (line 1887)
-* BFD_RELOC_860_SPLIT1: howto manager. (line 1889)
-* BFD_RELOC_860_SPLIT2: howto manager. (line 1891)
-* BFD_RELOC_8_BASEREL: howto manager. (line 84)
-* BFD_RELOC_8_FFnn: howto manager. (line 88)
-* BFD_RELOC_8_GOT_PCREL: howto manager. (line 53)
-* BFD_RELOC_8_GOTOFF: howto manager. (line 59)
-* BFD_RELOC_8_PCREL: howto manager. (line 40)
-* BFD_RELOC_8_PLT_PCREL: howto manager. (line 64)
-* BFD_RELOC_8_PLTOFF: howto manager. (line 71)
-* BFD_RELOC_ALPHA_BRSGP: howto manager. (line 275)
-* BFD_RELOC_ALPHA_CODEADDR: howto manager. (line 266)
-* BFD_RELOC_ALPHA_DTPMOD64: howto manager. (line 282)
-* BFD_RELOC_ALPHA_DTPREL16: howto manager. (line 287)
-* BFD_RELOC_ALPHA_DTPREL64: howto manager. (line 284)
-* BFD_RELOC_ALPHA_DTPREL_HI16: howto manager. (line 285)
-* BFD_RELOC_ALPHA_DTPREL_LO16: howto manager. (line 286)
-* BFD_RELOC_ALPHA_ELF_LITERAL: howto manager. (line 231)
-* BFD_RELOC_ALPHA_GOTDTPREL16: howto manager. (line 283)
-* BFD_RELOC_ALPHA_GOTTPREL16: howto manager. (line 288)
-* BFD_RELOC_ALPHA_GPDISP: howto manager. (line 225)
-* BFD_RELOC_ALPHA_GPDISP_HI16: howto manager. (line 211)
-* BFD_RELOC_ALPHA_GPDISP_LO16: howto manager. (line 219)
-* BFD_RELOC_ALPHA_GPREL_HI16: howto manager. (line 270)
-* BFD_RELOC_ALPHA_GPREL_LO16: howto manager. (line 271)
-* BFD_RELOC_ALPHA_HINT: howto manager. (line 257)
-* BFD_RELOC_ALPHA_LINKAGE: howto manager. (line 262)
-* BFD_RELOC_ALPHA_LITERAL: howto manager. (line 230)
-* BFD_RELOC_ALPHA_LITUSE: howto manager. (line 232)
-* BFD_RELOC_ALPHA_TLSGD: howto manager. (line 280)
-* BFD_RELOC_ALPHA_TLSLDM: howto manager. (line 281)
-* BFD_RELOC_ALPHA_TPREL16: howto manager. (line 292)
-* BFD_RELOC_ALPHA_TPREL64: howto manager. (line 289)
-* BFD_RELOC_ALPHA_TPREL_HI16: howto manager. (line 290)
-* BFD_RELOC_ALPHA_TPREL_LO16: howto manager. (line 291)
-* BFD_RELOC_ARC_B22_PCREL: howto manager. (line 873)
-* BFD_RELOC_ARC_B26: howto manager. (line 878)
-* BFD_RELOC_ARM_ADR_IMM: howto manager. (line 766)
-* BFD_RELOC_ARM_ADRL_IMMEDIATE: howto manager. (line 753)
-* BFD_RELOC_ARM_ALU_PC_G0: howto manager. (line 723)
-* BFD_RELOC_ARM_ALU_PC_G0_NC: howto manager. (line 722)
-* BFD_RELOC_ARM_ALU_PC_G1: howto manager. (line 725)
-* BFD_RELOC_ARM_ALU_PC_G1_NC: howto manager. (line 724)
-* BFD_RELOC_ARM_ALU_PC_G2: howto manager. (line 726)
-* BFD_RELOC_ARM_ALU_SB_G0: howto manager. (line 737)
-* BFD_RELOC_ARM_ALU_SB_G0_NC: howto manager. (line 736)
-* BFD_RELOC_ARM_ALU_SB_G1: howto manager. (line 739)
-* BFD_RELOC_ARM_ALU_SB_G1_NC: howto manager. (line 738)
-* BFD_RELOC_ARM_ALU_SB_G2: howto manager. (line 740)
-* BFD_RELOC_ARM_CP_OFF_IMM: howto manager. (line 762)
-* BFD_RELOC_ARM_CP_OFF_IMM_S2: howto manager. (line 763)
-* BFD_RELOC_ARM_GLOB_DAT: howto manager. (line 704)
-* BFD_RELOC_ARM_GOT32: howto manager. (line 705)
-* BFD_RELOC_ARM_GOTOFF: howto manager. (line 708)
-* BFD_RELOC_ARM_GOTPC: howto manager. (line 709)
-* BFD_RELOC_ARM_HWLITERAL: howto manager. (line 773)
-* BFD_RELOC_ARM_IMMEDIATE: howto manager. (line 752)
-* BFD_RELOC_ARM_IN_POOL: howto manager. (line 769)
-* BFD_RELOC_ARM_JUMP_SLOT: howto manager. (line 703)
-* BFD_RELOC_ARM_LDC_PC_G0: howto manager. (line 733)
-* BFD_RELOC_ARM_LDC_PC_G1: howto manager. (line 734)
-* BFD_RELOC_ARM_LDC_PC_G2: howto manager. (line 735)
-* BFD_RELOC_ARM_LDC_SB_G0: howto manager. (line 747)
-* BFD_RELOC_ARM_LDC_SB_G1: howto manager. (line 748)
-* BFD_RELOC_ARM_LDC_SB_G2: howto manager. (line 749)
-* BFD_RELOC_ARM_LDR_IMM: howto manager. (line 767)
-* BFD_RELOC_ARM_LDR_PC_G0: howto manager. (line 727)
-* BFD_RELOC_ARM_LDR_PC_G1: howto manager. (line 728)
-* BFD_RELOC_ARM_LDR_PC_G2: howto manager. (line 729)
-* BFD_RELOC_ARM_LDR_SB_G0: howto manager. (line 741)
-* BFD_RELOC_ARM_LDR_SB_G1: howto manager. (line 742)
-* BFD_RELOC_ARM_LDR_SB_G2: howto manager. (line 743)
-* BFD_RELOC_ARM_LDRS_PC_G0: howto manager. (line 730)
-* BFD_RELOC_ARM_LDRS_PC_G1: howto manager. (line 731)
-* BFD_RELOC_ARM_LDRS_PC_G2: howto manager. (line 732)
-* BFD_RELOC_ARM_LDRS_SB_G0: howto manager. (line 744)
-* BFD_RELOC_ARM_LDRS_SB_G1: howto manager. (line 745)
-* BFD_RELOC_ARM_LDRS_SB_G2: howto manager. (line 746)
-* BFD_RELOC_ARM_LITERAL: howto manager. (line 768)
-* BFD_RELOC_ARM_MOVT: howto manager. (line 694)
-* BFD_RELOC_ARM_MOVT_PCREL: howto manager. (line 696)
-* BFD_RELOC_ARM_MOVW: howto manager. (line 693)
-* BFD_RELOC_ARM_MOVW_PCREL: howto manager. (line 695)
-* BFD_RELOC_ARM_MULTI: howto manager. (line 761)
-* BFD_RELOC_ARM_OFFSET_IMM: howto manager. (line 667)
-* BFD_RELOC_ARM_OFFSET_IMM8: howto manager. (line 770)
-* BFD_RELOC_ARM_PCREL_BLX: howto manager. (line 638)
-* BFD_RELOC_ARM_PCREL_BRANCH: howto manager. (line 634)
-* BFD_RELOC_ARM_PCREL_CALL: howto manager. (line 648)
-* BFD_RELOC_ARM_PCREL_JUMP: howto manager. (line 652)
-* BFD_RELOC_ARM_PLT32: howto manager. (line 706)
-* BFD_RELOC_ARM_PREL31: howto manager. (line 690)
-* BFD_RELOC_ARM_RELATIVE: howto manager. (line 707)
-* BFD_RELOC_ARM_ROSEGREL32: howto manager. (line 679)
-* BFD_RELOC_ARM_SBREL32: howto manager. (line 682)
-* BFD_RELOC_ARM_SHIFT_IMM: howto manager. (line 758)
-* BFD_RELOC_ARM_SMC: howto manager. (line 759)
-* BFD_RELOC_ARM_SWI: howto manager. (line 760)
-* BFD_RELOC_ARM_T32_ADD_IMM: howto manager. (line 755)
-* BFD_RELOC_ARM_T32_ADD_PC12: howto manager. (line 757)
-* BFD_RELOC_ARM_T32_CP_OFF_IMM: howto manager. (line 764)
-* BFD_RELOC_ARM_T32_CP_OFF_IMM_S2: howto manager. (line 765)
-* BFD_RELOC_ARM_T32_IMM12: howto manager. (line 756)
-* BFD_RELOC_ARM_T32_IMMEDIATE: howto manager. (line 754)
-* BFD_RELOC_ARM_T32_OFFSET_IMM: howto manager. (line 772)
-* BFD_RELOC_ARM_T32_OFFSET_U8: howto manager. (line 771)
-* BFD_RELOC_ARM_TARGET1: howto manager. (line 675)
-* BFD_RELOC_ARM_TARGET2: howto manager. (line 685)
-* BFD_RELOC_ARM_THUMB_ADD: howto manager. (line 774)
-* BFD_RELOC_ARM_THUMB_IMM: howto manager. (line 775)
-* BFD_RELOC_ARM_THUMB_MOVT: howto manager. (line 698)
-* BFD_RELOC_ARM_THUMB_MOVT_PCREL: howto manager. (line 700)
-* BFD_RELOC_ARM_THUMB_MOVW: howto manager. (line 697)
-* BFD_RELOC_ARM_THUMB_MOVW_PCREL: howto manager. (line 699)
-* BFD_RELOC_ARM_THUMB_OFFSET: howto manager. (line 671)
-* BFD_RELOC_ARM_THUMB_SHIFT: howto manager. (line 776)
-* BFD_RELOC_ARM_TLS_DTPMOD32: howto manager. (line 716)
-* BFD_RELOC_ARM_TLS_DTPOFF32: howto manager. (line 715)
-* BFD_RELOC_ARM_TLS_GD32: howto manager. (line 712)
-* BFD_RELOC_ARM_TLS_IE32: howto manager. (line 718)
-* BFD_RELOC_ARM_TLS_LDM32: howto manager. (line 714)
-* BFD_RELOC_ARM_TLS_LDO32: howto manager. (line 713)
-* BFD_RELOC_ARM_TLS_LE32: howto manager. (line 719)
-* BFD_RELOC_ARM_TLS_TPOFF32: howto manager. (line 717)
-* BFD_RELOC_AVR_13_PCREL: howto manager. (line 1338)
-* BFD_RELOC_AVR_16_PM: howto manager. (line 1342)
-* BFD_RELOC_AVR_6: howto manager. (line 1429)
-* BFD_RELOC_AVR_6_ADIW: howto manager. (line 1433)
-* BFD_RELOC_AVR_7_PCREL: howto manager. (line 1334)
-* BFD_RELOC_AVR_CALL: howto manager. (line 1421)
-* BFD_RELOC_AVR_HH8_LDI: howto manager. (line 1354)
-* BFD_RELOC_AVR_HH8_LDI_NEG: howto manager. (line 1373)
-* BFD_RELOC_AVR_HH8_LDI_PM: howto manager. (line 1402)
-* BFD_RELOC_AVR_HH8_LDI_PM_NEG: howto manager. (line 1416)
-* BFD_RELOC_AVR_HI8_LDI: howto manager. (line 1350)
-* BFD_RELOC_AVR_HI8_LDI_GS: howto manager. (line 1396)
-* BFD_RELOC_AVR_HI8_LDI_NEG: howto manager. (line 1368)
-* BFD_RELOC_AVR_HI8_LDI_PM: howto manager. (line 1392)
-* BFD_RELOC_AVR_HI8_LDI_PM_NEG: howto manager. (line 1411)
-* BFD_RELOC_AVR_LDI: howto manager. (line 1425)
-* BFD_RELOC_AVR_LO8_LDI: howto manager. (line 1346)
-* BFD_RELOC_AVR_LO8_LDI_GS: howto manager. (line 1386)
-* BFD_RELOC_AVR_LO8_LDI_NEG: howto manager. (line 1363)
-* BFD_RELOC_AVR_LO8_LDI_PM: howto manager. (line 1382)
-* BFD_RELOC_AVR_LO8_LDI_PM_NEG: howto manager. (line 1407)
-* BFD_RELOC_AVR_MS8_LDI: howto manager. (line 1359)
-* BFD_RELOC_AVR_MS8_LDI_NEG: howto manager. (line 1378)
-* BFD_RELOC_BFIN_10_PCREL: howto manager. (line 898)
-* BFD_RELOC_BFIN_11_PCREL: howto manager. (line 901)
-* BFD_RELOC_BFIN_12_PCREL_JUMP: howto manager. (line 904)
-* BFD_RELOC_BFIN_12_PCREL_JUMP_S: howto manager. (line 907)
-* BFD_RELOC_BFIN_16_HIGH: howto manager. (line 886)
-* BFD_RELOC_BFIN_16_IMM: howto manager. (line 883)
-* BFD_RELOC_BFIN_16_LOW: howto manager. (line 895)
-* BFD_RELOC_BFIN_24_PCREL_CALL_X: howto manager. (line 910)
-* BFD_RELOC_BFIN_24_PCREL_JUMP_L: howto manager. (line 913)
-* BFD_RELOC_BFIN_4_PCREL: howto manager. (line 889)
-* BFD_RELOC_BFIN_5_PCREL: howto manager. (line 892)
-* BFD_RELOC_BFIN_FUNCDESC: howto manager. (line 919)
-* BFD_RELOC_BFIN_FUNCDESC_GOT17M4: howto manager. (line 920)
-* BFD_RELOC_BFIN_FUNCDESC_GOTHI: howto manager. (line 921)
-* BFD_RELOC_BFIN_FUNCDESC_GOTLO: howto manager. (line 922)
-* BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4: howto manager. (line 924)
-* BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI: howto manager. (line 925)
-* BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO: howto manager. (line 926)
-* BFD_RELOC_BFIN_FUNCDESC_VALUE: howto manager. (line 923)
-* BFD_RELOC_BFIN_GOT: howto manager. (line 932)
-* BFD_RELOC_BFIN_GOT17M4: howto manager. (line 916)
-* BFD_RELOC_BFIN_GOTHI: howto manager. (line 917)
-* BFD_RELOC_BFIN_GOTLO: howto manager. (line 918)
-* BFD_RELOC_BFIN_GOTOFF17M4: howto manager. (line 927)
-* BFD_RELOC_BFIN_GOTOFFHI: howto manager. (line 928)
-* BFD_RELOC_BFIN_GOTOFFLO: howto manager. (line 929)
-* BFD_RELOC_BFIN_PLTPC: howto manager. (line 935)
-* bfd_reloc_code_type: howto manager. (line 10)
-* BFD_RELOC_CR16_ABS20: howto manager. (line 1799)
-* BFD_RELOC_CR16_ABS24: howto manager. (line 1800)
-* BFD_RELOC_CR16_DISP16: howto manager. (line 1810)
-* BFD_RELOC_CR16_DISP20: howto manager. (line 1811)
-* BFD_RELOC_CR16_DISP24: howto manager. (line 1812)
-* BFD_RELOC_CR16_DISP24a: howto manager. (line 1813)
-* BFD_RELOC_CR16_DISP4: howto manager. (line 1808)
-* BFD_RELOC_CR16_DISP8: howto manager. (line 1809)
-* BFD_RELOC_CR16_IMM16: howto manager. (line 1803)
-* BFD_RELOC_CR16_IMM20: howto manager. (line 1804)
-* BFD_RELOC_CR16_IMM24: howto manager. (line 1805)
-* BFD_RELOC_CR16_IMM32: howto manager. (line 1806)
-* BFD_RELOC_CR16_IMM32a: howto manager. (line 1807)
-* BFD_RELOC_CR16_IMM4: howto manager. (line 1801)
-* BFD_RELOC_CR16_IMM8: howto manager. (line 1802)
-* BFD_RELOC_CR16_NUM16: howto manager. (line 1788)
-* BFD_RELOC_CR16_NUM32: howto manager. (line 1789)
-* BFD_RELOC_CR16_NUM32a: howto manager. (line 1790)
-* BFD_RELOC_CR16_NUM8: howto manager. (line 1787)
-* BFD_RELOC_CR16_REGREL0: howto manager. (line 1791)
-* BFD_RELOC_CR16_REGREL14: howto manager. (line 1794)
-* BFD_RELOC_CR16_REGREL14a: howto manager. (line 1795)
-* BFD_RELOC_CR16_REGREL16: howto manager. (line 1796)
-* BFD_RELOC_CR16_REGREL20: howto manager. (line 1797)
-* BFD_RELOC_CR16_REGREL20a: howto manager. (line 1798)
-* BFD_RELOC_CR16_REGREL4: howto manager. (line 1792)
-* BFD_RELOC_CR16_REGREL4a: howto manager. (line 1793)
-* BFD_RELOC_CRIS_16_GOT: howto manager. (line 1860)
-* BFD_RELOC_CRIS_16_GOTPLT: howto manager. (line 1866)
-* BFD_RELOC_CRIS_32_GOT: howto manager. (line 1857)
-* BFD_RELOC_CRIS_32_GOTPLT: howto manager. (line 1863)
-* BFD_RELOC_CRIS_32_GOTREL: howto manager. (line 1869)
-* BFD_RELOC_CRIS_32_PLT_GOTREL: howto manager. (line 1872)
-* BFD_RELOC_CRIS_32_PLT_PCREL: howto manager. (line 1875)
-* BFD_RELOC_CRIS_BDISP8: howto manager. (line 1838)
-* BFD_RELOC_CRIS_COPY: howto manager. (line 1851)
-* BFD_RELOC_CRIS_GLOB_DAT: howto manager. (line 1852)
-* BFD_RELOC_CRIS_JUMP_SLOT: howto manager. (line 1853)
-* BFD_RELOC_CRIS_LAPCQ_OFFSET: howto manager. (line 1846)
-* BFD_RELOC_CRIS_RELATIVE: howto manager. (line 1854)
-* BFD_RELOC_CRIS_SIGNED_16: howto manager. (line 1844)
-* BFD_RELOC_CRIS_SIGNED_6: howto manager. (line 1840)
-* BFD_RELOC_CRIS_SIGNED_8: howto manager. (line 1842)
-* BFD_RELOC_CRIS_UNSIGNED_16: howto manager. (line 1845)
-* BFD_RELOC_CRIS_UNSIGNED_4: howto manager. (line 1847)
-* BFD_RELOC_CRIS_UNSIGNED_5: howto manager. (line 1839)
-* BFD_RELOC_CRIS_UNSIGNED_6: howto manager. (line 1841)
-* BFD_RELOC_CRIS_UNSIGNED_8: howto manager. (line 1843)
-* BFD_RELOC_CRX_ABS16: howto manager. (line 1826)
-* BFD_RELOC_CRX_ABS32: howto manager. (line 1827)
-* BFD_RELOC_CRX_IMM16: howto manager. (line 1831)
-* BFD_RELOC_CRX_IMM32: howto manager. (line 1832)
-* BFD_RELOC_CRX_NUM16: howto manager. (line 1829)
-* BFD_RELOC_CRX_NUM32: howto manager. (line 1830)
-* BFD_RELOC_CRX_NUM8: howto manager. (line 1828)
-* BFD_RELOC_CRX_REGREL12: howto manager. (line 1822)
-* BFD_RELOC_CRX_REGREL22: howto manager. (line 1823)
-* BFD_RELOC_CRX_REGREL28: howto manager. (line 1824)
-* BFD_RELOC_CRX_REGREL32: howto manager. (line 1825)
-* BFD_RELOC_CRX_REL16: howto manager. (line 1819)
-* BFD_RELOC_CRX_REL24: howto manager. (line 1820)
-* BFD_RELOC_CRX_REL32: howto manager. (line 1821)
-* BFD_RELOC_CRX_REL4: howto manager. (line 1816)
-* BFD_RELOC_CRX_REL8: howto manager. (line 1817)
-* BFD_RELOC_CRX_REL8_CMP: howto manager. (line 1818)
-* BFD_RELOC_CRX_SWITCH16: howto manager. (line 1834)
-* BFD_RELOC_CRX_SWITCH32: howto manager. (line 1835)
-* BFD_RELOC_CRX_SWITCH8: howto manager. (line 1833)
-* BFD_RELOC_CTOR: howto manager. (line 628)
-* BFD_RELOC_D10V_10_PCREL_L: howto manager. (line 1002)
-* BFD_RELOC_D10V_10_PCREL_R: howto manager. (line 998)
-* BFD_RELOC_D10V_18: howto manager. (line 1007)
-* BFD_RELOC_D10V_18_PCREL: howto manager. (line 1010)
-* BFD_RELOC_D30V_15: howto manager. (line 1025)
-* BFD_RELOC_D30V_15_PCREL: howto manager. (line 1029)
-* BFD_RELOC_D30V_15_PCREL_R: howto manager. (line 1033)
-* BFD_RELOC_D30V_21: howto manager. (line 1038)
-* BFD_RELOC_D30V_21_PCREL: howto manager. (line 1042)
-* BFD_RELOC_D30V_21_PCREL_R: howto manager. (line 1046)
-* BFD_RELOC_D30V_32: howto manager. (line 1051)
-* BFD_RELOC_D30V_32_PCREL: howto manager. (line 1054)
-* BFD_RELOC_D30V_6: howto manager. (line 1013)
-* BFD_RELOC_D30V_9_PCREL: howto manager. (line 1016)
-* BFD_RELOC_D30V_9_PCREL_R: howto manager. (line 1020)
-* BFD_RELOC_DLX_HI16_S: howto manager. (line 1057)
-* BFD_RELOC_DLX_JMP26: howto manager. (line 1063)
-* BFD_RELOC_DLX_LO16: howto manager. (line 1060)
-* BFD_RELOC_FR30_10_IN_8: howto manager. (line 1242)
-* BFD_RELOC_FR30_12_PCREL: howto manager. (line 1250)
-* BFD_RELOC_FR30_20: howto manager. (line 1226)
-* BFD_RELOC_FR30_48: howto manager. (line 1223)
-* BFD_RELOC_FR30_6_IN_4: howto manager. (line 1230)
-* BFD_RELOC_FR30_8_IN_8: howto manager. (line 1234)
-* BFD_RELOC_FR30_9_IN_8: howto manager. (line 1238)
-* BFD_RELOC_FR30_9_PCREL: howto manager. (line 1246)
-* BFD_RELOC_FRV_FUNCDESC: howto manager. (line 393)
-* BFD_RELOC_FRV_FUNCDESC_GOT12: howto manager. (line 394)
-* BFD_RELOC_FRV_FUNCDESC_GOTHI: howto manager. (line 395)
-* BFD_RELOC_FRV_FUNCDESC_GOTLO: howto manager. (line 396)
-* BFD_RELOC_FRV_FUNCDESC_GOTOFF12: howto manager. (line 398)
-* BFD_RELOC_FRV_FUNCDESC_GOTOFFHI: howto manager. (line 399)
-* BFD_RELOC_FRV_FUNCDESC_GOTOFFLO: howto manager. (line 400)
-* BFD_RELOC_FRV_FUNCDESC_VALUE: howto manager. (line 397)
-* BFD_RELOC_FRV_GETTLSOFF: howto manager. (line 404)
-* BFD_RELOC_FRV_GETTLSOFF_RELAX: howto manager. (line 417)
-* BFD_RELOC_FRV_GOT12: howto manager. (line 390)
-* BFD_RELOC_FRV_GOTHI: howto manager. (line 391)
-* BFD_RELOC_FRV_GOTLO: howto manager. (line 392)
-* BFD_RELOC_FRV_GOTOFF12: howto manager. (line 401)
-* BFD_RELOC_FRV_GOTOFFHI: howto manager. (line 402)
-* BFD_RELOC_FRV_GOTOFFLO: howto manager. (line 403)
-* BFD_RELOC_FRV_GOTTLSDESC12: howto manager. (line 406)
-* BFD_RELOC_FRV_GOTTLSDESCHI: howto manager. (line 407)
-* BFD_RELOC_FRV_GOTTLSDESCLO: howto manager. (line 408)
-* BFD_RELOC_FRV_GOTTLSOFF12: howto manager. (line 412)
-* BFD_RELOC_FRV_GOTTLSOFFHI: howto manager. (line 413)
-* BFD_RELOC_FRV_GOTTLSOFFLO: howto manager. (line 414)
-* BFD_RELOC_FRV_GPREL12: howto manager. (line 385)
-* BFD_RELOC_FRV_GPREL32: howto manager. (line 387)
-* BFD_RELOC_FRV_GPRELHI: howto manager. (line 388)
-* BFD_RELOC_FRV_GPRELLO: howto manager. (line 389)
-* BFD_RELOC_FRV_GPRELU12: howto manager. (line 386)
-* BFD_RELOC_FRV_HI16: howto manager. (line 384)
-* BFD_RELOC_FRV_LABEL16: howto manager. (line 381)
-* BFD_RELOC_FRV_LABEL24: howto manager. (line 382)
-* BFD_RELOC_FRV_LO16: howto manager. (line 383)
-* BFD_RELOC_FRV_TLSDESC_RELAX: howto manager. (line 416)
-* BFD_RELOC_FRV_TLSDESC_VALUE: howto manager. (line 405)
-* BFD_RELOC_FRV_TLSMOFF: howto manager. (line 419)
-* BFD_RELOC_FRV_TLSMOFF12: howto manager. (line 409)
-* BFD_RELOC_FRV_TLSMOFFHI: howto manager. (line 410)
-* BFD_RELOC_FRV_TLSMOFFLO: howto manager. (line 411)
-* BFD_RELOC_FRV_TLSOFF: howto manager. (line 415)
-* BFD_RELOC_FRV_TLSOFF_RELAX: howto manager. (line 418)
-* BFD_RELOC_GPREL16: howto manager. (line 106)
-* BFD_RELOC_GPREL32: howto manager. (line 107)
-* BFD_RELOC_H8_DIR16A8: howto manager. (line 1917)
-* BFD_RELOC_H8_DIR16R8: howto manager. (line 1918)
-* BFD_RELOC_H8_DIR24A8: howto manager. (line 1919)
-* BFD_RELOC_H8_DIR24R8: howto manager. (line 1920)
-* BFD_RELOC_H8_DIR32A16: howto manager. (line 1921)
-* BFD_RELOC_HI16: howto manager. (line 305)
-* BFD_RELOC_HI16_BASEREL: howto manager. (line 82)
-* BFD_RELOC_HI16_GOTOFF: howto manager. (line 57)
-* BFD_RELOC_HI16_PCREL: howto manager. (line 317)
-* BFD_RELOC_HI16_PLTOFF: howto manager. (line 69)
-* BFD_RELOC_HI16_S: howto manager. (line 308)
-* BFD_RELOC_HI16_S_BASEREL: howto manager. (line 83)
-* BFD_RELOC_HI16_S_GOTOFF: howto manager. (line 58)
-* BFD_RELOC_HI16_S_PCREL: howto manager. (line 320)
-* BFD_RELOC_HI16_S_PLTOFF: howto manager. (line 70)
-* BFD_RELOC_HI22: howto manager. (line 101)
-* BFD_RELOC_I370_D12: howto manager. (line 625)
-* BFD_RELOC_I960_CALLJ: howto manager. (line 113)
-* BFD_RELOC_IA64_COPY: howto manager. (line 1681)
-* BFD_RELOC_IA64_DIR32LSB: howto manager. (line 1626)
-* BFD_RELOC_IA64_DIR32MSB: howto manager. (line 1625)
-* BFD_RELOC_IA64_DIR64LSB: howto manager. (line 1628)
-* BFD_RELOC_IA64_DIR64MSB: howto manager. (line 1627)
-* BFD_RELOC_IA64_DTPMOD64LSB: howto manager. (line 1691)
-* BFD_RELOC_IA64_DTPMOD64MSB: howto manager. (line 1690)
-* BFD_RELOC_IA64_DTPREL14: howto manager. (line 1693)
-* BFD_RELOC_IA64_DTPREL22: howto manager. (line 1694)
-* BFD_RELOC_IA64_DTPREL32LSB: howto manager. (line 1697)
-* BFD_RELOC_IA64_DTPREL32MSB: howto manager. (line 1696)
-* BFD_RELOC_IA64_DTPREL64I: howto manager. (line 1695)
-* BFD_RELOC_IA64_DTPREL64LSB: howto manager. (line 1699)
-* BFD_RELOC_IA64_DTPREL64MSB: howto manager. (line 1698)
-* BFD_RELOC_IA64_FPTR32LSB: howto manager. (line 1643)
-* BFD_RELOC_IA64_FPTR32MSB: howto manager. (line 1642)
-* BFD_RELOC_IA64_FPTR64I: howto manager. (line 1641)
-* BFD_RELOC_IA64_FPTR64LSB: howto manager. (line 1645)
-* BFD_RELOC_IA64_FPTR64MSB: howto manager. (line 1644)
-* BFD_RELOC_IA64_GPREL22: howto manager. (line 1629)
-* BFD_RELOC_IA64_GPREL32LSB: howto manager. (line 1632)
-* BFD_RELOC_IA64_GPREL32MSB: howto manager. (line 1631)
-* BFD_RELOC_IA64_GPREL64I: howto manager. (line 1630)
-* BFD_RELOC_IA64_GPREL64LSB: howto manager. (line 1634)
-* BFD_RELOC_IA64_GPREL64MSB: howto manager. (line 1633)
-* BFD_RELOC_IA64_IMM14: howto manager. (line 1622)
-* BFD_RELOC_IA64_IMM22: howto manager. (line 1623)
-* BFD_RELOC_IA64_IMM64: howto manager. (line 1624)
-* BFD_RELOC_IA64_IPLTLSB: howto manager. (line 1680)
-* BFD_RELOC_IA64_IPLTMSB: howto manager. (line 1679)
-* BFD_RELOC_IA64_LDXMOV: howto manager. (line 1683)
-* BFD_RELOC_IA64_LTOFF22: howto manager. (line 1635)
-* BFD_RELOC_IA64_LTOFF22X: howto manager. (line 1682)
-* BFD_RELOC_IA64_LTOFF64I: howto manager. (line 1636)
-* BFD_RELOC_IA64_LTOFF_DTPMOD22: howto manager. (line 1692)
-* BFD_RELOC_IA64_LTOFF_DTPREL22: howto manager. (line 1700)
-* BFD_RELOC_IA64_LTOFF_FPTR22: howto manager. (line 1657)
-* BFD_RELOC_IA64_LTOFF_FPTR32LSB: howto manager. (line 1660)
-* BFD_RELOC_IA64_LTOFF_FPTR32MSB: howto manager. (line 1659)
-* BFD_RELOC_IA64_LTOFF_FPTR64I: howto manager. (line 1658)
-* BFD_RELOC_IA64_LTOFF_FPTR64LSB: howto manager. (line 1662)
-* BFD_RELOC_IA64_LTOFF_FPTR64MSB: howto manager. (line 1661)
-* BFD_RELOC_IA64_LTOFF_TPREL22: howto manager. (line 1689)
-* BFD_RELOC_IA64_LTV32LSB: howto manager. (line 1676)
-* BFD_RELOC_IA64_LTV32MSB: howto manager. (line 1675)
-* BFD_RELOC_IA64_LTV64LSB: howto manager. (line 1678)
-* BFD_RELOC_IA64_LTV64MSB: howto manager. (line 1677)
-* BFD_RELOC_IA64_PCREL21B: howto manager. (line 1646)
-* BFD_RELOC_IA64_PCREL21BI: howto manager. (line 1647)
-* BFD_RELOC_IA64_PCREL21F: howto manager. (line 1649)
-* BFD_RELOC_IA64_PCREL21M: howto manager. (line 1648)
-* BFD_RELOC_IA64_PCREL22: howto manager. (line 1650)
-* BFD_RELOC_IA64_PCREL32LSB: howto manager. (line 1654)
-* BFD_RELOC_IA64_PCREL32MSB: howto manager. (line 1653)
-* BFD_RELOC_IA64_PCREL60B: howto manager. (line 1651)
-* BFD_RELOC_IA64_PCREL64I: howto manager. (line 1652)
-* BFD_RELOC_IA64_PCREL64LSB: howto manager. (line 1656)
-* BFD_RELOC_IA64_PCREL64MSB: howto manager. (line 1655)
-* BFD_RELOC_IA64_PLTOFF22: howto manager. (line 1637)
-* BFD_RELOC_IA64_PLTOFF64I: howto manager. (line 1638)
-* BFD_RELOC_IA64_PLTOFF64LSB: howto manager. (line 1640)
-* BFD_RELOC_IA64_PLTOFF64MSB: howto manager. (line 1639)
-* BFD_RELOC_IA64_REL32LSB: howto manager. (line 1672)
-* BFD_RELOC_IA64_REL32MSB: howto manager. (line 1671)
-* BFD_RELOC_IA64_REL64LSB: howto manager. (line 1674)
-* BFD_RELOC_IA64_REL64MSB: howto manager. (line 1673)
-* BFD_RELOC_IA64_SECREL32LSB: howto manager. (line 1668)
-* BFD_RELOC_IA64_SECREL32MSB: howto manager. (line 1667)
-* BFD_RELOC_IA64_SECREL64LSB: howto manager. (line 1670)
-* BFD_RELOC_IA64_SECREL64MSB: howto manager. (line 1669)
-* BFD_RELOC_IA64_SEGREL32LSB: howto manager. (line 1664)
-* BFD_RELOC_IA64_SEGREL32MSB: howto manager. (line 1663)
-* BFD_RELOC_IA64_SEGREL64LSB: howto manager. (line 1666)
-* BFD_RELOC_IA64_SEGREL64MSB: howto manager. (line 1665)
-* BFD_RELOC_IA64_TPREL14: howto manager. (line 1684)
-* BFD_RELOC_IA64_TPREL22: howto manager. (line 1685)
-* BFD_RELOC_IA64_TPREL64I: howto manager. (line 1686)
-* BFD_RELOC_IA64_TPREL64LSB: howto manager. (line 1688)
-* BFD_RELOC_IA64_TPREL64MSB: howto manager. (line 1687)
-* BFD_RELOC_IP2K_ADDR16CJP: howto manager. (line 1574)
-* BFD_RELOC_IP2K_BANK: howto manager. (line 1571)
-* BFD_RELOC_IP2K_EX8DATA: howto manager. (line 1582)
-* BFD_RELOC_IP2K_FR9: howto manager. (line 1568)
-* BFD_RELOC_IP2K_FR_OFFSET: howto manager. (line 1595)
-* BFD_RELOC_IP2K_HI8DATA: howto manager. (line 1581)
-* BFD_RELOC_IP2K_HI8INSN: howto manager. (line 1586)
-* BFD_RELOC_IP2K_LO8DATA: howto manager. (line 1580)
-* BFD_RELOC_IP2K_LO8INSN: howto manager. (line 1585)
-* BFD_RELOC_IP2K_PAGE3: howto manager. (line 1577)
-* BFD_RELOC_IP2K_PC_SKIP: howto manager. (line 1589)
-* BFD_RELOC_IP2K_TEXT: howto manager. (line 1592)
-* BFD_RELOC_IQ2000_OFFSET_16: howto manager. (line 1971)
-* BFD_RELOC_IQ2000_OFFSET_21: howto manager. (line 1972)
-* BFD_RELOC_IQ2000_UHI16: howto manager. (line 1973)
-* BFD_RELOC_LO10: howto manager. (line 102)
-* BFD_RELOC_LO16: howto manager. (line 314)
-* BFD_RELOC_LO16_BASEREL: howto manager. (line 81)
-* BFD_RELOC_LO16_GOTOFF: howto manager. (line 56)
-* BFD_RELOC_LO16_PCREL: howto manager. (line 323)
-* BFD_RELOC_LO16_PLTOFF: howto manager. (line 68)
-* BFD_RELOC_M32C_HI8: howto manager. (line 1066)
-* BFD_RELOC_M32C_RL_1ADDR: howto manager. (line 1068)
-* BFD_RELOC_M32C_RL_2ADDR: howto manager. (line 1069)
-* BFD_RELOC_M32C_RL_JUMP: howto manager. (line 1067)
-* BFD_RELOC_M32R_10_PCREL: howto manager. (line 1076)
-* BFD_RELOC_M32R_18_PCREL: howto manager. (line 1080)
-* BFD_RELOC_M32R_24: howto manager. (line 1072)
-* BFD_RELOC_M32R_26_PCREL: howto manager. (line 1083)
-* BFD_RELOC_M32R_26_PLTREL: howto manager. (line 1102)
-* BFD_RELOC_M32R_COPY: howto manager. (line 1103)
-* BFD_RELOC_M32R_GLOB_DAT: howto manager. (line 1104)
-* BFD_RELOC_M32R_GOT16_HI_SLO: howto manager. (line 1113)
-* BFD_RELOC_M32R_GOT16_HI_ULO: howto manager. (line 1112)
-* BFD_RELOC_M32R_GOT16_LO: howto manager. (line 1114)
-* BFD_RELOC_M32R_GOT24: howto manager. (line 1101)
-* BFD_RELOC_M32R_GOTOFF: howto manager. (line 1107)
-* BFD_RELOC_M32R_GOTOFF_HI_SLO: howto manager. (line 1109)
-* BFD_RELOC_M32R_GOTOFF_HI_ULO: howto manager. (line 1108)
-* BFD_RELOC_M32R_GOTOFF_LO: howto manager. (line 1110)
-* BFD_RELOC_M32R_GOTPC24: howto manager. (line 1111)
-* BFD_RELOC_M32R_GOTPC_HI_SLO: howto manager. (line 1116)
-* BFD_RELOC_M32R_GOTPC_HI_ULO: howto manager. (line 1115)
-* BFD_RELOC_M32R_GOTPC_LO: howto manager. (line 1117)
-* BFD_RELOC_M32R_HI16_SLO: howto manager. (line 1090)
-* BFD_RELOC_M32R_HI16_ULO: howto manager. (line 1086)
-* BFD_RELOC_M32R_JMP_SLOT: howto manager. (line 1105)
-* BFD_RELOC_M32R_LO16: howto manager. (line 1094)
-* BFD_RELOC_M32R_RELATIVE: howto manager. (line 1106)
-* BFD_RELOC_M32R_SDA16: howto manager. (line 1097)
-* BFD_RELOC_M68HC11_24: howto manager. (line 1736)
-* BFD_RELOC_M68HC11_3B: howto manager. (line 1711)
-* BFD_RELOC_M68HC11_HI8: howto manager. (line 1703)
-* BFD_RELOC_M68HC11_LO16: howto manager. (line 1725)
-* BFD_RELOC_M68HC11_LO8: howto manager. (line 1707)
-* BFD_RELOC_M68HC11_PAGE: howto manager. (line 1731)
-* BFD_RELOC_M68HC11_RL_GROUP: howto manager. (line 1720)
-* BFD_RELOC_M68HC11_RL_JUMP: howto manager. (line 1714)
-* BFD_RELOC_M68HC12_5B: howto manager. (line 1742)
-* BFD_RELOC_MCORE_PCREL_32: howto manager. (line 1257)
-* BFD_RELOC_MCORE_PCREL_IMM11BY2: howto manager. (line 1255)
-* BFD_RELOC_MCORE_PCREL_IMM4BY2: howto manager. (line 1256)
-* BFD_RELOC_MCORE_PCREL_IMM8BY4: howto manager. (line 1254)
-* BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2: howto manager. (line 1258)
-* BFD_RELOC_MCORE_RVA: howto manager. (line 1259)
-* BFD_RELOC_MEP_16: howto manager. (line 1263)
-* BFD_RELOC_MEP_32: howto manager. (line 1264)
-* BFD_RELOC_MEP_8: howto manager. (line 1262)
-* BFD_RELOC_MEP_ADDR24A4: howto manager. (line 1279)
-* BFD_RELOC_MEP_GNU_VTENTRY: howto manager. (line 1281)
-* BFD_RELOC_MEP_GNU_VTINHERIT: howto manager. (line 1280)
-* BFD_RELOC_MEP_GPREL: howto manager. (line 1273)
-* BFD_RELOC_MEP_HI16S: howto manager. (line 1272)
-* BFD_RELOC_MEP_HI16U: howto manager. (line 1271)
-* BFD_RELOC_MEP_LOW16: howto manager. (line 1270)
-* BFD_RELOC_MEP_PCABS24A2: howto manager. (line 1269)
-* BFD_RELOC_MEP_PCREL12A2: howto manager. (line 1266)
-* BFD_RELOC_MEP_PCREL17A2: howto manager. (line 1267)
-* BFD_RELOC_MEP_PCREL24A2: howto manager. (line 1268)
-* BFD_RELOC_MEP_PCREL8A2: howto manager. (line 1265)
-* BFD_RELOC_MEP_TPREL: howto manager. (line 1274)
-* BFD_RELOC_MEP_TPREL7: howto manager. (line 1275)
-* BFD_RELOC_MEP_TPREL7A2: howto manager. (line 1276)
-* BFD_RELOC_MEP_TPREL7A4: howto manager. (line 1277)
-* BFD_RELOC_MEP_UIMM24: howto manager. (line 1278)
-* BFD_RELOC_MIPS16_GPREL: howto manager. (line 302)
-* BFD_RELOC_MIPS16_HI16: howto manager. (line 326)
-* BFD_RELOC_MIPS16_HI16_S: howto manager. (line 329)
-* BFD_RELOC_MIPS16_JMP: howto manager. (line 299)
-* BFD_RELOC_MIPS16_LO16: howto manager. (line 335)
-* BFD_RELOC_MIPS_CALL16: howto manager. (line 342)
-* BFD_RELOC_MIPS_CALL_HI16: howto manager. (line 345)
-* BFD_RELOC_MIPS_CALL_LO16: howto manager. (line 346)
-* BFD_RELOC_MIPS_COPY: howto manager. (line 377)
-* BFD_RELOC_MIPS_DELETE: howto manager. (line 355)
-* BFD_RELOC_MIPS_GOT16: howto manager. (line 341)
-* BFD_RELOC_MIPS_GOT_DISP: howto manager. (line 350)
-* BFD_RELOC_MIPS_GOT_HI16: howto manager. (line 343)
-* BFD_RELOC_MIPS_GOT_LO16: howto manager. (line 344)
-* BFD_RELOC_MIPS_GOT_OFST: howto manager. (line 349)
-* BFD_RELOC_MIPS_GOT_PAGE: howto manager. (line 348)
-* BFD_RELOC_MIPS_HIGHER: howto manager. (line 357)
-* BFD_RELOC_MIPS_HIGHEST: howto manager. (line 356)
-* BFD_RELOC_MIPS_INSERT_A: howto manager. (line 353)
-* BFD_RELOC_MIPS_INSERT_B: howto manager. (line 354)
-* BFD_RELOC_MIPS_JALR: howto manager. (line 361)
-* BFD_RELOC_MIPS_JMP: howto manager. (line 295)
-* BFD_RELOC_MIPS_JUMP_SLOT: howto manager. (line 378)
-* BFD_RELOC_MIPS_LITERAL: howto manager. (line 338)
-* BFD_RELOC_MIPS_REL16: howto manager. (line 359)
-* BFD_RELOC_MIPS_RELGOT: howto manager. (line 360)
-* BFD_RELOC_MIPS_SCN_DISP: howto manager. (line 358)
-* BFD_RELOC_MIPS_SHIFT5: howto manager. (line 351)
-* BFD_RELOC_MIPS_SHIFT6: howto manager. (line 352)
-* BFD_RELOC_MIPS_SUB: howto manager. (line 347)
-* BFD_RELOC_MIPS_TLS_DTPMOD32: howto manager. (line 362)
-* BFD_RELOC_MIPS_TLS_DTPMOD64: howto manager. (line 364)
-* BFD_RELOC_MIPS_TLS_DTPREL32: howto manager. (line 363)
-* BFD_RELOC_MIPS_TLS_DTPREL64: howto manager. (line 365)
-* BFD_RELOC_MIPS_TLS_DTPREL_HI16: howto manager. (line 368)
-* BFD_RELOC_MIPS_TLS_DTPREL_LO16: howto manager. (line 369)
-* BFD_RELOC_MIPS_TLS_GD: howto manager. (line 366)
-* BFD_RELOC_MIPS_TLS_GOTTPREL: howto manager. (line 370)
-* BFD_RELOC_MIPS_TLS_LDM: howto manager. (line 367)
-* BFD_RELOC_MIPS_TLS_TPREL32: howto manager. (line 371)
-* BFD_RELOC_MIPS_TLS_TPREL64: howto manager. (line 372)
-* BFD_RELOC_MIPS_TLS_TPREL_HI16: howto manager. (line 373)
-* BFD_RELOC_MIPS_TLS_TPREL_LO16: howto manager. (line 374)
-* BFD_RELOC_MMIX_ADDR19: howto manager. (line 1310)
-* BFD_RELOC_MMIX_ADDR27: howto manager. (line 1314)
-* BFD_RELOC_MMIX_BASE_PLUS_OFFSET: howto manager. (line 1326)
-* BFD_RELOC_MMIX_CBRANCH: howto manager. (line 1290)
-* BFD_RELOC_MMIX_CBRANCH_1: howto manager. (line 1292)
-* BFD_RELOC_MMIX_CBRANCH_2: howto manager. (line 1293)
-* BFD_RELOC_MMIX_CBRANCH_3: howto manager. (line 1294)
-* BFD_RELOC_MMIX_CBRANCH_J: howto manager. (line 1291)
-* BFD_RELOC_MMIX_GETA: howto manager. (line 1284)
-* BFD_RELOC_MMIX_GETA_1: howto manager. (line 1285)
-* BFD_RELOC_MMIX_GETA_2: howto manager. (line 1286)
-* BFD_RELOC_MMIX_GETA_3: howto manager. (line 1287)
-* BFD_RELOC_MMIX_JMP: howto manager. (line 1304)
-* BFD_RELOC_MMIX_JMP_1: howto manager. (line 1305)
-* BFD_RELOC_MMIX_JMP_2: howto manager. (line 1306)
-* BFD_RELOC_MMIX_JMP_3: howto manager. (line 1307)
-* BFD_RELOC_MMIX_LOCAL: howto manager. (line 1330)
-* BFD_RELOC_MMIX_PUSHJ: howto manager. (line 1297)
-* BFD_RELOC_MMIX_PUSHJ_1: howto manager. (line 1298)
-* BFD_RELOC_MMIX_PUSHJ_2: howto manager. (line 1299)
-* BFD_RELOC_MMIX_PUSHJ_3: howto manager. (line 1300)
-* BFD_RELOC_MMIX_PUSHJ_STUBBABLE: howto manager. (line 1301)
-* BFD_RELOC_MMIX_REG: howto manager. (line 1322)
-* BFD_RELOC_MMIX_REG_OR_BYTE: howto manager. (line 1318)
-* BFD_RELOC_MN10300_16_PCREL: howto manager. (line 1192)
-* BFD_RELOC_MN10300_32_PCREL: howto manager. (line 1188)
-* BFD_RELOC_MN10300_COPY: howto manager. (line 437)
-* BFD_RELOC_MN10300_GLOB_DAT: howto manager. (line 440)
-* BFD_RELOC_MN10300_GOT16: howto manager. (line 433)
-* BFD_RELOC_MN10300_GOT24: howto manager. (line 429)
-* BFD_RELOC_MN10300_GOT32: howto manager. (line 425)
-* BFD_RELOC_MN10300_GOTOFF24: howto manager. (line 422)
-* BFD_RELOC_MN10300_JMP_SLOT: howto manager. (line 443)
-* BFD_RELOC_MN10300_RELATIVE: howto manager. (line 446)
-* BFD_RELOC_MSP430_10_PCREL: howto manager. (line 1962)
-* BFD_RELOC_MSP430_16: howto manager. (line 1964)
-* BFD_RELOC_MSP430_16_BYTE: howto manager. (line 1966)
-* BFD_RELOC_MSP430_16_PCREL: howto manager. (line 1963)
-* BFD_RELOC_MSP430_16_PCREL_BYTE: howto manager. (line 1965)
-* BFD_RELOC_MSP430_2X_PCREL: howto manager. (line 1967)
-* BFD_RELOC_MSP430_RL_PCREL: howto manager. (line 1968)
-* BFD_RELOC_MT_GNU_VTENTRY: howto manager. (line 1956)
-* BFD_RELOC_MT_GNU_VTINHERIT: howto manager. (line 1953)
-* BFD_RELOC_MT_HI16: howto manager. (line 1947)
-* BFD_RELOC_MT_LO16: howto manager. (line 1950)
-* BFD_RELOC_MT_PC16: howto manager. (line 1944)
-* BFD_RELOC_MT_PCINSN8: howto manager. (line 1959)
-* BFD_RELOC_NONE: howto manager. (line 116)
-* BFD_RELOC_NS32K_DISP_16: howto manager. (line 509)
-* BFD_RELOC_NS32K_DISP_16_PCREL: howto manager. (line 512)
-* BFD_RELOC_NS32K_DISP_32: howto manager. (line 510)
-* BFD_RELOC_NS32K_DISP_32_PCREL: howto manager. (line 513)
-* BFD_RELOC_NS32K_DISP_8: howto manager. (line 508)
-* BFD_RELOC_NS32K_DISP_8_PCREL: howto manager. (line 511)
-* BFD_RELOC_NS32K_IMM_16: howto manager. (line 503)
-* BFD_RELOC_NS32K_IMM_16_PCREL: howto manager. (line 506)
-* BFD_RELOC_NS32K_IMM_32: howto manager. (line 504)
-* BFD_RELOC_NS32K_IMM_32_PCREL: howto manager. (line 507)
-* BFD_RELOC_NS32K_IMM_8: howto manager. (line 502)
-* BFD_RELOC_NS32K_IMM_8_PCREL: howto manager. (line 505)
-* BFD_RELOC_OPENRISC_ABS_26: howto manager. (line 1913)
-* BFD_RELOC_OPENRISC_REL_26: howto manager. (line 1914)
-* BFD_RELOC_PDP11_DISP_6_PCREL: howto manager. (line 517)
-* BFD_RELOC_PDP11_DISP_8_PCREL: howto manager. (line 516)
-* BFD_RELOC_PJ_CODE_DIR16: howto manager. (line 522)
-* BFD_RELOC_PJ_CODE_DIR32: howto manager. (line 523)
-* BFD_RELOC_PJ_CODE_HI16: howto manager. (line 520)
-* BFD_RELOC_PJ_CODE_LO16: howto manager. (line 521)
-* BFD_RELOC_PJ_CODE_REL16: howto manager. (line 524)
-* BFD_RELOC_PJ_CODE_REL32: howto manager. (line 525)
-* BFD_RELOC_PPC64_ADDR16_DS: howto manager. (line 570)
-* BFD_RELOC_PPC64_ADDR16_LO_DS: howto manager. (line 571)
-* BFD_RELOC_PPC64_DTPREL16_DS: howto manager. (line 617)
-* BFD_RELOC_PPC64_DTPREL16_HIGHER: howto manager. (line 619)
-* BFD_RELOC_PPC64_DTPREL16_HIGHERA: howto manager. (line 620)
-* BFD_RELOC_PPC64_DTPREL16_HIGHEST: howto manager. (line 621)
-* BFD_RELOC_PPC64_DTPREL16_HIGHESTA: howto manager. (line 622)
-* BFD_RELOC_PPC64_DTPREL16_LO_DS: howto manager. (line 618)
-* BFD_RELOC_PPC64_GOT16_DS: howto manager. (line 572)
-* BFD_RELOC_PPC64_GOT16_LO_DS: howto manager. (line 573)
-* BFD_RELOC_PPC64_HIGHER: howto manager. (line 558)
-* BFD_RELOC_PPC64_HIGHER_S: howto manager. (line 559)
-* BFD_RELOC_PPC64_HIGHEST: howto manager. (line 560)
-* BFD_RELOC_PPC64_HIGHEST_S: howto manager. (line 561)
-* BFD_RELOC_PPC64_PLT16_LO_DS: howto manager. (line 574)
-* BFD_RELOC_PPC64_PLTGOT16: howto manager. (line 566)
-* BFD_RELOC_PPC64_PLTGOT16_DS: howto manager. (line 579)
-* BFD_RELOC_PPC64_PLTGOT16_HA: howto manager. (line 569)
-* BFD_RELOC_PPC64_PLTGOT16_HI: howto manager. (line 568)
-* BFD_RELOC_PPC64_PLTGOT16_LO: howto manager. (line 567)
-* BFD_RELOC_PPC64_PLTGOT16_LO_DS: howto manager. (line 580)
-* BFD_RELOC_PPC64_SECTOFF_DS: howto manager. (line 575)
-* BFD_RELOC_PPC64_SECTOFF_LO_DS: howto manager. (line 576)
-* BFD_RELOC_PPC64_TOC: howto manager. (line 565)
-* BFD_RELOC_PPC64_TOC16_DS: howto manager. (line 577)
-* BFD_RELOC_PPC64_TOC16_HA: howto manager. (line 564)
-* BFD_RELOC_PPC64_TOC16_HI: howto manager. (line 563)
-* BFD_RELOC_PPC64_TOC16_LO: howto manager. (line 562)
-* BFD_RELOC_PPC64_TOC16_LO_DS: howto manager. (line 578)
-* BFD_RELOC_PPC64_TPREL16_DS: howto manager. (line 611)
-* BFD_RELOC_PPC64_TPREL16_HIGHER: howto manager. (line 613)
-* BFD_RELOC_PPC64_TPREL16_HIGHERA: howto manager. (line 614)
-* BFD_RELOC_PPC64_TPREL16_HIGHEST: howto manager. (line 615)
-* BFD_RELOC_PPC64_TPREL16_HIGHESTA: howto manager. (line 616)
-* BFD_RELOC_PPC64_TPREL16_LO_DS: howto manager. (line 612)
-* BFD_RELOC_PPC_B16: howto manager. (line 531)
-* BFD_RELOC_PPC_B16_BRNTAKEN: howto manager. (line 533)
-* BFD_RELOC_PPC_B16_BRTAKEN: howto manager. (line 532)
-* BFD_RELOC_PPC_B26: howto manager. (line 528)
-* BFD_RELOC_PPC_BA16: howto manager. (line 534)
-* BFD_RELOC_PPC_BA16_BRNTAKEN: howto manager. (line 536)
-* BFD_RELOC_PPC_BA16_BRTAKEN: howto manager. (line 535)
-* BFD_RELOC_PPC_BA26: howto manager. (line 529)
-* BFD_RELOC_PPC_COPY: howto manager. (line 537)
-* BFD_RELOC_PPC_DTPMOD: howto manager. (line 584)
-* BFD_RELOC_PPC_DTPREL: howto manager. (line 594)
-* BFD_RELOC_PPC_DTPREL16: howto manager. (line 590)
-* BFD_RELOC_PPC_DTPREL16_HA: howto manager. (line 593)
-* BFD_RELOC_PPC_DTPREL16_HI: howto manager. (line 592)
-* BFD_RELOC_PPC_DTPREL16_LO: howto manager. (line 591)
-* BFD_RELOC_PPC_EMB_BIT_FLD: howto manager. (line 556)
-* BFD_RELOC_PPC_EMB_MRKREF: howto manager. (line 551)
-* BFD_RELOC_PPC_EMB_NADDR16: howto manager. (line 543)
-* BFD_RELOC_PPC_EMB_NADDR16_HA: howto manager. (line 546)
-* BFD_RELOC_PPC_EMB_NADDR16_HI: howto manager. (line 545)
-* BFD_RELOC_PPC_EMB_NADDR16_LO: howto manager. (line 544)
-* BFD_RELOC_PPC_EMB_NADDR32: howto manager. (line 542)
-* BFD_RELOC_PPC_EMB_RELSDA: howto manager. (line 557)
-* BFD_RELOC_PPC_EMB_RELSEC16: howto manager. (line 552)
-* BFD_RELOC_PPC_EMB_RELST_HA: howto manager. (line 555)
-* BFD_RELOC_PPC_EMB_RELST_HI: howto manager. (line 554)
-* BFD_RELOC_PPC_EMB_RELST_LO: howto manager. (line 553)
-* BFD_RELOC_PPC_EMB_SDA21: howto manager. (line 550)
-* BFD_RELOC_PPC_EMB_SDA2I16: howto manager. (line 548)
-* BFD_RELOC_PPC_EMB_SDA2REL: howto manager. (line 549)
-* BFD_RELOC_PPC_EMB_SDAI16: howto manager. (line 547)
-* BFD_RELOC_PPC_GLOB_DAT: howto manager. (line 538)
-* BFD_RELOC_PPC_GOT_DTPREL16: howto manager. (line 607)
-* BFD_RELOC_PPC_GOT_DTPREL16_HA: howto manager. (line 610)
-* BFD_RELOC_PPC_GOT_DTPREL16_HI: howto manager. (line 609)
-* BFD_RELOC_PPC_GOT_DTPREL16_LO: howto manager. (line 608)
-* BFD_RELOC_PPC_GOT_TLSGD16: howto manager. (line 595)
-* BFD_RELOC_PPC_GOT_TLSGD16_HA: howto manager. (line 598)
-* BFD_RELOC_PPC_GOT_TLSGD16_HI: howto manager. (line 597)
-* BFD_RELOC_PPC_GOT_TLSGD16_LO: howto manager. (line 596)
-* BFD_RELOC_PPC_GOT_TLSLD16: howto manager. (line 599)
-* BFD_RELOC_PPC_GOT_TLSLD16_HA: howto manager. (line 602)
-* BFD_RELOC_PPC_GOT_TLSLD16_HI: howto manager. (line 601)
-* BFD_RELOC_PPC_GOT_TLSLD16_LO: howto manager. (line 600)
-* BFD_RELOC_PPC_GOT_TPREL16: howto manager. (line 603)
-* BFD_RELOC_PPC_GOT_TPREL16_HA: howto manager. (line 606)
-* BFD_RELOC_PPC_GOT_TPREL16_HI: howto manager. (line 605)
-* BFD_RELOC_PPC_GOT_TPREL16_LO: howto manager. (line 604)
-* BFD_RELOC_PPC_JMP_SLOT: howto manager. (line 539)
-* BFD_RELOC_PPC_LOCAL24PC: howto manager. (line 541)
-* BFD_RELOC_PPC_RELATIVE: howto manager. (line 540)
-* BFD_RELOC_PPC_TLS: howto manager. (line 583)
-* BFD_RELOC_PPC_TOC16: howto manager. (line 530)
-* BFD_RELOC_PPC_TPREL: howto manager. (line 589)
-* BFD_RELOC_PPC_TPREL16: howto manager. (line 585)
-* BFD_RELOC_PPC_TPREL16_HA: howto manager. (line 588)
-* BFD_RELOC_PPC_TPREL16_HI: howto manager. (line 587)
-* BFD_RELOC_PPC_TPREL16_LO: howto manager. (line 586)
-* BFD_RELOC_RELC: howto manager. (line 1930)
-* BFD_RELOC_RVA: howto manager. (line 85)
-* BFD_RELOC_SCORE16_BRANCH: howto manager. (line 1559)
-* BFD_RELOC_SCORE16_JMP: howto manager. (line 1556)
-* BFD_RELOC_SCORE_BRANCH: howto manager. (line 1553)
-* BFD_RELOC_SCORE_CALL15: howto manager. (line 1564)
-* BFD_RELOC_SCORE_DUMMY1: howto manager. (line 1543)
-* BFD_RELOC_SCORE_DUMMY2: howto manager. (line 1549)
-* BFD_RELOC_SCORE_DUMMY_HI16: howto manager. (line 1565)
-* BFD_RELOC_SCORE_GOT15: howto manager. (line 1562)
-* BFD_RELOC_SCORE_GOT_LO16: howto manager. (line 1563)
-* BFD_RELOC_SCORE_GPREL15: howto manager. (line 1546)
-* BFD_RELOC_SCORE_JMP: howto manager. (line 1550)
-* BFD_RELOC_SH_ALIGN: howto manager. (line 802)
-* BFD_RELOC_SH_CODE: howto manager. (line 803)
-* BFD_RELOC_SH_COPY: howto manager. (line 808)
-* BFD_RELOC_SH_COPY64: howto manager. (line 833)
-* BFD_RELOC_SH_COUNT: howto manager. (line 801)
-* BFD_RELOC_SH_DATA: howto manager. (line 804)
-* BFD_RELOC_SH_DISP12: howto manager. (line 784)
-* BFD_RELOC_SH_DISP12BY2: howto manager. (line 785)
-* BFD_RELOC_SH_DISP12BY4: howto manager. (line 786)
-* BFD_RELOC_SH_DISP12BY8: howto manager. (line 787)
-* BFD_RELOC_SH_DISP20: howto manager. (line 788)
-* BFD_RELOC_SH_DISP20BY8: howto manager. (line 789)
-* BFD_RELOC_SH_GLOB_DAT: howto manager. (line 809)
-* BFD_RELOC_SH_GLOB_DAT64: howto manager. (line 834)
-* BFD_RELOC_SH_GOT10BY4: howto manager. (line 837)
-* BFD_RELOC_SH_GOT10BY8: howto manager. (line 838)
-* BFD_RELOC_SH_GOT_HI16: howto manager. (line 816)
-* BFD_RELOC_SH_GOT_LOW16: howto manager. (line 813)
-* BFD_RELOC_SH_GOT_MEDHI16: howto manager. (line 815)
-* BFD_RELOC_SH_GOT_MEDLOW16: howto manager. (line 814)
-* BFD_RELOC_SH_GOTOFF_HI16: howto manager. (line 828)
-* BFD_RELOC_SH_GOTOFF_LOW16: howto manager. (line 825)
-* BFD_RELOC_SH_GOTOFF_MEDHI16: howto manager. (line 827)
-* BFD_RELOC_SH_GOTOFF_MEDLOW16: howto manager. (line 826)
-* BFD_RELOC_SH_GOTPC: howto manager. (line 812)
-* BFD_RELOC_SH_GOTPC_HI16: howto manager. (line 832)
-* BFD_RELOC_SH_GOTPC_LOW16: howto manager. (line 829)
-* BFD_RELOC_SH_GOTPC_MEDHI16: howto manager. (line 831)
-* BFD_RELOC_SH_GOTPC_MEDLOW16: howto manager. (line 830)
-* BFD_RELOC_SH_GOTPLT10BY4: howto manager. (line 839)
-* BFD_RELOC_SH_GOTPLT10BY8: howto manager. (line 840)
-* BFD_RELOC_SH_GOTPLT32: howto manager. (line 841)
-* BFD_RELOC_SH_GOTPLT_HI16: howto manager. (line 820)
-* BFD_RELOC_SH_GOTPLT_LOW16: howto manager. (line 817)
-* BFD_RELOC_SH_GOTPLT_MEDHI16: howto manager. (line 819)
-* BFD_RELOC_SH_GOTPLT_MEDLOW16: howto manager. (line 818)
-* BFD_RELOC_SH_IMM3: howto manager. (line 782)
-* BFD_RELOC_SH_IMM3U: howto manager. (line 783)
-* BFD_RELOC_SH_IMM4: howto manager. (line 790)
-* BFD_RELOC_SH_IMM4BY2: howto manager. (line 791)
-* BFD_RELOC_SH_IMM4BY4: howto manager. (line 792)
-* BFD_RELOC_SH_IMM8: howto manager. (line 793)
-* BFD_RELOC_SH_IMM8BY2: howto manager. (line 794)
-* BFD_RELOC_SH_IMM8BY4: howto manager. (line 795)
-* BFD_RELOC_SH_IMM_HI16: howto manager. (line 859)
-* BFD_RELOC_SH_IMM_HI16_PCREL: howto manager. (line 860)
-* BFD_RELOC_SH_IMM_LOW16: howto manager. (line 853)
-* BFD_RELOC_SH_IMM_LOW16_PCREL: howto manager. (line 854)
-* BFD_RELOC_SH_IMM_MEDHI16: howto manager. (line 857)
-* BFD_RELOC_SH_IMM_MEDHI16_PCREL: howto manager. (line 858)
-* BFD_RELOC_SH_IMM_MEDLOW16: howto manager. (line 855)
-* BFD_RELOC_SH_IMM_MEDLOW16_PCREL: howto manager. (line 856)
-* BFD_RELOC_SH_IMMS10: howto manager. (line 847)
-* BFD_RELOC_SH_IMMS10BY2: howto manager. (line 848)
-* BFD_RELOC_SH_IMMS10BY4: howto manager. (line 849)
-* BFD_RELOC_SH_IMMS10BY8: howto manager. (line 850)
-* BFD_RELOC_SH_IMMS16: howto manager. (line 851)
-* BFD_RELOC_SH_IMMS6: howto manager. (line 844)
-* BFD_RELOC_SH_IMMS6BY32: howto manager. (line 845)
-* BFD_RELOC_SH_IMMU16: howto manager. (line 852)
-* BFD_RELOC_SH_IMMU5: howto manager. (line 843)
-* BFD_RELOC_SH_IMMU6: howto manager. (line 846)
-* BFD_RELOC_SH_JMP_SLOT: howto manager. (line 810)
-* BFD_RELOC_SH_JMP_SLOT64: howto manager. (line 835)
-* BFD_RELOC_SH_LABEL: howto manager. (line 805)
-* BFD_RELOC_SH_LOOP_END: howto manager. (line 807)
-* BFD_RELOC_SH_LOOP_START: howto manager. (line 806)
-* BFD_RELOC_SH_PCDISP12BY2: howto manager. (line 781)
-* BFD_RELOC_SH_PCDISP8BY2: howto manager. (line 780)
-* BFD_RELOC_SH_PCRELIMM8BY2: howto manager. (line 796)
-* BFD_RELOC_SH_PCRELIMM8BY4: howto manager. (line 797)
-* BFD_RELOC_SH_PLT_HI16: howto manager. (line 824)
-* BFD_RELOC_SH_PLT_LOW16: howto manager. (line 821)
-* BFD_RELOC_SH_PLT_MEDHI16: howto manager. (line 823)
-* BFD_RELOC_SH_PLT_MEDLOW16: howto manager. (line 822)
-* BFD_RELOC_SH_PT_16: howto manager. (line 861)
-* BFD_RELOC_SH_RELATIVE: howto manager. (line 811)
-* BFD_RELOC_SH_RELATIVE64: howto manager. (line 836)
-* BFD_RELOC_SH_SHMEDIA_CODE: howto manager. (line 842)
-* BFD_RELOC_SH_SWITCH16: howto manager. (line 798)
-* BFD_RELOC_SH_SWITCH32: howto manager. (line 799)
-* BFD_RELOC_SH_TLS_DTPMOD32: howto manager. (line 867)
-* BFD_RELOC_SH_TLS_DTPOFF32: howto manager. (line 868)
-* BFD_RELOC_SH_TLS_GD_32: howto manager. (line 862)
-* BFD_RELOC_SH_TLS_IE_32: howto manager. (line 865)
-* BFD_RELOC_SH_TLS_LD_32: howto manager. (line 863)
-* BFD_RELOC_SH_TLS_LDO_32: howto manager. (line 864)
-* BFD_RELOC_SH_TLS_LE_32: howto manager. (line 866)
-* BFD_RELOC_SH_TLS_TPOFF32: howto manager. (line 869)
-* BFD_RELOC_SH_USES: howto manager. (line 800)
-* BFD_RELOC_SPARC13: howto manager. (line 119)
-* BFD_RELOC_SPARC22: howto manager. (line 118)
-* BFD_RELOC_SPARC_10: howto manager. (line 141)
-* BFD_RELOC_SPARC_11: howto manager. (line 142)
-* BFD_RELOC_SPARC_5: howto manager. (line 154)
-* BFD_RELOC_SPARC_6: howto manager. (line 153)
-* BFD_RELOC_SPARC_64: howto manager. (line 140)
-* BFD_RELOC_SPARC_7: howto manager. (line 152)
-* BFD_RELOC_SPARC_BASE13: howto manager. (line 136)
-* BFD_RELOC_SPARC_BASE22: howto manager. (line 137)
-* BFD_RELOC_SPARC_COPY: howto manager. (line 126)
-* BFD_RELOC_SPARC_DISP64: howto manager. (line 155)
-* BFD_RELOC_SPARC_GLOB_DAT: howto manager. (line 127)
-* BFD_RELOC_SPARC_GOT10: howto manager. (line 120)
-* BFD_RELOC_SPARC_GOT13: howto manager. (line 121)
-* BFD_RELOC_SPARC_GOT22: howto manager. (line 122)
-* BFD_RELOC_SPARC_H44: howto manager. (line 160)
-* BFD_RELOC_SPARC_HH22: howto manager. (line 144)
-* BFD_RELOC_SPARC_HIX22: howto manager. (line 158)
-* BFD_RELOC_SPARC_HM10: howto manager. (line 145)
-* BFD_RELOC_SPARC_JMP_SLOT: howto manager. (line 128)
-* BFD_RELOC_SPARC_L44: howto manager. (line 162)
-* BFD_RELOC_SPARC_LM22: howto manager. (line 146)
-* BFD_RELOC_SPARC_LOX10: howto manager. (line 159)
-* BFD_RELOC_SPARC_M44: howto manager. (line 161)
-* BFD_RELOC_SPARC_OLO10: howto manager. (line 143)
-* BFD_RELOC_SPARC_PC10: howto manager. (line 123)
-* BFD_RELOC_SPARC_PC22: howto manager. (line 124)
-* BFD_RELOC_SPARC_PC_HH22: howto manager. (line 147)
-* BFD_RELOC_SPARC_PC_HM10: howto manager. (line 148)
-* BFD_RELOC_SPARC_PC_LM22: howto manager. (line 149)
-* BFD_RELOC_SPARC_PLT32: howto manager. (line 156)
-* BFD_RELOC_SPARC_PLT64: howto manager. (line 157)
-* BFD_RELOC_SPARC_REGISTER: howto manager. (line 163)
-* BFD_RELOC_SPARC_RELATIVE: howto manager. (line 129)
-* BFD_RELOC_SPARC_REV32: howto manager. (line 166)
-* BFD_RELOC_SPARC_TLS_DTPMOD32: howto manager. (line 187)
-* BFD_RELOC_SPARC_TLS_DTPMOD64: howto manager. (line 188)
-* BFD_RELOC_SPARC_TLS_DTPOFF32: howto manager. (line 189)
-* BFD_RELOC_SPARC_TLS_DTPOFF64: howto manager. (line 190)
-* BFD_RELOC_SPARC_TLS_GD_ADD: howto manager. (line 171)
-* BFD_RELOC_SPARC_TLS_GD_CALL: howto manager. (line 172)
-* BFD_RELOC_SPARC_TLS_GD_HI22: howto manager. (line 169)
-* BFD_RELOC_SPARC_TLS_GD_LO10: howto manager. (line 170)
-* BFD_RELOC_SPARC_TLS_IE_ADD: howto manager. (line 184)
-* BFD_RELOC_SPARC_TLS_IE_HI22: howto manager. (line 180)
-* BFD_RELOC_SPARC_TLS_IE_LD: howto manager. (line 182)
-* BFD_RELOC_SPARC_TLS_IE_LDX: howto manager. (line 183)
-* BFD_RELOC_SPARC_TLS_IE_LO10: howto manager. (line 181)
-* BFD_RELOC_SPARC_TLS_LDM_ADD: howto manager. (line 175)
-* BFD_RELOC_SPARC_TLS_LDM_CALL: howto manager. (line 176)
-* BFD_RELOC_SPARC_TLS_LDM_HI22: howto manager. (line 173)
-* BFD_RELOC_SPARC_TLS_LDM_LO10: howto manager. (line 174)
-* BFD_RELOC_SPARC_TLS_LDO_ADD: howto manager. (line 179)
-* BFD_RELOC_SPARC_TLS_LDO_HIX22: howto manager. (line 177)
-* BFD_RELOC_SPARC_TLS_LDO_LOX10: howto manager. (line 178)
-* BFD_RELOC_SPARC_TLS_LE_HIX22: howto manager. (line 185)
-* BFD_RELOC_SPARC_TLS_LE_LOX10: howto manager. (line 186)
-* BFD_RELOC_SPARC_TLS_TPOFF32: howto manager. (line 191)
-* BFD_RELOC_SPARC_TLS_TPOFF64: howto manager. (line 192)
-* BFD_RELOC_SPARC_UA16: howto manager. (line 130)
-* BFD_RELOC_SPARC_UA32: howto manager. (line 131)
-* BFD_RELOC_SPARC_UA64: howto manager. (line 132)
-* BFD_RELOC_SPARC_WDISP16: howto manager. (line 150)
-* BFD_RELOC_SPARC_WDISP19: howto manager. (line 151)
-* BFD_RELOC_SPARC_WDISP22: howto manager. (line 117)
-* BFD_RELOC_SPARC_WPLT30: howto manager. (line 125)
-* BFD_RELOC_SPU_HI16: howto manager. (line 206)
-* BFD_RELOC_SPU_IMM10: howto manager. (line 197)
-* BFD_RELOC_SPU_IMM10W: howto manager. (line 198)
-* BFD_RELOC_SPU_IMM16: howto manager. (line 199)
-* BFD_RELOC_SPU_IMM16W: howto manager. (line 200)
-* BFD_RELOC_SPU_IMM18: howto manager. (line 201)
-* BFD_RELOC_SPU_IMM7: howto manager. (line 195)
-* BFD_RELOC_SPU_IMM8: howto manager. (line 196)
-* BFD_RELOC_SPU_LO16: howto manager. (line 205)
-* BFD_RELOC_SPU_PCREL16: howto manager. (line 204)
-* BFD_RELOC_SPU_PCREL9a: howto manager. (line 202)
-* BFD_RELOC_SPU_PCREL9b: howto manager. (line 203)
-* BFD_RELOC_SPU_PPU32: howto manager. (line 207)
-* BFD_RELOC_SPU_PPU64: howto manager. (line 208)
-* BFD_RELOC_THUMB_PCREL_BLX: howto manager. (line 643)
-* BFD_RELOC_THUMB_PCREL_BRANCH12: howto manager. (line 657)
-* BFD_RELOC_THUMB_PCREL_BRANCH20: howto manager. (line 658)
-* BFD_RELOC_THUMB_PCREL_BRANCH23: howto manager. (line 659)
-* BFD_RELOC_THUMB_PCREL_BRANCH25: howto manager. (line 660)
-* BFD_RELOC_THUMB_PCREL_BRANCH7: howto manager. (line 655)
-* BFD_RELOC_THUMB_PCREL_BRANCH9: howto manager. (line 656)
-* BFD_RELOC_TIC30_LDP: howto manager. (line 1196)
-* BFD_RELOC_TIC54X_16_OF_23: howto manager. (line 1214)
-* BFD_RELOC_TIC54X_23: howto manager. (line 1211)
-* BFD_RELOC_TIC54X_MS7_OF_23: howto manager. (line 1219)
-* BFD_RELOC_TIC54X_PARTLS7: howto manager. (line 1201)
-* BFD_RELOC_TIC54X_PARTMS9: howto manager. (line 1206)
-* bfd_reloc_type_lookup: howto manager. (line 2068)
-* BFD_RELOC_V850_22_PCREL: howto manager. (line 1123)
-* BFD_RELOC_V850_9_PCREL: howto manager. (line 1120)
-* BFD_RELOC_V850_ALIGN: howto manager. (line 1181)
-* BFD_RELOC_V850_CALLT_16_16_OFFSET: howto manager. (line 1172)
-* BFD_RELOC_V850_CALLT_6_7_OFFSET: howto manager. (line 1169)
-* BFD_RELOC_V850_LO16_SPLIT_OFFSET: howto manager. (line 1184)
-* BFD_RELOC_V850_LONGCALL: howto manager. (line 1175)
-* BFD_RELOC_V850_LONGJUMP: howto manager. (line 1178)
-* BFD_RELOC_V850_SDA_15_16_OFFSET: howto manager. (line 1129)
-* BFD_RELOC_V850_SDA_16_16_OFFSET: howto manager. (line 1126)
-* BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET: howto manager. (line 1161)
-* BFD_RELOC_V850_TDA_16_16_OFFSET: howto manager. (line 1151)
-* BFD_RELOC_V850_TDA_4_4_OFFSET: howto manager. (line 1158)
-* BFD_RELOC_V850_TDA_4_5_OFFSET: howto manager. (line 1154)
-* BFD_RELOC_V850_TDA_6_8_OFFSET: howto manager. (line 1140)
-* BFD_RELOC_V850_TDA_7_7_OFFSET: howto manager. (line 1148)
-* BFD_RELOC_V850_TDA_7_8_OFFSET: howto manager. (line 1144)
-* BFD_RELOC_V850_ZDA_15_16_OFFSET: howto manager. (line 1136)
-* BFD_RELOC_V850_ZDA_16_16_OFFSET: howto manager. (line 1133)
-* BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET: howto manager. (line 1165)
-* BFD_RELOC_VAX_GLOB_DAT: howto manager. (line 1939)
-* BFD_RELOC_VAX_JMP_SLOT: howto manager. (line 1940)
-* BFD_RELOC_VAX_RELATIVE: howto manager. (line 1941)
-* BFD_RELOC_VPE4KMATH_DATA: howto manager. (line 1598)
-* BFD_RELOC_VPE4KMATH_INSN: howto manager. (line 1599)
-* BFD_RELOC_VTABLE_ENTRY: howto manager. (line 1603)
-* BFD_RELOC_VTABLE_INHERIT: howto manager. (line 1602)
-* BFD_RELOC_X86_64_32S: howto manager. (line 481)
-* BFD_RELOC_X86_64_COPY: howto manager. (line 476)
-* BFD_RELOC_X86_64_DTPMOD64: howto manager. (line 482)
-* BFD_RELOC_X86_64_DTPOFF32: howto manager. (line 487)
-* BFD_RELOC_X86_64_DTPOFF64: howto manager. (line 483)
-* BFD_RELOC_X86_64_GLOB_DAT: howto manager. (line 477)
-* BFD_RELOC_X86_64_GOT32: howto manager. (line 474)
-* BFD_RELOC_X86_64_GOT64: howto manager. (line 492)
-* BFD_RELOC_X86_64_GOTOFF64: howto manager. (line 490)
-* BFD_RELOC_X86_64_GOTPC32: howto manager. (line 491)
-* BFD_RELOC_X86_64_GOTPC32_TLSDESC: howto manager. (line 497)
-* BFD_RELOC_X86_64_GOTPC64: howto manager. (line 494)
-* BFD_RELOC_X86_64_GOTPCREL: howto manager. (line 480)
-* BFD_RELOC_X86_64_GOTPCREL64: howto manager. (line 493)
-* BFD_RELOC_X86_64_GOTPLT64: howto manager. (line 495)
-* BFD_RELOC_X86_64_GOTTPOFF: howto manager. (line 488)
-* BFD_RELOC_X86_64_JUMP_SLOT: howto manager. (line 478)
-* BFD_RELOC_X86_64_PLT32: howto manager. (line 475)
-* BFD_RELOC_X86_64_PLTOFF64: howto manager. (line 496)
-* BFD_RELOC_X86_64_RELATIVE: howto manager. (line 479)
-* BFD_RELOC_X86_64_TLSDESC: howto manager. (line 499)
-* BFD_RELOC_X86_64_TLSDESC_CALL: howto manager. (line 498)
-* BFD_RELOC_X86_64_TLSGD: howto manager. (line 485)
-* BFD_RELOC_X86_64_TLSLD: howto manager. (line 486)
-* BFD_RELOC_X86_64_TPOFF32: howto manager. (line 489)
-* BFD_RELOC_X86_64_TPOFF64: howto manager. (line 484)
-* BFD_RELOC_XC16X_PAG: howto manager. (line 1933)
-* BFD_RELOC_XC16X_POF: howto manager. (line 1934)
-* BFD_RELOC_XC16X_SEG: howto manager. (line 1935)
-* BFD_RELOC_XC16X_SOF: howto manager. (line 1936)
-* BFD_RELOC_XSTORMY16_12: howto manager. (line 1925)
-* BFD_RELOC_XSTORMY16_24: howto manager. (line 1926)
-* BFD_RELOC_XSTORMY16_FPTR16: howto manager. (line 1927)
-* BFD_RELOC_XSTORMY16_REL_12: howto manager. (line 1924)
-* BFD_RELOC_XTENSA_ASM_EXPAND: howto manager. (line 2045)
-* BFD_RELOC_XTENSA_ASM_SIMPLIFY: howto manager. (line 2050)
-* BFD_RELOC_XTENSA_DIFF16: howto manager. (line 1992)
-* BFD_RELOC_XTENSA_DIFF32: howto manager. (line 1993)
-* BFD_RELOC_XTENSA_DIFF8: howto manager. (line 1991)
-* BFD_RELOC_XTENSA_GLOB_DAT: howto manager. (line 1981)
-* BFD_RELOC_XTENSA_JMP_SLOT: howto manager. (line 1982)
-* BFD_RELOC_XTENSA_OP0: howto manager. (line 2039)
-* BFD_RELOC_XTENSA_OP1: howto manager. (line 2040)
-* BFD_RELOC_XTENSA_OP2: howto manager. (line 2041)
-* BFD_RELOC_XTENSA_PLT: howto manager. (line 1986)
-* BFD_RELOC_XTENSA_RELATIVE: howto manager. (line 1983)
-* BFD_RELOC_XTENSA_RTLD: howto manager. (line 1976)
-* BFD_RELOC_XTENSA_SLOT0_ALT: howto manager. (line 2021)
-* BFD_RELOC_XTENSA_SLOT0_OP: howto manager. (line 2001)
-* BFD_RELOC_XTENSA_SLOT10_ALT: howto manager. (line 2031)
-* BFD_RELOC_XTENSA_SLOT10_OP: howto manager. (line 2011)
-* BFD_RELOC_XTENSA_SLOT11_ALT: howto manager. (line 2032)
-* BFD_RELOC_XTENSA_SLOT11_OP: howto manager. (line 2012)
-* BFD_RELOC_XTENSA_SLOT12_ALT: howto manager. (line 2033)
-* BFD_RELOC_XTENSA_SLOT12_OP: howto manager. (line 2013)
-* BFD_RELOC_XTENSA_SLOT13_ALT: howto manager. (line 2034)
-* BFD_RELOC_XTENSA_SLOT13_OP: howto manager. (line 2014)
-* BFD_RELOC_XTENSA_SLOT14_ALT: howto manager. (line 2035)
-* BFD_RELOC_XTENSA_SLOT14_OP: howto manager. (line 2015)
-* BFD_RELOC_XTENSA_SLOT1_ALT: howto manager. (line 2022)
-* BFD_RELOC_XTENSA_SLOT1_OP: howto manager. (line 2002)
-* BFD_RELOC_XTENSA_SLOT2_ALT: howto manager. (line 2023)
-* BFD_RELOC_XTENSA_SLOT2_OP: howto manager. (line 2003)
-* BFD_RELOC_XTENSA_SLOT3_ALT: howto manager. (line 2024)
-* BFD_RELOC_XTENSA_SLOT3_OP: howto manager. (line 2004)
-* BFD_RELOC_XTENSA_SLOT4_ALT: howto manager. (line 2025)
-* BFD_RELOC_XTENSA_SLOT4_OP: howto manager. (line 2005)
-* BFD_RELOC_XTENSA_SLOT5_ALT: howto manager. (line 2026)
-* BFD_RELOC_XTENSA_SLOT5_OP: howto manager. (line 2006)
-* BFD_RELOC_XTENSA_SLOT6_ALT: howto manager. (line 2027)
-* BFD_RELOC_XTENSA_SLOT6_OP: howto manager. (line 2007)
-* BFD_RELOC_XTENSA_SLOT7_ALT: howto manager. (line 2028)
-* BFD_RELOC_XTENSA_SLOT7_OP: howto manager. (line 2008)
-* BFD_RELOC_XTENSA_SLOT8_ALT: howto manager. (line 2029)
-* BFD_RELOC_XTENSA_SLOT8_OP: howto manager. (line 2009)
-* BFD_RELOC_XTENSA_SLOT9_ALT: howto manager. (line 2030)
-* BFD_RELOC_XTENSA_SLOT9_OP: howto manager. (line 2010)
-* BFD_RELOC_Z80_DISP8: howto manager. (line 2055)
-* BFD_RELOC_Z8K_CALLR: howto manager. (line 2061)
-* BFD_RELOC_Z8K_DISP7: howto manager. (line 2058)
-* BFD_RELOC_Z8K_IMM4L: howto manager. (line 2064)
-* bfd_scan_arch: Architectures. (line 406)
-* bfd_scan_vma: BFD front end. (line 426)
-* bfd_seach_for_target: bfd_target. (line 464)
-* bfd_section_already_linked: Writing the symbol table.
- (line 55)
-* bfd_section_list_clear: section prototypes. (line 8)
-* bfd_sections_find_if: section prototypes. (line 176)
-* bfd_set_arch_info: Architectures. (line 447)
-* bfd_set_archive_head: Archives. (line 69)
-* bfd_set_default_target: bfd_target. (line 429)
-* bfd_set_error: BFD front end. (line 236)
-* bfd_set_error_handler: BFD front end. (line 278)
-* bfd_set_error_program_name: BFD front end. (line 287)
-* bfd_set_file_flags: BFD front end. (line 346)
-* bfd_set_format: Formats. (line 68)
-* bfd_set_gp_size: BFD front end. (line 416)
-* bfd_set_private_flags: BFD front end. (line 493)
-* bfd_set_reloc: BFD front end. (line 336)
-* bfd_set_section_contents: section prototypes. (line 207)
-* bfd_set_section_flags: section prototypes. (line 140)
-* bfd_set_section_size: section prototypes. (line 193)
-* bfd_set_start_address: BFD front end. (line 395)
-* bfd_set_symtab: symbol handling functions.
- (line 60)
-* bfd_symbol_info: symbol handling functions.
- (line 130)
-* bfd_target_list: bfd_target. (line 455)
-* bfd_write_bigendian_4byte_int: Internal. (line 13)
-* bfd_zalloc: Opening and Closing.
- (line 228)
-* bfd_zalloc2: Opening and Closing.
- (line 237)
-* coff_symbol_type: coff. (line 186)
-* core_file_matches_executable_p: Core Files. (line 30)
-* find_separate_debug_file: Opening and Closing.
- (line 279)
-* generic_core_file_matches_executable_p: Core Files. (line 40)
-* get_debug_link_info: Opening and Closing.
- (line 260)
-* Hash tables: Hash Tables. (line 6)
-* internal object-file format: Canonical format. (line 11)
-* Linker: Linker Functions. (line 6)
-* Other functions: BFD front end. (line 508)
-* separate_debug_file_exists: Opening and Closing.
- (line 270)
-* struct bfd_iovec: BFD front end. (line 711)
-* target vector (_bfd_final_link): Performing the Final Link.
- (line 6)
-* target vector (_bfd_link_add_symbols): Adding Symbols to the Hash Table.
- (line 6)
-* target vector (_bfd_link_hash_table_create): Creating a Linker Hash Table.
- (line 6)
-* The HOWTO Macro: typedef arelent. (line 291)
-* what is it?: Overview. (line 6)
-
-
-\1f
-Tag Table:
-Node: Top\7f1045
-Node: Overview\7f1384
-Node: History\7f2435
-Node: How It Works\7f3381
-Node: What BFD Version 2 Can Do\7f4924
-Node: BFD information loss\7f6239
-Node: Canonical format\7f8771
-Node: BFD front end\7f13143
-Node: Memory Usage\7f40479
-Node: Initialization\7f41707
-Node: Sections\7f42166
-Node: Section Input\7f42649
-Node: Section Output\7f44014
-Node: typedef asection\7f46500
-Node: section prototypes\7f71101
-Node: Symbols\7f80781
-Node: Reading Symbols\7f82376
-Node: Writing Symbols\7f83483
-Node: Mini Symbols\7f85192
-Node: typedef asymbol\7f86166
-Node: symbol handling functions\7f91427
-Node: Archives\7f96769
-Node: Formats\7f100495
-Node: Relocations\7f103443
-Node: typedef arelent\7f104170
-Node: howto manager\7f119981
-Node: Core Files\7f186663
-Node: Targets\7f188480
-Node: bfd_target\7f190450
-Node: Architectures\7f210755
-Node: Opening and Closing\7f232762
-Node: Internal\7f244026
-Node: File Caching\7f250359
-Node: Linker Functions\7f252273
-Node: Creating a Linker Hash Table\7f253946
-Node: Adding Symbols to the Hash Table\7f255684
-Node: Differing file formats\7f256584
-Node: Adding symbols from an object file\7f258332
-Node: Adding symbols from an archive\7f260483
-Node: Performing the Final Link\7f262897
-Node: Information provided by the linker\7f264139
-Node: Relocating the section contents\7f265293
-Node: Writing the symbol table\7f267044
-Node: Hash Tables\7f270086
-Node: Creating and Freeing a Hash Table\7f271284
-Node: Looking Up or Entering a String\7f272534
-Node: Traversing a Hash Table\7f273787
-Node: Deriving a New Hash Table Type\7f274576
-Node: Define the Derived Structures\7f275642
-Node: Write the Derived Creation Routine\7f276723
-Node: Write Other Derived Routines\7f279347
-Node: BFD back ends\7f280662
-Node: What to Put Where\7f280932
-Node: aout\7f281112
-Node: coff\7f287430
-Node: elf\7f311907
-Node: mmo\7f312770
-Node: File layout\7f313698
-Node: Symbol-table\7f319345
-Node: mmo section mapping\7f323114
-Node: GNU Free Documentation License\7f326766
-Node: BFD Index\7f346495
-\1f
-End Tag Table
+++ /dev/null
-This is binutils.info, produced by makeinfo version 4.8 from
-binutils.texi.
-
-START-INFO-DIR-ENTRY
-* Binutils: (binutils). The GNU binary utilities.
-* ar: (binutils)ar. Create, modify, and extract from archives
-* nm: (binutils)nm. List symbols from object files
-* objcopy: (binutils)objcopy. Copy and translate object files
-* objdump: (binutils)objdump. Display information from object files
-* ranlib: (binutils)ranlib. Generate index to archive contents
-* readelf: (binutils)readelf. Display the contents of ELF format files.
-* size: (binutils)size. List section sizes and total size
-* strings: (binutils)strings. List printable strings from files
-* strip: (binutils)strip. Discard symbols
-* c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols
-* cxxfilt: (binutils)c++filt. MS-DOS name for c++filt
-* addr2line: (binutils)addr2line. Convert addresses to file and line
-* nlmconv: (binutils)nlmconv. Converts object code into an NLM
-* windres: (binutils)windres. Manipulate Windows resources
-* windmc: (binutils)windmc. Generator for Windows message resources
-* dlltool: (binutils)dlltool. Create files needed to build and use DLLs
-END-INFO-DIR-ENTRY
-
- Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software
-Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-\1f
-File: binutils.info, Node: Top, Next: ar, Up: (dir)
-
-Introduction
-************
-
-This brief manual contains documentation for the GNU binary utilities
-(GNU Binutils) version 2.17.90:
-
- 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".
-
-* Menu:
-
-* ar:: Create, modify, and extract from archives
-* nm:: List symbols from object files
-* objcopy:: Copy and translate object files
-* objdump:: Display information from object files
-* ranlib:: Generate index to archive contents
-* readelf:: Display the contents of ELF format files.
-* size:: List section sizes and total size
-* strings:: List printable strings from files
-* strip:: Discard symbols
-* c++filt:: Filter to demangle encoded C++ symbols
-* cxxfilt: c++filt. MS-DOS name for c++filt
-* addr2line:: Convert addresses to file and line
-* nlmconv:: Converts object code into an NLM
-* windres:: Manipulate Windows resources
-* windmc:: Generator for Windows message resources
-* dlltool:: Create files needed to build and use DLLs
-* Common Options:: Command-line options for all utilities
-* Selecting The Target System:: How these utilities determine the target.
-* Reporting Bugs:: Reporting Bugs
-* GNU Free Documentation License:: GNU Free Documentation License
-* Binutils Index:: Binutils Index
-
-\1f
-File: binutils.info, Node: ar, Next: nm, Prev: Top, Up: Top
-
-1 ar
-****
-
- ar [-]P[MOD [RELPOS] [COUNT]] ARCHIVE [MEMBER...]
- ar -M [ <mri-script ]
-
- The GNU `ar' program creates, modifies, and extracts from archives.
-An "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 "members" of the archive).
-
- The original files' contents, mode (permissions), timestamp, owner,
-and group are preserved in the archive, and can be restored on
-extraction.
-
- GNU `ar' can maintain archives whose members have names of any
-length; however, depending on how `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).
-
- `ar' is considered a binary utility because archives of this sort
-are most often used as "libraries" holding commonly needed subroutines.
-
- `ar' creates an index to the symbols defined in relocatable object
-modules in the archive when you specify the modifier `s'. Once
-created, this index is updated in the archive whenever `ar' makes a
-change to its contents (save for the `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.
-
- You may use `nm -s' or `nm --print-armap' to list this index table.
-If an archive lacks the table, another form of `ar' called `ranlib' can
-be used to add just the table.
-
- GNU `ar' is designed to be compatible with two different facilities.
-You can control its activity using command-line options, like the
-different varieties of `ar' on Unix systems; or, if you specify the
-single command-line option `-M', you can control it with a script
-supplied via standard input, like the MRI "librarian" program.
-
-* Menu:
-
-* ar cmdline:: Controlling `ar' on the command line
-* ar scripts:: Controlling `ar' with a script
-
-\1f
-File: binutils.info, Node: ar cmdline, Next: ar scripts, Up: ar
-
-1.1 Controlling `ar' on the Command Line
-========================================
-
- ar [`-X32_64'] [`-']P[MOD [RELPOS] [COUNT]] ARCHIVE [MEMBER...]
-
- When you use `ar' in the Unix style, `ar' insists on at least two
-arguments to execute: one keyletter specifying the _operation_
-(optionally accompanied by other keyletters specifying _modifiers_),
-and the archive name to act on.
-
- Most operations can also accept further MEMBER arguments, specifying
-particular files to operate on.
-
- GNU `ar' allows you to mix the operation code P and modifier flags
-MOD in any order, within the first command-line argument.
-
- If you wish, you may begin the first command-line argument with a
-dash.
-
- The P keyletter specifies what operation to execute; it may be any
-of the following, but you must specify only one of them:
-
-`d'
- _Delete_ modules from the archive. Specify the names of modules to
- be deleted as MEMBER...; the archive is untouched if you specify
- no files to delete.
-
- If you specify the `v' modifier, `ar' lists each module as it is
- deleted.
-
-`m'
- Use this operation to _move_ members in an archive.
-
- 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.
-
- If no modifiers are used with `m', any members you name in the
- MEMBER arguments are moved to the _end_ of the archive; you can
- use the `a', `b', or `i' modifiers to move them to a specified
- place instead.
-
-`p'
- _Print_ the specified members of the archive, to the standard
- output file. If the `v' modifier is specified, show the member
- name before copying its contents to standard output.
-
- If you specify no MEMBER arguments, all the files in the archive
- are printed.
-
-`q'
- _Quick append_; Historically, add the files MEMBER... to the end of
- ARCHIVE, without checking for replacement.
-
- The modifiers `a', `b', and `i' do _not_ affect this operation;
- new members are always placed at the end of the archive.
-
- The modifier `v' makes `ar' list each file as it is appended.
-
- 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 `ar s' or `ranlib' explicitly to update the symbol table index.
-
- However, too many different systems assume quick append rebuilds
- the index, so GNU `ar' implements `q' as a synonym for `r'.
-
-`r'
- Insert the files MEMBER... into ARCHIVE (with _replacement_). This
- operation differs from `q' in that any previously existing members
- are deleted if their names match those being added.
-
- If one of the files named in MEMBER... does not exist, `ar'
- displays an error message, and leaves undisturbed any existing
- members of the archive matching that name.
-
- By default, new members are added at the end of the file; but you
- may use one of the modifiers `a', `b', or `i' to request placement
- relative to some existing member.
-
- The modifier `v' used with this operation elicits a line of output
- for each file inserted, along with one of the letters `a' or `r'
- to indicate whether the file was appended (no old member deleted)
- or replaced.
-
-`t'
- Display a _table_ listing the contents of ARCHIVE, or those of the
- files listed in 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 `v' modifier.
-
- If you do not specify a MEMBER, all files in the archive are
- listed.
-
- If there is more than one file with the same name (say, `fie') in
- an archive (say `b.a'), `ar t b.a fie' lists only the first
- instance; to see them all, you must ask for a complete listing--in
- our example, `ar t b.a'.
-
-`x'
- _Extract_ members (named MEMBER) from the archive. You can use
- the `v' modifier with this operation, to request that `ar' list
- each name as it extracts it.
-
- If you do not specify a MEMBER, all files in the archive are
- extracted.
-
-
- A number of modifiers (MOD) may immediately follow the P keyletter,
-to specify variations on an operation's behavior:
-
-`a'
- Add new files _after_ an existing member of the archive. If you
- use the modifier `a', the name of an existing archive member must
- be present as the RELPOS argument, before the ARCHIVE
- specification.
-
-`b'
- Add new files _before_ an existing member of the archive. If you
- use the modifier `b', the name of an existing archive member must
- be present as the RELPOS argument, before the ARCHIVE
- specification. (same as `i').
-
-`c'
- _Create_ the archive. The specified 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.
-
-`f'
- Truncate names in the archive. GNU `ar' will normally permit file
- names of any length. This will cause it to create archives which
- are not compatible with the native `ar' program on some systems.
- If this is a concern, the `f' modifier may be used to truncate file
- names when putting them in the archive.
-
-`i'
- Insert new files _before_ an existing member of the archive. If
- you use the modifier `i', the name of an existing archive member
- must be present as the RELPOS argument, before the ARCHIVE
- specification. (same as `b').
-
-`l'
- This modifier is accepted but not used.
-
-`N'
- Uses the COUNT parameter. This is used if there are multiple
- entries in the archive with the same name. Extract or delete
- instance COUNT of the given name from the archive.
-
-`o'
- Preserve the _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.
-
-`P'
- Use the full path name when matching names in the archive. GNU
- `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 `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.
-
-`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
- `ar s' on an archive is equivalent to running `ranlib' on 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 `S' modifier on the last execution of
- `ar', or you must run `ranlib' on the archive.
-
-`u'
- Normally, `ar r'... inserts all files listed into the archive. If
- you would like to insert _only_ those of the files you list that
- are newer than existing members of the same names, use this
- modifier. The `u' modifier is allowed only for the operation `r'
- (replace). In particular, the combination `qu' is not allowed,
- since checking the timestamps would lose any speed advantage from
- the operation `q'.
-
-`v'
- This modifier requests the _verbose_ version of an operation. Many
- operations display additional information, such as filenames
- processed, when the modifier `v' is appended.
-
-`V'
- This modifier shows the version number of `ar'.
-
- `ar' ignores an initial option spelt `-X32_64', for compatibility
-with AIX. The behaviour produced by this option is the default for GNU
-`ar'. `ar' does not support any of the other `-X' options; in
-particular, it does not support `-X32' which is the default for AIX
-`ar'.
-
-\1f
-File: binutils.info, Node: ar scripts, Prev: ar cmdline, Up: ar
-
-1.2 Controlling `ar' with a Script
-==================================
-
- ar -M [ <SCRIPT ]
-
- If you use the single command-line option `-M' with `ar', you can
-control its operation with a rudimentary command language. This form
-of `ar' operates interactively if standard input is coming directly
-from a terminal. During interactive use, `ar' prompts for input (the
-prompt is `AR >'), and continues executing even after errors. If you
-redirect standard input to a script file, no prompts are issued, and
-`ar' abandons execution (with a nonzero exit code) on any error.
-
- The `ar' command language is _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 `ar' for developers who already have scripts written
-for the MRI "librarian" program.
-
- The syntax for the `ar' command language is straightforward:
- * commands are recognized in upper or lower case; for example, `LIST'
- is the same as `list'. In the following descriptions, commands are
- shown in upper case for clarity.
-
- * a single command may appear on each line; it is the first word on
- the line.
-
- * empty lines are allowed, and have no effect.
-
- * comments are allowed; text after either of the characters `*' or
- `;' is ignored.
-
- * Whenever you use a list of names as part of the argument to an `ar'
- command, you can separate the individual names with either commas
- or blanks. Commas are shown in the explanations below, for
- clarity.
-
- * `+' is used as a line continuation character; if `+' appears at
- the end of a line, the text on the following line is considered
- part of the current command.
-
- Here are the commands you can use in `ar' scripts, or when using
-`ar' interactively. Three of them have special significance:
-
- `OPEN' or `CREATE' specify a "current archive", which is a temporary
-file required for most of the other commands.
-
- `SAVE' commits the changes so far specified by the script. Prior to
-`SAVE', commands affect only the temporary copy of the current archive.
-
-`ADDLIB ARCHIVE'
-`ADDLIB ARCHIVE (MODULE, MODULE, ... MODULE)'
- Add all the contents of ARCHIVE (or, if specified, each named
- MODULE from ARCHIVE) to the current archive.
-
- Requires prior use of `OPEN' or `CREATE'.
-
-`ADDMOD MEMBER, MEMBER, ... MEMBER'
- Add each named MEMBER as a module in the current archive.
-
- Requires prior use of `OPEN' or `CREATE'.
-
-`CLEAR'
- Discard the contents of the current archive, canceling the effect
- of any operations since the last `SAVE'. May be executed (with no
- effect) even if no current archive is specified.
-
-`CREATE 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 ARCHIVE until you use `SAVE'.
- You can overwrite existing archives; similarly, the contents of any
- existing file named ARCHIVE will not be destroyed until `SAVE'.
-
-`DELETE MODULE, MODULE, ... MODULE'
- Delete each listed MODULE from the current archive; equivalent to
- `ar -d ARCHIVE MODULE ... MODULE'.
-
- Requires prior use of `OPEN' or `CREATE'.
-
-`DIRECTORY ARCHIVE (MODULE, ... MODULE)'
-`DIRECTORY ARCHIVE (MODULE, ... MODULE) OUTPUTFILE'
- List each named MODULE present in ARCHIVE. The separate command
- `VERBOSE' specifies the form of the output: when verbose output is
- off, output is like that of `ar -t ARCHIVE MODULE...'. When
- verbose output is on, the listing is like `ar -tv ARCHIVE
- MODULE...'.
-
- Output normally goes to the standard output stream; however, if you
- specify OUTPUTFILE as a final argument, `ar' directs the output to
- that file.
-
-`END'
- Exit from `ar', with a `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 `SAVE' command,
- those changes are lost.
-
-`EXTRACT MODULE, MODULE, ... MODULE'
- Extract each named MODULE from the current archive, writing them
- into the current directory as separate files. Equivalent to `ar -x
- ARCHIVE MODULE...'.
-
- Requires prior use of `OPEN' or `CREATE'.
-
-`LIST'
- Display full contents of the current archive, in "verbose" style
- regardless of the state of `VERBOSE'. The effect is like `ar tv
- ARCHIVE'. (This single command is a GNU `ar' enhancement, rather
- than present for MRI compatibility.)
-
- Requires prior use of `OPEN' or `CREATE'.
-
-`OPEN 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 ARCHIVE until you next use
- `SAVE'.
-
-`REPLACE MODULE, MODULE, ... MODULE'
- In the current archive, replace each existing MODULE (named in the
- `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.
-
- Requires prior use of `OPEN' or `CREATE'.
-
-`VERBOSE'
- Toggle an internal flag governing the output from `DIRECTORY'.
- When the flag is on, `DIRECTORY' output matches output from `ar
- -tv '....
-
-`SAVE'
- Commit your changes to the current archive, and actually save it
- as a file with the name specified in the last `CREATE' or `OPEN'
- command.
-
- Requires prior use of `OPEN' or `CREATE'.
-
-
-\1f
-File: binutils.info, Node: nm, Next: objcopy, Prev: ar, Up: Top
-
-2 nm
-****
-
- 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] [`-f'FORMAT|`--format='FORMAT]
- [`--defined-only'] [`-l'|`--line-numbers'] [`--no-demangle']
- [`-V'|`--version'] [`-X 32_64'] [`--help'] [OBJFILE...]
-
- GNU `nm' lists the symbols from object files OBJFILE.... If no
-object files are listed as arguments, `nm' assumes the file `a.out'.
-
- For each symbol, `nm' shows:
-
- * The symbol value, in the radix selected by options (see below), or
- hexadecimal by default.
-
- * 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).
-
- `A'
- The symbol's value is absolute, and will not be changed by
- further linking.
-
- `B'
- The symbol is in the uninitialized data section (known as
- BSS).
-
- `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 *Note Linker options: (ld.info)Options.
-
- `D'
- The symbol is in the initialized data section.
-
- `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.
-
- `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.
-
- `N'
- The symbol is a debugging symbol.
-
- `R'
- The symbol is in a read only data section.
-
- `S'
- The symbol is in an uninitialized data section for small
- objects.
-
- `T'
- The symbol is in the text (code) section.
-
- `U'
- The symbol is undefined.
-
- `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.
-
- `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.
-
- `-'
- 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 *Note Stabs: (stabs.info)Top.
-
- `?'
- The symbol type is unknown, or object file format specific.
-
- * The symbol name.
-
- The long and short forms of options, shown here as alternatives, are
-equivalent.
-
-`-A'
-`-o'
-`--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.
-
-`-a'
-`--debug-syms'
- Display all symbols, even debugger-only symbols; normally these
- are not listed.
-
-`-B'
- The same as `--format=bsd' (for compatibility with the MIPS `nm').
-
-`-C'
-`--demangle[=STYLE]'
- Decode ("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. *Note c++filt::, for more information on demangling.
-
-`--no-demangle'
- Do not demangle low-level symbol names. This is the default.
-
-`-D'
-`--dynamic'
- Display the dynamic symbols rather than the normal symbols. This
- is only meaningful for dynamic objects, such as certain types of
- shared libraries.
-
-`-f FORMAT'
-`--format=FORMAT'
- Use the output format FORMAT, which can be `bsd', `sysv', or
- `posix'. The default is `bsd'. Only the first character of
- FORMAT is significant; it can be either upper or lower case.
-
-`-g'
-`--extern-only'
- Display only external symbols.
-
-`-l'
-`--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.
-
-`-n'
-`-v'
-`--numeric-sort'
- Sort symbols numerically by their addresses, rather than
- alphabetically by their names.
-
-`-p'
-`--no-sort'
- Do not bother to sort the symbols in any order; print them in the
- order encountered.
-
-`-P'
-`--portability'
- Use the POSIX.2 standard output format instead of the default
- format. Equivalent to `-f posix'.
-
-`-S'
-`--print-size'
- Print size, not the value, of defined symbols for the `bsd' output
- format.
-
-`-s'
-`--print-armap'
- When listing symbols from archive members, include the index: a
- mapping (stored in the archive by `ar' or `ranlib') of which
- modules contain definitions for which names.
-
-`-r'
-`--reverse-sort'
- Reverse the order of the sort (whether numeric or alphabetic); let
- the last come first.
-
-`--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 `bsd' output format is used the
- size of the symbol is printed, rather than the value, and `-S'
- must be used in order both size and value to be printed.
-
-`--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.
-
-`-t RADIX'
-`--radix=RADIX'
- Use RADIX as the radix for printing the symbol values. It must be
- `d' for decimal, `o' for octal, or `x' for hexadecimal.
-
-`--target=BFDNAME'
- Specify an object code format other than your system's default
- format. *Note Target Selection::, for more information.
-
-`-u'
-`--undefined-only'
- Display only undefined symbols (those external to each object
- file).
-
-`--defined-only'
- Display only defined symbols for each object file.
-
-`-V'
-`--version'
- Show the version number of `nm' and exit.
-
-`-X'
- This option is ignored for compatibility with the AIX version of
- `nm'. It takes one parameter which must be the string `32_64'.
- The default mode of AIX `nm' corresponds to `-X 32', which is not
- supported by GNU `nm'.
-
-`--help'
- Show a summary of the options to `nm' and exit.
-
-\1f
-File: binutils.info, Node: objcopy, Next: objdump, Prev: nm, Up: Top
-
-3 objcopy
-*********
-
- 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]
-
- The GNU `objcopy' utility copies the contents of an object file to
-another. `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
-`objcopy' is controlled by command-line options. Note that `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.
-
- `objcopy' creates temporary files to do its translations and deletes
-them afterward. `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. *Note BFD:
-(ld.info)BFD.
-
- `objcopy' can be used to generate S-records by using an output
-target of `srec' (e.g., use `-O srec').
-
- `objcopy' can be used to generate a raw binary file by using an
-output target of `binary' (e.g., use `-O binary'). When `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.
-
- When generating an S-record or a raw binary file, it may be helpful
-to use `-S' to remove sections containing debugging information. In
-some cases `-R' will be useful to remove sections which contain
-information that is not needed by the binary file.
-
- Note--`objcopy' is not able to change the endianness of its input
-files. If the input format has an endianness (some formats do not),
-`objcopy' can only copy the inputs into file formats that have the same
-endianness or which have no endianness (e.g., `srec'). (However, see
-the `--reverse-bytes' option.)
-
-`INFILE'
-`OUTFILE'
- The input and output files, respectively. If you do not specify
- OUTFILE, `objcopy' creates a temporary file and destructively
- renames the result with the name of INFILE.
-
-`-I BFDNAME'
-`--input-target=BFDNAME'
- Consider the source file's object format to be BFDNAME, rather than
- attempting to deduce it. *Note Target Selection::, for more
- information.
-
-`-O BFDNAME'
-`--output-target=BFDNAME'
- Write the output file using the object format BFDNAME. *Note
- Target Selection::, for more information.
-
-`-F BFDNAME'
-`--target=BFDNAME'
- Use 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. *Note Target Selection::, for more information.
-
-`-B BFDARCH'
-`--binary-architecture=BFDARCH'
- Useful when transforming a raw binary input file into an object
- file. In this case the output architecture can be set to BFDARCH.
- This option will be ignored if the input file has a known 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_OBJFILE_start,
- _binary_OBJFILE_end and _binary_OBJFILE_size. e.g. you can
- transform a picture file into an object file and then access it in
- your code using these symbols.
-
-`-j SECTIONNAME'
-`--only-section=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.
-
-`-R SECTIONNAME'
-`--remove-section=SECTIONNAME'
- Remove any section named 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.
-
-`-S'
-`--strip-all'
- Do not copy relocation and symbol information from the source file.
-
-`-g'
-`--strip-debug'
- Do not copy debugging symbols or sections from the source file.
-
-`--strip-unneeded'
- Strip all symbols that are not needed for relocation processing.
-
-`-K SYMBOLNAME'
-`--keep-symbol=SYMBOLNAME'
- When stripping symbols, keep symbol SYMBOLNAME even if it would
- normally be stripped. This option may be given more than once.
-
-`-N SYMBOLNAME'
-`--strip-symbol=SYMBOLNAME'
- Do not copy symbol SYMBOLNAME from the source file. This option
- may be given more than once.
-
-`--strip-unneeded-symbol=SYMBOLNAME'
- Do not copy symbol SYMBOLNAME from the source file unless it is
- needed by a relocation. This option may be given more than once.
-
-`-G SYMBOLNAME'
-`--keep-global-symbol=SYMBOLNAME'
- Keep only symbol 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.
-
-`--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 `-L'.
-
-`-L SYMBOLNAME'
-`--localize-symbol=SYMBOLNAME'
- Make symbol SYMBOLNAME local to the file, so that it is not
- visible externally. This option may be given more than once.
-
-`-W SYMBOLNAME'
-`--weaken-symbol=SYMBOLNAME'
- Make symbol SYMBOLNAME weak. This option may be given more than
- once.
-
-`--globalize-symbol=SYMBOLNAME'
- Give symbol 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.
-
-`-w'
-`--wildcard'
- Permit regular expressions in SYMBOLNAMEs used in other command
- line options. The question mark (?), asterisk (*), backslash (\)
- 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:
-
- -w -W !foo -W fo*
-
- would cause objcopy to weaken all symbols that start with "fo"
- except for the symbol "foo".
-
-`-x'
-`--discard-all'
- Do not copy non-global symbols from the source file.
-
-`-X'
-`--discard-locals'
- Do not copy compiler-generated local symbols. (These usually
- start with `L' or `.'.)
-
-`-b BYTE'
-`--byte=BYTE'
- Keep only every BYTEth byte of the input file (header data is not
- affected). BYTE can be in the range from 0 to INTERLEAVE-1, where
- INTERLEAVE is given by the `-i' or `--interleave' option, or the
- default of 4. This option is useful for creating files to program
- ROM. It is typically used with an `srec' output target.
-
-`-i INTERLEAVE'
-`--interleave=INTERLEAVE'
- Only copy one out of every INTERLEAVE bytes. Select which byte to
- copy with the `-b' or `--byte' option. The default is 4.
- `objcopy' ignores this option if you do not specify either `-b' or
- `--byte'.
-
-`-p'
-`--preserve-dates'
- Set the access and modification dates of the output file to be the
- same as those of the input file.
-
-`--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.
-
-`--gap-fill VAL'
- Fill gaps between sections with VAL. This operation applies to
- the _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 VAL.
-
-`--pad-to ADDRESS'
- Pad the output file up to the load address ADDRESS. This is done
- by increasing the size of the last section. The extra space is
- filled in with the value specified by `--gap-fill' (default zero).
-
-`--set-start VAL'
- Set the start address of the new file to VAL. Not all object file
- formats support setting the start address.
-
-`--change-start INCR'
-`--adjust-start INCR'
- Change the start address by adding INCR. Not all object file
- formats support setting the start address.
-
-`--change-addresses INCR'
-`--adjust-vma INCR'
- Change the VMA and LMA addresses of all sections, as well as the
- start address, by adding 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.
-
-`--change-section-address SECTION{=,+,-}VAL'
-`--adjust-section-vma SECTION{=,+,-}VAL'
- Set or change both the VMA address and the LMA address of the named
- SECTION. If `=' is used, the section address is set to VAL.
- Otherwise, VAL is added to or subtracted from the section address.
- See the comments under `--change-addresses', above. If SECTION
- does not exist in the input file, a warning will be issued, unless
- `--no-change-warnings' is used.
-
-`--change-section-lma SECTION{=,+,-}VAL'
- Set or change the LMA address of the named 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 `=' is used, the section
- address is set to VAL. Otherwise, VAL is added to or subtracted
- from the section address. See the comments under
- `--change-addresses', above. If SECTION does not exist in the
- input file, a warning will be issued, unless
- `--no-change-warnings' is used.
-
-`--change-section-vma SECTION{=,+,-}VAL'
- Set or change the VMA address of the named 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 `=' is used, the
- section address is set to VAL. Otherwise, VAL is added to or
- subtracted from the section address. See the comments under
- `--change-addresses', above. If SECTION does not exist in the
- input file, a warning will be issued, unless
- `--no-change-warnings' is used.
-
-`--change-warnings'
-`--adjust-warnings'
- If `--change-section-address' or `--change-section-lma' or
- `--change-section-vma' is used, and the named section does not
- exist, issue a warning. This is the default.
-
-`--no-change-warnings'
-`--no-adjust-warnings'
- Do not issue a warning if `--change-section-address' or
- `--adjust-section-lma' or `--adjust-section-vma' is used, even if
- the named section does not exist.
-
-`--set-section-flags SECTION=FLAGS'
- Set the flags for the named section. The FLAGS argument is a
- comma separated string of flag names. The recognized names are
- `alloc', `contents', `load', `noload', `readonly', `code', `data',
- `rom', `share', and `debug'. You can set the `contents' flag for
- a section which does not have contents, but it is not meaningful
- to clear the `contents' flag of a section which does have
- contents-just remove the section instead. Not all flags are
- meaningful for all object file formats.
-
-`--add-section SECTIONNAME=FILENAME'
- Add a new section named SECTIONNAME while copying the file. The
- contents of the new section are taken from the file 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.
-
-`--rename-section OLDNAME=NEWNAME[,FLAGS]'
- Rename a section from OLDNAME to NEWNAME, optionally changing the
- section's flags to 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.
-
- 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:
-
- objcopy -I binary -O <output_format> -B <architecture> \
- --rename-section .data=.rodata,alloc,load,readonly,data,contents \
- <input_binary_file> <output_object_file>
-
-`--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
- `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.
-
-`--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 `--change-leading-char'
- because it always changes the symbol name when appropriate,
- regardless of the object file format of the output file.
-
-`--reverse-bytes=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.
-
- 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.
-
- Consider a simple file with a section containing the following
- eight bytes: `12345678'.
-
- Using `--reverse-bytes=2' for the above example, the bytes in the
- output file would be ordered `21436587'.
-
- Using `--reverse-bytes=4' for the above example, the bytes in the
- output file would be ordered `43218765'.
-
- By using `--reverse-bytes=2' for the above example, followed by
- `--reverse-bytes=4' on the output file, the bytes in the second
- output file would be ordered `34127856'.
-
-`--srec-len=IVAL'
- Meaningful only for srec output. Set the maximum length of the
- Srecords being produced to IVAL. This length covers both address,
- data and crc fields.
-
-`--srec-forceS3'
- Meaningful only for srec output. Avoid generation of S1/S2
- records, creating S3-only record format.
-
-`--redefine-sym OLD=NEW'
- Change the name of a symbol OLD, to NEW. This can be useful when
- one is trying link two things together for which you have no
- source, and there are name collisions.
-
-`--redefine-syms=FILENAME'
- Apply `--redefine-sym' to each symbol pair "OLD NEW" listed in the
- file FILENAME. 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.
-
-`--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 `-R' option to the linker. This option is only
- effective when using an object file format which supports weak
- symbols.
-
-`--keep-symbols=FILENAME'
- Apply `--keep-symbol' option to each symbol listed in the file
- FILENAME. 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.
-
-`--strip-symbols=FILENAME'
- Apply `--strip-symbol' option to each symbol listed in the file
- FILENAME. 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.
-
-`--strip-unneeded-symbols=FILENAME'
- Apply `--strip-unneeded-symbol' option to each symbol listed in
- the file FILENAME. 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.
-
-`--keep-global-symbols=FILENAME'
- Apply `--keep-global-symbol' option to each symbol listed in the
- file FILENAME. 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.
-
-`--localize-symbols=FILENAME'
- Apply `--localize-symbol' option to each symbol listed in the file
- FILENAME. 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.
-
-`--globalize-symbols=FILENAME'
- Apply `--globalize-symbol' option to each symbol listed in the file
- FILENAME. 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.
-
-`--weaken-symbols=FILENAME'
- Apply `--weaken-symbol' option to each symbol listed in the file
- FILENAME. 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.
-
-`--alt-machine-code=INDEX'
- If the output architecture has alternate machine codes, use the
- INDEXth 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 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.
-
-`--writable-text'
- Mark the output text as writable. This option isn't meaningful
- for all object file formats.
-
-`--readonly-text'
- Make the output text write protected. This option isn't
- meaningful for all object file formats.
-
-`--pure'
- Mark the output file as demand paged. This option isn't
- meaningful for all object file formats.
-
-`--impure'
- Mark the output file as impure. This option isn't meaningful for
- all object file formats.
-
-`--prefix-symbols=STRING'
- Prefix all symbols in the output file with STRING.
-
-`--prefix-sections=STRING'
- Prefix all section names in the output file with STRING.
-
-`--prefix-alloc-sections=STRING'
- Prefix all the names of all allocated sections in the output file
- with STRING.
-
-`--add-gnu-debuglink=PATH-TO-FILE'
- Creates a .gnu_debuglink section which contains a reference to
- PATH-TO-FILE and adds it to the output file.
-
-`--keep-file-symbols'
- When stripping a file, perhaps with `--strip-debug' or
- `--strip-unneeded', retain any symbols specifying source file
- names, which would otherwise get stripped.
-
-`--only-keep-debug'
- Strip a file, removing contents of any sections that would not be
- stripped by `--strip-debug' and leaving the debugging sections
- intact. In ELF files, this preserves all note sections in the
- output.
-
- The intention is that this option will be used in conjunction with
- `--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:
-
- 1. Link the executable as normal. Assuming that is is called
- `foo' then...
-
- 2. Run `objcopy --only-keep-debug foo foo.dbg' to create a file
- containing the debugging info.
-
- 3. Run `objcopy --strip-debug foo' to create a stripped
- executable.
-
- 4. Run `objcopy --add-gnu-debuglink=foo.dbg foo' to add a link
- to the debugging info into the stripped executable.
-
- Note - the choice of `.dbg' as an extension for the debug info
- file is arbitrary. Also the `--only-keep-debug' step is optional.
- You could instead do this:
-
- 1. Link the executable as normal.
-
- 2. Copy `foo' to `foo.full'
-
- 3. Run `objcopy --strip-debug foo'
-
- 4. Run `objcopy --add-gnu-debuglink=foo.full foo'
-
- i.e., the file pointed to by the `--add-gnu-debuglink' can be the
- full executable. It does not have to be a file created by the
- `--only-keep-debug' switch.
-
- 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.
-
-`--extract-symbol'
- Keep the file's section flags and symbols but remove all section
- data. Specifically, the option:
-
- * sets the virtual and load addresses of every section to zero;
-
- * removes the contents of all sections;
-
- * sets the size of every section to zero; and
-
- * sets the file's start address to zero.
-
- This option is used to build a `.sym' file for a VxWorks kernel.
- It can also be a useful way of reducing the size of a
- `--just-symbols' linker input file.
-
-`-V'
-`--version'
- Show the version number of `objcopy'.
-
-`-v'
-`--verbose'
- Verbose output: list all object files modified. In the case of
- archives, `objcopy -V' lists all members of the archive.
-
-`--help'
- Show a summary of the options to `objcopy'.
-
-`--info'
- Display a list showing all architectures and object formats
- available.
-
-\1f
-File: binutils.info, Node: objdump, Next: ranlib, Prev: objcopy, Up: Top
-
-4 objdump
-*********
-
- 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...
-
- `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.
-
- OBJFILE... are the object files to be examined. When you specify
-archives, `objdump' shows information on each of the member object
-files.
-
- The long and short forms of options, shown here as alternatives, are
-equivalent. At least one option from the list
-`-a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x' must be given.
-
-`-a'
-`--archive-header'
- If any of the OBJFILE files are archives, display the archive
- header information (in a format similar to `ls -l'). Besides the
- information you could list with `ar tv', `objdump -a' shows the
- object file format of each archive member.
-
-`--adjust-vma=OFFSET'
- When dumping information, first add 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.
-
-`-b BFDNAME'
-`--target=BFDNAME'
- Specify that the object-code format for the object files is
- BFDNAME. This option may not be necessary; OBJDUMP can
- automatically recognize many formats.
-
- For example,
- objdump -b oasys -m vax -h fu.o
- displays summary information from the section headers (`-h') of
- `fu.o', which is explicitly identified (`-m') as a VAX object file
- in the format produced by Oasys compilers. You can list the
- formats available with the `-i' option. *Note Target Selection::,
- for more information.
-
-`-C'
-`--demangle[=STYLE]'
- Decode ("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. *Note c++filt::, for more information on demangling.
-
-`-g'
-`--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 `readelf -w'.
- *Note readelf::.
-
-`-e'
-`--debugging-tags'
- Like `-g', but the information is generated in a format compatible
- with ctags tool.
-
-`-d'
-`--disassemble'
- Display the assembler mnemonics for the machine instructions from
- OBJFILE. This option only disassembles those sections which are
- expected to contain instructions.
-
-`-D'
-`--disassemble-all'
- Like `-d', but disassemble the contents of all sections, not just
- those expected to contain instructions.
-
-`--prefix-addresses'
- When disassembling, print the complete address on each line. This
- is the older disassembly format.
-
-`-EB'
-`-EL'
-`--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.
-
-`-f'
-`--file-headers'
- Display summary information from the overall header of each of the
- OBJFILE files.
-
-`--file-start-context'
- Specify that when displaying interlisted source code/disassembly
- (assumes `-S') from a file that has not yet been displayed, extend
- the context to the start of the file.
-
-`-h'
-`--section-headers'
-`--headers'
- Display summary information from the section headers of the object
- file.
-
- File segments may be relocated to nonstandard addresses, for
- example by using the `-Ttext', `-Tdata', or `-Tbss' options to
- `ld'. However, some object file formats, such as a.out, do not
- store the starting address of the file segments. In those
- situations, although `ld' relocates the sections correctly, using
- `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.
-
-`-H'
-`--help'
- Print a summary of the options to `objdump' and exit.
-
-`-i'
-`--info'
- Display a list showing all architectures and object formats
- available for specification with `-b' or `-m'.
-
-`-j NAME'
-`--section=NAME'
- Display information only for section NAME.
-
-`-l'
-`--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 `-d', `-D', or `-r'.
-
-`-m MACHINE'
-`--architecture=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 `-i' option.
-
-`-M OPTIONS'
-`--disassembler-options=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 `-M' options can be
- used or can be placed together into a comma separated list.
-
- If the target is an ARM architecture then this switch can be used
- to select which register name set is used during disassembler.
- Specifying `-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 `-M reg-names-apcs' will select the
- name set used by the ARM Procedure Call Standard, whilst
- specifying `-M reg-names-raw' will just use `r' followed by the
- register number.
-
- There are also two variants on the APCS register naming scheme
- enabled by `-M reg-names-atpcs' and `-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).
-
- This option can also be used for ARM architectures to force the
- disassembler to interpret all instructions as Thumb instructions by
- using the switch `--disassembler-options=force-thumb'. This can be
- useful when attempting to disassemble thumb code produced by other
- compilers.
-
- For the x86, some of the options duplicate functions of the `-m'
- switch, but allow finer grained control. Multiple selections from
- the following may be specified as a comma separated string.
- `x86-64', `i386' and `i8086' select disassembly for the given
- architecture. `intel' and `att' select between intel syntax mode
- and AT&T syntax mode. `addr64', `addr32', `addr16', `data32' and
- `data16' specify the default address size and operand size. These
- four options will be overridden if `x86-64', `i386' or `i8086'
- appear later in the option string. Lastly, `suffix', when in AT&T
- mode, instructs the disassembler to print a mnemonic suffix even
- when the suffix could be inferred by the operands.
-
- For PPC, `booke', `booke32' and `booke64' select disassembly of
- BookE instructions. `32' and `64' select PowerPC and PowerPC64
- disassembly, respectively. `e300' selects disassembly for the
- e300 family. `440' selects disassembly for the PowerPC 440.
-
- 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:
-
- `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.
-
- `gpr-names=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.
-
- `fpr-names=ABI'
- Print FPR (floating-point register) names as appropriate for
- the specified ABI. By default, FPR numbers are printed
- rather than names.
-
- `cp0-names=ARCH'
- Print CP0 (system control coprocessor; coprocessor 0)
- register names as appropriate for the CPU or architecture
- specified by ARCH. By default, CP0 register names are
- selected according to the architecture and CPU of the binary
- being disassembled.
-
- `hwr-names=ARCH'
- Print HWR (hardware register, used by the `rdhwr'
- instruction) names as appropriate for the CPU or architecture
- specified by ARCH. By default, HWR names are selected
- according to the architecture and CPU of the binary being
- disassembled.
-
- `reg-names=ABI'
- Print GPR and FPR names as appropriate for the selected ABI.
-
- `reg-names=ARCH'
- Print CPU-specific register names (CP0 register and HWR names)
- as appropriate for the selected CPU or architecture.
-
- For any of the options listed above, ABI or ARCH may be specified
- as `numeric' to have numbers printed rather than names, for the
- selected types of registers. You can list the available values of
- ABI and ARCH using the `--help' option.
-
- For VAX, you can specify function entry addresses with `-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.
-
-`-p'
-`--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.
-
-`-r'
-`--reloc'
- Print the relocation entries of the file. If used with `-d' or
- `-D', the relocations are printed interspersed with the
- disassembly.
-
-`-R'
-`--dynamic-reloc'
- Print the dynamic relocation entries of the file. This is only
- meaningful for dynamic objects, such as certain types of shared
- libraries.
-
-`-s'
-`--full-contents'
- Display the full contents of any sections requested. By default
- all non-empty sections are displayed.
-
-`-S'
-`--source'
- Display source code intermixed with disassembly, if possible.
- Implies `-d'.
-
-`--show-raw-insn'
- When disassembling instructions, print the instruction in hex as
- well as in symbolic form. This is the default except when
- `--prefix-addresses' is used.
-
-`--no-show-raw-insn'
- When disassembling instructions, do not print the instruction
- bytes. This is the default when `--prefix-addresses' is used.
-
-`-W'
-`--dwarf'
- Displays the contents of the DWARF debug sections in the file, if
- any are present.
-
-`-G'
-`--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 `.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 `--syms' output. For more information on stabs symbols, see
- *Note Stabs: (stabs.info)Top.
-
-`--start-address=ADDRESS'
- Start displaying data at the specified address. This affects the
- output of the `-d', `-r' and `-s' options.
-
-`--stop-address=ADDRESS'
- Stop displaying data at the specified address. This affects the
- output of the `-d', `-r' and `-s' options.
-
-`-t'
-`--syms'
- Print the symbol table entries of the file. This is similar to
- the information provided by the `nm' program.
-
-`-T'
-`--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 `nm'
- program when given the `-D' (`--dynamic') option.
-
-`--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.
-
-`-V'
-`--version'
- Print the version number of `objdump' and exit.
-
-`-x'
-`--all-headers'
- Display all available header information, including the symbol
- table and relocation entries. Using `-x' is equivalent to
- specifying all of `-a -f -h -p -r -t'.
-
-`-w'
-`--wide'
- Format some lines for output devices that have more than 80
- columns. Also do not truncate symbol names when they are
- displayed.
-
-`-z'
-`--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.
-
-\1f
-File: binutils.info, Node: ranlib, Next: readelf, Prev: objdump, Up: Top
-
-5 ranlib
-********
-
- ranlib [`-vV'] ARCHIVE
-
- `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.
-
- You may use `nm -s' or `nm --print-armap' to list this index.
-
- 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.
-
- The GNU `ranlib' program is another form of GNU `ar'; running
-`ranlib' is completely equivalent to executing `ar -s'. *Note ar::.
-
-`-v'
-`-V'
-`--version'
- Show the version number of `ranlib'.
-
-\1f
-File: binutils.info, Node: size, Next: strings, Prev: readelf, Up: Top
-
-6 size
-******
-
- size [`-A'|`-B'|`--format='COMPATIBILITY]
- [`--help']
- [`-d'|`-o'|`-x'|`--radix='NUMBER]
- [`--common']
- [`-t'|`--totals']
- [`--target='BFDNAME] [`-V'|`--version']
- [OBJFILE...]
-
- The GNU `size' utility lists the section sizes--and the total
-size--for each of the object or archive files OBJFILE in its argument
-list. By default, one line of output is generated for each object file
-or each module in an archive.
-
- OBJFILE... are the object files to be examined. If none are
-specified, the file `a.out' will be used.
-
- The command line options have the following meanings:
-
-`-A'
-`-B'
-`--format=COMPATIBILITY'
- Using one of these options, you can choose whether the output from
- GNU `size' resembles output from System V `size' (using `-A', or
- `--format=sysv'), or Berkeley `size' (using `-B', or
- `--format=berkeley'). The default is the one-line format similar
- to Berkeley's.
-
- Here is an example of the Berkeley (default) format of output from
- `size':
- $ size --format=Berkeley ranlib size
- text data bss dec hex filename
- 294880 81920 11592 388392 5ed28 ranlib
- 294880 81920 11888 388688 5ee50 size
-
- This is the same data, but displayed closer to System V
- conventions:
-
- $ 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
-
-`--help'
- Show a summary of acceptable arguments and options.
-
-`-d'
-`-o'
-`-x'
-`--radix=NUMBER'
- Using one of these options, you can control whether the size of
- each section is given in decimal (`-d', or `--radix=10'); octal
- (`-o', or `--radix=8'); or hexadecimal (`-x', or `--radix=16').
- In `--radix=NUMBER', only the three values (8, 10, 16) are
- supported. The total size is always given in two radices; decimal
- and hexadecimal for `-d' or `-x' output, or octal and hexadecimal
- if you're using `-o'.
-
-`--common'
- Print total size of common symbols in each file. When using
- Berkeley format these are included in the bss size.
-
-`-t'
-`--totals'
- Show totals of all objects listed (Berkeley format listing mode
- only).
-
-`--target=BFDNAME'
- Specify that the object-code format for OBJFILE is BFDNAME. This
- option may not be necessary; `size' can automatically recognize
- many formats. *Note Target Selection::, for more information.
-
-`-V'
-`--version'
- Display the version number of `size'.
-
-\1f
-File: binutils.info, Node: strings, Next: strip, Prev: size, Up: Top
-
-7 strings
-*********
-
- 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...
-
- For each FILE given, GNU `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.
-
- `strings' is mainly useful for determining the contents of non-text
-files.
-
-`-a'
-`--all'
-`-'
- Do not scan only the initialized and loaded sections of object
- files; scan the whole files.
-
-`-f'
-`--print-file-name'
- Print the name of the file before each string.
-
-`--help'
- Print a summary of the program usage on the standard output and
- exit.
-
-`-MIN-LEN'
-`-n MIN-LEN'
-`--bytes=MIN-LEN'
- Print sequences of characters that are at least MIN-LEN characters
- long, instead of the default 4.
-
-`-o'
- Like `-t o'. Some other versions of `strings' have `-o' act like
- `-t d' instead. Since we can not be compatible with both ways, we
- simply chose one.
-
-`-t RADIX'
-`--radix=RADIX'
- Print the offset within the file before each string. The single
- character argument specifies the radix of the offset--`o' for
- octal, `x' for hexadecimal, or `d' for decimal.
-
-`-e ENCODING'
-`--encoding=ENCODING'
- Select the character encoding of the strings that are to be found.
- Possible values for ENCODING are: `s' = single-7-bit-byte
- characters (ASCII, ISO 8859, etc., default), `S' =
- single-8-bit-byte characters, `b' = 16-bit bigendian, `l' = 16-bit
- littleendian, `B' = 32-bit bigendian, `L' = 32-bit littleendian.
- Useful for finding wide character strings.
-
-`-T BFDNAME'
-`--target=BFDNAME'
- Specify an object code format other than your system's default
- format. *Note Target Selection::, for more information.
-
-`-v'
-`--version'
- Print the program version number on the standard output and exit.
-
-\1f
-File: binutils.info, Node: strip, Next: c++filt, Prev: strings, Up: Top
-
-8 strip
-*******
-
- 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...
-
- GNU `strip' discards all symbols from object files OBJFILE. The
-list of object files may include archives. At least one object file
-must be given.
-
- `strip' modifies the files named in its argument, rather than
-writing modified copies under different names.
-
-`-F BFDNAME'
-`--target=BFDNAME'
- Treat the original OBJFILE as a file with the object code format
- BFDNAME, and rewrite it in the same format. *Note Target
- Selection::, for more information.
-
-`--help'
- Show a summary of the options to `strip' and exit.
-
-`--info'
- Display a list showing all architectures and object formats
- available.
-
-`-I BFDNAME'
-`--input-target=BFDNAME'
- Treat the original OBJFILE as a file with the object code format
- BFDNAME. *Note Target Selection::, for more information.
-
-`-O BFDNAME'
-`--output-target=BFDNAME'
- Replace OBJFILE with a file in the output format BFDNAME. *Note
- Target Selection::, for more information.
-
-`-R SECTIONNAME'
-`--remove-section=SECTIONNAME'
- Remove any section named 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.
-
-`-s'
-`--strip-all'
- Remove all symbols.
-
-`-g'
-`-S'
-`-d'
-`--strip-debug'
- Remove debugging symbols only.
-
-`--strip-unneeded'
- Remove all symbols that are not needed for relocation processing.
-
-`-K SYMBOLNAME'
-`--keep-symbol=SYMBOLNAME'
- When stripping symbols, keep symbol SYMBOLNAME even if it would
- normally be stripped. This option may be given more than once.
-
-`-N SYMBOLNAME'
-`--strip-symbol=SYMBOLNAME'
- Remove symbol SYMBOLNAME from the source file. This option may be
- given more than once, and may be combined with strip options other
- than `-K'.
-
-`-o FILE'
- Put the stripped output in FILE, rather than replacing the
- existing file. When this argument is used, only one OBJFILE
- argument may be specified.
-
-`-p'
-`--preserve-dates'
- Preserve the access and modification dates of the file.
-
-`-w'
-`--wildcard'
- Permit regular expressions in SYMBOLNAMEs used in other command
- line options. The question mark (?), asterisk (*), backslash (\)
- 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:
-
- -w -K !foo -K fo*
-
- would cause strip to only keep symbols that start with the letters
- "fo", but to discard the symbol "foo".
-
-`-x'
-`--discard-all'
- Remove non-global symbols.
-
-`-X'
-`--discard-locals'
- Remove compiler-generated local symbols. (These usually start
- with `L' or `.'.)
-
-`--keep-file-symbols'
- When stripping a file, perhaps with `--strip-debug' or
- `--strip-unneeded', retain any symbols specifying source file
- names, which would otherwise get stripped.
-
-`--only-keep-debug'
- Strip a file, removing contents of any sections that would not be
- stripped by `--strip-debug' and leaving the debugging sections
- intact. In ELF files, this preserves all note sections in the
- output.
-
- The intention is that this option will be used in conjunction with
- `--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:
-
- 1. Link the executable as normal. Assuming that is is called
- `foo' then...
-
- 2. Run `objcopy --only-keep-debug foo foo.dbg' to create a file
- containing the debugging info.
-
- 3. Run `objcopy --strip-debug foo' to create a stripped
- executable.
-
- 4. Run `objcopy --add-gnu-debuglink=foo.dbg foo' to add a link
- to the debugging info into the stripped executable.
-
- Note - the choice of `.dbg' as an extension for the debug info
- file is arbitrary. Also the `--only-keep-debug' step is optional.
- You could instead do this:
-
- 1. Link the executable as normal.
-
- 2. Copy `foo' to `foo.full'
-
- 3. Run `strip --strip-debug foo'
-
- 4. Run `objcopy --add-gnu-debuglink=foo.full foo'
-
- ie the file pointed to by the `--add-gnu-debuglink' can be the
- full executable. It does not have to be a file created by the
- `--only-keep-debug' switch.
-
- 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.
-
-`-V'
-`--version'
- Show the version number for `strip'.
-
-`-v'
-`--verbose'
- Verbose output: list all object files modified. In the case of
- archives, `strip -v' lists all members of the archive.
-
-\1f
-File: binutils.info, Node: c++filt, Next: addr2line, Prev: strip, Up: Top
-
-9 c++filt
-*********
-
- c++filt [`-_'|`--strip-underscores']
- [`-n'|`--no-strip-underscores']
- [`-p'|`--no-params']
- [`-t'|`--types']
- [`-i'|`--no-verbose']
- [`-s' FORMAT|`--format='FORMAT]
- [`--help'] [`--version'] [SYMBOL...]
-
- 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 "mangling". The `c++filt'
-(1) program does the inverse mapping: it decodes ("demangles") low-level
-names into user-level names so that they can be read.
-
- 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 `c++filt' and see the same source file containing demangled
-names.
-
- You can also use `c++filt' to decipher individual symbols by passing
-them on the command line:
-
- c++filt SYMBOL
-
- If no SYMBOL arguments are given, `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:
-
- c++filt -n _Z1fv
-
- will work and demangle the name to "f()" whereas:
-
- c++filt -n _Z1fv,
-
- will not work. (Note the extra comma at the end of the mangled name
-which makes it invalid). This command however will work:
-
- echo _Z1fv, | c++filt -n
-
- and will display "f()," 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:
-
- .type _Z1fv, @function
-
-`-_'
-`--strip-underscores'
- On some systems, both the C and C++ compilers put an underscore in
- front of every name. For example, the C name `foo' gets the
- low-level name `_foo'. This option removes the initial
- underscore. Whether `c++filt' removes the underscore by default
- is target dependent.
-
-`-j'
-`--java'
- Prints demangled names using Java syntax. The default is to use
- C++ syntax.
-
-`-n'
-`--no-strip-underscores'
- Do not remove the initial underscore.
-
-`-p'
-`--no-params'
- When demangling the name of a function, do not display the types of
- the function's parameters.
-
-`-t'
-`--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 "a" treated as a mangled
- type name would be demangled to "signed char".
-
-`-i'
-`--no-verbose'
- Do not include implementation details (if any) in the demangled
- output.
-
-`-s FORMAT'
-`--format=FORMAT'
- `c++filt' can decode various methods of mangling, used by
- different compilers. The argument to this option selects which
- method it uses:
-
- `auto'
- Automatic selection based on executable (the default method)
-
- `gnu'
- the one used by the GNU C++ compiler (g++)
-
- `lucid'
- the one used by the Lucid compiler (lcc)
-
- `arm'
- the one specified by the C++ Annotated Reference Manual
-
- `hp'
- the one used by the HP compiler (aCC)
-
- `edg'
- the one used by the EDG compiler
-
- `gnu-v3'
- the one used by the GNU C++ compiler (g++) with the V3 ABI.
-
- `java'
- the one used by the GNU Java compiler (gcj)
-
- `gnat'
- the one used by the GNU Ada compiler (GNAT).
-
-`--help'
- Print a summary of the options to `c++filt' and exit.
-
-`--version'
- Print the version number of `c++filt' and exit.
-
- _Warning:_ `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,
-
- c++filt SYMBOL
-
- may in a future release become
-
- c++filt OPTION SYMBOL
-
- ---------- Footnotes ----------
-
- (1) MS-DOS does not allow `+' characters in file names, so on MS-DOS
-this program is named `CXXFILT'.
-
-\1f
-File: binutils.info, Node: addr2line, Next: nlmconv, Prev: c++filt, Up: Top
-
-10 addr2line
-************
-
- 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 ...]
-
- `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.
-
- The executable or relocatable object to use is specified with the
-`-e' option. The default is the file `a.out'. The section in the
-relocatable object to use is specified with the `-j' option.
-
- `addr2line' has two modes of operation.
-
- In the first, hexadecimal addresses are specified on the command
-line, and `addr2line' displays the file name and line number for each
-address.
-
- In the second, `addr2line' reads hexadecimal addresses from standard
-input, and prints the file name and line number for each address on
-standard output. In this mode, `addr2line' may be used in a pipe to
-convert dynamically chosen addresses.
-
- The format of the output is `FILENAME:LINENO'. The file name and
-line number for each address is printed on a separate line. If the
-`-f' option is used, then each `FILENAME:LINENO' line is preceded by a
-`FUNCTIONNAME' line which is the name of the function containing the
-address.
-
- If the file name or function name can not be determined, `addr2line'
-will print two question marks in their place. If the line number can
-not be determined, `addr2line' will print 0.
-
- The long and short forms of options, shown here as alternatives, are
-equivalent.
-
-`-b BFDNAME'
-`--target=BFDNAME'
- Specify that the object-code format for the object files is
- BFDNAME.
-
-`-C'
-`--demangle[=STYLE]'
- Decode ("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. *Note c++filt::, for more information on demangling.
-
-`-e FILENAME'
-`--exe=FILENAME'
- Specify the name of the executable for which addresses should be
- translated. The default file is `a.out'.
-
-`-f'
-`--functions'
- Display function names as well as file and line number information.
-
-`-s'
-`--basenames'
- Display only the base of each file name.
-
-`-i'
-`--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 `main' inlines
- `callee1' which inlines `callee2', and address is from `callee2',
- the source information for `callee1' and `main' will also be
- printed.
-
-`-j'
-`--section'
- Read offsets relative to the specified section instead of absolute
- addresses.
-
-\1f
-File: binutils.info, Node: nlmconv, Next: windres, Prev: addr2line, Up: Top
-
-11 nlmconv
-**********
-
-`nlmconv' converts a relocatable object file into a NetWare Loadable
-Module.
-
- _Warning:_ `nlmconv' is not always built as part of the binary
- utilities, since it is only useful for NLM targets.
-
- 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
-
- `nlmconv' converts the relocatable `i386' object file INFILE into
-the NetWare Loadable Module OUTFILE, optionally reading HEADERFILE for
-NLM header information. For instructions on writing the NLM command
-file language used in header files, see the `linkers' section,
-`NLMLINK' in particular, of the `NLM Development and Tools Overview',
-which is part of the NLM Software Developer's Kit ("NLM SDK"),
-available from Novell, Inc. `nlmconv' uses the GNU Binary File
-Descriptor library to read INFILE; see *Note BFD: (ld.info)BFD, for
-more information.
-
- `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, `nlmconv' calls the linker for you.
-
-`-I BFDNAME'
-`--input-target=BFDNAME'
- Object format of the input file. `nlmconv' can usually determine
- the format of a given file (so no default is necessary). *Note
- Target Selection::, for more information.
-
-`-O BFDNAME'
-`--output-target=BFDNAME'
- Object format of the output file. `nlmconv' infers the output
- format based on the input format, e.g. for a `i386' input file the
- output format is `nlm32-i386'. *Note Target Selection::, for more
- information.
-
-`-T HEADERFILE'
-`--header-file=HEADERFILE'
- Reads HEADERFILE for NLM header information. For instructions on
- writing the NLM command file language used in header files, see
- see the `linkers' section, of the `NLM Development and Tools
- Overview', which is part of the NLM Software Developer's Kit,
- available from Novell, Inc.
-
-`-d'
-`--debug'
- Displays (on standard error) the linker command line used by
- `nlmconv'.
-
-`-l LINKER'
-`--linker=LINKER'
- Use LINKER for any linking. LINKER can be an absolute or a
- relative pathname.
-
-`-h'
-`--help'
- Prints a usage summary.
-
-`-V'
-`--version'
- Prints the version number for `nlmconv'.
-
-\1f
-File: binutils.info, Node: windmc, Next: dlltool, Prev: windres, Up: Top
-
-12 windmc
-*********
-
-`windmc' may be used to generator Windows message resources.
-
- _Warning:_ `windmc' is not always built as part of the binary
- utilities, since it is only useful for Windows targets.
-
- windmc [options] input-file
-
- `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:
-
-`h'
- A C header file containing the message definitions.
-
-`rc'
- A resource file compilable by the `windres' tool.
-
-`bin'
- One or more binary files containing the resource data for a
- specific message language.
-
-`dbg'
- A C include file that maps message id's to their symbolic name.
-
- The exact description of these different formats is available in
-documentation from Microsoft.
-
- When `windmc' converts from the `mc' format to the `bin' format,
-`rc', `h', and optional `dbg' it is acting like the Windows Message
-Compiler.
-
-`-a'
-`--ascii_in'
- Specifies that the input file specified is ANSI. This is the
- default behaviour.
-
-`-A'
-`--ascii_out'
- Specifies that messages in the output `bin' files should be in ANSI
- format.
-
-`-b'
-`--binprefix'
- Specifies that `bin' filenames should have to be prefixed by the
- basename of the source file.
-
-`-c'
-`--customflag'
- Sets the customer bit in all message id's.
-
-`-C CODEPAGE'
-`--codepage_in CODEPAGE'
- Sets the default codepage to be used to convert input file to
- UTF16. The default is ocdepage 1252.
-
-`-d'
-`--decimal_values'
- Outputs the constants in the header file in decimal. Default is
- using hexadecimal output.
-
-`-e EXT'
-`--extension EXT'
- The extension for the header file. The default is .h extension.
-
-`-F TARGET'
-`--target TARGET'
- Specify the BFD format to use for a bin file as output. This is a
- BFD target name; you can use the `--help' option to see a list of
- supported targets. Normally `windmc' will use the default format,
- which is the first one listed by the `--help' option. *Note
- Target Selection::.
-
-`-h PATH'
-`--headerdir PATH'
- The target directory of the generated header file. The default is
- the current directory.
-
-`-H'
-`--help'
- Displays a list of command line options and then exits.
-
-`-m CHARACTERS'
-`--maxlength CHARACTERS'
- Instructs `windmc' to generate a warning if the length of any
- message exceeds the number specified.
-
-`-n'
-`--nullterminate'
- Terminate message text in `bin' files by zero. By default they are
- terminated by CR/LF.
-
-`-o'
-`--hresult_use'
- Not yet implemented. Instructs `windmc' to generate an OLE2 header
- file, using HRESULT definitions. Status codes are used if the flag
- is not specified.
-
-`-O CODEPAGE'
-`--codepage_out CODEPAGE'
- Sets the default codepage to be used to output text files. The
- default is ocdepage 1252.
-
-`-r PATH'
-`--rcdir PATH'
- The target directory for the generated `rc' script and the
- generated `bin' files that the resource compiler script includes.
- The default is the current directory.
-
-`-u'
-`--unicode_in'
- Specifies that the input file is UTF16.
-
-`-U'
-`--unicode_out'
- Specifies that messages in the output `bin' file should be in UTF16
- format. This is the default behaviour.
-
-`-v'
-
-`--verbose'
- Enable verbose mode. This tells you what the preprocessor is if
- you didn't specify one.
-
-`-V'
-
-`--version'
- Prints the version number for `windres'.
-
-`-x PATH'
-`--xdgb PATH'
- The path of the `dbg' C include file that maps message id's to the
- symbolic name. No such file is generated without specifying the
- switch.
-
-\1f
-File: binutils.info, Node: windres, Next: windmc, Prev: nlmconv, Up: Top
-
-13 windres
-**********
-
-`windres' may be used to manipulate Windows resources.
-
- _Warning:_ `windres' is not always built as part of the binary
- utilities, since it is only useful for Windows targets.
-
- windres [options] [input-file] [output-file]
-
- `windres' reads resources from an input file and copies them into an
-output file. Either file may be in one of three formats:
-
-`rc'
- A text format read by the Resource Compiler.
-
-`res'
- A binary format generated by the Resource Compiler.
-
-`coff'
- A COFF object or executable.
-
- The exact description of these different formats is available in
-documentation from Microsoft.
-
- When `windres' converts from the `rc' format to the `res' format, it
-is acting like the Windows Resource Compiler. When `windres' converts
-from the `res' format to the `coff' format, it is acting like the
-Windows `CVTRES' program.
-
- When `windres' generates an `rc' file, the output is similar but not
-identical to the format expected for the input. When an input `rc'
-file refers to an external filename, an output `rc' file will instead
-include the file contents.
-
- If the input or output format is not specified, `windres' will guess
-based on the file name, or, for the input file, the file contents. A
-file with an extension of `.rc' will be treated as an `rc' file, a file
-with an extension of `.res' will be treated as a `res' file, and a file
-with an extension of `.o' or `.exe' will be treated as a `coff' file.
-
- If no output file is specified, `windres' will print the resources
-in `rc' format to standard output.
-
- The normal use is for you to write an `rc' file, use `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 `rc' file
-available to Windows.
-
-`-i FILENAME'
-`--input FILENAME'
- The name of the input file. If this option is not used, then
- `windres' will use the first non-option argument as the input file
- name. If there are no non-option arguments, then `windres' will
- read from standard input. `windres' can not read a COFF file from
- standard input.
-
-`-o FILENAME'
-`--output FILENAME'
- The name of the output file. If this option is not used, then
- `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 `windres' will write to standard output.
- `windres' can not write a COFF file to standard output. Note, for
- compatibility with `rc' the option `-fo' is also accepted, but its
- use is not recommended.
-
-`-J FORMAT'
-`--input-format FORMAT'
- The input format to read. FORMAT may be `res', `rc', or `coff'.
- If no input format is specified, `windres' will guess, as
- described above.
-
-`-O FORMAT'
-`--output-format FORMAT'
- The output format to generate. FORMAT may be `res', `rc', or
- `coff'. If no output format is specified, `windres' will guess,
- as described above.
-
-`-F TARGET'
-`--target 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 `--help' option to see
- a list of supported targets. Normally `windres' will use the
- default format, which is the first one listed by the `--help'
- option. *Note Target Selection::.
-
-`--preprocessor PROGRAM'
- When `windres' reads an `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 `gcc -E -xc-header -DRC_INVOKED'.
-
-`-I DIRECTORY'
-`--include-dir DIRECTORY'
- Specify an include directory to use when reading an `rc' file.
- `windres' will pass this to the preprocessor as an `-I' option.
- `windres' will also search this directory when looking for files
- named in the `rc' file. If the argument passed to this command
- matches any of the supported FORMATS (as described in the `-J'
- option), it will issue a deprecation warning, and behave just like
- the `-J' option. New programs should not use this behaviour. If a
- directory happens to match a FORMAT, simple prefix it with `./' to
- disable the backward compatibility.
-
-`-D TARGET'
-`--define SYM[=VAL]'
- Specify a `-D' option to pass to the preprocessor when reading an
- `rc' file.
-
-`-U TARGET'
-`--undefine SYM'
- Specify a `-U' option to pass to the preprocessor when reading an
- `rc' file.
-
-`-r'
- Ignored for compatibility with rc.
-
-`-v'
- Enable verbose mode. This tells you what the preprocessor is if
- you didn't specify one.
-
-`-c VAL'
-
-`--codepage VAL'
- Specify the default codepage to use when reading an `rc' file.
- VAL should be a hexadecimal prefixed by `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.
-
-`-l VAL'
-
-`--language VAL'
- Specify the default language to use when reading an `rc' file.
- VAL should be a hexadecimal language code. The low eight bits are
- the language, and the high eight bits are the sublanguage.
-
-`--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).
-
-`--no-use-temp-file'
- Use popen, not a temporary file, to read the output of the
- preprocessor. This is the default behaviour.
-
-`-h'
-
-`--help'
- Prints a usage summary.
-
-`-V'
-
-`--version'
- Prints the version number for `windres'.
-
-`--yydebug'
- If `windres' is compiled with `YYDEBUG' defined as `1', this will
- turn on parser debugging.
-
-\1f
-File: binutils.info, Node: dlltool, Next: Common Options, Prev: windmc, Up: Top
-
-14 dlltool
-**********
-
-`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.
-
- The export table is generated by this program by reading in a `.def'
-file or scanning the `.a' and `.o' files which will be in the DLL. A
-`.o' file can contain information in special `.drectve' sections with
-export information.
-
- _Note:_ `dlltool' is not always built as part of the binary
- utilities, since it is only useful for those targets which support
- DLLs.
-
- 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 ...]
-
- `dlltool' reads its inputs, which can come from the `-d' and `-b'
-options as well as object files specified on the command line. It then
-processes these inputs and if the `-e' option has been specified it
-creates a exports file. If the `-l' option has been specified it
-creates a library file and if the `-z' option has been specified it
-creates a def file. Any or all of the `-e', `-l' and `-z' options can
-be present in one invocation of dlltool.
-
- When creating a DLL, along with the source for the DLL, it is
-necessary to have three other files. `dlltool' can help with the
-creation of these files.
-
- The first file is a `.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 `dlltool' can be used to
-create it using the `-z' option. In this case `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 `.def' file it creates.
-
- In order to mark a function as being exported from a DLL, it needs to
-have an `-export:<name_of_function>' entry in the `.drectve' section of
-the object file. This can be done in C by using the asm() operator:
-
- asm (".section .drectve");
- asm (".ascii \"-export:my_func\"");
-
- int my_func (void) { ... }
-
- 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 `-e' option to
-`dlltool' when it is creating or reading in a `.def' file.
-
- 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 `-l' option to dlltool when it
-is creating or reading in a `.def' file.
-
- `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 `-S' command line option can be used to
-specify the path to the assembler that dlltool will use, and the `-f'
-option can be used to pass specific flags to that assembler. The `-n'
-can be used to prevent dlltool from deleting these temporary assembler
-files when it is done, and if `-n' is specified twice then this will
-prevent dlltool from deleting the temporary object files it used to
-build the library.
-
- Here is an example of creating a DLL from a source file `dll.c' and
-also creating a program (from an object file called `program.o') that
-uses that DLL:
-
- 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
-
- The command line options have the following meanings:
-
-`-d FILENAME'
-`--input-def FILENAME'
- Specifies the name of a `.def' file to be read in and processed.
-
-`-b FILENAME'
-`--base-file 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.
-
-`-e FILENAME'
-`--output-exp FILENAME'
- Specifies the name of the export file to be created by dlltool.
-
-`-z FILENAME'
-`--output-def FILENAME'
- Specifies the name of the `.def' file to be created by dlltool.
-
-`-l FILENAME'
-`--output-lib FILENAME'
- Specifies the name of the library file to be created by dlltool.
-
-`--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 `--no-default-excludes'
- option. You may add to the list of symbols to not export by using
- the `--exclude-symbols' option.
-
-`--no-export-all-symbols'
- Only export symbols explicitly listed in an input `.def' file or in
- `.drectve' sections in the input object files. This is the default
- behaviour. The `.drectve' sections are created by `dllexport'
- attributes in the source code.
-
-`--exclude-symbols LIST'
- Do not export the symbols in 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
- `--export-all-symbols' is used.
-
-`--no-default-excludes'
- When `--export-all-symbols' is used, it will by default avoid
- exporting certain special symbols. The current list of symbols to
- avoid exporting is `DllMain@12', `DllEntryPoint@0', `impure_ptr'.
- You may use the `--no-default-excludes' option to go ahead and
- export these special symbols. This is only meaningful when
- `--export-all-symbols' is used.
-
-`-S PATH'
-`--as PATH'
- Specifies the path, including the filename, of the assembler to be
- used to create the exports file.
-
-`-f OPTIONS'
-`--as-flags 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 `-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.
-
-`-D NAME'
-`--dll-name NAME'
- Specifies the name to be stored in the `.def' file as the name of
- the DLL when the `-e' option is used. If this option is not
- present, then the filename given to the `-e' option will be used
- as the name of the DLL.
-
-`-m MACHINE'
-`-machine MACHINE'
- Specifies the type of machine for which the library file should be
- built. `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.
-
-`-a'
-`--add-indirect'
- Specifies that when `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!
-
-`-U'
-`--add-underscore'
- Specifies that when `dlltool' is creating the exports file it
- should prepend an underscore to the names of _all_ exported
- symbols.
-
-`--add-stdcall-underscore'
- Specifies that when `dlltool' is creating the exports file it
- should prepend an underscore to the names of exported _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.
-
-`-k'
-`--kill-at'
- Specifies that when `dlltool' is creating the exports file it
- should not append the string `@ <number>'. These numbers are
- called ordinal numbers and they represent another way of accessing
- the function in a DLL, other than by name.
-
-`-A'
-`--add-stdcall-alias'
- Specifies that when `dlltool' is creating the exports file it
- should add aliases for stdcall symbols without `@ <number>' in
- addition to the symbols with `@ <number>'.
-
-`-p'
-`--ext-prefix-alias PREFIX'
- Causes `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.
-
-`-x'
-`--no-idata4'
- Specifies that when `dlltool' is creating the exports and library
- files it should omit the `.idata4' section. This is for
- compatibility with certain operating systems.
-
-`-c'
-`--no-idata5'
- Specifies that when `dlltool' is creating the exports and library
- files it should omit the `.idata5' section. This is for
- compatibility with certain operating systems.
-
-`-i'
-`--interwork'
- Specifies that `dlltool' should mark the objects in the library
- file and exports file that it produces as supporting interworking
- between ARM and Thumb code.
-
-`-n'
-`--nodelete'
- Makes `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.
-
-`-t PREFIX'
-`--temp-prefix PREFIX'
- Makes `dlltool' use PREFIX when constructing the names of
- temporary assembler and object files. By default, the temp file
- prefix is generated from the pid.
-
-`-v'
-`--verbose'
- Make dlltool describe what it is doing.
-
-`-h'
-`--help'
- Displays a list of command line options and then exits.
-
-`-V'
-`--version'
- Displays dlltool's version number and then exits.
-
-
-* Menu:
-
-* def file format:: The format of the dlltool `.def' file
-
-\1f
-File: binutils.info, Node: def file format, Up: dlltool
-
-14.1 The format of the `dlltool' `.def' file
-============================================
-
-A `.def' file contains any number of the following commands:
-
-`NAME' NAME `[ ,' BASE `]'
- The result is going to be named NAME`.exe'.
-
-`LIBRARY' NAME `[ ,' BASE `]'
- The result is going to be named NAME`.dll'.
-
-`EXPORTS ( ( (' NAME1 `[ = ' NAME2 `] ) | ( ' NAME1 `=' MODULE-NAME `.' EXTERNAL-NAME `) )'
-
-`[' INTEGER `] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *'
- Declares NAME1 as an exported symbol from the DLL, with optional
- ordinal number INTEGER, or declares NAME1 as an alias (forward) of
- the function EXTERNAL-NAME in the DLL MODULE-NAME.
-
-`IMPORTS ( (' INTERNAL-NAME `=' MODULE-NAME `.' INTEGER `) | [' INTERNAL-NAME `= ]' MODULE-NAME `.' EXTERNAL-NAME `) ) *'
- Declares that EXTERNAL-NAME or the exported function whose ordinal
- number is INTEGER is to be imported from the file MODULE-NAME. If
- INTERNAL-NAME is specified then this is the name that the imported
- function will be referred to in the body of the DLL.
-
-`DESCRIPTION' STRING
- Puts STRING into the output `.exp' file in the `.rdata' section.
-
-`STACKSIZE' NUMBER-RESERVE `[, ' NUMBER-COMMIT `]'
-
-`HEAPSIZE' NUMBER-RESERVE `[, ' NUMBER-COMMIT `]'
- Generates `--stack' or `--heap' NUMBER-RESERVE,NUMBER-COMMIT in
- the output `.drectve' section. The linker will see this and act
- upon it.
-
-`CODE' ATTR `+'
-
-`DATA' ATTR `+'
-
-`SECTIONS (' SECTION-NAME ATTR` + ) *'
- Generates `--attr' SECTION-NAME ATTR in the output `.drectve'
- section, where ATTR is one of `READ', `WRITE', `EXECUTE' or
- `SHARED'. The linker will see this and act upon it.
-
-
-\1f
-File: binutils.info, Node: readelf, Next: size, Prev: ranlib, Up: Top
-
-15 readelf
-**********
-
- 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...
-
- `readelf' displays information about one or more ELF format object
-files. The options control what particular information to display.
-
- ELFFILE... are the object files to be examined. 32-bit and 64-bit
-ELF files are supported, as are archives containing ELF files.
-
- This program performs a similar function to `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.
-
- The long and short forms of options, shown here as alternatives, are
-equivalent. At least one option besides `-v' or `-H' must be given.
-
-`-a'
-`--all'
- Equivalent to specifying `--file-header', `--program-headers',
- `--sections', `--symbols', `--relocs', `--dynamic', `--notes' and
- `--version-info'.
-
-`-h'
-`--file-header'
- Displays the information contained in the ELF header at the start
- of the file.
-
-`-l'
-`--program-headers'
-`--segments'
- Displays the information contained in the file's segment headers,
- if it has any.
-
-`-S'
-`--sections'
-`--section-headers'
- Displays the information contained in the file's section headers,
- if it has any.
-
-`-g'
-`--section-groups'
- Displays the information contained in the file's section groups,
- if it has any.
-
-`-t'
-`--section-details'
- Displays the detailed section information. Implies `-S'.
-
-`-s'
-`--symbols'
-`--syms'
- Displays the entries in symbol table section of the file, if it
- has one.
-
-`-e'
-`--headers'
- Display all the headers in the file. Equivalent to `-h -l -S'.
-
-`-n'
-`--notes'
- Displays the contents of the NOTE segments and/or sections, if any.
-
-`-r'
-`--relocs'
- Displays the contents of the file's relocation section, if it has
- one.
-
-`-u'
-`--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.
-
-`-d'
-`--dynamic'
- Displays the contents of the file's dynamic section, if it has one.
-
-`-V'
-`--version-info'
- Displays the contents of the version sections in the file, it they
- exist.
-
-`-A'
-`--arch-specific'
- Displays architecture-specific information in the file, if there
- is any.
-
-`-D'
-`--use-dynamic'
- When displaying symbols, this option makes `readelf' use the
- symbol table in the file's dynamic section, rather than the one in
- the symbols section.
-
-`-x <number or name>'
-`--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.
-
-`-w[liaprmfFsoR]'
-`--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.
-
-`-I'
-`--histogram'
- Display a histogram of bucket list lengths when displaying the
- contents of the symbol tables.
-
-`-v'
-`--version'
- Display the version number of readelf.
-
-`-W'
-`--wide'
- Don't break output lines to fit into 80 columns. By default
- `readelf' breaks section header and segment listing lines for
- 64-bit ELF files, so that they fit into 80 columns. This option
- causes `readelf' to print each section header resp. each segment
- one a single line, which is far more readable on terminals wider
- than 80 columns.
-
-`-H'
-`--help'
- Display the command line options understood by `readelf'.
-
-
-\1f
-File: binutils.info, Node: Common Options, Next: Selecting The Target System, Prev: dlltool, Up: Top
-
-16 Common Options
-*****************
-
-The following command-line options are supported by all of the programs
-described in this manual.
-
-`@FILE'
- Read command-line options from FILE. The options read are
- inserted in place of the original @FILE option. If FILE does not
- exist, or cannot be read, then the option will be treated
- literally, and not removed.
-
- Options in 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 FILE may itself contain
- additional @FILE options; any such options will be processed
- recursively.
-
-`--help'
- Display the command-line options supported by the program.
-
-`--version'
- Display the version number of the program.
-
-
-\1f
-File: binutils.info, Node: Selecting The Target System, Next: Reporting Bugs, Prev: Common Options, Up: Top
-
-17 Selecting the Target System
-******************************
-
-You can specify two aspects of the target system to the GNU binary file
-utilities, each in several ways:
-
- * the target
-
- * the architecture
-
- 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.
-
- The commands to list valid values only list the values for which the
-programs you are running were configured. If they were configured with
-`--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 "native" (on hosts with the
-same type as the target system).
-
-* Menu:
-
-* Target Selection::
-* Architecture Selection::
-
-\1f
-File: binutils.info, Node: Target Selection, Next: Architecture Selection, Up: Selecting The Target System
-
-17.1 Target Selection
-=====================
-
-A "target" is an object file format. A given target may be supported
-for multiple architectures (*note Architecture Selection::). A target
-selection may also have variations for different operating systems or
-architectures.
-
- The command to list valid target values is `objdump -i' (the first
-column of output contains the relevant information).
-
- Some sample values are: `a.out-hp300bsd', `ecoff-littlemips',
-`a.out-sunos-big'.
-
- You can also specify a target using a configuration triplet. This is
-the same sort of name that is passed to `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 `config.sub' which is included with the
-sources.
-
- Some sample configuration triplets are: `m68k-hp-bsd',
-`mips-dec-ultrix', `sparc-sun-sunos'.
-
-`objdump' Target
-----------------
-
-Ways to specify:
-
- 1. command line option: `-b' or `--target'
-
- 2. environment variable `GNUTARGET'
-
- 3. deduced from the input file
-
-`objcopy' and `strip' Input Target
-----------------------------------
-
-Ways to specify:
-
- 1. command line options: `-I' or `--input-target', or `-F' or
- `--target'
-
- 2. environment variable `GNUTARGET'
-
- 3. deduced from the input file
-
-`objcopy' and `strip' Output Target
------------------------------------
-
-Ways to specify:
-
- 1. command line options: `-O' or `--output-target', or `-F' or
- `--target'
-
- 2. the input target (see "`objcopy' and `strip' Input Target" above)
-
- 3. environment variable `GNUTARGET'
-
- 4. deduced from the input file
-
-`nm', `size', and `strings' Target
-----------------------------------
-
-Ways to specify:
-
- 1. command line option: `--target'
-
- 2. environment variable `GNUTARGET'
-
- 3. deduced from the input file
-
-\1f
-File: binutils.info, Node: Architecture Selection, Prev: Target Selection, Up: Selecting The Target System
-
-17.2 Architecture Selection
-===========================
-
-An "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.
-
- The command to list valid architecture values is `objdump -i' (the
-second column contains the relevant information).
-
- Sample values: `m68k:68020', `mips:3000', `sparc'.
-
-`objdump' Architecture
-----------------------
-
-Ways to specify:
-
- 1. command line option: `-m' or `--architecture'
-
- 2. deduced from the input file
-
-`objcopy', `nm', `size', `strings' Architecture
------------------------------------------------
-
-Ways to specify:
-
- 1. deduced from the input file
-
-\1f
-File: binutils.info, Node: Reporting Bugs, Next: GNU Free Documentation License, Prev: Selecting The Target System, Up: Top
-
-18 Reporting Bugs
-*****************
-
-Your bug reports play an essential role in making the binary utilities
-reliable.
-
- 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.
-
- In order for a bug report to serve its purpose, you must include the
-information that enables us to fix the bug.
-
-* Menu:
-
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-
-\1f
-File: binutils.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs
-
-18.1 Have You Found a Bug?
-==========================
-
-If you are not sure whether you have found a bug, here are some
-guidelines:
-
- * If a binary utility gets a fatal signal, for any input whatever,
- that is a bug. Reliable utilities never crash.
-
- * If a binary utility produces an error message for valid input,
- that is a bug.
-
- * If you are an experienced user of binary utilities, your
- suggestions for improvement are welcome in any case.
-
-\1f
-File: binutils.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
-
-18.2 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.
-
- You can find contact information for many support companies and
-individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
-
- In any event, we also recommend that you send bug reports for the
-binary utilities to `http://www.sourceware.org/bugzilla/'.
-
- The fundamental principle of reporting bugs usefully is this:
-*report all the facts*. If you are not sure whether to state a fact or
-leave it out, state it!
-
- 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.
-
- 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.
-
- Sometimes people give a few sketchy facts and ask, "Does this ring a
-bell?" 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.
-
- To enable us to fix the bug, you should include all these things:
-
- * The version of the utility. Each utility announces it if you
- start it with the `--version' argument.
-
- Without this, we will not know whether there is any point in
- looking for the bug in the current version of the binary utilities.
-
- * Any patches you may have applied to the source, including any
- patches made to the `BFD' library.
-
- * The type of machine you are using, and the operating system name
- and version number.
-
- * What compiler (and its version) was used to compile the
- utilities--e.g. "`gcc-2.7'".
-
- * 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.
-
- If we were to try to guess the arguments, we would probably guess
- wrong and then we might not encounter the bug.
-
- * 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.
-
- If the source files were produced exclusively using GNU programs
- (e.g., `gcc', `gas', and/or the GNU `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 `gcc', or whatever, was
- used to produce the object files. Also say how `gcc', or
- whatever, was configured.
-
- * A description of what behavior you observe that you believe is
- incorrect. For example, "It gets a fatal signal."
-
- 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.
-
- 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.
-
- * If you wish to suggest changes to the source, send us context
- diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
- Always send diffs from the old file to the new file. If you wish
- to discuss something in the `ld' source, refer to it by context,
- not by line number.
-
- The line numbers in our development sources will not match those
- in your sources. Your line numbers would convey no useful
- information to us.
-
- Here are some things that are not necessary:
-
- * A description of the envelope of the bug.
-
- 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.
-
- 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.
-
- Of course, if you can find a simpler example to report _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.
-
- 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.
-
- * A patch for the bug.
-
- 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.
-
- 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.
-
- 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.
-
- * A guess about what the bug is or what it depends on.
-
- Such guesses are usually wrong. Even we cannot guess right about
- such things without first using the debugger to find the facts.
-
-\1f
-File: binutils.info, Node: GNU Free Documentation License, Next: Binutils Index, Prev: Reporting Bugs, Up: Top
-
-Appendix A GNU Free Documentation License
-*****************************************
-
- Version 1.1, March 2000
-
- Copyright (C) 2000, 2003 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.
-
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone
- the effective freedom to copy and redistribute it, with or without
- modifying it, either commercially or noncommercially. Secondarily,
- this License preserves for the author and publisher a way to get
- credit for their work, while not being considered responsible for
- modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to
- software manuals; it can be used for any textual work, regardless
- of subject matter or whether it is published as a printed book.
- We recommend this License principally for works whose purpose is
- instruction or reference.
-
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be distributed
- under the terms of this License. The "Document", below, refers to
- any such manual or work. Any member of the public is a licensee,
- and is addressed as "you."
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter
- section of the Document that deals exclusively with the
- relationship of the publishers or authors of the Document to the
- Document's overall subject (or to related matters) and contains
- nothing that could fall directly within that overall subject.
- (For example, if the Document is in part a textbook of
- mathematics, a Secondary Section may not explain any mathematics.)
- The relationship could be a matter of historical connection with
- the subject or with related matters, or of legal, commercial,
- philosophical, ethical or political position regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, whose contents can be viewed and edited directly
- and straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup has been designed
- to thwart or discourage subsequent modification by readers is not
- Transparent. A copy that is not "Transparent" is called "Opaque."
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human modification.
- Opaque formats include PostScript, PDF, proprietary formats that
- can be read and edited only by proprietary word processors, SGML
- or XML for which the DTD and/or processing tools are not generally
- available, and the machine-generated HTML produced by some word
- processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, "Title
- Page" means the text near the most prominent appearance of the
- work's title, preceding the beginning of the body of the text.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow
- the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more than
- 100, and the Document's license notice requires Cover Texts, you
- must enclose the copies in covers that carry, clearly and legibly,
- all these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the
- title equally prominent and visible. You may add other material
- on the covers in addition. Copying with changes limited to the
- covers, as long as they preserve the title of the Document and
- satisfy these conditions, can be treated as verbatim copying in
- other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy, or
- state in or with each Opaque copy a publicly-accessible
- computer-network location containing a complete Transparent copy
- of the Document, free of added material, which the general
- network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with
- the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version to
- whoever possesses a copy of it. In addition, you must do these
- things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title
- as a previous version if the original publisher of that version
- gives permission.
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it
- has less than five).
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page.
- If there is no section entitled "History" in the Document,
- create one stating the title, year, authors, and publisher of
- the Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in the
- "History" section. You may omit a network location for a work
- that was published at least four years before the Document
- itself, or if the original publisher of the version it refers
- to gives permission.
- K. In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
- M. Delete any section entitled "Endorsements." Such a section
- may not be included in the Modified Version.
- N. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do this,
- add their titles to the list of Invariant Sections in the Modified
- Version's license notice. These titles must be distinct from any
- other section titles.
-
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties-for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition
- of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If the
- Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same entity
- you are acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section
- entitled "History"; likewise combine any sections entitled
- "Acknowledgements", and any sections entitled "Dedications." You
- must delete all sections entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow
- this License in all other respects regarding verbatim copying of
- that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of
- a storage or distribution medium, does not as a whole count as a
- Modified Version of the Document, provided no compilation
- copyright is claimed for the compilation. Such a compilation is
- called an "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document, on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may be
- placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License provided that you also include the
- original English version of this License. In case of a
- disagreement between the translation and the original English
- version of this License, the original English version will prevail.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-====================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.1
- or any later version published by the Free Software Foundation;
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License."
-
- If you have no Invariant Sections, write "with no Invariant Sections"
-instead of saying which ones are invariant. If you have no Front-Cover
-Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
-LIST"; likewise for Back-Cover Texts.
-
- If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License, to
-permit their use in free software.
-
-\1f
-File: binutils.info, Node: Binutils Index, Prev: GNU Free Documentation License, Up: Top
-
-Binutils Index
-**************
-
-\0\b[index\0\b]
-* Menu:
-
-* .stab: objdump. (line 324)
-* addr2line: addr2line. (line 6)
-* address to file name and line number: addr2line. (line 6)
-* all header information, object file: objdump. (line 364)
-* ar: ar. (line 6)
-* ar compatibility: ar. (line 40)
-* architecture: objdump. (line 176)
-* architectures available: objdump. (line 161)
-* archive contents: ranlib. (line 6)
-* archive headers: objdump. (line 60)
-* archives: ar. (line 6)
-* base files: dlltool. (line 108)
-* bug criteria: Bug Criteria. (line 6)
-* bug reports: Bug Reporting. (line 6)
-* bugs: Reporting Bugs. (line 6)
-* bugs, reporting: Bug Reporting. (line 6)
-* c++filt: c++filt. (line 6)
-* changing object addresses: objcopy. (line 275)
-* changing section address: objcopy. (line 285)
-* changing section LMA: objcopy. (line 293)
-* changing section VMA: objcopy. (line 306)
-* changing start address: objcopy. (line 270)
-* collections of files: ar. (line 6)
-* compatibility, ar: ar. (line 40)
-* contents of archive: ar cmdline. (line 88)
-* crash: Bug Criteria. (line 9)
-* creating archives: ar cmdline. (line 127)
-* cxxfilt: c++filt. (line 14)
-* dates in archive: ar cmdline. (line 154)
-* debug symbols: objdump. (line 319)
-* debugging symbols: nm. (line 116)
-* deleting from archive: ar cmdline. (line 26)
-* demangling C++ symbols: c++filt. (line 6)
-* demangling in nm: nm. (line 124)
-* demangling in objdump <1>: addr2line. (line 55)
-* demangling in objdump: objdump. (line 88)
-* disassembling object code: objdump. (line 110)
-* disassembly architecture: objdump. (line 176)
-* disassembly endianness: objdump. (line 126)
-* disassembly, with source: objdump. (line 305)
-* discarding symbols: strip. (line 6)
-* DLL: dlltool. (line 6)
-* dlltool: dlltool. (line 6)
-* DWARF: objdump. (line 319)
-* dynamic relocation entries, in object file: objdump. (line 294)
-* dynamic symbol table entries, printing: objdump. (line 348)
-* dynamic symbols: nm. (line 136)
-* ELF dynamic section information: readelf. (line 102)
-* ELF file header information: readelf. (line 51)
-* ELF file information: readelf. (line 6)
-* ELF notes: readelf. (line 87)
-* ELF object file format: objdump. (line 324)
-* ELF program header information: readelf. (line 57)
-* ELF reloc information: readelf. (line 91)
-* ELF section group information: readelf. (line 68)
-* ELF section information: readelf. (line 63)
-* ELF segment information: readelf. (line 57)
-* ELF symbol table information: readelf. (line 78)
-* ELF version sections informations: readelf. (line 106)
-* endianness: objdump. (line 126)
-* error on valid input: Bug Criteria. (line 12)
-* external symbols: nm. (line 148)
-* extract from archive: ar cmdline. (line 103)
-* fatal signal: Bug Criteria. (line 9)
-* file name: nm. (line 110)
-* header information, all: objdump. (line 364)
-* input .def file: dlltool. (line 104)
-* input file name: nm. (line 110)
-* libraries: ar. (line 25)
-* listings strings: strings. (line 6)
-* machine instructions: objdump. (line 110)
-* moving in archive: ar cmdline. (line 34)
-* MRI compatibility, ar: ar scripts. (line 8)
-* name duplication in archive: ar cmdline. (line 97)
-* name length: ar. (line 18)
-* nm: nm. (line 6)
-* nm compatibility: nm. (line 120)
-* nm format: nm. (line 120)
-* not writing archive index: ar cmdline. (line 173)
-* objdump: objdump. (line 6)
-* object code format <1>: addr2line. (line 50)
-* object code format <2>: strings. (line 66)
-* object code format <3>: size. (line 84)
-* object code format <4>: objdump. (line 74)
-* object code format: nm. (line 212)
-* object file header: objdump. (line 132)
-* object file information: objdump. (line 6)
-* object file sections: objdump. (line 300)
-* object formats available: objdump. (line 161)
-* operations on archive: ar cmdline. (line 22)
-* printing from archive: ar cmdline. (line 46)
-* printing strings: strings. (line 6)
-* quick append to archive: ar cmdline. (line 54)
-* radix for section sizes: size. (line 66)
-* ranlib: ranlib. (line 6)
-* readelf: readelf. (line 6)
-* relative placement in archive: ar cmdline. (line 115)
-* relocation entries, in object file: objdump. (line 288)
-* removing symbols: strip. (line 6)
-* repeated names in archive: ar cmdline. (line 97)
-* replacement in archive: ar cmdline. (line 70)
-* reporting bugs: Reporting Bugs. (line 6)
-* scripts, ar: ar scripts. (line 8)
-* section addresses in objdump: objdump. (line 66)
-* section headers: objdump. (line 143)
-* section information: objdump. (line 166)
-* section sizes: size. (line 6)
-* sections, full contents: objdump. (line 300)
-* size: size. (line 6)
-* size display format: size. (line 27)
-* size number format: size. (line 66)
-* sorting symbols: nm. (line 167)
-* source code context: objdump. (line 136)
-* source disassembly: objdump. (line 305)
-* source file name: nm. (line 110)
-* source filenames for object files: objdump. (line 170)
-* stab: objdump. (line 324)
-* start-address: objdump. (line 334)
-* stop-address: objdump. (line 338)
-* strings: strings. (line 6)
-* strings, printing: strings. (line 6)
-* strip: strip. (line 6)
-* symbol index <1>: ranlib. (line 6)
-* symbol index: ar. (line 28)
-* symbol index, listing: nm. (line 182)
-* symbol line numbers: nm. (line 152)
-* symbol table entries, printing: objdump. (line 343)
-* symbols: nm. (line 6)
-* symbols, discarding: strip. (line 6)
-* undefined symbols: nm. (line 217)
-* Unix compatibility, ar: ar cmdline. (line 8)
-* unwind information: readelf. (line 96)
-* updating an archive: ar cmdline. (line 180)
-* version: Top. (line 6)
-* VMA in objdump: objdump. (line 66)
-* wide output, printing: objdump. (line 370)
-* writing archive index: ar cmdline. (line 167)
-
-
-\1f
-Tag Table:
-Node: Top\7f1785
-Node: ar\7f3412
-Node: ar cmdline\7f5590
-Node: ar scripts\7f13733
-Node: nm\7f19421
-Node: objcopy\7f27616
-Node: objdump\7f53142
-Node: ranlib\7f68108
-Node: size\7f68863
-Node: strings\7f71868
-Node: strip\7f74246
-Node: c++filt\7f80196
-Ref: c++filt-Footnote-1\7f85120
-Node: addr2line\7f85226
-Node: nlmconv\7f88497
-Node: windmc\7f91103
-Node: windres\7f94824
-Node: dlltool\7f100851
-Node: def file format\7f111688
-Node: readelf\7f113426
-Node: Common Options\7f118133
-Node: Selecting The Target System\7f119173
-Node: Target Selection\7f120105
-Node: Architecture Selection\7f122087
-Node: Reporting Bugs\7f122915
-Node: Bug Criteria\7f123694
-Node: Bug Reporting\7f124247
-Node: GNU Free Documentation License\7f131117
-Node: Binutils Index\7f150858
-\1f
-End Tag Table
+++ /dev/null
-("cs" 0x0
- (("size") (1 byte) ("size"))
-
- (("hd") (1 byte) ("hd"))
- (("hs") (1 byte) ("hs"))
- (("un") (1 byte) ("un"))
- (("us") (1 byte) ("us"))
-
- (("sc") (1 byte) ("sc"))
- (("ss") (1 byte) ("ss"))
- (("er") (1 byte) ("er"))
- (("ed") (1 byte) ("ed"))
-
- (("sh") (1 byte) ("sh"))
- (("ob") (1 byte) ("ob"))
- (("rl") (1 byte) ("rl"))
- (("du") (1 byte) ("du"))
-
- (("dps") (1 byte) ("dps"))
- (("dsy") (1 byte) ("dsy"))
- (("dty") (1 byte) ("dty"))
- (("dln") (1 byte) ("dln"))
-
- (("dso") (1 byte) ("dso"))
- (("dus") (1 byte) ("dus"))
- (("dss") (1 byte) ("dss"))
- (("dbt") (1 byte) ("dbt"))
-
- (("dpp") (1 byte) ("dpp"))
- (("dfp") (1 byte) ("dfp"))
- (("den") (1 byte) ("den"))
- (("dds") (1 byte) ("dds"))
-
- (("dar") (1 byte) ("dar"))
- (("dpt") (1 byte) ("dpt"))
- (("dul") (1 byte) ("dul"))
- (("dse") (1 byte) ("dse"))
-
- (("dot") (1 byte) ("dot")))
-
-
-("hd" 0x04
- (("module type") (4 bits) ("mt")
- (("MTYPE_ABS_LM" "0")
- ("MTYPE_REL_LM" "1")
- ("MTYPE_OMS_OR_LMS" "2")
- ("MTYPE_UNSPEC" "0xf")))
- (("spare")(4 bits) ("spare1"))
- (("creation date")( chars 12 bytes)( "cd"))
- (("number of units") (2 bytes) ("nu"))
- (("code") (1 byte) ("code"))
- (("version") (chars 4 bytes) ("ver"))
- (("address update") (1 byte) ("au"))
- (("segment identifier") (1 bit) ("si"))
- (("address field length") (4 bits) ("afl"))
- (("spare")(3 bits) ("spare2"))
- (("space size within segment") (1 byte) ("spcsz"))
- (("segment size") (1 byte) ("segsz"))
- (("segment shift") (1 byte) ("segsh"))
- (("entry point") (1 byte) ("ep"))
- (cond "ptr->ep"
- (cond "ptr->mt != MTYPE_ABS_LM"
- (("unit appearance number") (2 bytes) ("uan"))
- (("section appearance number") (2 bytes) ("sa")))
- (cond "segmented_p"
- (("segment address") (segsize bytes) ("sad")))
- (("address") (addrsize bytes) ("address")))
- (("os name") (chars variable bytes) ("os"))
- (("sys name") (chars variable bytes) ("sys"))
- (("module name") (chars variable bytes) ("mn"))
- (("cpu") (chars variable bytes) ("cpu")))
-
-
-("hs" 0x05
- (("neg number") (2 bytes) ("neg")))
-
-
-("un" 0x06
- (("format") (2 bits) ("format")
- (("FORMAT_LM" "0")
- ("FORMAT_OM" "1")
- ("FORMAT_OMS_OR_LMS" "2")))
- (("spare") (6 bits) ("spare1"))
- (("number of sections") (2 bytes) ("nsections"))
- (("number of external refs") (2 bytes) ("nextrefs"))
- (("number of external defs") (2 bytes) ("nextdefs"))
- (("unit name") (chars variable byte) ("name"))
- (("tool name") (chars variable byte) ("tool"))
- (("creation date") (chars 12 bytes) ("tcd"))
- (("linker name") (chars variable byte) ("linker"))
- (("creation date") (chars 12 bytes) ("lcd")))
-
-
-("us" 0x07
- (("negotiation number") (2 bytes) ("neg")))
-
-
-("sc" 0x08
- (("format") (2 bits) ("format"))
- (("spare") (6 bits) ("spare"))
- (("segment address") (segsize bytes) ("segadd"))
- (("address") (addrsize bytes) ("addr"))
- (("length") (addrsize bytes) ("length"))
- (("alignment") (addrsize bytes) ("align"))
- (("contents") (4 bits) ("contents")
- (("CONTENTS_CODE" "0")
- ("CONTENTS_DATA" "1")
- ("CONTENTS_STACK" "2")
- ("CONTENTS_DUMMY" "3")
- ("CONTENTS_SPECIAL" "4")
- ("CONTENTS_NONSPEC" "0xf")))
- (("concat") (4 bits) ("concat")
- (("CONCAT_SIMPLE" "0")
- ("CONCAT_SHAREDC" "1")
- ("CONCAT_DUMMY" "2")
- ("CONCAT_GROUP" "3")
- ("CONCAT_SHARED" "4")
- ("CONCAT_PRIVATE" "5")
- ("CONCAT_UNSPEC" "0xf")))
- (("read") (2 bits) ("read"))
- (("write") (2 bits) ("write"))
- (("exec") (2 bits) ("exec"))
- (("initialized") (2 bits) ("init"))
- (("mode") (2 bits) ("mode"))
- (("spare") (6 bits) ("spare1"))
- (("name") (chars variable byte) ("name")))
-
-
-("ss" 0x09
- (("neg number") (2 bytes) ("neg")))
-
-
-("er" 0x0c
- (("symbol type") (2 bits) ("type")
- (("ER_ENTRY" "0")
- ("ER_DATA" "1")
- ("ER_NOTDEF" "2")
- ("ER_NOTSPEC" "3")))
- (("spare") (6 bits) ("spare"))
- (("symbol name") (chars variable byte) ("name")))
-
-
-("ed" 0x14
- (("section appearance number") (2 bytes) ("section"))
- (("symbol type") (3 bits) ("type")
- (("ED_TYPE_ENTRY" "0")
- ("ED_TYPE_DATA" "1")
- ("ED_TYPE_CONST" "2")
- ("ED_TYPE_NOTSPEC" "7")))
- (("spare") (5 bits) ("spare"))
- (cond "ptr->type==ED_TYPE_ENTRY || ptr->type==ED_TYPE_DATA"
- (("symbol address") (addrsize bytes) ("address")))
- (cond "ptr->type==ED_TYPE_CONST"
- (("constant value") (addrsize bytes) ("constant")))
- (("symbol name") (chars variable byte) ("name")))
-
-
-("sh" 0x1a
- (("unit appearance number") (2 bytes) ("unit"))
- (("section appearance number") (2 bytes) ("section")))
-
-
-("ob" 0x1c
- (("starting address flag") (1 bit) ("saf"))
- (("compression flag") (1 bit) ("cpf"))
- (("spare") (6 bits) ("spare"))
- (cond "ptr->saf"
- ( ("starting address") (addrsize bytes) ("address")))
- (cond "ptr->cpf"
- (("comp reps") (addrsize bytes) ("compreps")))
- (("data") (barray counted byte) ("data")))
-
-
-("rl" 0x20
- (("boundary of relocatable area") (4 bits) ("boundary"))
- (("address polarity") (1 bit) ("apol"))
- (("segment number") (1 bit) ("segment"))
- (("sign of relocation") (1 bit) ("sign"))
- (("check range") (1 bit) ("check"))
- (("reloc address") (addrsize bytes) ("addr"))
-
- (("bit loc") (1 byte) ("bitloc"))
- (("field length") (1 byte) ("flen"))
- (("bcount") (1 byte) ("bcount"))
- (("operator") (1 byte) ("op")
- (("OP_RELOC_ADDR" "1")
- ("OP_SEC_REF" "0")
- ("OP_EXT_REF" "2")))
- (cond "ptr->op == OP_EXT_REF"
- (("symbol number") (2 bytes) ("symn")) )
-
- (cond "ptr->op == OP_SEC_REF"
- (("section number") (2 bytes) ("secn"))
- (("const opcode") (1 byte) ("copcode_is_3"))
- (("addend length") (1 byte) ("alength_is_4"))
- (("addend") (4 byte) ("addend"))
- (("plus opcode") (1 byte) ("aopcode_is_0x20")))
-
- (cond "ptr->op == OP_RELOC_ADDR"
- (("dunno") (2 bytes) ("dunno")))
-
- (("end") (1 byte) ("end")))
-
-
-("du" 0x30
- (("format") (2 bits) ("format"))
- (("optimized") (1 bit) ("optimized"))
- (("stackfrmt") (2 bits) ("stackfrmt"))
- (("spare") (3 bits) ("spare"))
- (("unit number") (2 bytes) ("unit"))
- (("sections") (2 bytes) ("sections"))
- (repeat "ptr->sections"
- (("section appearance number") (2 bytes) ("san"))
- (("address") (addrsize bytes) ("address"))
- (("section length") (addrsize bytes) ("length")))
- (("tool name") (chars variable byte) ("tool"))
- (("creation date") (chars 12 bytes) ("date")))
-
-
-("dsy" 0x34
- (("symbol type") (7 bits) ("type")
- (("STYPE_VAR" "0")
- ("STYPE_LAB" "1")
- ("STYPE_PROC" "2")
- ("STYPE_FUNC" "3")
- ("STYPE_TYPE" "4")
- ("STYPE_CONST" "5")
- ("STYPE_ENTRY" "6")
- ("STYPE_MEMBER" "7")
- ("STYPE_ENUM" "8")
- ("STYPE_TAG" "9")
- ("STYPE_PACKAGE" "10")
- ("STYPE_GENERIC" "11")
- ("STYPE_TASK" "12")
- ("STYPE_EXCEPTION" "13")
- ("STYPE_PARAMETER" "14")
- ("STYPE_EQUATE" "15")
- ("STYPE_UNSPEC" "0x7f")))
- (("assignment info") (1 bit) ("assign"))
- (("symbol id") (2 bytes) ("snumber"))
- (("symbol name") (chars variable bytes) ("sname"))
- (("nesting level") (2 bytes) ("nesting"))
- (cond "ptr->assign"
- (("assignment type") (1 byte) ("ainfo")
- (("AINFO_REG" "1")
- ("AINFO_STATIC_EXT_DEF" "2")
- ("AINFO_STATIC_EXT_REF" "3")
- ("AINFO_STATIC_INT" "4")
- ("AINFO_STATIC_COM" "5")
- ("AINFO_AUTO" "6")
- ("AINFO_CONST" "7")
- ("AINFO_UNSPEC" "0xff")))
- (("data length") (addrsize bytes) ("dlength"))
- (cond "ptr->ainfo == AINFO_STATIC_EXT_DEF
- || ptr->ainfo == AINFO_STATIC_INT
- || ptr->ainfo == AINFO_STATIC_COM"
- (("section number") (2 bytes) ("section")))
- (cond "ptr->ainfo == AINFO_STATIC_EXT_DEF
- || ptr->ainfo == AINFO_STATIC_INT
- || ptr->ainfo == AINFO_STATIC_COM
- || ptr->ainfo == AINFO_AUTO"
- (("address") (addrsize bytes) ("address")))
- (cond "ptr->ainfo == AINFO_REG"
- (("register name") (chars variable bytes) ("reg")))
- (cond "ptr->ainfo == AINFO_STATIC_EXT_DEF
- || ptr->ainfo == AINFO_STATIC_EXT_REF"
- (("external name") (chars variable bytes) ("ename")))
- (cond "ptr->ainfo == AINFO_CONST"
- (("constant") (chars variable bytes) ("constant"))))
- (cond "ptr->type == STYPE_MEMBER"
- (("assignment unit") (1 bit) ("bitunit"))
- (("spare") (7 bits) ("spare2"))
- (("field length") (addrsize bytes) ("field_len"))
- (("field offset") (addrsize bytes) ("field_off"))
- (cond "ptr->bitunit"
- (("bit offset") (addrsize bytes) ("field_bitoff"))))
- (cond "ptr->type== STYPE_ENUM"
- (("value length") (1 byte) ("evallen"))
- (("value") (4 bytes) ("evalue")))
- (cond "ptr->type == STYPE_CONST"
- (("value") (chars variable bytes) ("cvalue")))
- (cond "ptr->type == STYPE_EQUATE"
- (("value length") (1 byte) ("qvallen"))
- (("value") (4 bytes) ("qvalue"))
- (("basic type") (1 byte) ("btype"))
- (("size information") (addrsize bytes) ("sizeinfo"))
- (("sign") (2 bits) ("sign"))
- (("floating point type") (6 bits) ("flt_type")))
- (("source file number") (2 bytes) ("sfn"))
- (("source line number") (2 bytes) ("sln"))
- (("negotiation number") (2 bytes) ("neg"))
- (cond "ptr->type == STYPE_TAG"
- (("magic") (1 byte) ("magic"))))
-
-
-
-("dul" 0x52
- (("max declaration type flag") (1 bit) ("max_variable"))
- (("max spare") (7 bits) ("maxspare"))
- (cond "ptr->max_variable == 0"
- (("maximum") (addrsize bytes) ("max"))
- (("max mode") (chars variable bytes) ("maxmode")))
-
- (("min declaration type flag") (1 bit) ("min_variable"))
- (("min spare") (7 bits) ("minspare"))
- (cond "ptr->min_variable == 0"
- (("minimum") (addrsize bytes) ("min"))
- (("min mode") (chars variable bytes) ("minmode"))))
-
-
-("dty" 0x36
- (("end flag") (1 bit) ("end"))
- (("spare") (7 bits) ("spare"))
- (cond "!ptr->end"
- (("negotiation") (2 bytes) ("neg"))))
-
-
-("dbt" 0x44
- (("basic type") (1 byte) ("btype")
- (("BTYPE_VOID" "0")
- ("BTYPE_UNDEF" "1")
- ("BTYPE_CHAR" "2")
- ("BTYPE_INT" "3")
- ("BTYPE_FLOAT" "4")
- ("BTYPE_BIT" "5")
- ("BTYPE_STRING" "6")
- ("BTYPE_DECIMAL" "7")
- ("BTYPE_ENUM" "8")
- ("BTYPE_STRUCT" "9")
- ("BTYPE_TYPE" "10")
- ("BTYPE_TAG" "11")
- ("BTYPE_UNSPEC" "0xff")))
- (("size info") (addrsize bytes) ("bitsize"))
- (("sign") (2 bits) ("sign")
- (("SIGN_SIGNED" "0")
- ("SIGN_UNSIGNED" "1")
- ("SIGN_UNSPEC" "3")))
- (("floating point type") (6 bits) ("fptype")
- (("FPTYPE_SINGLE" "0")
- ("FPTYPE_DOUBLE" "1")
- ("FPTYPE_EXTENDED" "2")
- ("FPTYPE_NOTSPEC" "0x3f")))
- (cond "ptr->btype==BTYPE_TAG || ptr->btype == BTYPE_TYPE"
- (("symbol id") (2 bytes) ("sid")))
- (("negotiation") (2 bytes) ("neg")))
-
-("dar" 0x4e
- (("element length" ) (addrsize bytes) ("length"))
- (("dims") (1 byte) ("dims"))
- (repeat "ptr->dims"
- (("variable flag") (1 bit) ("variable")
- (("VARIABLE_FIXED" "0")
- ("VARIABLE_VARIABLE" "1")))
-
- (("subscript type") (1 bit) ("subtype")
- (("SUB_INTEGER" "0")
- ("SUB_TYPE" "1")))
-
- (("spare") (6 bits) ("spare"))
-
- (cond "ptr->subtype[n] == SUB_TYPE"
- (("sub symbol id") (2 bytes) ("sid")))
-
- (cond "ptr->subtype[n] == SUB_INTEGER"
- (("max declaration type flag") (1 bit) ("max_variable"))
- (("max spare") (7 bits) ("maxspare"))
- ;; FIXME: next field should be conditional on max_variable,
- (("maximum") (addrsize bytes) ("max"))
-
- (("min declaration type flag") (1 bit) ("min_variable"))
- (("min spare") (7 bits) ("minspare"))
- ;; FIXME: next field should be conditional on min_variable
- (("minimum") (addrsize bytes) ("min"))))
- (("negotiation") (2 bytes) ("neg")))
-
-
-("dso" 0x3a
- (("function name") (2 bytes) ("sid"))
- (("sp update count") (4 bytes) ("spupdates"))
- (repeat "ptr->spupdates"
- (("update address") (addrsize bytes) ("address"))
- (("offset") (addrsize bytes) ("offset"))))
-
-("dln" 0x38
- (("number of lines") (2 bytes) ("nln"))
- (repeat "ptr->nln"
- (("source file number") (2 bytes) ("sfn"))
- (("source line number") (2 bytes) ("sln"))
- (("section number") (2 bytes) ("section"))
- (("from address") (addrsize bytes) ("from_address"))
- (("to address") (addrsize bytes) ("to_address"))
- (("call count") (2 bytes) ("cc"))
- )
- (("neg") (2 bytes) ("neg")))
-
-("dpp" 0x46
- (("start/end") (1 bit) ("end"))
- (("spare") (7 bits) ("spare"))
- (cond "!ptr->end"
- (("params") (1 byte) ("params"))
- (("neg number") (2 bytes) ("neg"))))
-
-("den" 0x4a
- (("start/end") (1 bit) ("end"))
- (("spare") (7 bits) ("spare"))
- (cond "!ptr->end"
- (("neg number") (2 bytes) ("neg"))))
-
-("dfp" 0x48
- (("start/end flag") (1 bit) ("end"))
- (("spare") (7 bits) ("spare"))
- (cond "!ptr->end"
- (("number of parameters") (1 byte) ("nparams"))
- (("neg number") (2 bytes) ("neg"))))
-
-("dds" 0x4c
- (("start/end") (1 bit) ("end"))
- (("spare") (7 bits) ("spare"))
- (cond "!ptr->end"
- (("neg number") (2 bytes) ("neg"))))
-
-("dpt" 0x50
- (("neg number") (2 bytes) ("neg"))
- (("dunno") (1 byte) ("dunno")))
-
-("dse" 0x54
- (("neg number") (2 bytes) ("neg"))
- (("dunno") (1 byte) ("dunno")))
-
-("dot" 0x56
- (("unknown") (1 byte) ("unknown")))
-; FIXME: unknown field should be repeated symbol number?
-
-
-("dss" 0x42
- (("type") (1 byte) ("type"))
- (("external/internal") (1 bit) ("internal"))
- (("spare") (7 bits) ("spare"))
- (cond "!ptr->internal"
- ( ("package name") (chars variable byte) ("package")))
- (cond "ptr->internal"
- (("symbol id") (2 bytes) ("id")))
- (("record type") (2 bytes) ("record"))
- (("rules") (chars variable byte) ("rules"))
- (("number of symbols") (2 bytes) ("nsymbols"))
- (("unknown" ) (2 bytes) ("fixme")))
-
-("pss" 0x40
- (("negotiation number") (2 bytes) ("efn"))
- (("number of source files") (2 bytes) ("ns"))
- (repeat "ptr->ns"
- (("directory reference bit") (1 bit) ("drb"))
- (("spare") (7 bits) ("spare"))
- (("completed file name") (chars variable byte) ("fname"))
- (cond "ptr->drb[n]"
- (("directory apperance number") (2 bytes) ("dan"))))
-
- (("number of directories") (2 bytes) ("ndir"))
- (repeat "ptr->ndir"
- (("directory name") (chars variable bytes) ("dname"))))
-
-
-; FIXME: the tr block has no contents. sysinfo, etc. aren't prepared
-; to deal with that.
-; ("tr" 0x7f)
-
-
-("dus" 0x40
- (("negotiation number") (2 bytes) ("efn"))
- (("number of source files") (2 bytes) ("ns"))
- (repeat "ptr->ns"
- (("directory reference bit") (1 bit) ("drb"))
- (("spare") (7 bits) ("spare"))
- (("completed file name") (chars variable byte) ("fname"))
- (cond "ptr->drb[n]"
- (("directory apperance number") (2 bytes) ("dan"))))
- (("number of directories") (2 bytes) ("ndir"))
- (repeat "ptr->ndir"
- (("directory name") (chars variable bytes) ("dname"))))
-
-
-("dps" 0x32
- (("start/end flag") (1 bit) ("end"))
- (("block type") (7 bits) ("type")
- (("BLOCK_TYPE_COMPUNIT" "0")
- ("BLOCK_TYPE_PROCEDURE" "2")
- ("BLOCK_TYPE_FUNCTION" "3")
- ("BLOCK_TYPE_BLOCK" "4")
- ("BLOCK_TYPE_BASIC" "9")))
- (cond "!ptr->end"
- (("optimization") (1 byte) ("opt"))
- (("section number") (2 bytes) ("san"))
- (("address") (addrsize bytes) ("address"))
- (("block size") (addrsize bytes) ("block_size"))
- (("nesting") (1 byte) ("nesting"))
- (cond "ptr->type == BLOCK_TYPE_PROCEDURE
- || ptr->type == BLOCK_TYPE_FUNCTION"
- (("return address") (1 bit) ("retaddr"))
- (("interrupt function flag") (1 bit) ("intrflag"))
- (("stack update flag") (1 bit) ("stackflag"))
- (("intra page JMP") (1 bit) ("intrpagejmp"))
- (("spare") (4 bits) ("spare")))
- (("neg number") (2 bytes) ("neg"))))
-
+++ /dev/null
-This is configure.info, produced by makeinfo version 4.8 from
-.././etc/configure.texi.
-
-INFO-DIR-SECTION GNU admin
-START-INFO-DIR-ENTRY
-* configure: (configure). The GNU configure and build system
-END-INFO-DIR-ENTRY
-
- This file documents the GNU configure and build system.
-
- Copyright (C) 1998 Cygnus Solutions.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
-\1f
-File: configure.info, Node: Top, Next: Introduction, Up: (dir)
-
-GNU configure and build system
-******************************
-
-The GNU configure and build system.
-
-* Menu:
-
-* Introduction:: Introduction.
-* Getting Started:: Getting Started.
-* Files:: Files.
-* Configuration Names:: Configuration Names.
-* Cross Compilation Tools:: Cross Compilation Tools.
-* Canadian Cross:: Canadian Cross.
-* Cygnus Configure:: Cygnus Configure.
-* Multilibs:: Multilibs.
-* FAQ:: Frequently Asked Questions.
-* Index:: Index.
-
-\1f
-File: configure.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top
-
-1 Introduction
-**************
-
-This document describes the GNU configure and build systems. It
-describes how autoconf, automake, libtool, and make fit together. It
-also includes a discussion of the older Cygnus configure system.
-
- This document does not describe in detail how to use each of the
-tools; see the respective manuals for that. Instead, it describes
-which files the developer must write, which files are machine generated
-and how they are generated, and where certain common problems should be
-addressed.
-
- This document draws on several sources, including the autoconf
-manual by David MacKenzie (*note autoconf overview: (autoconf)Top.),
-the automake manual by David MacKenzie and Tom Tromey (*note automake
-overview: (automake)Top.), the libtool manual by Gordon Matzigkeit
-(*note libtool overview: (libtool)Top.), and the Cygnus configure
-manual by K. Richard Pixley.
-
-* Menu:
-
-* Goals:: Goals.
-* Tools:: The tools.
-* History:: History.
-* Building:: Building.
-
-\1f
-File: configure.info, Node: Goals, Next: Tools, Up: Introduction
-
-1.1 Goals
-=========
-
-The GNU configure and build system has two main goals.
-
- The first is to simplify the development of portable programs. The
-system permits the developer to concentrate on writing the program,
-simplifying many details of portability across Unix and even Windows
-systems, and permitting the developer to describe how to build the
-program using simple rules rather than complex Makefiles.
-
- The second is to simplify the building of programs distributed as
-source code. All programs are built using a simple, standardized, two
-step process. The program builder need not install any special tools in
-order to build the program.
-
-\1f
-File: configure.info, Node: Tools, Next: History, Prev: Goals, Up: Introduction
-
-1.2 Tools
-=========
-
-The GNU configure and build system is comprised of several different
-tools. Program developers must build and install all of these tools.
-
- People who just want to build programs from distributed sources
-normally do not need any special tools beyond a Unix shell, a make
-program, and a C compiler.
-
-autoconf
- provides a general portability framework, based on testing the
- features of the host system at build time.
-
-automake
- a system for describing how to build a program, permitting the
- developer to write a simplified `Makefile'.
-
-libtool
- a standardized approach to building shared libraries.
-
-gettext
- provides a framework for translation of text messages into other
- languages; not really discussed in this document.
-
-m4
- autoconf requires the GNU version of m4; the standard Unix m4 does
- not suffice.
-
-perl
- automake requires perl.
-
-\1f
-File: configure.info, Node: History, Next: Building, Prev: Tools, Up: Introduction
-
-1.3 History
-===========
-
-This is a very brief and probably inaccurate history.
-
- As the number of Unix variants increased during the 1980s, it became
-harder to write programs which could run on all variants. While it was
-often possible to use `#ifdef' to identify particular systems,
-developers frequently did not have access to every system, and the
-characteristics of some systems changed from version to version.
-
- By 1992, at least three different approaches had been developed:
- * The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael
- Manfredi.
-
- * The Cygnus configure script, by K. Richard Pixley, and the gcc
- configure script, by Richard Stallman. These use essentially the
- same approach, and the developers communicated regularly.
-
- * The autoconf program, by David MacKenzie.
-
- The Metaconfig program is still used for Perl and a few other
-programs. It is part of the Dist package. I do not know if it is
-being developed.
-
- In 1994, David MacKenzie and others modified autoconf to incorporate
-all the features of Cygnus configure. Since then, there has been a
-slow but steady conversion of GNU programs from Cygnus configure to
-autoconf. gcc has been converted, eliminating the gcc configure script.
-
- GNU autoconf was regularly maintained until late 1996. As of this
-writing in June, 1998, it has no public maintainer.
-
- Most programs are built using the make program, which requires the
-developer to write Makefiles describing how to build the programs.
-Since most programs are built in pretty much the same way, this led to a
-lot of duplication.
-
- The X Window system is built using the imake tool, which uses a
-database of rules to eliminate the duplication. However, building a
-tool which was developed using imake requires that the builder have
-imake installed, violating one of the goals of the GNU system.
-
- The new BSD make provides a standard library of Makefile fragments,
-which permits developers to write very simple Makefiles. However, this
-requires that the builder install the new BSD make program.
-
- In 1994, David MacKenzie wrote the first version of automake, which
-permitted writing a simple build description which was converted into a
-Makefile which could be used by the standard make program. In 1995, Tom
-Tromey completely rewrote automake in Perl, and he continues to enhance
-it.
-
- Various free packages built libraries, and by around 1995 several
-included support to build shared libraries on various platforms.
-However, there was no consistent approach. In early 1996, Gordon
-Matzigkeit began working on libtool, which provided a standardized
-approach to building shared libraries. This was integrated into
-automake from the start.
-
- The development of automake and libtool was driven by the GNITS
-project, a group of GNU maintainers who designed standardized tools to
-help meet the GNU coding standards.
-
-\1f
-File: configure.info, Node: Building, Prev: History, Up: Introduction
-
-1.4 Building
-============
-
-Most readers of this document should already know how to build a tool by
-running `configure' and `make'. This section may serve as a quick
-introduction or reminder.
-
- Building a tool is normally as simple as running `configure'
-followed by `make'. You should normally run `configure' from an empty
-directory, using some path to refer to the `configure' script in the
-source directory. The directory in which you run `configure' is called
-the "object directory".
-
- In order to use a object directory which is different from the source
-directory, you must be using the GNU version of `make', which has the
-required `VPATH' support. Despite this restriction, using a different
-object directory is highly recommended:
- * It keeps the files generated during the build from cluttering up
- your sources.
-
- * It permits you to remove the built files by simply removing the
- entire build directory.
-
- * It permits you to build from the same sources with several sets of
- configure options simultaneously.
-
- If you don't have GNU `make', you will have to run `configure' in
-the source directory. All GNU packages should support this; in
-particular, GNU packages should not assume the presence of GNU `make'.
-
- After running `configure', you can build the tools by running `make'.
-
- To install the tools, run `make install'. Installing the tools will
-copy the programs and any required support files to the "installation
-directory". The location of the installation directory is controlled
-by `configure' options, as described below.
-
- In the Cygnus tree at present, the info files are built and
-installed as a separate step. To build them, run `make info'. To
-install them, run `make install-info'. The equivalent html files are
-also built and installed in a separate step. To build the html files,
-run `make html'. To install the html files run `make install-html'.
-
- All `configure' scripts support a wide variety of options. The most
-interesting ones are `--with' and `--enable' options which are
-generally specific to particular tools. You can usually use the
-`--help' option to get a list of interesting options for a particular
-configure script.
-
- The only generic options you are likely to use are the `--prefix'
-and `--exec-prefix' options. These options are used to specify the
-installation directory.
-
- The directory named by the `--prefix' option will hold machine
-independent files such as info files.
-
- The directory named by the `--exec-prefix' option, which is normally
-a subdirectory of the `--prefix' directory, will hold machine dependent
-files such as executables.
-
- The default for `--prefix' is `/usr/local'. The default for
-`--exec-prefix' is the value used for `--prefix'.
-
- The convention used in Cygnus releases is to use a `--prefix' option
-of `/usr/cygnus/RELEASE', where RELEASE is the name of the release, and
-to use a `--exec-prefix' option of `/usr/cygnus/RELEASE/H-HOST', where
-HOST is the configuration name of the host system (*note Configuration
-Names::).
-
- Do not use either the source or the object directory as the
-installation directory. That will just lead to confusion.
-
-\1f
-File: configure.info, Node: Getting Started, Next: Files, Prev: Introduction, Up: Top
-
-2 Getting Started
-*****************
-
-To start using the GNU configure and build system with your software
-package, you must write three files, and you must run some tools to
-manually generate additional files.
-
-* Menu:
-
-* Write configure.in:: Write configure.in.
-* Write Makefile.am:: Write Makefile.am.
-* Write acconfig.h:: Write acconfig.h.
-* Generate files:: Generate files.
-* Getting Started Example:: Example.
-
-\1f
-File: configure.info, Node: Write configure.in, Next: Write Makefile.am, Up: Getting Started
-
-2.1 Write configure.in
-======================
-
-You must first write the file `configure.in'. This is an autoconf
-input file, and the autoconf manual describes in detail what this file
-should look like.
-
- You will write tests in your `configure.in' file to check for
-conditions that may change from one system to another, such as the
-presence of particular header files or functions.
-
- For example, not all systems support the `gettimeofday' function.
-If you want to use the `gettimeofday' function when it is available,
-and to use some other function when it is not, you would check for this
-by putting `AC_CHECK_FUNCS(gettimeofday)' in `configure.in'.
-
- When the configure script is run at build time, this will arrange to
-define the preprocessor macro `HAVE_GETTIMEOFDAY' to the value 1 if the
-`gettimeofday' function is available, and to not define the macro at
-all if the function is not available. Your code can then use `#ifdef'
-to test whether it is safe to call `gettimeofday'.
-
- If you have an existing body of code, the `autoscan' program may
-help identify potential portability problems, and hence configure tests
-that you will want to use. *Note Invoking autoscan: (autoconf)Invoking
-autoscan.
-
- Another handy tool for an existing body of code is `ifnames'. This
-will show you all the preprocessor conditionals that the code already
-uses. *Note Invoking ifnames: (autoconf)Invoking ifnames.
-
- Besides the portability tests which are specific to your particular
-package, every `configure.in' file should contain the following macros.
-
-`AC_INIT'
- This macro takes a single argument, which is the name of a file in
- your package. For example, `AC_INIT(foo.c)'.
-
-`AC_PREREQ(VERSION)'
- This macro is optional. It may be used to indicate the version of
- `autoconf' that you are using. This will prevent users from
- running an earlier version of `autoconf' and perhaps getting an
- invalid `configure' script. For example, `AC_PREREQ(2.12)'.
-
-`AM_INIT_AUTOMAKE'
- This macro takes two arguments: the name of the package, and a
- version number. For example, `AM_INIT_AUTOMAKE(foo, 1.0)'. (This
- macro is not needed if you are not using automake).
-
-`AM_CONFIG_HEADER'
- This macro names the header file which will hold the preprocessor
- macro definitions at run time. Normally this should be
- `config.h'. Your sources would then use `#include "config.h"' to
- include it.
-
- This macro may optionally name the input file for that header
- file; by default, this is `config.h.in', but that file name works
- poorly on DOS filesystems. Therefore, it is often better to name
- it explicitly as `config.in'.
-
- This is what you should normally put in `configure.in':
- AM_CONFIG_HEADER(config.h:config.in)
-
- (If you are not using automake, use `AC_CONFIG_HEADER' rather than
- `AM_CONFIG_HEADER').
-
-`AM_MAINTAINER_MODE'
- This macro always appears in Cygnus configure scripts. Other
- programs may or may not use it.
-
- If this macro is used, the `--enable-maintainer-mode' option is
- required to enable automatic rebuilding of generated files used by
- the configure system. This of course requires that developers be
- aware of, and use, that option.
-
- If this macro is not used, then the generated files will always be
- rebuilt automatically. This will cause problems if the wrong
- versions of autoconf, automake, or others are in the builder's
- `PATH'.
-
- (If you are not using automake, you do not need to use this macro).
-
-`AC_EXEEXT'
- Either this macro or `AM_EXEEXT' always appears in Cygnus configure
- files. Other programs may or may not use one of them.
-
- This macro looks for the executable suffix used on the host
- system. On Unix systems, this is the empty string. On Windows
- systems, this is `.exe'. This macro directs automake to use the
- executable suffix as appropriate when creating programs. This
- macro does not take any arguments.
-
- The `AC_EXEEXT' form is new, and is part of a Cygnus patch to
- autoconf to support compiling with Visual C++. Older programs use
- `AM_EXEEXT' instead.
-
- (Programs which do not use automake use neither `AC_EXEEXT' nor
- `AM_EXEEXT').
-
-`AC_PROG_CC'
- If you are writing C code, you will normally want to use this
- macro. It locates the C compiler to use. It does not take any
- arguments.
-
- However, if this `configure.in' file is for a library which is to
- be compiled by a cross compiler which may not fully work, then you
- will not want to use `AC_PROG_CC'. Instead, you will want to use a
- variant which does not call the macro `AC_PROG_CC_WORKS'. Examples
- can be found in various `configure.in' files for libraries that are
- compiled with cross compilers, such as libiberty or libgloss.
- This is essentially a bug in autoconf, and there will probably be
- a better workaround at some point.
-
-`AC_PROG_CXX'
- If you are writing C++ code, you will want to use this macro. It
- locates the C++ compiler to use. It does not take any arguments.
- The same cross compiler comments apply as for `AC_PROG_CC'.
-
-`AM_PROG_LIBTOOL'
- If you want to build libraries, and you want to permit them to be
- shared, or you want to link against libraries which were built
- using libtool, then you will need this macro. This macro is
- required in order to use libtool.
-
- By default, this will cause all libraries to be built as shared
- libraries. To prevent this-to change the default-use
- `AM_DISABLE_SHARED' before `AM_PROG_LIBTOOL'. The configure
- options `--enable-shared' and `--disable-shared' may be used to
- override the default at build time.
-
-`AC_DEFINE(_GNU_SOURCE)'
- GNU packages should normally include this line before any other
- feature tests. This defines the macro `_GNU_SOURCE' when
- compiling, which directs the libc header files to provide the
- standard GNU system interfaces including all GNU extensions. If
- this macro is not defined, certain GNU extensions may not be
- available.
-
-`AC_OUTPUT'
- This macro takes a list of file names which the configure process
- should produce. This is normally a list of one or more `Makefile'
- files in different directories. If your package lives entirely in
- a single directory, you would use simply `AC_OUTPUT(Makefile)'.
- If you also have, for example, a `lib' subdirectory, you would use
- `AC_OUTPUT(Makefile lib/Makefile)'.
-
- If you want to use locally defined macros in your `configure.in'
-file, then you will need to write a `acinclude.m4' file which defines
-them (if not using automake, this file is called `aclocal.m4').
-Alternatively, you can put separate macros in an `m4' subdirectory, and
-put `ACLOCAL_AMFLAGS = -I m4' in your `Makefile.am' file so that the
-`aclocal' program will be able to find them.
-
- The different macro prefixes indicate which tool defines the macro.
-Macros which start with `AC_' are part of autoconf. Macros which start
-with `AM_' are provided by automake or libtool.
-
-\1f
-File: configure.info, Node: Write Makefile.am, Next: Write acconfig.h, Prev: Write configure.in, Up: Getting Started
-
-2.2 Write Makefile.am
-=====================
-
-You must write the file `Makefile.am'. This is an automake input file,
-and the automake manual describes in detail what this file should look
-like.
-
- The automake commands in `Makefile.am' mostly look like variable
-assignments in a `Makefile'. automake recognizes special variable
-names, and automatically add make rules to the output as needed.
-
- There will be one `Makefile.am' file for each directory in your
-package. For each directory with subdirectories, the `Makefile.am'
-file should contain the line
- SUBDIRS = DIR DIR ...
- where each DIR is the name of a subdirectory.
-
- For each `Makefile.am', there should be a corresponding `Makefile'
-in the `AC_OUTPUT' macro in `configure.in'.
-
- Every `Makefile.am' written at Cygnus should contain the line
- AUTOMAKE_OPTIONS = cygnus
- This puts automake into Cygnus mode. See the automake manual for
-details.
-
- You may to include the version number of `automake' that you are
-using on the `AUTOMAKE_OPTIONS' line. For example,
- AUTOMAKE_OPTIONS = cygnus 1.3
- This will prevent users from running an earlier version of
-`automake' and perhaps getting an invalid `Makefile.in'.
-
- If your package builds a program, then in the directory where that
-program is built you will normally want a line like
- bin_PROGRAMS = PROGRAM
- where PROGRAM is the name of the program. You will then want a line
-like
- PROGRAM_SOURCES = FILE FILE ...
- where each FILE is the name of a source file to link into the
-program (e.g., `foo.c').
-
- If your package builds a library, and you do not want the library to
-ever be built as a shared library, then in the directory where that
-library is built you will normally want a line like
- lib_LIBRARIES = libNAME.a
- where `libNAME.a' is the name of the library. You will then want a
-line like
- libNAME_a_SOURCES = FILE FILE ...
- where each FILE is the name of a source file to add to the library.
-
- If your package builds a library, and you want to permit building the
-library as a shared library, then in the directory where that library is
-built you will normally want a line like
- lib_LTLIBRARIES = libNAME.la
- The use of `LTLIBRARIES', and the `.la' extension, indicate a
-library to be built using libtool. As usual, you will then want a line
-like
- libNAME_la_SOURCES = FILE FILE ...
-
- The strings `bin' and `lib' that appear above in `bin_PROGRAMS' and
-`lib_LIBRARIES' are not arbitrary. They refer to particular
-directories, which may be set by the `--bindir' and `--libdir' options
-to `configure'. If those options are not used, the default values are
-based on the `--prefix' or `--exec-prefix' options to `configure'. It
-is possible to use other names if the program or library should be
-installed in some other directory.
-
- The `Makefile.am' file may also contain almost anything that may
-appear in a normal `Makefile'. automake also supports many other
-special variables, as well as conditionals.
-
- See the automake manual for more information.
-
-\1f
-File: configure.info, Node: Write acconfig.h, Next: Generate files, Prev: Write Makefile.am, Up: Getting Started
-
-2.3 Write acconfig.h
-====================
-
-If you are generating a portability header file, (i.e., you are using
-`AM_CONFIG_HEADER' in `configure.in'), then you will have to write a
-`acconfig.h' file. It will have to contain the following lines.
-
- /* Name of package. */
- #undef PACKAGE
-
- /* Version of package. */
- #undef VERSION
-
- This requirement is really a bug in the system, and the requirement
-may be eliminated at some later date.
-
- The `acconfig.h' file will also similar comment and `#undef' lines
-for any unusual macros in the `configure.in' file, including any macro
-which appears in a `AC_DEFINE' macro.
-
- In particular, if you are writing a GNU package and therefore include
-`AC_DEFINE(_GNU_SOURCE)' in `configure.in' as suggested above, you will
-need lines like this in `acconfig.h':
- /* Enable GNU extensions. */
- #undef _GNU_SOURCE
-
- Normally the `autoheader' program will inform you of any such
-requirements by printing an error message when it is run. However, if
-you do anything particular odd in your `configure.in' file, you will
-have to make sure that the right entries appear in `acconfig.h', since
-otherwise the results of the tests may not be available in the
-`config.h' file which your code will use.
-
- (Thee `PACKAGE' and `VERSION' lines are not required if you are not
-using automake, and in that case you may not need a `acconfig.h' file
-at all).
-
-\1f
-File: configure.info, Node: Generate files, Next: Getting Started Example, Prev: Write acconfig.h, Up: Getting Started
-
-2.4 Generate files
-==================
-
-Once you have written `configure.in', `Makefile.am', `acconfig.h', and
-possibly `acinclude.m4', you must use autoconf and automake programs to
-produce the first versions of the generated files. This is done by
-executing the following sequence of commands.
-
- aclocal
- autoconf
- autoheader
- automake
-
- The `aclocal' and `automake' commands are part of the automake
-package, and the `autoconf' and `autoheader' commands are part of the
-autoconf package.
-
- If you are using a `m4' subdirectory for your macros, you will need
-to use the `-I m4' option when you run `aclocal'.
-
- If you are not using the Cygnus tree, use the `-a' option when
-running `automake' command in order to copy the required support files
-into your source directory.
-
- If you are using libtool, you must build and install the libtool
-package with the same `--prefix' and `--exec-prefix' options as you
-used with the autoconf and automake packages. You must do this before
-running any of the above commands. If you are not using the Cygnus
-tree, you will need to run the `libtoolize' program to copy the libtool
-support files into your directory.
-
- Once you have managed to run these commands without getting any
-errors, you should create a new empty directory, and run the `configure'
-script which will have been created by `autoconf' with the
-`--enable-maintainer-mode' option. This will give you a set of
-Makefiles which will include rules to automatically rebuild all the
-generated files.
-
- After doing that, whenever you have changed some of the input files
-and want to regenerated the other files, go to your object directory
-and run `make'. Doing this is more reliable than trying to rebuild the
-files manually, because there are complex order dependencies and it is
-easy to forget something.
-
-\1f
-File: configure.info, Node: Getting Started Example, Prev: Generate files, Up: Getting Started
-
-2.5 Example
-===========
-
-Let's consider a trivial example.
-
- Suppose we want to write a simple version of `touch'. Our program,
-which we will call `poke', will take a single file name argument, and
-use the `utime' system call to set the modification and access times of
-the file to the current time. We want this program to be highly
-portable.
-
- We'll first see what this looks like without using autoconf and
-automake, and then see what it looks like with them.
-
-* Menu:
-
-* Getting Started Example 1:: First Try.
-* Getting Started Example 2:: Second Try.
-* Getting Started Example 3:: Third Try.
-* Generate Files in Example:: Generate Files.
-
-\1f
-File: configure.info, Node: Getting Started Example 1, Next: Getting Started Example 2, Up: Getting Started Example
-
-2.5.1 First Try
----------------
-
-Here is our first try at `poke.c'. Note that we've written it without
-ANSI/ISO C prototypes, since we want it to be highly portable.
-
- #include <stdio.h>
- #include <stdlib.h>
- #include <sys/types.h>
- #include <utime.h>
-
- int
- main (argc, argv)
- int argc;
- char **argv;
- {
- if (argc != 2)
- {
- fprintf (stderr, "Usage: poke file\n");
- exit (1);
- }
-
- if (utime (argv[1], NULL) < 0)
- {
- perror ("utime");
- exit (1);
- }
-
- exit (0);
- }
-
- We also write a simple `Makefile'.
-
- CC = gcc
- CFLAGS = -g -O2
-
- all: poke
-
- poke: poke.o
- $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o
-
- So far, so good.
-
- Unfortunately, there are a few problems.
-
- On older Unix systems derived from BSD 4.3, the `utime' system call
-does not accept a second argument of `NULL'. On those systems, we need
-to pass a pointer to `struct utimbuf' structure. Unfortunately, even
-older systems don't define that structure; on those systems, we need to
-pass an array of two `long' values.
-
- The header file `stdlib.h' was invented by ANSI C, and older systems
-don't have a copy. We included it above to get a declaration of `exit'.
-
- We can find some of these portability problems by running
-`autoscan', which will create a `configure.scan' file which we can use
-as a prototype for our `configure.in' file. I won't show the output,
-but it will notice the potential problems with `utime' and `stdlib.h'.
-
- In our `Makefile', we don't provide any way to install the program.
-This doesn't matter much for such a simple example, but a real program
-will need an `install' target. For that matter, we will also want a
-`clean' target.
-
-\1f
-File: configure.info, Node: Getting Started Example 2, Next: Getting Started Example 3, Prev: Getting Started Example 1, Up: Getting Started Example
-
-2.5.2 Second Try
-----------------
-
-Here is our second try at this program.
-
- We modify `poke.c' to use preprocessor macros to control what
-features are available. (I've cheated a bit by using the same macro
-names which autoconf will use).
-
- #include <stdio.h>
-
- #ifdef STDC_HEADERS
- #include <stdlib.h>
- #endif
-
- #include <sys/types.h>
-
- #ifdef HAVE_UTIME_H
- #include <utime.h>
- #endif
-
- #ifndef HAVE_UTIME_NULL
-
- #include <time.h>
-
- #ifndef HAVE_STRUCT_UTIMBUF
-
- struct utimbuf
- {
- long actime;
- long modtime;
- };
-
- #endif
-
- static int
- utime_now (file)
- char *file;
- {
- struct utimbuf now;
-
- now.actime = now.modtime = time (NULL);
- return utime (file, &now);
- }
-
- #define utime(f, p) utime_now (f)
-
- #endif /* HAVE_UTIME_NULL */
-
- int
- main (argc, argv)
- int argc;
- char **argv;
- {
- if (argc != 2)
- {
- fprintf (stderr, "Usage: poke file\n");
- exit (1);
- }
-
- if (utime (argv[1], NULL) < 0)
- {
- perror ("utime");
- exit (1);
- }
-
- exit (0);
- }
-
- Here is the associated `Makefile'. We've added support for the
-preprocessor flags we use. We've also added `install' and `clean'
-targets.
-
- # Set this to your installation directory.
- bindir = /usr/local/bin
-
- # Uncomment this if you have the standard ANSI/ISO C header files.
- # STDC_HDRS = -DSTDC_HEADERS
-
- # Uncomment this if you have utime.h.
- # UTIME_H = -DHAVE_UTIME_H
-
- # Uncomment this if utime (FILE, NULL) works on your system.
- # UTIME_NULL = -DHAVE_UTIME_NULL
-
- # Uncomment this if struct utimbuf is defined in utime.h.
- # UTIMBUF = -DHAVE_STRUCT_UTIMBUF
-
- CC = gcc
- CFLAGS = -g -O2
-
- ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS)
-
- all: poke
-
- poke: poke.o
- $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o
-
- .c.o:
- $(CC) -c $(ALL_CFLAGS) poke.c
-
- install: poke
- cp poke $(bindir)/poke
-
- clean:
- rm poke poke.o
-
- Some problems with this approach should be clear.
-
- Users who want to compile poke will have to know how `utime' works
-on their systems, so that they can uncomment the `Makefile' correctly.
-
- The installation is done using `cp', but many systems have an
-`install' program which may be used, and which supports optional
-features such as stripping debugging information out of the installed
-binary.
-
- The use of `Makefile' variables like `CC', `CFLAGS' and `LDFLAGS'
-follows the requirements of the GNU standards. This is convenient for
-all packages, since it reduces surprises for users. However, it is
-easy to get the details wrong, and wind up with a slightly nonstandard
-distribution.
-
-\1f
-File: configure.info, Node: Getting Started Example 3, Next: Generate Files in Example, Prev: Getting Started Example 2, Up: Getting Started Example
-
-2.5.3 Third Try
----------------
-
-For our third try at this program, we will write a `configure.in'
-script to discover the configuration features on the host system, rather
-than requiring the user to edit the `Makefile'. We will also write a
-`Makefile.am' rather than a `Makefile'.
-
- The only change to `poke.c' is to add a line at the start of the
-file:
- #include "config.h"
-
- The new `configure.in' file is as follows.
-
- AC_INIT(poke.c)
- AM_INIT_AUTOMAKE(poke, 1.0)
- AM_CONFIG_HEADER(config.h:config.in)
- AC_PROG_CC
- AC_HEADER_STDC
- AC_CHECK_HEADERS(utime.h)
- AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF))
- AC_FUNC_UTIME_NULL
- AC_OUTPUT(Makefile)
-
- The first four macros in this file, and the last one, were described
-above; see *Note Write configure.in::. If we omit these macros, then
-when we run `automake' we will get a reminder that we need them.
-
- The other macros are standard autoconf macros.
-
-`AC_HEADER_STDC'
- Check for standard C headers.
-
-`AC_CHECK_HEADERS'
- Check whether a particular header file exists.
-
-`AC_EGREP_HEADER'
- Check for a particular string in a particular header file, in this
- case checking for `utimbuf' in `utime.h'.
-
-`AC_FUNC_UTIME_NULL'
- Check whether `utime' accepts a NULL second argument to set the
- file change time to the current time.
-
- See the autoconf manual for a more complete description.
-
- The new `Makefile.am' file is as follows. Note how simple this is
-compared to our earlier `Makefile'.
-
- bin_PROGRAMS = poke
-
- poke_SOURCES = poke.c
-
- This means that we should build a single program name `poke'. It
-should be installed in the binary directory, which we called `bindir'
-earlier. The program `poke' is built from the source file `poke.c'.
-
- We must also write a `acconfig.h' file. Besides `PACKAGE' and
-`VERSION', which must be mentioned for all packages which use automake,
-we must include `HAVE_STRUCT_UTIMBUF', since we mentioned it in an
-`AC_DEFINE'.
-
- /* Name of package. */
- #undef PACKAGE
-
- /* Version of package. */
- #undef VERSION
-
- /* Whether utime.h defines struct utimbuf. */
- #undef HAVE_STRUCT_UTIMBUF
-
-\1f
-File: configure.info, Node: Generate Files in Example, Prev: Getting Started Example 3, Up: Getting Started Example
-
-2.5.4 Generate Files
---------------------
-
-We must now generate the other files, using the following commands.
-
- aclocal
- autoconf
- autoheader
- automake
-
- When we run `autoheader', it will remind us of any macros we forgot
-to add to `acconfig.h'.
-
- When we run `automake', it will want to add some files to our
-distribution. It will add them automatically if we use the
-`--add-missing' option.
-
- By default, `automake' will run in GNU mode, which means that it
-will want us to create certain additional files; as of this writing, it
-will want `NEWS', `README', `AUTHORS', and `ChangeLog', all of which
-are files which should appear in a standard GNU distribution. We can
-either add those files, or run `automake' with the `--foreign' option.
-
- Running these tools will generate the following files, all of which
-are described in the next chapter.
-
- * `aclocal.m4'
-
- * `configure'
-
- * `config.in'
-
- * `Makefile.in'
-
- * `stamp-h.in'
-
-\1f
-File: configure.info, Node: Files, Next: Configuration Names, Prev: Getting Started, Up: Top
-
-3 Files
-*******
-
-As was seen in the previous chapter, the GNU configure and build system
-uses a number of different files. The developer must write a few files.
-The others are generated by various tools.
-
- The system is rather flexible, and can be used in many different
-ways. In describing the files that it uses, I will describe the common
-case, and mention some other cases that may arise.
-
-* Menu:
-
-* Developer Files:: Developer Files.
-* Build Files:: Build Files.
-* Support Files:: Support Files.
-
-\1f
-File: configure.info, Node: Developer Files, Next: Build Files, Up: Files
-
-3.1 Developer Files
-===================
-
-This section describes the files written or generated by the developer
-of a package.
-
-* Menu:
-
-* Developer Files Picture:: Developer Files Picture.
-* Written Developer Files:: Written Developer Files.
-* Generated Developer Files:: Generated Developer Files.
-
-\1f
-File: configure.info, Node: Developer Files Picture, Next: Written Developer Files, Up: Developer Files
-
-3.1.1 Developer Files Picture
------------------------------
-
-Here is a picture of the files which are written by the developer, the
-generated files which would be included with a complete source
-distribution, and the tools which create those files. The file names
-are plain text and the tool names are enclosed by `*' characters (e.g.,
-`autoheader' is the name of a tool, not the name of a file).
-
- acconfig.h configure.in Makefile.am
- | | |
- | --------------+---------------------- |
- | | | | |
- v v | acinclude.m4 | |
- *autoheader* | | v v
- | | v --->*automake*
- v |--->*aclocal* | |
- config.in | | | v
- | v | Makefile.in
- | aclocal.m4---
- | |
- v v
- *autoconf*
- |
- v
- configure
-
-\1f
-File: configure.info, Node: Written Developer Files, Next: Generated Developer Files, Prev: Developer Files Picture, Up: Developer Files
-
-3.1.2 Written Developer Files
------------------------------
-
-The following files would be written by the developer.
-
-`configure.in'
- This is the configuration script. This script contains
- invocations of autoconf macros. It may also contain ordinary
- shell script code. This file will contain feature tests for
- portability issues. The last thing in the file will normally be
- an `AC_OUTPUT' macro listing which files to create when the
- builder runs the configure script. This file is always required
- when using the GNU configure system. *Note Write configure.in::.
-
-`Makefile.am'
- This is the automake input file. It describes how the code should
- be built. It consists of definitions of automake variables. It
- may also contain ordinary Makefile targets. This file is only
- needed when using automake (newer tools normally use automake, but
- there are still older tools which have not been converted, in
- which the developer writes `Makefile.in' directly). *Note Write
- Makefile.am::.
-
-`acconfig.h'
- When the configure script creates a portability header file, by
- using `AM_CONFIG_HEADER' (or, if not using automake,
- `AC_CONFIG_HEADER'), this file is used to describe macros which are
- not recognized by the `autoheader' command. This is normally a
- fairly uninteresting file, consisting of a collection of `#undef'
- lines with comments. Normally any call to `AC_DEFINE' in
- `configure.in' will require a line in this file. *Note Write
- acconfig.h::.
-
-`acinclude.m4'
- This file is not always required. It defines local autoconf
- macros. These macros may then be used in `configure.in'. If you
- don't need any local autoconf macros, then you don't need this
- file at all. In fact, in general, you never need local autoconf
- macros, since you can put everything in `configure.in', but
- sometimes a local macro is convenient.
-
- Newer tools may omit `acinclude.m4', and instead use a
- subdirectory, typically named `m4', and define `ACLOCAL_AMFLAGS =
- -I m4' in `Makefile.am' to force `aclocal' to look there for macro
- definitions. The macro definitions are then placed in separate
- files in that directory.
-
- The `acinclude.m4' file is only used when using automake; in older
- tools, the developer writes `aclocal.m4' directly, if it is needed.
-
-\1f
-File: configure.info, Node: Generated Developer Files, Prev: Written Developer Files, Up: Developer Files
-
-3.1.3 Generated Developer Files
--------------------------------
-
-The following files would be generated by the developer.
-
- When using automake, these files are normally not generated manually
-after the first time. Instead, the generated `Makefile' contains rules
-to automatically rebuild the files as required. When
-`AM_MAINTAINER_MODE' is used in `configure.in' (the normal case in
-Cygnus code), the automatic rebuilding rules will only be defined if
-you configure using the `--enable-maintainer-mode' option.
-
- When using automatic rebuilding, it is important to ensure that all
-the various tools have been built and installed on your `PATH'. Using
-automatic rebuilding is highly recommended, so much so that I'm not
-going to explain what you have to do if you don't use it.
-
-`configure'
- This is the configure script which will be run when building the
- package. This is generated by `autoconf' from `configure.in' and
- `aclocal.m4'. This is a shell script.
-
-`Makefile.in'
- This is the file which the configure script will turn into the
- `Makefile' at build time. This file is generated by `automake'
- from `Makefile.am'. If you aren't using automake, you must write
- this file yourself. This file is pretty much a normal `Makefile',
- with some configure substitutions for certain variables.
-
-`aclocal.m4'
- This file is created by the `aclocal' program, based on the
- contents of `configure.in' and `acinclude.m4' (or, as noted in the
- description of `acinclude.m4' above, on the contents of an `m4'
- subdirectory). This file contains definitions of autoconf macros
- which `autoconf' will use when generating the file `configure'.
- These autoconf macros may be defined by you in `acinclude.m4' or
- they may be defined by other packages such as automake, libtool or
- gettext. If you aren't using automake, you will normally write
- this file yourself; in that case, if `configure.in' uses only
- standard autoconf macros, this file will not be needed at all.
-
-`config.in'
- This file is created by `autoheader' based on `acconfig.h' and
- `configure.in'. At build time, the configure script will define
- some of the macros in it to create `config.h', which may then be
- included by your program. This permits your C code to use
- preprocessor conditionals to change its behaviour based on the
- characteristics of the host system. This file may also be called
- `config.h.in'.
-
-`stamp.h-in'
- This rather uninteresting file, which I omitted from the picture,
- is generated by `automake'. It always contains the string
- `timestamp'. It is used as a timestamp file indicating whether
- `config.in' is up to date. Using a timestamp file means that
- `config.in' can be marked as up to date without actually changing
- its modification time. This is useful since `config.in' depends
- upon `configure.in', but it is easy to change `configure.in' in a
- way which does not affect `config.in'.
-
-\1f
-File: configure.info, Node: Build Files, Next: Support Files, Prev: Developer Files, Up: Files
-
-3.2 Build Files
-===============
-
-This section describes the files which are created at configure and
-build time. These are the files which somebody who builds the package
-will see.
-
- Of course, the developer will also build the package. The
-distinction between developer files and build files is not that the
-developer does not see the build files, but that somebody who only
-builds the package does not have to worry about the developer files.
-
-* Menu:
-
-* Build Files Picture:: Build Files Picture.
-* Build Files Description:: Build Files Description.
-
-\1f
-File: configure.info, Node: Build Files Picture, Next: Build Files Description, Up: Build Files
-
-3.2.1 Build Files Picture
--------------------------
-
-Here is a picture of the files which will be created at build time.
-`config.status' is both a created file and a shell script which is run
-to create other files, and the picture attempts to show that.
-
- config.in *configure* Makefile.in
- | | |
- | v |
- | config.status |
- | | |
- *config.status*<======+==========>*config.status*
- | |
- v v
- config.h Makefile
-
-\1f
-File: configure.info, Node: Build Files Description, Prev: Build Files Picture, Up: Build Files
-
-3.2.2 Build Files Description
------------------------------
-
-This is a description of the files which are created at build time.
-
-`config.status'
- The first step in building a package is to run the `configure'
- script. The `configure' script will create the file
- `config.status', which is itself a shell script. When you first
- run `configure', it will automatically run `config.status'. An
- `Makefile' derived from an automake generated `Makefile.in' will
- contain rules to automatically run `config.status' again when
- necessary to recreate certain files if their inputs change.
-
-`Makefile'
- This is the file which make will read to build the program. The
- `config.status' script will transform `Makefile.in' into
- `Makefile'.
-
-`config.h'
- This file defines C preprocessor macros which C code can use to
- adjust its behaviour on different systems. The `config.status'
- script will transform `config.in' into `config.h'.
-
-`config.cache'
- This file did not fit neatly into the picture, and I omitted it.
- It is used by the `configure' script to cache results between
- runs. This can be an important speedup. If you modify
- `configure.in' in such a way that the results of old tests should
- change (perhaps you have added a new library to `LDFLAGS'), then
- you will have to remove `config.cache' to force the tests to be
- rerun.
-
- The autoconf manual explains how to set up a site specific cache
- file. This can speed up running `configure' scripts on your
- system.
-
-`stamp.h'
- This file, which I omitted from the picture, is similar to
- `stamp-h.in'. It is used as a timestamp file indicating whether
- `config.h' is up to date. This is useful since `config.h' depends
- upon `config.status', but it is easy for `config.status' to change
- in a way which does not affect `config.h'.
-
-\1f
-File: configure.info, Node: Support Files, Prev: Build Files, Up: Files
-
-3.3 Support Files
-=================
-
-The GNU configure and build system requires several support files to be
-included with your distribution. You do not normally need to concern
-yourself with these. If you are using the Cygnus tree, most are already
-present. Otherwise, they will be installed with your source by
-`automake' (with the `--add-missing' option) and `libtoolize'.
-
- You don't have to put the support files in the top level directory.
-You can put them in a subdirectory, and use the `AC_CONFIG_AUX_DIR'
-macro in `configure.in' to tell `automake' and the `configure' script
-where they are.
-
- In this section, I describe the support files, so that you can know
-what they are and why they are there.
-
-`ABOUT-NLS'
- Added by automake if you are using gettext. This is a
- documentation file about the gettext project.
-
-`ansi2knr.c'
- Used by an automake generated `Makefile' if you put `ansi2knr' in
- `AUTOMAKE_OPTIONS' in `Makefile.am'. This permits compiling ANSI
- C code with a K&R C compiler.
-
-`ansi2knr.1'
- The man page which goes with `ansi2knr.c'.
-
-`config.guess'
- A shell script which determines the configuration name for the
- system on which it is run.
-
-`config.sub'
- A shell script which canonicalizes a configuration name entered by
- a user.
-
-`elisp-comp'
- Used to compile Emacs LISP files.
-
-`install-sh'
- A shell script which installs a program. This is used if the
- configure script can not find an install binary.
-
-`ltconfig'
- Used by libtool. This is a shell script which configures libtool
- for the particular system on which it is used.
-
-`ltmain.sh'
- Used by libtool. This is the actual libtool script which is used,
- after it is configured by `ltconfig' to build a library.
-
-`mdate-sh'
- A shell script used by an automake generated `Makefile' to pretty
- print the modification time of a file. This is used to maintain
- version numbers for texinfo files.
-
-`missing'
- A shell script used if some tool is missing entirely. This is
- used by an automake generated `Makefile' to avoid certain sorts of
- timestamp problems.
-
-`mkinstalldirs'
- A shell script which creates a directory, including all parent
- directories. This is used by an automake generated `Makefile'
- during installation.
-
-`texinfo.tex'
- Required if you have any texinfo files. This is used when
- converting Texinfo files into DVI using `texi2dvi' and TeX.
-
-`ylwrap'
- A shell script used by an automake generated `Makefile' to run
- programs like `bison', `yacc', `flex', and `lex'. These programs
- default to producing output files with a fixed name, and the
- `ylwrap' script runs them in a subdirectory to avoid file name
- conflicts when using a parallel make program.
-
-\1f
-File: configure.info, Node: Configuration Names, Next: Cross Compilation Tools, Prev: Files, Up: Top
-
-4 Configuration Names
-*********************
-
-The GNU configure system names all systems using a "configuration
-name". All such names used to be triplets (they may now contain four
-parts in certain cases), and the term "configuration triplet" is still
-seen.
-
-* Menu:
-
-* Configuration Name Definition:: Configuration Name Definition.
-* Using Configuration Names:: Using Configuration Names.
-
-\1f
-File: configure.info, Node: Configuration Name Definition, Next: Using Configuration Names, Up: Configuration Names
-
-4.1 Configuration Name Definition
-=================================
-
-This is a string of the form CPU-MANUFACTURER-OPERATING_SYSTEM. In
-some cases, this is extended to a four part form:
-CPU-MANUFACTURER-KERNEL-OPERATING_SYSTEM.
-
- When using a configuration name in a configure option, it is normally
-not necessary to specify an entire name. In particular, the
-MANUFACTURER field is often omitted, leading to strings such as
-`i386-linux' or `sparc-sunos'. The shell script `config.sub' will
-translate these shortened strings into the canonical form. autoconf
-will arrange for `config.sub' to be run automatically when it is needed.
-
- The fields of a configuration name are as follows:
-
-CPU
- The type of processor. This is typically something like `i386' or
- `sparc'. More specific variants are used as well, such as
- `mipsel' to indicate a little endian MIPS processor.
-
-MANUFACTURER
- A somewhat freeform field which indicates the manufacturer of the
- system. This is often simply `unknown'. Other common strings are
- `pc' for an IBM PC compatible system, or the name of a workstation
- vendor, such as `sun'.
-
-OPERATING_SYSTEM
- The name of the operating system which is run on the system. This
- will be something like `solaris2.5' or `irix6.3'. There is no
- particular restriction on the version number, and strings like
- `aix4.1.4.0' are seen. For an embedded system, which has no
- operating system, this field normally indicates the type of object
- file format, such as `elf' or `coff'.
-
-KERNEL
- This is used mainly for GNU/Linux. A typical GNU/Linux
- configuration name is `i586-pc-linux-gnulibc1'. In this case the
- kernel, `linux', is separated from the operating system,
- `gnulibc1'.
-
- The shell script `config.guess' will normally print the correct
-configuration name for the system on which it is run. It does by
-running `uname' and by examining other characteristics of the system.
-
- Because `config.guess' can normally determine the configuration name
-for a machine, it is normally only necessary to specify a configuration
-name when building a cross-compiler or when building using a
-cross-compiler.
-
-\1f
-File: configure.info, Node: Using Configuration Names, Prev: Configuration Name Definition, Up: Configuration Names
-
-4.2 Using Configuration Names
-=============================
-
-A configure script will sometimes have to make a decision based on a
-configuration name. You will need to do this if you have to compile
-code differently based on something which can not be tested using a
-standard autoconf feature test.
-
- It is normally better to test for particular features, rather than to
-test for a particular system. This is because as Unix evolves,
-different systems copy features from one another. Even if you need to
-determine whether the feature is supported based on a configuration
-name, you should define a macro which describes the feature, rather than
-defining a macro which describes the particular system you are on.
-
- Testing for a particular system is normally done using a case
-statement in `configure.in'. The case statement might look something
-like the following, assuming that `host' is a shell variable holding a
-canonical configuration name (which will be the case if `configure.in'
-uses the `AC_CANONICAL_HOST' or `AC_CANONICAL_SYSTEM' macro).
-
- case "${host}" in
- i[3-7]86-*-linux-gnu*) do something ;;
- sparc*-sun-solaris2.[56789]*) do something ;;
- sparc*-sun-solaris*) do something ;;
- mips*-*-elf*) do something ;;
- esac
-
- It is particularly important to use `*' after the operating system
-field, in order to match the version number which will be generated by
-`config.guess'.
-
- In most cases you must be careful to match a range of processor
-types. For most processor families, a trailing `*' suffices, as in
-`mips*' above. For the i386 family, something along the lines of
-`i[3-7]86' suffices at present. For the m68k family, you will need
-something like `m68*'. Of course, if you do not need to match on the
-processor, it is simpler to just replace the entire field by a `*', as
-in `*-*-irix*'.
-
-\1f
-File: configure.info, Node: Cross Compilation Tools, Next: Canadian Cross, Prev: Configuration Names, Up: Top
-
-5 Cross Compilation Tools
-*************************
-
-The GNU configure and build system can be used to build "cross
-compilation" tools. A cross compilation tool is a tool which runs on
-one system and produces code which runs on another system.
-
-* Menu:
-
-* Cross Compilation Concepts:: Cross Compilation Concepts.
-* Host and Target:: Host and Target.
-* Using the Host Type:: Using the Host Type.
-* Specifying the Target:: Specifying the Target.
-* Using the Target Type:: Using the Target Type.
-* Cross Tools in the Cygnus Tree:: Cross Tools in the Cygnus Tree
-
-\1f
-File: configure.info, Node: Cross Compilation Concepts, Next: Host and Target, Up: Cross Compilation Tools
-
-5.1 Cross Compilation Concepts
-==============================
-
-A compiler which produces programs which run on a different system is a
-cross compilation compiler, or simply a "cross compiler". Similarly,
-we speak of cross assemblers, cross linkers, etc.
-
- In the normal case, a compiler produces code which runs on the same
-system as the one on which the compiler runs. When it is necessary to
-distinguish this case from the cross compilation case, such a compiler
-is called a "native compiler". Similarly, we speak of native
-assemblers, etc.
-
- Although the debugger is not strictly speaking a compilation tool,
-it is nevertheless meaningful to speak of a cross debugger: a debugger
-which is used to debug code which runs on another system. Everything
-that is said below about configuring cross compilation tools applies to
-the debugger as well.
-
-\1f
-File: configure.info, Node: Host and Target, Next: Using the Host Type, Prev: Cross Compilation Concepts, Up: Cross Compilation Tools
-
-5.2 Host and Target
-===================
-
-When building cross compilation tools, there are two different systems
-involved: the system on which the tools will run, and the system for
-which the tools generate code.
-
- The system on which the tools will run is called the "host" system.
-
- The system for which the tools generate code is called the "target"
-system.
-
- For example, suppose you have a compiler which runs on a GNU/Linux
-system and generates ELF programs for a MIPS embedded system. In this
-case the GNU/Linux system is the host, and the MIPS ELF system is the
-target. Such a compiler could be called a GNU/Linux cross MIPS ELF
-compiler, or, equivalently, a `i386-linux-gnu' cross `mips-elf'
-compiler.
-
- Naturally, most programs are not cross compilation tools. For those
-programs, it does not make sense to speak of a target. It only makes
-sense to speak of a target for tools like `gcc' or the `binutils' which
-actually produce running code. For example, it does not make sense to
-speak of the target of a tool like `bison' or `make'.
-
- Most cross compilation tools can also serve as native tools. For a
-native compilation tool, it is still meaningful to speak of a target.
-For a native tool, the target is the same as the host. For example, for
-a GNU/Linux native compiler, the host is GNU/Linux, and the target is
-also GNU/Linux.
-
-\1f
-File: configure.info, Node: Using the Host Type, Next: Specifying the Target, Prev: Host and Target, Up: Cross Compilation Tools
-
-5.3 Using the Host Type
-=======================
-
-In almost all cases the host system is the system on which you run the
-`configure' script, and on which you build the tools (for the case when
-they differ, *note Canadian Cross::).
-
- If your configure script needs to know the configuration name of the
-host system, and the package is not a cross compilation tool and
-therefore does not have a target, put `AC_CANONICAL_HOST' in
-`configure.in'. This macro will arrange to define a few shell
-variables when the `configure' script is run.
-
-`host'
- The canonical configuration name of the host. This will normally
- be determined by running the `config.guess' shell script, although
- the user is permitted to override this by using an explicit
- `--host' option.
-
-`host_alias'
- In the unusual case that the user used an explicit `--host' option,
- this will be the argument to `--host'. In the normal case, this
- will be the same as the `host' variable.
-
-`host_cpu'
-`host_vendor'
-`host_os'
- The first three parts of the canonical configuration name.
-
- The shell variables may be used by putting shell code in
-`configure.in'. For an example, see *Note Using Configuration Names::.
-
-\1f
-File: configure.info, Node: Specifying the Target, Next: Using the Target Type, Prev: Using the Host Type, Up: Cross Compilation Tools
-
-5.4 Specifying the Target
-=========================
-
-By default, the `configure' script will assume that the target is the
-same as the host. This is the more common case; for example, it leads
-to a native compiler rather than a cross compiler.
-
- If you want to build a cross compilation tool, you must specify the
-target explicitly by using the `--target' option when you run
-`configure'. The argument to `--target' is the configuration name of
-the system for which you wish to generate code. *Note Configuration
-Names::.
-
- For example, to build tools which generate code for a MIPS ELF
-embedded system, you would use `--target mips-elf'.
-
-\1f
-File: configure.info, Node: Using the Target Type, Next: Cross Tools in the Cygnus Tree, Prev: Specifying the Target, Up: Cross Compilation Tools
-
-5.5 Using the Target Type
-=========================
-
-When writing `configure.in' for a cross compilation tool, you will need
-to use information about the target. To do this, put
-`AC_CANONICAL_SYSTEM' in `configure.in'.
-
- `AC_CANONICAL_SYSTEM' will look for a `--target' option and
-canonicalize it using the `config.sub' shell script. It will also run
-`AC_CANONICAL_HOST' (*note Using the Host Type::).
-
- The target type will be recorded in the following shell variables.
-Note that the host versions of these variables will also be defined by
-`AC_CANONICAL_HOST'.
-
-`target'
- The canonical configuration name of the target.
-
-`target_alias'
- The argument to the `--target' option. If the user did not specify
- a `--target' option, this will be the same as `host_alias'.
-
-`target_cpu'
-`target_vendor'
-`target_os'
- The first three parts of the canonical target configuration name.
-
- Note that if `host' and `target' are the same string, you can assume
-a native configuration. If they are different, you can assume a cross
-configuration.
-
- It is arguably possible for `host' and `target' to represent the
-same system, but for the strings to not be identical. For example, if
-`config.guess' returns `sparc-sun-sunos4.1.4', and somebody configures
-with `--target sparc-sun-sunos4.1', then the slight differences between
-the two versions of SunOS may be unimportant for your tool. However,
-in the general case it can be quite difficult to determine whether the
-differences between two configuration names are significant or not.
-Therefore, by convention, if the user specifies a `--target' option
-without specifying a `--host' option, it is assumed that the user wants
-to configure a cross compilation tool.
-
- The variables `target' and `target_alias' should be handled
-differently.
-
- In general, whenever the user may actually see a string,
-`target_alias' should be used. This includes anything which may appear
-in the file system, such as a directory name or part of a tool name.
-It also includes any tool output, unless it is clearly labelled as the
-canonical target configuration name. This permits the user to use the
-`--target' option to specify how the tool will appear to the outside
-world.
-
- On the other hand, when checking for characteristics of the target
-system, `target' should be used. This is because a wide variety of
-`--target' options may map into the same canonical configuration name.
-You should not attempt to duplicate the canonicalization done by
-`config.sub' in your own code.
-
- By convention, cross tools are installed with a prefix of the
-argument used with the `--target' option, also known as `target_alias'
-(*note Using the Target Type::). If the user does not use the
-`--target' option, and thus is building a native tool, no prefix is
-used.
-
- For example, if gcc is configured with `--target mips-elf', then the
-installed binary will be named `mips-elf-gcc'. If gcc is configured
-without a `--target' option, then the installed binary will be named
-`gcc'.
-
- The autoconf macro `AC_ARG_PROGRAM' will handle this for you. If
-you are using automake, no more need be done; the programs will
-automatically be installed with the correct prefixes. Otherwise, see
-the autoconf documentation for `AC_ARG_PROGRAM'.
-
-\1f
-File: configure.info, Node: Cross Tools in the Cygnus Tree, Prev: Using the Target Type, Up: Cross Compilation Tools
-
-5.6 Cross Tools in the Cygnus Tree
-==================================
-
-The Cygnus tree is used for various packages including gdb, the GNU
-binutils, and egcs. It is also, of course, used for Cygnus releases.
-
- In the Cygnus tree, the top level `configure' script uses the old
-Cygnus configure system, not autoconf. The top level `Makefile.in' is
-written to build packages based on what is in the source tree, and
-supports building a large number of tools in a single
-`configure'/`make' step.
-
- The Cygnus tree may be configured with a `--target' option. The
-`--target' option applies recursively to every subdirectory, and
-permits building an entire set of cross tools at once.
-
-* Menu:
-
-* Host and Target Libraries:: Host and Target Libraries.
-* Target Library Configure Scripts:: Target Library Configure Scripts.
-* Make Targets in Cygnus Tree:: Make Targets in Cygnus Tree.
-* Target libiberty:: Target libiberty
-
-\1f
-File: configure.info, Node: Host and Target Libraries, Next: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree
-
-5.6.1 Host and Target Libraries
--------------------------------
-
-The Cygnus tree distinguishes host libraries from target libraries.
-
- Host libraries are built with the compiler used to build the programs
-which run on the host, which is called the host compiler. This includes
-libraries such as `bfd' and `tcl'. These libraries are built with the
-host compiler, and are linked into programs like the binutils or gcc
-which run on the host.
-
- Target libraries are built with the target compiler. If gcc is
-present in the source tree, then the target compiler is the gcc that is
-built using the host compiler. Target libraries are libraries such as
-`newlib' and `libstdc++'. These libraries are not linked into the host
-programs, but are instead made available for use with programs built
-with the target compiler.
-
- For the rest of this section, assume that gcc is present in the
-source tree, so that it will be used to build the target libraries.
-
- There is a complication here. The configure process needs to know
-which compiler you are going to use to build a tool; otherwise, the
-feature tests will not work correctly. The Cygnus tree handles this by
-not configuring the target libraries until the target compiler is
-built. In order to permit everything to build using a single
-`configure'/`make', the configuration of the target libraries is
-actually triggered during the make step.
-
- When the target libraries are configured, the `--target' option is
-not used. Instead, the `--host' option is used with the argument of
-the `--target' option for the overall configuration. If no `--target'
-option was used for the overall configuration, the `--host' option will
-be passed with the output of the `config.guess' shell script. Any
-`--build' option is passed down unchanged.
-
- This translation of configuration options is done because since the
-target libraries are compiled with the target compiler, they are being
-built in order to run on the target of the overall configuration. By
-the definition of host, this means that their host system is the same as
-the target system of the overall configuration.
-
- The same process is used for both a native configuration and a cross
-configuration. Even when using a native configuration, the target
-libraries will be configured and built using the newly built compiler.
-This is particularly important for the C++ libraries, since there is no
-reason to assume that the C++ compiler used to build the host tools (if
-there even is one) uses the same ABI as the g++ compiler which will be
-used to build the target libraries.
-
- There is one difference between a native configuration and a cross
-configuration. In a native configuration, the target libraries are
-normally configured and built as siblings of the host tools. In a cross
-configuration, the target libraries are normally built in a subdirectory
-whose name is the argument to `--target'. This is mainly for
-historical reasons.
-
- To summarize, running `configure' in the Cygnus tree configures all
-the host libraries and tools, but does not configure any of the target
-libraries. Running `make' then does the following steps:
-
- * Build the host libraries.
-
- * Build the host programs, including gcc. Note that we call gcc
- both a host program (since it runs on the host) and a target
- compiler (since it generates code for the target).
-
- * Using the newly built target compiler, configure the target
- libraries.
-
- * Build the target libraries.
-
- The steps need not be done in precisely this order, since they are
-actually controlled by `Makefile' targets.
-
-\1f
-File: configure.info, Node: Target Library Configure Scripts, Next: Make Targets in Cygnus Tree, Prev: Host and Target Libraries, Up: Cross Tools in the Cygnus Tree
-
-5.6.2 Target Library Configure Scripts
---------------------------------------
-
-There are a few things you must know in order to write a configure
-script for a target library. This is just a quick sketch, and beginners
-shouldn't worry if they don't follow everything here.
-
- The target libraries are configured and built using a newly built
-target compiler. There may not be any startup files or libraries for
-this target compiler. In fact, those files will probably be built as
-part of some target library, which naturally means that they will not
-exist when your target library is configured.
-
- This means that the configure script for a target library may not use
-any test which requires doing a link. This unfortunately includes many
-useful autoconf macros, such as `AC_CHECK_FUNCS'. autoconf macros
-which do a compile but not a link, such as `AC_CHECK_HEADERS', may be
-used.
-
- This is a severe restriction, but normally not a fatal one, as target
-libraries can often assume the presence of other target libraries, and
-thus know which functions will be available.
-
- As of this writing, the autoconf macro `AC_PROG_CC' does a link to
-make sure that the compiler works. This may fail in a target library,
-so target libraries must use a different set of macros to locate the
-compiler. See the `configure.in' file in a directory like `libiberty'
-or `libgloss' for an example.
-
- As noted in the previous section, target libraries are sometimes
-built in directories which are siblings to the host tools, and are
-sometimes built in a subdirectory. The `--with-target-subdir' configure
-option will be passed when the library is configured. Its value will be
-an empty string if the target library is a sibling. Its value will be
-the name of the subdirectory if the target library is in a subdirectory.
-
- If the overall build is not a native build (i.e., the overall
-configure used the `--target' option), then the library will be
-configured with the `--with-cross-host' option. The value of this
-option will be the host system of the overall build. Recall that the
-host system of the library will be the target of the overall build. If
-the overall build is a native build, the `--with-cross-host' option
-will not be used.
-
- A library which can be built both standalone and as a target library
-may want to install itself into different directories depending upon the
-case. When built standalone, or when built native, the library should
-be installed in `$(libdir)'. When built as a target library which is
-not native, the library should be installed in `$(tooldir)/lib'. The
-`--with-cross-host' option may be used to distinguish these cases.
-
- This same test of `--with-cross-host' may be used to see whether it
-is OK to use link tests in the configure script. If the
-`--with-cross-host' option is not used, then the library is being built
-either standalone or native, and a link should work.
-
-\1f
-File: configure.info, Node: Make Targets in Cygnus Tree, Next: Target libiberty, Prev: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree
-
-5.6.3 Make Targets in Cygnus Tree
----------------------------------
-
-The top level `Makefile' in the Cygnus tree defines targets for every
-known subdirectory.
-
- For every subdirectory DIR which holds a host library or program,
-the `Makefile' target `all-DIR' will build that library or program.
-
- There are dependencies among host tools. For example, building gcc
-requires first building gas, because the gcc build process invokes the
-target assembler. These dependencies are reflected in the top level
-`Makefile'.
-
- For every subdirectory DIR which holds a target library, the
-`Makefile' target `configure-target-DIR' will configure that library.
-The `Makefile' target `all-target-DIR' will build that library.
-
- Every `configure-target-DIR' target depends upon `all-gcc', since
-gcc, the target compiler, is required to configure the tool. Every
-`all-target-DIR' target depends upon the corresponding
-`configure-target-DIR' target.
-
- There are several other targets which may be of interest for each
-directory: `install-DIR', `clean-DIR', and `check-DIR'. There are also
-corresponding `target' versions of these for the target libraries ,
-such as `install-target-DIR'.
-
-\1f
-File: configure.info, Node: Target libiberty, Prev: Make Targets in Cygnus Tree, Up: Cross Tools in the Cygnus Tree
-
-5.6.4 Target libiberty
-----------------------
-
-The `libiberty' subdirectory is currently a special case, in that it is
-the only directory which is built both using the host compiler and
-using the target compiler.
-
- This is because the files in `libiberty' are used when building the
-host tools, and they are also incorporated into the `libstdc++' target
-library as support code.
-
- This duality does not pose any particular difficulties. It means
-that there are targets for both `all-libiberty' and
-`all-target-libiberty'.
-
- In a native configuration, when target libraries are not built in a
-subdirectory, the same objects are normally used as both the host build
-and the target build. This is normally OK, since libiberty contains
-only C code, and in a native configuration the results of the host
-compiler and the target compiler are normally interoperable.
-
- Irix 6 is again an exception here, since the SGI native compiler
-defaults to using the `O32' ABI, and gcc defaults to using the `N32'
-ABI. On Irix 6, the target libraries are built in a subdirectory even
-for a native configuration, avoiding this problem.
-
- There are currently no other libraries built for both the host and
-the target, but there is no conceptual problem with adding more.
-
-\1f
-File: configure.info, Node: Canadian Cross, Next: Cygnus Configure, Prev: Cross Compilation Tools, Up: Top
-
-6 Canadian Cross
-****************
-
-It is possible to use the GNU configure and build system to build a
-program which will run on a system which is different from the system on
-which the tools are built. In other words, it is possible to build
-programs using a cross compiler.
-
- This is referred to as a "Canadian Cross".
-
-* Menu:
-
-* Canadian Cross Example:: Canadian Cross Example.
-* Canadian Cross Concepts:: Canadian Cross Concepts.
-* Build Cross Host Tools:: Build Cross Host Tools.
-* Build and Host Options:: Build and Host Options.
-* CCross not in Cygnus Tree:: Canadian Cross not in Cygnus Tree.
-* CCross in Cygnus Tree:: Canadian Cross in Cygnus Tree.
-* Supporting Canadian Cross:: Supporting Canadian Cross.
-
-\1f
-File: configure.info, Node: Canadian Cross Example, Next: Canadian Cross Concepts, Up: Canadian Cross
-
-6.1 Canadian Cross Example
-==========================
-
-Here is an example of a Canadian Cross.
-
- While running on a GNU/Linux, you can build a program which will run
-on a Solaris system. You would use a GNU/Linux cross Solaris compiler
-to build the program.
-
- Of course, you could not run the resulting program on your GNU/Linux
-system. You would have to copy it over to a Solaris system before you
-would run it.
-
- Of course, you could also simply build the programs on the Solaris
-system in the first place. However, perhaps the Solaris system is not
-available for some reason; perhaps you actually don't have one, but you
-want to build the tools for somebody else to use. Or perhaps your
-GNU/Linux system is much faster than your Solaris system.
-
- A Canadian Cross build is most frequently used when building
-programs to run on a non-Unix system, such as DOS or Windows. It may
-be simpler to configure and build on a Unix system than to support the
-configuration machinery on a non-Unix system.
-
-\1f
-File: configure.info, Node: Canadian Cross Concepts, Next: Build Cross Host Tools, Prev: Canadian Cross Example, Up: Canadian Cross
-
-6.2 Canadian Cross Concepts
-===========================
-
-When building a Canadian Cross, there are at least two different systems
-involved: the system on which the tools are being built, and the system
-on which the tools will run.
-
- The system on which the tools are being built is called the "build"
-system.
-
- The system on which the tools will run is called the host system.
-
- For example, if you are building a Solaris program on a GNU/Linux
-system, as in the previous section, the build system would be GNU/Linux,
-and the host system would be Solaris.
-
- It is, of course, possible to build a cross compiler using a Canadian
-Cross (i.e., build a cross compiler using a cross compiler). In this
-case, the system for which the resulting cross compiler generates code
-is called the target system. (For a more complete discussion of host
-and target systems, *note Host and Target::).
-
- An example of building a cross compiler using a Canadian Cross would
-be building a Windows cross MIPS ELF compiler on a GNU/Linux system. In
-this case the build system would be GNU/Linux, the host system would be
-Windows, and the target system would be MIPS ELF.
-
- The name Canadian Cross comes from the case when the build, host, and
-target systems are all different. At the time that these issues were
-all being hashed out, Canada had three national political parties.
-
-\1f
-File: configure.info, Node: Build Cross Host Tools, Next: Build and Host Options, Prev: Canadian Cross Concepts, Up: Canadian Cross
-
-6.3 Build Cross Host Tools
-==========================
-
-In order to configure a program for a Canadian Cross build, you must
-first build and install the set of cross tools you will use to build the
-program.
-
- These tools will be build cross host tools. That is, they will run
-on the build system, and will produce code that runs on the host system.
-
- It is easy to confuse the meaning of build and host here. Always
-remember that the build system is where you are doing the build, and the
-host system is where the resulting program will run. Therefore, you
-need a build cross host compiler.
-
- In general, you must have a complete cross environment in order to do
-the build. This normally means a cross compiler, cross assembler, and
-so forth, as well as libraries and include files for the host system.
-
-\1f
-File: configure.info, Node: Build and Host Options, Next: CCross not in Cygnus Tree, Prev: Build Cross Host Tools, Up: Canadian Cross
-
-6.4 Build and Host Options
-==========================
-
-When you run `configure', you must use both the `--build' and `--host'
-options.
-
- The `--build' option is used to specify the configuration name of
-the build system. This can normally be the result of running the
-`config.guess' shell script, and it is reasonable to use
-`--build=`config.guess`'.
-
- The `--host' option is used to specify the configuration name of the
-host system.
-
- As we explained earlier, `config.guess' is used to set the default
-value for the `--host' option (*note Using the Host Type::). We can
-now see that since `config.guess' returns the type of system on which
-it is run, it really identifies the build system. Since the host
-system is normally the same as the build system (i.e., people do not
-normally build using a cross compiler), it is reasonable to use the
-result of `config.guess' as the default for the host system when the
-`--host' option is not used.
-
- It might seem that if the `--host' option were used without the
-`--build' option that the configure script could run `config.guess' to
-determine the build system, and presume a Canadian Cross if the result
-of `config.guess' differed from the `--host' option. However, for
-historical reasons, some configure scripts are routinely run using an
-explicit `--host' option, rather than using the default from
-`config.guess'. As noted earlier, it is difficult or impossible to
-reliably compare configuration names (*note Using the Target Type::).
-Therefore, by convention, if the `--host' option is used, but the
-`--build' option is not used, then the build system defaults to the
-host system.
-
-\1f
-File: configure.info, Node: CCross not in Cygnus Tree, Next: CCross in Cygnus Tree, Prev: Build and Host Options, Up: Canadian Cross
-
-6.5 Canadian Cross not in Cygnus Tree.
-======================================
-
-If you are not using the Cygnus tree, you must explicitly specify the
-cross tools which you want to use to build the program. This is done by
-setting environment variables before running the `configure' script.
-
- You must normally set at least the environment variables `CC', `AR',
-and `RANLIB' to the cross tools which you want to use to build.
-
- For some programs, you must set additional cross tools as well, such
-as `AS', `LD', or `NM'.
-
- You would set these environment variables to the build cross tools
-which you are going to use.
-
- For example, if you are building a Solaris program on a GNU/Linux
-system, and your GNU/Linux cross Solaris compiler were named
-`solaris-gcc', then you would set the environment variable `CC' to
-`solaris-gcc'.
-
-\1f
-File: configure.info, Node: CCross in Cygnus Tree, Next: Supporting Canadian Cross, Prev: CCross not in Cygnus Tree, Up: Canadian Cross
-
-6.6 Canadian Cross in Cygnus Tree
-=================================
-
-This section describes configuring and building a Canadian Cross when
-using the Cygnus tree.
-
-* Menu:
-
-* Standard Cygnus CCross:: Building a Normal Program.
-* Cross Cygnus CCross:: Building a Cross Program.
-
-\1f
-File: configure.info, Node: Standard Cygnus CCross, Next: Cross Cygnus CCross, Up: CCross in Cygnus Tree
-
-6.6.1 Building a Normal Program
--------------------------------
-
-When configuring a Canadian Cross in the Cygnus tree, all the
-appropriate environment variables are automatically set to `HOST-TOOL',
-where HOST is the value used for the `--host' option, and TOOL is the
-name of the tool (e.g., `gcc', `as', etc.). These tools must be on
-your `PATH'.
-
- Adding a prefix of HOST will give the usual name for the build cross
-host tools. To see this, consider that when these cross tools were
-built, they were configured to run on the build system and to produce
-code for the host system. That is, they were configured with a
-`--target' option that is the same as the system which we are now
-calling the host. Recall that the default name for installed cross
-tools uses the target system as a prefix (*note Using the Target
-Type::). Since that is the system which we are now calling the host,
-HOST is the right prefix to use.
-
- For example, if you configure with `--build=i386-linux-gnu' and
-`--host=solaris', then the Cygnus tree will automatically default to
-using the compiler `solaris-gcc'. You must have previously built and
-installed this compiler, probably by doing a build with no `--host'
-option and with a `--target' option of `solaris'.
-
-\1f
-File: configure.info, Node: Cross Cygnus CCross, Prev: Standard Cygnus CCross, Up: CCross in Cygnus Tree
-
-6.6.2 Building a Cross Program
-------------------------------
-
-There are additional considerations if you want to build a cross
-compiler, rather than a native compiler, in the Cygnus tree using a
-Canadian Cross.
-
- When you build a cross compiler using the Cygnus tree, then the
-target libraries will normally be built with the newly built target
-compiler (*note Host and Target Libraries::). However, this will not
-work when building with a Canadian Cross. This is because the newly
-built target compiler will be a program which runs on the host system,
-and therefore will not be able to run on the build system.
-
- Therefore, when building a cross compiler with the Cygnus tree, you
-must first install a set of build cross target tools. These tools will
-be used when building the target libraries.
-
- Note that this is not a requirement of a Canadian Cross in general.
-For example, it would be possible to build just the host cross target
-tools on the build system, to copy the tools to the host system, and to
-build the target libraries on the host system. The requirement for
-build cross target tools is imposed by the Cygnus tree, which expects
-to be able to build both host programs and target libraries in a single
-`configure'/`make' step. Because it builds these in a single step, it
-expects to be able to build the target libraries on the build system,
-which means that it must use a build cross target toolchain.
-
- For example, suppose you want to build a Windows cross MIPS ELF
-compiler on a GNU/Linux system. You must have previously installed
-both a GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF
-compiler.
-
- In order to build the Windows (configuration name `i386-cygwin32')
-cross MIPS ELF (configure name `mips-elf') compiler, you might execute
-the following commands (long command lines are broken across lines with
-a trailing backslash as a continuation character).
-
- mkdir linux-x-cygwin32
- cd linux-x-cygwin32
- SRCDIR/configure --target i386-cygwin32 --prefix=INSTALLDIR \
- --exec-prefix=INSTALLDIR/H-i386-linux
- make
- make install
- cd ..
- mkdir linux-x-mips-elf
- cd linux-x-mips-elf
- SRCDIR/configure --target mips-elf --prefix=INSTALLDIR \
- --exec-prefix=INSTALLDIR/H-i386-linux
- make
- make install
- cd ..
- mkdir cygwin32-x-mips-elf
- cd cygwin32-x-mips-elf
- SRCDIR/configure --build=i386-linux-gnu --host=i386-cygwin32 \
- --target=mips-elf --prefix=WININSTALLDIR \
- --exec-prefix=WININSTALLDIR/H-i386-cygwin32
- make
- make install
-
- You would then copy the contents of WININSTALLDIR over to the
-Windows machine, and run the resulting programs.
-
-\1f
-File: configure.info, Node: Supporting Canadian Cross, Prev: CCross in Cygnus Tree, Up: Canadian Cross
-
-6.7 Supporting Canadian Cross
-=============================
-
-If you want to make it possible to build a program you are developing
-using a Canadian Cross, you must take some care when writing your
-configure and make rules. Simple cases will normally work correctly.
-However, it is not hard to write configure and make tests which will
-fail in a Canadian Cross.
-
-* Menu:
-
-* CCross in Configure:: Supporting Canadian Cross in Configure Scripts.
-* CCross in Make:: Supporting Canadian Cross in Makefiles.
-
-\1f
-File: configure.info, Node: CCross in Configure, Next: CCross in Make, Up: Supporting Canadian Cross
-
-6.7.1 Supporting Canadian Cross in Configure Scripts
-----------------------------------------------------
-
-In a `configure.in' file, after calling `AC_PROG_CC', you can find out
-whether this is a Canadian Cross configure by examining the shell
-variable `cross_compiling'. In a Canadian Cross, which means that the
-compiler is a cross compiler, `cross_compiling' will be `yes'. In a
-normal configuration, `cross_compiling' will be `no'.
-
- You ordinarily do not need to know the type of the build system in a
-configure script. However, if you do need that information, you can get
-it by using the macro `AC_CANONICAL_SYSTEM', the same macro that is
-used to determine the target system. This macro will set the variables
-`build', `build_alias', `build_cpu', `build_vendor', and `build_os',
-which correspond to the similar `target' and `host' variables, except
-that they describe the build system.
-
- When writing tests in `configure.in', you must remember that you
-want to test the host environment, not the build environment.
-
- Macros like `AC_CHECK_FUNCS' which use the compiler will test the
-host environment. That is because the tests will be done by running the
-compiler, which is actually a build cross host compiler. If the
-compiler can find the function, that means that the function is present
-in the host environment.
-
- Tests like `test -f /dev/ptyp0', on the other hand, will test the
-build environment. Remember that the configure script is running on the
-build system, not the host system. If your configure scripts examines
-files, those files will be on the build system. Whatever you determine
-based on those files may or may not be the case on the host system.
-
- Most autoconf macros will work correctly for a Canadian Cross. The
-main exception is `AC_TRY_RUN'. This macro tries to compile and run a
-test program. This will fail in a Canadian Cross, because the program
-will be compiled for the host system, which means that it will not run
-on the build system.
-
- The `AC_TRY_RUN' macro provides an optional argument to tell the
-configure script what to do in a Canadian Cross. If that argument is
-not present, you will get a warning when you run `autoconf':
- warning: AC_TRY_RUN called without default to allow cross compiling
- This tells you that the resulting `configure' script will not work
-with a Canadian Cross.
-
- In some cases while it may better to perform a test at configure
-time, it is also possible to perform the test at run time. In such a
-case you can use the cross compiling argument to `AC_TRY_RUN' to tell
-your program that the test could not be performed at configure time.
-
- There are a few other autoconf macros which will not work correctly
-with a Canadian Cross: a partial list is `AC_FUNC_GETPGRP',
-`AC_FUNC_SETPGRP', `AC_FUNC_SETVBUF_REVERSED', and
-`AC_SYS_RESTARTABLE_SYSCALLS'. The `AC_CHECK_SIZEOF' macro is
-generally not very useful with a Canadian Cross; it permits an optional
-argument indicating the default size, but there is no way to know what
-the correct default should be.
-
-\1f
-File: configure.info, Node: CCross in Make, Prev: CCross in Configure, Up: Supporting Canadian Cross
-
-6.7.2 Supporting Canadian Cross in Makefiles.
----------------------------------------------
-
-The main Canadian Cross issue in a `Makefile' arises when you want to
-use a subsidiary program to generate code or data which you will then
-include in your real program.
-
- If you compile this subsidiary program using `$(CC)' in the usual
-way, you will not be able to run it. This is because `$(CC)' will
-build a program for the host system, but the program is being built on
-the build system.
-
- You must instead use a compiler for the build system, rather than the
-host system. In the Cygnus tree, this make variable `$(CC_FOR_BUILD)'
-will hold a compiler for the build system.
-
- Note that you should not include `config.h' in a file you are
-compiling with `$(CC_FOR_BUILD)'. The `configure' script will build
-`config.h' with information for the host system. However, you are
-compiling the file using a compiler for the build system (a native
-compiler). Subsidiary programs are normally simple filters which do no
-user interaction, and it is normally possible to write them in a highly
-portable fashion so that the absence of `config.h' is not crucial.
-
- The gcc `Makefile.in' shows a complex situation in which certain
-files, such as `rtl.c', must be compiled into both subsidiary programs
-run on the build system and into the final program. This approach may
-be of interest for advanced build system hackers. Note that the build
-system compiler is rather confusingly called `HOST_CC'.
-
-\1f
-File: configure.info, Node: Cygnus Configure, Next: Multilibs, Prev: Canadian Cross, Up: Top
-
-7 Cygnus Configure
-******************
-
-The Cygnus configure script predates autoconf. All of its interesting
-features have been incorporated into autoconf. No new programs should
-be written to use the Cygnus configure script.
-
- However, the Cygnus configure script is still used in a few places:
-at the top of the Cygnus tree and in a few target libraries in the
-Cygnus tree. Until those uses have been replaced with autoconf, some
-brief notes are appropriate here. This is not complete documentation,
-but it should be possible to use this as a guide while examining the
-scripts themselves.
-
-* Menu:
-
-* Cygnus Configure Basics:: Cygnus Configure Basics.
-* Cygnus Configure in C++ Libraries:: Cygnus Configure in C++ Libraries.
-
-\1f
-File: configure.info, Node: Cygnus Configure Basics, Next: Cygnus Configure in C++ Libraries, Up: Cygnus Configure
-
-7.1 Cygnus Configure Basics
-===========================
-
-Cygnus configure does not use any generated files; there is no program
-corresponding to `autoconf'. Instead, there is a single shell script
-named `configure' which may be found at the top of the Cygnus tree.
-This shell script was written by hand; it was not generated by
-autoconf, and it is incorrect, and indeed harmful, to run `autoconf' in
-the top level of a Cygnus tree.
-
- Cygnus configure works in a particular directory by examining the
-file `configure.in' in that directory. That file is broken into four
-separate shell scripts.
-
- The first is the contents of `configure.in' up to a line that starts
-with `# per-host:'. This is the common part.
-
- The second is the rest of `configure.in' up to a line that starts
-with `# per-target:'. This is the per host part.
-
- The third is the rest of `configure.in' up to a line that starts
-with `# post-target:'. This is the per target part.
-
- The fourth is the remainder of `configure.in'. This is the post
-target part.
-
- If any of these comment lines are missing, the corresponding shell
-script is empty.
-
- Cygnus configure will first execute the common part. This must set
-the shell variable `srctrigger' to the name of a source file, to
-confirm that Cygnus configure is looking at the right directory. This
-may set the shell variables `package_makefile_frag' and
-`package_makefile_rules_frag'.
-
- Cygnus configure will next set the `build' and `host' shell
-variables, and execute the per host part. This may set the shell
-variable `host_makefile_frag'.
-
- Cygnus configure will next set the `target' variable, and execute
-the per target part. This may set the shell variable
-`target_makefile_frag'.
-
- Any of these scripts may set the `subdirs' shell variable. This
-variable is a list of subdirectories where a `Makefile.in' file may be
-found. Cygnus configure will automatically look for a `Makefile.in'
-file in the current directory. The `subdirs' shell variable is not
-normally used, and I believe that the only directory which uses it at
-present is `newlib'.
-
- For each `Makefile.in', Cygnus configure will automatically create a
-`Makefile' by adding definitions for `make' variables such as `host'
-and `target', and automatically editing the values of `make' variables
-such as `prefix' if they are present.
-
- Also, if any of the `makefile_frag' shell variables are set, Cygnus
-configure will interpret them as file names relative to either the
-working directory or the source directory, and will read the contents of
-the file into the generated `Makefile'. The file contents will be read
-in after the first line in `Makefile.in' which starts with `####'.
-
- These `Makefile' fragments are used to customize behaviour for a
-particular host or target. They serve to select particular files to
-compile, and to define particular preprocessor macros by providing
-values for `make' variables which are then used during compilation.
-Cygnus configure, unlike autoconf, normally does not do feature tests,
-and normally requires support to be added manually for each new host.
-
- The `Makefile' fragment support is similar to the autoconf
-`AC_SUBST_FILE' macro.
-
- After creating each `Makefile', the post target script will be run
-(i.e., it may be run several times). This script may further customize
-the `Makefile'. When it is run, the shell variable `Makefile' will
-hold the name of the `Makefile', including the appropriate directory
-component.
-
- Like an autoconf generated `configure' script, Cygnus configure will
-create a file named `config.status' which, when run, will automatically
-recreate the configuration. The `config.status' file will simply
-execute the Cygnus configure script again with the appropriate
-arguments.
-
- Any of the parts of `configure.in' may set the shell variables
-`files' and `links'. Cygnus configure will set up symlinks from the
-names in `links' to the files named in `files'. This is similar to the
-autoconf `AC_LINK_FILES' macro.
-
- Finally, any of the parts of `configure.in' may set the shell
-variable `configdirs' to a set of subdirectories. If it is set, Cygnus
-configure will recursively run the configure process in each
-subdirectory. If the subdirectory uses Cygnus configure, it will
-contain a `configure.in' file but no `configure' file, in which case
-Cygnus configure will invoke itself recursively. If the subdirectory
-has a `configure' file, Cygnus configure assumes that it is an autoconf
-generated `configure' script, and simply invokes it directly.
-
-\1f
-File: configure.info, Node: Cygnus Configure in C++ Libraries, Prev: Cygnus Configure Basics, Up: Cygnus Configure
-
-7.2 Cygnus Configure in C++ Libraries
-=====================================
-
-The C++ library configure system, written by Per Bothner, deserves
-special mention. It uses Cygnus configure, but it does feature testing
-like that done by autoconf generated `configure' scripts. This
-approach is used in the libraries `libio', `libstdc++', and `libg++'.
-
- Most of the `Makefile' information is written out by the shell
-script `libio/config.shared'. Each `configure.in' file sets certain
-shell variables, and then invokes `config.shared' to create two package
-`Makefile' fragments. These fragments are then incorporated into the
-resulting `Makefile' by the Cygnus configure script.
-
- The file `_G_config.h' is created in the `libio' object directory by
-running the shell script `libio/gen-params'. This shell script uses
-feature tests to define macros and typedefs in `_G_config.h'.
-
-\1f
-File: configure.info, Node: Multilibs, Next: FAQ, Prev: Cygnus Configure, Up: Top
-
-8 Multilibs
-***********
-
-For some targets gcc may have different processor requirements depending
-upon command line options. An obvious example is the `-msoft-float'
-option supported on several processors. This option means that the
-floating point registers are not available, which means that floating
-point operations must be done by calling an emulation subroutine rather
-than by using machine instructions.
-
- For such options, gcc is often configured to compile target libraries
-twice: once with `-msoft-float' and once without. When gcc compiles
-target libraries more than once, the resulting libraries are called
-"multilibs".
-
- Multilibs are not really part of the GNU configure and build system,
-but we discuss them here since they require support in the `configure'
-scripts and `Makefile's used for target libraries.
-
-* Menu:
-
-* Multilibs in gcc:: Multilibs in gcc.
-* Multilibs in Target Libraries:: Multilibs in Target Libraries.
-
-\1f
-File: configure.info, Node: Multilibs in gcc, Next: Multilibs in Target Libraries, Up: Multilibs
-
-8.1 Multilibs in gcc
-====================
-
-In gcc, multilibs are defined by setting the variable
-`MULTILIB_OPTIONS' in the target `Makefile' fragment. Several other
-`MULTILIB' variables may also be defined there. *Note The Target
-Makefile Fragment: (gcc)Target Fragment.
-
- If you have built gcc, you can see what multilibs it uses by running
-it with the `-print-multi-lib' option. The output `.;' means that no
-multilibs are used. In general, the output is a sequence of lines, one
-per multilib. The first part of each line, up to the `;', is the name
-of the multilib directory. The second part is a list of compiler
-options separated by `@' characters.
-
- Multilibs are built in a tree of directories. The top of the tree,
-represented by `.' in the list of multilib directories, is the default
-library to use when no special compiler options are used. The
-subdirectories of the tree hold versions of the library to use when
-particular compiler options are used.
-
-\1f
-File: configure.info, Node: Multilibs in Target Libraries, Prev: Multilibs in gcc, Up: Multilibs
-
-8.2 Multilibs in Target Libraries
-=================================
-
-The target libraries in the Cygnus tree are automatically built with
-multilibs. That means that each library is built multiple times.
-
- This default is set in the top level `configure.in' file, by adding
-`--enable-multilib' to the list of arguments passed to configure when
-it is run for the target libraries (*note Host and Target Libraries::).
-
- Each target library uses the shell script `config-ml.in', written by
-Doug Evans, to prepare to build target libraries. This shell script is
-invoked after the `Makefile' has been created by the `configure'
-script. If multilibs are not enabled, it does nothing, otherwise it
-modifies the `Makefile' to support multilibs.
-
- The `config-ml.in' script makes one copy of the `Makefile' for each
-multilib in the appropriate subdirectory. When configuring in the
-source directory (which is not recommended), it will build a symlink
-tree of the sources in each subdirectory.
-
- The `config-ml.in' script sets several variables in the various
-`Makefile's. The `Makefile.in' must have definitions for these
-variables already; `config-ml.in' simply changes the existing values.
-The `Makefile' should use default values for these variables which will
-do the right thing in the subdirectories.
-
-`MULTISRCTOP'
- `config-ml.in' will set this to a sequence of `../' strings, where
- the number of strings is the number of multilib levels in the
- source tree. The default value should be the empty string.
-
-`MULTIBUILDTOP'
- `config-ml.in' will set this to a sequence of `../' strings, where
- the number of strings is number of multilib levels in the object
- directory. The default value should be the empty string. This
- will differ from `MULTISRCTOP' when configuring in the source tree
- (which is not recommended).
-
-`MULTIDIRS'
- In the top level `Makefile' only, `config-ml.in' will set this to
- the list of multilib subdirectories. The default value should be
- the empty string.
-
-`MULTISUBDIR'
- `config-ml.in' will set this to the installed subdirectory name to
- use for this subdirectory, with a leading `/'. The default value
- shold be the empty string.
-
-`MULTIDO'
-`MULTICLEAN'
- In the top level `Makefile' only, `config-ml.in' will set these
- variables to commands to use when doing a recursive make. These
- variables should both default to the string `true', so that by
- default nothing happens.
-
- All references to the parent of the source directory should use the
-variable `MULTISRCTOP'. Instead of writing `$(srcdir)/..', you must
-write `$(srcdir)/$(MULTISRCTOP)..'.
-
- Similarly, references to the parent of the object directory should
-use the variable `MULTIBUILDTOP'.
-
- In the installation target, the libraries should be installed in the
-subdirectory `MULTISUBDIR'. Instead of installing
-`$(libdir)/libfoo.a', install `$(libdir)$(MULTISUBDIR)/libfoo.a'.
-
- The `config-ml.in' script also modifies the top level `Makefile' to
-add `multi-do' and `multi-clean' targets which are used when building
-multilibs.
-
- The default target of the `Makefile' should include the following
-command:
- @$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
- This assumes that `$(FLAGS_TO_PASS)' is defined as a set of
-variables to pass to a recursive invocation of `make'. This will build
-all the multilibs. Note that the default value of `MULTIDO' is `true',
-so by default this command will do nothing. It will only do something
-in the top level `Makefile' if multilibs were enabled.
-
- The `install' target of the `Makefile' should include the following
-command:
- @$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
-
- In general, any operation, other than clean, which should be
-performed on all the multilibs should use a `$(MULTIDO)' line, setting
-the variable `DO' to the target of each recursive call to `make'.
-
- The `clean' targets (`clean', `mostlyclean', etc.) should use
-`$(MULTICLEAN)'. For example, the `clean' target should do this:
- @$(MULTICLEAN) DO=clean multi-clean
-
-\1f
-File: configure.info, Node: FAQ, Next: Index, Prev: Multilibs, Up: Top
-
-9 Frequently Asked Questions
-****************************
-
-Which do I run first, `autoconf' or `automake'?
- Except when you first add autoconf or automake support to a
- package, you shouldn't run either by hand. Instead, configure
- with the `--enable-maintainer-mode' option, and let `make' take
- care of it.
-
-`autoconf' says something about undefined macros.
- This means that you have macros in your `configure.in' which are
- not defined by `autoconf'. You may be using an old version of
- `autoconf'; try building and installing a newer one. Make sure the
- newly installled `autoconf' is first on your `PATH'. Also, see
- the next question.
-
-My `configure' script has stuff like `CY_GNU_GETTEXT' in it.
- This means that you have macros in your `configure.in' which should
- be defined in your `aclocal.m4' file, but aren't. This usually
- means that `aclocal' was not able to appropriate definitions of the
- macros. Make sure that you have installed all the packages you
- need. In particular, make sure that you have installed libtool
- (this is where `AM_PROG_LIBTOOL' is defined) and gettext (this is
- where `CY_GNU_GETTEXT' is defined, at least in the Cygnus version
- of gettext).
-
-My `Makefile' has `@' characters in it.
- This may mean that you tried to use an autoconf substitution in
- your `Makefile.in' without adding the appropriate `AC_SUBST' call
- to your `configure' script. Or it may just mean that you need to
- rebuild `Makefile' in your build directory. To rebuild `Makefile'
- from `Makefile.in', run the shell script `config.status' with no
- arguments. If you need to force `configure' to run again, first
- run `config.status --recheck'. These runs are normally done
- automatically by `Makefile' targets, but if your `Makefile' has
- gotten messed up you'll need to help them along.
-
-Why do I have to run both `config.status --recheck' and `config.status'?
- Normally, you don't; they will be run automatically by `Makefile'
- targets. If you do need to run them, use `config.status --recheck'
- to run the `configure' script again with the same arguments as the
- first time you ran it. Use `config.status' (with no arguments) to
- regenerate all files (`Makefile', `config.h', etc.) based on the
- results of the configure script. The two cases are separate
- because it isn't always necessary to regenerate all the files
- after running `config.status --recheck'. The `Makefile' targets
- generated by automake will use the environment variables
- `CONFIG_FILES' and `CONFIG_HEADERS' to only regenerate files as
- they are needed.
-
-What is the Cygnus tree?
- The Cygnus tree is used for various packages including gdb, the GNU
- binutils, and egcs. It is also, of course, used for Cygnus
- releases. It is the build system which was developed at Cygnus,
- using the Cygnus configure script. It permits building many
- different packages with a single configure and make. The
- configure scripts in the tree are being converted to autoconf, but
- the general build structure remains intact.
-
-Why do I have to keep rebuilding and reinstalling the tools?
- I know, it's a pain. Unfortunately, there are bugs in the tools
- themselves which need to be fixed, and each time that happens
- everybody who uses the tools need to reinstall new versions of
- them. I don't know if there is going to be a clever fix until the
- tools stabilize.
-
-Why not just have a Cygnus tree `make' target to update the tools?
- The tools unfortunately need to be installed before they can be
- used. That means that they must be built using an appropriate
- prefix, and it seems unwise to assume that every configuration
- uses an appropriate prefix. It might be possible to make them
- work in place, or it might be possible to install them in some
- subdirectory; so far these approaches have not been implemented.
-
-\1f
-File: configure.info, Node: Index, Prev: FAQ, Up: Top
-
-Index
-*****
-
-\0\b[index\0\b]
-* Menu:
-
-* --build option: Build and Host Options.
- (line 9)
-* --host option: Build and Host Options.
- (line 14)
-* --target option: Specifying the Target.
- (line 10)
-* _GNU_SOURCE: Write configure.in. (line 134)
-* AC_CANONICAL_HOST: Using the Host Type. (line 10)
-* AC_CANONICAL_SYSTEM: Using the Target Type.
- (line 6)
-* AC_CONFIG_HEADER: Write configure.in. (line 66)
-* AC_EXEEXT: Write configure.in. (line 86)
-* AC_INIT: Write configure.in. (line 38)
-* AC_OUTPUT: Write configure.in. (line 142)
-* AC_PREREQ: Write configure.in. (line 42)
-* AC_PROG_CC: Write configure.in. (line 103)
-* AC_PROG_CXX: Write configure.in. (line 117)
-* acconfig.h: Written Developer Files.
- (line 27)
-* acconfig.h, writing: Write acconfig.h. (line 6)
-* acinclude.m4: Written Developer Files.
- (line 37)
-* aclocal.m4: Generated Developer Files.
- (line 33)
-* AM_CONFIG_HEADER: Write configure.in. (line 53)
-* AM_DISABLE_SHARED: Write configure.in. (line 127)
-* AM_EXEEXT: Write configure.in. (line 86)
-* AM_INIT_AUTOMAKE: Write configure.in. (line 48)
-* AM_MAINTAINER_MODE: Write configure.in. (line 70)
-* AM_PROG_LIBTOOL: Write configure.in. (line 122)
-* AM_PROG_LIBTOOL in configure: FAQ. (line 19)
-* build option: Build and Host Options.
- (line 9)
-* building with a cross compiler: Canadian Cross. (line 6)
-* canadian cross: Canadian Cross. (line 6)
-* canadian cross in configure: CCross in Configure. (line 6)
-* canadian cross in cygnus tree: CCross in Cygnus Tree.
- (line 6)
-* canadian cross in makefile: CCross in Make. (line 6)
-* canadian cross, configuring: Build and Host Options.
- (line 6)
-* canonical system names: Configuration Names. (line 6)
-* config.cache: Build Files Description.
- (line 28)
-* config.h: Build Files Description.
- (line 23)
-* config.h.in: Generated Developer Files.
- (line 45)
-* config.in: Generated Developer Files.
- (line 45)
-* config.status: Build Files Description.
- (line 9)
-* config.status --recheck: FAQ. (line 40)
-* configuration names: Configuration Names. (line 6)
-* configuration triplets: Configuration Names. (line 6)
-* configure: Generated Developer Files.
- (line 21)
-* configure build system: Build and Host Options.
- (line 9)
-* configure host: Build and Host Options.
- (line 14)
-* configure target: Specifying the Target.
- (line 10)
-* configure.in: Written Developer Files.
- (line 9)
-* configure.in, writing: Write configure.in. (line 6)
-* configuring a canadian cross: Build and Host Options.
- (line 6)
-* cross compiler: Cross Compilation Concepts.
- (line 6)
-* cross compiler, building with: Canadian Cross. (line 6)
-* cross tools: Cross Compilation Tools.
- (line 6)
-* CY_GNU_GETTEXT in configure: FAQ. (line 19)
-* cygnus configure: Cygnus Configure. (line 6)
-* goals: Goals. (line 6)
-* history: History. (line 6)
-* host names: Configuration Names. (line 6)
-* host option: Build and Host Options.
- (line 14)
-* host system: Host and Target. (line 6)
-* host triplets: Configuration Names. (line 6)
-* HOST_CC: CCross in Make. (line 27)
-* libg++ configure: Cygnus Configure in C++ Libraries.
- (line 6)
-* libio configure: Cygnus Configure in C++ Libraries.
- (line 6)
-* libstdc++ configure: Cygnus Configure in C++ Libraries.
- (line 6)
-* Makefile: Build Files Description.
- (line 18)
-* Makefile, garbage characters: FAQ. (line 29)
-* Makefile.am: Written Developer Files.
- (line 18)
-* Makefile.am, writing: Write Makefile.am. (line 6)
-* Makefile.in: Generated Developer Files.
- (line 26)
-* multilibs: Multilibs. (line 6)
-* stamp-h: Build Files Description.
- (line 41)
-* stamp-h.in: Generated Developer Files.
- (line 54)
-* system names: Configuration Names. (line 6)
-* system types: Configuration Names. (line 6)
-* target option: Specifying the Target.
- (line 10)
-* target system: Host and Target. (line 6)
-* triplets: Configuration Names. (line 6)
-* undefined macros: FAQ. (line 12)
-
-
-\1f
-Tag Table:
-Node: Top\7f978
-Node: Introduction\7f1506
-Node: Goals\7f2588
-Node: Tools\7f3312
-Node: History\7f4306
-Node: Building\7f7304
-Node: Getting Started\7f10567
-Node: Write configure.in\7f11080
-Node: Write Makefile.am\7f18331
-Node: Write acconfig.h\7f21508
-Node: Generate files\7f23045
-Node: Getting Started Example\7f25011
-Node: Getting Started Example 1\7f25766
-Node: Getting Started Example 2\7f27687
-Node: Getting Started Example 3\7f30682
-Node: Generate Files in Example\7f33046
-Node: Files\7f34136
-Node: Developer Files\7f34747
-Node: Developer Files Picture\7f35127
-Node: Written Developer Files\7f36415
-Node: Generated Developer Files\7f38967
-Node: Build Files\7f42111
-Node: Build Files Picture\7f42772
-Node: Build Files Description\7f43536
-Node: Support Files\7f45542
-Node: Configuration Names\7f48424
-Node: Configuration Name Definition\7f48924
-Node: Using Configuration Names\7f51247
-Node: Cross Compilation Tools\7f53217
-Node: Cross Compilation Concepts\7f53908
-Node: Host and Target\7f54876
-Node: Using the Host Type\7f56377
-Node: Specifying the Target\7f57726
-Node: Using the Target Type\7f58515
-Node: Cross Tools in the Cygnus Tree\7f61946
-Node: Host and Target Libraries\7f63003
-Node: Target Library Configure Scripts\7f66752
-Node: Make Targets in Cygnus Tree\7f69844
-Node: Target libiberty\7f71192
-Node: Canadian Cross\7f72579
-Node: Canadian Cross Example\7f73420
-Node: Canadian Cross Concepts\7f74539
-Node: Build Cross Host Tools\7f76051
-Node: Build and Host Options\7f77003
-Node: CCross not in Cygnus Tree\7f78789
-Node: CCross in Cygnus Tree\7f79767
-Node: Standard Cygnus CCross\7f80188
-Node: Cross Cygnus CCross\7f81552
-Node: Supporting Canadian Cross\7f84352
-Node: CCross in Configure\7f84967
-Node: CCross in Make\7f88135
-Node: Cygnus Configure\7f89738
-Node: Cygnus Configure Basics\7f90573
-Node: Cygnus Configure in C++ Libraries\7f95251
-Node: Multilibs\7f96258
-Node: Multilibs in gcc\7f97303
-Node: Multilibs in Target Libraries\7f98381
-Node: FAQ\7f102572
-Node: Index\7f106672
-\1f
-End Tag Table
+++ /dev/null
-This is standards.info, produced by makeinfo version 4.8 from
-.././etc/standards.texi.
-
-START-INFO-DIR-ENTRY
-* Standards: (standards). GNU coding standards.
-END-INFO-DIR-ENTRY
-
- GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
-1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-\1f
-File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
-
-Version
-*******
-
-Last updated February 14, 2002.
-
-* Menu:
-
-* Preface:: About the GNU Coding Standards
-* Legal Issues:: Keeping Free Software Free
-* Design Advice:: General Program Design
-* Program Behavior:: Program Behavior for All Programs
-* Writing C:: Making The Best Use of C
-* Documentation:: Documenting Programs
-* Managing Releases:: The Release Process
-* References:: References to Non-Free Software or Documentation
-* Copying This Manual:: How to Make Copies of This Manual
-* Index::
-
-\1f
-File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
-
-1 About the GNU Coding Standards
-********************************
-
-The GNU Coding Standards were written by Richard Stallman and other GNU
-Project volunteers. Their purpose is to make the GNU system clean,
-consistent, and easy to install. This document can also be read as a
-guide to writing portable, robust and reliable programs. It focuses on
-programs written in C, but many of the rules and principles are useful
-even if you write in another programming language. The rules often
-state reasons for writing in a certain way.
-
- This release of the GNU Coding Standards was last updated February
-14, 2002.
-
- If you did not obtain this file directly from the GNU project and
-recently, please check for a newer version. You can ftp the GNU Coding
-Standards from any GNU FTP host in the directory `/pub/gnu/standards/'.
-The GNU Coding Standards are available there in several different
-formats: `standards.text', `standards.info', and `standards.dvi', as
-well as the Texinfo "source" which is divided in two files:
-`standards.texi' and `make-stds.texi'. The GNU Coding Standards are
-also available on the GNU World Wide Web server:
-`http://www.gnu.org/prep/standards_toc.html'.
-
- Corrections or suggestions for this document should be sent to
-<bug-standards@gnu.org>. If you make a suggestion, please include a
-suggested new wording for it; our time is limited. We prefer a context
-diff to the `standards.texi' or `make-stds.texi' files, but if you
-don't have those files, please mail your suggestion anyway.
-
- These standards cover the minimum of what is important when writing a
-GNU package. Likely, the needs for additional standards will come up.
-Sometimes, you might suggest that such standards be added to this
-document. If you think your standards would be generally useful, please
-do suggest them.
-
- You should also set standards for your package on many questions not
-addressed or not firmly specified here. The most important point is to
-be self-consistent--try to stick to the conventions you pick, and try
-to document them as much as possible. That way, your program will be
-more maintainable by others.
-
-\1f
-File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
-
-2 Keeping Free Software Free
-****************************
-
-This node discusses how you can make sure that GNU software avoids
-legal difficulties, and other related issues.
-
-* Menu:
-
-* Reading Non-Free Code:: Referring to Proprietary Programs
-* Contributions:: Accepting Contributions
-* Trademarks:: How We Deal with Trademark Issues
-
-\1f
-File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
-
-2.1 Referring to Proprietary Programs
-=====================================
-
-Don't in any circumstances refer to Unix source code for or during your
-work on GNU! (Or to any other proprietary programs.)
-
- If you have a vague recollection of the internals of a Unix program,
-this does not absolutely mean you can't write an imitation of it, but
-do try to organize the imitation internally along different lines,
-because this is likely to make the details of the Unix version
-irrelevant and dissimilar to your results.
-
- For example, Unix utilities were generally optimized to minimize
-memory use; if you go for speed instead, your program will be very
-different. You could keep the entire input file in core and scan it
-there instead of using stdio. Use a smarter algorithm discovered more
-recently than the Unix program. Eliminate use of temporary files. Do
-it in one pass instead of two (we did this in the assembler).
-
- Or, on the contrary, emphasize simplicity instead of speed. For some
-applications, the speed of today's computers makes simpler algorithms
-adequate.
-
- Or go for generality. For example, Unix programs often have static
-tables or fixed-size strings, which make for arbitrary limits; use
-dynamic allocation instead. Make sure your program handles NULs and
-other funny characters in the input files. Add a programming language
-for extensibility and write part of the program in that language.
-
- Or turn some parts of the program into independently usable
-libraries. Or use a simple garbage collector instead of tracking
-precisely when to free memory, or use a new GNU facility such as
-obstacks.
-
-\1f
-File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
-
-2.2 Accepting Contributions
-===========================
-
-If the program you are working on is copyrighted by the Free Software
-Foundation, then when someone else sends you a piece of code to add to
-the program, we need legal papers to use it--just as we asked you to
-sign papers initially. _Each_ person who makes a nontrivial
-contribution to a program must sign some sort of legal papers in order
-for us to have clear title to the program; the main author alone is not
-enough.
-
- So, before adding in any contributions from other people, please tell
-us, so we can arrange to get the papers. Then wait until we tell you
-that we have received the signed papers, before you actually use the
-contribution.
-
- This applies both before you release the program and afterward. If
-you receive diffs to fix a bug, and they make significant changes, we
-need legal papers for that change.
-
- This also applies to comments and documentation files. For copyright
-law, comments and code are just text. Copyright applies to all kinds of
-text, so we need legal papers for all kinds.
-
- We know it is frustrating to ask for legal papers; it's frustrating
-for us as well. But if you don't wait, you are going out on a limb--for
-example, what if the contributor's employer won't sign a disclaimer?
-You might have to take that code out again!
-
- You don't need papers for changes of a few lines here or there, since
-they are not significant for copyright purposes. Also, you don't need
-papers if all you get from the suggestion is some ideas, not actual code
-which you use. For example, if someone send you one implementation, but
-you write a different implementation of the same idea, you don't need to
-get papers.
-
- The very worst thing is if you forget to tell us about the other
-contributor. We could be very embarrassed in court some day as a
-result.
-
- We have more detailed advice for maintainers of programs; if you have
-reached the stage of actually maintaining a program for GNU (whether
-released or not), please ask us for a copy.
-
-\1f
-File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
-
-2.3 Trademarks
-==============
-
-Please do not include any trademark acknowledgements in GNU software
-packages or documentation.
-
- Trademark acknowledgements are the statements that such-and-such is a
-trademark of so-and-so. The GNU Project has no objection to the basic
-idea of trademarks, but these acknowledgements feel like kowtowing, so
-we don't use them. There is no legal requirement for them.
-
- What is legally required, as regards other people's trademarks, is to
-avoid using them in ways which a reader might read as naming or labeling
-our own programs or activities. For example, since "Objective C" is
-(or at least was) a trademark, we made sure to say that we provide a
-"compiler for the Objective C language" rather than an "Objective C
-compiler". The latter is meant to be short for the former, but it does
-not explicitly state the relationship, so it could be misinterpreted as
-using "Objective C" as a label for the compiler rather than for the
-language.
-
-\1f
-File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
-
-3 General Program Design
-************************
-
-This node discusses some of the issues you should take into account
-when designing your program.
-
-* Menu:
-
-* Source Language:: Which languges to use.
-* Compatibility:: Compatibility with other implementations
-* Using Extensions:: Using non-standard features
-* Standard C:: Using Standard C features
-* Conditional Compilation:: Compiling Code Only If A Conditional is True
-
-\1f
-File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
-
-3.1 Which Languages to Use
-==========================
-
-When you want to use a language that gets compiled and runs at high
-speed, the best language to use is C. Using another language is like
-using a non-standard feature: it will cause trouble for users. Even if
-GCC supports the other language, users may find it inconvenient to have
-to install the compiler for that other language in order to build your
-program. For example, if you write your program in C++, people will
-have to install the GNU C++ compiler in order to compile your program.
-
- C has one other advantage over C++ and other compiled languages: more
-people know C, so more people will find it easy to read and modify the
-program if it is written in C.
-
- So in general it is much better to use C, rather than the comparable
-alternatives.
-
- But there are two exceptions to that conclusion:
-
- * It is no problem to use another language to write a tool
- specifically intended for use with that language. That is because
- the only people who want to build the tool will be those who have
- installed the other language anyway.
-
- * If an application is of interest only to a narrow part of the
- community, then the question of which language it is written in
- has less effect on other people, so you may as well please
- yourself.
-
- Many programs are designed to be extensible: they include an
-interpreter for a language that is higher level than C. Often much of
-the program is written in that language, too. The Emacs editor
-pioneered this technique.
-
- The standard extensibility interpreter for GNU software is GUILE,
-which implements the language Scheme (an especially clean and simple
-dialect of Lisp). `http://www.gnu.org/software/guile/'. We don't
-reject programs written in other "scripting languages" such as Perl and
-Python, but using GUILE is very important for the overall consistency of
-the GNU system.
-
-\1f
-File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
-
-3.2 Compatibility with Other Implementations
-============================================
-
-With occasional exceptions, utility programs and libraries for GNU
-should be upward compatible with those in Berkeley Unix, and upward
-compatible with Standard C if Standard C specifies their behavior, and
-upward compatible with POSIX if POSIX specifies their behavior.
-
- When these standards conflict, it is useful to offer compatibility
-modes for each of them.
-
- Standard C and POSIX prohibit many kinds of extensions. Feel free
-to make the extensions anyway, and include a `--ansi', `--posix', or
-`--compatible' option to turn them off. However, if the extension has
-a significant chance of breaking any real programs or scripts, then it
-is not really upward compatible. So you should try to redesign its
-interface to make it upward compatible.
-
- Many GNU programs suppress extensions that conflict with POSIX if the
-environment variable `POSIXLY_CORRECT' is defined (even if it is
-defined with a null value). Please make your program recognize this
-variable if appropriate.
-
- When a feature is used only by users (not by programs or command
-files), and it is done poorly in Unix, feel free to replace it
-completely with something totally different and better. (For example,
-`vi' is replaced with Emacs.) But it is nice to offer a compatible
-feature as well. (There is a free `vi' clone, so we offer it.)
-
- Additional useful features are welcome regardless of whether there
-is any precedent for them.
-
-\1f
-File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
-
-3.3 Using Non-standard Features
-===============================
-
-Many GNU facilities that already exist support a number of convenient
-extensions over the comparable Unix facilities. Whether to use these
-extensions in implementing your program is a difficult question.
-
- On the one hand, using the extensions can make a cleaner program.
-On the other hand, people will not be able to build the program unless
-the other GNU tools are available. This might cause the program to
-work on fewer kinds of machines.
-
- With some extensions, it might be easy to provide both alternatives.
-For example, you can define functions with a "keyword" `INLINE' and
-define that as a macro to expand into either `inline' or nothing,
-depending on the compiler.
-
- In general, perhaps it is best not to use the extensions if you can
-straightforwardly do without them, but to use the extensions if they
-are a big improvement.
-
- An exception to this rule are the large, established programs (such
-as Emacs) which run on a great variety of systems. Using GNU
-extensions in such programs would make many users unhappy, so we don't
-do that.
-
- Another exception is for programs that are used as part of
-compilation: anything that must be compiled with other compilers in
-order to bootstrap the GNU compilation facilities. If these require
-the GNU compiler, then no one can compile them without having them
-installed already. That would be extremely troublesome in certain
-cases.
-
-\1f
-File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice
-
-3.4 Standard C and Pre-Standard C
-=================================
-
-1989 Standard C is widespread enough now that it is ok to use its
-features in new programs. There is one exception: do not ever use the
-"trigraph" feature of Standard C.
-
- 1999 Standard C is not widespread yet, so please do not require its
-features in programs. It is ok to use its features if they are present.
-
- However, it is easy to support pre-standard compilers in most
-programs, so if you know how to do that, feel free. If a program you
-are maintaining has such support, you should try to keep it working.
-
- To support pre-standard C, instead of writing function definitions in
-standard prototype form,
-
- int
- foo (int x, int y)
- ...
-
-write the definition in pre-standard style like this,
-
- int
- foo (x, y)
- int x, y;
- ...
-
-and use a separate declaration to specify the argument prototype:
-
- int foo (int, int);
-
- You need such a declaration anyway, in a header file, to get the
-benefit of prototypes in all the files where the function is called.
-And once you have the declaration, you normally lose nothing by writing
-the function definition in the pre-standard style.
-
- This technique does not work for integer types narrower than `int'.
-If you think of an argument as being of a type narrower than `int',
-declare it as `int' instead.
-
- There are a few special cases where this technique is hard to use.
-For example, if a function argument needs to hold the system type
-`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
-some machines; but you cannot use `int' instead, because `dev_t' is
-wider than `int' on some machines. There is no type you can safely use
-on all machines in a non-standard definition. The only way to support
-non-standard C and pass such an argument is to check the width of
-`dev_t' using Autoconf and choose the argument type accordingly. This
-may not be worth the trouble.
-
- In order to support pre-standard compilers that do not recognize
-prototypes, you may want to use a preprocessor macro like this:
-
- /* Declare the prototype for a general external function. */
- #if defined (__STDC__) || defined (WINDOWSNT)
- #define P_(proto) proto
- #else
- #define P_(proto) ()
- #endif
-
-\1f
-File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice
-
-3.5 Conditional Compilation
-===========================
-
-When supporting configuration options already known when building your
-program we prefer using `if (... )' over conditional compilation, as in
-the former case the compiler is able to perform more extensive checking
-of all possible code paths.
-
- For example, please write
-
- if (HAS_FOO)
- ...
- else
- ...
-
- instead of:
-
- #ifdef HAS_FOO
- ...
- #else
- ...
- #endif
-
- A modern compiler such as GCC will generate exactly the same code in
-both cases, and we have been using similar techniques with good success
-in several projects.
-
- While this is not a silver bullet solving all portability problems,
-following this policy would have saved the GCC project alone many person
-hours if not days per year.
-
- In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
-which cannot be simply used in `if( ...)' statements, there is an easy
-workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
-in the following example:
-
- #ifdef REVERSIBLE_CC_MODE
- #define HAS_REVERSIBLE_CC_MODE 1
- #else
- #define HAS_REVERSIBLE_CC_MODE 0
- #endif
-
-\1f
-File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
-
-4 Program Behavior for All Programs
-***********************************
-
-This node describes conventions for writing robust software. It also
-describes general standards for error messages, the command line
-interface, and how libraries should behave.
-
-* Menu:
-
-* Semantics:: Writing robust programs
-* Libraries:: Library behavior
-* Errors:: Formatting error messages
-* User Interfaces:: Standards about interfaces generally
-* Graphical Interfaces:: Standards for graphical interfaces
-* Command-Line Interfaces:: Standards for command line interfaces
-* Option Table:: Table of long options
-* Memory Usage:: When and how to care about memory needs
-* File Usage:: Which files to use, and where
-
-\1f
-File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior
-
-4.1 Writing Robust Programs
-===========================
-
-Avoid arbitrary limits on the length or number of _any_ data structure,
-including file names, lines, files, and symbols, by allocating all data
-structures dynamically. In most Unix utilities, "long lines are
-silently truncated". This is not acceptable in a GNU utility.
-
- Utilities reading files should not drop NUL characters, or any other
-nonprinting characters _including those with codes above 0177_. The
-only sensible exceptions would be utilities specifically intended for
-interface to certain types of terminals or printers that can't handle
-those characters. Whenever possible, try to make programs work
-properly with sequences of bytes that represent multibyte characters,
-using encodings such as UTF-8 and others.
-
- Check every system call for an error return, unless you know you
-wish to ignore errors. Include the system error text (from `perror' or
-equivalent) in _every_ error message resulting from a failing system
-call, as well as the name of the file if any and the name of the
-utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
-
- Check every call to `malloc' or `realloc' to see if it returned
-zero. Check `realloc' even if you are making the block smaller; in a
-system that rounds block sizes to a power of 2, `realloc' may get a
-different block if you ask for less space.
-
- In Unix, `realloc' can destroy the storage block if it returns zero.
-GNU `realloc' does not have this bug: if it fails, the original block
-is unchanged. Feel free to assume the bug is fixed. If you wish to
-run your program on Unix, and wish to avoid lossage in this case, you
-can use the GNU `malloc'.
-
- You must expect `free' to alter the contents of the block that was
-freed. Anything you want to fetch from the block, you must fetch before
-calling `free'.
-
- If `malloc' fails in a noninteractive program, make that a fatal
-error. In an interactive program (one that reads commands from the
-user), it is better to abort the command and return to the command
-reader loop. This allows the user to kill other processes to free up
-virtual memory, and then try the command again.
-
- Use `getopt_long' to decode arguments, unless the argument syntax
-makes this unreasonable.
-
- When static storage is to be written in during program execution, use
-explicit C code to initialize it. Reserve C initialized declarations
-for data that will not be changed.
-
- Try to avoid low-level interfaces to obscure Unix data structures
-(such as file directories, utmp, or the layout of kernel memory), since
-these are less likely to work compatibly. If you need to find all the
-files in a directory, use `readdir' or some other high-level interface.
-These are supported compatibly by GNU.
-
- The preferred signal handling facilities are the BSD variant of
-`signal', and the POSIX `sigaction' function; the alternative USG
-`signal' interface is an inferior design.
-
- Nowadays, using the POSIX signal functions may be the easiest way to
-make a program portable. If you use `signal', then on GNU/Linux
-systems running GNU libc version 1, you should include `bsd/signal.h'
-instead of `signal.h', so as to get BSD behavior. It is up to you
-whether to support systems where `signal' has only the USG behavior, or
-give up on them.
-
- In error checks that detect "impossible" conditions, just abort.
-There is usually no point in printing any message. These checks
-indicate the existence of bugs. Whoever wants to fix the bugs will have
-to read the source code and run a debugger. So explain the problem with
-comments in the source. The relevant data will be in variables, which
-are easy to examine with the debugger, so there is no point moving them
-elsewhere.
-
- Do not use a count of errors as the exit status for a program.
-_That does not work_, because exit status values are limited to 8 bits
-(0 through 255). A single run of the program might have 256 errors; if
-you try to return 256 as the exit status, the parent process will see 0
-as the status, and it will appear that the program succeeded.
-
- If you make temporary files, check the `TMPDIR' environment
-variable; if that variable is defined, use the specified directory
-instead of `/tmp'.
-
- In addition, be aware that there is a possible security problem when
-creating temporary files in world-writable directories. In C, you can
-avoid this problem by creating temporary files in this manner:
-
- fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
-
-or by using the `mkstemps' function from libiberty.
-
- In bash, use `set -C' to avoid this problem.
-
-\1f
-File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
-
-4.2 Library Behavior
-====================
-
-Try to make library functions reentrant. If they need to do dynamic
-storage allocation, at least try to avoid any nonreentrancy aside from
-that of `malloc' itself.
-
- Here are certain name conventions for libraries, to avoid name
-conflicts.
-
- Choose a name prefix for the library, more than two characters long.
-All external function and variable names should start with this prefix.
-In addition, there should only be one of these in any given library
-member. This usually means putting each one in a separate source file.
-
- An exception can be made when two external symbols are always used
-together, so that no reasonable program could use one without the
-other; then they can both go in the same file.
-
- External symbols that are not documented entry points for the user
-should have names beginning with `_'. The `_' should be followed by
-the chosen name prefix for the library, to prevent collisions with
-other libraries. These can go in the same files with user entry points
-if you like.
-
- Static functions and variables can be used as you like and need not
-fit any naming convention.
-
-\1f
-File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
-
-4.3 Formatting Error Messages
-=============================
-
-Error messages from compilers should look like this:
-
- SOURCE-FILE-NAME:LINENO: MESSAGE
-
-If you want to mention the column number, use this format:
-
- SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
-
-Line numbers should start from 1 at the beginning of the file, and
-column numbers should start from 1 at the beginning of the line. (Both
-of these conventions are chosen for compatibility.) Calculate column
-numbers assuming that space and all ASCII printing characters have
-equal width, and assuming tab stops every 8 columns.
-
- Error messages from other noninteractive programs should look like
-this:
-
- PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
-
-when there is an appropriate source file, or like this:
-
- PROGRAM: MESSAGE
-
-when there is no relevant source file.
-
- If you want to mention the column number, use this format:
-
- PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
-
- In an interactive program (one that is reading commands from a
-terminal), it is better not to include the program name in an error
-message. The place to indicate which program is running is in the
-prompt or with the screen layout. (When the same program runs with
-input from a source other than a terminal, it is not interactive and
-would do best to print error messages using the noninteractive style.)
-
- The string MESSAGE should not begin with a capital letter when it
-follows a program name and/or file name. Also, it should not end with
-a period.
-
- Error messages from interactive programs, and other messages such as
-usage messages, should start with a capital letter. But they should not
-end with a period.
-
-\1f
-File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
-
-4.4 Standards for Interfaces Generally
-======================================
-
-Please don't make the behavior of a utility depend on the name used to
-invoke it. It is useful sometimes to make a link to a utility with a
-different name, and that should not change what it does.
-
- Instead, use a run time option or a compilation switch or both to
-select among the alternate behaviors.
-
- Likewise, please don't make the behavior of the program depend on the
-type of output device it is used with. Device independence is an
-important principle of the system's design; do not compromise it merely
-to save someone from typing an option now and then. (Variation in error
-message syntax when using a terminal is ok, because that is a side issue
-that people do not depend on.)
-
- If you think one behavior is most useful when the output is to a
-terminal, and another is most useful when the output is a file or a
-pipe, then it is usually best to make the default behavior the one that
-is useful with output to a terminal, and have an option for the other
-behavior.
-
- Compatibility requires certain programs to depend on the type of
-output device. It would be disastrous if `ls' or `sh' did not do so in
-the way all users expect. In some of these cases, we supplement the
-program with a preferred alternate version that does not depend on the
-output device type. For example, we provide a `dir' program much like
-`ls' except that its default output format is always multi-column
-format.
-
-\1f
-File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
-
-4.5 Standards for Graphical Interfaces
-======================================
-
-When you write a program that provides a graphical user interface,
-please make it work with X Windows and the GTK toolkit unless the
-functionality specifically requires some alternative (for example,
-"displaying jpeg images while in console mode").
-
- In addition, please provide a command-line interface to control the
-functionality. (In many cases, the graphical user interface can be a
-separate program which invokes the command-line program.) This is so
-that the same jobs can be done from scripts.
-
- Please also consider providing a CORBA interface (for use from
-GNOME), a library interface (for use from C), and perhaps a
-keyboard-driven console interface (for use by users from console mode).
-Once you are doing the work to provide the functionality and the
-graphical interface, these won't be much extra work.
-
-\1f
-File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
-
-4.6 Standards for Command Line Interfaces
-=========================================
-
-It is a good idea to follow the POSIX guidelines for the command-line
-options of a program. The easiest way to do this is to use `getopt' to
-parse them. Note that the GNU version of `getopt' will normally permit
-options anywhere among the arguments unless the special argument `--'
-is used. This is not what POSIX specifies; it is a GNU extension.
-
- Please define long-named options that are equivalent to the
-single-letter Unix-style options. We hope to make GNU more user
-friendly this way. This is easy to do with the GNU function
-`getopt_long'.
-
- One of the advantages of long-named options is that they can be
-consistent from program to program. For example, users should be able
-to expect the "verbose" option of any GNU program which has one, to be
-spelled precisely `--verbose'. To achieve this uniformity, look at the
-table of common long-option names when you choose the option names for
-your program (*note Option Table::).
-
- It is usually a good idea for file names given as ordinary arguments
-to be input files only; any output files would be specified using
-options (preferably `-o' or `--output'). Even if you allow an output
-file name as an ordinary argument for compatibility, try to provide an
-option as another way to specify it. This will lead to more consistency
-among GNU utilities, and fewer idiosyncracies for users to remember.
-
- All programs should support two standard options: `--version' and
-`--help'.
-
-`--version'
- This option should direct the program to print information about
- its name, version, origin and legal status, all on standard
- output, and then exit successfully. Other options and arguments
- should be ignored once this is seen, and the program should not
- perform its normal function.
-
- The first line is meant to be easy for a program to parse; the
- version number proper starts after the last space. In addition,
- it contains the canonical name for this program, in this format:
-
- GNU Emacs 19.30
-
- The program's name should be a constant string; _don't_ compute it
- from `argv[0]'. The idea is to state the standard or canonical
- name for the program, not its file name. There are other ways to
- find out the precise file name where a command is found in `PATH'.
-
- If the program is a subsidiary part of a larger package, mention
- the package name in parentheses, like this:
-
- emacsserver (GNU Emacs) 19.30
-
- If the package has a version number which is different from this
- program's version number, you can mention the package version
- number just before the close-parenthesis.
-
- If you *need* to mention the version numbers of libraries which
- are distributed separately from the package which contains this
- program, you can do so by printing an additional line of version
- info for each library you want to mention. Use the same format
- for these lines as for the first line.
-
- Please do not mention all of the libraries that the program uses
- "just for completeness"--that would produce a lot of unhelpful
- clutter. Please mention library version numbers only if you find
- in practice that they are very important to you in debugging.
-
- The following line, after the version number line or lines, should
- be a copyright notice. If more than one copyright notice is
- called for, put each on a separate line.
-
- Next should follow a brief statement that the program is free
- software, and that users are free to copy and change it on certain
- conditions. If the program is covered by the GNU GPL, say so
- here. Also mention that there is no warranty, to the extent
- permitted by law.
-
- It is ok to finish the output with a list of the major authors of
- the program, as a way of giving credit.
-
- Here's an example of output that follows these rules:
-
- GNU Emacs 19.34.5
- Copyright (C) 1996 Free Software Foundation, Inc.
- GNU Emacs comes with NO WARRANTY,
- to the extent permitted by law.
- You may redistribute copies of GNU Emacs
- under the terms of the GNU General Public License.
- For more information about these matters,
- see the files named COPYING.
-
- You should adapt this to your program, of course, filling in the
- proper year, copyright holder, name of program, and the references
- to distribution terms, and changing the rest of the wording as
- necessary.
-
- This copyright notice only needs to mention the most recent year in
- which changes were made--there's no need to list the years for
- previous versions' changes. You don't have to mention the name of
- the program in these notices, if that is inconvenient, since it
- appeared in the first line.
-
- Translations of the above lines must preserve the validity of the
- copyright notices (*note Internationalization::). If the
- translation's character set supports it, the `(C)' should be
- replaced with the copyright symbol, as follows:
-
- (the official copyright symbol, which is the letter C in a circle);
-
- Write the word "Copyright" exactly like that, in English. Do not
- translate it into another language. International treaties
- recognize the English word "Copyright"; translations into other
- languages do not have legal significance.
-
-`--help'
- This option should output brief documentation for how to invoke the
- program, on standard output, then exit successfully. Other
- options and arguments should be ignored once this is seen, and the
- program should not perform its normal function.
-
- Near the end of the `--help' option's output there should be a line
- that says where to mail bug reports. It should have this format:
-
- Report bugs to MAILING-ADDRESS.
-
-\1f
-File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior
-
-4.7 Table of Long Options
-=========================
-
-Here is a table of long options used by GNU programs. It is surely
-incomplete, but we aim to list all the options that a new program might
-want to be compatible with. If you use names not already in the table,
-please send <bug-standards@gnu.org> a list of them, with their
-meanings, so we can update the table.
-
-`after-date'
- `-N' in `tar'.
-
-`all'
- `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
-
-`all-text'
- `-a' in `diff'.
-
-`almost-all'
- `-A' in `ls'.
-
-`append'
- `-a' in `etags', `tee', `time'; `-r' in `tar'.
-
-`archive'
- `-a' in `cp'.
-
-`archive-name'
- `-n' in `shar'.
-
-`arglength'
- `-l' in `m4'.
-
-`ascii'
- `-a' in `diff'.
-
-`assign'
- `-v' in `gawk'.
-
-`assume-new'
- `-W' in Make.
-
-`assume-old'
- `-o' in Make.
-
-`auto-check'
- `-a' in `recode'.
-
-`auto-pager'
- `-a' in `wdiff'.
-
-`auto-reference'
- `-A' in `ptx'.
-
-`avoid-wraps'
- `-n' in `wdiff'.
-
-`background'
- For server programs, run in the background.
-
-`backward-search'
- `-B' in `ctags'.
-
-`basename'
- `-f' in `shar'.
-
-`batch'
- Used in GDB.
-
-`baud'
- Used in GDB.
-
-`before'
- `-b' in `tac'.
-
-`binary'
- `-b' in `cpio' and `diff'.
-
-`bits-per-code'
- `-b' in `shar'.
-
-`block-size'
- Used in `cpio' and `tar'.
-
-`blocks'
- `-b' in `head' and `tail'.
-
-`break-file'
- `-b' in `ptx'.
-
-`brief'
- Used in various programs to make output shorter.
-
-`bytes'
- `-c' in `head', `split', and `tail'.
-
-`c++'
- `-C' in `etags'.
-
-`catenate'
- `-A' in `tar'.
-
-`cd'
- Used in various programs to specify the directory to use.
-
-`changes'
- `-c' in `chgrp' and `chown'.
-
-`classify'
- `-F' in `ls'.
-
-`colons'
- `-c' in `recode'.
-
-`command'
- `-c' in `su'; `-x' in GDB.
-
-`compare'
- `-d' in `tar'.
-
-`compat'
- Used in `gawk'.
-
-`compress'
- `-Z' in `tar' and `shar'.
-
-`concatenate'
- `-A' in `tar'.
-
-`confirmation'
- `-w' in `tar'.
-
-`context'
- Used in `diff'.
-
-`copyleft'
- `-W copyleft' in `gawk'.
-
-`copyright'
- `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
-
-`core'
- Used in GDB.
-
-`count'
- `-q' in `who'.
-
-`count-links'
- `-l' in `du'.
-
-`create'
- Used in `tar' and `cpio'.
-
-`cut-mark'
- `-c' in `shar'.
-
-`cxref'
- `-x' in `ctags'.
-
-`date'
- `-d' in `touch'.
-
-`debug'
- `-d' in Make and `m4'; `-t' in Bison.
-
-`define'
- `-D' in `m4'.
-
-`defines'
- `-d' in Bison and `ctags'.
-
-`delete'
- `-D' in `tar'.
-
-`dereference'
- `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
-
-`dereference-args'
- `-D' in `du'.
-
-`device'
- Specify an I/O device (special file name).
-
-`diacritics'
- `-d' in `recode'.
-
-`dictionary-order'
- `-d' in `look'.
-
-`diff'
- `-d' in `tar'.
-
-`digits'
- `-n' in `csplit'.
-
-`directory'
- Specify the directory to use, in various programs. In `ls', it
- means to show directories themselves rather than their contents.
- In `rm' and `ln', it means to not treat links to directories
- specially.
-
-`discard-all'
- `-x' in `strip'.
-
-`discard-locals'
- `-X' in `strip'.
-
-`dry-run'
- `-n' in Make.
-
-`ed'
- `-e' in `diff'.
-
-`elide-empty-files'
- `-z' in `csplit'.
-
-`end-delete'
- `-x' in `wdiff'.
-
-`end-insert'
- `-z' in `wdiff'.
-
-`entire-new-file'
- `-N' in `diff'.
-
-`environment-overrides'
- `-e' in Make.
-
-`eof'
- `-e' in `xargs'.
-
-`epoch'
- Used in GDB.
-
-`error-limit'
- Used in `makeinfo'.
-
-`error-output'
- `-o' in `m4'.
-
-`escape'
- `-b' in `ls'.
-
-`exclude-from'
- `-X' in `tar'.
-
-`exec'
- Used in GDB.
-
-`exit'
- `-x' in `xargs'.
-
-`exit-0'
- `-e' in `unshar'.
-
-`expand-tabs'
- `-t' in `diff'.
-
-`expression'
- `-e' in `sed'.
-
-`extern-only'
- `-g' in `nm'.
-
-`extract'
- `-i' in `cpio'; `-x' in `tar'.
-
-`faces'
- `-f' in `finger'.
-
-`fast'
- `-f' in `su'.
-
-`fatal-warnings'
- `-E' in `m4'.
-
-`file'
- `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
- in `touch'.
-
-`field-separator'
- `-F' in `gawk'.
-
-`file-prefix'
- `-b' in Bison.
-
-`file-type'
- `-F' in `ls'.
-
-`files-from'
- `-T' in `tar'.
-
-`fill-column'
- Used in `makeinfo'.
-
-`flag-truncation'
- `-F' in `ptx'.
-
-`fixed-output-files'
- `-y' in Bison.
-
-`follow'
- `-f' in `tail'.
-
-`footnote-style'
- Used in `makeinfo'.
-
-`force'
- `-f' in `cp', `ln', `mv', and `rm'.
-
-`force-prefix'
- `-F' in `shar'.
-
-`foreground'
- For server programs, run in the foreground; in other words, don't
- do anything special to run the server in the background.
-
-`format'
- Used in `ls', `time', and `ptx'.
-
-`freeze-state'
- `-F' in `m4'.
-
-`fullname'
- Used in GDB.
-
-`gap-size'
- `-g' in `ptx'.
-
-`get'
- `-x' in `tar'.
-
-`graphic'
- `-i' in `ul'.
-
-`graphics'
- `-g' in `recode'.
-
-`group'
- `-g' in `install'.
-
-`gzip'
- `-z' in `tar' and `shar'.
-
-`hashsize'
- `-H' in `m4'.
-
-`header'
- `-h' in `objdump' and `recode'
-
-`heading'
- `-H' in `who'.
-
-`help'
- Used to ask for brief usage information.
-
-`here-delimiter'
- `-d' in `shar'.
-
-`hide-control-chars'
- `-q' in `ls'.
-
-`html'
- In `makeinfo', output HTML.
-
-`idle'
- `-u' in `who'.
-
-`ifdef'
- `-D' in `diff'.
-
-`ignore'
- `-I' in `ls'; `-x' in `recode'.
-
-`ignore-all-space'
- `-w' in `diff'.
-
-`ignore-backups'
- `-B' in `ls'.
-
-`ignore-blank-lines'
- `-B' in `diff'.
-
-`ignore-case'
- `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
-
-`ignore-errors'
- `-i' in Make.
-
-`ignore-file'
- `-i' in `ptx'.
-
-`ignore-indentation'
- `-I' in `etags'.
-
-`ignore-init-file'
- `-f' in Oleo.
-
-`ignore-interrupts'
- `-i' in `tee'.
-
-`ignore-matching-lines'
- `-I' in `diff'.
-
-`ignore-space-change'
- `-b' in `diff'.
-
-`ignore-zeros'
- `-i' in `tar'.
-
-`include'
- `-i' in `etags'; `-I' in `m4'.
-
-`include-dir'
- `-I' in Make.
-
-`incremental'
- `-G' in `tar'.
-
-`info'
- `-i', `-l', and `-m' in Finger.
-
-`init-file'
- In some programs, specify the name of the file to read as the
- user's init file.
-
-`initial'
- `-i' in `expand'.
-
-`initial-tab'
- `-T' in `diff'.
-
-`inode'
- `-i' in `ls'.
-
-`interactive'
- `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
- `-w' in `tar'.
-
-`intermix-type'
- `-p' in `shar'.
-
-`iso-8601'
- Used in `date'
-
-`jobs'
- `-j' in Make.
-
-`just-print'
- `-n' in Make.
-
-`keep-going'
- `-k' in Make.
-
-`keep-files'
- `-k' in `csplit'.
-
-`kilobytes'
- `-k' in `du' and `ls'.
-
-`language'
- `-l' in `etags'.
-
-`less-mode'
- `-l' in `wdiff'.
-
-`level-for-gzip'
- `-g' in `shar'.
-
-`line-bytes'
- `-C' in `split'.
-
-`lines'
- Used in `split', `head', and `tail'.
-
-`link'
- `-l' in `cpio'.
-
-`lint'
-`lint-old'
- Used in `gawk'.
-
-`list'
- `-t' in `cpio'; `-l' in `recode'.
-
-`list'
- `-t' in `tar'.
-
-`literal'
- `-N' in `ls'.
-
-`load-average'
- `-l' in Make.
-
-`login'
- Used in `su'.
-
-`machine'
- No listing of which programs already use this; someone should
- check to see if any actually do, and tell <gnu@gnu.org>.
-
-`macro-name'
- `-M' in `ptx'.
-
-`mail'
- `-m' in `hello' and `uname'.
-
-`make-directories'
- `-d' in `cpio'.
-
-`makefile'
- `-f' in Make.
-
-`mapped'
- Used in GDB.
-
-`max-args'
- `-n' in `xargs'.
-
-`max-chars'
- `-n' in `xargs'.
-
-`max-lines'
- `-l' in `xargs'.
-
-`max-load'
- `-l' in Make.
-
-`max-procs'
- `-P' in `xargs'.
-
-`mesg'
- `-T' in `who'.
-
-`message'
- `-T' in `who'.
-
-`minimal'
- `-d' in `diff'.
-
-`mixed-uuencode'
- `-M' in `shar'.
-
-`mode'
- `-m' in `install', `mkdir', and `mkfifo'.
-
-`modification-time'
- `-m' in `tar'.
-
-`multi-volume'
- `-M' in `tar'.
-
-`name-prefix'
- `-a' in Bison.
-
-`nesting-limit'
- `-L' in `m4'.
-
-`net-headers'
- `-a' in `shar'.
-
-`new-file'
- `-W' in Make.
-
-`no-builtin-rules'
- `-r' in Make.
-
-`no-character-count'
- `-w' in `shar'.
-
-`no-check-existing'
- `-x' in `shar'.
-
-`no-common'
- `-3' in `wdiff'.
-
-`no-create'
- `-c' in `touch'.
-
-`no-defines'
- `-D' in `etags'.
-
-`no-deleted'
- `-1' in `wdiff'.
-
-`no-dereference'
- `-d' in `cp'.
-
-`no-inserted'
- `-2' in `wdiff'.
-
-`no-keep-going'
- `-S' in Make.
-
-`no-lines'
- `-l' in Bison.
-
-`no-piping'
- `-P' in `shar'.
-
-`no-prof'
- `-e' in `gprof'.
-
-`no-regex'
- `-R' in `etags'.
-
-`no-sort'
- `-p' in `nm'.
-
-`no-split'
- Used in `makeinfo'.
-
-`no-static'
- `-a' in `gprof'.
-
-`no-time'
- `-E' in `gprof'.
-
-`no-timestamp'
- `-m' in `shar'.
-
-`no-validate'
- Used in `makeinfo'.
-
-`no-wait'
- Used in `emacsclient'.
-
-`no-warn'
- Used in various programs to inhibit warnings.
-
-`node'
- `-n' in `info'.
-
-`nodename'
- `-n' in `uname'.
-
-`nonmatching'
- `-f' in `cpio'.
-
-`nstuff'
- `-n' in `objdump'.
-
-`null'
- `-0' in `xargs'.
-
-`number'
- `-n' in `cat'.
-
-`number-nonblank'
- `-b' in `cat'.
-
-`numeric-sort'
- `-n' in `nm'.
-
-`numeric-uid-gid'
- `-n' in `cpio' and `ls'.
-
-`nx'
- Used in GDB.
-
-`old-archive'
- `-o' in `tar'.
-
-`old-file'
- `-o' in Make.
-
-`one-file-system'
- `-l' in `tar', `cp', and `du'.
-
-`only-file'
- `-o' in `ptx'.
-
-`only-prof'
- `-f' in `gprof'.
-
-`only-time'
- `-F' in `gprof'.
-
-`options'
- `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
-
-`output'
- In various programs, specify the output file name.
-
-`output-prefix'
- `-o' in `shar'.
-
-`override'
- `-o' in `rm'.
-
-`overwrite'
- `-c' in `unshar'.
-
-`owner'
- `-o' in `install'.
-
-`paginate'
- `-l' in `diff'.
-
-`paragraph-indent'
- Used in `makeinfo'.
-
-`parents'
- `-p' in `mkdir' and `rmdir'.
-
-`pass-all'
- `-p' in `ul'.
-
-`pass-through'
- `-p' in `cpio'.
-
-`port'
- `-P' in `finger'.
-
-`portability'
- `-c' in `cpio' and `tar'.
-
-`posix'
- Used in `gawk'.
-
-`prefix-builtins'
- `-P' in `m4'.
-
-`prefix'
- `-f' in `csplit'.
-
-`preserve'
- Used in `tar' and `cp'.
-
-`preserve-environment'
- `-p' in `su'.
-
-`preserve-modification-time'
- `-m' in `cpio'.
-
-`preserve-order'
- `-s' in `tar'.
-
-`preserve-permissions'
- `-p' in `tar'.
-
-`print'
- `-l' in `diff'.
-
-`print-chars'
- `-L' in `cmp'.
-
-`print-data-base'
- `-p' in Make.
-
-`print-directory'
- `-w' in Make.
-
-`print-file-name'
- `-o' in `nm'.
-
-`print-symdefs'
- `-s' in `nm'.
-
-`printer'
- `-p' in `wdiff'.
-
-`prompt'
- `-p' in `ed'.
-
-`proxy'
- Specify an HTTP proxy.
-
-`query-user'
- `-X' in `shar'.
-
-`question'
- `-q' in Make.
-
-`quiet'
- Used in many programs to inhibit the usual output. *Note_* every
- program accepting `--quiet' should accept `--silent' as a synonym.
-
-`quiet-unshar'
- `-Q' in `shar'
-
-`quote-name'
- `-Q' in `ls'.
-
-`rcs'
- `-n' in `diff'.
-
-`re-interval'
- Used in `gawk'.
-
-`read-full-blocks'
- `-B' in `tar'.
-
-`readnow'
- Used in GDB.
-
-`recon'
- `-n' in Make.
-
-`record-number'
- `-R' in `tar'.
-
-`recursive'
- Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
-
-`reference-limit'
- Used in `makeinfo'.
-
-`references'
- `-r' in `ptx'.
-
-`regex'
- `-r' in `tac' and `etags'.
-
-`release'
- `-r' in `uname'.
-
-`reload-state'
- `-R' in `m4'.
-
-`relocation'
- `-r' in `objdump'.
-
-`rename'
- `-r' in `cpio'.
-
-`replace'
- `-i' in `xargs'.
-
-`report-identical-files'
- `-s' in `diff'.
-
-`reset-access-time'
- `-a' in `cpio'.
-
-`reverse'
- `-r' in `ls' and `nm'.
-
-`reversed-ed'
- `-f' in `diff'.
-
-`right-side-defs'
- `-R' in `ptx'.
-
-`same-order'
- `-s' in `tar'.
-
-`same-permissions'
- `-p' in `tar'.
-
-`save'
- `-g' in `stty'.
-
-`se'
- Used in GDB.
-
-`sentence-regexp'
- `-S' in `ptx'.
-
-`separate-dirs'
- `-S' in `du'.
-
-`separator'
- `-s' in `tac'.
-
-`sequence'
- Used by `recode' to chose files or pipes for sequencing passes.
-
-`shell'
- `-s' in `su'.
-
-`show-all'
- `-A' in `cat'.
-
-`show-c-function'
- `-p' in `diff'.
-
-`show-ends'
- `-E' in `cat'.
-
-`show-function-line'
- `-F' in `diff'.
-
-`show-tabs'
- `-T' in `cat'.
-
-`silent'
- Used in many programs to inhibit the usual output. *Note_* every
- program accepting `--silent' should accept `--quiet' as a synonym.
-
-`size'
- `-s' in `ls'.
-
-`socket'
- Specify a file descriptor for a network server to use for its
- socket, instead of opening and binding a new socket. This
- provides a way to run, in a nonpriveledged process, a server that
- normally needs a reserved port number.
-
-`sort'
- Used in `ls'.
-
-`source'
- `-W source' in `gawk'.
-
-`sparse'
- `-S' in `tar'.
-
-`speed-large-files'
- `-H' in `diff'.
-
-`split-at'
- `-E' in `unshar'.
-
-`split-size-limit'
- `-L' in `shar'.
-
-`squeeze-blank'
- `-s' in `cat'.
-
-`start-delete'
- `-w' in `wdiff'.
-
-`start-insert'
- `-y' in `wdiff'.
-
-`starting-file'
- Used in `tar' and `diff' to specify which file within a directory
- to start processing with.
-
-`statistics'
- `-s' in `wdiff'.
-
-`stdin-file-list'
- `-S' in `shar'.
-
-`stop'
- `-S' in Make.
-
-`strict'
- `-s' in `recode'.
-
-`strip'
- `-s' in `install'.
-
-`strip-all'
- `-s' in `strip'.
-
-`strip-debug'
- `-S' in `strip'.
-
-`submitter'
- `-s' in `shar'.
-
-`suffix'
- `-S' in `cp', `ln', `mv'.
-
-`suffix-format'
- `-b' in `csplit'.
-
-`sum'
- `-s' in `gprof'.
-
-`summarize'
- `-s' in `du'.
-
-`symbolic'
- `-s' in `ln'.
-
-`symbols'
- Used in GDB and `objdump'.
-
-`synclines'
- `-s' in `m4'.
-
-`sysname'
- `-s' in `uname'.
-
-`tabs'
- `-t' in `expand' and `unexpand'.
-
-`tabsize'
- `-T' in `ls'.
-
-`terminal'
- `-T' in `tput' and `ul'. `-t' in `wdiff'.
-
-`text'
- `-a' in `diff'.
-
-`text-files'
- `-T' in `shar'.
-
-`time'
- Used in `ls' and `touch'.
-
-`timeout'
- Specify how long to wait before giving up on some operation.
-
-`to-stdout'
- `-O' in `tar'.
-
-`total'
- `-c' in `du'.
-
-`touch'
- `-t' in Make, `ranlib', and `recode'.
-
-`trace'
- `-t' in `m4'.
-
-`traditional'
- `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
- and `ptx'.
-
-`tty'
- Used in GDB.
-
-`typedefs'
- `-t' in `ctags'.
-
-`typedefs-and-c++'
- `-T' in `ctags'.
-
-`typeset-mode'
- `-t' in `ptx'.
-
-`uncompress'
- `-z' in `tar'.
-
-`unconditional'
- `-u' in `cpio'.
-
-`undefine'
- `-U' in `m4'.
-
-`undefined-only'
- `-u' in `nm'.
-
-`update'
- `-u' in `cp', `ctags', `mv', `tar'.
-
-`usage'
- Used in `gawk'; same as `--help'.
-
-`uuencode'
- `-B' in `shar'.
-
-`vanilla-operation'
- `-V' in `shar'.
-
-`verbose'
- Print more information about progress. Many programs support this.
-
-`verify'
- `-W' in `tar'.
-
-`version'
- Print the version number.
-
-`version-control'
- `-V' in `cp', `ln', `mv'.
-
-`vgrind'
- `-v' in `ctags'.
-
-`volume'
- `-V' in `tar'.
-
-`what-if'
- `-W' in Make.
-
-`whole-size-limit'
- `-l' in `shar'.
-
-`width'
- `-w' in `ls' and `ptx'.
-
-`word-regexp'
- `-W' in `ptx'.
-
-`writable'
- `-T' in `who'.
-
-`zeros'
- `-z' in `gprof'.
-
-\1f
-File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior
-
-4.8 Memory Usage
-================
-
-If a program typically uses just a few meg of memory, don't bother
-making any effort to reduce memory usage. For example, if it is
-impractical for other reasons to operate on files more than a few meg
-long, it is reasonable to read entire input files into core to operate
-on them.
-
- However, for programs such as `cat' or `tail', that can usefully
-operate on very large files, it is important to avoid using a technique
-that would artificially limit the size of files it can handle. If a
-program works by lines and could be applied to arbitrary user-supplied
-input files, it should keep only a line in memory, because this is not
-very hard and users will want to be able to operate on input files that
-are bigger than will fit in core all at once.
-
- If your program creates complicated data structures, just make them
-in core and give a fatal error if `malloc' returns zero.
-
-\1f
-File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
-
-4.9 File Usage
-==============
-
-Programs should be prepared to operate when `/usr' and `/etc' are
-read-only file systems. Thus, if the program manages log files, lock
-files, backup files, score files, or any other files which are modified
-for internal purposes, these files should not be stored in `/usr' or
-`/etc'.
-
- There are two exceptions. `/etc' is used to store system
-configuration information; it is reasonable for a program to modify
-files in `/etc' when its job is to update the system configuration.
-Also, if the user explicitly asks to modify one file in a directory, it
-is reasonable for the program to store other files in the same
-directory.
-
-\1f
-File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
-
-5 Making The Best Use of C
-**************************
-
-This node provides advice on how best to use the C language when
-writing GNU software.
-
-* Menu:
-
-* Formatting:: Formatting Your Source Code
-* Comments:: Commenting Your Work
-* Syntactic Conventions:: Clean Use of C Constructs
-* Names:: Naming Variables, Functions, and Files
-* System Portability:: Portability between different operating systems
-* CPU Portability:: Supporting the range of CPU types
-* System Functions:: Portability and ``standard'' library functions
-* Internationalization:: Techniques for internationalization
-* Mmap:: How you can safely use `mmap'.
-
-\1f
-File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
-
-5.1 Formatting Your Source Code
-===============================
-
-It is important to put the open-brace that starts the body of a C
-function in column zero, and avoid putting any other open-brace or
-open-parenthesis or open-bracket in column zero. Several tools look
-for open-braces in column zero to find the beginnings of C functions.
-These tools will not work on code not formatted that way.
-
- It is also important for function definitions to start the name of
-the function in column zero. This helps people to search for function
-definitions, and may also help certain tools recognize them. Thus, the
-proper format is this:
-
- static char *
- concat (s1, s2) /* Name starts in column zero here */
- char *s1, *s2;
- { /* Open brace in column zero here */
- ...
- }
-
-or, if you want to use Standard C syntax, format the definition like
-this:
-
- static char *
- concat (char *s1, char *s2)
- {
- ...
- }
-
- In Standard C, if the arguments don't fit nicely on one line, split
-it like this:
-
- int
- lots_of_args (int an_integer, long a_long, short a_short,
- double a_double, float a_float)
- ...
-
- The rest of this section gives our recommendations for other aspects
-of C formatting style, which is also the default style of the `indent'
-program in version 1.2 and newer. It corresponds to the options
-
- -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
- -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
-
- We don't think of these recommendations as requirements, because it
-causes no problems for users if two different programs have different
-formatting styles.
-
- But whatever style you use, please use it consistently, since a
-mixture of styles within one program tends to look ugly. If you are
-contributing changes to an existing program, please follow the style of
-that program.
-
- For the body of the function, our recommended style looks like this:
-
- if (x < foo (y, z))
- haha = bar[4] + 5;
- else
- {
- while (z)
- {
- haha += foo (z, z);
- z--;
- }
- return ++x + bar ();
- }
-
- We find it easier to read a program when it has spaces before the
-open-parentheses and after the commas. Especially after the commas.
-
- When you split an expression into multiple lines, split it before an
-operator, not after one. Here is the right way:
-
- if (foo_this_is_long && bar > win (x, y, z)
- && remaining_condition)
-
- Try to avoid having two operators of different precedence at the same
-level of indentation. For example, don't write this:
-
- mode = (inmode[j] == VOIDmode
- || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
- ? outmode[j] : inmode[j]);
-
- Instead, use extra parentheses so that the indentation shows the
-nesting:
-
- mode = ((inmode[j] == VOIDmode
- || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
- ? outmode[j] : inmode[j]);
-
- Insert extra parentheses so that Emacs will indent the code properly.
-For example, the following indentation looks nice if you do it by hand,
-
- v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
- + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
-
-but Emacs would alter it. Adding a set of parentheses produces
-something that looks equally nice, and which Emacs will preserve:
-
- v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
- + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
-
- Format do-while statements like this:
-
- do
- {
- a = foo (a);
- }
- while (a > 0);
-
- Please use formfeed characters (control-L) to divide the program into
-pages at logical places (but not within a function). It does not matter
-just how long the pages are, since they do not have to fit on a printed
-page. The formfeeds should appear alone on lines by themselves.
-
-\1f
-File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
-
-5.2 Commenting Your Work
-========================
-
-Every program should start with a comment saying briefly what it is for.
-Example: `fmt - filter for simple filling of text'.
-
- Please write the comments in a GNU program in English, because
-English is the one language that nearly all programmers in all
-countries can read. If you do not write English well, please write
-comments in English as well as you can, then ask other people to help
-rewrite them. If you can't write comments in English, please find
-someone to work with you and translate your comments into English.
-
- Please put a comment on each function saying what the function does,
-what sorts of arguments it gets, and what the possible values of
-arguments mean and are used for. It is not necessary to duplicate in
-words the meaning of the C argument declarations, if a C type is being
-used in its customary fashion. If there is anything nonstandard about
-its use (such as an argument of type `char *' which is really the
-address of the second character of a string, not the first), or any
-possible values that would not work the way one would expect (such as,
-that strings containing newlines are not guaranteed to work), be sure
-to say so.
-
- Also explain the significance of the return value, if there is one.
-
- Please put two spaces after the end of a sentence in your comments,
-so that the Emacs sentence commands will work. Also, please write
-complete sentences and capitalize the first word. If a lower-case
-identifier comes at the beginning of a sentence, don't capitalize it!
-Changing the spelling makes it a different identifier. If you don't
-like starting a sentence with a lower case letter, write the sentence
-differently (e.g., "The identifier lower-case is ...").
-
- The comment on a function is much clearer if you use the argument
-names to speak about the argument values. The variable name itself
-should be lower case, but write it in upper case when you are speaking
-about the value rather than the variable itself. Thus, "the inode
-number NODE_NUM" rather than "an inode".
-
- There is usually no purpose in restating the name of the function in
-the comment before it, because the reader can see that for himself.
-There might be an exception when the comment is so long that the
-function itself would be off the bottom of the screen.
-
- There should be a comment on each static variable as well, like this:
-
- /* Nonzero means truncate lines in the display;
- zero means continue them. */
- int truncate_lines;
-
- Every `#endif' should have a comment, except in the case of short
-conditionals (just a few lines) that are not nested. The comment should
-state the condition of the conditional that is ending, _including its
-sense_. `#else' should have a comment describing the condition _and
-sense_ of the code that follows. For example:
-
- #ifdef foo
- ...
- #else /* not foo */
- ...
- #endif /* not foo */
- #ifdef foo
- ...
- #endif /* foo */
-
-but, by contrast, write the comments this way for a `#ifndef':
-
- #ifndef foo
- ...
- #else /* foo */
- ...
- #endif /* foo */
- #ifndef foo
- ...
- #endif /* not foo */
-
-\1f
-File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
-
-5.3 Clean Use of C Constructs
-=============================
-
-Please explicitly declare the types of all objects. For example, you
-should explicitly declare all arguments to functions, and you should
-declare functions to return `int' rather than omitting the `int'.
-
- Some programmers like to use the GCC `-Wall' option, and change the
-code whenever it issues a warning. If you want to do this, then do.
-Other programmers prefer not to use `-Wall', because it gives warnings
-for valid and legitimate code which they do not want to change. If you
-want to do this, then do. The compiler should be your servant, not
-your master.
-
- Declarations of external functions and functions to appear later in
-the source file should all go in one place near the beginning of the
-file (somewhere before the first function definition in the file), or
-else should go in a header file. Don't put `extern' declarations inside
-functions.
-
- It used to be common practice to use the same local variables (with
-names like `tem') over and over for different values within one
-function. Instead of doing this, it is better declare a separate local
-variable for each distinct purpose, and give it a name which is
-meaningful. This not only makes programs easier to understand, it also
-facilitates optimization by good compilers. You can also move the
-declaration of each local variable into the smallest scope that includes
-all its uses. This makes the program even cleaner.
-
- Don't use local variables or parameters that shadow global
-identifiers.
-
- Don't declare multiple variables in one declaration that spans lines.
-Start a new declaration on each line, instead. For example, instead of
-this:
-
- int foo,
- bar;
-
-write either this:
-
- int foo, bar;
-
-or this:
-
- int foo;
- int bar;
-
-(If they are global variables, each should have a comment preceding it
-anyway.)
-
- When you have an `if'-`else' statement nested in another `if'
-statement, always put braces around the `if'-`else'. Thus, never write
-like this:
-
- if (foo)
- if (bar)
- win ();
- else
- lose ();
-
-always like this:
-
- if (foo)
- {
- if (bar)
- win ();
- else
- lose ();
- }
-
- If you have an `if' statement nested inside of an `else' statement,
-either write `else if' on one line, like this,
-
- if (foo)
- ...
- else if (bar)
- ...
-
-with its `then'-part indented like the preceding `then'-part, or write
-the nested `if' within braces like this:
-
- if (foo)
- ...
- else
- {
- if (bar)
- ...
- }
-
- Don't declare both a structure tag and variables or typedefs in the
-same declaration. Instead, declare the structure tag separately and
-then use it to declare the variables or typedefs.
-
- Try to avoid assignments inside `if'-conditions. For example, don't
-write this:
-
- if ((foo = (char *) malloc (sizeof *foo)) == 0)
- fatal ("virtual memory exhausted");
-
-instead, write this:
-
- foo = (char *) malloc (sizeof *foo);
- if (foo == 0)
- fatal ("virtual memory exhausted");
-
- Don't make the program ugly to placate `lint'. Please don't insert
-any casts to `void'. Zero without a cast is perfectly fine as a null
-pointer constant, except when calling a varargs function.
-
-\1f
-File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
-
-5.4 Naming Variables, Functions, and Files
-==========================================
-
-The names of global variables and functions in a program serve as
-comments of a sort. So don't choose terse names--instead, look for
-names that give useful information about the meaning of the variable or
-function. In a GNU program, names should be English, like other
-comments.
-
- Local variable names can be shorter, because they are used only
-within one context, where (presumably) comments explain their purpose.
-
- Try to limit your use of abbreviations in symbol names. It is ok to
-make a few abbreviations, explain what they mean, and then use them
-frequently, but don't use lots of obscure abbreviations.
-
- Please use underscores to separate words in a name, so that the Emacs
-word commands can be useful within them. Stick to lower case; reserve
-upper case for macros and `enum' constants, and for name-prefixes that
-follow a uniform convention.
-
- For example, you should use names like `ignore_space_change_flag';
-don't use names like `iCantReadThis'.
-
- Variables that indicate whether command-line options have been
-specified should be named after the meaning of the option, not after
-the option-letter. A comment should state both the exact meaning of
-the option and its letter. For example,
-
- /* Ignore changes in horizontal whitespace (-b). */
- int ignore_space_change_flag;
-
- When you want to define names with constant integer values, use
-`enum' rather than `#define'. GDB knows about enumeration constants.
-
- You might want to make sure that none of the file names would
-conflict the files were loaded onto an MS-DOS file system which
-shortens the names. You can use the program `doschk' to test for this.
-
- Some GNU programs were designed to limit themselves to file names of
-14 characters or less, to avoid file name conflicts if they are read
-into older System V systems. Please preserve this feature in the
-existing GNU programs that have it, but there is no need to do this in
-new GNU programs. `doschk' also reports file names longer than 14
-characters.
-
-\1f
-File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
-
-5.5 Portability between System Types
-====================================
-
-In the Unix world, "portability" refers to porting to different Unix
-versions. For a GNU program, this kind of portability is desirable, but
-not paramount.
-
- The primary purpose of GNU software is to run on top of the GNU
-kernel, compiled with the GNU C compiler, on various types of CPU. So
-the kinds of portability that are absolutely necessary are quite
-limited. But it is important to support Linux-based GNU systems, since
-they are the form of GNU that is popular.
-
- Beyond that, it is good to support the other free operating systems
-(*BSD), and it is nice to support other Unix-like systems if you want
-to. Supporting a variety of Unix-like systems is desirable, although
-not paramount. It is usually not too hard, so you may as well do it.
-But you don't have to consider it an obligation, if it does turn out to
-be hard.
-
- The easiest way to achieve portability to most Unix-like systems is
-to use Autoconf. It's unlikely that your program needs to know more
-information about the host platform than Autoconf can provide, simply
-because most of the programs that need such knowledge have already been
-written.
-
- Avoid using the format of semi-internal data bases (e.g.,
-directories) when there is a higher-level alternative (`readdir').
-
- As for systems that are not like Unix, such as MSDOS, Windows, the
-Macintosh, VMS, and MVS, supporting them is often a lot of work. When
-that is the case, it is better to spend your time adding features that
-will be useful on GNU and GNU/Linux, rather than on supporting other
-incompatible systems.
-
- It is a good idea to define the "feature test macro" `_GNU_SOURCE'
-when compiling your C files. When you compile on GNU or GNU/Linux,
-this will enable the declarations of GNU library extension functions,
-and that will usually give you a compiler error message if you define
-the same function names in some other way in your program. (You don't
-have to actually _use_ these functions, if you prefer to make the
-program more portable to other systems.)
-
- But whether or not you use these GNU extensions, you should avoid
-using their names for any other meanings. Doing so would make it hard
-to move your code into other GNU programs.
-
-\1f
-File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
-
-5.6 Portability between CPUs
-============================
-
-Even GNU systems will differ because of differences among CPU
-types--for example, difference in byte ordering and alignment
-requirements. It is absolutely essential to handle these differences.
-However, don't make any effort to cater to the possibility that an
-`int' will be less than 32 bits. We don't support 16-bit machines in
-GNU.
-
- Similarly, don't make any effort to cater to the possibility that
-`long' will be smaller than predefined types like `size_t'. For
-example, the following code is ok:
-
- printf ("size = %lu\n", (unsigned long) sizeof array);
- printf ("diff = %ld\n", (long) (pointer2 - pointer1));
-
- 1989 Standard C requires this to work, and we know of only one
-counterexample: 64-bit programs on Microsoft Windows IA-64. We will
-leave it to those who want to port GNU programs to that environment to
-figure out how to do it.
-
- Predefined file-size types like `off_t' are an exception: they are
-longer than `long' on many platforms, so code like the above won't work
-with them. One way to print an `off_t' value portably is to print its
-digits yourself, one by one.
-
- Don't assume that the address of an `int' object is also the address
-of its least-significant byte. This is false on big-endian machines.
-Thus, don't make the following mistake:
-
- int c;
- ...
- while ((c = getchar()) != EOF)
- write(file_descriptor, &c, 1);
-
- When calling functions, you need not worry about the difference
-between pointers of various types, or between pointers and integers.
-On most machines, there's no difference anyway. As for the few
-machines where there is a difference, all of them support Standard C
-prototypes, so you can use prototypes (perhaps conditionalized to be
-active only in Standard C) to make the code work on those systems.
-
- In certain cases, it is ok to pass integer and pointer arguments
-indiscriminately to the same function, and use no prototype on any
-system. For example, many GNU programs have error-reporting functions
-that pass their arguments along to `printf' and friends:
-
- error (s, a1, a2, a3)
- char *s;
- char *a1, *a2, *a3;
- {
- fprintf (stderr, "error: ");
- fprintf (stderr, s, a1, a2, a3);
- }
-
-In practice, this works on all machines, since a pointer is generally
-the widest possible kind of argument; it is much simpler than any
-"correct" alternative. Be sure _not_ to use a prototype for such
-functions.
-
- If you have decided to use Standard C, then you can instead define
-`error' using `stdarg.h', and pass the arguments along to `vfprintf'.
-
- Avoid casting pointers to integers if you can. Such casts greatly
-reduce portability, and in most programs they are easy to avoid. In the
-cases where casting pointers to integers is essential--such as, a Lisp
-interpreter which stores type information as well as an address in one
-word--you'll have to make explicit provisions to handle different word
-sizes. You will also need to make provision for systems in which the
-normal range of addresses you can get from `malloc' starts far away
-from zero.
-
-\1f
-File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
-
-5.7 Calling System Functions
-============================
-
-C implementations differ substantially. Standard C reduces but does
-not eliminate the incompatibilities; meanwhile, many GNU packages still
-support pre-standard compilers because this is not hard to do. This
-chapter gives recommendations for how to use the more-or-less standard C
-library functions to avoid unnecessary loss of portability.
-
- * Don't use the return value of `sprintf'. It returns the number of
- characters written on some systems, but not on all systems.
-
- * Be aware that `vfprintf' is not always available.
-
- * `main' should be declared to return type `int'. It should
- terminate either by calling `exit' or by returning the integer
- status code; make sure it cannot ever return an undefined value.
-
- * Don't declare system functions explicitly.
-
- Almost any declaration for a system function is wrong on some
- system. To minimize conflicts, leave it to the system header
- files to declare system functions. If the headers don't declare a
- function, let it remain undeclared.
-
- While it may seem unclean to use a function without declaring it,
- in practice this works fine for most system library functions on
- the systems where this really happens; thus, the disadvantage is
- only theoretical. By contrast, actual declarations have
- frequently caused actual conflicts.
-
- * If you must declare a system function, don't specify the argument
- types. Use an old-style declaration, not a Standard C prototype.
- The more you specify about the function, the more likely a
- conflict.
-
- * In particular, don't unconditionally declare `malloc' or `realloc'.
-
- Most GNU programs use those functions just once, in functions
- conventionally named `xmalloc' and `xrealloc'. These functions
- call `malloc' and `realloc', respectively, and check the results.
-
- Because `xmalloc' and `xrealloc' are defined in your program, you
- can declare them in other files without any risk of type conflict.
-
- On most systems, `int' is the same length as a pointer; thus, the
- calls to `malloc' and `realloc' work fine. For the few
- exceptional systems (mostly 64-bit machines), you can use
- *conditionalized* declarations of `malloc' and `realloc'--or put
- these declarations in configuration files specific to those
- systems.
-
- * The string functions require special treatment. Some Unix systems
- have a header file `string.h'; others have `strings.h'. Neither
- file name is portable. There are two things you can do: use
- Autoconf to figure out which file to include, or don't include
- either file.
-
- * If you don't include either strings file, you can't get
- declarations for the string functions from the header file in the
- usual way.
-
- That causes less of a problem than you might think. The newer
- standard string functions should be avoided anyway because many
- systems still don't support them. The string functions you can
- use are these:
-
- strcpy strncpy strcat strncat
- strlen strcmp strncmp
- strchr strrchr
-
- The copy and concatenate functions work fine without a declaration
- as long as you don't use their values. Using their values without
- a declaration fails on systems where the width of a pointer
- differs from the width of `int', and perhaps in other cases. It
- is trivial to avoid using their values, so do that.
-
- The compare functions and `strlen' work fine without a declaration
- on most systems, possibly all the ones that GNU software runs on.
- You may find it necessary to declare them *conditionally* on a few
- systems.
-
- The search functions must be declared to return `char *'. Luckily,
- there is no variation in the data type they return. But there is
- variation in their names. Some systems give these functions the
- names `index' and `rindex'; other systems use the names `strchr'
- and `strrchr'. Some systems support both pairs of names, but
- neither pair works on all systems.
-
- You should pick a single pair of names and use it throughout your
- program. (Nowadays, it is better to choose `strchr' and `strrchr'
- for new programs, since those are the standard names.) Declare
- both of those names as functions returning `char *'. On systems
- which don't support those names, define them as macros in terms of
- the other pair. For example, here is what to put at the beginning
- of your file (or in a header) if you want to use the names
- `strchr' and `strrchr' throughout:
-
- #ifndef HAVE_STRCHR
- #define strchr index
- #endif
- #ifndef HAVE_STRRCHR
- #define strrchr rindex
- #endif
-
- char *strchr ();
- char *strrchr ();
-
- Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
-defined in systems where the corresponding functions exist. One way to
-get them properly defined is to use Autoconf.
-
-\1f
-File: standards.info, Node: Internationalization, Next: Mmap, Prev: System Functions, Up: Writing C
-
-5.8 Internationalization
-========================
-
-GNU has a library called GNU gettext that makes it easy to translate the
-messages in a program into various languages. You should use this
-library in every program. Use English for the messages as they appear
-in the program, and let gettext provide the way to translate them into
-other languages.
-
- Using GNU gettext involves putting a call to the `gettext' macro
-around each string that might need translation--like this:
-
- printf (gettext ("Processing file `%s'..."));
-
-This permits GNU gettext to replace the string `"Processing file
-`%s'..."' with a translated version.
-
- Once a program uses gettext, please make a point of writing calls to
-`gettext' when you add new strings that call for translation.
-
- Using GNU gettext in a package involves specifying a "text domain
-name" for the package. The text domain name is used to separate the
-translations for this package from the translations for other packages.
-Normally, the text domain name should be the same as the name of the
-package--for example, `fileutils' for the GNU file utilities.
-
- To enable gettext to work well, avoid writing code that makes
-assumptions about the structure of words or sentences. When you want
-the precise text of a sentence to vary depending on the data, use two or
-more alternative string constants each containing a complete sentences,
-rather than inserting conditionalized words or phrases into a single
-sentence framework.
-
- Here is an example of what not to do:
-
- printf ("%d file%s processed", nfiles,
- nfiles != 1 ? "s" : "");
-
-The problem with that example is that it assumes that plurals are made
-by adding `s'. If you apply gettext to the format string, like this,
-
- printf (gettext ("%d file%s processed"), nfiles,
- nfiles != 1 ? "s" : "");
-
-the message can use different words, but it will still be forced to use
-`s' for the plural. Here is a better way:
-
- printf ((nfiles != 1 ? "%d files processed"
- : "%d file processed"),
- nfiles);
-
-This way, you can apply gettext to each of the two strings
-independently:
-
- printf ((nfiles != 1 ? gettext ("%d files processed")
- : gettext ("%d file processed")),
- nfiles);
-
-This can be any method of forming the plural of the word for "file", and
-also handles languages that require agreement in the word for
-"processed".
-
- A similar problem appears at the level of sentence structure with
-this code:
-
- printf ("# Implicit rule search has%s been done.\n",
- f->tried_implicit ? "" : " not");
-
-Adding `gettext' calls to this code cannot give correct results for all
-languages, because negation in some languages requires adding words at
-more than one place in the sentence. By contrast, adding `gettext'
-calls does the job straightfowardly if the code starts out like this:
-
- printf (f->tried_implicit
- ? "# Implicit rule search has been done.\n",
- : "# Implicit rule search has not been done.\n");
-
-\1f
-File: standards.info, Node: Mmap, Prev: Internationalization, Up: Writing C
-
-5.9 Mmap
-========
-
-Don't assume that `mmap' either works on all files or fails for all
-files. It may work on some files and fail on others.
-
- The proper way to use `mmap' is to try it on the specific file for
-which you want to use it--and if `mmap' doesn't work, fall back on
-doing the job in another way using `read' and `write'.
-
- The reason this precaution is needed is that the GNU kernel (the
-HURD) provides a user-extensible file system, in which there can be many
-different kinds of "ordinary files." Many of them support `mmap', but
-some do not. It is important to make programs handle all these kinds
-of files.
-
-\1f
-File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
-
-6 Documenting Programs
-**********************
-
-A GNU program should ideally come with full free documentation, adequate
-for both reference and tutorial purposes. If the package can be
-programmed or extended, the documentation should cover programming or
-extending it, as well as just using it.
-
-* Menu:
-
-* GNU Manuals:: Writing proper manuals.
-* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
-* Manual Structure Details:: Specific structure conventions.
-* License for Manuals:: Writing the distribution terms for a manual.
-* Manual Credits:: Giving credit to documentation contributors.
-* Printed Manuals:: Mentioning the printed manual.
-* NEWS File:: NEWS files supplement manuals.
-* Change Logs:: Recording Changes
-* Man Pages:: Man pages are secondary.
-* Reading other Manuals:: How far you can go in learning
- from other manuals.
-
-\1f
-File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
-
-6.1 GNU Manuals
-===============
-
-The preferred document format for the GNU system is the Texinfo
-formatting language. Every GNU package should (ideally) have
-documentation in Texinfo both for reference and for learners. Texinfo
-makes it possible to produce a good quality formatted book, using TeX,
-and to generate an Info file. It is also possible to generate HTML
-output from Texinfo source. See the Texinfo manual, either the
-hardcopy, or the on-line version available through `info' or the Emacs
-Info subsystem (`C-h i').
-
- Nowadays some other formats such as Docbook and Sgmltexi can be
-converted automatically into Texinfo. It is ok to produce the Texinfo
-documentation by conversion this way, as long as it gives good results.
-
- Programmers often find it most natural to structure the documentation
-following the structure of the implementation, which they know. But
-this structure is not necessarily good for explaining how to use the
-program; it may be irrelevant and confusing for a user.
-
- At every level, from the sentences in a paragraph to the grouping of
-topics into separate manuals, the right way to structure documentation
-is according to the concepts and questions that a user will have in mind
-when reading it. Sometimes this structure of ideas matches the
-structure of the implementation of the software being documented--but
-often they are different. Often the most important part of learning to
-write good documentation is learning to notice when you are structuring
-the documentation like the implementation, and think about better
-alternatives.
-
- For example, each program in the GNU system probably ought to be
-documented in one manual; but this does not mean each program should
-have its own manual. That would be following the structure of the
-implementation, rather than the structure that helps the user
-understand.
-
- Instead, each manual should cover a coherent _topic_. For example,
-instead of a manual for `diff' and a manual for `diff3', we have one
-manual for "comparison of files" which covers both of those programs,
-as well as `cmp'. By documenting these programs together, we can make
-the whole subject clearer.
-
- The manual which discusses a program should certainly document all of
-the program's command-line options and all of its commands. It should
-give examples of their use. But don't organize the manual as a list of
-features. Instead, organize it logically, by subtopics. Address the
-questions that a user will ask when thinking about the job that the
-program does.
-
- In general, a GNU manual should serve both as tutorial and reference.
-It should be set up for convenient access to each topic through Info,
-and for reading straight through (appendixes aside). A GNU manual
-should give a good introduction to a beginner reading through from the
-start, and should also provide all the details that hackers want. The
-Bison manual is a good example of this--please take a look at it to see
-what we mean.
-
- That is not as hard as it first sounds. Arrange each chapter as a
-logical breakdown of its topic, but order the sections, and write their
-text, so that reading the chapter straight through makes sense. Do
-likewise when structuring the book into chapters, and when structuring a
-section into paragraphs. The watchword is, _at each point, address the
-most fundamental and important issue raised by the preceding text._
-
- If necessary, add extra chapters at the beginning of the manual which
-are purely tutorial and cover the basics of the subject. These provide
-the framework for a beginner to understand the rest of the manual. The
-Bison manual provides a good example of how to do this.
-
- To serve as a reference, a manual should have an Index that list all
-the functions, variables, options, and important concepts that are part
-of the program. One combined Index should do for a short manual, but
-sometimes for a complex package it is better to use multiple indices.
-The Texinfo manual includes advice on preparing good index entries, see
-*Note Making Index Entries: (texinfo)Index Entries, and see *Note
-Defining the Entries of an Index: (texinfo)Indexing Commands.
-
- Don't use Unix man pages as a model for how to write GNU
-documentation; most of them are terse, badly structured, and give
-inadequate explanation of the underlying concepts. (There are, of
-course, some exceptions.) Also, Unix man pages use a particular format
-which is different from what we use in GNU manuals.
-
- Please include an email address in the manual for where to report
-bugs _in the manual_.
-
- Please do not use the term "pathname" that is used in Unix
-documentation; use "file name" (two words) instead. We use the term
-"path" only for search paths, which are lists of directory names.
-
- Please do not use the term "illegal" to refer to erroneous input to a
-computer program. Please use "invalid" for this, and reserve the term
-"illegal" for activities punishable by law.
-
-\1f
-File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
-
-6.2 Doc Strings and Manuals
-===========================
-
-Some programming systems, such as Emacs, provide a documentation string
-for each function, command or variable. You may be tempted to write a
-reference manual by compiling the documentation strings and writing a
-little additional text to go around them--but you must not do it. That
-approach is a fundamental mistake. The text of well-written
-documentation strings will be entirely wrong for a manual.
-
- A documentation string needs to stand alone--when it appears on the
-screen, there will be no other text to introduce or explain it.
-Meanwhile, it can be rather informal in style.
-
- The text describing a function or variable in a manual must not stand
-alone; it appears in the context of a section or subsection. Other text
-at the beginning of the section should explain some of the concepts, and
-should often make some general points that apply to several functions or
-variables. The previous descriptions of functions and variables in the
-section will also have given information about the topic. A description
-written to stand alone would repeat some of that information; this
-redundance looks bad. Meanwhile, the informality that is acceptable in
-a documentation string is totally unacceptable in a manual.
-
- The only good way to use documentation strings in writing a good
-manual is to use them as a source of information for writing good text.
-
-\1f
-File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
-
-6.3 Manual Structure Details
-============================
-
-The title page of the manual should state the version of the programs or
-packages documented in the manual. The Top node of the manual should
-also contain this information. If the manual is changing more
-frequently than or independent of the program, also state a version
-number for the manual in both of these places.
-
- Each program documented in the manual should have a node named
-`PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
-its subnodes, if any) should describe the program's command line
-arguments and how to run it (the sort of information people would look
-in a man page for). Start with an `@example' containing a template for
-all the options and arguments that the program uses.
-
- Alternatively, put a menu item in some menu whose item name fits one
-of the above patterns. This identifies the node which that item points
-to as the node for this purpose, regardless of the node's actual name.
-
- The `--usage' feature of the Info reader looks for such a node or
-menu item in order to find the relevant text, so it is essential for
-every Texinfo file to have one.
-
- If one manual describes several programs, it should have such a node
-for each program described in the manual.
-
-\1f
-File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
-
-6.4 License for Manuals
-=======================
-
-Please use the GNU Free Documentation License for all GNU manuals that
-are more than a few pages long. Likewise for a collection of short
-documents--you only need one copy of the GNU FDL for the whole
-collection. For a single short document, you can use a very permissive
-non-copyleft license, to avoid taking up space with a long license.
-
- See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
-of how to employ the GFDL.
-
- Note that it is not obligatory to include a copy of the GNU GPL or
-GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It
-can be a good idea to include the program's license in a large manual;
-in a short manual, whose size would be increased considerably by
-including the program's license, it is probably better not to include
-it.
-
-\1f
-File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
-
-6.5 Manual Credits
-==================
-
-Please credit the principal human writers of the manual as the authors,
-on the title page of the manual. If a company sponsored the work, thank
-the company in a suitable place in the manual, but do not cite the
-company as an author.
-
-\1f
-File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
-
-6.6 Printed Manuals
-===================
-
-The FSF publishes some GNU manuals in printed form. To encourage sales
-of these manuals, the on-line versions of the manual should mention at
-the very start that the printed manual is available and should point at
-information for getting it--for instance, with a link to the page
-`http://www.gnu.org/order/order.html'. This should not be included in
-the printed manual, though, because there it is redundant.
-
- It is also useful to explain in the on-line forms of the manual how
-the user can print out the manual from the sources.
-
-\1f
-File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
-
-6.7 The NEWS File
-=================
-
-In addition to its manual, the package should have a file named `NEWS'
-which contains a list of user-visible changes worth mentioning. In
-each new release, add items to the front of the file and identify the
-version they pertain to. Don't discard old items; leave them in the
-file after the newer items. This way, a user upgrading from any
-previous version can see what is new.
-
- If the `NEWS' file gets very long, move some of the older items into
-a file named `ONEWS' and put a note at the end referring the user to
-that file.
-
-\1f
-File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
-
-6.8 Change Logs
-===============
-
-Keep a change log to describe all the changes made to program source
-files. The purpose of this is so that people investigating bugs in the
-future will know about the changes that might have introduced the bug.
-Often a new bug can be found by looking at what was recently changed.
-More importantly, change logs can help you eliminate conceptual
-inconsistencies between different parts of a program, by giving you a
-history of how the conflicting concepts arose and who they came from.
-
-* Menu:
-
-* Change Log Concepts::
-* Style of Change Logs::
-* Simple Changes::
-* Conditional Changes::
-* Indicating the Part Changed::
-
-\1f
-File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
-
-6.8.1 Change Log Concepts
--------------------------
-
-You can think of the change log as a conceptual "undo list" which
-explains how earlier versions were different from the current version.
-People can see the current version; they don't need the change log to
-tell them what is in it. What they want from a change log is a clear
-explanation of how the earlier version differed.
-
- The change log file is normally called `ChangeLog' and covers an
-entire directory. Each directory can have its own change log, or a
-directory can use the change log of its parent directory-it's up to you.
-
- Another alternative is to record change log information with a
-version control system such as RCS or CVS. This can be converted
-automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
-command `C-x v a' (`vc-update-change-log') does the job.
-
- There's no need to describe the full purpose of the changes or how
-they work together. If you think that a change calls for explanation,
-you're probably right. Please do explain it--but please put the
-explanation in comments in the code, where people will see it whenever
-they see the code. For example, "New function" is enough for the
-change log when you add a function, because there should be a comment
-before the function definition to explain what it does.
-
- However, sometimes it is useful to write one line to describe the
-overall purpose of a batch of changes.
-
- The easiest way to add an entry to `ChangeLog' is with the Emacs
-command `M-x add-change-log-entry'. An entry should have an asterisk,
-the name of the changed file, and then in parentheses the name of the
-changed functions, variables or whatever, followed by a colon. Then
-describe the changes you made to that function or variable.
-
-\1f
-File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
-
-6.8.2 Style of Change Logs
---------------------------
-
-Here are some simple examples of change log entries, starting with the
-header line that says who made the change and when, followed by
-descriptions of specific changes. (These examples are drawn from Emacs
-and GCC.)
-
- 1998-08-17 Richard Stallman <rms@gnu.org>
-
- * register.el (insert-register): Return nil.
- (jump-to-register): Likewise.
-
- * sort.el (sort-subr): Return nil.
-
- * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
- Restart the tex shell if process is gone or stopped.
- (tex-shell-running): New function.
-
- * expr.c (store_one_arg): Round size up for move_block_to_reg.
- (expand_call): Round up when emitting USE insns.
- * stmt.c (assign_parms): Round size up for move_block_from_reg.
-
- It's important to name the changed function or variable in full.
-Don't abbreviate function or variable names, and don't combine them.
-Subsequent maintainers will often search for a function name to find all
-the change log entries that pertain to it; if you abbreviate the name,
-they won't find it when they search.
-
- For example, some people are tempted to abbreviate groups of function
-names by writing `* register.el ({insert,jump-to}-register)'; this is
-not a good idea, since searching for `jump-to-register' or
-`insert-register' would not find that entry.
-
- Separate unrelated change log entries with blank lines. When two
-entries represent parts of the same change, so that they work together,
-then don't put blank lines between them. Then you can omit the file
-name and the asterisk when successive entries are in the same file.
-
- Break long lists of function names by closing continued lines with
-`)', rather than `,', and opening the continuation with `(' as in this
-example:
-
- * keyboard.c (menu_bar_items, tool_bar_items)
- (Fexecute_extended_command): Deal with `keymap' property.
-
-\1f
-File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
-
-6.8.3 Simple Changes
---------------------
-
-Certain simple kinds of changes don't need much detail in the change
-log.
-
- When you change the calling sequence of a function in a simple
-fashion, and you change all the callers of the function to use the new
-calling sequence, there is no need to make individual entries for all
-the callers that you changed. Just write in the entry for the function
-being called, "All callers changed"--like this:
-
- * keyboard.c (Fcommand_execute): New arg SPECIAL.
- All callers changed.
-
- When you change just comments or doc strings, it is enough to write
-an entry for the file, without mentioning the functions. Just "Doc
-fixes" is enough for the change log.
-
- There's no need to make change log entries for documentation files.
-This is because documentation is not susceptible to bugs that are hard
-to fix. Documentation does not consist of parts that must interact in a
-precisely engineered fashion. To correct an error, you need not know
-the history of the erroneous passage; it is enough to compare what the
-documentation says with the way the program actually works.
-
-\1f
-File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
-
-6.8.4 Conditional Changes
--------------------------
-
-C programs often contain compile-time `#if' conditionals. Many changes
-are conditional; sometimes you add a new definition which is entirely
-contained in a conditional. It is very useful to indicate in the
-change log the conditions for which the change applies.
-
- Our convention for indicating conditional changes is to use square
-brackets around the name of the condition.
-
- Here is a simple example, describing a change which is conditional
-but does not have a function or entity name associated with it:
-
- * xterm.c [SOLARIS2]: Include string.h.
-
- Here is an entry describing a new definition which is entirely
-conditional. This new definition for the macro `FRAME_WINDOW_P' is
-used only when `HAVE_X_WINDOWS' is defined:
-
- * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
-
- Here is an entry for a change within the function `init_display',
-whose definition as a whole is unconditional, but the changes themselves
-are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
-
- * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
-
- Here is an entry for a change that takes affect only when a certain
-macro is _not_ defined:
-
- (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
-
-\1f
-File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
-
-6.8.5 Indicating the Part Changed
----------------------------------
-
-Indicate the part of a function which changed by using angle brackets
-enclosing an indication of what the changed part does. Here is an entry
-for a change in the part of the function `sh-while-getopts' that deals
-with `sh' commands:
-
- * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
- user-specified option string is empty.
-
-\1f
-File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
-
-6.9 Man Pages
-=============
-
-In the GNU project, man pages are secondary. It is not necessary or
-expected for every GNU program to have a man page, but some of them do.
-It's your choice whether to include a man page in your program.
-
- When you make this decision, consider that supporting a man page
-requires continual effort each time the program is changed. The time
-you spend on the man page is time taken away from more useful work.
-
- For a simple program which changes little, updating the man page may
-be a small job. Then there is little reason not to include a man page,
-if you have one.
-
- For a large program that changes a great deal, updating a man page
-may be a substantial burden. If a user offers to donate a man page,
-you may find this gift costly to accept. It may be better to refuse
-the man page unless the same person agrees to take full responsibility
-for maintaining it--so that you can wash your hands of it entirely. If
-this volunteer later ceases to do the job, then don't feel obliged to
-pick it up yourself; it may be better to withdraw the man page from the
-distribution until someone else agrees to update it.
-
- When a program changes only a little, you may feel that the
-discrepancies are small enough that the man page remains useful without
-updating. If so, put a prominent note near the beginning of the man
-page explaining that you don't maintain it and that the Texinfo manual
-is more authoritative. The note should say how to access the Texinfo
-documentation.
-
-\1f
-File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
-
-6.10 Reading other Manuals
-==========================
-
-There may be non-free books or documentation files that describe the
-program you are documenting.
-
- It is ok to use these documents for reference, just as the author of
-a new algebra textbook can read other books on algebra. A large portion
-of any non-fiction book consists of facts, in this case facts about how
-a certain program works, and these facts are necessarily the same for
-everyone who writes about the subject. But be careful not to copy your
-outline structure, wording, tables or examples from preexisting non-free
-documentation. Copying from free documentation may be ok; please check
-with the FSF about the individual case.
-
-\1f
-File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
-
-7 The Release Process
-*********************
-
-Making a release is more than just bundling up your source files in a
-tar file and putting it up for FTP. You should set up your software so
-that it can be configured to run on a variety of systems. Your Makefile
-should conform to the GNU standards described below, and your directory
-layout should also conform to the standards discussed below. Doing so
-makes it easy to include your package into the larger framework of all
-GNU software.
-
-* Menu:
-
-* Configuration:: How Configuration Should Work
-* Makefile Conventions:: Makefile Conventions
-* Releases:: Making Releases
-
-\1f
-File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
-
-7.1 How Configuration Should Work
-=================================
-
-Each GNU distribution should come with a shell script named
-`configure'. This script is given arguments which describe the kind of
-machine and system you want to compile the program for.
-
- The `configure' script must record the configuration options so that
-they affect compilation.
-
- One way to do this is to make a link from a standard name such as
-`config.h' to the proper configuration file for the chosen system. If
-you use this technique, the distribution should _not_ contain a file
-named `config.h'. This is so that people won't be able to build the
-program without configuring it first.
-
- Another thing that `configure' can do is to edit the Makefile. If
-you do this, the distribution should _not_ contain a file named
-`Makefile'. Instead, it should include a file `Makefile.in' which
-contains the input used for editing. Once again, this is so that people
-won't be able to build the program without configuring it first.
-
- If `configure' does write the `Makefile', then `Makefile' should
-have a target named `Makefile' which causes `configure' to be rerun,
-setting up the same configuration that was set up last time. The files
-that `configure' reads should be listed as dependencies of `Makefile'.
-
- All the files which are output from the `configure' script should
-have comments at the beginning explaining that they were generated
-automatically using `configure'. This is so that users won't think of
-trying to edit them by hand.
-
- The `configure' script should write a file named `config.status'
-which describes which configuration options were specified when the
-program was last configured. This file should be a shell script which,
-if run, will recreate the same configuration.
-
- The `configure' script should accept an option of the form
-`--srcdir=DIRNAME' to specify the directory where sources are found (if
-it is not the current directory). This makes it possible to build the
-program in a separate directory, so that the actual source directory is
-not modified.
-
- If the user does not specify `--srcdir', then `configure' should
-check both `.' and `..' to see if it can find the sources. If it finds
-the sources in one of these places, it should use them from there.
-Otherwise, it should report that it cannot find the sources, and should
-exit with nonzero status.
-
- Usually the easy way to support `--srcdir' is by editing a
-definition of `VPATH' into the Makefile. Some rules may need to refer
-explicitly to the specified source directory. To make this possible,
-`configure' can add to the Makefile a variable named `srcdir' whose
-value is precisely the specified directory.
-
- The `configure' script should also take an argument which specifies
-the type of system to build the program for. This argument should look
-like this:
-
- CPU-COMPANY-SYSTEM
-
- For example, a Sun 3 might be `m68k-sun-sunos4.1'.
-
- The `configure' script needs to be able to decode all plausible
-alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
-would be a valid alias. For many programs, `vax-dec-ultrix' would be
-an alias for `vax-dec-bsd', simply because the differences between
-Ultrix and BSD are rarely noticeable, but a few programs might need to
-distinguish them.
-
- There is a shell script called `config.sub' that you can use as a
-subroutine to validate system types and canonicalize aliases.
-
- Other options are permitted to specify in more detail the software
-or hardware present on the machine, and include or exclude optional
-parts of the package:
-
-`--enable-FEATURE[=PARAMETER]'
- Configure the package to build and install an optional user-level
- facility called FEATURE. This allows users to choose which
- optional features to include. Giving an optional PARAMETER of
- `no' should omit FEATURE, if it is built by default.
-
- No `--enable' option should *ever* cause one feature to replace
- another. No `--enable' option should ever substitute one useful
- behavior for another useful behavior. The only proper use for
- `--enable' is for questions of whether to build part of the program
- or exclude it.
-
-`--with-PACKAGE'
- The package PACKAGE will be installed, so configure this package
- to work with PACKAGE.
-
- Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
- `gnu-libc', `gdb', `x', and `x-toolkit'.
-
- Do not use a `--with' option to specify the file name to use to
- find certain files. That is outside the scope of what `--with'
- options are for.
-
- All `configure' scripts should accept all of these "detail" options,
-whether or not they make any difference to the particular package at
-hand. In particular, they should accept any option that starts with
-`--with-' or `--enable-'. This is so users will be able to configure
-an entire GNU source tree at once with a single set of options.
-
- You will note that the categories `--with-' and `--enable-' are
-narrow: they *do not* provide a place for any sort of option you might
-think of. That is deliberate. We want to limit the possible
-configuration options in GNU software. We do not want GNU programs to
-have idiosyncratic configuration options.
-
- Packages that perform part of the compilation process may support
-cross-compilation. In such a case, the host and target machines for the
-program may be different.
-
- The `configure' script should normally treat the specified type of
-system as both the host and the target, thus producing a program which
-works for the same type of machine that it runs on.
-
- To configure a cross-compiler, cross-assembler, or what have you, you
-should specify a target different from the host, using the configure
-option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
-for the host type. So the command would look like this:
-
- ./configure HOSTTYPE --target=TARGETTYPE
-
- Programs for which cross-operation is not meaningful need not accept
-the `--target' option, because configuring an entire operating system
-for cross-operation is not a meaningful operation.
-
- Bootstrapping a cross-compiler requires compiling it on a machine
-other than the host it will run on. Compilation packages accept a
-configuration option `--build=BUILDTYPE' for specifying the
-configuration on which you will compile them, but the configure script
-should normally guess the build machine type (using `config.guess'), so
-this option is probably not necessary. The host and target types
-normally default from the build type, so in bootstrapping a
-cross-compiler you must specify them both explicitly.
-
- Some programs have ways of configuring themselves automatically. If
-your program is set up to do this, your `configure' script can simply
-ignore most of its arguments.
-
-\1f
-File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
-
-7.2 Makefile Conventions
-========================
-
-This node describes conventions for writing the Makefiles for GNU
-programs. Using Automake will help you write a Makefile that follows
-these conventions.
-
-* Menu:
-
-* Makefile Basics:: General Conventions for Makefiles
-* Utilities in Makefiles:: Utilities in Makefiles
-* Command Variables:: Variables for Specifying Commands
-* Directory Variables:: Variables for Installation Directories
-* Standard Targets:: Standard Targets for Users
-* Install Command Categories:: Three categories of commands in the `install'
- rule: normal, pre-install and post-install.
-
-\1f
-File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
-
-7.2.1 General Conventions for Makefiles
----------------------------------------
-
-Every Makefile should contain this line:
-
- SHELL = /bin/sh
-
-to avoid trouble on systems where the `SHELL' variable might be
-inherited from the environment. (This is never a problem with GNU
-`make'.)
-
- Different `make' programs have incompatible suffix lists and
-implicit rules, and this sometimes creates confusion or misbehavior. So
-it is a good idea to set the suffix list explicitly using only the
-suffixes you need in the particular Makefile, like this:
-
- .SUFFIXES:
- .SUFFIXES: .c .o
-
-The first line clears out the suffix list, the second introduces all
-suffixes which may be subject to implicit rules in this Makefile.
-
- Don't assume that `.' is in the path for command execution. When
-you need to run programs that are a part of your package during the
-make, please make sure that it uses `./' if the program is built as
-part of the make or `$(srcdir)/' if the file is an unchanging part of
-the source code. Without one of these prefixes, the current search
-path is used.
-
- The distinction between `./' (the "build directory") and
-`$(srcdir)/' (the "source directory") is important because users can
-build in a separate directory using the `--srcdir' option to
-`configure'. A rule of the form:
-
- foo.1 : foo.man sedscript
- sed -e sedscript foo.man > foo.1
-
-will fail when the build directory is not the source directory, because
-`foo.man' and `sedscript' are in the source directory.
-
- When using GNU `make', relying on `VPATH' to find the source file
-will work in the case where there is a single dependency file, since
-the `make' automatic variable `$<' will represent the source file
-wherever it is. (Many versions of `make' set `$<' only in implicit
-rules.) A Makefile target like
-
- foo.o : bar.c
- $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
-
-should instead be written as
-
- foo.o : bar.c
- $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
-
-in order to allow `VPATH' to work correctly. When the target has
-multiple dependencies, using an explicit `$(srcdir)' is the easiest way
-to make the rule work well. For example, the target above for `foo.1'
-is best written as:
-
- foo.1 : foo.man sedscript
- sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
-
- GNU distributions usually contain some files which are not source
-files--for example, Info files, and the output from Autoconf, Automake,
-Bison or Flex. Since these files normally appear in the source
-directory, they should always appear in the source directory, not in the
-build directory. So Makefile rules to update them should put the
-updated files in the source directory.
-
- However, if a file does not appear in the distribution, then the
-Makefile should not put it in the source directory, because building a
-program in ordinary circumstances should not modify the source directory
-in any way.
-
- Try to make the build and installation targets, at least (and all
-their subtargets) work correctly with a parallel `make'.
-
-\1f
-File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
-
-7.2.2 Utilities in Makefiles
-----------------------------
-
-Write the Makefile commands (and any shell scripts, such as
-`configure') to run in `sh', not in `csh'. Don't use any special
-features of `ksh' or `bash'.
-
- The `configure' script and the Makefile rules for building and
-installation should not use any utilities directly except these:
-
- cat cmp cp diff echo egrep expr false grep install-info
- ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
-
- The compression program `gzip' can be used in the `dist' rule.
-
- Stick to the generally supported options for these programs. For
-example, don't use `mkdir -p', convenient as it may be, because most
-systems don't support it.
-
- It is a good idea to avoid creating symbolic links in makefiles,
-since a few systems don't support them.
-
- The Makefile rules for building and installation can also use
-compilers and related programs, but should do so via `make' variables
-so that the user can substitute alternatives. Here are some of the
-programs we mean:
-
- ar bison cc flex install ld ldconfig lex
- make makeinfo ranlib texi2dvi yacc
-
- Use the following `make' variables to run those programs:
-
- $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
- $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
-
- When you use `ranlib' or `ldconfig', you should make sure nothing
-bad happens if the system does not have the program in question.
-Arrange to ignore an error from that command, and print a message before
-the command to tell the user that failure of this command does not mean
-a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
-
- If you use symbolic links, you should implement a fallback for
-systems that don't have symbolic links.
-
- Additional utilities that can be used via Make variables are:
-
- chgrp chmod chown mknod
-
- It is ok to use other utilities in Makefile portions (or scripts)
-intended only for particular systems where you know those utilities
-exist.
-
-\1f
-File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
-
-7.2.3 Variables for Specifying Commands
----------------------------------------
-
-Makefiles should provide variables for overriding certain commands,
-options, and so on.
-
- In particular, you should run most utility programs via variables.
-Thus, if you use Bison, have a variable named `BISON' whose default
-value is set with `BISON = bison', and refer to it with `$(BISON)'
-whenever you need to use Bison.
-
- File management utilities such as `ln', `rm', `mv', and so on, need
-not be referred to through variables in this way, since users don't
-need to replace them with other programs.
-
- Each program-name variable should come with an options variable that
-is used to supply options to the program. Append `FLAGS' to the
-program-name variable name to get the options variable name--for
-example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
-`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
-but we keep them because they are standard.) Use `CPPFLAGS' in any
-compilation command that runs the preprocessor, and use `LDFLAGS' in
-any compilation command that does linking as well as in any direct use
-of `ld'.
-
- If there are C compiler options that _must_ be used for proper
-compilation of certain files, do not include them in `CFLAGS'. Users
-expect to be able to specify `CFLAGS' freely themselves. Instead,
-arrange to pass the necessary options to the C compiler independently
-of `CFLAGS', by writing them explicitly in the compilation commands or
-by defining an implicit rule, like this:
-
- CFLAGS = -g
- ALL_CFLAGS = -I. $(CFLAGS)
- .c.o:
- $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
-
- Do include the `-g' option in `CFLAGS', because that is not
-_required_ for proper compilation. You can consider it a default that
-is only recommended. If the package is set up so that it is compiled
-with GCC by default, then you might as well include `-O' in the default
-value of `CFLAGS' as well.
-
- Put `CFLAGS' last in the compilation command, after other variables
-containing compiler options, so the user can use `CFLAGS' to override
-the others.
-
- `CFLAGS' should be used in every invocation of the C compiler, both
-those which do compilation and those which do linking.
-
- Every Makefile should define the variable `INSTALL', which is the
-basic command for installing a file into the system.
-
- Every Makefile should also define the variables `INSTALL_PROGRAM'
-and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
-`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
-644'.) Then it should use those variables as the commands for actual
-installation, for executables and nonexecutables respectively. Use
-these variables as follows:
-
- $(INSTALL_PROGRAM) foo $(bindir)/foo
- $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
-
- Optionally, you may prepend the value of `DESTDIR' to the target
-filename. Doing this allows the installer to create a snapshot of the
-installation to be copied onto the real target filesystem later. Do not
-set the value of `DESTDIR' in your Makefile, and do not include it in
-any installed files. With support for `DESTDIR', the above examples
-become:
-
- $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
- $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
-
-Always use a file name, not a directory name, as the second argument of
-the installation commands. Use a separate command for each file to be
-installed.
-
-\1f
-File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
-
-7.2.4 Variables for Installation Directories
---------------------------------------------
-
-Installation directories should always be named by variables, so it is
-easy to install in a nonstandard place. The standard names for these
-variables are described below. They are based on a standard filesystem
-layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
-and other modern operating systems.
-
- These two variables set the root for the installation. All the other
-installation directories should be subdirectories of one of these two,
-and nothing should be directly installed into these two directories.
-
-`prefix'
- A prefix used in constructing the default values of the variables
- listed below. The default value of `prefix' should be
- `/usr/local'. When building the complete GNU system, the prefix
- will be empty and `/usr' will be a symbolic link to `/'. (If you
- are using Autoconf, write it as `@prefix@'.)
-
- Running `make install' with a different value of `prefix' from the
- one used to build the program should _not_ recompile the program.
-
-`exec_prefix'
- A prefix used in constructing the default values of some of the
- variables listed below. The default value of `exec_prefix' should
- be `$(prefix)'. (If you are using Autoconf, write it as
- `@exec_prefix@'.)
-
- Generally, `$(exec_prefix)' is used for directories that contain
- machine-specific files (such as executables and subroutine
- libraries), while `$(prefix)' is used directly for other
- directories.
-
- Running `make install' with a different value of `exec_prefix'
- from the one used to build the program should _not_ recompile the
- program.
-
- Executable programs are installed in one of the following
-directories.
-
-`bindir'
- The directory for installing executable programs that users can
- run. This should normally be `/usr/local/bin', but write it as
- `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
- `@bindir@'.)
-
-`sbindir'
- The directory for installing executable programs that can be run
- from the shell, but are only generally useful to system
- administrators. This should normally be `/usr/local/sbin', but
- write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
- write it as `@sbindir@'.)
-
-`libexecdir'
- The directory for installing executable programs to be run by other
- programs rather than by users. This directory should normally be
- `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
- (If you are using Autoconf, write it as `@libexecdir@'.)
-
- Data files used by the program during its execution are divided into
-categories in two ways.
-
- * Some files are normally modified by programs; others are never
- normally modified (though users may edit some of these).
-
- * Some files are architecture-independent and can be shared by all
- machines at a site; some are architecture-dependent and can be
- shared only by machines of the same kind and operating system;
- others may never be shared between two machines.
-
- This makes for six different possibilities. However, we want to
-discourage the use of architecture-dependent files, aside from object
-files and libraries. It is much cleaner to make other data files
-architecture-independent, and it is generally not hard.
-
- Therefore, here are the variables Makefiles should use to specify
-directories:
-
-`datadir'
- The directory for installing read-only architecture independent
- data files. This should normally be `/usr/local/share', but write
- it as `$(prefix)/share'. (If you are using Autoconf, write it as
- `@datadir@'.) As a special exception, see `$(infodir)' and
- `$(includedir)' below.
-
-`sysconfdir'
- The directory for installing read-only data files that pertain to a
- single machine-that is to say, files for configuring a host.
- Mailer and network configuration files, `/etc/passwd', and so
- forth belong here. All the files in this directory should be
- ordinary ASCII text files. This directory should normally be
- `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
- using Autoconf, write it as `@sysconfdir@'.)
-
- Do not install executables here in this directory (they probably
- belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
- files that are modified in the normal course of their use (programs
- whose purpose is to change the configuration of the system
- excluded). Those probably belong in `$(localstatedir)'.
-
-`sharedstatedir'
- The directory for installing architecture-independent data files
- which the programs modify while they run. This should normally be
- `/usr/local/com', but write it as `$(prefix)/com'. (If you are
- using Autoconf, write it as `@sharedstatedir@'.)
-
-`localstatedir'
- The directory for installing data files which the programs modify
- while they run, and that pertain to one specific machine. Users
- should never need to modify files in this directory to configure
- the package's operation; put such configuration information in
- separate files that go in `$(datadir)' or `$(sysconfdir)'.
- `$(localstatedir)' should normally be `/usr/local/var', but write
- it as `$(prefix)/var'. (If you are using Autoconf, write it as
- `@localstatedir@'.)
-
-`libdir'
- The directory for object files and libraries of object code. Do
- not install executables here, they probably ought to go in
- `$(libexecdir)' instead. The value of `libdir' should normally be
- `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
- are using Autoconf, write it as `@libdir@'.)
-
-`infodir'
- The directory for installing the Info files for this package. By
- default, it should be `/usr/local/info', but it should be written
- as `$(prefix)/info'. (If you are using Autoconf, write it as
- `@infodir@'.)
-
-`lispdir'
- The directory for installing any Emacs Lisp files in this package.
- By default, it should be `/usr/local/share/emacs/site-lisp', but
- it should be written as `$(prefix)/share/emacs/site-lisp'.
-
- If you are using Autoconf, write the default as `@lispdir@'. In
- order to make `@lispdir@' work, you need the following lines in
- your `configure.in' file:
-
- lispdir='${datadir}/emacs/site-lisp'
- AC_SUBST(lispdir)
-
-`includedir'
- The directory for installing header files to be included by user
- programs with the C `#include' preprocessor directive. This
- should normally be `/usr/local/include', but write it as
- `$(prefix)/include'. (If you are using Autoconf, write it as
- `@includedir@'.)
-
- Most compilers other than GCC do not look for header files in
- directory `/usr/local/include'. So installing the header files
- this way is only useful with GCC. Sometimes this is not a problem
- because some libraries are only really intended to work with GCC.
- But some libraries are intended to work with other compilers.
- They should install their header files in two places, one
- specified by `includedir' and one specified by `oldincludedir'.
-
-`oldincludedir'
- The directory for installing `#include' header files for use with
- compilers other than GCC. This should normally be `/usr/include'.
- (If you are using Autoconf, you can write it as `@oldincludedir@'.)
-
- The Makefile commands should check whether the value of
- `oldincludedir' is empty. If it is, they should not try to use
- it; they should cancel the second installation of the header files.
-
- A package should not replace an existing header in this directory
- unless the header came from the same package. Thus, if your Foo
- package provides a header file `foo.h', then it should install the
- header file in the `oldincludedir' directory if either (1) there
- is no `foo.h' there or (2) the `foo.h' that exists came from the
- Foo package.
-
- To tell whether `foo.h' came from the Foo package, put a magic
- string in the file--part of a comment--and `grep' for that string.
-
- Unix-style man pages are installed in one of the following:
-
-`mandir'
- The top-level directory for installing the man pages (if any) for
- this package. It will normally be `/usr/local/man', but you should
- write it as `$(prefix)/man'. (If you are using Autoconf, write it
- as `@mandir@'.)
-
-`man1dir'
- The directory for installing section 1 man pages. Write it as
- `$(mandir)/man1'.
-
-`man2dir'
- The directory for installing section 2 man pages. Write it as
- `$(mandir)/man2'
-
-`...'
- *Don't make the primary documentation for any GNU software be a
- man page. Write a manual in Texinfo instead. Man pages are just
- for the sake of people running GNU software on Unix, which is a
- secondary application only.*
-
-`manext'
- The file name extension for the installed man page. This should
- contain a period followed by the appropriate digit; it should
- normally be `.1'.
-
-`man1ext'
- The file name extension for installed section 1 man pages.
-
-`man2ext'
- The file name extension for installed section 2 man pages.
-
-`...'
- Use these names instead of `manext' if the package needs to
- install man pages in more than one section of the manual.
-
- And finally, you should set the following variable:
-
-`srcdir'
- The directory for the sources being compiled. The value of this
- variable is normally inserted by the `configure' shell script.
- (If you are using Autconf, use `srcdir = @srcdir@'.)
-
- For example:
-
- # Common prefix for installation directories.
- # NOTE: This directory must exist when you start the install.
- prefix = /usr/local
- exec_prefix = $(prefix)
- # Where to put the executable for the command `gcc'.
- bindir = $(exec_prefix)/bin
- # Where to put the directories used by the compiler.
- libexecdir = $(exec_prefix)/libexec
- # Where to put the Info files.
- infodir = $(prefix)/info
-
- If your program installs a large number of files into one of the
-standard user-specified directories, it might be useful to group them
-into a subdirectory particular to that program. If you do this, you
-should write the `install' rule to create these subdirectories.
-
- Do not expect the user to include the subdirectory name in the value
-of any of the variables listed above. The idea of having a uniform set
-of variable names for installation directories is to enable the user to
-specify the exact same values for several different GNU packages. In
-order for this to be useful, all the packages must be designed so that
-they will work sensibly when the user does so.
-
-\1f
-File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
-
-7.2.5 Standard Targets for Users
---------------------------------
-
-All GNU programs should have the following targets in their Makefiles:
-
-`all'
- Compile the entire program. This should be the default target.
- This target need not rebuild any documentation files; Info files
- should normally be included in the distribution, and DVI files
- should be made only when explicitly asked for.
-
- By default, the Make rules should compile and link with `-g', so
- that executable programs have debugging symbols. Users who don't
- mind being helpless can strip the executables later if they wish.
-
-`install'
- Compile the program and copy the executables, libraries, and so on
- to the file names where they should reside for actual use. If
- there is a simple test to verify that a program is properly
- installed, this target should run that test.
-
- Do not strip executables when installing them. Devil-may-care
- users can use the `install-strip' target to do that.
-
- If possible, write the `install' target rule so that it does not
- modify anything in the directory where the program was built,
- provided `make all' has just been done. This is convenient for
- building the program under one user name and installing it under
- another.
-
- The commands should create all the directories in which files are
- to be installed, if they don't already exist. This includes the
- directories specified as the values of the variables `prefix' and
- `exec_prefix', as well as all subdirectories that are needed. One
- way to do this is by means of an `installdirs' target as described
- below.
-
- Use `-' before any command for installing a man page, so that
- `make' will ignore any errors. This is in case there are systems
- that don't have the Unix man page documentation system installed.
-
- The way to install Info files is to copy them into `$(infodir)'
- with `$(INSTALL_DATA)' (*note Command Variables::), and then run
- the `install-info' program if it is present. `install-info' is a
- program that edits the Info `dir' file to add or update the menu
- entry for the given Info file; it is part of the Texinfo package.
- Here is a sample rule to install an Info file:
-
- $(DESTDIR)$(infodir)/foo.info: foo.info
- $(POST_INSTALL)
- # There may be a newer info file in . than in srcdir.
- -if test -f foo.info; then d=.; \
- else d=$(srcdir); fi; \
- $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
- # Run install-info only if it exists.
- # Use `if' instead of just prepending `-' to the
- # line so we notice real errors from install-info.
- # We use `$(SHELL) -c' because some shells do not
- # fail gracefully when there is an unknown command.
- if $(SHELL) -c 'install-info --version' \
- >/dev/null 2>&1; then \
- install-info --dir-file=$(DESTDIR)$(infodir)/dir \
- $(DESTDIR)$(infodir)/foo.info; \
- else true; fi
-
- When writing the `install' target, you must classify all the
- commands into three categories: normal ones, "pre-installation"
- commands and "post-installation" commands. *Note Install Command
- Categories::.
-
-`uninstall'
- Delete all the installed files--the copies that the `install'
- target creates.
-
- This rule should not modify the directories where compilation is
- done, only the directories where files are installed.
-
- The uninstallation commands are divided into three categories,
- just like the installation commands. *Note Install Command
- Categories::.
-
-`install-strip'
- Like `install', but strip the executable files while installing
- them. In simple cases, this target can use the `install' target in
- a simple way:
-
- install-strip:
- $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
- install
-
- But if the package installs scripts as well as real executables,
- the `install-strip' target can't just refer to the `install'
- target; it has to strip the executables but not the scripts.
-
- `install-strip' should not strip the executables in the build
- directory which are being copied for installation. It should only
- strip the copies that are installed.
-
- Normally we do not recommend stripping an executable unless you
- are sure the program has no bugs. However, it can be reasonable
- to install a stripped executable for actual execution while saving
- the unstripped executable elsewhere in case there is a bug.
-
-`clean'
- Delete all files from the current directory that are normally
- created by building the program. Don't delete the files that
- record the configuration. Also preserve files that could be made
- by building, but normally aren't because the distribution comes
- with them.
-
- Delete `.dvi' files here if they are not part of the distribution.
-
-`distclean'
- Delete all files from the current directory that are created by
- configuring or building the program. If you have unpacked the
- source and built the program without creating any other files,
- `make distclean' should leave only the files that were in the
- distribution.
-
-`mostlyclean'
- Like `clean', but may refrain from deleting a few files that people
- normally don't want to recompile. For example, the `mostlyclean'
- target for GCC does not delete `libgcc.a', because recompiling it
- is rarely necessary and takes a lot of time.
-
-`maintainer-clean'
- Delete almost everything from the current directory that can be
- reconstructed with this Makefile. This typically includes
- everything deleted by `distclean', plus more: C source files
- produced by Bison, tags tables, Info files, and so on.
-
- The reason we say "almost everything" is that running the command
- `make maintainer-clean' should not delete `configure' even if
- `configure' can be remade using a rule in the Makefile. More
- generally, `make maintainer-clean' should not delete anything that
- needs to exist in order to run `configure' and then begin to build
- the program. This is the only exception; `maintainer-clean' should
- delete everything else that can be rebuilt.
-
- The `maintainer-clean' target is intended to be used by a
- maintainer of the package, not by ordinary users. You may need
- special tools to reconstruct some of the files that `make
- maintainer-clean' deletes. Since these files are normally
- included in the distribution, we don't take care to make them easy
- to reconstruct. If you find you need to unpack the full
- distribution again, don't blame us.
-
- To help make users aware of this, the commands for the special
- `maintainer-clean' target should start with these two:
-
- @echo 'This command is intended for maintainers to use; it'
- @echo 'deletes files that may need special tools to rebuild.'
-
-`TAGS'
- Update a tags table for this program.
-
-`info'
- Generate any Info files needed. The best way to write the rules
- is as follows:
-
- info: foo.info
-
- foo.info: foo.texi chap1.texi chap2.texi
- $(MAKEINFO) $(srcdir)/foo.texi
-
- You must define the variable `MAKEINFO' in the Makefile. It should
- run the `makeinfo' program, which is part of the Texinfo
- distribution.
-
- Normally a GNU distribution comes with Info files, and that means
- the Info files are present in the source directory. Therefore,
- the Make rule for an info file should update it in the source
- directory. When users build the package, ordinarily Make will not
- update the Info files because they will already be up to date.
-
-`dvi'
- Generate DVI files for all Texinfo documentation. For example:
-
- dvi: foo.dvi
-
- foo.dvi: foo.texi chap1.texi chap2.texi
- $(TEXI2DVI) $(srcdir)/foo.texi
-
- You must define the variable `TEXI2DVI' in the Makefile. It should
- run the program `texi2dvi', which is part of the Texinfo
- distribution.(1) Alternatively, write just the dependencies, and
- allow GNU `make' to provide the command.
-
-`dist'
- Create a distribution tar file for this program. The tar file
- should be set up so that the file names in the tar file start with
- a subdirectory name which is the name of the package it is a
- distribution for. This name can include the version number.
-
- For example, the distribution tar file of GCC version 1.40 unpacks
- into a subdirectory named `gcc-1.40'.
-
- The easiest way to do this is to create a subdirectory
- appropriately named, use `ln' or `cp' to install the proper files
- in it, and then `tar' that subdirectory.
-
- Compress the tar file with `gzip'. For example, the actual
- distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
-
- The `dist' target should explicitly depend on all non-source files
- that are in the distribution, to make sure they are up to date in
- the distribution. *Note Making Releases: Releases.
-
-`check'
- Perform self-tests (if any). The user must build the program
- before running the tests, but need not install the program; you
- should write the self-tests so that they work when the program is
- built but not installed.
-
- The following targets are suggested as conventional names, for
-programs in which they are useful.
-
-`installcheck'
- Perform installation tests (if any). The user must build and
- install the program before running the tests. You should not
- assume that `$(bindir)' is in the search path.
-
-`installdirs'
- It's useful to add a target named `installdirs' to create the
- directories where files are installed, and their parent
- directories. There is a script called `mkinstalldirs' which is
- convenient for this; you can find it in the Texinfo package. You
- can use a rule like this:
-
- # Make sure all installation directories (e.g. $(bindir))
- # actually exist by making them if necessary.
- installdirs: mkinstalldirs
- $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
- $(libdir) $(infodir) \
- $(mandir)
-
- or, if you wish to support `DESTDIR',
-
- # Make sure all installation directories (e.g. $(bindir))
- # actually exist by making them if necessary.
- installdirs: mkinstalldirs
- $(srcdir)/mkinstalldirs \
- $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
- $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
- $(DESTDIR)$(mandir)
-
- This rule should not modify the directories where compilation is
- done. It should do nothing but create installation directories.
-
- ---------- Footnotes ----------
-
- (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
-not distributed with Texinfo.
-
-\1f
-File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
-
-7.2.6 Install Command Categories
---------------------------------
-
-When writing the `install' target, you must classify all the commands
-into three categories: normal ones, "pre-installation" commands and
-"post-installation" commands.
-
- Normal commands move files into their proper places, and set their
-modes. They may not alter any files except the ones that come entirely
-from the package they belong to.
-
- Pre-installation and post-installation commands may alter other
-files; in particular, they can edit global configuration files or data
-bases.
-
- Pre-installation commands are typically executed before the normal
-commands, and post-installation commands are typically run after the
-normal commands.
-
- The most common use for a post-installation command is to run
-`install-info'. This cannot be done with a normal command, since it
-alters a file (the Info directory) which does not come entirely and
-solely from the package being installed. It is a post-installation
-command because it needs to be done after the normal command which
-installs the package's Info files.
-
- Most programs don't need any pre-installation commands, but we have
-the feature just in case it is needed.
-
- To classify the commands in the `install' rule into these three
-categories, insert "category lines" among them. A category line
-specifies the category for the commands that follow.
-
- A category line consists of a tab and a reference to a special Make
-variable, plus an optional comment at the end. There are three
-variables you can use, one for each category; the variable name
-specifies the category. Category lines are no-ops in ordinary execution
-because these three Make variables are normally undefined (and you
-_should not_ define them in the makefile).
-
- Here are the three possible category lines, each with a comment that
-explains what it means:
-
- $(PRE_INSTALL) # Pre-install commands follow.
- $(POST_INSTALL) # Post-install commands follow.
- $(NORMAL_INSTALL) # Normal commands follow.
-
- If you don't use a category line at the beginning of the `install'
-rule, all the commands are classified as normal until the first category
-line. If you don't use any category lines, all the commands are
-classified as normal.
-
- These are the category lines for `uninstall':
-
- $(PRE_UNINSTALL) # Pre-uninstall commands follow.
- $(POST_UNINSTALL) # Post-uninstall commands follow.
- $(NORMAL_UNINSTALL) # Normal commands follow.
-
- Typically, a pre-uninstall command would be used for deleting entries
-from the Info directory.
-
- If the `install' or `uninstall' target has any dependencies which
-act as subroutines of installation, then you should start _each_
-dependency's commands with a category line, and start the main target's
-commands with a category line also. This way, you can ensure that each
-command is placed in the right category regardless of which of the
-dependencies actually run.
-
- Pre-installation and post-installation commands should not run any
-programs except for these:
-
- [ basename bash cat chgrp chmod chown cmp cp dd diff echo
- egrep expand expr false fgrep find getopt grep gunzip gzip
- hostname install install-info kill ldconfig ln ls md5sum
- mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
- test touch true uname xargs yes
-
- The reason for distinguishing the commands in this way is for the
-sake of making binary packages. Typically a binary package contains
-all the executables and other files that need to be installed, and has
-its own method of installing them--so it does not need to run the normal
-installation commands. But installing the binary package does need to
-execute the pre-installation and post-installation commands.
-
- Programs to build binary packages work by extracting the
-pre-installation and post-installation commands. Here is one way of
-extracting the pre-installation commands:
-
- make -n install -o all \
- PRE_INSTALL=pre-install \
- POST_INSTALL=post-install \
- NORMAL_INSTALL=normal-install \
- | gawk -f pre-install.awk
-
-where the file `pre-install.awk' could contain this:
-
- $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
- on {print $0}
- $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
-
- The resulting file of pre-installation commands is executed as a
-shell script as part of installing the binary package.
-
-\1f
-File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
-
-7.3 Making Releases
-===================
-
-Package the distribution of `Foo version 69.96' up in a gzipped tar
-file with the name `foo-69.96.tar.gz'. It should unpack into a
-subdirectory named `foo-69.96'.
-
- Building and installing the program should never modify any of the
-files contained in the distribution. This means that all the files
-that form part of the program in any way must be classified into "source
-files" and "non-source files". Source files are written by humans and
-never changed automatically; non-source files are produced from source
-files by programs under the control of the Makefile.
-
- The distribution should contain a file named `README' which gives
-the name of the package, and a general description of what it does. It
-is also good to explain the purpose of each of the first-level
-subdirectories in the package, if there are any. The `README' file
-should either state the version number of the package, or refer to where
-in the package it can be found.
-
- The `README' file should refer to the file `INSTALL', which should
-contain an explanation of the installation procedure.
-
- The `README' file should also refer to the file which contains the
-copying conditions. The GNU GPL, if used, should be in a file called
-`COPYING'. If the GNU LGPL is used, it should be in a file called
-`COPYING.LIB'.
-
- Naturally, all the source files must be in the distribution. It is
-okay to include non-source files in the distribution, provided they are
-up-to-date and machine-independent, so that building the distribution
-normally will never modify them. We commonly include non-source files
-produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
-unnecessary dependencies between our distributions, so that users can
-install whichever packages they want to install.
-
- Non-source files that might actually be modified by building and
-installing the program should *never* be included in the distribution.
-So if you do distribute non-source files, always make sure they are up
-to date when you make a new distribution.
-
- Make sure that the directory into which the distribution unpacks (as
-well as any subdirectories) are all world-writable (octal mode 777).
-This is so that old versions of `tar' which preserve the ownership and
-permissions of the files from the tar archive will be able to extract
-all the files even if the user is unprivileged.
-
- Make sure that all the files in the distribution are world-readable.
-
- Make sure that no file name in the distribution is more than 14
-characters long. Likewise, no file created by building the program
-should have a name longer than 14 characters. The reason for this is
-that some systems adhere to a foolish interpretation of the POSIX
-standard, and refuse to open a longer name, rather than truncating as
-they did in the past.
-
- Don't include any symbolic links in the distribution itself. If the
-tar file contains symbolic links, then people cannot even unpack it on
-systems that don't support symbolic links. Also, don't use multiple
-names for one file in different directories, because certain file
-systems cannot handle this and that prevents unpacking the distribution.
-
- Try to make sure that all the file names will be unique on MS-DOS. A
-name on MS-DOS consists of up to 8 characters, optionally followed by a
-period and up to three characters. MS-DOS will truncate extra
-characters both before and after the period. Thus, `foobarhacker.c'
-and `foobarhacker.o' are not ambiguous; they are truncated to
-`foobarha.c' and `foobarha.o', which are distinct.
-
- Include in your distribution a copy of the `texinfo.tex' you used to
-test print any `*.texinfo' or `*.texi' files.
-
- Likewise, if your program uses small GNU software packages like
-regex, getopt, obstack, or termcap, include them in the distribution
-file. Leaving them out would make the distribution file a little
-smaller at the expense of possible inconvenience to a user who doesn't
-know what other files to get.
-
-\1f
-File: standards.info, Node: References, Next: Copying This Manual, Prev: Managing Releases, Up: Top
-
-8 References to Non-Free Software and Documentation
-***************************************************
-
-A GNU program should not recommend use of any non-free program. We
-can't stop some people from writing proprietary programs, or stop other
-people from using them, but we can and should avoid helping to
-advertise them to new potential customers. Proprietary software is a
-social and ethical problem, and the point of GNU is to solve that
-problem.
-
- When a non-free program or system is well known, you can mention it
-in passing--that is harmless, since users who might want to use it
-probably already know about it. For instance, it is fine to explain
-how to build your package on top of some non-free operating system, or
-how to use it together with some widely used non-free program.
-
- However, you should give only the necessary information to help those
-who already use the non-free program to use your program with it--don't
-give, or refer to, any further information about the proprietary
-program, and don't imply that the proprietary program enhances your
-program, or that its existence is in any way a good thing. The goal
-should be that people already using the proprietary program will get
-the advice they need about how to use your free program, while people
-who don't already use the proprietary program will not see anything to
-lead them to take an interest in it.
-
- If a non-free program or system is obscure in your program's domain,
-your program should not mention or support it at all, since doing so
-would tend to popularize the non-free program more than it popularizes
-your program. (You cannot hope to find many additional users among the
-users of Foobar if the users of Foobar are few.)
-
- A GNU package should not refer the user to any non-free documentation
-for free software. Free documentation that can be included in free
-operating systems is essential for completing the GNU system, so it is
-a major focus of the GNU Project; to recommend use of documentation
-that we are not allowed to use in GNU would undermine the efforts to
-get documentation that we can include. So GNU packages should never
-recommend non-free documentation.
-
-\1f
-File: standards.info, Node: Copying This Manual, Next: Index, Prev: References, Up: Top
-
-Appendix A Copying This Manual
-******************************
-
-* Menu:
-
-* GNU Free Documentation License:: License for copying this manual
-
-\1f
-File: standards.info, Node: GNU Free Documentation License, Up: Copying This Manual
-
-Appendix B GNU Free Documentation License
-*****************************************
-
- Version 1.1, March 2000
-
- Copyright (C) 2000 Free Software Foundation, Inc.
- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone
- the effective freedom to copy and redistribute it, with or without
- modifying it, either commercially or noncommercially. Secondarily,
- this License preserves for the author and publisher a way to get
- credit for their work, while not being considered responsible for
- modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to
- software manuals; it can be used for any textual work, regardless
- of subject matter or whether it is published as a printed book.
- We recommend this License principally for works whose purpose is
- instruction or reference.
-
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be distributed
- under the terms of this License. The "Document", below, refers to
- any such manual or work. Any member of the public is a licensee,
- and is addressed as "you."
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter
- section of the Document that deals exclusively with the
- relationship of the publishers or authors of the Document to the
- Document's overall subject (or to related matters) and contains
- nothing that could fall directly within that overall subject.
- (For example, if the Document is in part a textbook of
- mathematics, a Secondary Section may not explain any mathematics.)
- The relationship could be a matter of historical connection with
- the subject or with related matters, or of legal, commercial,
- philosophical, ethical or political position regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, whose contents can be viewed and edited directly
- and straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup has been designed
- to thwart or discourage subsequent modification by readers is not
- Transparent. A copy that is not "Transparent" is called "Opaque."
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human modification.
- Opaque formats include PostScript, PDF, proprietary formats that
- can be read and edited only by proprietary word processors, SGML
- or XML for which the DTD and/or processing tools are not generally
- available, and the machine-generated HTML produced by some word
- processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, "Title
- Page" means the text near the most prominent appearance of the
- work's title, preceding the beginning of the body of the text.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow
- the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more than
- 100, and the Document's license notice requires Cover Texts, you
- must enclose the copies in covers that carry, clearly and legibly,
- all these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the
- title equally prominent and visible. You may add other material
- on the covers in addition. Copying with changes limited to the
- covers, as long as they preserve the title of the Document and
- satisfy these conditions, can be treated as verbatim copying in
- other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy, or
- state in or with each Opaque copy a publicly-accessible
- computer-network location containing a complete Transparent copy
- of the Document, free of added material, which the general
- network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with
- the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version to
- whoever possesses a copy of it. In addition, you must do these
- things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title
- as a previous version if the original publisher of that version
- gives permission.
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it
- has less than five).
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page.
- If there is no section entitled "History" in the Document,
- create one stating the title, year, authors, and publisher of
- the Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in the
- "History" section. You may omit a network location for a work
- that was published at least four years before the Document
- itself, or if the original publisher of the version it refers
- to gives permission.
- K. In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
- M. Delete any section entitled "Endorsements." Such a section
- may not be included in the Modified Version.
- N. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do this,
- add their titles to the list of Invariant Sections in the Modified
- Version's license notice. These titles must be distinct from any
- other section titles.
-
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties-for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition
- of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If the
- Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same entity
- you are acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section
- entitled "History"; likewise combine any sections entitled
- "Acknowledgements", and any sections entitled "Dedications." You
- must delete all sections entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow
- this License in all other respects regarding verbatim copying of
- that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of
- a storage or distribution medium, does not as a whole count as a
- Modified Version of the Document, provided no compilation
- copyright is claimed for the compilation. Such a compilation is
- called an "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document, on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may be
- placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License provided that you also include the
- original English version of this License. In case of a
- disagreement between the translation and the original English
- version of this License, the original English version will prevail.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-====================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.1
- or any later version published by the Free Software Foundation;
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License."
-
- If you have no Invariant Sections, write "with no Invariant Sections"
-instead of saying which ones are invariant. If you have no Front-Cover
-Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
-LIST"; likewise for Back-Cover Texts.
-
- If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License, to
-permit their use in free software.
-
-\1f
-File: standards.info, Node: Index, Prev: Copying This Manual, Up: Top
-
-Index
-*****
-
-\0\b[index\0\b]
-* Menu:
-
-* #endif, commenting: Comments. (line 54)
-* --help option: Command-Line Interfaces.
- (line 119)
-* --version option: Command-Line Interfaces.
- (line 34)
-* -Wall compiler option: Syntactic Conventions.
- (line 10)
-* accepting contributions: Contributions. (line 6)
-* address for bug reports: Command-Line Interfaces.
- (line 125)
-* ANSI C standard: Standard C. (line 6)
-* arbitrary limits on data: Semantics. (line 6)
-* autoconf: System Portability. (line 23)
-* avoiding proprietary code: Reading Non-Free Code.
- (line 6)
-* behavior, dependent on program's name: User Interfaces. (line 6)
-* binary packages: Install Command Categories.
- (line 80)
-* bindir: Directory Variables. (line 45)
-* braces, in C source: Formatting. (line 6)
-* bug reports: Command-Line Interfaces.
- (line 125)
-* canonical name of a program: Command-Line Interfaces.
- (line 41)
-* casting pointers to integers: CPU Portability. (line 67)
-* change logs: Change Logs. (line 6)
-* change logs, conditional changes: Conditional Changes. (line 6)
-* change logs, style: Style of Change Logs.
- (line 6)
-* command-line arguments, decoding: Semantics. (line 46)
-* command-line interface: Command-Line Interfaces.
- (line 6)
-* commenting: Comments. (line 6)
-* compatibility with C and POSIX standards: Compatibility. (line 6)
-* compiler warnings: Syntactic Conventions.
- (line 10)
-* conditional changes, and change logs: Conditional Changes. (line 6)
-* conditionals, comments for: Comments. (line 54)
-* configure: Configuration. (line 6)
-* control-L: Formatting. (line 114)
-* conventions for makefiles: Makefile Conventions.
- (line 6)
-* corba: Graphical Interfaces.
- (line 16)
-* credits for manuals: Manual Credits. (line 6)
-* data types, and portability: CPU Portability. (line 6)
-* declaration for system functions: System Functions. (line 21)
-* documentation: Documentation. (line 6)
-* doschk: Names. (line 38)
-* downloading this manual: Preface. (line 17)
-* error messages: Semantics. (line 19)
-* error messages, formatting: Errors. (line 6)
-* exec_prefix: Directory Variables. (line 27)
-* expressions, splitting: Formatting. (line 77)
-* file usage: File Usage. (line 6)
-* file-name limitations: Names. (line 38)
-* formatting error messages: Errors. (line 6)
-* formatting source code: Formatting. (line 6)
-* formfeed: Formatting. (line 114)
-* function argument, declaring: Syntactic Conventions.
- (line 6)
-* function prototypes: Standard C. (line 17)
-* getopt: Command-Line Interfaces.
- (line 6)
-* gettext: Internationalization.
- (line 6)
-* gnome: Graphical Interfaces.
- (line 16)
-* graphical user interface: Graphical Interfaces.
- (line 6)
-* gtk: Graphical Interfaces.
- (line 6)
-* GUILE: Source Language. (line 38)
-* implicit int: Syntactic Conventions.
- (line 6)
-* impossible conditions: Semantics. (line 70)
-* internationalization: Internationalization.
- (line 6)
-* legal aspects: Legal Issues. (line 6)
-* legal papers: Contributions. (line 6)
-* libexecdir: Directory Variables. (line 58)
-* libraries: Libraries. (line 6)
-* library functions, and portability: System Functions. (line 6)
-* license for manuals: License for Manuals. (line 6)
-* lint: Syntactic Conventions.
- (line 109)
-* long option names: Option Table. (line 6)
-* long-named options: Command-Line Interfaces.
- (line 12)
-* makefile, conventions for: Makefile Conventions.
- (line 6)
-* malloc return value: Semantics. (line 25)
-* man pages: Man Pages. (line 6)
-* manual structure: Manual Structure Details.
- (line 6)
-* memory allocation failure: Semantics. (line 25)
-* memory usage: Memory Usage. (line 6)
-* message text, and internationalization: Internationalization.
- (line 29)
-* mmap: Mmap. (line 6)
-* multiple variables in a line: Syntactic Conventions.
- (line 35)
-* names of variables, functions, and files: Names. (line 6)
-* NEWS file: NEWS File. (line 6)
-* non-POSIX systems, and portability: System Portability. (line 32)
-* non-standard extensions: Using Extensions. (line 6)
-* NUL characters: Semantics. (line 11)
-* open brace: Formatting. (line 6)
-* optional features, configure-time: Configuration. (line 76)
-* options for compatibility: Compatibility. (line 14)
-* output device and program's behavior: User Interfaces. (line 13)
-* packaging: Releases. (line 6)
-* portability, and data types: CPU Portability. (line 6)
-* portability, and library functions: System Functions. (line 6)
-* portability, between system types: System Portability. (line 6)
-* POSIX compatibility: Compatibility. (line 6)
-* POSIXLY_CORRECT, environment variable: Compatibility. (line 21)
-* post-installation commands: Install Command Categories.
- (line 6)
-* pre-installation commands: Install Command Categories.
- (line 6)
-* prefix: Directory Variables. (line 17)
-* program configuration: Configuration. (line 6)
-* program design: Design Advice. (line 6)
-* program name and its behavior: User Interfaces. (line 6)
-* program's canonical name: Command-Line Interfaces.
- (line 41)
-* programming languges: Source Language. (line 6)
-* proprietary programs: Reading Non-Free Code.
- (line 6)
-* README file: Releases. (line 17)
-* references to non-free material: References. (line 6)
-* releasing: Managing Releases. (line 6)
-* sbindir: Directory Variables. (line 51)
-* signal handling: Semantics. (line 59)
-* spaces before open-paren: Formatting. (line 71)
-* standard command-line options: Command-Line Interfaces.
- (line 31)
-* standards for makefiles: Makefile Conventions.
- (line 6)
-* string library functions: System Functions. (line 55)
-* syntactic conventions: Syntactic Conventions.
- (line 6)
-* table of long options: Option Table. (line 6)
-* temporary files: Semantics. (line 84)
-* temporary variables: Syntactic Conventions.
- (line 23)
-* texinfo.tex, in a distribution: Releases. (line 73)
-* TMPDIR environment variable: Semantics. (line 84)
-* trademarks: Trademarks. (line 6)
-* where to obtain standards.texi: Preface. (line 17)
-
-
-\1f
-Tag Table:
-Node: Top\7f696
-Node: Preface\7f1396
-Node: Legal Issues\7f3616
-Node: Reading Non-Free Code\7f4080
-Node: Contributions\7f5808
-Node: Trademarks\7f7962
-Node: Design Advice\7f9025
-Node: Source Language\7f9609
-Node: Compatibility\7f11621
-Node: Using Extensions\7f13249
-Node: Standard C\7f14825
-Node: Conditional Compilation\7f17228
-Node: Program Behavior\7f18527
-Node: Semantics\7f19446
-Node: Libraries\7f24139
-Node: Errors\7f25384
-Node: User Interfaces\7f27165
-Node: Graphical Interfaces\7f28770
-Node: Command-Line Interfaces\7f29805
-Node: Option Table\7f35876
-Node: Memory Usage\7f50885
-Node: File Usage\7f51910
-Node: Writing C\7f52658
-Node: Formatting\7f53508
-Node: Comments\7f57571
-Node: Syntactic Conventions\7f60873
-Node: Names\7f64285
-Node: System Portability\7f66494
-Node: CPU Portability\7f68879
-Node: System Functions\7f72135
-Node: Internationalization\7f77332
-Node: Mmap\7f80485
-Node: Documentation\7f81195
-Node: GNU Manuals\7f82300
-Node: Doc Strings and Manuals\7f87357
-Node: Manual Structure Details\7f88910
-Node: License for Manuals\7f90328
-Node: Manual Credits\7f91302
-Node: Printed Manuals\7f91695
-Node: NEWS File\7f92381
-Node: Change Logs\7f93059
-Node: Change Log Concepts\7f93813
-Node: Style of Change Logs\7f95677
-Node: Simple Changes\7f97712
-Node: Conditional Changes\7f98956
-Node: Indicating the Part Changed\7f100378
-Node: Man Pages\7f100905
-Node: Reading other Manuals\7f102529
-Node: Managing Releases\7f103320
-Node: Configuration\7f104083
-Node: Makefile Conventions\7f110988
-Node: Makefile Basics\7f111794
-Node: Utilities in Makefiles\7f114968
-Node: Command Variables\7f117113
-Node: Directory Variables\7f120690
-Node: Standard Targets\7f131584
-Ref: Standard Targets-Footnote-1\7f142824
-Node: Install Command Categories\7f142924
-Node: Releases\7f147506
-Node: References\7f151594
-Node: Copying This Manual\7f153879
-Node: GNU Free Documentation License\7f154115
-Node: Index\7f173816
-\1f
-End Tag Table
+++ /dev/null
-This is as.info, produced by makeinfo version 4.8 from as.texinfo.
-
-START-INFO-DIR-ENTRY
-* As: (as). The GNU assembler.
-* Gas: (as). The GNU assembler.
-END-INFO-DIR-ENTRY
-
- This file documents the GNU Assembler "as".
-
- Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002,
-2006, 2007 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-\1f
-File: as.info, Node: Top, Next: Overview, Up: (dir)
-
-Using as
-********
-
-This file is a user guide to the GNU assembler `as' (GNU Binutils)
-version 2.17.90.
-
- 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".
-
-* Menu:
-
-* Overview:: Overview
-* Invoking:: Command-Line Options
-* Syntax:: Syntax
-* Sections:: Sections and Relocation
-* Symbols:: Symbols
-* Expressions:: Expressions
-* Pseudo Ops:: Assembler Directives
-* Machine Dependencies:: Machine Dependent Features
-* Reporting Bugs:: Reporting Bugs
-* Acknowledgements:: Who Did What
-* GNU Free Documentation License:: GNU Free Documentation License
-* AS Index:: AS Index
-
-\1f
-File: as.info, Node: Overview, Next: Invoking, Prev: Top, Up: Top
-
-1 Overview
-**********
-
-Here is a brief summary of how to invoke `as'. For details, see *Note
-Command-Line Options: Invoking.
-
- as [-a[cdhlns][=FILE]] [-alternate] [-D]
- [-debug-prefix-map OLD=NEW]
- [-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 Alpha options:_
- [-mCPU]
- [-mdebug | -no-mdebug]
- [-relax] [-g] [-GSIZE]
- [-F] [-32addr]
-
- _Target ARC options:_
- [-marc[5|6|7|8]]
- [-EB|-EL]
-
- _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 CRIS options:_
- [-underscore | -no-underscore]
- [-pic] [-N]
- [-emulation=criself | -emulation=crisaout]
- [-march=v0_v10 | -march=v10 | -march=v32 | -march=common_v10_v32]
-
- _Target D10V options:_
- [-O]
-
- _Target D30V options:_
- [-O|-n|-N]
-
- _Target i386 options:_
- [-32|-64] [-n]
- [-march=CPU] [-mtune=CPU]
-
- _Target i960 options:_
- [-ACA|-ACA_A|-ACB|-ACC|-AKA|-AKB|
- -AKC|-AMC]
- [-b] [-no-relax]
-
- _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 IP2K options:_
- [-mip2022|-mip2022ext]
-
- _Target M32C options:_
- [-m32c|-m16c]
-
- _Target M32R options:_
- [-m32rx|-[no-]warn-explicit-parallel-conflicts|
- -W[n]p]
-
- _Target M680X0 options:_
- [-l] [-m68000|-m68010|-m68020|...]
-
- _Target M68HC11 options:_
- [-m68hc11|-m68hc12|-m68hcs12]
- [-mshort|-mlong]
- [-mshort-double|-mlong-double]
- [-force-long-branches] [-short-branches]
- [-strict-direct-mode] [-print-insn-syntax]
- [-print-opcodes] [-generate-example]
-
- _Target MCORE options:_
- [-jsri2bsr] [-sifilter] [-relax]
- [-mcpu=[210|340]]
-
- _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 MMIX options:_
- [-fixed-special-register-names] [-globalize-symbols]
- [-gnu-syntax] [-relax] [-no-predefined-symbols]
- [-no-expand] [-no-merge-gregs] [-x]
- [-linker-allocated-gregs]
-
- _Target PDP11 options:_
- [-mpic|-mno-pic] [-mall] [-mno-extensions]
- [-mEXTENSION|-mno-EXTENSION]
- [-mCPU] [-mMACHINE]
-
- _Target picoJava options:_
- [-mb|-me]
-
- _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]
-
- _Target TIC54X options:_
- [-mcpu=54[123589]|-mcpu=54[56]lp] [-mfar-mode|-mf]
- [-merrors-to-file <FILENAME>|-me <FILENAME>]
-
-
- _Target Z80 options:_
- [-z80] [-r800]
- [ -ignore-undocumented-instructions] [-Wnud]
- [ -ignore-unportable-instructions] [-Wnup]
- [ -warn-undocumented-instructions] [-Wud]
- [ -warn-unportable-instructions] [-Wup]
- [ -forbid-undocumented-instructions] [-Fud]
- [ -forbid-unportable-instructions] [-Fup]
-
-
- _Target Xtensa options:_
- [-[no-]text-section-literals] [-[no-]absolute-literals]
- [-[no-]target-align] [-[no-]longcalls]
- [-[no-]transform]
- [-rename-section OLDNAME=NEWNAME]
-
-`@FILE'
- Read command-line options from FILE. The options read are
- inserted in place of the original @FILE option. If FILE does not
- exist, or cannot be read, then the option will be treated
- literally, and not removed.
-
- Options in 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 FILE may itself contain
- additional @FILE options; any such options will be processed
- recursively.
-
-`-a[cdhlmns]'
- Turn on listings, in any of a variety of ways:
-
- `-ac'
- omit false conditionals
-
- `-ad'
- omit debugging directives
-
- `-ah'
- include high-level source
-
- `-al'
- include assembly
-
- `-am'
- include macro expansions
-
- `-an'
- omit forms processing
-
- `-as'
- include symbols
-
- `=file'
- set the name of the listing file
-
- You may combine these options; for example, use `-aln' for assembly
- listing without forms processing. The `=file' option, if used,
- must be the last one. By itself, `-a' defaults to `-ahls'.
-
-`--alternate'
- Begin in alternate macro mode. *Note `.altmacro': Altmacro.
-
-`-D'
- Ignored. This option is accepted for script compatibility with
- calls to other assemblers.
-
-`--debug-prefix-map OLD=NEW'
- When assembling files in directory `OLD', record debugging
- information describing them as in `NEW' instead.
-
-`--defsym SYM=VALUE'
- Define the symbol SYM to be VALUE before assembling the input file.
- VALUE must be an integer constant. As in C, a leading `0x'
- indicates a hexadecimal value, and a leading `0' indicates an octal
- value. The value of the symbol can be overridden inside a source
- file via the use of a `.set' pseudo-op.
-
-`-f'
- "fast"--skip whitespace and comment preprocessing (assume source is
- compiler output).
-
-`-g'
-`--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.
-
-`--gstabs'
- Generate stabs debugging information for each assembler line. This
- may help debugging assembler code, if the debugger can handle 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.
-
-`--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.
-
-`--help'
- Print a summary of the command line options and exit.
-
-`--target-help'
- Print a summary of all target specific options and exit.
-
-`-I DIR'
- Add directory DIR to the search list for `.include' directives.
-
-`-J'
- Don't warn about signed overflow.
-
-`-K'
- Issue warnings when difference tables altered for long
- displacements.
-
-`-L'
-`--keep-locals'
- Keep (in the symbol table) local symbols. These symbols start with
- system-specific local label prefixes, typically `.L' for ELF
- systems or `L' for traditional a.out systems. *Note Symbol
- Names::.
-
-`--listing-lhs-width=NUMBER'
- Set the maximum width, in words, of the output data column for an
- assembler listing to NUMBER.
-
-`--listing-lhs-width2=NUMBER'
- Set the maximum width, in words, of the output data column for
- continuation lines in an assembler listing to NUMBER.
-
-`--listing-rhs-width=NUMBER'
- Set the maximum width of an input source line, as displayed in a
- listing, to NUMBER bytes.
-
-`--listing-cont-lines=NUMBER'
- Set the maximum number of lines printed in a listing for a single
- line of input to NUMBER + 1.
-
-`-o OBJFILE'
- Name the object-file output from `as' OBJFILE.
-
-`-R'
- Fold the data section into the text section.
-
- Set the default size of GAS's hash tables to a prime number close
- to 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.
-
-`--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 `--hash-size=4051', but in the future it may have
- other effects as well.
-
-`--statistics'
- Print the maximum space (in bytes) and total time (in seconds)
- used by assembly.
-
-`--strip-local-absolute'
- Remove local absolute symbols from the outgoing symbol table.
-
-`-v'
-`-version'
- Print the `as' version.
-
-`--version'
- Print the `as' version and exit.
-
-`-W'
-`--no-warn'
- Suppress warning messages.
-
-`--fatal-warnings'
- Treat warnings as errors.
-
-`--warn'
- Don't suppress warning messages or treat them as errors.
-
-`-w'
- Ignored.
-
-`-x'
- Ignored.
-
-`-Z'
- Generate an object file even after errors.
-
-`-- | FILES ...'
- Standard input, or source files to assemble.
-
-
- The following options are available when as is configured for an ARC
-processor.
-
-`-marc[5|6|7|8]'
- This option selects the core processor variant.
-
-`-EB | -EL'
- Select either big-endian (-EB) or little-endian (-EL) output.
-
- The following options are available when as is configured for the ARM
-processor family.
-
-`-mcpu=PROCESSOR[+EXTENSION...]'
- Specify which ARM processor variant is the target.
-
-`-march=ARCHITECTURE[+EXTENSION...]'
- Specify which ARM architecture variant is used by the target.
-
-`-mfpu=FLOATING-POINT-FORMAT'
- Select which Floating Point architecture is the target.
-
-`-mfloat-abi=ABI'
- Select which floating point ABI is in use.
-
-`-mthumb'
- Enable Thumb only instruction decoding.
-
-`-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant'
- Select which procedure calling convention is in use.
-
-`-EB | -EL'
- Select either big-endian (-EB) or little-endian (-EL) output.
-
-`-mthumb-interwork'
- Specify that the code has been generated with interworking between
- Thumb and ARM code in mind.
-
-`-k'
- Specify that PIC code has been generated.
-
- See the info pages for documentation of the CRIS-specific options.
-
- The following options are available when as is configured for a D10V
-processor.
-`-O'
- Optimize output by parallelizing instructions.
-
- The following options are available when as is configured for a D30V
-processor.
-`-O'
- Optimize output by parallelizing instructions.
-
-`-n'
- Warn when nops are generated.
-
-`-N'
- Warn when a nop after a 32-bit multiply instruction is generated.
-
- The following options are available when as is configured for the
-Intel 80960 processor.
-
-`-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC'
- Specify which variant of the 960 architecture is the target.
-
-`-b'
- Add code to collect statistics about branches taken.
-
-`-no-relax'
- Do not alter compare-and-branch instructions for long
- displacements; error if necessary.
-
-
- The following options are available when as is configured for the
-Ubicom IP2K series.
-
-`-mip2022ext'
- Specifies that the extended IP2022 instructions are allowed.
-
-`-mip2022'
- Restores the default behaviour, which restricts the permitted
- instructions to just the basic IP2022 ones.
-
-
- The following options are available when as is configured for the
-Renesas M32C and M16C processors.
-
-`-m32c'
- Assemble M32C instructions.
-
-`-m16c'
- Assemble M16C instructions (the default).
-
-
- The following options are available when as is configured for the
-Renesas M32R (formerly Mitsubishi M32R) series.
-
-`--m32rx'
- Specify which processor in the M32R family is the target. The
- default is normally the M32R, but this option changes it to the
- M32RX.
-
-`--warn-explicit-parallel-conflicts or --Wp'
- Produce warning messages when questionable parallel constructs are
- encountered.
-
-`--no-warn-explicit-parallel-conflicts or --Wnp'
- Do not produce warning messages when questionable parallel
- constructs are encountered.
-
-
- The following options are available when as is configured for the
-Motorola 68000 series.
-
-`-l'
- Shorten references to undefined symbols, to one word instead of
- two.
-
-`-m68000 | -m68008 | -m68010 | -m68020 | -m68030'
-`| -m68040 | -m68060 | -m68302 | -m68331 | -m68332'
-`| -m68333 | -m68340 | -mcpu32 | -m5200'
- Specify what processor in the 68000 family is the target. The
- default is normally the 68020, but this can be changed at
- configuration time.
-
-`-m68881 | -m68882 | -mno-68881 | -mno-68882'
- The target machine does (or does not) have a floating-point
- coprocessor. The default is to assume a coprocessor for 68020,
- 68030, and cpu32. Although the basic 68000 is not compatible with
- the 68881, a combination of the two can be specified, since it's
- possible to do emulation of the coprocessor instructions with the
- main processor.
-
-`-m68851 | -mno-68851'
- The target machine does (or does not) have a memory-management
- unit coprocessor. The default is to assume an MMU for 68020 and
- up.
-
-
- For details about the PDP-11 machine dependent features options, see
-*Note PDP-11-Options::.
-
-`-mpic | -mno-pic'
- Generate position-independent (or position-dependent) code. The
- default is `-mpic'.
-
-`-mall'
-`-mall-extensions'
- Enable all instruction set extensions. This is the default.
-
-`-mno-extensions'
- Disable all instruction set extensions.
-
-`-mEXTENSION | -mno-EXTENSION'
- Enable (or disable) a particular instruction set extension.
-
-`-mCPU'
- Enable the instruction set extensions supported by a particular
- CPU, and disable all other extensions.
-
-`-mMACHINE'
- Enable the instruction set extensions supported by a particular
- machine model, and disable all other extensions.
-
- The following options are available when as is configured for a
-picoJava processor.
-
-`-mb'
- Generate "big endian" format output.
-
-`-ml'
- Generate "little endian" format output.
-
-
- The following options are available when as is configured for the
-Motorola 68HC11 or 68HC12 series.
-
-`-m68hc11 | -m68hc12 | -m68hcs12'
- Specify what processor is the target. The default is defined by
- the configuration option when building the assembler.
-
-`-mshort'
- Specify to use the 16-bit integer ABI.
-
-`-mlong'
- Specify to use the 32-bit integer ABI.
-
-`-mshort-double'
- Specify to use the 32-bit double ABI.
-
-`-mlong-double'
- Specify to use the 64-bit double ABI.
-
-`--force-long-branches'
- Relative branches are turned into absolute ones. This concerns
- conditional branches, unconditional branches and branches to a sub
- routine.
-
-`-S | --short-branches'
- Do not turn relative branches into absolute ones when the offset
- is out of range.
-
-`--strict-direct-mode'
- Do not turn the direct addressing mode into extended addressing
- mode when the instruction does not support direct addressing mode.
-
-`--print-insn-syntax'
- Print the syntax of instruction in case of error.
-
-`--print-opcodes'
- print the list of instructions with syntax and then exit.
-
-`--generate-example'
- print an example of instruction for each possible instruction and
- then exit. This option is only useful for testing `as'.
-
-
- The following options are available when `as' is configured for the
-SPARC architecture:
-
-`-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite'
-`-Av8plus | -Av8plusa | -Av9 | -Av9a'
- Explicitly select a variant of the SPARC architecture.
-
- `-Av8plus' and `-Av8plusa' select a 32 bit environment. `-Av9'
- and `-Av9a' select a 64 bit environment.
-
- `-Av8plusa' and `-Av9a' enable the SPARC V9 instruction set with
- UltraSPARC extensions.
-
-`-xarch=v8plus | -xarch=v8plusa'
- For compatibility with the Solaris v9 assembler. These options are
- equivalent to -Av8plus and -Av8plusa, respectively.
-
-`-bump'
- Warn when the assembler switches to another architecture.
-
- The following options are available when as is configured for the
-'c54x architecture.
-
-`-mfar-mode'
- Enable extended addressing mode. All addresses and relocations
- will assume extended addressing (usually 23 bits).
-
-`-mcpu=CPU_VERSION'
- Sets the CPU version being compiled for.
-
-`-merrors-to-file FILENAME'
- Redirect error output to a file, for broken systems which don't
- support such behaviour in the shell.
-
- The following options are available when as is configured for a MIPS
-processor.
-
-`-G NUM'
- This option sets the largest size of an object that can be
- referenced implicitly with the `gp' register. It is only accepted
- for targets that use ECOFF format, such as a DECstation running
- Ultrix. The default value is 8.
-
-`-EB'
- Generate "big endian" format output.
-
-`-EL'
- Generate "little endian" format output.
-
-`-mips1'
-`-mips2'
-`-mips3'
-`-mips4'
-`-mips5'
-`-mips32'
-`-mips32r2'
-`-mips64'
-`-mips64r2'
- Generate code for a particular MIPS Instruction Set Architecture
- level. `-mips1' is an alias for `-march=r3000', `-mips2' is an
- alias for `-march=r6000', `-mips3' is an alias for `-march=r4000'
- and `-mips4' is an alias for `-march=r8000'. `-mips5', `-mips32',
- `-mips32r2', `-mips64', and `-mips64r2' correspond to generic
- `MIPS V', `MIPS32', `MIPS32 Release 2', `MIPS64', and `MIPS64
- Release 2' ISA processors, respectively.
-
-`-march=CPU'
- Generate code for a particular MIPS cpu.
-
-`-mtune=CPU'
- Schedule and tune for a particular MIPS cpu.
-
-`-mfix7000'
-`-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.
-
-`-mdebug'
-`-no-mdebug'
- Cause stabs-style debugging output to go into an ECOFF-style
- .mdebug section instead of the standard ELF .stabs sections.
-
-`-mpdr'
-`-mno-pdr'
- Control generation of `.pdr' sections.
-
-`-mgp32'
-`-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. `-mgp32' controls the size of
- general-purpose registers and `-mfp32' controls the size of
- floating-point registers.
-
-`-mips16'
-`-no-mips16'
- Generate code for the MIPS 16 processor. This is equivalent to
- putting `.set mips16' at the start of the assembly file.
- `-no-mips16' turns off this option.
-
-`-msmartmips'
-`-mno-smartmips'
- Enables the SmartMIPS extension to the MIPS32 instruction set.
- This is equivalent to putting `.set smartmips' at the start of the
- assembly file. `-mno-smartmips' turns off this option.
-
-`-mips3d'
-`-no-mips3d'
- Generate code for the MIPS-3D Application Specific Extension.
- This tells the assembler to accept MIPS-3D instructions.
- `-no-mips3d' turns off this option.
-
-`-mdmx'
-`-no-mdmx'
- Generate code for the MDMX Application Specific Extension. This
- tells the assembler to accept MDMX instructions. `-no-mdmx' turns
- off this option.
-
-`-mdsp'
-`-mno-dsp'
- Generate code for the DSP Release 1 Application Specific Extension.
- This tells the assembler to accept DSP Release 1 instructions.
- `-mno-dsp' turns off this option.
-
-`-mdspr2'
-`-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. `-mno-dspr2' turns off this option.
-
-`-mmt'
-`-mno-mt'
- Generate code for the MT Application Specific Extension. This
- tells the assembler to accept MT instructions. `-mno-mt' turns
- off this option.
-
-`--construct-floats'
-`--no-construct-floats'
- The `--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
- `--construct-floats' is selected, allowing construction of these
- floating point constants.
-
-`--emulation=NAME'
- This option causes `as' to emulate `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:
- `mipsecoff', `mipself', `mipslecoff', `mipsbecoff', `mipslelf',
- `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 `b' or `l' in the name. Using `-EB' or `-EL'
- will override the endianness selection in any case.
-
- This option is currently supported only when the primary target
- `as' is configured for is a MIPS ELF or ECOFF target.
- Furthermore, the primary target or others specified with
- `--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.
-
- Eventually, this option will support more configurations, with more
- fine-grained control over the assembler's behavior, and will be
- supported for more processors.
-
-`-nocpp'
- `as' ignores this option. It is accepted for compatibility with
- the native tools.
-
-`--trap'
-`--no-trap'
-`--break'
-`--no-break'
- Control how to deal with multiplication overflow and division by
- zero. `--trap' or `--no-break' (which are synonyms) take a trap
- exception (and only work for Instruction Set Architecture level 2
- and higher); `--break' or `--no-trap' (also synonyms, and the
- default) take a break exception.
-
-`-n'
- When this option is used, `as' will issue a warning every time it
- generates a nop instruction from a macro.
-
- The following options are available when as is configured for an
-MCore processor.
-
-`-jsri2bsr'
-`-nojsri2bsr'
- Enable or disable the JSRI to BSR transformation. By default this
- is enabled. The command line option `-nojsri2bsr' can be used to
- disable it.
-
-`-sifilter'
-`-nosifilter'
- Enable or disable the silicon filter behaviour. By default this
- is disabled. The default can be overridden by the `-sifilter'
- command line option.
-
-`-relax'
- Alter jump instructions for long displacements.
-
-`-mcpu=[210|340]'
- Select the cpu type on the target hardware. This controls which
- instructions can be assembled.
-
-`-EB'
- Assemble for a big endian target.
-
-`-EL'
- Assemble for a little endian target.
-
-
- See the info pages for documentation of the MMIX-specific options.
-
- The following options are available when as is configured for an
-Xtensa processor.
-
-`--text-section-literals | --no-text-section-literals'
- With `--text-section-literals', literal pools are interspersed in
- the text section. The default is `--no-text-section-literals',
- which places literals in a separate section in the output file.
- These options only affect literals referenced via PC-relative
- `L32R' instructions; literals for absolute mode `L32R'
- instructions are handled separately.
-
-`--absolute-literals | --no-absolute-literals'
- Indicate to the assembler whether `L32R' instructions use absolute
- or PC-relative addressing. The default is to assume absolute
- addressing if the Xtensa processor includes the absolute `L32R'
- addressing option. Otherwise, only the PC-relative `L32R' mode
- can be used.
-
-`--target-align | --no-target-align'
- Enable or disable automatic alignment to reduce branch penalties
- at the expense of some code density. The default is
- `--target-align'.
-
-`--longcalls | --no-longcalls'
- Enable or disable transformation of call instructions to allow
- calls across a greater range of addresses. The default is
- `--no-longcalls'.
-
-`--transform | --no-transform'
- Enable or disable all assembler transformations of Xtensa
- instructions. The default is `--transform'; `--no-transform'
- should be used only in the rare cases when the instructions must
- be exactly as specified in the assembly source.
-
- The following options are available when as is configured for a Z80
-family processor.
-`-z80'
- Assemble for Z80 processor.
-
-`-r800'
- Assemble for R800 processor.
-
-`-ignore-undocumented-instructions'
-`-Wnud'
- Assemble undocumented Z80 instructions that also work on R800
- without warning.
-
-`-ignore-unportable-instructions'
-`-Wnup'
- Assemble all undocumented Z80 instructions without warning.
-
-`-warn-undocumented-instructions'
-`-Wud'
- Issue a warning for undocumented Z80 instructions that also work
- on R800.
-
-`-warn-unportable-instructions'
-`-Wup'
- Issue a warning for undocumented Z80 instructions that do not work
- on R800.
-
-`-forbid-undocumented-instructions'
-`-Fud'
- Treat all undocumented instructions as errors.
-
-`-forbid-unportable-instructions'
-`-Fup'
- Treat undocumented Z80 instructions that do not work on R800 as
- errors.
-
-* Menu:
-
-* Manual:: Structure of this Manual
-* GNU Assembler:: The GNU Assembler
-* Object Formats:: Object File Formats
-* Command Line:: Command Line
-* Input Files:: Input Files
-* Object:: Output (Object) File
-* Errors:: Error and Warning Messages
-
-\1f
-File: as.info, Node: Manual, Next: GNU Assembler, Up: Overview
-
-1.1 Structure of this Manual
-============================
-
-This manual is intended to describe what you need to know to use GNU
-`as'. We cover the syntax expected in source files, including notation
-for symbols, constants, and expressions; the directives that `as'
-understands; and of course how to invoke `as'.
-
- This manual also describes some of the machine-dependent features of
-various flavors of the assembler.
-
- On the other hand, this manual is _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 _not_ describe the instruction set, standard
-mnemonics, registers or addressing modes that are standard to a
-particular architecture. You may want to consult the manufacturer's
-machine architecture manual for this information.
-
-\1f
-File: as.info, Node: GNU Assembler, Next: Object Formats, Prev: Manual, Up: Overview
-
-1.2 The GNU Assembler
-=====================
-
-GNU `as' is really a family of assemblers. 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 "pseudo-ops") and assembler syntax.
-
- `as' is primarily intended to assemble the output of the GNU C
-compiler `gcc' for use by the linker `ld'. Nevertheless, we've tried
-to make `as' assemble correctly everything that other assemblers for
-the same machine would assemble. Any exceptions are documented
-explicitly (*note Machine Dependencies::). This doesn't mean `as'
-always uses the same syntax as another assembler for the same
-architecture; for example, we know of several incompatible versions of
-680x0 assembly language syntax.
-
- Unlike older assemblers, `as' is designed to assemble a source
-program in one pass of the source file. This has a subtle impact on the
-`.org' directive (*note `.org': Org.).
-
-\1f
-File: as.info, Node: Object Formats, Next: Command Line, Prev: GNU Assembler, Up: Overview
-
-1.3 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. *Note Symbol
-Attributes: Symbol Attributes.
-
-\1f
-File: as.info, Node: Command Line, Next: Input Files, Prev: Object Formats, Up: Overview
-
-1.4 Command Line
-================
-
-After the program name `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.
-
- `--' (two hyphens) by itself names the standard input file
-explicitly, as one of the files for `as' to assemble.
-
- Except for `--' any command line argument that begins with a hyphen
-(`-') is an option. Each option changes the behavior of `as'. No
-option changes the way another option works. An option is a `-'
-followed by one or more letters; the case of the letter is important.
-All options are optional.
-
- 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:
-
- as -o my-object-file.o mumble.s
- as -omy-object-file.o mumble.s
-
-\1f
-File: as.info, Node: Input Files, Next: Object, Prev: Command Line, Up: Overview
-
-1.5 Input Files
-===============
-
-We use the phrase "source program", abbreviated "source", to describe
-the program input to one run of `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.
-
- The source program is a concatenation of the text in all the files,
-in the order specified.
-
- Each time you run `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.)
-
- You give `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.
-
- If you give `as' no file names it attempts to read one input file
-from the `as' standard input, which is normally your terminal. You may
-have to type <ctl-D> to tell `as' there is no more program to assemble.
-
- Use `--' if you need to explicitly name the standard input file in
-your command line.
-
- If the source is empty, `as' produces a small, empty object file.
-
-Filenames and Line-numbers
---------------------------
-
-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
-"logical" file. *Note Error and Warning Messages: Errors.
-
- "Physical files" are those files named in the command line given to
-`as'.
-
- "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 `as'
-source is itself synthesized from other files. `as' understands the
-`#' directives emitted by the `gcc' preprocessor. See also *Note
-`.file': File.
-
-\1f
-File: as.info, Node: Object, Next: Errors, Prev: Input Files, Up: Overview
-
-1.6 Output (Object) File
-========================
-
-Every time you run `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 `a.out'. You can give it another
-name by using the `-o' option. Conventionally, object file names end
-with `.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 `a.out' format.)
-
- The object file is meant for input to the linker `ld'. It contains
-assembled program code, information to help `ld' integrate the
-assembled program into a runnable file, and (optionally) symbolic
-information for the debugger.
-
-\1f
-File: as.info, Node: Errors, Prev: Object, Up: Overview
-
-1.7 Error and Warning Messages
-==============================
-
-`as' may write warnings and error messages to the standard error file
-(usually your terminal). This should not happen when a compiler runs
-`as' automatically. Warnings report an assumption made so that `as'
-could keep assembling a flawed program; errors report a grave problem
-that stops the assembly.
-
- Warning messages have the format
-
- file_name:NNN:Warning Message Text
-
-(where NNN is a line number). If a logical file name has been given
-(*note `.file': File.) it is used for the filename, otherwise the name
-of the current input file is used. If a logical line number was given
-(*note `.line': Line.) 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).
-
- Error messages have the format
- file_name:NNN:FATAL:Error Message Text
- 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.
-
-\1f
-File: as.info, Node: Invoking, Next: Syntax, Prev: Overview, Up: Top
-
-2 Command-Line Options
-**********************
-
-This chapter describes command-line options available in _all_ versions
-of the GNU assembler; see *Note Machine Dependencies::, for options
-specific to particular machine architectures.
-
- If you are invoking `as' via the GNU C compiler, you can use the
-`-Wa' option to pass arguments through to the assembler. The assembler
-arguments must be separated from each other (and the `-Wa') by commas.
-For example:
-
- gcc -c -g -O -Wa,-alh,-L file.c
-
-This passes two options to the assembler: `-alh' (emit a listing to
-standard output with high-level and assembly source) and `-L' (retain
-local symbols in the symbol table).
-
- Usually you do not need to use this `-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 `-v'
-option to see precisely what options it passes to each compilation
-pass, including the assembler.)
-
-* Menu:
-
-* a:: -a[cdhlns] enable listings
-* alternate:: --alternate enable alternate macro syntax
-* D:: -D for compatibility
-* f:: -f to work faster
-* I:: -I for .include search path
-
-* K:: -K for difference tables
-
-* L:: -L to retain local symbols
-* listing:: --listing-XXX to configure listing output
-* M:: -M or --mri to assemble in MRI compatibility mode
-* MD:: --MD for dependency tracking
-* o:: -o to name the object file
-* R:: -R to join data and text sections
-* statistics:: --statistics to see statistics about assembly
-* traditional-format:: --traditional-format for compatible output
-* v:: -v to announce version
-* W:: -W, --no-warn, --warn, --fatal-warnings to control warnings
-* Z:: -Z to make object file even after errors
-
-\1f
-File: as.info, Node: a, Next: alternate, Up: Invoking
-
-2.1 Enable Listings: `-a[cdhlns]'
-=================================
-
-These options enable listing output from the assembler. By itself,
-`-a' requests high-level, assembly, and symbols listing. You can use
-other letters to select specific options for the list: `-ah' requests a
-high-level language listing, `-al' requests an output-program assembly
-listing, and `-as' requests a symbol table listing. High-level
-listings require that a compiler debugging option like `-g' be used,
-and that assembly listings (`-al') be requested also.
-
- Use the `-ac' option to omit false conditionals from a listing. Any
-lines which are not assembled because of a false `.if' (or `.ifdef', or
-any other conditional), or a true `.if' followed by an `.else', will be
-omitted from the listing.
-
- Use the `-ad' option to omit debugging directives from the listing.
-
- Once you have specified one of these options, you can further control
-listing output and its appearance using the directives `.list',
-`.nolist', `.psize', `.eject', `.title', and `.sbttl'. The `-an'
-option turns off all forms processing. If you do not request listing
-output with one of the `-a' options, the listing-control directives
-have no effect.
-
- The letters after `-a' may be combined into one option, _e.g._,
-`-aln'.
-
- Note if the assembler source is coming from the standard input (e.g.,
-because it is being created by `gcc' and the `-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.
-
-\1f
-File: as.info, Node: alternate, Next: D, Prev: a, Up: Invoking
-
-2.2 `--alternate'
-=================
-
-Begin in alternate macro mode, see *Note `.altmacro': Altmacro.
-
-\1f
-File: as.info, Node: D, Next: f, Prev: alternate, Up: Invoking
-
-2.3 `-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 `as'.
-
-\1f
-File: as.info, Node: f, Next: I, Prev: D, Up: Invoking
-
-2.4 Work Faster: `-f'
-=====================
-
-`-f' should only be used when assembling programs written by a
-(trusted) compiler. `-f' stops the assembler from doing whitespace and
-comment preprocessing on the input file(s) before assembling them.
-*Note Preprocessing: Preprocessing.
-
- _Warning:_ if you use `-f' when the files actually need to be
- preprocessed (if they contain comments, for example), `as' does
- not work correctly.
-
-\1f
-File: as.info, Node: I, Next: K, Prev: f, Up: Invoking
-
-2.5 `.include' Search Path: `-I' PATH
-=====================================
-
-Use this option to add a PATH to the list of directories `as' searches
-for files specified in `.include' directives (*note `.include':
-Include.). You may use `-I' as many times as necessary to include a
-variety of paths. The current working directory is always searched
-first; after that, `as' searches any `-I' directories in the same order
-as they were specified (left to right) on the command line.
-
-\1f
-File: as.info, Node: K, Next: L, Prev: I, Up: Invoking
-
-2.6 Difference Tables: `-K'
-===========================
-
-`as' sometimes alters the code emitted for directives of the form
-`.word SYM1-SYM2'. *Note `.word': Word. You can use the `-K' option
-if you want a warning issued when this is done.
-
-\1f
-File: as.info, Node: L, Next: listing, Prev: K, Up: Invoking
-
-2.7 Include Local Symbols: `-L'
-===============================
-
-Symbols beginning with system-specific local label prefixes, typically
-`.L' for ELF systems or `L' for traditional a.out systems, are called
-"local symbols". *Note 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 `as' and `ld' discard such symbols, so you do
-not normally debug with them.
-
- This option tells `as' to retain those local symbols in the object
-file. Usually if you do this you also tell the linker `ld' to preserve
-those symbols.
-
-\1f
-File: as.info, Node: listing, Next: M, Prev: L, Up: Invoking
-
-2.8 Configuring listing output: `--listing'
-===========================================
-
-The listing feature of the assembler can be enabled via the command
-line switch `-a' (*note 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., `.list' (*note List::), `.title' (*note Title::), `.sbttl'
-(*note Sbttl::), `.psize' (*note Psize::), and `.eject' (*note Eject::)
-and also by the following switches:
-
-`--listing-lhs-width=`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.
-
-`--listing-lhs-width2=`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 `--listing-lhs-width'. If neither switch is used the default
- is to one.
-
-`--listing-rhs-width=`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.
-
-`--listing-cont-lines=`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.
-
-\1f
-File: as.info, Node: M, Next: MD, Prev: listing, Up: Invoking
-
-2.9 Assemble in MRI Compatibility Mode: `-M'
-============================================
-
-The `-M' or `--mri' option selects MRI compatibility mode. This
-changes the syntax and pseudo-op handling of `as' to make it compatible
-with the `ASM68K' or the `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 `as'.
-
- 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:
-
- * global symbols in common section
-
- The m68k MRI assembler supports common sections which are merged
- by the linker. Other object file formats do not support this.
- `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.
-
- * complex relocations
-
- 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.
-
- * `END' pseudo-op specifying start address
-
- The MRI `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 `-e' option to
- the linker, or in a linker script.
-
- * `IDNT', `.ident' and `NAME' pseudo-ops
-
- The MRI `IDNT', `.ident' and `NAME' pseudo-ops assign a module
- name to the output file. This is not supported by other object
- file formats.
-
- * `ORG' pseudo-op
-
- The m68k MRI `ORG' pseudo-op begins an absolute section at a given
- address. This differs from the usual `as' `.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.
-
- There are some other features of the MRI assembler which are not
-supported by `as', typically either because they are difficult or
-because they seem of little consequence. Some of these may be
-supported in future releases.
-
- * EBCDIC strings
-
- EBCDIC strings are not supported.
-
- * packed binary coded decimal
-
- Packed binary coded decimal is not supported. This means that the
- `DC.P' and `DCB.P' pseudo-ops are not supported.
-
- * `FEQU' pseudo-op
-
- The m68k `FEQU' pseudo-op is not supported.
-
- * `NOOBJ' pseudo-op
-
- The m68k `NOOBJ' pseudo-op is not supported.
-
- * `OPT' branch control options
-
- The m68k `OPT' branch control options--`B', `BRS', `BRB', `BRL',
- and `BRW'--are ignored. `as' automatically relaxes all branches,
- whether forward or backward, to an appropriate size, so these
- options serve no purpose.
-
- * `OPT' list control options
-
- The following m68k `OPT' list control options are ignored: `C',
- `CEX', `CL', `CRE', `E', `G', `I', `M', `MEX', `MC', `MD', `X'.
-
- * other `OPT' options
-
- The following m68k `OPT' options are ignored: `NEST', `O', `OLD',
- `OP', `P', `PCO', `PCR', `PCS', `R'.
-
- * `OPT' `D' option is default
-
- The m68k `OPT' `D' option is the default, unlike the MRI assembler.
- `OPT NOD' may be used to turn it off.
-
- * `XREF' pseudo-op.
-
- The m68k `XREF' pseudo-op is ignored.
-
- * `.debug' pseudo-op
-
- The i960 `.debug' pseudo-op is not supported.
-
- * `.extended' pseudo-op
-
- The i960 `.extended' pseudo-op is not supported.
-
- * `.list' pseudo-op.
-
- The various options of the i960 `.list' pseudo-op are not
- supported.
-
- * `.optimize' pseudo-op
-
- The i960 `.optimize' pseudo-op is not supported.
-
- * `.output' pseudo-op
-
- The i960 `.output' pseudo-op is not supported.
-
- * `.setreal' pseudo-op
-
- The i960 `.setreal' pseudo-op is not supported.
-
-
-\1f
-File: as.info, Node: MD, Next: o, Prev: M, Up: Invoking
-
-2.10 Dependency Tracking: `--MD'
-================================
-
-`as' can generate a dependency file for the file it creates. This file
-consists of a single rule suitable for `make' describing the
-dependencies of the main source file.
-
- The rule is written to the file named in its argument.
-
- This feature is used in the automatic updating of makefiles.
-
-\1f
-File: as.info, Node: o, Next: R, Prev: MD, Up: Invoking
-
-2.11 Name the Object File: `-o'
-===============================
-
-There is always one object file output when you run `as'. By default
-it has the name `a.out' (or `b.out', for Intel 960 targets only). You
-use this option (which takes exactly one filename) to give the object
-file a different name.
-
- Whatever the object file is called, `as' overwrites any existing
-file of the same name.
-
-\1f
-File: as.info, Node: R, Next: statistics, Prev: o, Up: Invoking
-
-2.12 Join Data and Text Sections: `-R'
-======================================
-
-`-R' tells `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. (*Note
-Sections and Relocation: Sections.)
-
- When you specify `-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 `as'. In future, `-R' may work this way.
-
- When `as' is configured for COFF or ELF output, this option is only
-useful if you use sections named `.text' and `.data'.
-
- `-R' is not supported for any of the HPPA targets. Using `-R'
-generates a warning from `as'.
-
-\1f
-File: as.info, Node: statistics, Next: traditional-format, Prev: R, Up: Invoking
-
-2.13 Display Assembly Statistics: `--statistics'
-================================================
-
-Use `--statistics' to display two statistics about the resources used by
-`as': the maximum amount of space allocated during the assembly (in
-bytes), and the total execution time taken for the assembly (in CPU
-seconds).
-
-\1f
-File: as.info, Node: traditional-format, Next: v, Prev: statistics, Up: Invoking
-
-2.14 Compatible Output: `--traditional-format'
-==============================================
-
-For some targets, the output of `as' is different in some ways from the
-output of some existing assembler. This switch requests `as' to use
-the traditional format instead.
-
- For example, it disables the exception frame optimizations which
-`as' normally does by default on `gcc' output.
-
-\1f
-File: as.info, Node: v, Next: W, Prev: traditional-format, Up: Invoking
-
-2.15 Announce Version: `-v'
-===========================
-
-You can find out what version of as is running by including the option
-`-v' (which you can also spell as `-version') on the command line.
-
-\1f
-File: as.info, Node: W, Next: Z, Prev: v, Up: Invoking
-
-2.16 Control Warnings: `-W', `--warn', `--no-warn', `--fatal-warnings'
-======================================================================
-
-`as' should never give a warning or error message when assembling
-compiler output. But programs written by people often cause `as' to
-give a warning that a particular assumption was made. All such
-warnings are directed to the standard error file.
-
- If you use the `-W' and `--no-warn' options, no warnings are issued.
-This only affects the warning messages: it does not change any
-particular of how `as' assembles your file. Errors, which stop the
-assembly, are still reported.
-
- If you use the `--fatal-warnings' option, `as' considers files that
-generate warnings to be in error.
-
- You can switch these options off again by specifying `--warn', which
-causes warnings to be output as usual.
-
-\1f
-File: as.info, Node: Z, Prev: W, Up: Invoking
-
-2.17 Generate Object File in Spite of Errors: `-Z'
-==================================================
-
-After an error message, `as' normally produces no output. If for some
-reason you are interested in object file output even after `as' gives
-an error message on your program, use the `-Z' option. If there are
-any errors, `as' continues anyways, and writes an object file after a
-final warning message of the form `N errors, M warnings, generating bad
-object file.'
-
-\1f
-File: as.info, Node: Syntax, Next: Sections, Prev: Invoking, Up: Top
-
-3 Syntax
-********
-
-This chapter describes the machine-independent syntax allowed in a
-source file. `as' syntax is similar to what many other assemblers use;
-it is inspired by the BSD 4.2 assembler, except that `as' does not
-assemble Vax bit-fields.
-
-* Menu:
-
-* Preprocessing:: Preprocessing
-* Whitespace:: Whitespace
-* Comments:: Comments
-* Symbol Intro:: Symbols
-* Statements:: Statements
-* Constants:: Constants
-
-\1f
-File: as.info, Node: Preprocessing, Next: Whitespace, Up: Syntax
-
-3.1 Preprocessing
-=================
-
-The `as' internal preprocessor:
- * 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.
-
- * removes all comments, replacing them with a single space, or an
- appropriate number of newlines.
-
- * converts character constants into the appropriate numeric values.
-
- 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 `.include' directive (*note
-`.include': Include.). You can use the GNU C compiler driver to get
-other "CPP" style preprocessing by giving the input file a `.S' suffix.
-*Note Options Controlling the Kind of Output: (gcc.info)Overall
-Options.
-
- Excess whitespace, comments, and character constants cannot be used
-in the portions of the input text that are not preprocessed.
-
- If the first line of an input file is `#NO_APP' or if you use the
-`-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 `#APP'
-before the text that may contain whitespace or comments, and putting a
-line that says `#NO_APP' after this text. This feature is mainly
-intend to support `asm' statements in compilers whose output is
-otherwise free of comments and whitespace.
-
-\1f
-File: as.info, Node: Whitespace, Next: Comments, Prev: Preprocessing, Up: Syntax
-
-3.2 Whitespace
-==============
-
-"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 (*note Character Constants:
-Characters.), any whitespace means the same as exactly one space.
-
-\1f
-File: as.info, Node: Comments, Next: Symbol Intro, Prev: Whitespace, Up: Syntax
-
-3.3 Comments
-============
-
-There are two ways of rendering comments to `as'. In both cases the
-comment is equivalent to one space.
-
- Anything from `/*' through the next `*/' is a comment. This means
-you may not nest these comments.
-
- /*
- The only way to include a newline ('\n') in a comment
- is to use this sort of comment.
- */
-
- /* This sort of comment does not nest. */
-
- Anything from the "line comment" character to the next newline is
-considered a comment and is ignored. The line comment character is `;'
-on the ARC; `@' on the ARM; `;' for the H8/300 family; `;' for the HPPA;
-`#' on the i386 and x86-64; `#' on the i960; `;' for the PDP-11; `;'
-for picoJava; `#' for Motorola PowerPC; `!' for the Renesas / SuperH SH;
-`!' on the SPARC; `#' on the ip2k; `#' on the m32c; `#' on the m32r;
-`|' on the 680x0; `#' on the 68HC11 and 68HC12; `#' on the Vax; `;' for
-the Z80; `!' for the Z8000; `#' on the V850; `#' for Xtensa systems;
-see *Note Machine Dependencies::.
-
- On some machines there are two different line comment characters.
-One character only begins a comment if it is the first non-whitespace
-character on a line, while the other always begins a comment.
-
- The V850 assembler also supports a double dash as starting a comment
-that extends to the end of the line.
-
- `--';
-
- To be compatible with past assemblers, lines that begin with `#'
-have a special interpretation. Following the `#' should be an absolute
-expression (*note Expressions::): the logical line number of the _next_
-line. Then a string (*note Strings: Strings.) is allowed: if present
-it is a new logical file name. The rest of the line, if any, should be
-whitespace.
-
- If the first non-whitespace characters on the line are not numeric,
-the line is ignored. (Just like a comment.)
-
- # This is an ordinary comment.
- # 42-6 "new_file_name" # New logical file name
- # This is logical line # 36.
- This feature is deprecated, and may disappear from future versions
-of `as'.
-
-\1f
-File: as.info, Node: Symbol Intro, Next: Statements, Prev: Comments, Up: Syntax
-
-3.4 Symbols
-===========
-
-A "symbol" is one or more characters chosen from the set of all letters
-(both upper and lower case), digits and the three characters `_.$'. On
-most machines, you can also use `$' in symbol names; exceptions are
-noted in *Note Machine Dependencies::. 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). *Note
-Symbols::.
-
-\1f
-File: as.info, Node: Statements, Next: Constants, Prev: Symbol Intro, Up: Syntax
-
-3.5 Statements
-==============
-
-A "statement" ends at a newline character (`\n') or line separator
-character. (The line separator is usually `;', unless this conflicts
-with the comment character; see *Note Machine Dependencies::.) The
-newline or separator character is considered part of the preceding
-statement. Newlines and separators within character constants are an
-exception: they do not end statements.
-
-It is an error to end any statement with end-of-file: the last
-character of any input file should be a newline.
-
- An empty statement is allowed, and may include whitespace. It is
-ignored.
-
- 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 `.' 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 "instruction": it
-assembles into a machine language instruction. Different versions of
-`as' for different computers recognize different instructions. In
-fact, the same symbol may represent a different instruction in a
-different computer's assembly language.
-
- A label is a symbol immediately followed by a colon (`:').
-Whitespace before a label or after a colon is permitted, but you may not
-have whitespace between a label's symbol and its colon. *Note Labels::.
-
- For HPPA targets, labels need not be immediately followed by a
-colon, but the definition of a label must begin in column zero. This
-also implies that only one label may be defined on each line.
-
- label: .directive followed by something
- another_label: # This is an empty statement.
- instruction operand_1, operand_2, ...
-
-\1f
-File: as.info, Node: Constants, Prev: Statements, Up: Syntax
-
-3.6 Constants
-=============
-
-A constant is a number, written so that its value is known by
-inspection, without knowing any context. Like this:
- .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
- .ascii "Ring the bell\7" # A string constant.
- .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
- .float 0f-314159265358979323846264338327\
- 95028841971.693993751E-40 # - pi, a flonum.
-
-* Menu:
-
-* Characters:: Character Constants
-* Numbers:: Number Constants
-
-\1f
-File: as.info, Node: Characters, Next: Numbers, Up: Constants
-
-3.6.1 Character Constants
--------------------------
-
-There are two kinds of character constants. A "character" stands for
-one character in one byte and its value may be used in numeric
-expressions. String constants (properly called string _literals_) are
-potentially many bytes and their values may not be used in arithmetic
-expressions.
-
-* Menu:
-
-* Strings:: Strings
-* Chars:: Characters
-
-\1f
-File: as.info, Node: Strings, Next: Chars, Up: Characters
-
-3.6.1.1 Strings
-...............
-
-A "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 "escape" these characters: precede them with a
-backslash `\' character. For example `\\' represents one backslash:
-the first `\' is an escape which tells `as' to interpret the second
-character literally as a backslash (which prevents `as' from
-recognizing the second `\' as an escape character). The complete list
-of escapes follows.
-
-`\b'
- Mnemonic for backspace; for ASCII this is octal code 010.
-
-`\f'
- Mnemonic for FormFeed; for ASCII this is octal code 014.
-
-`\n'
- Mnemonic for newline; for ASCII this is octal code 012.
-
-`\r'
- Mnemonic for carriage-Return; for ASCII this is octal code 015.
-
-`\t'
- Mnemonic for horizontal Tab; for ASCII this is octal code 011.
-
-`\ DIGIT DIGIT 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, `\008' has the value 010, and `\009' the
- value 011.
-
-`\`x' HEX-DIGITS...'
- A hex character code. All trailing hex digits are combined.
- Either upper or lower case `x' works.
-
-`\\'
- Represents one `\' character.
-
-`\"'
- Represents one `"' character. Needed in strings to represent this
- character, because an unescaped `"' would end the string.
-
-`\ ANYTHING-ELSE'
- Any other character when escaped by `\' gives a warning, but
- assembles as if the `\' 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 `as' has no
- other interpretation, so `as' knows it is giving you the wrong
- code and warns you of the fact.
-
- 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.
-
-\1f
-File: as.info, Node: Chars, Prev: Strings, Up: Characters
-
-3.6.1.2 Characters
-..................
-
-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 `'\\' where the first `\' escapes the second `\'. As you can
-see, the quote is an acute accent, not a grave accent. A newline
-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. `as' assumes your character code is ASCII: `'A' means
-65, `'B' means 66, and so on.
-
-\1f
-File: as.info, Node: Numbers, Prev: Characters, Up: Constants
-
-3.6.2 Number Constants
-----------------------
-
-`as' distinguishes three kinds of numbers according to how they are
-stored in the target machine. _Integers_ are numbers that would fit
-into an `int' in the C language. _Bignums_ are integers, but they are
-stored in more than 32 bits. _Flonums_ are floating point numbers,
-described below.
-
-* Menu:
-
-* Integers:: Integers
-* Bignums:: Bignums
-* Flonums:: Flonums
-
-\1f
-File: as.info, Node: Integers, Next: Bignums, Up: Numbers
-
-3.6.2.1 Integers
-................
-
-A binary integer is `0b' or `0B' followed by zero or more of the binary
-digits `01'.
-
- An octal integer is `0' followed by zero or more of the octal digits
-(`01234567').
-
- A decimal integer starts with a non-zero digit followed by zero or
-more digits (`0123456789').
-
- A hexadecimal integer is `0x' or `0X' followed by one or more
-hexadecimal digits chosen from `0123456789abcdefABCDEF'.
-
- Integers have the usual values. To denote a negative integer, use
-the prefix operator `-' discussed under expressions (*note Prefix
-Operators: Prefix Ops.).
-
-\1f
-File: as.info, Node: Bignums, Next: Flonums, Prev: Integers, Up: Numbers
-
-3.6.2.2 Bignums
-...............
-
-A "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.
-
-\1f
-File: as.info, Node: Flonums, Prev: Bignums, Up: Numbers
-
-3.6.2.3 Flonums
-...............
-
-A "flonum" represents a floating point number. The translation is
-indirect: a decimal floating point number from the text is converted by
-`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 `as' specialized to that computer.
-
- A flonum is written by writing (in order)
- * The digit `0'. (`0' is optional on the HPPA.)
-
- * A letter, to tell `as' the rest of the number is a flonum. `e' is
- recommended. Case is not important.
-
- On the H8/300, Renesas / SuperH SH, and AMD 29K architectures, the
- letter must be one of the letters `DFPRSX' (in upper or lower
- case).
-
- On the ARC, the letter must be one of the letters `DFRS' (in upper
- or lower case).
-
- On the Intel 960 architecture, the letter must be one of the
- letters `DFT' (in upper or lower case).
-
- On the HPPA architecture, the letter must be `E' (upper case only).
-
- * An optional sign: either `+' or `-'.
-
- * An optional "integer part": zero or more decimal digits.
-
- * An optional "fractional part": `.' followed by zero or more
- decimal digits.
-
- * An optional exponent, consisting of:
-
- * An `E' or `e'.
-
- * Optional sign: either `+' or `-'.
-
- * One or more decimal digits.
-
-
- At least one of the integer part or the fractional part must be
-present. The floating point number has the usual base-10 value.
-
- `as' does all processing using integers. Flonums are computed
-independently of any floating point hardware in the computer running
-`as'.
-
-\1f
-File: as.info, Node: Sections, Next: Symbols, Prev: Syntax, Up: Top
-
-4 Sections and Relocation
-*************************
-
-* Menu:
-
-* Secs Background:: Background
-* Ld Sections:: Linker Sections
-* As Sections:: Assembler Internal Sections
-* Sub-Sections:: Sub-Sections
-* bss:: bss Section
-
-\1f
-File: as.info, Node: Secs Background, Next: Ld Sections, Up: Sections
-
-4.1 Background
-==============
-
-Roughly, a section is a range of addresses, with no gaps; all data "in"
-those addresses is treated the same for some particular purpose. For
-example there may be a "read only" section.
-
- The linker `ld' reads many object files (partial programs) and
-combines their contents to form a runnable program. When `as' emits an
-object file, the partial program is assumed to start at address 0.
-`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 `as' uses sections.
-
- `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 _section_. Assigning
-run-time addresses to sections is called "relocation". It includes the
-task of adjusting mentions of object-file addresses so they refer to
-the proper run-time addresses. For the H8/300, and for the Renesas /
-SuperH SH, `as' pads sections if needed to ensure they end on a word
-(sixteen bit) boundary.
-
- An object file written by `as' has at least three sections, any of
-which may be empty. These are named "text", "data" and "bss" sections.
-
- When it generates COFF or ELF output, `as' can also generate
-whatever other named sections you specify using the `.section'
-directive (*note `.section': Section.). If you do not use any
-directives that place output in the `.text' or `.data' sections, these
-sections still exist, but are empty.
-
- When `as' generates SOM or ELF output for the HPPA, `as' can also
-generate whatever other named sections you specify using the `.space'
-and `.subspace' directives. See `HP9000 Series 800 Assembly Language
-Reference Manual' (HP 92432-90001) for details on the `.space' and
-`.subspace' assembler directives.
-
- Additionally, `as' uses different names for the standard text, data,
-and bss sections when generating SOM output. Program text is placed
-into the `$CODE$' section, data into `$DATA$', and BSS into `$BSS$'.
-
- Within the object file, the text section starts at address `0', the
-data section follows, and the bss section follows the data section.
-
- When generating either SOM or ELF output files on the HPPA, the text
-section starts at address `0', the data section at address `0x4000000',
-and the bss section follows the data section.
-
- To let `ld' know which data changes when the sections are relocated,
-and how to change that data, `as' also writes to the object file
-details of the relocation needed. To perform relocation `ld' must
-know, each time an address in the object file is mentioned:
- * Where in the object file is the beginning of this reference to an
- address?
-
- * How long (in bytes) is this reference?
-
- * Which section does the address refer to? What is the numeric
- value of
- (ADDRESS) - (START-ADDRESS OF SECTION)?
-
- * Is the reference to an address "Program-Counter relative"?
-
- In fact, every address `as' ever uses is expressed as
- (SECTION) + (OFFSET INTO SECTION)
- Further, most expressions `as' computes have this section-relative
-nature. (For some object formats, such as SOM for the HPPA, some
-expressions are symbol-relative instead.)
-
- In this manual we use the notation {SECNAME N} to mean "offset N
-into section SECNAME."
-
- Apart from text, data and bss sections you need to know about the
-"absolute" section. When `ld' mixes partial programs, addresses in the
-absolute section remain unchanged. For example, address `{absolute 0}'
-is "relocated" to run-time address 0 by `ld'. Although the linker
-never arranges two partial programs' data sections with overlapping
-addresses after linking, _by definition_ their absolute sections must
-overlap. Address `{absolute 239}' in one part of a program is always
-the same address when the program is running as address `{absolute
-239}' in any other part of the program.
-
- The idea of sections is extended to the "undefined" section. Any
-address whose section is unknown at assembly time is by definition
-rendered {undefined U}--where 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 _undefined_.
-
- By analogy the word _section_ is used to describe groups of sections
-in the linked program. `ld' puts all partial programs' text sections
-in contiguous addresses in the linked program. It is customary to
-refer to the _text section_ of a program, meaning all the addresses of
-all partial programs' text sections. Likewise for data and bss
-sections.
-
- Some sections are manipulated by `ld'; others are invented for use
-of `as' and have no meaning except during assembly.
-
-\1f
-File: as.info, Node: Ld Sections, Next: As Sections, Prev: Secs Background, Up: Sections
-
-4.2 Linker Sections
-===================
-
-`ld' deals with just four kinds of sections, summarized below.
-
-*named sections*
-*text section*
-*data section*
- These sections hold your program. `as' and `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.
-
-*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.
-
-*absolute section*
- Address 0 of this section is always "relocated" to runtime address
- 0. This is useful if you want to refer to an address that `ld'
- must not change when relocating. In this sense we speak of
- absolute addresses being "unrelocatable": they do not change
- during relocation.
-
-*undefined section*
- This "section" is a catch-all for address references to objects
- not in the preceding sections.
-
- An idealized example of three relocatable sections follows. The
-example uses the traditional section names `.text' and `.data'. Memory
-addresses are on the horizontal axis.
-
- +-----+----+--+
- 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 ...
-
-\1f
-File: as.info, Node: As Sections, Next: Sub-Sections, Prev: Ld Sections, Up: Sections
-
-4.3 Assembler Internal Sections
-===============================
-
-These sections are meant only for the internal use of `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 `as' warning
-messages, so it might be helpful to have an idea of their meanings to
-`as'. These sections are used to permit the value of every expression
-in your assembly language program to be a section-relative address.
-
-ASSEMBLER-INTERNAL-LOGIC-ERROR!
- An internal assembler logic error has been found. This means
- there is a bug in the assembler.
-
-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.
-
-\1f
-File: as.info, Node: Sub-Sections, Next: bss, Prev: As Sections, Up: Sections
-
-4.4 Sub-Sections
-================
-
-Assembled bytes conventionally fall into two sections: text and data.
-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. `as' allows you to use
-"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 `.text 0' before each section of code being
-output, and a `.text 1' before each group of constants being output.
-
-Subsections are optional. If you do not use subsections, everything
-goes in subsection number zero.
-
- Each subsection is zero-padded up to a multiple of four bytes.
-(Subsections may be padded a different amount on different flavors of
-`as'.)
-
- 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; `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.
-
- To specify which subsection you want subsequent statements assembled
-into, use a numeric argument to specify it, in a `.text EXPRESSION' or
-a `.data EXPRESSION' statement. When generating COFF output, you can
-also use an extra subsection argument with arbitrary named sections:
-`.section NAME, EXPRESSION'. When generating ELF output, you can also
-use the `.subsection' directive (*note SubSection::) to specify a
-subsection: `.subsection EXPRESSION'. EXPRESSION should be an absolute
-expression (*note Expressions::). If you just say `.text' then `.text
-0' is assumed. Likewise `.data' means `.data 0'. Assembly begins in
-`text 0'. For instance:
- .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 (*)."
-
- Each section has a "location counter" incremented by one for every
-byte assembled into that section. Because subsections are merely a
-convenience restricted to `as' there is no concept of a subsection
-location counter. There is no way to directly manipulate a location
-counter--but the `.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 "active"
-location counter.
-
-\1f
-File: as.info, Node: bss, Prev: Sub-Sections, Up: Sections
-
-4.5 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.
-
- The `.lcomm' pseudo-op defines a symbol in the bss section; see
-*Note `.lcomm': Lcomm.
-
- The `.comm' pseudo-op may be used to declare a common symbol, which
-is another form of uninitialized symbol; see *Note `.comm': Comm.
-
- When assembling for a target which supports multiple sections, such
-as ELF or COFF, you may switch into the `.bss' section and define
-symbols as usual; see *Note `.section': Section. You may only assemble
-zero values into the section. Typically the section will only contain
-symbol definitions and `.skip' directives (*note `.skip': Skip.).
-
-\1f
-File: as.info, Node: Symbols, Next: Expressions, Prev: Sections, Up: Top
-
-5 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.
-
- _Warning:_ `as' does not place symbols in the object file in the
- same order they were declared. This may break some debuggers.
-
-* Menu:
-
-* Labels:: Labels
-* Setting Symbols:: Giving Symbols Other Values
-* Symbol Names:: Symbol Names
-* Dot:: The Special Dot Symbol
-* Symbol Attributes:: Symbol Attributes
-
-\1f
-File: as.info, Node: Labels, Next: Setting Symbols, Up: Symbols
-
-5.1 Labels
-==========
-
-A "label" is written as a symbol immediately followed by a colon `:'.
-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.
-
- On the HPPA, the usual form for a label need not be immediately
-followed by a colon, but instead must start in column zero. Only one
-label may be defined on a single line. To work around this, the HPPA
-version of `as' also provides a special directive `.label' for defining
-labels more flexibly.
-
-\1f
-File: as.info, Node: Setting Symbols, Next: Symbol Names, Prev: Labels, Up: Symbols
-
-5.2 Giving Symbols Other Values
-===============================
-
-A symbol can be given an arbitrary value by writing a symbol, followed
-by an equals sign `=', followed by an expression (*note Expressions::).
-This is equivalent to using the `.set' directive. *Note `.set': Set.
-In the same way, using a double equals sign `='`=' here represents an
-equivalent of the `.eqv' directive. *Note `.eqv': Eqv.
-
-\1f
-File: as.info, Node: Symbol Names, Next: Dot, Prev: Setting Symbols, Up: Symbols
-
-5.3 Symbol Names
-================
-
-Symbol names begin with a letter or with one of `._'. On most
-machines, you can also use `$' in symbol names; exceptions are noted in
-*Note 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.
-
-Case of letters is significant: `foo' is a different symbol name than
-`Foo'.
-
- 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.
-
-Local Symbol Names
-------------------
-
-A local symbol is any symbol beginning with certain local label
-prefixes. By default, the local label prefix is `.L' for ELF systems or
-`L' for traditional a.out systems, but each target may have its own set
-of local label prefixes. On the HPPA local symbols begin with `L$'.
-
- 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 `-L' option (*note Include Local Symbols:
-`-L': L.) to retain the local symbols in the object files.
-
-Local Labels
-------------
-
-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 `N:'
-(where N represents any positive integer). To refer to the most recent
-previous definition of that label write `Nb', using the same number as
-when you defined the label. To refer to the next definition of a local
-label, write `Nf'--the `b' stands for "backwards" and the `f' stands
-for "forwards".
-
- 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 `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 (`0:'...`9:') are implemented in a slightly more efficient
-manner than the others.
-
- Here is an example:
-
- 1: branch 1f
- 2: branch 1b
- 1: branch 2f
- 2: branch 1b
-
- Which is the equivalent of:
-
- label_1: branch label_3
- label_2: branch label_1
- label_3: branch label_4
- label_4: branch label_3
-
- 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:
-
-`_local label prefix_'
- All local symbols begin with the system-specific local label
- prefix. Normally both `as' and `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 `-L' option then
- `as' retains these symbols in the object file. If you also
- instruct `ld' to retain these symbols, you may use them in
- debugging.
-
-`NUMBER'
- This is the number that was used in the local label definition.
- So if the label is written `55:' then the number is `55'.
-
-`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 `\002' (control-B).
-
-`_ordinal number_'
- This is a serial number to keep the labels distinct. The first
- definition of `0:' gets the number `1'. The 15th definition of
- `0:' gets the number `15', and so on. Likewise the first
- definition of `1:' gets the number `1' and its 15th definition
- gets `15' as well.
-
- So for example, the first `1:' may be named `.L1C-B1', and the 44th
-`3:' may be named `.L3C-B44'.
-
-Dollar Local Labels
--------------------
-
-`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.
-
- 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., `55$'.
-
- They can also be distinguished from ordinary local labels by their
-transformed names which use ASCII character `\001' (control-A) as the
-magic character to distinguish them from ordinary labels. For example,
-the fifth definition of `6$' may be named `.L6C-A5'.
-
-\1f
-File: as.info, Node: Dot, Next: Symbol Attributes, Prev: Symbol Names, Up: Symbols
-
-5.4 The Special Dot Symbol
-==========================
-
-The special symbol `.' refers to the current address that `as' is
-assembling into. Thus, the expression `melvin: .long .' defines
-`melvin' to contain its own address. Assigning a value to `.' is
-treated the same as a `.org' directive. Thus, the expression `.=.+4'
-is the same as saying `.space 4'.
-
-\1f
-File: as.info, Node: Symbol Attributes, Prev: Dot, Up: Symbols
-
-5.5 Symbol Attributes
-=====================
-
-Every symbol has, as well as its name, the attributes "Value" and
-"Type". Depending on output format, symbols can also have auxiliary
-attributes.
-
- If you use a symbol without defining it, `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.
-
-* Menu:
-
-* Symbol Value:: Value
-* Symbol Type:: Type
-
-
-* a.out Symbols:: Symbol Attributes: `a.out'
-
-* COFF Symbols:: Symbol Attributes for COFF
-
-* SOM Symbols:: Symbol Attributes for SOM
-
-\1f
-File: as.info, Node: Symbol Value, Next: Symbol Type, Up: Symbol Attributes
-
-5.5.1 Value
------------
-
-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 `ld' changes section base addresses during linking. Absolute
-symbols' values do not change during linking: that is why they are
-called absolute.
-
- 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
-`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 `.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.
-
-\1f
-File: as.info, Node: Symbol Type, Next: a.out Symbols, Prev: Symbol Value, Up: Symbol Attributes
-
-5.5.2 Type
-----------
-
-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.
-
-\1f
-File: as.info, Node: a.out Symbols, Next: COFF Symbols, Prev: Symbol Type, Up: Symbol Attributes
-
-5.5.3 Symbol Attributes: `a.out'
---------------------------------
-
-* Menu:
-
-* Symbol Desc:: Descriptor
-* Symbol Other:: Other
-
-\1f
-File: as.info, Node: Symbol Desc, Next: Symbol Other, Up: a.out Symbols
-
-5.5.3.1 Descriptor
-..................
-
-This is an arbitrary 16-bit value. You may establish a symbol's
-descriptor value by using a `.desc' statement (*note `.desc': Desc.).
-A descriptor value means nothing to `as'.
-
-\1f
-File: as.info, Node: Symbol Other, Prev: Symbol Desc, Up: a.out Symbols
-
-5.5.3.2 Other
-.............
-
-This is an arbitrary 8-bit value. It means nothing to `as'.
-
-\1f
-File: as.info, Node: COFF Symbols, Next: SOM Symbols, Prev: a.out Symbols, Up: Symbol Attributes
-
-5.5.4 Symbol Attributes for COFF
---------------------------------
-
-The COFF format supports a multitude of auxiliary symbol attributes;
-like the primary symbol attributes, they are set between `.def' and
-`.endef' directives.
-
-5.5.4.1 Primary Attributes
-..........................
-
-The symbol name is set with `.def'; the value and type, respectively,
-with `.val' and `.type'.
-
-5.5.4.2 Auxiliary Attributes
-............................
-
-The `as' directives `.dim', `.line', `.scl', `.size', `.tag', and
-`.weak' can generate auxiliary symbol table information for COFF.
-
-\1f
-File: as.info, Node: SOM Symbols, Prev: COFF Symbols, Up: Symbol Attributes
-
-5.5.5 Symbol Attributes for SOM
--------------------------------
-
-The SOM format for the HPPA supports a multitude of symbol attributes
-set with the `.EXPORT' and `.IMPORT' directives.
-
- The attributes are described in `HP9000 Series 800 Assembly Language
-Reference Manual' (HP 92432-90001) under the `IMPORT' and `EXPORT'
-assembler directive documentation.
-
-\1f
-File: as.info, Node: Expressions, Next: Pseudo Ops, Prev: Symbols, Up: Top
-
-6 Expressions
-*************
-
-An "expression" specifies an address or numeric value. Whitespace may
-precede and/or follow an expression.
-
- 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 `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. `as' aborts with an error message in this situation.
-
-* Menu:
-
-* Empty Exprs:: Empty Expressions
-* Integer Exprs:: Integer Expressions
-
-\1f
-File: as.info, Node: Empty Exprs, Next: Integer Exprs, Up: Expressions
-
-6.1 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 `as' assumes a value of (absolute) 0. This is
-compatible with other assemblers.
-
-\1f
-File: as.info, Node: Integer Exprs, Prev: Empty Exprs, Up: Expressions
-
-6.2 Integer Expressions
-=======================
-
-An "integer expression" is one or more _arguments_ delimited by
-_operators_.
-
-* Menu:
-
-* Arguments:: Arguments
-* Operators:: Operators
-* Prefix Ops:: Prefix Operators
-* Infix Ops:: Infix Operators
-
-\1f
-File: as.info, Node: Arguments, Next: Operators, Up: Integer Exprs
-
-6.2.1 Arguments
----------------
-
-"Arguments" are symbols, numbers or subexpressions. In other contexts
-arguments are sometimes called "arithmetic operands". In this manual,
-to avoid confusing them with the "instruction operands" of the machine
-language, we use the term "argument" to refer to parts of expressions
-only, reserving the word "operand" to refer only to machine instruction
-operands.
-
- Symbols are evaluated to yield {SECTION NNN} where SECTION is one of
-text, data, bss, absolute, or undefined. NNN is a signed, 2's
-complement 32 bit integer.
-
- Numbers are usually integers.
-
- A number can be a flonum or bignum. In this case, you are warned
-that only the low order 32 bits are used, and `as' pretends these 32
-bits are an integer. You may write integer-manipulating instructions
-that act on exotic constants, compatible with other assemblers.
-
- Subexpressions are a left parenthesis `(' followed by an integer
-expression, followed by a right parenthesis `)'; or a prefix operator
-followed by an argument.
-
-\1f
-File: as.info, Node: Operators, Next: Prefix Ops, Prev: Arguments, Up: Integer Exprs
-
-6.2.2 Operators
----------------
-
-"Operators" are arithmetic functions, like `+' or `%'. Prefix
-operators are followed by an argument. Infix operators appear between
-their arguments. Operators may be preceded and/or followed by
-whitespace.
-
-\1f
-File: as.info, Node: Prefix Ops, Next: Infix Ops, Prev: Operators, Up: Integer Exprs
-
-6.2.3 Prefix Operator
----------------------
-
-`as' has the following "prefix operators". They each take one
-argument, which must be absolute.
-
-`-'
- "Negation". Two's complement negation.
-
-`~'
- "Complementation". Bitwise not.
-
-\1f
-File: as.info, Node: Infix Ops, Prev: Prefix Ops, Up: Integer Exprs
-
-6.2.4 Infix Operators
----------------------
-
-"Infix operators" take two arguments, one on either side. Operators
-have precedence, but operations with equal precedence are performed left
-to right. Apart from `+' or `-', both arguments must be absolute, and
-the result is absolute.
-
- 1. Highest Precedence
-
- `*'
- "Multiplication".
-
- `/'
- "Division". Truncation is the same as the C operator `/'
-
- `%'
- "Remainder".
-
- `<<'
- "Shift Left". Same as the C operator `<<'.
-
- `>>'
- "Shift Right". Same as the C operator `>>'.
-
- 2. Intermediate precedence
-
- `|'
- "Bitwise Inclusive Or".
-
- `&'
- "Bitwise And".
-
- `^'
- "Bitwise Exclusive Or".
-
- `!'
- "Bitwise Or Not".
-
- 3. Low Precedence
-
- `+'
- "Addition". If either argument is absolute, the result has
- the section of the other argument. You may not add together
- arguments from different sections.
-
- `-'
- "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.
-
- `=='
- "Is Equal To"
-
- `<>'
- `!='
- "Is Not Equal To"
-
- `<'
- "Is Less Than"
-
- `>'
- "Is Greater Than"
-
- `>='
- "Is Greater Than Or Equal To"
-
- `<='
- "Is Less Than Or Equal To"
-
- 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.
-
- 4. Lowest Precedence
-
- `&&'
- "Logical And".
-
- `||'
- "Logical Or".
-
- 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.
-
-
- In short, it's only meaningful to add or subtract the _offsets_ in an
-address; you can only have a defined section in one of the two
-arguments.
-
-\1f
-File: as.info, Node: Pseudo Ops, Next: Machine Dependencies, Prev: Expressions, Up: Top
-
-7 Assembler Directives
-**********************
-
-All assembler directives have names that begin with a period (`.').
-The rest of the name is letters, usually in lower case.
-
- This chapter discusses directives that are available regardless of
-the target machine configuration for the GNU assembler. Some machine
-configurations provide additional directives. *Note Machine
-Dependencies::.
-
-* Menu:
-
-* Abort:: `.abort'
-
-* ABORT (COFF):: `.ABORT'
-
-* Align:: `.align ABS-EXPR , ABS-EXPR'
-* Altmacro:: `.altmacro'
-* Ascii:: `.ascii "STRING"'...
-* Asciz:: `.asciz "STRING"'...
-* Balign:: `.balign ABS-EXPR , ABS-EXPR'
-* Byte:: `.byte EXPRESSIONS'
-* Comm:: `.comm SYMBOL , LENGTH '
-
-* CFI directives:: `.cfi_startproc [simple]', `.cfi_endproc', etc.
-
-* Data:: `.data SUBSECTION'
-
-* Def:: `.def NAME'
-
-* Desc:: `.desc SYMBOL, ABS-EXPRESSION'
-
-* Dim:: `.dim'
-
-* Double:: `.double FLONUMS'
-* Eject:: `.eject'
-* Else:: `.else'
-* Elseif:: `.elseif'
-* End:: `.end'
-
-* Endef:: `.endef'
-
-* Endfunc:: `.endfunc'
-* Endif:: `.endif'
-* Equ:: `.equ SYMBOL, EXPRESSION'
-* Equiv:: `.equiv SYMBOL, EXPRESSION'
-* Eqv:: `.eqv SYMBOL, EXPRESSION'
-* Err:: `.err'
-* Error:: `.error STRING'
-* Exitm:: `.exitm'
-* Extern:: `.extern'
-* Fail:: `.fail'
-
-* File:: `.file STRING'
-
-* Fill:: `.fill REPEAT , SIZE , VALUE'
-* Float:: `.float FLONUMS'
-* Func:: `.func'
-* Global:: `.global SYMBOL', `.globl SYMBOL'
-
-* Hidden:: `.hidden NAMES'
-
-* hword:: `.hword EXPRESSIONS'
-* Ident:: `.ident'
-* If:: `.if ABSOLUTE EXPRESSION'
-* Incbin:: `.incbin "FILE"[,SKIP[,COUNT]]'
-* Include:: `.include "FILE"'
-* Int:: `.int EXPRESSIONS'
-
-* Internal:: `.internal NAMES'
-
-* Irp:: `.irp SYMBOL,VALUES'...
-* Irpc:: `.irpc SYMBOL,VALUES'...
-* Lcomm:: `.lcomm SYMBOL , LENGTH'
-* Lflags:: `.lflags'
-
-* Line:: `.line LINE-NUMBER'
-
-* Linkonce:: `.linkonce [TYPE]'
-* List:: `.list'
-* Ln:: `.ln LINE-NUMBER'
-
-* LNS directives:: `.file', `.loc', etc.
-
-* Long:: `.long EXPRESSIONS'
-
-* Macro:: `.macro NAME ARGS'...
-* MRI:: `.mri VAL'
-* Noaltmacro:: `.noaltmacro'
-* Nolist:: `.nolist'
-* Octa:: `.octa BIGNUMS'
-* Org:: `.org NEW-LC, FILL'
-* P2align:: `.p2align ABS-EXPR, ABS-EXPR, ABS-EXPR'
-
-* PopSection:: `.popsection'
-* Previous:: `.previous'
-
-* Print:: `.print STRING'
-
-* Protected:: `.protected NAMES'
-
-* Psize:: `.psize LINES, COLUMNS'
-* Purgem:: `.purgem NAME'
-
-* PushSection:: `.pushsection NAME'
-
-* Quad:: `.quad BIGNUMS'
-* Reloc:: `.reloc OFFSET, RELOC_NAME[, EXPRESSION]'
-* Rept:: `.rept COUNT'
-* Sbttl:: `.sbttl "SUBHEADING"'
-
-* Scl:: `.scl CLASS'
-
-* Section:: `.section NAME'
-
-* Set:: `.set SYMBOL, EXPRESSION'
-* Short:: `.short EXPRESSIONS'
-* Single:: `.single FLONUMS'
-
-* Size:: `.size [NAME , EXPRESSION]'
-
-* Skip:: `.skip SIZE , FILL'
-* Sleb128:: `.sleb128 EXPRESSIONS'
-* Space:: `.space SIZE , FILL'
-
-* Stab:: `.stabd, .stabn, .stabs'
-
-* String:: `.string "STR"'
-* Struct:: `.struct EXPRESSION'
-
-* SubSection:: `.subsection'
-* Symver:: `.symver NAME,NAME2@NODENAME'
-
-
-* Tag:: `.tag STRUCTNAME'
-
-* Text:: `.text SUBSECTION'
-* Title:: `.title "HEADING"'
-
-* Type:: `.type <INT | NAME , TYPE DESCRIPTION>'
-
-* Uleb128:: `.uleb128 EXPRESSIONS'
-
-* Val:: `.val ADDR'
-
-
-* Version:: `.version "STRING"'
-* VTableEntry:: `.vtable_entry TABLE, OFFSET'
-* VTableInherit:: `.vtable_inherit CHILD, PARENT'
-
-* Warning:: `.warning STRING'
-* Weak:: `.weak NAMES'
-* Weakref:: `.weakref ALIAS, SYMBOL'
-* Word:: `.word EXPRESSIONS'
-* Deprecated:: Deprecated Directives
-
-\1f
-File: as.info, Node: Abort, Next: ABORT (COFF), Up: Pseudo Ops
-
-7.1 `.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 `as' to quit also.
-One day `.abort' will not be supported.
-
-\1f
-File: as.info, Node: ABORT (COFF), Next: Align, Prev: Abort, Up: Pseudo Ops
-
-7.2 `.ABORT' (COFF)
-===================
-
-When producing COFF output, `as' accepts this directive as a synonym
-for `.abort'.
-
-\1f
-File: as.info, Node: Align, Next: Altmacro, Prev: ABORT (COFF), Up: Pseudo Ops
-
-7.3 `.align ABS-EXPR, ABS-EXPR, 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.
-
- 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.
-
- 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.
-
- 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 `.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.
-
- 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 `.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.
-
- This inconsistency is due to the different behaviors of the various
-native assemblers for these systems which GAS must emulate. GAS also
-provides `.balign' and `.p2align' directives, described later, which
-have a consistent behavior across all architectures (but are specific
-to GAS).
-
-\1f
-File: as.info, Node: Ascii, Next: Asciz, Prev: Altmacro, Up: Pseudo Ops
-
-7.4 `.ascii "STRING"'...
-========================
-
-`.ascii' expects zero or more string literals (*note Strings::)
-separated by commas. It assembles each string (with no automatic
-trailing zero byte) into consecutive addresses.
-
-\1f
-File: as.info, Node: Asciz, Next: Balign, Prev: Ascii, Up: Pseudo Ops
-
-7.5 `.asciz "STRING"'...
-========================
-
-`.asciz' is just like `.ascii', but each string is followed by a zero
-byte. The "z" in `.asciz' stands for "zero".
-
-\1f
-File: as.info, Node: Balign, Next: Byte, Prev: Asciz, Up: Pseudo Ops
-
-7.6 `.balign[wl] ABS-EXPR, ABS-EXPR, 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 `.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.
-
- 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.
-
- 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.
-
- The `.balignw' and `.balignl' directives are variants of the
-`.balign' directive. The `.balignw' directive treats the fill pattern
-as a two byte word value. The `.balignl' directives treats the fill
-pattern as a four byte longword value. For example, `.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.
-
-\1f
-File: as.info, Node: Byte, Next: Comm, Prev: Balign, Up: Pseudo Ops
-
-7.7 `.byte EXPRESSIONS'
-=======================
-
-`.byte' expects zero or more expressions, separated by commas. Each
-expression is assembled into the next byte.
-
-\1f
-File: as.info, Node: Comm, Next: CFI directives, Prev: Byte, Up: Pseudo Ops
-
-7.8 `.comm SYMBOL , LENGTH '
-============================
-
-`.comm' declares a common symbol named 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 `ld' does not see a
-definition for the symbol-just one or more common symbols-then it will
-allocate LENGTH bytes of uninitialized memory. LENGTH must be an
-absolute expression. If `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.
-
- When using ELF, the `.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 `ld'
-allocates uninitialized memory for the common symbol, it will use the
-alignment when placing the symbol. If no alignment is specified, `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.
-
- The syntax for `.comm' differs slightly on the HPPA. The syntax is
-`SYMBOL .comm, LENGTH'; SYMBOL is optional.
-
-\1f
-File: as.info, Node: CFI directives, Next: Data, Prev: Comm, Up: Pseudo Ops
-
-7.9 `.cfi_startproc [simple]'
-=============================
-
-`.cfi_startproc' is used at the beginning of each function that should
-have an entry in `.eh_frame'. It initializes some internal data
-structures. Don't forget to close the function by `.cfi_endproc'.
-
- Unless `.cfi_startproc' is used along with parameter `simple' it
-also emits some architecture dependent initial CFI instructions.
-
-7.10 `.cfi_endproc'
-===================
-
-`.cfi_endproc' is used at the end of a function where it closes its
-unwind entry previously opened by `.cfi_startproc', and emits it to
-`.eh_frame'.
-
-7.11 `.cfi_personality ENCODING [, EXP]'
-========================================
-
-`.cfi_personality' defines personality routine and its encoding.
-ENCODING must be a constant determining how the personality should be
-encoded. If it is 255 (`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 `.cfi_startproc' is
-`.cfi_personality 0xff', no personality routine.
-
-7.12 `.cfi_lsda ENCODING [, EXP]'
-=================================
-
-`.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant
-determining how the LSDA should be encoded. If it is 255
-(`DW_EH_PE_omit'), second argument is not present, otherwise second
-argument should be a constant or a symbol name. The default after
-`.cfi_startproc' is `.cfi_lsda 0xff', no LSDA.
-
-7.13 `.cfi_def_cfa REGISTER, OFFSET'
-====================================
-
-`.cfi_def_cfa' defines a rule for computing CFA as: take address from
-REGISTER and add OFFSET to it.
-
-7.14 `.cfi_def_cfa_register REGISTER'
-=====================================
-
-`.cfi_def_cfa_register' modifies a rule for computing CFA. From now on
-REGISTER will be used instead of the old one. Offset remains the same.
-
-7.15 `.cfi_def_cfa_offset OFFSET'
-=================================
-
-`.cfi_def_cfa_offset' modifies a rule for computing CFA. Register
-remains the same, but OFFSET is new. Note that it is the absolute
-offset that will be added to a defined register to compute CFA address.
-
-7.16 `.cfi_adjust_cfa_offset OFFSET'
-====================================
-
-Same as `.cfi_def_cfa_offset' but OFFSET is a relative value that is
-added/substracted from the previous offset.
-
-7.17 `.cfi_offset REGISTER, OFFSET'
-===================================
-
-Previous value of REGISTER is saved at offset OFFSET from CFA.
-
-7.18 `.cfi_rel_offset REGISTER, OFFSET'
-=======================================
-
-Previous value of REGISTER is saved at offset OFFSET from the current
-CFA register. This is transformed to `.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.
-
-7.19 `.cfi_register REGISTER1, REGISTER2'
-=========================================
-
-Previous value of REGISTER1 is saved in register REGISTER2.
-
-7.20 `.cfi_restore REGISTER'
-============================
-
-`.cfi_restore' says that the rule for REGISTER is now the same as it
-was at the beginning of the function, after all initial instruction
-added by `.cfi_startproc' were executed.
-
-7.21 `.cfi_undefined REGISTER'
-==============================
-
-From now on the previous value of REGISTER can't be restored anymore.
-
-7.22 `.cfi_same_value REGISTER'
-===============================
-
-Current value of REGISTER is the same like in the previous frame, i.e.
-no restoration needed.
-
-7.23 `.cfi_remember_state',
-===========================
-
-First save all current rules for all registers by `.cfi_remember_state',
-then totally screw them up by subsequent `.cfi_*' directives and when
-everything is hopelessly bad, use `.cfi_restore_state' to restore the
-previous saved state.
-
-7.24 `.cfi_return_column REGISTER'
-==================================
-
-Change return column REGISTER, i.e. the return address is either
-directly in REGISTER or can be accessed by rules for REGISTER.
-
-7.25 `.cfi_signal_frame'
-========================
-
-Mark current function as signal trampoline.
-
-7.26 `.cfi_window_save'
-=======================
-
-SPARC register window has been saved.
-
-7.27 `.cfi_escape' 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.
-
-\1f
-File: as.info, Node: LNS directives, Next: Long, Prev: Ln, Up: Pseudo Ops
-
-7.28 `.file FILENO FILENAME'
-============================
-
-When emitting dwarf2 line number information `.file' assigns filenames
-to the `.debug_line' file name table. The FILENO operand should be a
-unique positive integer to use as the index of the entry in the table.
-The FILENAME operand is a C string literal.
-
- The detail of filename indices is exposed to the user because the
-filename table is shared with the `.debug_info' section of the dwarf2
-debugging information, and thus the user must know the exact indices
-that table entries will have.
-
-7.29 `.loc FILENO LINENO [COLUMN] [OPTIONS]'
-============================================
-
-The `.loc' directive will add row to the `.debug_line' line number
-matrix corresponding to the immediately following assembly instruction.
-The FILENO, LINENO, and optional COLUMN arguments will be applied to
-the `.debug_line' state machine before the row is added.
-
- The OPTIONS are a sequence of the following tokens in any order:
-
-`basic_block'
- This option will set the `basic_block' register in the
- `.debug_line' state machine to `true'.
-
-`prologue_end'
- This option will set the `prologue_end' register in the
- `.debug_line' state machine to `true'.
-
-`epilogue_begin'
- This option will set the `epilogue_begin' register in the
- `.debug_line' state machine to `true'.
-
-`is_stmt VALUE'
- This option will set the `is_stmt' register in the `.debug_line'
- state machine to `value', which must be either 0 or 1.
-
-`isa VALUE'
- This directive will set the `isa' register in the `.debug_line'
- state machine to VALUE, which must be an unsigned integer.
-
-
-7.30 `.loc_mark_blocks ENABLE'
-==============================
-
-The `.loc_mark_blocks' directive makes the assembler emit an entry to
-the `.debug_line' line number matrix with the `basic_block' register in
-the state machine set whenever a code label is seen. The ENABLE
-argument should be either 1 or 0, to enable or disable this function
-respectively.
-
-\1f
-File: as.info, Node: Data, Next: Def, Prev: CFI directives, Up: Pseudo Ops
-
-7.31 `.data SUBSECTION'
-=======================
-
-`.data' tells `as' to assemble the following statements onto the end of
-the data subsection numbered SUBSECTION (which is an absolute
-expression). If SUBSECTION is omitted, it defaults to zero.
-
-\1f
-File: as.info, Node: Def, Next: Desc, Prev: Data, Up: Pseudo Ops
-
-7.32 `.def NAME'
-================
-
-Begin defining debugging information for a symbol NAME; the definition
-extends until the `.endef' directive is encountered.
-
-\1f
-File: as.info, Node: Desc, Next: Dim, Prev: Def, Up: Pseudo Ops
-
-7.33 `.desc SYMBOL, ABS-EXPRESSION'
-===================================
-
-This directive sets the descriptor of the symbol (*note Symbol
-Attributes::) to the low 16 bits of an absolute expression.
-
- The `.desc' directive is not available when `as' is configured for
-COFF output; it is only for `a.out' or `b.out' object format. For the
-sake of compatibility, `as' accepts it, but produces no output, when
-configured for COFF.
-
-\1f
-File: as.info, Node: Dim, Next: Double, Prev: Desc, Up: Pseudo Ops
-
-7.34 `.dim'
-===========
-
-This directive is generated by compilers to include auxiliary debugging
-information in the symbol table. It is only permitted inside
-`.def'/`.endef' pairs.
-
-\1f
-File: as.info, Node: Double, Next: Eject, Prev: Dim, Up: Pseudo Ops
-
-7.35 `.double FLONUMS'
-======================
-
-`.double' expects zero or more flonums, separated by commas. It
-assembles floating point numbers. The exact kind of floating point
-numbers emitted depends on how `as' is configured. *Note Machine
-Dependencies::.
-
-\1f
-File: as.info, Node: Eject, Next: Else, Prev: Double, Up: Pseudo Ops
-
-7.36 `.eject'
-=============
-
-Force a page break at this point, when generating assembly listings.
-
-\1f
-File: as.info, Node: Else, Next: Elseif, Prev: Eject, Up: Pseudo Ops
-
-7.37 `.else'
-============
-
-`.else' is part of the `as' support for conditional assembly; see *Note
-`.if': If. It marks the beginning of a section of code to be assembled
-if the condition for the preceding `.if' was false.
-
-\1f
-File: as.info, Node: Elseif, Next: End, Prev: Else, Up: Pseudo Ops
-
-7.38 `.elseif'
-==============
-
-`.elseif' is part of the `as' support for conditional assembly; see
-*Note `.if': If. It is shorthand for beginning a new `.if' block that
-would otherwise fill the entire `.else' section.
-
-\1f
-File: as.info, Node: End, Next: Endef, Prev: Elseif, Up: Pseudo Ops
-
-7.39 `.end'
-===========
-
-`.end' marks the end of the assembly file. `as' does not process
-anything in the file past the `.end' directive.
-
-\1f
-File: as.info, Node: Endef, Next: Endfunc, Prev: End, Up: Pseudo Ops
-
-7.40 `.endef'
-=============
-
-This directive flags the end of a symbol definition begun with `.def'.
-
-\1f
-File: as.info, Node: Endfunc, Next: Endif, Prev: Endef, Up: Pseudo Ops
-
-7.41 `.endfunc'
-===============
-
-`.endfunc' marks the end of a function specified with `.func'.
-
-\1f
-File: as.info, Node: Endif, Next: Equ, Prev: Endfunc, Up: Pseudo Ops
-
-7.42 `.endif'
-=============
-
-`.endif' is part of the `as' support for conditional assembly; it marks
-the end of a block of code that is only assembled conditionally. *Note
-`.if': If.
-
-\1f
-File: as.info, Node: Equ, Next: Equiv, Prev: Endif, Up: Pseudo Ops
-
-7.43 `.equ SYMBOL, EXPRESSION'
-==============================
-
-This directive sets the value of SYMBOL to EXPRESSION. It is
-synonymous with `.set'; see *Note `.set': Set.
-
- The syntax for `equ' on the HPPA is `SYMBOL .equ EXPRESSION'.
-
- The syntax for `equ' on the Z80 is `SYMBOL equ EXPRESSION'. On the
-Z80 it is an eror if SYMBOL is already defined, but the symbol is not
-protected from later redefinition. Compare *Note Equiv::.
-
-\1f
-File: as.info, Node: Equiv, Next: Eqv, Prev: Equ, Up: Pseudo Ops
-
-7.44 `.equiv SYMBOL, EXPRESSION'
-================================
-
-The `.equiv' directive is like `.equ' and `.set', except that the
-assembler will signal an error if SYMBOL is already defined. Note a
-symbol which has been referenced but not actually defined is considered
-to be undefined.
-
- Except for the contents of the error message, this is roughly
-equivalent to
- .ifdef SYM
- .err
- .endif
- .equ SYM,VAL
- plus it protects the symbol from later redefinition.
-
-\1f
-File: as.info, Node: Eqv, Next: Err, Prev: Equiv, Up: Pseudo Ops
-
-7.45 `.eqv SYMBOL, EXPRESSION'
-==============================
-
-The `.eqv' directive is like `.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.
-
-\1f
-File: as.info, Node: Err, Next: Error, Prev: Eqv, Up: Pseudo Ops
-
-7.46 `.err'
-===========
-
-If `as' assembles a `.err' directive, it will print an error message
-and, unless the `-Z' option was used, it will not generate an object
-file. This can be used to signal an error in conditionally compiled
-code.
-
-\1f
-File: as.info, Node: Error, Next: Exitm, Prev: Err, Up: Pseudo Ops
-
-7.47 `.error "STRING"'
-======================
-
-Similarly to `.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 `".error directive invoked in
-source file"'. *Note Error and Warning Messages: Errors.
-
- .error "This code has not been assembled and tested."
-
-\1f
-File: as.info, Node: Exitm, Next: Extern, Prev: Error, Up: Pseudo Ops
-
-7.48 `.exitm'
-=============
-
-Exit early from the current macro definition. *Note Macro::.
-
-\1f
-File: as.info, Node: Extern, Next: Fail, Prev: Exitm, Up: Pseudo Ops
-
-7.49 `.extern'
-==============
-
-`.extern' is accepted in the source program--for compatibility with
-other assemblers--but it is ignored. `as' treats all undefined symbols
-as external.
-
-\1f
-File: as.info, Node: Fail, Next: File, Prev: Extern, Up: Pseudo Ops
-
-7.50 `.fail EXPRESSION'
-=======================
-
-Generates an error or a warning. If the value of the EXPRESSION is 500
-or more, `as' will print a warning message. If the value is less than
-500, `as' will print an error message. The message will include the
-value of EXPRESSION. This can occasionally be useful inside complex
-nested macros or conditional assembly.
-
-\1f
-File: as.info, Node: File, Next: Fill, Prev: Fail, Up: Pseudo Ops
-
-7.51 `.file STRING'
-===================
-
-`.file' tells `as' that we are about to start a new logical file.
-STRING is the new file name. In general, the filename is recognized
-whether or not it is surrounded by quotes `"'; but if you wish to
-specify an empty file name, you must give the quotes-`""'. This
-statement may go away in future: it is only recognized to be compatible
-with old `as' programs.
-
-\1f
-File: as.info, Node: Fill, Next: Float, Prev: File, Up: Pseudo Ops
-
-7.52 `.fill REPEAT , SIZE , VALUE'
-==================================
-
-REPEAT, SIZE and VALUE are absolute expressions. This emits REPEAT
-copies of SIZE bytes. REPEAT may be zero or more. 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 REPEAT
-bytes is taken from an 8-byte number. The highest order 4 bytes are
-zero. The lowest order 4 bytes are VALUE rendered in the byte-order of
-an integer on the computer `as' is assembling for. Each SIZE bytes in
-a repetition is taken from the lowest order SIZE bytes of this number.
-Again, this bizarre behavior is compatible with other people's
-assemblers.
-
- SIZE and VALUE are optional. If the second comma and VALUE are
-absent, VALUE is assumed zero. If the first comma and following tokens
-are absent, SIZE is assumed to be 1.
-
-\1f
-File: as.info, Node: Float, Next: Func, Prev: Fill, Up: Pseudo Ops
-
-7.53 `.float FLONUMS'
-=====================
-
-This directive assembles zero or more flonums, separated by commas. It
-has the same effect as `.single'. The exact kind of floating point
-numbers emitted depends on how `as' is configured. *Note Machine
-Dependencies::.
-
-\1f
-File: as.info, Node: Func, Next: Global, Prev: Float, Up: Pseudo Ops
-
-7.54 `.func NAME[,LABEL]'
-=========================
-
-`.func' emits debugging information to denote function NAME, and is
-ignored unless the file is assembled with debugging enabled. Only
-`--gstabs[+]' is currently supported. LABEL is the entry point of the
-function and if omitted NAME prepended with the `leading char' is used.
-`leading char' is usually `_' or nothing, depending on the target. All
-functions are currently defined to have `void' return type. The
-function must be terminated with `.endfunc'.
-
-\1f
-File: as.info, Node: Global, Next: Hidden, Prev: Func, Up: Pseudo Ops
-
-7.55 `.global SYMBOL', `.globl SYMBOL'
-======================================
-
-`.global' makes the symbol visible to `ld'. If you define SYMBOL in
-your partial program, its value is made available to other partial
-programs that are linked with it. Otherwise, SYMBOL takes its
-attributes from a symbol of the same name from another file linked into
-the same program.
-
- Both spellings (`.globl' and `.global') are accepted, for
-compatibility with other assemblers.
-
- On the HPPA, `.global' is not always enough to make it accessible to
-other partial programs. You may need the HPPA-only `.EXPORT' directive
-as well. *Note HPPA Assembler Directives: HPPA Directives.
-
-\1f
-File: as.info, Node: Hidden, Next: hword, Prev: Global, Up: Pseudo Ops
-
-7.56 `.hidden NAMES'
-====================
-
-This is one of the ELF visibility directives. The other two are
-`.internal' (*note `.internal': Internal.) and `.protected' (*note
-`.protected': Protected.).
-
- This directive overrides the named symbols default visibility (which
-is set by their binding: local, global or weak). The directive sets
-the visibility to `hidden' which means that the symbols are not visible
-to other components. Such symbols are always considered to be
-`protected' as well.
-
-\1f
-File: as.info, Node: hword, Next: Ident, Prev: Hidden, Up: Pseudo Ops
-
-7.57 `.hword EXPRESSIONS'
-=========================
-
-This expects zero or more EXPRESSIONS, and emits a 16 bit number for
-each.
-
- This directive is a synonym for `.short'; depending on the target
-architecture, it may also be a synonym for `.word'.
-
-\1f
-File: as.info, Node: Ident, Next: If, Prev: hword, Up: Pseudo Ops
-
-7.58 `.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, `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 `.comment' or `.rdata' section, depending on the target. When
-using ELF, comments are emitted to the `.comment' section.
-
-\1f
-File: as.info, Node: If, Next: Incbin, Prev: Ident, Up: Pseudo Ops
-
-7.59 `.if ABSOLUTE EXPRESSION'
-==============================
-
-`.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 ABSOLUTE EXPRESSION) is non-zero. The end of the conditional
-section of code must be marked by `.endif' (*note `.endif': Endif.);
-optionally, you may include code for the alternative condition, flagged
-by `.else' (*note `.else': Else.). If you have several conditions to
-check, `.elseif' may be used to avoid nesting blocks if/else within
-each subsequent `.else' block.
-
- The following variants of `.if' are also supported:
-`.ifdef SYMBOL'
- Assembles the following section of code if the specified SYMBOL
- has been defined. Note a symbol which has been referenced but not
- yet defined is considered to be undefined.
-
-`.ifb TEXT'
- Assembles the following section of code if the operand is blank
- (empty).
-
-`.ifc STRING1,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.
-
-`.ifeq ABSOLUTE EXPRESSION'
- Assembles the following section of code if the argument is zero.
-
-`.ifeqs STRING1,STRING2'
- Another form of `.ifc'. The strings must be quoted using double
- quotes.
-
-`.ifge ABSOLUTE EXPRESSION'
- Assembles the following section of code if the argument is greater
- than or equal to zero.
-
-`.ifgt ABSOLUTE EXPRESSION'
- Assembles the following section of code if the argument is greater
- than zero.
-
-`.ifle ABSOLUTE EXPRESSION'
- Assembles the following section of code if the argument is less
- than or equal to zero.
-
-`.iflt ABSOLUTE EXPRESSION'
- Assembles the following section of code if the argument is less
- than zero.
-
-`.ifnb TEXT'
- Like `.ifb', but the sense of the test is reversed: this assembles
- the following section of code if the operand is non-blank
- (non-empty).
-
-`.ifnc STRING1,STRING2.'
- Like `.ifc', but the sense of the test is reversed: this assembles
- the following section of code if the two strings are not the same.
-
-`.ifndef SYMBOL'
-`.ifnotdef SYMBOL'
- Assembles the following section of code if the specified 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.
-
-`.ifne ABSOLUTE EXPRESSION'
- Assembles the following section of code if the argument is not
- equal to zero (in other words, this is equivalent to `.if').
-
-`.ifnes STRING1,STRING2'
- Like `.ifeqs', but the sense of the test is reversed: this
- assembles the following section of code if the two strings are not
- the same.
-
-\1f
-File: as.info, Node: Incbin, Next: Include, Prev: If, Up: Pseudo Ops
-
-7.60 `.incbin "FILE"[,SKIP[,COUNT]]'
-====================================
-
-The `incbin' directive includes FILE verbatim at the current location.
-You can control the search paths used with the `-I' command-line option
-(*note Command-Line Options: Invoking.). Quotation marks are required
-around FILE.
-
- The SKIP argument skips a number of bytes from the start of the
-FILE. The 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 `incbin' directive.
-
-\1f
-File: as.info, Node: Include, Next: Int, Prev: Incbin, Up: Pseudo Ops
-
-7.61 `.include "FILE"'
-======================
-
-This directive provides a way to include supporting files at specified
-points in your source program. The code from FILE is assembled as if
-it followed the point of the `.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 `-I' command-line option (*note
-Command-Line Options: Invoking.). Quotation marks are required around
-FILE.
-
-\1f
-File: as.info, Node: Int, Next: Internal, Prev: Include, Up: Pseudo Ops
-
-7.62 `.int EXPRESSIONS'
-=======================
-
-Expect zero or more 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.
-
-\1f
-File: as.info, Node: Internal, Next: Irp, Prev: Int, Up: Pseudo Ops
-
-7.63 `.internal NAMES'
-======================
-
-This is one of the ELF visibility directives. The other two are
-`.hidden' (*note `.hidden': Hidden.) and `.protected' (*note
-`.protected': Protected.).
-
- This directive overrides the named symbols default visibility (which
-is set by their binding: local, global or weak). The directive sets
-the visibility to `internal' which means that the symbols are
-considered to be `hidden' (i.e., not visible to other components), and
-that some extra, processor specific processing must also be performed
-upon the symbols as well.
-
-\1f
-File: as.info, Node: Irp, Next: Irpc, Prev: Internal, Up: Pseudo Ops
-
-7.64 `.irp SYMBOL,VALUES'...
-============================
-
-Evaluate a sequence of statements assigning different values to SYMBOL.
-The sequence of statements starts at the `.irp' directive, and is
-terminated by an `.endr' directive. For each VALUE, SYMBOL is set to
-VALUE, and the sequence of statements is assembled. If no VALUE is
-listed, the sequence of statements is assembled once, with SYMBOL set
-to the null string. To refer to SYMBOL within the sequence of
-statements, use \SYMBOL.
-
- For example, assembling
-
- .irp param,1,2,3
- move d\param,sp@-
- .endr
-
- is equivalent to assembling
-
- move d1,sp@-
- move d2,sp@-
- move d3,sp@-
-
- For some caveats with the spelling of SYMBOL, see also *Note Macro::.
-
-\1f
-File: as.info, Node: Irpc, Next: Lcomm, Prev: Irp, Up: Pseudo Ops
-
-7.65 `.irpc SYMBOL,VALUES'...
-=============================
-
-Evaluate a sequence of statements assigning different values to SYMBOL.
-The sequence of statements starts at the `.irpc' directive, and is
-terminated by an `.endr' directive. For each character in VALUE,
-SYMBOL is set to the character, and the sequence of statements is
-assembled. If no VALUE is listed, the sequence of statements is
-assembled once, with SYMBOL set to the null string. To refer to SYMBOL
-within the sequence of statements, use \SYMBOL.
-
- For example, assembling
-
- .irpc param,123
- move d\param,sp@-
- .endr
-
- is equivalent to assembling
-
- move d1,sp@-
- move d2,sp@-
- move d3,sp@-
-
- For some caveats with the spelling of SYMBOL, see also the discussion
-at *Note Macro::.
-
-\1f
-File: as.info, Node: Lcomm, Next: Lflags, Prev: Irpc, Up: Pseudo Ops
-
-7.66 `.lcomm SYMBOL , LENGTH'
-=============================
-
-Reserve LENGTH (an absolute expression) bytes for a local common
-denoted by SYMBOL. The section and value of 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. SYMBOL is not declared
-global (*note `.global': Global.), so is normally not visible to `ld'.
-
- Some targets permit a third argument to be used with `.lcomm'. This
-argument specifies the desired alignment of the symbol in the bss
-section.
-
- The syntax for `.lcomm' differs slightly on the HPPA. The syntax is
-`SYMBOL .lcomm, LENGTH'; SYMBOL is optional.
-
-\1f
-File: as.info, Node: Lflags, Next: Line, Prev: Lcomm, Up: Pseudo Ops
-
-7.67 `.lflags'
-==============
-
-`as' accepts this directive, for compatibility with other assemblers,
-but ignores it.
-
-\1f
-File: as.info, Node: Line, Next: Linkonce, Prev: Lflags, Up: Pseudo Ops
-
-7.68 `.line LINE-NUMBER'
-========================
-
- Change the logical line number. LINE-NUMBER must be an absolute
-expression. The next line has that logical line number. Therefore any
-other statements on the current line (after a statement separator
-character) are reported as on logical line number LINE-NUMBER - 1. One
-day `as' will no longer support this directive: it is recognized only
-for compatibility with existing assembler programs.
-
- Even though this is a directive associated with the `a.out' or
-`b.out' object-code formats, `as' still recognizes it when producing
-COFF output, and treats `.line' as though it were the COFF `.ln' _if_
-it is found outside a `.def'/`.endef' pair.
-
- Inside a `.def', `.line' is, instead, one of the directives used by
-compilers to generate auxiliary symbol information for debugging.
-
-\1f
-File: as.info, Node: Linkonce, Next: List, Prev: Line, Up: Pseudo Ops
-
-7.69 `.linkonce [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 `.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.
-
- 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.
-
- The TYPE argument is optional. If specified, it must be one of the
-following strings. For example:
- .linkonce same_size
- Not all types may be supported on all object file formats.
-
-`discard'
- Silently discard duplicate sections. This is the default.
-
-`one_only'
- Warn if there are duplicate sections, but still keep only one copy.
-
-`same_size'
- Warn if any of the duplicates have different sizes.
-
-`same_contents'
- Warn if any of the duplicates do not have exactly the same
- contents.
-
-\1f
-File: as.info, Node: Ln, Next: LNS directives, Prev: List, Up: Pseudo Ops
-
-7.70 `.ln LINE-NUMBER'
-======================
-
-`.ln' is a synonym for `.line'.
-
-\1f
-File: as.info, Node: MRI, Next: Noaltmacro, Prev: Macro, Up: Pseudo Ops
-
-7.71 `.mri VAL'
-===============
-
-If VAL is non-zero, this tells `as' to enter MRI mode. If VAL is zero,
-this tells `as' to exit MRI mode. This change affects code assembled
-until the next `.mri' directive, or until the end of the file. *Note
-MRI mode: M.
-
-\1f
-File: as.info, Node: List, Next: Ln, Prev: Linkonce, Up: Pseudo Ops
-
-7.72 `.list'
-============
-
-Control (in conjunction with the `.nolist' directive) whether or not
-assembly listings are generated. These two directives maintain an
-internal counter (which is zero initially). `.list' increments the
-counter, and `.nolist' decrements it. Assembly listings are generated
-whenever the counter is greater than zero.
-
- By default, listings are disabled. When you enable them (with the
-`-a' command line option; *note Command-Line Options: Invoking.), the
-initial value of the listing counter is one.
-
-\1f
-File: as.info, Node: Long, Next: Macro, Prev: LNS directives, Up: Pseudo Ops
-
-7.73 `.long EXPRESSIONS'
-========================
-
-`.long' is the same as `.int'. *Note `.int': Int.
-
-\1f
-File: as.info, Node: Macro, Next: MRI, Prev: Long, Up: Pseudo Ops
-
-7.74 `.macro'
-=============
-
-The commands `.macro' and `.endm' allow you to define macros that
-generate assembly output. For example, this definition specifies a
-macro `sum' that puts a sequence of numbers into memory:
-
- .macro sum from=0, to=5
- .long \from
- .if \to-\from
- sum "(\from+1)",\to
- .endif
- .endm
-
-With that definition, `SUM 0,5' is equivalent to this assembly input:
-
- .long 0
- .long 1
- .long 2
- .long 3
- .long 4
- .long 5
-
-`.macro MACNAME'
-`.macro MACNAME MACARGS ...'
- Begin the definition of a macro called 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 `:`req''), or whether it takes all of the
- remaining arguments (through `:`vararg''). You can supply a
- default value for any macro argument by following the name with
- `=DEFLT'. You cannot define two macros with the same MACNAME
- unless it has been subject to the `.purgem' directive (*note
- Purgem::) between the two definitions. For example, these are all
- valid `.macro' statements:
-
- `.macro comm'
- Begin the definition of a macro called `comm', which takes no
- arguments.
-
- `.macro plus1 p, p1'
- `.macro plus1 p p1'
- Either statement begins the definition of a macro called
- `plus1', which takes two arguments; within the macro
- definition, write `\p' or `\p1' to evaluate the arguments.
-
- `.macro reserve_str p1=0 p2'
- Begin the definition of a macro called `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 `reserve_str A,B' (with `\p1' evaluating
- to A and `\p2' evaluating to B), or as `reserve_str ,B' (with
- `\p1' evaluating as the default, in this case `0', and `\p2'
- evaluating to B).
-
- `.macro m p1:req, p2=0, p3:vararg'
- Begin the definition of a macro called `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.
-
- When you call a macro, you can specify the argument values
- either by position, or by keyword. For example, `sum 9,17'
- is equivalent to `sum to=17, from=9'.
-
-
- Note that since each of the 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 (`:') 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:
-
- .macro label l
- \l:
- .endm
-
- might not work as expected. Invoking `label foo' might not create
- a label called `foo' but instead just insert the text `\l:' into
- the assembler source, probably generating an error about an
- unrecognised identifier.
-
- Similarly problems might occur with the period character (`.')
- 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:
-
- .macro opcode base length
- \base.\length
- .endm
-
- and invoking it as `opcode store l' will not create a `store.l'
- instruction but instead generate some kind of error as the
- assembler tries to interpret the text `\base.\length'.
-
- There are several possible ways around this problem:
-
- `Insert white space'
- If it is possible to use white space characters then this is
- the simplest solution. eg:
-
- .macro label l
- \l :
- .endm
-
- `Use `\()''
- The string `\()' can be used to separate the end of a macro
- argument from the following text. eg:
-
- .macro opcode base length
- \base\().\length
- .endm
-
- `Use the alternate macro syntax mode'
- In the alternative macro syntax mode the ampersand character
- (`&') can be used as a separator. eg:
-
- .altmacro
- .macro label l
- l&:
- .endm
-
- Note: this problem of correctly identifying string parameters to
- pseudo ops also applies to the identifiers used in `.irp' (*note
- Irp::) and `.irpc' (*note Irpc::) as well.
-
-`.endm'
- Mark the end of a macro definition.
-
-`.exitm'
- Exit early from the current macro definition.
-
-`\@'
- `as' maintains a counter of how many macros it has executed in
- this pseudo-variable; you can copy that number to your output with
- `\@', but _only within a macro definition_.
-
-`LOCAL NAME [ , ... ]'
- _Warning: `LOCAL' is only available if you select "alternate macro
- syntax" with `--alternate' or `.altmacro'._ *Note `.altmacro':
- Altmacro.
-
-\1f
-File: as.info, Node: Altmacro, Next: Ascii, Prev: Align, Up: Pseudo Ops
-
-7.75 `.altmacro'
-================
-
-Enable alternate macro mode, enabling:
-
-`LOCAL NAME [ , ... ]'
- One additional directive, `LOCAL', is available. It is used to
- generate a string replacement for each of the NAME arguments, and
- replace any instances of NAME in each macro expansion. The
- replacement string is unique in the assembly, and different for
- each separate macro expansion. `LOCAL' allows you to write macros
- that define symbols, without fear of conflict between separate
- macro expansions.
-
-`String delimiters'
- You can write strings delimited in these other ways besides
- `"STRING"':
-
- `'STRING''
- You can delimit strings with single-quote characters.
-
- `<STRING>'
- You can delimit strings with matching angle brackets.
-
-`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 `!' (an exclamation mark). For example,
- you can write `<4.3 !> 5.4!!>' to get the literal text `4.3 >
- 5.4!'.
-
-`Expression results as strings'
- You can write `%EXPR' to evaluate the expression EXPR and use the
- result as a string.
-
-\1f
-File: as.info, Node: Noaltmacro, Next: Nolist, Prev: MRI, Up: Pseudo Ops
-
-7.76 `.noaltmacro'
-==================
-
-Disable alternate macro mode. *Note Altmacro::.
-
-\1f
-File: as.info, Node: Nolist, Next: Octa, Prev: Noaltmacro, Up: Pseudo Ops
-
-7.77 `.nolist'
-==============
-
-Control (in conjunction with the `.list' directive) whether or not
-assembly listings are generated. These two directives maintain an
-internal counter (which is zero initially). `.list' increments the
-counter, and `.nolist' decrements it. Assembly listings are generated
-whenever the counter is greater than zero.
-
-\1f
-File: as.info, Node: Octa, Next: Org, Prev: Nolist, Up: Pseudo Ops
-
-7.78 `.octa BIGNUMS'
-====================
-
-This directive expects zero or more bignums, separated by commas. For
-each bignum, it emits a 16-byte integer.
-
- The term "octa" comes from contexts in which a "word" is two bytes;
-hence _octa_-word for 16 bytes.
-
-\1f
-File: as.info, Node: Org, Next: P2align, Prev: Octa, Up: Pseudo Ops
-
-7.79 `.org NEW-LC , FILL'
-=========================
-
-Advance the location counter of the current section to NEW-LC. NEW-LC
-is either an absolute expression or an expression with the same section
-as the current subsection. That is, you can't use `.org' to cross
-sections: if NEW-LC has the wrong section, the `.org' directive is
-ignored. To be compatible with former assemblers, if the section of
-NEW-LC is absolute, `as' issues a warning, then pretends the section of
-NEW-LC is the same as the current subsection.
-
- `.org' may only increase the location counter, or leave it
-unchanged; you cannot use `.org' to move the location counter backwards.
-
- Because `as' tries to assemble programs in one pass, NEW-LC may not
-be undefined. If you really detest this restriction we eagerly await a
-chance to share your improved assembler.
-
- 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.
-
- When the location counter (of the current subsection) is advanced,
-the intervening bytes are filled with FILL which should be an absolute
-expression. If the comma and FILL are omitted, FILL defaults to zero.
-
-\1f
-File: as.info, Node: P2align, Next: PopSection, Prev: Org, Up: Pseudo Ops
-
-7.80 `.p2align[wl] ABS-EXPR, ABS-EXPR, 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 `.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.
-
- 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.
-
- 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.
-
- The `.p2alignw' and `.p2alignl' directives are variants of the
-`.p2align' directive. The `.p2alignw' directive treats the fill
-pattern as a two byte word value. The `.p2alignl' directives treats the
-fill pattern as a four byte longword value. For example, `.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.
-
-\1f
-File: as.info, Node: Previous, Next: Print, Prev: PopSection, Up: Pseudo Ops
-
-7.81 `.previous'
-================
-
-This is one of the ELF section stack manipulation directives. The
-others are `.section' (*note Section::), `.subsection' (*note
-SubSection::), `.pushsection' (*note PushSection::), and `.popsection'
-(*note PopSection::).
-
- This directive swaps the current section (and subsection) with most
-recently referenced section (and subsection) prior to this one.
-Multiple `.previous' directives in a row will flip between two sections
-(and their subsections).
-
- In terms of the section stack, this directive swaps the current
-section with the top section on the section stack.
-
-\1f
-File: as.info, Node: PopSection, Next: Previous, Prev: P2align, Up: Pseudo Ops
-
-7.82 `.popsection'
-==================
-
-This is one of the ELF section stack manipulation directives. The
-others are `.section' (*note Section::), `.subsection' (*note
-SubSection::), `.pushsection' (*note PushSection::), and `.previous'
-(*note Previous::).
-
- 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.
-
-\1f
-File: as.info, Node: Print, Next: Protected, Prev: Previous, Up: Pseudo Ops
-
-7.83 `.print STRING'
-====================
-
-`as' will print STRING on the standard output during assembly. You
-must put STRING in double quotes.
-
-\1f
-File: as.info, Node: Protected, Next: Psize, Prev: Print, Up: Pseudo Ops
-
-7.84 `.protected NAMES'
-=======================
-
-This is one of the ELF visibility directives. The other two are
-`.hidden' (*note Hidden::) and `.internal' (*note Internal::).
-
- This directive overrides the named symbols default visibility (which
-is set by their binding: local, global or weak). The directive sets
-the visibility to `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.
-
-\1f
-File: as.info, Node: Psize, Next: Purgem, Prev: Protected, Up: Pseudo Ops
-
-7.85 `.psize LINES , COLUMNS'
-=============================
-
-Use this directive to declare the number of lines--and, optionally, the
-number of columns--to use for each page, when generating listings.
-
- If you do not use `.psize', listings use a default line-count of 60.
-You may omit the comma and COLUMNS specification; the default width is
-200 columns.
-
- `as' generates formfeeds whenever the specified number of lines is
-exceeded (or whenever you explicitly request one, using `.eject').
-
- If you specify LINES as `0', no formfeeds are generated save those
-explicitly specified with `.eject'.
-
-\1f
-File: as.info, Node: Purgem, Next: PushSection, Prev: Psize, Up: Pseudo Ops
-
-7.86 `.purgem NAME'
-===================
-
-Undefine the macro NAME, so that later uses of the string will not be
-expanded. *Note Macro::.
-
-\1f
-File: as.info, Node: PushSection, Next: Quad, Prev: Purgem, Up: Pseudo Ops
-
-7.87 `.pushsection NAME , SUBSECTION'
-=====================================
-
-This is one of the ELF section stack manipulation directives. The
-others are `.section' (*note Section::), `.subsection' (*note
-SubSection::), `.popsection' (*note PopSection::), and `.previous'
-(*note Previous::).
-
- This directive pushes the current section (and subsection) onto the
-top of the section stack, and then replaces the current section and
-subsection with `name' and `subsection'.
-
-\1f
-File: as.info, Node: Quad, Next: Reloc, Prev: PushSection, Up: Pseudo Ops
-
-7.88 `.quad BIGNUMS'
-====================
-
-`.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.
-
- The term "quad" comes from contexts in which a "word" is two bytes;
-hence _quad_-word for 8 bytes.
-
-\1f
-File: as.info, Node: Reloc, Next: Rept, Prev: Quad, Up: Pseudo Ops
-
-7.89 `.reloc OFFSET, RELOC_NAME[, EXPRESSION]'
-==============================================
-
-Generate a relocation at OFFSET of type RELOC_NAME with value
-EXPRESSION. If OFFSET is a number, the relocation is generated in the
-current section. If OFFSET is an expression that resolves to a symbol
-plus offset, the relocation is generated in the given symbol's section.
-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.
-
-\1f
-File: as.info, Node: Rept, Next: Sbttl, Prev: Reloc, Up: Pseudo Ops
-
-7.90 `.rept COUNT'
-==================
-
-Repeat the sequence of lines between the `.rept' directive and the next
-`.endr' directive COUNT times.
-
- For example, assembling
-
- .rept 3
- .long 0
- .endr
-
- is equivalent to assembling
-
- .long 0
- .long 0
- .long 0
-
-\1f
-File: as.info, Node: Sbttl, Next: Scl, Prev: Rept, Up: Pseudo Ops
-
-7.91 `.sbttl "SUBHEADING"'
-==========================
-
-Use SUBHEADING as the title (third line, immediately after the title
-line) when generating assembly listings.
-
- This directive affects subsequent pages, as well as the current page
-if it appears within ten lines of the top of a page.
-
-\1f
-File: as.info, Node: Scl, Next: Section, Prev: Sbttl, Up: Pseudo Ops
-
-7.92 `.scl CLASS'
-=================
-
-Set the storage-class value for a symbol. This directive may only be
-used inside a `.def'/`.endef' pair. Storage class may flag whether a
-symbol is static or external, or it may record further symbolic
-debugging information.
-
-\1f
-File: as.info, Node: Section, Next: Set, Prev: Scl, Up: Pseudo Ops
-
-7.93 `.section NAME'
-====================
-
-Use the `.section' directive to assemble the following code into a
-section named NAME.
-
- This directive is only supported for targets that actually support
-arbitrarily named sections; on `a.out' targets, for example, it is not
-accepted, even with a standard `a.out' section name.
-
-COFF Version
-------------
-
- For COFF targets, the `.section' directive is used in one of the
-following ways:
-
- .section NAME[, "FLAGS"]
- .section NAME[, SUBSEGMENT]
-
- If the optional argument is quoted, it is taken as flags to use for
-the section. Each flag is a single character. The following flags are
-recognized:
-`b'
- bss section (uninitialized data)
-
-`n'
- section is not loaded
-
-`w'
- writable section
-
-`d'
- data section
-
-`r'
- read-only section
-
-`x'
- executable section
-
-`s'
- shared section (meaningful for PE targets)
-
-`a'
- ignored. (For compatibility with the ELF version)
-
- 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 be loaded and writable. Note the `n' and `w' flags
-remove attributes from the section, rather than adding them, so if they
-are used on their own it will be as if no flags had been specified at
-all.
-
- If the optional argument to the `.section' directive is not quoted,
-it is taken as a subsegment number (*note Sub-Sections::).
-
-ELF Version
------------
-
- This is one of the ELF section stack manipulation directives. The
-others are `.subsection' (*note SubSection::), `.pushsection' (*note
-PushSection::), `.popsection' (*note PopSection::), and `.previous'
-(*note Previous::).
-
- For ELF targets, the `.section' directive is used like this:
-
- .section NAME [, "FLAGS"[, @TYPE[,FLAG_SPECIFIC_ARGUMENTS]]]
-
- The optional FLAGS argument is a quoted string which may contain any
-combination of the following characters:
-`a'
- section is allocatable
-
-`w'
- section is writable
-
-`x'
- section is executable
-
-`M'
- section is mergeable
-
-`S'
- section contains zero terminated strings
-
-`G'
- section is a member of a section group
-
-`T'
- section is used for thread-local-storage
-
- The optional TYPE argument may contain one of the following
-constants:
-`@progbits'
- section contains data
-
-`@nobits'
- section does not contain data (i.e., section only occupies space)
-
-`@note'
- section contains data which is used by things other than the
- program
-
-`@init_array'
- section contains an array of pointers to init functions
-
-`@fini_array'
- section contains an array of pointers to finish functions
-
-`@preinit_array'
- section contains an array of pointers to pre-init functions
-
- Many targets only support the first three section types.
-
- Note on targets where the `@' character is the start of a comment (eg
-ARM) then another character is used instead. For example the ARM port
-uses the `%' character.
-
- If FLAGS contains the `M' symbol then the TYPE argument must be
-specified as well as an extra argument--ENTSIZE--like this:
-
- .section NAME , "FLAGS"M, @TYPE, ENTSIZE
-
- Sections with the `M' flag but not `S' flag must contain fixed size
-constants, each ENTSIZE octets long. Sections with both `M' and `S'
-must contain zero terminated strings where each character is ENTSIZE
-bytes long. The linker may remove duplicates within sections with the
-same name, same entity size and same flags. ENTSIZE must be an
-absolute expression.
-
- If FLAGS contains the `G' symbol then the TYPE argument must be
-present along with an additional field like this:
-
- .section NAME , "FLAGS"G, @TYPE, GROUPNAME[, LINKAGE]
-
- The GROUPNAME field specifies the name of the section group to which
-this particular section belongs. The optional linkage field can
-contain:
-`comdat'
- indicates that only one copy of this section should be retained
-
-`.gnu.linkonce'
- an alias for comdat
-
- Note: if both the M and G flags are present then the fields for the
-Merge flag should come first, like this:
-
- .section NAME , "FLAGS"MG, @TYPE, ENTSIZE, GROUPNAME[, LINKAGE]
-
- 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.
-
- For ELF targets, the assembler supports another type of `.section'
-directive for compatibility with the Solaris assembler:
-
- .section "NAME"[, FLAGS...]
-
- Note that the section name is quoted. There may be a sequence of
-comma separated flags:
-`#alloc'
- section is allocatable
-
-`#write'
- section is writable
-
-`#execinstr'
- section is executable
-
-`#tls'
- section is used for thread local storage
-
- This directive replaces the current section and subsection. See the
-contents of the gas testsuite directory `gas/testsuite/gas/elf' for
-some examples of how this directive and the other section stack
-directives work.
-
-\1f
-File: as.info, Node: Set, Next: Short, Prev: Section, Up: Pseudo Ops
-
-7.94 `.set SYMBOL, EXPRESSION'
-==============================
-
-Set the value of SYMBOL to EXPRESSION. This changes SYMBOL's value and
-type to conform to EXPRESSION. If SYMBOL was flagged as external, it
-remains flagged (*note Symbol Attributes::).
-
- You may `.set' a symbol many times in the same assembly.
-
- If you `.set' a global symbol, the value stored in the object file
-is the last value stored into it.
-
- The syntax for `set' on the HPPA is `SYMBOL .set EXPRESSION'.
-
- On Z80 `set' is a real instruction, use `SYMBOL defl EXPRESSION'
-instead.
-
-\1f
-File: as.info, Node: Short, Next: Single, Prev: Set, Up: Pseudo Ops
-
-7.95 `.short EXPRESSIONS'
-=========================
-
-`.short' is normally the same as `.word'. *Note `.word': Word.
-
- In some configurations, however, `.short' and `.word' generate
-numbers of different lengths. *Note Machine Dependencies::.
-
-\1f
-File: as.info, Node: Single, Next: Size, Prev: Short, Up: Pseudo Ops
-
-7.96 `.single FLONUMS'
-======================
-
-This directive assembles zero or more flonums, separated by commas. It
-has the same effect as `.float'. The exact kind of floating point
-numbers emitted depends on how `as' is configured. *Note Machine
-Dependencies::.
-
-\1f
-File: as.info, Node: Size, Next: Skip, Prev: Single, Up: Pseudo Ops
-
-7.97 `.size'
-============
-
-This directive is used to set the size associated with a symbol.
-
-COFF Version
-------------
-
- For COFF targets, the `.size' directive is only permitted inside
-`.def'/`.endef' pairs. It is used like this:
-
- .size EXPRESSION
-
-ELF Version
------------
-
- For ELF targets, the `.size' directive is used like this:
-
- .size NAME , EXPRESSION
-
- This directive sets the size associated with a symbol NAME. The
-size in bytes is computed from EXPRESSION which can make use of label
-arithmetic. This directive is typically used to set the size of
-function symbols.
-
-\1f
-File: as.info, Node: Sleb128, Next: Space, Prev: Skip, Up: Pseudo Ops
-
-7.98 `.sleb128 EXPRESSIONS'
-===========================
-
-SLEB128 stands for "signed little endian base 128." This is a compact,
-variable length representation of numbers used by the DWARF symbolic
-debugging format. *Note `.uleb128': Uleb128.
-
-\1f
-File: as.info, Node: Skip, Next: Sleb128, Prev: Size, Up: Pseudo Ops
-
-7.99 `.skip SIZE , FILL'
-========================
-
-This directive emits SIZE bytes, each of value FILL. Both SIZE and
-FILL are absolute expressions. If the comma and FILL are omitted, FILL
-is assumed to be zero. This is the same as `.space'.
-
-\1f
-File: as.info, Node: Space, Next: Stab, Prev: Sleb128, Up: Pseudo Ops
-
-7.100 `.space SIZE , FILL'
-==========================
-
-This directive emits SIZE bytes, each of value FILL. Both SIZE and
-FILL are absolute expressions. If the comma and FILL are omitted, FILL
-is assumed to be zero. This is the same as `.skip'.
-
- _Warning:_ `.space' has a completely different meaning for HPPA
- targets; use `.block' as a substitute. See `HP9000 Series 800
- Assembly Language Reference Manual' (HP 92432-90001) for the
- meaning of the `.space' directive. *Note HPPA Assembler
- Directives: HPPA Directives, for a summary.
-
-\1f
-File: as.info, Node: Stab, Next: String, Prev: Space, Up: Pseudo Ops
-
-7.101 `.stabd, .stabn, .stabs'
-==============================
-
-There are three directives that begin `.stab'. All emit symbols (*note
-Symbols::), for use by symbolic debuggers. The symbols are not entered
-in the `as' hash table: they cannot be referenced elsewhere in the
-source file. Up to five fields are required:
-
-STRING
- This is the symbol's name. It may contain any character except
- `\000', so is more general than ordinary symbol names. Some
- debuggers used to code arbitrarily complex structures into symbol
- names using this field.
-
-TYPE
- An absolute expression. The symbol's type is set to the low 8
- bits of this expression. Any bit pattern is permitted, but `ld'
- and debuggers choke on silly bit patterns.
-
-OTHER
- An absolute expression. The symbol's "other" attribute is set to
- the low 8 bits of this expression.
-
-DESC
- An absolute expression. The symbol's descriptor is set to the low
- 16 bits of this expression.
-
-VALUE
- An absolute expression which becomes the symbol's value.
-
- If a warning is detected while reading a `.stabd', `.stabn', or
-`.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!
-
-`.stabd TYPE , OTHER , DESC'
- The "name" 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.
-
- 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 `.stabd' was assembled.
-
-`.stabn TYPE , OTHER , DESC , VALUE'
- The name of the symbol is set to the empty string `""'.
-
-`.stabs STRING , TYPE , OTHER , DESC , VALUE'
- All five fields are specified.
-
-\1f
-File: as.info, Node: String, Next: Struct, Prev: Stab, Up: Pseudo Ops
-
-7.102 `.string' "STR"
-=====================
-
-Copy the characters in 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 *Note Strings: Strings.
-
-\1f
-File: as.info, Node: Struct, Next: SubSection, Prev: String, Up: Pseudo Ops
-
-7.103 `.struct EXPRESSION'
-==========================
-
-Switch to the absolute section, and set the section offset to
-EXPRESSION, which must be an absolute expression. You might use this
-as follows:
- .struct 0
- field1:
- .struct field1 + 4
- field2:
- .struct field2 + 4
- field3:
- This would define the symbol `field1' to have the value 0, the symbol
-`field2' to have the value 4, and the symbol `field3' to have the value
-8. Assembly would be left in the absolute section, and you would need
-to use a `.section' directive of some sort to change to some other
-section before further assembly.
-
-\1f
-File: as.info, Node: SubSection, Next: Symver, Prev: Struct, Up: Pseudo Ops
-
-7.104 `.subsection NAME'
-========================
-
-This is one of the ELF section stack manipulation directives. The
-others are `.section' (*note Section::), `.pushsection' (*note
-PushSection::), `.popsection' (*note PopSection::), and `.previous'
-(*note Previous::).
-
- This directive replaces the current subsection with `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.
-
-\1f
-File: as.info, Node: Symver, Next: Tag, Prev: SubSection, Up: Pseudo Ops
-
-7.105 `.symver'
-===============
-
-Use the `.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.
-
- For ELF targets, the `.symver' directive can be used like this:
- .symver NAME, NAME2@NODENAME
- If the symbol NAME is defined within the file being assembled, the
-`.symver' directive effectively creates a symbol alias with the name
-NAME2@NODENAME, and in fact the main reason that we just don't try and
-create a regular alias is that the @ character isn't permitted in
-symbol names. The NAME2 part of the name is the actual name of the
-symbol by which it will be externally referenced. The name 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 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
-NODENAME should correspond to the nodename of the symbol you are trying
-to override.
-
- If the symbol NAME is not defined within the file being assembled,
-all references to NAME will be changed to NAME2@NODENAME. If no
-reference to NAME is made, NAME2@NODENAME will be removed from the
-symbol table.
-
- Another usage of the `.symver' directive is:
- .symver NAME, NAME2@@NODENAME
- In this case, the symbol NAME must exist and be defined within the
-file being assembled. It is similar to NAME2@NODENAME. The difference
-is NAME2@@NODENAME will also be used to resolve references to NAME2 by
-the linker.
-
- The third usage of the `.symver' directive is:
- .symver NAME, NAME2@@@NODENAME
- When NAME is not defined within the file being assembled, it is
-treated as NAME2@NODENAME. When NAME is defined within the file being
-assembled, the symbol name, NAME, will be changed to NAME2@@NODENAME.
-
-\1f
-File: as.info, Node: Tag, Next: Text, Prev: Symver, Up: Pseudo Ops
-
-7.106 `.tag STRUCTNAME'
-=======================
-
-This directive is generated by compilers to include auxiliary debugging
-information in the symbol table. It is only permitted inside
-`.def'/`.endef' pairs. Tags are used to link structure definitions in
-the symbol table with instances of those structures.
-
-\1f
-File: as.info, Node: Text, Next: Title, Prev: Tag, Up: Pseudo Ops
-
-7.107 `.text SUBSECTION'
-========================
-
-Tells `as' to assemble the following statements onto the end of the
-text subsection numbered SUBSECTION, which is an absolute expression.
-If SUBSECTION is omitted, subsection number zero is used.
-
-\1f
-File: as.info, Node: Title, Next: Type, Prev: Text, Up: Pseudo Ops
-
-7.108 `.title "HEADING"'
-========================
-
-Use HEADING as the title (second line, immediately after the source
-file name and pagenumber) when generating assembly listings.
-
- This directive affects subsequent pages, as well as the current page
-if it appears within ten lines of the top of a page.
-
-\1f
-File: as.info, Node: Type, Next: Uleb128, Prev: Title, Up: Pseudo Ops
-
-7.109 `.type'
-=============
-
-This directive is used to set the type of a symbol.
-
-COFF Version
-------------
-
- For COFF targets, this directive is permitted only within
-`.def'/`.endef' pairs. It is used like this:
-
- .type INT
-
- This records the integer INT as the type attribute of a symbol table
-entry.
-
-ELF Version
------------
-
- For ELF targets, the `.type' directive is used like this:
-
- .type NAME , TYPE DESCRIPTION
-
- This sets the type of symbol NAME to be either a function symbol or
-an object symbol. There are five different syntaxes supported for the
-TYPE DESCRIPTION field, in order to provide compatibility with various
-other assemblers.
-
- Because some of the characters used in these syntaxes (such as `@'
-and `#') 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.
-
- The syntaxes supported are:
-
- .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"
-
-\1f
-File: as.info, Node: Uleb128, Next: Val, Prev: Type, Up: Pseudo Ops
-
-7.110 `.uleb128 EXPRESSIONS'
-============================
-
-ULEB128 stands for "unsigned little endian base 128." This is a
-compact, variable length representation of numbers used by the DWARF
-symbolic debugging format. *Note `.sleb128': Sleb128.
-
-\1f
-File: as.info, Node: Val, Next: Version, Prev: Uleb128, Up: Pseudo Ops
-
-7.111 `.val ADDR'
-=================
-
-This directive, permitted only within `.def'/`.endef' pairs, records
-the address ADDR as the value attribute of a symbol table entry.
-
-\1f
-File: as.info, Node: Version, Next: VTableEntry, Prev: Val, Up: Pseudo Ops
-
-7.112 `.version "STRING"'
-=========================
-
-This directive creates a `.note' section and places into it an ELF
-formatted note of type NT_VERSION. The note's name is set to `string'.
-
-\1f
-File: as.info, Node: VTableEntry, Next: VTableInherit, Prev: Version, Up: Pseudo Ops
-
-7.113 `.vtable_entry TABLE, OFFSET'
-===================================
-
-This directive finds or creates a symbol `table' and creates a
-`VTABLE_ENTRY' relocation for it with an addend of `offset'.
-
-\1f
-File: as.info, Node: VTableInherit, Next: Warning, Prev: VTableEntry, Up: Pseudo Ops
-
-7.114 `.vtable_inherit CHILD, PARENT'
-=====================================
-
-This directive finds the symbol `child' and finds or creates the symbol
-`parent' and then creates a `VTABLE_INHERIT' relocation for the parent
-whose addend is the value of the child symbol. As a special case the
-parent name of `0' is treated as referring to the `*ABS*' section.
-
-\1f
-File: as.info, Node: Warning, Next: Weak, Prev: VTableInherit, Up: Pseudo Ops
-
-7.115 `.warning "STRING"'
-=========================
-
-Similar to the directive `.error' (*note `.error "STRING"': Error.),
-but just emits a warning.
-
-\1f
-File: as.info, Node: Weak, Next: Weakref, Prev: Warning, Up: Pseudo Ops
-
-7.116 `.weak NAMES'
-===================
-
-This directive sets the weak attribute on the comma separated list of
-symbol `names'. If the symbols do not already exist, they will be
-created.
-
- 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 `names'. If the symbols do not already exist, they will be
-created.
-
- 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.
-
-\1f
-File: as.info, Node: Weakref, Next: Word, Prev: Weak, Up: Pseudo Ops
-
-7.117 `.weakref ALIAS, 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.
-
- 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.
-
- The alias itself never makes to the symbol table, and is entirely
-handled within the assembler.
-
-\1f
-File: as.info, Node: Word, Next: Deprecated, Prev: Weakref, Up: Pseudo Ops
-
-7.118 `.word EXPRESSIONS'
-=========================
-
-This directive expects zero or more EXPRESSIONS, of any section,
-separated by commas.
-
- The size of the number emitted, and its byte order, depend on what
-target computer the assembly is for.
-
- _Warning: Special Treatment to support Compilers_
-
- Machines with a 32-bit address space, but that do less than 32-bit
-addressing, require the following special treatment. If the machine of
-interest to you does 32-bit addressing (or doesn't require it; *note
-Machine Dependencies::), you can ignore this issue.
-
- In order to assemble compiler output into something that works, `as'
-occasionally does strange things to `.word' directives. Directives of
-the form `.word sym1-sym2' are often emitted by compilers as part of
-jump tables. Therefore, when `as' assembles a directive of the form
-`.word sym1-sym2', and the difference between `sym1' and `sym2' does
-not fit in 16 bits, `as' creates a "secondary jump table", immediately
-before the next label. This secondary jump table is preceded by a
-short-jump to the first byte after the secondary table. This
-short-jump prevents the flow of control from accidentally falling into
-the new table. Inside the table is a long-jump to `sym2'. The
-original `.word' contains `sym1' minus the address of the long-jump to
-`sym2'.
-
- If there were several occurrences of `.word sym1-sym2' before the
-secondary jump table, all of them are adjusted. If there was a `.word
-sym3-sym4', that also did not fit in sixteen bits, a long-jump to
-`sym4' is included in the secondary jump table, and the `.word'
-directives are adjusted to contain `sym3' minus the address of the
-long-jump to `sym4'; and so on, for as many entries in the original
-jump table as necessary.
-
-\1f
-File: as.info, Node: Deprecated, Prev: Word, Up: Pseudo Ops
-
-7.119 Deprecated Directives
-===========================
-
-One day these directives won't work. They are included for
-compatibility with older assemblers.
-.abort
-
-.line
-
-\1f
-File: as.info, Node: Machine Dependencies, Next: Reporting Bugs, Prev: Pseudo Ops, Up: Top
-
-8 Machine Dependent Features
-****************************
-
-The machine instruction sets are (almost by definition) different on
-each machine where `as' runs. Floating point representations vary as
-well, and `as' often supports a few additional directives or
-command-line options for compatibility with other assemblers on a
-particular platform. Finally, some versions of `as' support special
-pseudo-instructions for branch optimization.
-
- This chapter discusses most of these differences, though it does not
-include details on any machine's instruction set. For details on that
-subject, see the hardware manufacturer's manual.
-
-* Menu:
-
-
-* Alpha-Dependent:: Alpha Dependent Features
-
-* ARC-Dependent:: ARC Dependent Features
-
-* ARM-Dependent:: ARM Dependent Features
-
-* AVR-Dependent:: AVR Dependent Features
-
-* BFIN-Dependent:: BFIN Dependent Features
-
-* CR16-Dependent:: CR16 Dependent Features
-
-* CRIS-Dependent:: CRIS Dependent Features
-
-* D10V-Dependent:: D10V Dependent Features
-
-* D30V-Dependent:: D30V Dependent Features
-
-* H8/300-Dependent:: Renesas H8/300 Dependent Features
-
-* HPPA-Dependent:: HPPA Dependent Features
-
-* ESA/390-Dependent:: IBM ESA/390 Dependent Features
-
-* i386-Dependent:: Intel 80386 and AMD x86-64 Dependent Features
-
-* i860-Dependent:: Intel 80860 Dependent Features
-
-* i960-Dependent:: Intel 80960 Dependent Features
-
-* IA-64-Dependent:: Intel IA-64 Dependent Features
-
-* IP2K-Dependent:: IP2K Dependent Features
-
-* M32C-Dependent:: M32C Dependent Features
-
-* M32R-Dependent:: M32R Dependent Features
-
-* M68K-Dependent:: M680x0 Dependent Features
-
-* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features
-
-* MIPS-Dependent:: MIPS Dependent Features
-
-* MMIX-Dependent:: MMIX Dependent Features
-
-* MSP430-Dependent:: MSP430 Dependent Features
-
-* SH-Dependent:: Renesas / SuperH SH Dependent Features
-* SH64-Dependent:: SuperH SH64 Dependent Features
-
-* PDP-11-Dependent:: PDP-11 Dependent Features
-
-* PJ-Dependent:: picoJava Dependent Features
-
-* PPC-Dependent:: PowerPC Dependent Features
-
-* Sparc-Dependent:: SPARC Dependent Features
-
-* TIC54X-Dependent:: TI TMS320C54x Dependent Features
-
-* V850-Dependent:: V850 Dependent Features
-
-* Xtensa-Dependent:: Xtensa Dependent Features
-
-* Z80-Dependent:: Z80 Dependent Features
-
-* Z8000-Dependent:: Z8000 Dependent Features
-
-* Vax-Dependent:: VAX Dependent Features
-
-\1f
-File: as.info, Node: Alpha-Dependent, Next: ARC-Dependent, Up: Machine Dependencies
-
-8.1 Alpha Dependent Features
-============================
-
-* Menu:
-
-* Alpha Notes:: Notes
-* Alpha Options:: Options
-* Alpha Syntax:: Syntax
-* Alpha Floating Point:: Floating Point
-* Alpha Directives:: Alpha Machine Directives
-* Alpha Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: Alpha Notes, Next: Alpha Options, Up: Alpha-Dependent
-
-8.1.1 Notes
------------
-
-The documentation here is primarily for the ELF object format. `as'
-also supports the ECOFF and EVAX formats, but features specific to
-these formats are not yet documented.
-
-\1f
-File: as.info, Node: Alpha Options, Next: Alpha Syntax, Prev: Alpha Notes, Up: Alpha-Dependent
-
-8.1.2 Options
--------------
-
-`-mCPU'
- This option specifies the target processor. If an attempt is made
- to assemble an instruction which will not execute on the target
- processor, the assembler may either expand the instruction as a
- macro or issue an error message. This option is equivalent to the
- `.arch' directive.
-
- The following processor names are recognized: `21064', `21064a',
- `21066', `21068', `21164', `21164a', `21164pc', `21264', `21264a',
- `21264b', `ev4', `ev5', `lca45', `ev5', `ev56', `pca56', `ev6',
- `ev67', `ev68'. The special name `all' may be used to allow the
- assembler to accept instructions valid for any Alpha processor.
-
- In order to support existing practice in OSF/1 with respect to
- `.arch', and existing practice within `MILO' (the Linux ARC
- bootloader), the numbered processor names (e.g. 21064) enable the
- processor-specific PALcode instructions, while the
- "electro-vlasic" names (e.g. `ev4') do not.
-
-`-mdebug'
-`-no-mdebug'
- Enables or disables the generation of `.mdebug' encapsulation for
- stabs directives and procedure descriptors. The default is to
- automatically enable `.mdebug' when the first stabs directive is
- seen.
-
-`-relax'
- This option forces all relocations to be put into the object file,
- instead of saving space and resolving some relocations at assembly
- time. Note that this option does not propagate all symbol
- arithmetic into the object file, because not all symbol arithmetic
- can be represented. However, the option can still be useful in
- specific applications.
-
-`-g'
- This option is used when the compiler generates debug information.
- When `gcc' is using `mips-tfile' to generate debug information
- for ECOFF, local labels must be passed through to the object file.
- Otherwise this option has no effect.
-
-`-GSIZE'
- A local common symbol larger than SIZE is placed in `.bss', while
- smaller symbols are placed in `.sbss'.
-
-`-F'
-`-32addr'
- These options are ignored for backward compatibility.
-
-\1f
-File: as.info, Node: Alpha Syntax, Next: Alpha Floating Point, Prev: Alpha Options, Up: Alpha-Dependent
-
-8.1.3 Syntax
-------------
-
-The assembler syntax closely follow the Alpha Reference Manual;
-assembler directives and general syntax closely follow the OSF/1 and
-OpenVMS syntax, with a few differences for ELF.
-
-* Menu:
-
-* Alpha-Chars:: Special Characters
-* Alpha-Regs:: Register Names
-* Alpha-Relocs:: Relocations
-
-\1f
-File: as.info, Node: Alpha-Chars, Next: Alpha-Regs, Up: Alpha Syntax
-
-8.1.3.1 Special Characters
-..........................
-
-`#' is the line comment character.
-
- `;' can be used instead of a newline to separate statements.
-
-\1f
-File: as.info, Node: Alpha-Regs, Next: Alpha-Relocs, Prev: Alpha-Chars, Up: Alpha Syntax
-
-8.1.3.2 Register Names
-......................
-
-The 32 integer registers are referred to as `$N' or `$rN'. In
-addition, registers 15, 28, 29, and 30 may be referred to by the
-symbols `$fp', `$at', `$gp', and `$sp' respectively.
-
- The 32 floating-point registers are referred to as `$fN'.
-
-\1f
-File: as.info, Node: Alpha-Relocs, Prev: Alpha-Regs, Up: Alpha Syntax
-
-8.1.3.3 Relocations
-...................
-
-Some of these relocations are available for ECOFF, but mostly only for
-ELF. They are modeled after the relocation format introduced in
-Digital Unix 4.0, but there are additions.
-
- The format is `!TAG' or `!TAG!NUMBER' where TAG is the name of the
-relocation. In some cases NUMBER is used to relate specific
-instructions.
-
- The relocation is placed at the end of the instruction like so:
-
- ldah $0,a($29) !gprelhigh
- lda $0,a($0) !gprellow
- ldq $1,b($29) !literal!100
- ldl $2,0($1) !lituse_base!100
-
-`!literal'
-`!literal!N'
- Used with an `ldq' instruction to load the address of a symbol
- from the GOT.
-
- A sequence number N is optional, and if present is used to pair
- `lituse' relocations with this `literal' relocation. The `lituse'
- relocations are used by the linker to optimize the code based on
- the final location of the symbol.
-
- Note that these optimizations are dependent on the data flow of the
- program. Therefore, if _any_ `lituse' is paired with a `literal'
- relocation, then _all_ uses of the register set by the `literal'
- instruction must also be marked with `lituse' relocations. This
- is because the original `literal' instruction may be deleted or
- transformed into another instruction.
-
- Also note that there may be a one-to-many relationship between
- `literal' and `lituse', but not a many-to-one. That is, if there
- are two code paths that load up the same address and feed the
- value to a single use, then the use may not use a `lituse'
- relocation.
-
-`!lituse_base!N'
- Used with any memory format instruction (e.g. `ldl') to indicate
- that the literal is used for an address load. The offset field of
- the instruction must be zero. During relaxation, the code may be
- altered to use a gp-relative load.
-
-`!lituse_jsr!N'
- Used with a register branch format instruction (e.g. `jsr') to
- indicate that the literal is used for a call. During relaxation,
- the code may be altered to use a direct branch (e.g. `bsr').
-
-`!lituse_jsrdirect!N'
- Similar to `lituse_jsr', but also that this call cannot be vectored
- through a PLT entry. This is useful for functions with special
- calling conventions which do not allow the normal call-clobbered
- registers to be clobbered.
-
-`!lituse_bytoff!N'
- Used with a byte mask instruction (e.g. `extbl') to indicate that
- only the low 3 bits of the address are relevant. During
- relaxation, the code may be altered to use an immediate instead of
- a register shift.
-
-`!lituse_addr!N'
- Used with any other instruction to indicate that the original
- address is in fact used, and the original `ldq' instruction may
- not be altered or deleted. This is useful in conjunction with
- `lituse_jsr' to test whether a weak symbol is defined.
-
- ldq $27,foo($29) !literal!1
- beq $27,is_undef !lituse_addr!1
- jsr $26,($27),foo !lituse_jsr!1
-
-`!lituse_tlsgd!N'
- Used with a register branch format instruction to indicate that the
- literal is the call to `__tls_get_addr' used to compute the
- address of the thread-local storage variable whose descriptor was
- loaded with `!tlsgd!N'.
-
-`!lituse_tlsldm!N'
- Used with a register branch format instruction to indicate that the
- literal is the call to `__tls_get_addr' used to compute the
- address of the base of the thread-local storage block for the
- current module. The descriptor for the module must have been
- loaded with `!tlsldm!N'.
-
-`!gpdisp!N'
- Used with `ldah' and `lda' to load the GP from the current
- address, a-la the `ldgp' macro. The source register for the
- `ldah' instruction must contain the address of the `ldah'
- instruction. There must be exactly one `lda' instruction paired
- with the `ldah' instruction, though it may appear anywhere in the
- instruction stream. The immediate operands must be zero.
-
- bsr $26,foo
- ldah $29,0($26) !gpdisp!1
- lda $29,0($29) !gpdisp!1
-
-`!gprelhigh'
- Used with an `ldah' instruction to add the high 16 bits of a
- 32-bit displacement from the GP.
-
-`!gprellow'
- Used with any memory format instruction to add the low 16 bits of a
- 32-bit displacement from the GP.
-
-`!gprel'
- Used with any memory format instruction to add a 16-bit
- displacement from the GP.
-
-`!samegp'
- Used with any branch format instruction to skip the GP load at the
- target address. The referenced symbol must have the same GP as the
- source object file, and it must be declared to either not use `$27'
- or perform a standard GP load in the first two instructions via the
- `.prologue' directive.
-
-`!tlsgd'
-`!tlsgd!N'
- Used with an `lda' instruction to load the address of a TLS
- descriptor for a symbol in the GOT.
-
- The sequence number N is optional, and if present it used to pair
- the descriptor load with both the `literal' loading the address of
- the `__tls_get_addr' function and the `lituse_tlsgd' marking the
- call to that function.
-
- For proper relaxation, both the `tlsgd', `literal' and `lituse'
- relocations must be in the same extended basic block. That is,
- the relocation with the lowest address must be executed first at
- runtime.
-
-`!tlsldm'
-`!tlsldm!N'
- Used with an `lda' instruction to load the address of a TLS
- descriptor for the current module in the GOT.
-
- Similar in other respects to `tlsgd'.
-
-`!gotdtprel'
- Used with an `ldq' instruction to load the offset of the TLS
- symbol within its module's thread-local storage block. Also known
- as the dynamic thread pointer offset or dtp-relative offset.
-
-`!dtprelhi'
-`!dtprello'
-`!dtprel'
- Like `gprel' relocations except they compute dtp-relative offsets.
-
-`!gottprel'
- Used with an `ldq' instruction to load the offset of the TLS
- symbol from the thread pointer. Also known as the tp-relative
- offset.
-
-`!tprelhi'
-`!tprello'
-`!tprel'
- Like `gprel' relocations except they compute tp-relative offsets.
-
-\1f
-File: as.info, Node: Alpha Floating Point, Next: Alpha Directives, Prev: Alpha Syntax, Up: Alpha-Dependent
-
-8.1.4 Floating Point
---------------------
-
-The Alpha family uses both IEEE and VAX floating-point numbers.
-
-\1f
-File: as.info, Node: Alpha Directives, Next: Alpha Opcodes, Prev: Alpha Floating Point, Up: Alpha-Dependent
-
-8.1.5 Alpha Assembler Directives
---------------------------------
-
-`as' for the Alpha supports many additional directives for
-compatibility with the native assembler. This section describes them
-only briefly.
-
- These are the additional directives in `as' for the Alpha:
-
-`.arch CPU'
- Specifies the target processor. This is equivalent to the `-mCPU'
- command-line option. *Note Options: Alpha Options, for a list of
- values for CPU.
-
-`.ent FUNCTION[, N]'
- Mark the beginning of FUNCTION. An optional number may follow for
- compatibility with the OSF/1 assembler, but is ignored. When
- generating `.mdebug' information, this will create a procedure
- descriptor for the function. In ELF, it will mark the symbol as a
- function a-la the generic `.type' directive.
-
-`.end FUNCTION'
- Mark the end of FUNCTION. In ELF, it will set the size of the
- symbol a-la the generic `.size' directive.
-
-`.mask MASK, OFFSET'
- Indicate which of the integer registers are saved in the current
- function's stack frame. MASK is interpreted a bit mask in which
- bit N set indicates that register N is saved. The registers are
- saved in a block located OFFSET bytes from the "canonical frame
- address" (CFA) which is the value of the stack pointer on entry to
- the function. The registers are saved sequentially, except that
- the return address register (normally `$26') is saved first.
-
- This and the other directives that describe the stack frame are
- currently only used when generating `.mdebug' information. They
- may in the future be used to generate DWARF2 `.debug_frame' unwind
- information for hand written assembly.
-
-`.fmask MASK, OFFSET'
- Indicate which of the floating-point registers are saved in the
- current stack frame. The MASK and OFFSET parameters are
- interpreted as with `.mask'.
-
-`.frame FRAMEREG, FRAMEOFFSET, RETREG[, ARGOFFSET]'
- Describes the shape of the stack frame. The frame pointer in use
- is FRAMEREG; normally this is either `$fp' or `$sp'. The frame
- pointer is FRAMEOFFSET bytes below the CFA. The return address is
- initially located in RETREG until it is saved as indicated in
- `.mask'. For compatibility with OSF/1 an optional ARGOFFSET
- parameter is accepted and ignored. It is believed to indicate the
- offset from the CFA to the saved argument registers.
-
-`.prologue N'
- Indicate that the stack frame is set up and all registers have been
- spilled. The argument N indicates whether and how the function
- uses the incoming "procedure vector" (the address of the called
- function) in `$27'. 0 indicates that `$27' is not used; 1
- indicates that the first two instructions of the function use `$27'
- to perform a load of the GP register; 2 indicates that `$27' is
- used in some non-standard way and so the linker cannot elide the
- load of the procedure vector during relaxation.
-
-`.usepv FUNCTION, WHICH'
- Used to indicate the use of the `$27' register, similar to
- `.prologue', but without the other semantics of needing to be
- inside an open `.ent'/`.end' block.
-
- The WHICH argument should be either `no', indicating that `$27' is
- not used, or `std', indicating that the first two instructions of
- the function perform a GP load.
-
- One might use this directive instead of `.prologue' if you are
- also using dwarf2 CFI directives.
-
-`.gprel32 EXPRESSION'
- Computes the difference between the address in EXPRESSION and the
- GP for the current object file, and stores it in 4 bytes. In
- addition to being smaller than a full 8 byte address, this also
- does not require a dynamic relocation when used in a shared
- library.
-
-`.t_floating EXPRESSION'
- Stores EXPRESSION as an IEEE double precision value.
-
-`.s_floating EXPRESSION'
- Stores EXPRESSION as an IEEE single precision value.
-
-`.f_floating EXPRESSION'
- Stores EXPRESSION as a VAX F format value.
-
-`.g_floating EXPRESSION'
- Stores EXPRESSION as a VAX G format value.
-
-`.d_floating EXPRESSION'
- Stores EXPRESSION as a VAX D format value.
-
-`.set FEATURE'
- Enables or disables various assembler features. Using the positive
- name of the feature enables while using `noFEATURE' disables.
-
- `at'
- Indicates that macro expansions may clobber the "assembler
- temporary" (`$at' or `$28') register. Some macros may not be
- expanded without this and will generate an error message if
- `noat' is in effect. When `at' is in effect, a warning will
- be generated if `$at' is used by the programmer.
-
- `macro'
- Enables the expansion of macro instructions. Note that
- variants of real instructions, such as `br label' vs `br
- $31,label' are considered alternate forms and not macros.
-
- `move'
- `reorder'
- `volatile'
- These control whether and how the assembler may re-order
- instructions. Accepted for compatibility with the OSF/1
- assembler, but `as' does not do instruction scheduling, so
- these features are ignored.
-
- The following directives are recognized for compatibility with the
-OSF/1 assembler but are ignored.
-
- .proc .aproc
- .reguse .livereg
- .option .aent
- .ugen .eflag
- .alias .noalias
-
-\1f
-File: as.info, Node: Alpha Opcodes, Prev: Alpha Directives, Up: Alpha-Dependent
-
-8.1.6 Opcodes
--------------
-
-For detailed information on the Alpha machine instruction set, see the
-Alpha Architecture Handbook
-(ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf).
-
-\1f
-File: as.info, Node: ARC-Dependent, Next: ARM-Dependent, Prev: Alpha-Dependent, Up: Machine Dependencies
-
-8.2 ARC Dependent Features
-==========================
-
-* Menu:
-
-* ARC Options:: Options
-* ARC Syntax:: Syntax
-* ARC Floating Point:: Floating Point
-* ARC Directives:: ARC Machine Directives
-* ARC Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: ARC Options, Next: ARC Syntax, Up: ARC-Dependent
-
-8.2.1 Options
--------------
-
-`-marc[5|6|7|8]'
- This option selects the core processor variant. Using `-marc' is
- the same as `-marc6', which is also the default.
-
- `arc5'
- Base instruction set.
-
- `arc6'
- Jump-and-link (jl) instruction. No requirement of an
- instruction between setting flags and conditional jump. For
- example:
-
- mov.f r0,r1
- beq foo
-
- `arc7'
- Break (brk) and sleep (sleep) instructions.
-
- `arc8'
- Software interrupt (swi) instruction.
-
-
- Note: the `.option' directive can to be used to select a core
- variant from within assembly code.
-
-`-EB'
- This option specifies that the output generated by the assembler
- should be marked as being encoded for a big-endian processor.
-
-`-EL'
- This option specifies that the output generated by the assembler
- should be marked as being encoded for a little-endian processor -
- this is the default.
-
-
-\1f
-File: as.info, Node: ARC Syntax, Next: ARC Floating Point, Prev: ARC Options, Up: ARC-Dependent
-
-8.2.2 Syntax
-------------
-
-* Menu:
-
-* ARC-Chars:: Special Characters
-* ARC-Regs:: Register Names
-
-\1f
-File: as.info, Node: ARC-Chars, Next: ARC-Regs, Up: ARC Syntax
-
-8.2.2.1 Special Characters
-..........................
-
-*TODO*
-
-\1f
-File: as.info, Node: ARC-Regs, Prev: ARC-Chars, Up: ARC Syntax
-
-8.2.2.2 Register Names
-......................
-
-*TODO*
-
-\1f
-File: as.info, Node: ARC Floating Point, Next: ARC Directives, Prev: ARC Syntax, Up: ARC-Dependent
-
-8.2.3 Floating Point
---------------------
-
-The ARC core does not currently have hardware floating point support.
-Software floating point support is provided by `GCC' and uses IEEE
-floating-point numbers.
-
-\1f
-File: as.info, Node: ARC Directives, Next: ARC Opcodes, Prev: ARC Floating Point, Up: ARC-Dependent
-
-8.2.4 ARC Machine Directives
-----------------------------
-
-The ARC version of `as' supports the following additional machine
-directives:
-
-`.2byte EXPRESSIONS'
- *TODO*
-
-`.3byte EXPRESSIONS'
- *TODO*
-
-`.4byte EXPRESSIONS'
- *TODO*
-
-`.extAuxRegister NAME,ADDRESS,MODE'
- The ARCtangent A4 has extensible auxiliary register space. The
- auxiliary registers can be defined in the assembler source code by
- using this directive. The first parameter is the NAME of the new
- auxiallry register. The second parameter is the ADDRESS of the
- register in the auxiliary register memory map for the variant of
- the ARC. The third parameter specifies the MODE in which the
- register can be operated is and it can be one of:
-
- `r (readonly)'
-
- `w (write only)'
-
- `r|w (read or write)'
-
- For example:
-
- .extAuxRegister mulhi,0x12,w
-
- This specifies an extension auxiliary register called _mulhi_
- which is at address 0x12 in the memory space and which is only
- writable.
-
-`.extCondCode SUFFIX,VALUE'
- The condition codes on the ARCtangent A4 are extensible and can be
- specified by means of this assembler directive. They are specified
- by the suffix and the value for the condition code. They can be
- used to specify extra condition codes with any values. For
- example:
-
- .extCondCode is_busy,0x14
-
- add.is_busy r1,r2,r3
- bis_busy _main
-
-`.extCoreRegister NAME,REGNUM,MODE,SHORTCUT'
- Specifies an extension core register NAME for the application.
- This allows a register NAME with a valid REGNUM between 0 and 60,
- with the following as valid values for MODE
-
- `_r_ (readonly)'
-
- `_w_ (write only)'
-
- `_r|w_ (read or write)'
-
- The other parameter gives a description of the register having a
- SHORTCUT in the pipeline. The valid values are:
-
- `can_shortcut'
-
- `cannot_shortcut'
-
- For example:
-
- .extCoreRegister mlo,57,r,can_shortcut
-
- This defines an extension core register mlo with the value 57 which
- can shortcut the pipeline.
-
-`.extInstruction NAME,OPCODE,SUBOPCODE,SUFFIXCLASS,SYNTAXCLASS'
- The ARCtangent A4 allows the user to specify extension
- instructions. The extension instructions are not macros. The
- assembler creates encodings for use of these instructions
- according to the specification by the user. The parameters are:
-
- *NAME
- Name of the extension instruction
-
- *OPCODE
- Opcode to be used. (Bits 27:31 in the encoding). Valid values
- 0x10-0x1f or 0x03
-
- *SUBOPCODE
- Subopcode to be used. Valid values are from 0x09-0x3f.
- However the correct value also depends on SYNTAXCLASS
-
- *SUFFIXCLASS
- Determines the kinds of suffixes to be allowed. Valid values
- are `SUFFIX_NONE', `SUFFIX_COND', `SUFFIX_FLAG' which
- indicates the absence or presence of conditional suffixes and
- flag setting by the extension instruction. It is also
- possible to specify that an instruction sets the flags and is
- condtional by using `SUFFIX_CODE' | `SUFFIX_FLAG'.
-
- *SYNTAXCLASS
- Determines the syntax class for the instruction. It can have
- the following values:
-
- ``SYNTAX_2OP':'
- 2 Operand Instruction
-
- ``SYNTAX_3OP':'
- 3 Operand Instruction
-
- In addition there could be modifiers for the syntax class as
- described below:
-
- Syntax Class Modifiers are:
-
- - `OP1_MUST_BE_IMM': Modifies syntax class SYNTAX_3OP,
- specifying that the first operand of a three-operand
- instruction must be an immediate (i.e., the result is
- discarded). OP1_MUST_BE_IMM is used by bitwise ORing it
- with SYNTAX_3OP as given in the example below. This
- could usually be used to set the flags using specific
- instructions and not retain results.
-
- - `OP1_IMM_IMPLIED': Modifies syntax class SYNTAX_20P, it
- specifies that there is an implied immediate destination
- operand which does not appear in the syntax. For
- example, if the source code contains an instruction like:
-
- inst r1,r2
-
- it really means that the first argument is an implied
- immediate (that is, the result is discarded). This is
- the same as though the source code were: inst 0,r1,r2.
- You use OP1_IMM_IMPLIED by bitwise ORing it with
- SYNTAX_20P.
-
-
- For example, defining 64-bit multiplier with immediate operands:
-
- .extInstruction mp64,0x14,0x0,SUFFIX_COND | SUFFIX_FLAG ,
- SYNTAX_3OP|OP1_MUST_BE_IMM
-
- The above specifies an extension instruction called mp64 which has
- 3 operands, sets the flags, can be used with a condition code, for
- which the first operand is an immediate. (Equivalent to
- discarding the result of the operation).
-
- .extInstruction mul64,0x14,0x00,SUFFIX_COND, SYNTAX_2OP|OP1_IMM_IMPLIED
-
- This describes a 2 operand instruction with an implicit first
- immediate operand. The result of this operation would be
- discarded.
-
-`.half EXPRESSIONS'
- *TODO*
-
-`.long EXPRESSIONS'
- *TODO*
-
-`.option ARC|ARC5|ARC6|ARC7|ARC8'
- The `.option' directive must be followed by the desired core
- version. Again `arc' is an alias for `arc6'.
-
- Note: the `.option' directive overrides the command line option
- `-marc'; a warning is emitted when the version is not consistent
- between the two - even for the implicit default core version
- (arc6).
-
-`.short EXPRESSIONS'
- *TODO*
-
-`.word EXPRESSIONS'
- *TODO*
-
-
-\1f
-File: as.info, Node: ARC Opcodes, Prev: ARC Directives, Up: ARC-Dependent
-
-8.2.5 Opcodes
--------------
-
-For information on the ARC instruction set, see `ARC Programmers
-Reference Manual', ARC International (www.arc.com)
-
-\1f
-File: as.info, Node: ARM-Dependent, Next: AVR-Dependent, Prev: ARC-Dependent, Up: Machine Dependencies
-
-8.3 ARM Dependent Features
-==========================
-
-* Menu:
-
-* ARM Options:: Options
-* ARM Syntax:: Syntax
-* ARM Floating Point:: Floating Point
-* ARM Directives:: ARM Machine Directives
-* ARM Opcodes:: Opcodes
-* ARM Mapping Symbols:: Mapping Symbols
-
-\1f
-File: as.info, Node: ARM Options, Next: ARM Syntax, Up: ARM-Dependent
-
-8.3.1 Options
--------------
-
-`-mcpu=PROCESSOR[+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: `arm1', `arm2', `arm250',
- `arm3', `arm6', `arm60', `arm600', `arm610', `arm620', `arm7',
- `arm7m', `arm7d', `arm7dm', `arm7di', `arm7dmi', `arm70', `arm700',
- `arm700i', `arm710', `arm710t', `arm720', `arm720t', `arm740t',
- `arm710c', `arm7100', `arm7500', `arm7500fe', `arm7t', `arm7tdmi',
- `arm7tdmi-s', `arm8', `arm810', `strongarm', `strongarm1',
- `strongarm110', `strongarm1100', `strongarm1110', `arm9', `arm920',
- `arm920t', `arm922t', `arm940t', `arm9tdmi', `arm9e', `arm926e',
- `arm926ej-s', `arm946e-r0', `arm946e', `arm946e-s', `arm966e-r0',
- `arm966e', `arm966e-s', `arm968e-s', `arm10t', `arm10tdmi',
- `arm10e', `arm1020', `arm1020t', `arm1020e', `arm1022e',
- `arm1026ej-s', `arm1136j-s', `arm1136jf-s', `arm1156t2-s',
- `arm1156t2f-s', `arm1176jz-s', `arm1176jzf-s', `mpcore',
- `mpcorenovfp', `cortex-a8', `cortex-r4', `cortex-m3', `ep9312'
- (ARM920 with Cirrus Maverick coprocessor), `i80200' (Intel XScale
- processor) `iwmmxt' (Intel(r) XScale processor with Wireless
- MMX(tm) technology coprocessor) and `xscale'. The special name
- `all' may be used to allow the assembler to accept instructions
- valid for any ARM processor.
-
- 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,
- `-mcpu=arm920+maverick' is equivalent to specifying
- `-mcpu=ep9312'. The following extensions are currently supported:
- `+maverick' `+iwmmxt' and `+xscale'.
-
-`-march=ARCHITECTURE[+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: `armv1', `armv2',
- `armv2a', `armv2s', `armv3', `armv3m', `armv4', `armv4xm',
- `armv4t', `armv4txm', `armv5', `armv5t', `armv5txm', `armv5te',
- `armv5texp', `armv6', `armv6j', `armv6k', `armv6z', `armv6zk',
- `armv7', `armv7-a', `armv7-r', `armv7-m', `iwmmxt' and `xscale'.
- If both `-mcpu' and `-march' are specified, the assembler will use
- the setting for `-mcpu'.
-
- The architecture option can be extended with the same instruction
- set extension options as the `-mcpu' option.
-
-`-mfpu=FLOATING-POINT-FORMAT'
- 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:
- `softfpa', `fpe', `fpe2', `fpe3', `fpa', `fpa10', `fpa11',
- `arm7500fe', `softvfp', `softvfp+vfp', `vfp', `vfp10', `vfp10-r0',
- `vfp9', `vfpxd', `arm1020t', `arm1020e', `arm1136jf-s' and
- `maverick'.
-
- In addition to determining which instructions are assembled, this
- option also affects the way in which the `.double' assembler
- directive behaves when assembling little-endian code.
-
- 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.
-
-`-mthumb'
- This option specifies that the assembler should start assembling
- Thumb instructions; that is, it should behave as though the file
- starts with a `.code 16' directive.
-
-`-mthumb-interwork'
- This option specifies that the output generated by the assembler
- should be marked as supporting interworking.
-
-`-mapcs `[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.
-
-`-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.
-
-`-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.
-
-`-mapcs-reentrant'
- This indicates that the reentrant variant of the APCS should be
- used. This variant supports position independent code.
-
-`-mfloat-abi=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: `soft', `softfp' and `hard'.
-
-`-meabi=VER'
- This option specifies which EABI version the produced object files
- should conform to. The following values are recognized: `gnu', `4'
- and `5'.
-
-`-EB'
- This option specifies that the output generated by the assembler
- should be marked as being encoded for a big-endian processor.
-
-`-EL'
- This option specifies that the output generated by the assembler
- should be marked as being encoded for a little-endian processor.
-
-`-k'
- This option specifies that the output of the assembler should be
- marked as position-independent code (PIC).
-
-
-\1f
-File: as.info, Node: ARM Syntax, Next: ARM Floating Point, Prev: ARM Options, Up: ARM-Dependent
-
-8.3.2 Syntax
-------------
-
-* Menu:
-
-* ARM-Chars:: Special Characters
-* ARM-Regs:: Register Names
-* ARM-Relocations:: Relocations
-
-\1f
-File: as.info, Node: ARM-Chars, Next: ARM-Regs, Up: ARM Syntax
-
-8.3.2.1 Special Characters
-..........................
-
-The presence of a `@' on a line indicates the start of a comment that
-extends to the end of the current line. If a `#' appears as the first
-character of a line, the whole line is treated as a comment.
-
- The `;' character can be used instead of a newline to separate
-statements.
-
- Either `#' or `$' can be used to indicate immediate operands.
-
- *TODO* Explain about /data modifier on symbols.
-
-\1f
-File: as.info, Node: ARM-Regs, Next: ARM-Relocations, Prev: ARM-Chars, Up: ARM Syntax
-
-8.3.2.2 Register Names
-......................
-
-*TODO* Explain about ARM register naming, and the predefined names.
-
-\1f
-File: as.info, Node: ARM Floating Point, Next: ARM Directives, Prev: ARM Syntax, Up: ARM-Dependent
-
-8.3.3 Floating Point
---------------------
-
-The ARM family uses IEEE floating-point numbers.
-
-\1f
-File: as.info, Node: ARM-Relocations, Prev: ARM-Regs, Up: ARM Syntax
-
-8.3.3.1 ARM relocation generation
-.................................
-
-Specific data relocations can be generated by putting the relocation
-name in parentheses after the symbol name. For example:
-
- .word foo(TARGET1)
-
- This will generate an `R_ARM_TARGET1' relocation against the symbol
-FOO. The following relocations are supported: `GOT', `GOTOFF',
-`TARGET1', `TARGET2', `SBREL', `TLSGD', `TLSLDM', `TLSLDO', `GOTTPOFF'
-and `TPOFF'.
-
- For compatibility with older toolchains the assembler also accepts
-`(PLT)' after branch targets. This will generate the deprecated
-`R_ARM_PLT32' relocation.
-
- Relocations for `MOVW' and `MOVT' instructions can be generated by
-prefixing the value with `#:lower16:' and `#:upper16' respectively.
-For example to load the 32-bit address of foo into r0:
-
- MOVW r0, #:lower16:foo
- MOVT r0, #:upper16:foo
-
-\1f
-File: as.info, Node: ARM Directives, Next: ARM Opcodes, Prev: ARM Floating Point, Up: ARM-Dependent
-
-8.3.4 ARM Machine Directives
-----------------------------
-
-`.align EXPRESSION [, EXPRESSION]'
- This is the generic .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.
-
-`NAME .req REGISTER NAME'
- This creates an alias for REGISTER NAME called NAME. For example:
-
- foo .req r0
-
-`.unreq ALIAS-NAME'
- This undefines a register alias which was previously defined using
- the `req', `dn' or `qn' directives. For example:
-
- foo .req r0
- .unreq foo
-
- 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.
-
-`NAME .dn REGISTER NAME [.TYPE] [[INDEX]]'
-
-`NAME .qn REGISTER NAME [.TYPE] [[INDEX]]'
- The `dn' and `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.
-
- 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:
-
- x .dn d2.f32
- y .dn d3.f32
- z .dn d4.f32[1]
- vmul x,y,z
-
- This is equivalent to writing the following:
-
- vmul.f32 d2,d3,d4[1]
-
- Aliases created using `dn' or `qn' can be destroyed using `unreq'.
-
-`.code `[16|32]''
- This directive selects the instruction set being generated. The
- value 16 selects Thumb, with the value 32 selecting ARM.
-
-`.thumb'
- This performs the same action as .CODE 16.
-
-`.arm'
- This performs the same action as .CODE 32.
-
-`.force_thumb'
- This directive forces the selection of Thumb instructions, even if
- the target processor does not support those instructions
-
-`.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 `.thumb'
-
- This directive is not neccessary when generating EABI objects. On
- these targets the encoding is implicit when generating Thumb code.
-
-`.thumb_set'
- This performs the equivalent of a `.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 `.thumb_func' directive does.
-
-`.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). `GAS' maintains a separate literal pool for each
- section and each sub-section. The `.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.
-
- Note - older versions of `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.
-
-`.pool'
- This is a synonym for .ltorg.
-
-`.unwind_fnstart'
- Marks the start of a function with an unwind table entry.
-
-`.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.
-
- 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.
-
-`.cantunwind'
- Prevents unwinding through the current function. No personality
- routine or exception table data is required or permitted.
-
-`.personality NAME'
- Sets the personality routine for the current function to NAME.
-
-`.personalityindex INDEX'
- Sets the personality routine for the current function to the EABI
- standard routine number INDEX
-
-`.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 `.fnend' directive will be added to the
- exception table entry.
-
- Must be preceded by a `.personality' or `.personalityindex'
- directive.
-
-`.save REGLIST'
- Generate unwinder annotations to restore the registers in REGLIST.
- The format of REGLIST is the same as the corresponding
- store-multiple instruction.
-
- _core registers_
- .save {r4, r5, r6, lr}
- stmfd sp!, {r4, r5, r6, lr}
- _FPA registers_
- .save f4, 2
- sfmfd f4, 2, [sp]!
- _VFP registers_
- .save {d8, d9, d10}
- fstmdx sp!, {d8, d9, d10}
- _iWMMXt registers_
- .save {wr10, wr11}
- wstrd wr11, [sp, #-8]!
- wstrd wr10, [sp, #-8]!
- or
- .save wr11
- wstrd wr11, [sp, #-8]!
- .save wr10
- wstrd wr10, [sp, #-8]!
-
-`.vsave VFP-REGLIST'
- Generate unwinder annotations to restore the VFP registers in
- VFP-REGLIST using FLDMD. Also works for VFPv3 registers that are
- to be restored using VLDM. The format of VFP-REGLIST is the same
- as the corresponding store-multiple instruction.
-
- _VFP registers_
- .vsave {d8, d9, d10}
- fstmdd sp!, {d8, d9, d10}
- _VFPv3 registers_
- .vsave {d15, d16, d17}
- vstm sp!, {d15, d16, d17}
-
- Since FLDMX and FSTMX are now deprecated, this directive should be
- used in favour of `.save' for saving VFP registers for ARMv6 and
- above.
-
-`.pad #COUNT'
- Generate unwinder annotations for a stack adjustment of COUNT
- bytes. A positive value indicates the function prologue allocated
- stack space by decrementing the stack pointer.
-
-`.movsp REG [, #OFFSET]'
- Tell the unwinder that REG contains an offset from the current
- stack pointer. If OFFSET is not specified then it is assumed to be
- zero.
-
-`.setfp FPREG, SPREG [, #OFFSET]'
- Make all unwinder annotations relaive to a frame pointer. Without
- this the unwinder will use offsets from the stack pointer.
-
- The syntax of this directive is the same as the `sub' or `mov'
- instruction used to set the frame pointer. SPREG must be either
- `sp' or mentioned in a previous `.movsp' directive.
-
- .movsp ip
- mov ip, sp
- ...
- .setfp fp, ip, #4
- sub fp, ip, #4
-
-`.raw OFFSET, BYTE1, ...'
- Insert one of more arbitary unwind opcode bytes, which are known
- to adjust the stack pointer by OFFSET bytes.
-
- For example `.unwind_raw 4, 0xb1, 0x01' is equivalent to `.save
- {r0}'
-
-`.cpu NAME'
- Select the target processor. Valid values for NAME are the same as
- for the `-mcpu' commandline option.
-
-`.arch NAME'
- Select the target architecture. Valid values for NAME are the
- same as for the `-march' commandline option.
-
-`.object_arch NAME'
- Override the architecture recorded in the EABI object attribute
- section. Valid values for NAME are the same as for the `.arch'
- directive. Typically this is useful when code uses runtime
- detection of CPU features.
-
-`.fpu NAME'
- Select the floating point unit to assemble for. Valid values for
- NAME are the same as for the `-mfpu' commandline option.
-
-`.eabi_attribute TAG, VALUE'
- Set the EABI object attribute number TAG to VALUE. The value is
- either a `number', `"string"', or `number, "string"' depending on
- the tag.
-
-
-\1f
-File: as.info, Node: ARM Opcodes, Next: ARM Mapping Symbols, Prev: ARM Directives, Up: ARM-Dependent
-
-8.3.5 Opcodes
--------------
-
-`as' implements all the standard ARM opcodes. It also implements
-several pseudo opcodes, including several synthetic load instructions.
-
-`NOP'
- nop
-
- This pseudo op will always evaluate to a legal ARM instruction
- that does nothing. Currently it will evaluate to MOV r0, r0.
-
-`LDR'
- ldr <register> , = <expression>
-
- 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.
-
-`ADR'
- adr <register> <label>
-
- This instruction will load the address of 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.
-
-`ADRL'
- adrl <register> <label>
-
- This instruction will load the address of 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.
-
- 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.
-
-
- For information on the ARM or Thumb instruction sets, see `ARM
-Software Development Toolkit Reference Manual', Advanced RISC Machines
-Ltd.
-
-\1f
-File: as.info, Node: ARM Mapping Symbols, Prev: ARM Opcodes, Up: ARM-Dependent
-
-8.3.6 Mapping Symbols
----------------------
-
-The ARM ELF specification requires that special symbols be inserted
-into object files to mark certain features:
-
-`$a'
- At the start of a region of code containing ARM instructions.
-
-`$t'
- At the start of a region of code containing THUMB instructions.
-
-`$d'
- At the start of a region of data.
-
-
- 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.
-
-\1f
-File: as.info, Node: AVR-Dependent, Next: BFIN-Dependent, Prev: ARM-Dependent, Up: Machine Dependencies
-
-8.4 AVR Dependent Features
-==========================
-
-* Menu:
-
-* AVR Options:: Options
-* AVR Syntax:: Syntax
-* AVR Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: AVR Options, Next: AVR Syntax, Up: AVR-Dependent
-
-8.4.1 Options
--------------
-
-`-mmcu=MCU'
- Specify ATMEL AVR instruction set or MCU type.
-
- Instruction set avr1 is for the minimal AVR core, not supported by
- the C compiler, only for assembler programs (MCU types: at90s1200,
- attiny10, attiny11, attiny12, attiny15, attiny28).
-
- Instruction set avr2 (default) is for the classic AVR core with up
- to 8K program memory space (MCU types: at90s2313, at90s2323,
- attiny22, attiny26, at90s2333, at90s2343, at90s4414, at90s4433,
- at90s4434, at90s8515, at90c8534, at90s8535, at86rf401, attiny13,
- attiny2313, attiny261, attiny461, attiny861, attiny24, attiny44,
- attiny84, attiny25, attiny45, attiny85).
-
- Instruction set avr3 is for the classic AVR core with up to 128K
- program memory space (MCU types: atmega103, atmega603, at43usb320,
- at43usb355, at76c711).
-
- Instruction set avr4 is for the enhanced AVR core with up to 8K
- program memory space (MCU types: atmega48, atmega8, atmega83,
- atmega85, atmega88, atmega8515, atmega8535, atmega8hva, at90pwm1,
- at90pwm2, at90pwm3).
-
- Instruction set avr5 is for the enhanced AVR core with up to 128K
- program memory space (MCU types: atmega16, atmega161, atmega162,
- atmega163, atmega164p, atmega165, atmega165p, atmega168,
- atmega169, atmega169p, atmega32, atmega323, atmega324p, atmega325,
- atmega325p, atmega329, atmega329p, atmega3250, atmega3250p,
- atmega3290, atmega3290p, atmega406, atmega64, atmega640,
- atmega644, atmega644p, atmega128, atmega1280, atmega1281,
- atmega645, atmega649, atmega6450, atmega6490, atmega16hva,
- at90can32, at90can64, at90can128, at90usb82, at90usb162,
- at90usb646, at90usb647, at90usb1286, at90usb1287, at94k).
-
- Instruction set avr6 is for the enhanced AVR core with 256K program
- memory space (MCU types: atmega2560, atmega2561).
-
-`-mall-opcodes'
- Accept all AVR opcodes, even if not supported by `-mmcu'.
-
-`-mno-skip-bug'
- This option disable warnings for skipping two-word instructions.
-
-`-mno-wrap'
- This option reject `rjmp/rcall' instructions with 8K wrap-around.
-
-
-\1f
-File: as.info, Node: AVR Syntax, Next: AVR Opcodes, Prev: AVR Options, Up: AVR-Dependent
-
-8.4.2 Syntax
-------------
-
-* Menu:
-
-* AVR-Chars:: Special Characters
-* AVR-Regs:: Register Names
-* AVR-Modifiers:: Relocatable Expression Modifiers
-
-\1f
-File: as.info, Node: AVR-Chars, Next: AVR-Regs, Up: AVR Syntax
-
-8.4.2.1 Special Characters
-..........................
-
-The presence of a `;' on a line indicates the start of a comment that
-extends to the end of the current line. If a `#' appears as the first
-character of a line, the whole line is treated as a comment.
-
- The `$' character can be used instead of a newline to separate
-statements.
-
-\1f
-File: as.info, Node: AVR-Regs, Next: AVR-Modifiers, Prev: AVR-Chars, Up: AVR Syntax
-
-8.4.2.2 Register Names
-......................
-
-The AVR has 32 x 8-bit general purpose working registers `r0', `r1',
-... `r31'. Six of the 32 registers can be used as three 16-bit
-indirect address register pointers for Data Space addressing. One of
-the these address pointers can also be used as an address pointer for
-look up tables in Flash program memory. These added function registers
-are the 16-bit `X', `Y' and `Z' - registers.
-
- X = r26:r27
- Y = r28:r29
- Z = r30:r31
-
-\1f
-File: as.info, Node: AVR-Modifiers, Prev: AVR-Regs, Up: AVR Syntax
-
-8.4.2.3 Relocatable Expression Modifiers
-........................................
-
-The assembler supports several modifiers when using relocatable
-addresses in AVR instruction operands. The general syntax is the
-following:
-
- modifier(relocatable-expression)
-
-`lo8'
- This modifier allows you to use bits 0 through 7 of an address
- expression as 8 bit relocatable expression.
-
-`hi8'
- This modifier allows you to use bits 7 through 15 of an address
- expression as 8 bit relocatable expression. This is useful with,
- for example, the AVR `ldi' instruction and `lo8' modifier.
-
- For example
-
- ldi r26, lo8(sym+10)
- ldi r27, hi8(sym+10)
-
-`hh8'
- This modifier allows you to use bits 16 through 23 of an address
- expression as 8 bit relocatable expression. Also, can be useful
- for loading 32 bit constants.
-
-`hlo8'
- Synonym of `hh8'.
-
-`hhi8'
- This modifier allows you to use bits 24 through 31 of an
- expression as 8 bit expression. This is useful with, for example,
- the AVR `ldi' instruction and `lo8', `hi8', `hlo8', `hhi8',
- modifier.
-
- For example
-
- ldi r26, lo8(285774925)
- ldi r27, hi8(285774925)
- ldi r28, hlo8(285774925)
- ldi r29, hhi8(285774925)
- ; r29,r28,r27,r26 = 285774925
-
-`pm_lo8'
- This modifier allows you to use bits 0 through 7 of an address
- expression as 8 bit relocatable expression. This modifier useful
- for addressing data or code from Flash/Program memory. The using
- of `pm_lo8' similar to `lo8'.
-
-`pm_hi8'
- This modifier allows you to use bits 8 through 15 of an address
- expression as 8 bit relocatable expression. This modifier useful
- for addressing data or code from Flash/Program memory.
-
-`pm_hh8'
- This modifier allows you to use bits 15 through 23 of an address
- expression as 8 bit relocatable expression. This modifier useful
- for addressing data or code from Flash/Program memory.
-
-
-\1f
-File: as.info, Node: AVR Opcodes, Prev: AVR Syntax, Up: AVR-Dependent
-
-8.4.3 Opcodes
--------------
-
-For detailed information on the AVR machine instruction set, see
-`www.atmel.com/products/AVR'.
-
- `as' implements all the standard AVR opcodes. The following table
-summarizes the AVR opcodes, and their arguments.
-
- Legend:
- r any register
- d `ldi' register (r16-r31)
- v `movw' even register (r0, r2, ..., r28, r30)
- a `fmul' register (r16-r23)
- w `adiw' register (r24,r26,r28,r30)
- e pointer registers (X,Y,Z)
- b base pointer register and displacement ([YZ]+disp)
- z Z pointer register (for [e]lpm Rd,Z[+])
- M immediate value from 0 to 255
- n immediate value from 0 to 255 ( n = ~M ). Relocation impossible
- s immediate value from 0 to 7
- P Port address value from 0 to 63. (in, out)
- p Port address value from 0 to 31. (cbi, sbi, sbic, sbis)
- K immediate value from 0 to 63 (used in `adiw', `sbiw')
- i immediate value
- l signed pc relative offset from -64 to 63
- L signed pc relative offset from -2048 to 2047
- h absolute code address (call, jmp)
- S immediate value from 0 to 7 (S = s << 4)
- ? use this opcode entry if no parameters, else use next opcode entry
-
- 1001010010001000 clc
- 1001010011011000 clh
- 1001010011111000 cli
- 1001010010101000 cln
- 1001010011001000 cls
- 1001010011101000 clt
- 1001010010111000 clv
- 1001010010011000 clz
- 1001010000001000 sec
- 1001010001011000 seh
- 1001010001111000 sei
- 1001010000101000 sen
- 1001010001001000 ses
- 1001010001101000 set
- 1001010000111000 sev
- 1001010000011000 sez
- 100101001SSS1000 bclr S
- 100101000SSS1000 bset S
- 1001010100001001 icall
- 1001010000001001 ijmp
- 1001010111001000 lpm ?
- 1001000ddddd010+ lpm r,z
- 1001010111011000 elpm ?
- 1001000ddddd011+ elpm r,z
- 0000000000000000 nop
- 1001010100001000 ret
- 1001010100011000 reti
- 1001010110001000 sleep
- 1001010110011000 break
- 1001010110101000 wdr
- 1001010111101000 spm
- 000111rdddddrrrr adc r,r
- 000011rdddddrrrr add r,r
- 001000rdddddrrrr and r,r
- 000101rdddddrrrr cp r,r
- 000001rdddddrrrr cpc r,r
- 000100rdddddrrrr cpse r,r
- 001001rdddddrrrr eor r,r
- 001011rdddddrrrr mov r,r
- 100111rdddddrrrr mul r,r
- 001010rdddddrrrr or r,r
- 000010rdddddrrrr sbc r,r
- 000110rdddddrrrr sub r,r
- 001001rdddddrrrr clr r
- 000011rdddddrrrr lsl r
- 000111rdddddrrrr rol r
- 001000rdddddrrrr tst r
- 0111KKKKddddKKKK andi d,M
- 0111KKKKddddKKKK cbr d,n
- 1110KKKKddddKKKK ldi d,M
- 11101111dddd1111 ser d
- 0110KKKKddddKKKK ori d,M
- 0110KKKKddddKKKK sbr d,M
- 0011KKKKddddKKKK cpi d,M
- 0100KKKKddddKKKK sbci d,M
- 0101KKKKddddKKKK subi d,M
- 1111110rrrrr0sss sbrc r,s
- 1111111rrrrr0sss sbrs r,s
- 1111100ddddd0sss bld r,s
- 1111101ddddd0sss bst r,s
- 10110PPdddddPPPP in r,P
- 10111PPrrrrrPPPP out P,r
- 10010110KKddKKKK adiw w,K
- 10010111KKddKKKK sbiw w,K
- 10011000pppppsss cbi p,s
- 10011010pppppsss sbi p,s
- 10011001pppppsss sbic p,s
- 10011011pppppsss sbis p,s
- 111101lllllll000 brcc l
- 111100lllllll000 brcs l
- 111100lllllll001 breq l
- 111101lllllll100 brge l
- 111101lllllll101 brhc l
- 111100lllllll101 brhs l
- 111101lllllll111 brid l
- 111100lllllll111 brie l
- 111100lllllll000 brlo l
- 111100lllllll100 brlt l
- 111100lllllll010 brmi l
- 111101lllllll001 brne l
- 111101lllllll010 brpl l
- 111101lllllll000 brsh l
- 111101lllllll110 brtc l
- 111100lllllll110 brts l
- 111101lllllll011 brvc l
- 111100lllllll011 brvs l
- 111101lllllllsss brbc s,l
- 111100lllllllsss brbs s,l
- 1101LLLLLLLLLLLL rcall L
- 1100LLLLLLLLLLLL rjmp L
- 1001010hhhhh111h call h
- 1001010hhhhh110h jmp h
- 1001010rrrrr0101 asr r
- 1001010rrrrr0000 com r
- 1001010rrrrr1010 dec r
- 1001010rrrrr0011 inc r
- 1001010rrrrr0110 lsr r
- 1001010rrrrr0001 neg r
- 1001000rrrrr1111 pop r
- 1001001rrrrr1111 push r
- 1001010rrrrr0111 ror r
- 1001010rrrrr0010 swap r
- 00000001ddddrrrr movw v,v
- 00000010ddddrrrr muls d,d
- 000000110ddd0rrr mulsu a,a
- 000000110ddd1rrr fmul a,a
- 000000111ddd0rrr fmuls a,a
- 000000111ddd1rrr fmulsu a,a
- 1001001ddddd0000 sts i,r
- 1001000ddddd0000 lds r,i
- 10o0oo0dddddbooo ldd r,b
- 100!000dddddee-+ ld r,e
- 10o0oo1rrrrrbooo std b,r
- 100!001rrrrree-+ st e,r
- 1001010100011001 eicall
- 1001010000011001 eijmp
-
-\1f
-File: as.info, Node: BFIN-Dependent, Next: CR16-Dependent, Prev: AVR-Dependent, Up: Machine Dependencies
-
-8.5 Blackfin Dependent Features
-===============================
-
-* Menu:
-
-* BFIN Syntax:: BFIN Syntax
-* BFIN Directives:: BFIN Directives
-
-\1f
-File: as.info, Node: BFIN Syntax, Next: BFIN Directives, Up: BFIN-Dependent
-
-8.5.1 Syntax
-------------
-
-`Special Characters'
- Assembler input is free format and may appear anywhere on the line.
- One instruction may extend across multiple lines or more than one
- instruction may appear on the same line. White space (space, tab,
- comments or newline) may appear anywhere between tokens. A token
- must not have embedded spaces. Tokens include numbers, register
- names, keywords, user identifiers, and also some multicharacter
- special symbols like "+=", "/*" or "||".
-
-`Instruction Delimiting'
- A semicolon must terminate every instruction. Sometimes a complete
- instruction will consist of more than one operation. There are two
- cases where this occurs. The first is when two general operations
- are combined. Normally a comma separates the different parts, as
- in
-
- a0= r3.h * r2.l, a1 = r3.l * r2.h ;
-
- The second case occurs when a general instruction is combined with
- one or two memory references for joint issue. The latter portions
- are set off by a "||" token.
-
- a0 = r3.h * r2.l || r1 = [p3++] || r4 = [i2++];
-
-`Register Names'
- The assembler treats register names and instruction keywords in a
- case insensitive manner. User identifiers are case sensitive.
- Thus, R3.l, R3.L, r3.l and r3.L are all equivalent input to the
- assembler.
-
- Register names are reserved and may not be used as program
- identifiers.
-
- Some operations (such as "Move Register") require a register pair.
- Register pairs are always data registers and are denoted using a
- colon, eg., R3:2. The larger number must be written firsts. Note
- that the hardware only supports odd-even pairs, eg., R7:6, R5:4,
- R3:2, and R1:0.
-
- Some instructions (such as -SP (Push Multiple)) require a group of
- adjacent registers. Adjacent registers are denoted in the syntax
- by the range enclosed in parentheses and separated by a colon,
- eg., (R7:3). Again, the larger number appears first.
-
- Portions of a particular register may be individually specified.
- This is written with a dot (".") following the register name and
- then a letter denoting the desired portion. For 32-bit registers,
- ".H" denotes the most significant ("High") portion. ".L" denotes
- the least-significant portion. The subdivisions of the 40-bit
- registers are described later.
-
-`Accumulators'
- The set of 40-bit registers A1 and A0 that normally contain data
- that is being manipulated. Each accumulator can be accessed in
- four ways.
-
- `one 40-bit register'
- The register will be referred to as A1 or A0.
-
- `one 32-bit register'
- The registers are designated as A1.W or A0.W.
-
- `two 16-bit registers'
- The registers are designated as A1.H, A1.L, A0.H or A0.L.
-
- `one 8-bit register'
- The registers are designated as A1.X or A0.X for the bits that
- extend beyond bit 31.
-
-`Data Registers'
- The set of 32-bit registers (R0, R1, R2, R3, R4, R5, R6 and R7)
- that normally contain data for manipulation. These are
- abbreviated as D-register or Dreg. Data registers can be accessed
- as 32-bit registers or as two independent 16-bit registers. The
- least significant 16 bits of each register is called the "low"
- half and is designated with ".L" following the register name. The
- most significant 16 bits are called the "high" half and is
- designated with ".H" following the name.
-
- R7.L, r2.h, r4.L, R0.H
-
-`Pointer Registers'
- The set of 32-bit registers (P0, P1, P2, P3, P4, P5, SP and FP)
- that normally contain byte addresses of data structures. These are
- abbreviated as P-register or Preg.
-
- p2, p5, fp, sp
-
-`Stack Pointer SP'
- The stack pointer contains the 32-bit address of the last occupied
- byte location in the stack. The stack grows by decrementing the
- stack pointer.
-
-`Frame Pointer FP'
- The frame pointer contains the 32-bit address of the previous frame
- pointer in the stack. It is located at the top of a frame.
-
-`Loop Top'
- LT0 and LT1. These registers contain the 32-bit address of the
- top of a zero overhead loop.
-
-`Loop Count'
- LC0 and LC1. These registers contain the 32-bit counter of the
- zero overhead loop executions.
-
-`Loop Bottom'
- LB0 and LB1. These registers contain the 32-bit address of the
- bottom of a zero overhead loop.
-
-`Index Registers'
- The set of 32-bit registers (I0, I1, I2, I3) that normally contain
- byte addresses of data structures. Abbreviated I-register or Ireg.
-
-`Modify Registers'
- The set of 32-bit registers (M0, M1, M2, M3) that normally contain
- offset values that are added and subracted to one of the index
- registers. Abbreviated as Mreg.
-
-`Length Registers'
- The set of 32-bit registers (L0, L1, L2, L3) that normally contain
- the length in bytes of the circular buffer. Abbreviated as Lreg.
- Clear the Lreg to disable circular addressing for the
- corresponding Ireg.
-
-`Base Registers'
- The set of 32-bit registers (B0, B1, B2, B3) that normally contain
- the base address in bytes of the circular buffer. Abbreviated as
- Breg.
-
-`Floating Point'
- The Blackfin family has no hardware floating point but the .float
- directive generates ieee floating point numbers for use with
- software floating point libraries.
-
-`Blackfin Opcodes'
- For detailed information on the Blackfin machine instruction set,
- see the Blackfin(r) Processor Instruction Set Reference.
-
-
-\1f
-File: as.info, Node: BFIN Directives, Prev: BFIN Syntax, Up: BFIN-Dependent
-
-8.5.2 Directives
-----------------
-
-The following directives are provided for compatibility with the VDSP
-assembler.
-
-`.byte2'
- Initializes a four byte data object.
-
-`.byte4'
- Initializes a two byte data object.
-
-`.db'
- TBD
-
-`.dd'
- TBD
-
-`.dw'
- TBD
-
-`.var'
- Define and initialize a 32 bit data object.
-
-\1f
-File: as.info, Node: CR16-Dependent, Next: CRIS-Dependent, Prev: BFIN-Dependent, Up: Machine Dependencies
-
-8.6 CR16 Dependent Features
-===========================
-
-* Menu:
-
-* CR16 Operand Qualifiers:: CR16 Machine Operand Qualifiers
-
-\1f
-File: as.info, Node: CR16 Operand Qualifiers, Up: CR16-Dependent
-
-8.6.1 CR16 Operand Qualifiers
------------------------------
-
-The National Semiconductor CR16 target of `as' has a few machine
-dependent operand qualifiers.
-
- Operand expression type qualifier is an optional field in the
-instruction operand, to determines the type of the expression field of
-an operand. The `@' is required. CR16 architecture uses one of the
-following expression qualifiers:
-
-`s'
- - `Specifies expression operand type as small'
-
-`m'
- - `Specifies expression operand type as medium'
-
-`l'
- - `Specifies expression operand type as large'
-
-`c'
- - `Specifies the CR16 Assembler generates a relocation entry for
- the operand, where pc has implied bit, the expression is adjusted
- accordingly. The linker uses the relocation entry to update the
- operand address at link time.'
-
- CR16 target operand qualifiers and its size (in bits):
-
-`Immediate Operand'
- - s --- 4 bits
-
-`'
- - m --- 16 bits, for movb and movw instructions.
-
-`'
- - m --- 20 bits, movd instructions.
-
-`'
- - l --- 32 bits
-
-`Absolute Operand'
- - s --- Illegal specifier for this operand.
-
-`'
- - m --- 20 bits, movd instructions.
-
-`Displacement Operand'
- - s --- 8 bits
-
-`'
- - m --- 16 bits
-
-`'
- - l --- 24 bits
-
- For example:
- 1 `movw $_myfun@c,r1'
-
- This loads the address of _myfun, shifted right by 1, into r1.
-
- 2 `movd $_myfun@c,(r2,r1)'
-
- This loads the address of _myfun, shifted right by 1, into register-pair r2-r1.
-
- 3 `_myfun_ptr:'
- `.long _myfun@c'
- `loadd _myfun_ptr, (r1,r0)'
- `jal (r1,r0)'
-
- This .long directive, the address of _myfunc, shifted right by 1 at link time.
-
-\1f
-File: as.info, Node: CRIS-Dependent, Next: D10V-Dependent, Prev: CR16-Dependent, Up: Machine Dependencies
-
-8.7 CRIS Dependent Features
-===========================
-
-* Menu:
-
-* CRIS-Opts:: Command-line Options
-* CRIS-Expand:: Instruction expansion
-* CRIS-Symbols:: Symbols
-* CRIS-Syntax:: Syntax
-
-\1f
-File: as.info, Node: CRIS-Opts, Next: CRIS-Expand, Up: CRIS-Dependent
-
-8.7.1 Command-line Options
---------------------------
-
-The CRIS version of `as' has these machine-dependent command-line
-options.
-
- The format of the generated object files can be either ELF or a.out,
-specified by the command-line options `--emulation=crisaout' and
-`--emulation=criself'. The default is ELF (criself), unless `as' has
-been configured specifically for a.out by using the configuration name
-`cris-axis-aout'.
-
- There are two different link-incompatible ELF object file variants
-for CRIS, for use in environments where symbols are expected to be
-prefixed by a leading `_' character and for environments without such a
-symbol prefix. The variant used for GNU/Linux port has no symbol
-prefix. Which variant to produce is specified by either of the options
-`--underscore' and `--no-underscore'. The default is `--underscore'.
-Since symbols in CRIS a.out objects are expected to have a `_' prefix,
-specifying `--no-underscore' when generating a.out objects is an error.
-Besides the object format difference, the effect of this option is to
-parse register names differently (*note crisnous::). The
-`--no-underscore' option makes a `$' register prefix mandatory.
-
- The option `--pic' must be passed to `as' in order to recognize the
-symbol syntax used for ELF (SVR4 PIC) position-independent-code (*note
-crispic::). This will also affect expansion of instructions. The
-expansion with `--pic' will use PC-relative rather than (slightly
-faster) absolute addresses in those expansions.
-
- The option `--march=ARCHITECTURE' specifies the recognized
-instruction set and recognized register names. It also controls the
-architecture type of the object file. Valid values for ARCHITECTURE
-are:
-`v0_v10'
- All instructions and register names for any architecture variant
- in the set v0...v10 are recognized. This is the default if the
- target is configured as cris-*.
-
-`v10'
- Only instructions and register names for CRIS v10 (as found in
- ETRAX 100 LX) are recognized. This is the default if the target
- is configured as crisv10-*.
-
-`v32'
- Only instructions and register names for CRIS v32 (code name
- Guinness) are recognized. This is the default if the target is
- configured as crisv32-*. This value implies `--no-mul-bug-abort'.
- (A subsequent `--mul-bug-abort' will turn it back on.)
-
-`common_v10_v32'
- Only instructions with register names and addressing modes with
- opcodes common to the v10 and v32 are recognized.
-
- When `-N' is specified, `as' will emit a warning when a 16-bit
-branch instruction is expanded into a 32-bit multiple-instruction
-construct (*note CRIS-Expand::).
-
- Some versions of the CRIS v10, for example in the Etrax 100 LX,
-contain a bug that causes destabilizing memory accesses when a multiply
-instruction is executed with certain values in the first operand just
-before a cache-miss. When the `--mul-bug-abort' command line option is
-active (the default value), `as' will refuse to assemble a file
-containing a multiply instruction at a dangerous offset, one that could
-be the last on a cache-line, or is in a section with insufficient
-alignment. This placement checking does not catch any case where the
-multiply instruction is dangerously placed because it is located in a
-delay-slot. The `--mul-bug-abort' command line option turns off the
-checking.
-
-\1f
-File: as.info, Node: CRIS-Expand, Next: CRIS-Symbols, Prev: CRIS-Opts, Up: CRIS-Dependent
-
-8.7.2 Instruction expansion
----------------------------
-
-`as' will silently choose an instruction that fits the operand size for
-`[register+constant]' operands. For example, the offset `127' in
-`move.d [r3+127],r4' fits in an instruction using a signed-byte offset.
-Similarly, `move.d [r2+32767],r1' will generate an instruction using a
-16-bit offset. For symbolic expressions and constants that do not fit
-in 16 bits including the sign bit, a 32-bit offset is generated.
-
- For branches, `as' will expand from a 16-bit branch instruction into
-a sequence of instructions that can reach a full 32-bit address. Since
-this does not correspond to a single instruction, such expansions can
-optionally be warned about. *Note CRIS-Opts::.
-
- If the operand is found to fit the range, a `lapc' mnemonic will
-translate to a `lapcq' instruction. Use `lapc.d' to force the 32-bit
-`lapc' instruction.
-
- Similarly, the `addo' mnemonic will translate to the shortest
-fitting instruction of `addoq', `addo.w' and `addo.d', when used with a
-operand that is a constant known at assembly time.
-
-\1f
-File: as.info, Node: CRIS-Symbols, Next: CRIS-Syntax, Prev: CRIS-Expand, Up: CRIS-Dependent
-
-8.7.3 Symbols
--------------
-
-Some symbols are defined by the assembler. They're intended to be used
-in conditional assembly, for example:
- .if ..asm.arch.cris.v32
- CODE FOR CRIS V32
- .elseif ..asm.arch.cris.common_v10_v32
- CODE COMMON TO CRIS V32 AND CRIS V10
- .elseif ..asm.arch.cris.v10 | ..asm.arch.cris.any_v0_v10
- CODE FOR V10
- .else
- .error "Code needs to be added here."
- .endif
-
- These symbols are defined in the assembler, reflecting command-line
-options, either when specified or the default. They are always
-defined, to 0 or 1.
-`..asm.arch.cris.any_v0_v10'
- This symbol is non-zero when `--march=v0_v10' is specified or the
- default.
-
-`..asm.arch.cris.common_v10_v32'
- Set according to the option `--march=common_v10_v32'.
-
-`..asm.arch.cris.v10'
- Reflects the option `--march=v10'.
-
-`..asm.arch.cris.v32'
- Corresponds to `--march=v10'.
-
- Speaking of symbols, when a symbol is used in code, it can have a
-suffix modifying its value for use in position-independent code. *Note
-CRIS-Pic::.
-
-\1f
-File: as.info, Node: CRIS-Syntax, Prev: CRIS-Symbols, Up: CRIS-Dependent
-
-8.7.4 Syntax
-------------
-
-There are different aspects of the CRIS assembly syntax.
-
-* Menu:
-
-* CRIS-Chars:: Special Characters
-* CRIS-Pic:: Position-Independent Code Symbols
-* CRIS-Regs:: Register Names
-* CRIS-Pseudos:: Assembler Directives
-
-\1f
-File: as.info, Node: CRIS-Chars, Next: CRIS-Pic, Up: CRIS-Syntax
-
-8.7.4.1 Special Characters
-..........................
-
-The character `#' is a line comment character. It starts a comment if
-and only if it is placed at the beginning of a line.
-
- A `;' character starts a comment anywhere on the line, causing all
-characters up to the end of the line to be ignored.
-
- A `@' character is handled as a line separator equivalent to a
-logical new-line character (except in a comment), so separate
-instructions can be specified on a single line.
-
-\1f
-File: as.info, Node: CRIS-Pic, Next: CRIS-Regs, Prev: CRIS-Chars, Up: CRIS-Syntax
-
-8.7.4.2 Symbols in position-independent code
-............................................
-
-When generating position-independent code (SVR4 PIC) for use in
-cris-axis-linux-gnu or crisv32-axis-linux-gnu shared libraries, symbol
-suffixes are used to specify what kind of run-time symbol lookup will
-be used, expressed in the object as different _relocation types_.
-Usually, all absolute symbol values must be located in a table, the
-_global offset table_, leaving the code position-independent;
-independent of values of global symbols and independent of the address
-of the code. The suffix modifies the value of the symbol, into for
-example an index into the global offset table where the real symbol
-value is entered, or a PC-relative value, or a value relative to the
-start of the global offset table. All symbol suffixes start with the
-character `:' (omitted in the list below). Every symbol use in code or
-a read-only section must therefore have a PIC suffix to enable a useful
-shared library to be created. Usually, these constructs must not be
-used with an additive constant offset as is usually allowed, i.e. no 4
-as in `symbol + 4' is allowed. This restriction is checked at
-link-time, not at assembly-time.
-
-`GOT'
- Attaching this suffix to a symbol in an instruction causes the
- symbol to be entered into the global offset table. The value is a
- 32-bit index for that symbol into the global offset table. The
- name of the corresponding relocation is `R_CRIS_32_GOT'. Example:
- `move.d [$r0+extsym:GOT],$r9'
-
-`GOT16'
- Same as for `GOT', but the value is a 16-bit index into the global
- offset table. The corresponding relocation is `R_CRIS_16_GOT'.
- Example: `move.d [$r0+asymbol:GOT16],$r10'
-
-`PLT'
- This suffix is used for function symbols. It causes a _procedure
- linkage table_, an array of code stubs, to be created at the time
- the shared object is created or linked against, together with a
- global offset table entry. The value is a pc-relative offset to
- the corresponding stub code in the procedure linkage table. This
- arrangement causes the run-time symbol resolver to be called to
- look up and set the value of the symbol the first time the
- function is called (at latest; depending environment variables).
- It is only safe to leave the symbol unresolved this way if all
- references are function calls. The name of the relocation is
- `R_CRIS_32_PLT_PCREL'. Example: `add.d fnname:PLT,$pc'
-
-`PLTG'
- Like PLT, but the value is relative to the beginning of the global
- offset table. The relocation is `R_CRIS_32_PLT_GOTREL'. Example:
- `move.d fnname:PLTG,$r3'
-
-`GOTPLT'
- Similar to `PLT', but the value of the symbol is a 32-bit index
- into the global offset table. This is somewhat of a mix between
- the effect of the `GOT' and the `PLT' suffix; the difference to
- `GOT' is that there will be a procedure linkage table entry
- created, and that the symbol is assumed to be a function entry and
- will be resolved by the run-time resolver as with `PLT'. The
- relocation is `R_CRIS_32_GOTPLT'. Example: `jsr
- [$r0+fnname:GOTPLT]'
-
-`GOTPLT16'
- A variant of `GOTPLT' giving a 16-bit value. Its relocation name
- is `R_CRIS_16_GOTPLT'. Example: `jsr [$r0+fnname:GOTPLT16]'
-
-`GOTOFF'
- This suffix must only be attached to a local symbol, but may be
- used in an expression adding an offset. The value is the address
- of the symbol relative to the start of the global offset table.
- The relocation name is `R_CRIS_32_GOTREL'. Example: `move.d
- [$r0+localsym:GOTOFF],r3'
-
-\1f
-File: as.info, Node: CRIS-Regs, Next: CRIS-Pseudos, Prev: CRIS-Pic, Up: CRIS-Syntax
-
-8.7.4.3 Register names
-......................
-
-A `$' character may always prefix a general or special register name in
-an instruction operand but is mandatory when the option
-`--no-underscore' is specified or when the `.syntax register_prefix'
-directive is in effect (*note crisnous::). Register names are
-case-insensitive.
-
-\1f
-File: as.info, Node: CRIS-Pseudos, Prev: CRIS-Regs, Up: CRIS-Syntax
-
-8.7.4.4 Assembler Directives
-............................
-
-There are a few CRIS-specific pseudo-directives in addition to the
-generic ones. *Note Pseudo Ops::. Constants emitted by
-pseudo-directives are in little-endian order for CRIS. There is no
-support for floating-point-specific directives for CRIS.
-
-`.dword EXPRESSIONS'
- The `.dword' directive is a synonym for `.int', expecting zero or
- more EXPRESSIONS, separated by commas. For each expression, a
- 32-bit little-endian constant is emitted.
-
-`.syntax ARGUMENT'
- The `.syntax' directive takes as ARGUMENT one of the following
- case-sensitive choices.
-
- `no_register_prefix'
- The `.syntax no_register_prefix' directive makes a `$'
- character prefix on all registers optional. It overrides a
- previous setting, including the corresponding effect of the
- option `--no-underscore'. If this directive is used when
- ordinary symbols do not have a `_' character prefix, care
- must be taken to avoid ambiguities whether an operand is a
- register or a symbol; using symbols with names the same as
- general or special registers then invoke undefined behavior.
-
- `register_prefix'
- This directive makes a `$' character prefix on all registers
- mandatory. It overrides a previous setting, including the
- corresponding effect of the option `--underscore'.
-
- `leading_underscore'
- This is an assertion directive, emitting an error if the
- `--no-underscore' option is in effect.
-
- `no_leading_underscore'
- This is the opposite of the `.syntax leading_underscore'
- directive and emits an error if the option `--underscore' is
- in effect.
-
-`.arch ARGUMENT'
- This is an assertion directive, giving an error if the specified
- ARGUMENT is not the same as the specified or default value for the
- `--march=ARCHITECTURE' option (*note march-option::).
-
-
-\1f
-File: as.info, Node: D10V-Dependent, Next: D30V-Dependent, Prev: CRIS-Dependent, Up: Machine Dependencies
-
-8.8 D10V Dependent Features
-===========================
-
-* Menu:
-
-* D10V-Opts:: D10V Options
-* D10V-Syntax:: Syntax
-* D10V-Float:: Floating Point
-* D10V-Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: D10V-Opts, Next: D10V-Syntax, Up: D10V-Dependent
-
-8.8.1 D10V Options
-------------------
-
-The Mitsubishi D10V version of `as' has a few machine dependent options.
-
-`-O'
- The D10V can often execute two sub-instructions in parallel. When
- this option is used, `as' will attempt to optimize its output by
- detecting when instructions can be executed in parallel.
-
-`--nowarnswap'
- To optimize execution performance, `as' will sometimes swap the
- order of instructions. Normally this generates a warning. When
- this option is used, no warning will be generated when
- instructions are swapped.
-
-`--gstabs-packing'
-
-`--no-gstabs-packing'
- `as' packs adjacent short instructions into a single packed
- instruction. `--no-gstabs-packing' turns instruction packing off if
- `--gstabs' is specified as well; `--gstabs-packing' (the default)
- turns instruction packing on even when `--gstabs' is specified.
-
-\1f
-File: as.info, Node: D10V-Syntax, Next: D10V-Float, Prev: D10V-Opts, Up: D10V-Dependent
-
-8.8.2 Syntax
-------------
-
-The D10V syntax is based on the syntax in Mitsubishi's D10V
-architecture manual. The differences are detailed below.
-
-* Menu:
-
-* D10V-Size:: Size Modifiers
-* D10V-Subs:: Sub-Instructions
-* D10V-Chars:: Special Characters
-* D10V-Regs:: Register Names
-* D10V-Addressing:: Addressing Modes
-* D10V-Word:: @WORD Modifier
-
-\1f
-File: as.info, Node: D10V-Size, Next: D10V-Subs, Up: D10V-Syntax
-
-8.8.2.1 Size Modifiers
-......................
-
-The D10V version of `as' uses the instruction names in the D10V
-Architecture Manual. However, the names in the manual are sometimes
-ambiguous. There are instruction names that can assemble to a short or
-long form opcode. How does the assembler pick the correct form? `as'
-will always pick the smallest form if it can. When dealing with a
-symbol that is not defined yet when a line is being assembled, it will
-always use the long form. If you need to force the assembler to use
-either the short or long form of the instruction, you can append either
-`.s' (short) or `.l' (long) to it. For example, if you are writing an
-assembly program and you want to do a branch to a symbol that is
-defined later in your program, you can write `bra.s foo'. Objdump
-and GDB will always append `.s' or `.l' to instructions which have both
-short and long forms.
-
-\1f
-File: as.info, Node: D10V-Subs, Next: D10V-Chars, Prev: D10V-Size, Up: D10V-Syntax
-
-8.8.2.2 Sub-Instructions
-........................
-
-The D10V assembler takes as input a series of instructions, either
-one-per-line, or in the special two-per-line format described in the
-next section. Some of these instructions will be short-form or
-sub-instructions. These sub-instructions can be packed into a single
-instruction. The assembler will do this automatically. It will also
-detect when it should not pack instructions. For example, when a label
-is defined, the next instruction will never be packaged with the
-previous one. Whenever a branch and link instruction is called, it
-will not be packaged with the next instruction so the return address
-will be valid. Nops are automatically inserted when necessary.
-
- If you do not want the assembler automatically making these
-decisions, you can control the packaging and execution type (parallel
-or sequential) with the special execution symbols described in the next
-section.
-
-\1f
-File: as.info, Node: D10V-Chars, Next: D10V-Regs, Prev: D10V-Subs, Up: D10V-Syntax
-
-8.8.2.3 Special Characters
-..........................
-
-`;' and `#' are the line comment characters. Sub-instructions may be
-executed in order, in reverse-order, or in parallel. Instructions
-listed in the standard one-per-line format will be executed
-sequentially. To specify the executing order, use the following
-symbols:
-`->'
- Sequential with instruction on the left first.
-
-`<-'
- Sequential with instruction on the right first.
-
-`||'
- Parallel
- The D10V syntax allows either one instruction per line, one
-instruction per line with the execution symbol, or two instructions per
-line. For example
-`abs a1 -> abs r0'
- Execute these sequentially. The instruction on the right is in
- the right container and is executed second.
-
-`abs r0 <- abs a1'
- Execute these reverse-sequentially. The instruction on the right
- is in the right container, and is executed first.
-
-`ld2w r2,@r8+ || mac a0,r0,r7'
- Execute these in parallel.
-
-`ld2w r2,@r8+ ||'
-`mac a0,r0,r7'
- Two-line format. Execute these in parallel.
-
-`ld2w r2,@r8+'
-`mac a0,r0,r7'
- Two-line format. Execute these sequentially. Assembler will put
- them in the proper containers.
-
-`ld2w r2,@r8+ ->'
-`mac a0,r0,r7'
- Two-line format. Execute these sequentially. Same as above but
- second instruction will always go into right container.
- Since `$' has no special meaning, you may use it in symbol names.
-
-\1f
-File: as.info, Node: D10V-Regs, Next: D10V-Addressing, Prev: D10V-Chars, Up: D10V-Syntax
-
-8.8.2.4 Register Names
-......................
-
-You can use the predefined symbols `r0' through `r15' to refer to the
-D10V registers. You can also use `sp' as an alias for `r15'. The
-accumulators are `a0' and `a1'. There are special register-pair names
-that may optionally be used in opcodes that require even-numbered
-registers. Register names are not case sensitive.
-
- Register Pairs
-`r0-r1'
-
-`r2-r3'
-
-`r4-r5'
-
-`r6-r7'
-
-`r8-r9'
-
-`r10-r11'
-
-`r12-r13'
-
-`r14-r15'
-
- The D10V also has predefined symbols for these control registers and
-status bits:
-`psw'
- Processor Status Word
-
-`bpsw'
- Backup Processor Status Word
-
-`pc'
- Program Counter
-
-`bpc'
- Backup Program Counter
-
-`rpt_c'
- Repeat Count
-
-`rpt_s'
- Repeat Start address
-
-`rpt_e'
- Repeat End address
-
-`mod_s'
- Modulo Start address
-
-`mod_e'
- Modulo End address
-
-`iba'
- Instruction Break Address
-
-`f0'
- Flag 0
-
-`f1'
- Flag 1
-
-`c'
- Carry flag
-
-\1f
-File: as.info, Node: D10V-Addressing, Next: D10V-Word, Prev: D10V-Regs, Up: D10V-Syntax
-
-8.8.2.5 Addressing Modes
-........................
-
-`as' understands the following addressing modes for the D10V. `RN' in
-the following refers to any of the numbered registers, but _not_ the
-control registers.
-`RN'
- Register direct
-
-`@RN'
- Register indirect
-
-`@RN+'
- Register indirect with post-increment
-
-`@RN-'
- Register indirect with post-decrement
-
-`@-SP'
- Register indirect with pre-decrement
-
-`@(DISP, RN)'
- Register indirect with displacement
-
-`ADDR'
- PC relative address (for branch or rep).
-
-`#IMM'
- Immediate data (the `#' is optional and ignored)
-
-\1f
-File: as.info, Node: D10V-Word, Prev: D10V-Addressing, Up: D10V-Syntax
-
-8.8.2.6 @WORD Modifier
-......................
-
-Any symbol followed by `@word' will be replaced by the symbol's value
-shifted right by 2. This is used in situations such as loading a
-register with the address of a function (or any other code fragment).
-For example, if you want to load a register with the location of the
-function `main' then jump to that function, you could do it as follows:
- ldi r2, main@word
- jmp r2
-
-\1f
-File: as.info, Node: D10V-Float, Next: D10V-Opcodes, Prev: D10V-Syntax, Up: D10V-Dependent
-
-8.8.3 Floating Point
---------------------
-
-The D10V has no hardware floating point, but the `.float' and `.double'
-directives generates IEEE floating-point numbers for compatibility with
-other development tools.
-
-\1f
-File: as.info, Node: D10V-Opcodes, Prev: D10V-Float, Up: D10V-Dependent
-
-8.8.4 Opcodes
--------------
-
-For detailed information on the D10V machine instruction set, see `D10V
-Architecture: A VLIW Microprocessor for Multimedia Applications'
-(Mitsubishi Electric Corp.). `as' implements all the standard D10V
-opcodes. The only changes are those described in the section on size
-modifiers
-
-\1f
-File: as.info, Node: D30V-Dependent, Next: H8/300-Dependent, Prev: D10V-Dependent, Up: Machine Dependencies
-
-8.9 D30V Dependent Features
-===========================
-
-* Menu:
-
-* D30V-Opts:: D30V Options
-* D30V-Syntax:: Syntax
-* D30V-Float:: Floating Point
-* D30V-Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: D30V-Opts, Next: D30V-Syntax, Up: D30V-Dependent
-
-8.9.1 D30V Options
-------------------
-
-The Mitsubishi D30V version of `as' has a few machine dependent options.
-
-`-O'
- The D30V can often execute two sub-instructions in parallel. When
- this option is used, `as' will attempt to optimize its output by
- detecting when instructions can be executed in parallel.
-
-`-n'
- When this option is used, `as' will issue a warning every time it
- adds a nop instruction.
-
-`-N'
- When this option is used, `as' will issue a warning if it needs to
- insert a nop after a 32-bit multiply before a load or 16-bit
- multiply instruction.
-
-\1f
-File: as.info, Node: D30V-Syntax, Next: D30V-Float, Prev: D30V-Opts, Up: D30V-Dependent
-
-8.9.2 Syntax
-------------
-
-The D30V syntax is based on the syntax in Mitsubishi's D30V
-architecture manual. The differences are detailed below.
-
-* Menu:
-
-* D30V-Size:: Size Modifiers
-* D30V-Subs:: Sub-Instructions
-* D30V-Chars:: Special Characters
-* D30V-Guarded:: Guarded Execution
-* D30V-Regs:: Register Names
-* D30V-Addressing:: Addressing Modes
-
-\1f
-File: as.info, Node: D30V-Size, Next: D30V-Subs, Up: D30V-Syntax
-
-8.9.2.1 Size Modifiers
-......................
-
-The D30V version of `as' uses the instruction names in the D30V
-Architecture Manual. However, the names in the manual are sometimes
-ambiguous. There are instruction names that can assemble to a short or
-long form opcode. How does the assembler pick the correct form? `as'
-will always pick the smallest form if it can. When dealing with a
-symbol that is not defined yet when a line is being assembled, it will
-always use the long form. If you need to force the assembler to use
-either the short or long form of the instruction, you can append either
-`.s' (short) or `.l' (long) to it. For example, if you are writing an
-assembly program and you want to do a branch to a symbol that is
-defined later in your program, you can write `bra.s foo'. Objdump and
-GDB will always append `.s' or `.l' to instructions which have both
-short and long forms.
-
-\1f
-File: as.info, Node: D30V-Subs, Next: D30V-Chars, Prev: D30V-Size, Up: D30V-Syntax
-
-8.9.2.2 Sub-Instructions
-........................
-
-The D30V assembler takes as input a series of instructions, either
-one-per-line, or in the special two-per-line format described in the
-next section. Some of these instructions will be short-form or
-sub-instructions. These sub-instructions can be packed into a single
-instruction. The assembler will do this automatically. It will also
-detect when it should not pack instructions. For example, when a label
-is defined, the next instruction will never be packaged with the
-previous one. Whenever a branch and link instruction is called, it
-will not be packaged with the next instruction so the return address
-will be valid. Nops are automatically inserted when necessary.
-
- If you do not want the assembler automatically making these
-decisions, you can control the packaging and execution type (parallel
-or sequential) with the special execution symbols described in the next
-section.
-
-\1f
-File: as.info, Node: D30V-Chars, Next: D30V-Guarded, Prev: D30V-Subs, Up: D30V-Syntax
-
-8.9.2.3 Special Characters
-..........................
-
-`;' and `#' are the line comment characters. Sub-instructions may be
-executed in order, in reverse-order, or in parallel. Instructions
-listed in the standard one-per-line format will be executed
-sequentially unless you use the `-O' option.
-
- To specify the executing order, use the following symbols:
-`->'
- Sequential with instruction on the left first.
-
-`<-'
- Sequential with instruction on the right first.
-
-`||'
- Parallel
-
- The D30V syntax allows either one instruction per line, one
-instruction per line with the execution symbol, or two instructions per
-line. For example
-`abs r2,r3 -> abs r4,r5'
- Execute these sequentially. The instruction on the right is in
- the right container and is executed second.
-
-`abs r2,r3 <- abs r4,r5'
- Execute these reverse-sequentially. The instruction on the right
- is in the right container, and is executed first.
-
-`abs r2,r3 || abs r4,r5'
- Execute these in parallel.
-
-`ldw r2,@(r3,r4) ||'
-`mulx r6,r8,r9'
- Two-line format. Execute these in parallel.
-
-`mulx a0,r8,r9'
-`stw r2,@(r3,r4)'
- Two-line format. Execute these sequentially unless `-O' option is
- used. If the `-O' option is used, the assembler will determine if
- the instructions could be done in parallel (the above two
- instructions can be done in parallel), and if so, emit them as
- parallel instructions. The assembler will put them in the proper
- containers. In the above example, the assembler will put the
- `stw' instruction in left container and the `mulx' instruction in
- the right container.
-
-`stw r2,@(r3,r4) ->'
-`mulx a0,r8,r9'
- Two-line format. Execute the `stw' instruction followed by the
- `mulx' instruction sequentially. The first instruction goes in the
- left container and the second instruction goes into right
- container. The assembler will give an error if the machine
- ordering constraints are violated.
-
-`stw r2,@(r3,r4) <-'
-`mulx a0,r8,r9'
- Same as previous example, except that the `mulx' instruction is
- executed before the `stw' instruction.
-
- Since `$' has no special meaning, you may use it in symbol names.
-
-\1f
-File: as.info, Node: D30V-Guarded, Next: D30V-Regs, Prev: D30V-Chars, Up: D30V-Syntax
-
-8.9.2.4 Guarded Execution
-.........................
-
-`as' supports the full range of guarded execution directives for each
-instruction. Just append the directive after the instruction proper.
-The directives are:
-
-`/tx'
- Execute the instruction if flag f0 is true.
-
-`/fx'
- Execute the instruction if flag f0 is false.
-
-`/xt'
- Execute the instruction if flag f1 is true.
-
-`/xf'
- Execute the instruction if flag f1 is false.
-
-`/tt'
- Execute the instruction if both flags f0 and f1 are true.
-
-`/tf'
- Execute the instruction if flag f0 is true and flag f1 is false.
-
-\1f
-File: as.info, Node: D30V-Regs, Next: D30V-Addressing, Prev: D30V-Guarded, Up: D30V-Syntax
-
-8.9.2.5 Register Names
-......................
-
-You can use the predefined symbols `r0' through `r63' to refer to the
-D30V registers. You can also use `sp' as an alias for `r63' and `link'
-as an alias for `r62'. The accumulators are `a0' and `a1'.
-
- The D30V also has predefined symbols for these control registers and
-status bits:
-`psw'
- Processor Status Word
-
-`bpsw'
- Backup Processor Status Word
-
-`pc'
- Program Counter
-
-`bpc'
- Backup Program Counter
-
-`rpt_c'
- Repeat Count
-
-`rpt_s'
- Repeat Start address
-
-`rpt_e'
- Repeat End address
-
-`mod_s'
- Modulo Start address
-
-`mod_e'
- Modulo End address
-
-`iba'
- Instruction Break Address
-
-`f0'
- Flag 0
-
-`f1'
- Flag 1
-
-`f2'
- Flag 2
-
-`f3'
- Flag 3
-
-`f4'
- Flag 4
-
-`f5'
- Flag 5
-
-`f6'
- Flag 6
-
-`f7'
- Flag 7
-
-`s'
- Same as flag 4 (saturation flag)
-
-`v'
- Same as flag 5 (overflow flag)
-
-`va'
- Same as flag 6 (sticky overflow flag)
-
-`c'
- Same as flag 7 (carry/borrow flag)
-
-`b'
- Same as flag 7 (carry/borrow flag)
-
-\1f
-File: as.info, Node: D30V-Addressing, Prev: D30V-Regs, Up: D30V-Syntax
-
-8.9.2.6 Addressing Modes
-........................
-
-`as' understands the following addressing modes for the D30V. `RN' in
-the following refers to any of the numbered registers, but _not_ the
-control registers.
-`RN'
- Register direct
-
-`@RN'
- Register indirect
-
-`@RN+'
- Register indirect with post-increment
-
-`@RN-'
- Register indirect with post-decrement
-
-`@-SP'
- Register indirect with pre-decrement
-
-`@(DISP, RN)'
- Register indirect with displacement
-
-`ADDR'
- PC relative address (for branch or rep).
-
-`#IMM'
- Immediate data (the `#' is optional and ignored)
-
-\1f
-File: as.info, Node: D30V-Float, Next: D30V-Opcodes, Prev: D30V-Syntax, Up: D30V-Dependent
-
-8.9.3 Floating Point
---------------------
-
-The D30V has no hardware floating point, but the `.float' and `.double'
-directives generates IEEE floating-point numbers for compatibility with
-other development tools.
-
-\1f
-File: as.info, Node: D30V-Opcodes, Prev: D30V-Float, Up: D30V-Dependent
-
-8.9.4 Opcodes
--------------
-
-For detailed information on the D30V machine instruction set, see `D30V
-Architecture: A VLIW Microprocessor for Multimedia Applications'
-(Mitsubishi Electric Corp.). `as' implements all the standard D30V
-opcodes. The only changes are those described in the section on size
-modifiers
-
-\1f
-File: as.info, Node: H8/300-Dependent, Next: HPPA-Dependent, Prev: D30V-Dependent, Up: Machine Dependencies
-
-8.10 H8/300 Dependent Features
-==============================
-
-* Menu:
-
-* H8/300 Options:: Options
-* H8/300 Syntax:: Syntax
-* H8/300 Floating Point:: Floating Point
-* H8/300 Directives:: H8/300 Machine Directives
-* H8/300 Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: H8/300 Options, Next: H8/300 Syntax, Up: H8/300-Dependent
-
-8.10.1 Options
---------------
-
-`as' has no additional command-line options for the Renesas (formerly
-Hitachi) H8/300 family.
-
-\1f
-File: as.info, Node: H8/300 Syntax, Next: H8/300 Floating Point, Prev: H8/300 Options, Up: H8/300-Dependent
-
-8.10.2 Syntax
--------------
-
-* Menu:
-
-* H8/300-Chars:: Special Characters
-* H8/300-Regs:: Register Names
-* H8/300-Addressing:: Addressing Modes
-
-\1f
-File: as.info, Node: H8/300-Chars, Next: H8/300-Regs, Up: H8/300 Syntax
-
-8.10.2.1 Special Characters
-...........................
-
-`;' is the line comment character.
-
- `$' can be used instead of a newline to separate statements.
-Therefore _you may not use `$' in symbol names_ on the H8/300.
-
-\1f
-File: as.info, Node: H8/300-Regs, Next: H8/300-Addressing, Prev: H8/300-Chars, Up: H8/300 Syntax
-
-8.10.2.2 Register Names
-.......................
-
-You can use predefined symbols of the form `rNh' and `rNl' to refer to
-the H8/300 registers as sixteen 8-bit general-purpose registers. N is
-a digit from `0' to `7'); for instance, both `r0h' and `r7l' are valid
-register names.
-
- You can also use the eight predefined symbols `rN' to refer to the
-H8/300 registers as 16-bit registers (you must use this form for
-addressing).
-
- On the H8/300H, you can also use the eight predefined symbols `erN'
-(`er0' ... `er7') to refer to the 32-bit general purpose registers.
-
- The two control registers are called `pc' (program counter; a 16-bit
-register, except on the H8/300H where it is 24 bits) and `ccr'
-(condition code register; an 8-bit register). `r7' is used as the
-stack pointer, and can also be called `sp'.
-
-\1f
-File: as.info, Node: H8/300-Addressing, Prev: H8/300-Regs, Up: H8/300 Syntax
-
-8.10.2.3 Addressing Modes
-.........................
-
-as understands the following addressing modes for the H8/300:
-`rN'
- Register direct
-
-`@rN'
- Register indirect
-
-`@(D, rN)'
-`@(D:16, rN)'
-`@(D:24, rN)'
- Register indirect: 16-bit or 24-bit displacement D from register
- N. (24-bit displacements are only meaningful on the H8/300H.)
-
-`@rN+'
- Register indirect with post-increment
-
-`@-rN'
- Register indirect with pre-decrement
-
-``@'AA'
-``@'AA:8'
-``@'AA:16'
-``@'AA:24'
- Absolute address `aa'. (The address size `:24' only makes sense
- on the H8/300H.)
-
-`#XX'
-`#XX:8'
-`#XX:16'
-`#XX:32'
- Immediate data XX. You may specify the `:8', `:16', or `:32' for
- clarity, if you wish; but `as' neither requires this nor uses
- it--the data size required is taken from context.
-
-``@'`@'AA'
-``@'`@'AA:8'
- Memory indirect. You may specify the `:8' for clarity, if you
- wish; but `as' neither requires this nor uses it.
-
-\1f
-File: as.info, Node: H8/300 Floating Point, Next: H8/300 Directives, Prev: H8/300 Syntax, Up: H8/300-Dependent
-
-8.10.3 Floating Point
----------------------
-
-The H8/300 family has no hardware floating point, but the `.float'
-directive generates IEEE floating-point numbers for compatibility with
-other development tools.
-
-\1f
-File: as.info, Node: H8/300 Directives, Next: H8/300 Opcodes, Prev: H8/300 Floating Point, Up: H8/300-Dependent
-
-8.10.4 H8/300 Machine Directives
---------------------------------
-
-`as' has the following machine-dependent directives for the H8/300:
-
-`.h8300h'
- Recognize and emit additional instructions for the H8/300H
- variant, and also make `.int' emit 32-bit numbers rather than the
- usual (16-bit) for the H8/300 family.
-
-`.h8300s'
- Recognize and emit additional instructions for the H8S variant, and
- also make `.int' emit 32-bit numbers rather than the usual (16-bit)
- for the H8/300 family.
-
-`.h8300hn'
- Recognize and emit additional instructions for the H8/300H variant
- in normal mode, and also make `.int' emit 32-bit numbers rather
- than the usual (16-bit) for the H8/300 family.
-
-`.h8300sn'
- Recognize and emit additional instructions for the H8S variant in
- normal mode, and also make `.int' emit 32-bit numbers rather than
- the usual (16-bit) for the H8/300 family.
-
- On the H8/300 family (including the H8/300H) `.word' directives
-generate 16-bit numbers.
-
-\1f
-File: as.info, Node: H8/300 Opcodes, Prev: H8/300 Directives, Up: H8/300-Dependent
-
-8.10.5 Opcodes
---------------
-
-For detailed information on the H8/300 machine instruction set, see
-`H8/300 Series Programming Manual'. For information specific to the
-H8/300H, see `H8/300H Series Programming Manual' (Renesas).
-
- `as' implements all the standard H8/300 opcodes. No additional
-pseudo-instructions are needed on this family.
-
- The following table summarizes the H8/300 opcodes, and their
-arguments. Entries marked `*' are opcodes used only on the H8/300H.
-
- Legend:
- Rs source register
- Rd destination register
- abs absolute address
- imm immediate data
- disp:N N-bit displacement from a register
- pcrel:N N-bit displacement relative to program counter
-
- add.b #imm,rd * andc #imm,ccr
- add.b rs,rd band #imm,rd
- add.w rs,rd band #imm,@rd
- * add.w #imm,rd band #imm,@abs:8
- * add.l rs,rd bra pcrel:8
- * add.l #imm,rd * bra pcrel:16
- adds #imm,rd bt pcrel:8
- addx #imm,rd * bt pcrel:16
- addx rs,rd brn pcrel:8
- and.b #imm,rd * brn pcrel:16
- and.b rs,rd bf pcrel:8
- * and.w rs,rd * bf pcrel:16
- * and.w #imm,rd bhi pcrel:8
- * and.l #imm,rd * bhi pcrel:16
- * and.l rs,rd bls pcrel:8
-
- * bls pcrel:16 bld #imm,rd
- bcc pcrel:8 bld #imm,@rd
- * bcc pcrel:16 bld #imm,@abs:8
- bhs pcrel:8 bnot #imm,rd
- * bhs pcrel:16 bnot #imm,@rd
- bcs pcrel:8 bnot #imm,@abs:8
- * bcs pcrel:16 bnot rs,rd
- blo pcrel:8 bnot rs,@rd
- * blo pcrel:16 bnot rs,@abs:8
- bne pcrel:8 bor #imm,rd
- * bne pcrel:16 bor #imm,@rd
- beq pcrel:8 bor #imm,@abs:8
- * beq pcrel:16 bset #imm,rd
- bvc pcrel:8 bset #imm,@rd
- * bvc pcrel:16 bset #imm,@abs:8
- bvs pcrel:8 bset rs,rd
- * bvs pcrel:16 bset rs,@rd
- bpl pcrel:8 bset rs,@abs:8
- * bpl pcrel:16 bsr pcrel:8
- bmi pcrel:8 bsr pcrel:16
- * bmi pcrel:16 bst #imm,rd
- bge pcrel:8 bst #imm,@rd
- * bge pcrel:16 bst #imm,@abs:8
- blt pcrel:8 btst #imm,rd
- * blt pcrel:16 btst #imm,@rd
- bgt pcrel:8 btst #imm,@abs:8
- * bgt pcrel:16 btst rs,rd
- ble pcrel:8 btst rs,@rd
- * ble pcrel:16 btst rs,@abs:8
- bclr #imm,rd bxor #imm,rd
- bclr #imm,@rd bxor #imm,@rd
- bclr #imm,@abs:8 bxor #imm,@abs:8
- bclr rs,rd cmp.b #imm,rd
- bclr rs,@rd cmp.b rs,rd
- bclr rs,@abs:8 cmp.w rs,rd
- biand #imm,rd cmp.w rs,rd
- biand #imm,@rd * cmp.w #imm,rd
- biand #imm,@abs:8 * cmp.l #imm,rd
- bild #imm,rd * cmp.l rs,rd
- bild #imm,@rd daa rs
- bild #imm,@abs:8 das rs
- bior #imm,rd dec.b rs
- bior #imm,@rd * dec.w #imm,rd
- bior #imm,@abs:8 * dec.l #imm,rd
- bist #imm,rd divxu.b rs,rd
- bist #imm,@rd * divxu.w rs,rd
- bist #imm,@abs:8 * divxs.b rs,rd
- bixor #imm,rd * divxs.w rs,rd
- bixor #imm,@rd eepmov
- bixor #imm,@abs:8 * eepmovw
-
- * exts.w rd mov.w rs,@abs:16
- * exts.l rd * mov.l #imm,rd
- * extu.w rd * mov.l rs,rd
- * extu.l rd * mov.l @rs,rd
- inc rs * mov.l @(disp:16,rs),rd
- * inc.w #imm,rd * mov.l @(disp:24,rs),rd
- * inc.l #imm,rd * mov.l @rs+,rd
- jmp @rs * mov.l @abs:16,rd
- jmp abs * mov.l @abs:24,rd
- jmp @@abs:8 * mov.l rs,@rd
- jsr @rs * mov.l rs,@(disp:16,rd)
- jsr abs * mov.l rs,@(disp:24,rd)
- jsr @@abs:8 * mov.l rs,@-rd
- ldc #imm,ccr * mov.l rs,@abs:16
- ldc rs,ccr * mov.l rs,@abs:24
- * ldc @abs:16,ccr movfpe @abs:16,rd
- * ldc @abs:24,ccr movtpe rs,@abs:16
- * ldc @(disp:16,rs),ccr mulxu.b rs,rd
- * ldc @(disp:24,rs),ccr * mulxu.w rs,rd
- * ldc @rs+,ccr * mulxs.b rs,rd
- * ldc @rs,ccr * mulxs.w rs,rd
- * mov.b @(disp:24,rs),rd neg.b rs
- * mov.b rs,@(disp:24,rd) * neg.w rs
- mov.b @abs:16,rd * neg.l rs
- mov.b rs,rd nop
- mov.b @abs:8,rd not.b rs
- mov.b rs,@abs:8 * not.w rs
- mov.b rs,rd * not.l rs
- mov.b #imm,rd or.b #imm,rd
- mov.b @rs,rd or.b rs,rd
- mov.b @(disp:16,rs),rd * or.w #imm,rd
- mov.b @rs+,rd * or.w rs,rd
- mov.b @abs:8,rd * or.l #imm,rd
- mov.b rs,@rd * or.l rs,rd
- mov.b rs,@(disp:16,rd) orc #imm,ccr
- mov.b rs,@-rd pop.w rs
- mov.b rs,@abs:8 * pop.l rs
- mov.w rs,@rd push.w rs
- * mov.w @(disp:24,rs),rd * push.l rs
- * mov.w rs,@(disp:24,rd) rotl.b rs
- * mov.w @abs:24,rd * rotl.w rs
- * mov.w rs,@abs:24 * rotl.l rs
- mov.w rs,rd rotr.b rs
- mov.w #imm,rd * rotr.w rs
- mov.w @rs,rd * rotr.l rs
- mov.w @(disp:16,rs),rd rotxl.b rs
- mov.w @rs+,rd * rotxl.w rs
- mov.w @abs:16,rd * rotxl.l rs
- mov.w rs,@(disp:16,rd) rotxr.b rs
- mov.w rs,@-rd * rotxr.w rs
-
- * rotxr.l rs * stc ccr,@(disp:24,rd)
- bpt * stc ccr,@-rd
- rte * stc ccr,@abs:16
- rts * stc ccr,@abs:24
- shal.b rs sub.b rs,rd
- * shal.w rs sub.w rs,rd
- * shal.l rs * sub.w #imm,rd
- shar.b rs * sub.l rs,rd
- * shar.w rs * sub.l #imm,rd
- * shar.l rs subs #imm,rd
- shll.b rs subx #imm,rd
- * shll.w rs subx rs,rd
- * shll.l rs * trapa #imm
- shlr.b rs xor #imm,rd
- * shlr.w rs xor rs,rd
- * shlr.l rs * xor.w #imm,rd
- sleep * xor.w rs,rd
- stc ccr,rd * xor.l #imm,rd
- * stc ccr,@rs * xor.l rs,rd
- * stc ccr,@(disp:16,rd) xorc #imm,ccr
-
- Four H8/300 instructions (`add', `cmp', `mov', `sub') are defined
-with variants using the suffixes `.b', `.w', and `.l' to specify the
-size of a memory operand. `as' supports these suffixes, but does not
-require them; since one of the operands is always a register, `as' can
-deduce the correct size.
-
- For example, since `r0' refers to a 16-bit register,
- mov r0,@foo
-is equivalent to
- mov.w r0,@foo
-
- If you use the size suffixes, `as' issues a warning when the suffix
-and the register size do not match.
-
-\1f
-File: as.info, Node: HPPA-Dependent, Next: ESA/390-Dependent, Prev: H8/300-Dependent, Up: Machine Dependencies
-
-8.11 HPPA Dependent Features
-============================
-
-* Menu:
-
-* HPPA Notes:: Notes
-* HPPA Options:: Options
-* HPPA Syntax:: Syntax
-* HPPA Floating Point:: Floating Point
-* HPPA Directives:: HPPA Machine Directives
-* HPPA Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: HPPA Notes, Next: HPPA Options, Up: HPPA-Dependent
-
-8.11.1 Notes
-------------
-
-As a back end for GNU CC `as' has been throughly tested and should work
-extremely well. We have tested it only minimally on hand written
-assembly code and no one has tested it much on the assembly output from
-the HP compilers.
-
- The format of the debugging sections has changed since the original
-`as' port (version 1.3X) was released; therefore, you must rebuild all
-HPPA objects and libraries with the new assembler so that you can debug
-the final executable.
-
- The HPPA `as' port generates a small subset of the relocations
-available in the SOM and ELF object file formats. Additional relocation
-support will be added as it becomes necessary.
-
-\1f
-File: as.info, Node: HPPA Options, Next: HPPA Syntax, Prev: HPPA Notes, Up: HPPA-Dependent
-
-8.11.2 Options
---------------
-
-`as' has no machine-dependent command-line options for the HPPA.
-
-\1f
-File: as.info, Node: HPPA Syntax, Next: HPPA Floating Point, Prev: HPPA Options, Up: HPPA-Dependent
-
-8.11.3 Syntax
--------------
-
-The assembler syntax closely follows the HPPA instruction set reference
-manual; assembler directives and general syntax closely follow the HPPA
-assembly language reference manual, with a few noteworthy differences.
-
- First, a colon may immediately follow a label definition. This is
-simply for compatibility with how most assembly language programmers
-write code.
-
- Some obscure expression parsing problems may affect hand written
-code which uses the `spop' instructions, or code which makes significant
-use of the `!' line separator.
-
- `as' is much less forgiving about missing arguments and other
-similar oversights than the HP assembler. `as' notifies you of missing
-arguments as syntax errors; this is regarded as a feature, not a bug.
-
- Finally, `as' allows you to use an external symbol without
-explicitly importing the symbol. _Warning:_ in the future this will be
-an error for HPPA targets.
-
- Special characters for HPPA targets include:
-
- `;' is the line comment character.
-
- `!' can be used instead of a newline to separate statements.
-
- Since `$' has no special meaning, you may use it in symbol names.
-
-\1f
-File: as.info, Node: HPPA Floating Point, Next: HPPA Directives, Prev: HPPA Syntax, Up: HPPA-Dependent
-
-8.11.4 Floating Point
----------------------
-
-The HPPA family uses IEEE floating-point numbers.
-
-\1f
-File: as.info, Node: HPPA Directives, Next: HPPA Opcodes, Prev: HPPA Floating Point, Up: HPPA-Dependent
-
-8.11.5 HPPA Assembler Directives
---------------------------------
-
-`as' for the HPPA supports many additional directives for compatibility
-with the native assembler. This section describes them only briefly.
-For detailed information on HPPA-specific assembler directives, see
-`HP9000 Series 800 Assembly Language Reference Manual' (HP 92432-90001).
-
- `as' does _not_ support the following assembler directives described
-in the HP manual:
-
- .endm .liston
- .enter .locct
- .leave .macro
- .listoff
-
- Beyond those implemented for compatibility, `as' supports one
-additional assembler directive for the HPPA: `.param'. It conveys
-register argument locations for static functions. Its syntax closely
-follows the `.export' directive.
-
- These are the additional directives in `as' for the HPPA:
-
-`.block N'
-`.blockz N'
- Reserve N bytes of storage, and initialize them to zero.
-
-`.call'
- Mark the beginning of a procedure call. Only the special case
- with _no arguments_ is allowed.
-
-`.callinfo [ PARAM=VALUE, ... ] [ FLAG, ... ]'
- Specify a number of parameters and flags that define the
- environment for a procedure.
-
- PARAM may be any of `frame' (frame size), `entry_gr' (end of
- general register range), `entry_fr' (end of float register range),
- `entry_sr' (end of space register range).
-
- The values for FLAG are `calls' or `caller' (proc has
- subroutines), `no_calls' (proc does not call subroutines),
- `save_rp' (preserve return pointer), `save_sp' (proc preserves
- stack pointer), `no_unwind' (do not unwind this proc), `hpux_int'
- (proc is interrupt routine).
-
-`.code'
- Assemble into the standard section called `$TEXT$', subsection
- `$CODE$'.
-
-`.copyright "STRING"'
- In the SOM object format, insert STRING into the object code,
- marked as a copyright string.
-
-`.copyright "STRING"'
- In the ELF object format, insert STRING into the object code,
- marked as a version string.
-
-`.enter'
- Not yet supported; the assembler rejects programs containing this
- directive.
-
-`.entry'
- Mark the beginning of a procedure.
-
-`.exit'
- Mark the end of a procedure.
-
-`.export NAME [ ,TYP ] [ ,PARAM=R ]'
- Make a procedure NAME available to callers. TYP, if present, must
- be one of `absolute', `code' (ELF only, not SOM), `data', `entry',
- `data', `entry', `millicode', `plabel', `pri_prog', or `sec_prog'.
-
- PARAM, if present, provides either relocation information for the
- procedure arguments and result, or a privilege level. PARAM may be
- `argwN' (where N ranges from `0' to `3', and indicates one of four
- one-word arguments); `rtnval' (the procedure's result); or
- `priv_lev' (privilege level). For arguments or the result, R
- specifies how to relocate, and must be one of `no' (not
- relocatable), `gr' (argument is in general register), `fr' (in
- floating point register), or `fu' (upper half of float register).
- For `priv_lev', R is an integer.
-
-`.half N'
- Define a two-byte integer constant N; synonym for the portable
- `as' directive `.short'.
-
-`.import NAME [ ,TYP ]'
- Converse of `.export'; make a procedure available to call. The
- arguments use the same conventions as the first two arguments for
- `.export'.
-
-`.label NAME'
- Define NAME as a label for the current assembly location.
-
-`.leave'
- Not yet supported; the assembler rejects programs containing this
- directive.
-
-`.origin LC'
- Advance location counter to LC. Synonym for the `as' portable
- directive `.org'.
-
-`.param NAME [ ,TYP ] [ ,PARAM=R ]'
- Similar to `.export', but used for static procedures.
-
-`.proc'
- Use preceding the first statement of a procedure.
-
-`.procend'
- Use following the last statement of a procedure.
-
-`LABEL .reg EXPR'
- Synonym for `.equ'; define LABEL with the absolute expression EXPR
- as its value.
-
-`.space SECNAME [ ,PARAMS ]'
- Switch to section SECNAME, creating a new section by that name if
- necessary. You may only use PARAMS when creating a new section,
- not when switching to an existing one. SECNAME may identify a
- section by number rather than by name.
-
- If specified, the list PARAMS declares attributes of the section,
- identified by keywords. The keywords recognized are `spnum=EXP'
- (identify this section by the number EXP, an absolute expression),
- `sort=EXP' (order sections according to this sort key when linking;
- EXP is an absolute expression), `unloadable' (section contains no
- loadable data), `notdefined' (this section defined elsewhere), and
- `private' (data in this section not available to other programs).
-
-`.spnum SECNAM'
- Allocate four bytes of storage, and initialize them with the
- section number of the section named SECNAM. (You can define the
- section number with the HPPA `.space' directive.)
-
-`.string "STR"'
- Copy the characters in the string STR to the object file. *Note
- Strings: Strings, for information on escape sequences you can use
- in `as' strings.
-
- _Warning!_ The HPPA version of `.string' differs from the usual
- `as' definition: it does _not_ write a zero byte after copying STR.
-
-`.stringz "STR"'
- Like `.string', but appends a zero byte after copying STR to object
- file.
-
-`.subspa NAME [ ,PARAMS ]'
-`.nsubspa NAME [ ,PARAMS ]'
- Similar to `.space', but selects a subsection NAME within the
- current section. You may only specify PARAMS when you create a
- subsection (in the first instance of `.subspa' for this NAME).
-
- If specified, the list PARAMS declares attributes of the
- subsection, identified by keywords. The keywords recognized are
- `quad=EXPR' ("quadrant" for this subsection), `align=EXPR'
- (alignment for beginning of this subsection; a power of two),
- `access=EXPR' (value for "access rights" field), `sort=EXPR'
- (sorting order for this subspace in link), `code_only' (subsection
- contains only code), `unloadable' (subsection cannot be loaded
- into memory), `comdat' (subsection is comdat), `common'
- (subsection is common block), `dup_comm' (subsection may have
- duplicate names), or `zero' (subsection is all zeros, do not write
- in object file).
-
- `.nsubspa' always creates a new subspace with the given name, even
- if one with the same name already exists.
-
- `comdat', `common' and `dup_comm' can be used to implement various
- flavors of one-only support when using the SOM linker. The SOM
- linker only supports specific combinations of these flags. The
- details are not documented. A brief description is provided here.
-
- `comdat' provides a form of linkonce support. It is useful for
- both code and data subspaces. A `comdat' subspace has a key symbol
- marked by the `is_comdat' flag or `ST_COMDAT'. Only the first
- subspace for any given key is selected. The key symbol becomes
- universal in shared links. This is similar to the behavior of
- `secondary_def' symbols.
-
- `common' provides Fortran named common support. It is only useful
- for data subspaces. Symbols with the flag `is_common' retain this
- flag in shared links. Referencing a `is_common' symbol in a shared
- library from outside the library doesn't work. Thus, `is_common'
- symbols must be output whenever they are needed.
-
- `common' and `dup_comm' together provide Cobol common support.
- The subspaces in this case must all be the same length.
- Otherwise, this support is similar to the Fortran common support.
-
- `dup_comm' by itself provides a type of one-only support for code.
- Only the first `dup_comm' subspace is selected. There is a rather
- complex algorithm to compare subspaces. Code symbols marked with
- the `dup_common' flag are hidden. This support was intended for
- "C++ duplicate inlines".
-
- A simplified technique is used to mark the flags of symbols based
- on the flags of their subspace. A symbol with the scope
- SS_UNIVERSAL and type ST_ENTRY, ST_CODE or ST_DATA is marked with
- the corresponding settings of `comdat', `common' and `dup_comm'
- from the subspace, respectively. This avoids having to introduce
- additional directives to mark these symbols. The HP assembler
- sets `is_common' from `common'. However, it doesn't set the
- `dup_common' from `dup_comm'. It doesn't have `comdat' support.
-
-`.version "STR"'
- Write STR as version identifier in object code.
-
-\1f
-File: as.info, Node: HPPA Opcodes, Prev: HPPA Directives, Up: HPPA-Dependent
-
-8.11.6 Opcodes
---------------
-
-For detailed information on the HPPA machine instruction set, see
-`PA-RISC Architecture and Instruction Set Reference Manual' (HP
-09740-90039).
-
-\1f
-File: as.info, Node: ESA/390-Dependent, Next: i386-Dependent, Prev: HPPA-Dependent, Up: Machine Dependencies
-
-8.12 ESA/390 Dependent Features
-===============================
-
-* Menu:
-
-* ESA/390 Notes:: Notes
-* ESA/390 Options:: Options
-* ESA/390 Syntax:: Syntax
-* ESA/390 Floating Point:: Floating Point
-* ESA/390 Directives:: ESA/390 Machine Directives
-* ESA/390 Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: ESA/390 Notes, Next: ESA/390 Options, Up: ESA/390-Dependent
-
-8.12.1 Notes
-------------
-
-The ESA/390 `as' port is currently intended to be a back-end for the
-GNU CC compiler. It is not HLASM compatible, although it does support
-a subset of some of the HLASM directives. The only supported binary
-file format is ELF; none of the usual MVS/VM/OE/USS object file
-formats, such as ESD or XSD, are supported.
-
- When used with the GNU CC compiler, the ESA/390 `as' will produce
-correct, fully relocated, functional binaries, and has been used to
-compile and execute large projects. However, many aspects should still
-be considered experimental; these include shared library support,
-dynamically loadable objects, and any relocation other than the 31-bit
-relocation.
-
-\1f
-File: as.info, Node: ESA/390 Options, Next: ESA/390 Syntax, Prev: ESA/390 Notes, Up: ESA/390-Dependent
-
-8.12.2 Options
---------------
-
-`as' has no machine-dependent command-line options for the ESA/390.
-
-\1f
-File: as.info, Node: ESA/390 Syntax, Next: ESA/390 Floating Point, Prev: ESA/390 Options, Up: ESA/390-Dependent
-
-8.12.3 Syntax
--------------
-
-The opcode/operand syntax follows the ESA/390 Principles of Operation
-manual; assembler directives and general syntax are loosely based on the
-prevailing AT&T/SVR4/ELF/Solaris style notation. HLASM-style directives
-are _not_ supported for the most part, with the exception of those
-described herein.
-
- A leading dot in front of directives is optional, and the case of
-directives is ignored; thus for example, .using and USING have the same
-effect.
-
- A colon may immediately follow a label definition. This is simply
-for compatibility with how most assembly language programmers write
-code.
-
- `#' is the line comment character.
-
- `;' can be used instead of a newline to separate statements.
-
- Since `$' has no special meaning, you may use it in symbol names.
-
- Registers can be given the symbolic names r0..r15, fp0, fp2, fp4,
-fp6. By using thesse symbolic names, `as' can detect simple syntax
-errors. The name rarg or r.arg is a synonym for r11, rtca or r.tca for
-r12, sp, r.sp, dsa r.dsa for r13, lr or r.lr for r14, rbase or r.base
-for r3 and rpgt or r.pgt for r4.
-
- `*' is the current location counter. Unlike `.' it is always
-relative to the last USING directive. Note that this means that
-expressions cannot use multiplication, as any occurrence of `*' will be
-interpreted as a location counter.
-
- All labels are relative to the last USING. Thus, branches to a label
-always imply the use of base+displacement.
-
- Many of the usual forms of address constants / address literals are
-supported. Thus,
- .using *,r3
- L r15,=A(some_routine)
- LM r6,r7,=V(some_longlong_extern)
- A r1,=F'12'
- AH r0,=H'42'
- ME r6,=E'3.1416'
- MD r6,=D'3.14159265358979'
- O r6,=XL4'cacad0d0'
- .ltorg
- should all behave as expected: that is, an entry in the literal pool
-will be created (or reused if it already exists), and the instruction
-operands will be the displacement into the literal pool using the
-current base register (as last declared with the `.using' directive).
-
-\1f
-File: as.info, Node: ESA/390 Floating Point, Next: ESA/390 Directives, Prev: ESA/390 Syntax, Up: ESA/390-Dependent
-
-8.12.4 Floating Point
----------------------
-
-The assembler generates only IEEE floating-point numbers. The older
-floating point formats are not supported.
-
-\1f
-File: as.info, Node: ESA/390 Directives, Next: ESA/390 Opcodes, Prev: ESA/390 Floating Point, Up: ESA/390-Dependent
-
-8.12.5 ESA/390 Assembler Directives
------------------------------------
-
-`as' for the ESA/390 supports all of the standard ELF/SVR4 assembler
-directives that are documented in the main part of this documentation.
-Several additional directives are supported in order to implement the
-ESA/390 addressing model. The most important of these are `.using' and
-`.ltorg'
-
- These are the additional directives in `as' for the ESA/390:
-
-`.dc'
- A small subset of the usual DC directive is supported.
-
-`.drop REGNO'
- Stop using REGNO as the base register. The REGNO must have been
- previously declared with a `.using' directive in the same section
- as the current section.
-
-`.ebcdic STRING'
- Emit the EBCDIC equivalent of the indicated string. The emitted
- string will be null terminated. Note that the directives
- `.string' etc. emit ascii strings by default.
-
-`EQU'
- The standard HLASM-style EQU directive is not supported; however,
- the standard `as' directive .equ can be used to the same effect.
-
-`.ltorg'
- Dump the literal pool accumulated so far; begin a new literal pool.
- The literal pool will be written in the current section; in order
- to generate correct assembly, a `.using' must have been previously
- specified in the same section.
-
-`.using EXPR,REGNO'
- Use REGNO as the base register for all subsequent RX, RS, and SS
- form instructions. The EXPR will be evaluated to obtain the base
- address; usually, EXPR will merely be `*'.
-
- This assembler allows two `.using' directives to be simultaneously
- outstanding, one in the `.text' section, and one in another section
- (typically, the `.data' section). This feature allows dynamically
- loaded objects to be implemented in a relatively straightforward
- way. A `.using' directive must always be specified in the `.text'
- section; this will specify the base register that will be used for
- branches in the `.text' section. A second `.using' may be
- specified in another section; this will specify the base register
- that is used for non-label address literals. When a second
- `.using' is specified, then the subsequent `.ltorg' must be put in
- the same section; otherwise an error will result.
-
- Thus, for example, the following code uses `r3' to address branch
- targets and `r4' to address the literal pool, which has been
- written to the `.data' section. The is, the constants
- `=A(some_routine)', `=H'42'' and `=E'3.1416'' will all appear in
- the `.data' section.
-
- .data
- .using LITPOOL,r4
- .text
- BASR r3,0
- .using *,r3
- B START
- .long LITPOOL
- START:
- L r4,4(,r3)
- L r15,=A(some_routine)
- LTR r15,r15
- BNE LABEL
- AH r0,=H'42'
- LABEL:
- ME r6,=E'3.1416'
- .data
- LITPOOL:
- .ltorg
-
- Note that this dual-`.using' directive semantics extends and is
- not compatible with HLASM semantics. Note that this assembler
- directive does not support the full range of HLASM semantics.
-
-
-\1f
-File: as.info, Node: ESA/390 Opcodes, Prev: ESA/390 Directives, Up: ESA/390-Dependent
-
-8.12.6 Opcodes
---------------
-
-For detailed information on the ESA/390 machine instruction set, see
-`ESA/390 Principles of Operation' (IBM Publication Number DZ9AR004).
-
-\1f
-File: as.info, Node: i386-Dependent, Next: i860-Dependent, Prev: ESA/390-Dependent, Up: Machine Dependencies
-
-8.13 80386 Dependent Features
-=============================
-
- The i386 version `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.
-
-* Menu:
-
-* i386-Options:: Options
-* i386-Syntax:: AT&T Syntax versus Intel Syntax
-* i386-Mnemonics:: Instruction Naming
-* i386-Regs:: Register Naming
-* i386-Prefixes:: Instruction Prefixes
-* i386-Memory:: Memory References
-* i386-Jumps:: Handling of Jump Instructions
-* i386-Float:: Floating Point
-* i386-SIMD:: Intel's MMX and AMD's 3DNow! SIMD Operations
-* i386-16bit:: Writing 16-bit Code
-* i386-Arch:: Specifying an x86 CPU architecture
-* i386-Bugs:: AT&T Syntax bugs
-* i386-Notes:: Notes
-
-\1f
-File: as.info, Node: i386-Options, Next: i386-Syntax, Up: i386-Dependent
-
-8.13.1 Options
---------------
-
-The i386 version of `as' has a few machine dependent options:
-
-`--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.
-
- 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).
-
-`-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.
-
-`--divide'
- On SVR4-derived platforms, the character `/' is treated as a
- comment character, which means that it cannot be used in
- expressions. The `--divide' option turns `/' into a normal
- character. This does not disable `/' at the beginning of a line
- starting a comment, or affect using `#' for starting a comment.
-
-`-march=CPU'
- This option specifies an instruction set architecture for
- generating instructions. The following architectures are
- recognized: `i8086', `i186', `i286', `i386', `i486', `i586',
- `i686', `pentium', `pentiumpro', `pentiumii', `pentiumiii',
- `pentium4', `prescott', `nocona', `core', `core2', `k6', `k6_2',
- `athlon', `sledgehammer', `opteron', `k8', `generic32' and
- `generic64'.
-
- This option only affects instructions generated by the assembler.
- The `.arch' directive will take precedent.
-
-`-mtune=CPU'
- This option specifies a processor to optimize for. When used in
- conjunction with the `-march' option, only instructions of the
- processor specified by the `-march' option will be generated.
-
- Valid CPU values are identical to `-march=CPU'.
-
-
-\1f
-File: as.info, Node: i386-Syntax, Next: i386-Mnemonics, Prev: i386-Options, Up: i386-Dependent
-
-8.13.2 AT&T Syntax versus Intel Syntax
---------------------------------------
-
-`as' now supports assembly using Intel assembler syntax.
-`.intel_syntax' selects Intel mode, and `.att_syntax' switches back to
-the usual AT&T mode for compatibility with the output of `gcc'. Either
-of these directives may have an optional argument, `prefix', or
-`noprefix' specifying whether registers require a `%' 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:
-
- * AT&T immediate operands are preceded by `$'; Intel immediate
- operands are undelimited (Intel `push 4' is AT&T `pushl $4').
- AT&T register operands are preceded by `%'; Intel register operands
- are undelimited. AT&T absolute (as opposed to PC relative)
- jump/call operands are prefixed by `*'; they are undelimited in
- Intel syntax.
-
- * AT&T and Intel syntax use the opposite order for source and
- destination operands. Intel `add eax, 4' is `addl $4, %eax'. The
- `source, dest' convention is maintained for compatibility with
- previous Unix assemblers. Note that instructions with more than
- one source operand, such as the `enter' instruction, do _not_ have
- reversed order. *Note i386-Bugs::.
-
- * In AT&T syntax the size of memory operands is determined from the
- last character of the instruction mnemonic. Mnemonic suffixes of
- `b', `w', `l' and `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 (_not_ the
- instruction mnemonics) with `byte ptr', `word ptr', `dword ptr'
- and `qword ptr'. Thus, Intel `mov al, byte ptr FOO' is `movb FOO,
- %al' in AT&T syntax.
-
- * Immediate form long jumps and calls are `lcall/ljmp $SECTION,
- $OFFSET' in AT&T syntax; the Intel syntax is `call/jmp far
- SECTION:OFFSET'. Also, the far return instruction is `lret
- $STACK-ADJUST' in AT&T syntax; Intel syntax is `ret far
- STACK-ADJUST'.
-
- * The AT&T assembler does not provide support for multiple section
- programs. Unix style systems expect all programs to be single
- sections.
-
-\1f
-File: as.info, Node: i386-Mnemonics, Next: i386-Regs, Prev: i386-Syntax, Up: i386-Dependent
-
-8.13.3 Instruction Naming
--------------------------
-
-Instruction mnemonics are suffixed with one character modifiers which
-specify the size of operands. The letters `b', `w', `l' and `q'
-specify byte, word, long and quadruple word operands. If no suffix is
-specified by an instruction then `as' tries to fill in the missing
-suffix based on the destination register operand (the last one by
-convention). Thus, `mov %ax, %bx' is equivalent to `movw %ax, %bx';
-also, `mov $1, %bx' is equivalent to `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.)
-
- 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 _from_ and a size to zero extend _to_. This is
-accomplished by using two instruction mnemonic suffixes in AT&T syntax.
-Base names for sign extend and zero extend are `movs...' and `movz...'
-in AT&T syntax (`movsx' and `movzx' in Intel syntax). The instruction
-mnemonic suffixes are tacked on to this base name, the _from_ suffix
-before the _to_ suffix. Thus, `movsbl %al, %edx' is AT&T syntax for
-"move sign extend _from_ %al _to_ %edx." Possible suffixes, thus, are
-`bl' (from byte to long), `bw' (from byte to word), `wl' (from word to
-long), `bq' (from byte to quadruple word), `wq' (from word to quadruple
-word), and `lq' (from long to quadruple word).
-
- The Intel-syntax conversion instructions
-
- * `cbw' -- sign-extend byte in `%al' to word in `%ax',
-
- * `cwde' -- sign-extend word in `%ax' to long in `%eax',
-
- * `cwd' -- sign-extend word in `%ax' to long in `%dx:%ax',
-
- * `cdq' -- sign-extend dword in `%eax' to quad in `%edx:%eax',
-
- * `cdqe' -- sign-extend dword in `%eax' to quad in `%rax' (x86-64
- only),
-
- * `cqo' -- sign-extend quad in `%rax' to octuple in `%rdx:%rax'
- (x86-64 only),
-
-are called `cbtw', `cwtl', `cwtd', `cltd', `cltq', and `cqto' in AT&T
-naming. `as' accepts either naming for these instructions.
-
- Far call/jump instructions are `lcall' and `ljmp' in AT&T syntax,
-but are `call far' and `jump far' in Intel convention.
-
-\1f
-File: as.info, Node: i386-Regs, Next: i386-Prefixes, Prev: i386-Mnemonics, Up: i386-Dependent
-
-8.13.4 Register Naming
-----------------------
-
-Register operands are always prefixed with `%'. The 80386 registers
-consist of
-
- * the 8 32-bit registers `%eax' (the accumulator), `%ebx', `%ecx',
- `%edx', `%edi', `%esi', `%ebp' (the frame pointer), and `%esp'
- (the stack pointer).
-
- * the 8 16-bit low-ends of these: `%ax', `%bx', `%cx', `%dx', `%di',
- `%si', `%bp', and `%sp'.
-
- * the 8 8-bit registers: `%ah', `%al', `%bh', `%bl', `%ch', `%cl',
- `%dh', and `%dl' (These are the high-bytes and low-bytes of `%ax',
- `%bx', `%cx', and `%dx')
-
- * the 6 section registers `%cs' (code section), `%ds' (data
- section), `%ss' (stack section), `%es', `%fs', and `%gs'.
-
- * the 3 processor control registers `%cr0', `%cr2', and `%cr3'.
-
- * the 6 debug registers `%db0', `%db1', `%db2', `%db3', `%db6', and
- `%db7'.
-
- * the 2 test registers `%tr6' and `%tr7'.
-
- * the 8 floating point register stack `%st' or equivalently
- `%st(0)', `%st(1)', `%st(2)', `%st(3)', `%st(4)', `%st(5)',
- `%st(6)', and `%st(7)'. These registers are overloaded by 8 MMX
- registers `%mm0', `%mm1', `%mm2', `%mm3', `%mm4', `%mm5', `%mm6'
- and `%mm7'.
-
- * the 8 SSE registers registers `%xmm0', `%xmm1', `%xmm2', `%xmm3',
- `%xmm4', `%xmm5', `%xmm6' and `%xmm7'.
-
- The AMD x86-64 architecture extends the register set by:
-
- * enhancing the 8 32-bit registers to 64-bit: `%rax' (the
- accumulator), `%rbx', `%rcx', `%rdx', `%rdi', `%rsi', `%rbp' (the
- frame pointer), `%rsp' (the stack pointer)
-
- * the 8 extended registers `%r8'-`%r15'.
-
- * the 8 32-bit low ends of the extended registers: `%r8d'-`%r15d'
-
- * the 8 16-bit low ends of the extended registers: `%r8w'-`%r15w'
-
- * the 8 8-bit low ends of the extended registers: `%r8b'-`%r15b'
-
- * the 4 8-bit registers: `%sil', `%dil', `%bpl', `%spl'.
-
- * the 8 debug registers: `%db8'-`%db15'.
-
- * the 8 SSE registers: `%xmm8'-`%xmm15'.
-
-\1f
-File: as.info, Node: i386-Prefixes, Next: i386-Memory, Prev: i386-Regs, Up: i386-Dependent
-
-8.13.5 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 "operand size" prefix.)
-Instruction prefixes are best written on the same line as the
-instruction they act upon. For example, the `scas' (scan string)
-instruction is repeated with:
-
- repne scas %es:(%edi),%al
-
- You may also place prefixes on the lines immediately preceding the
-instruction, but this circumvents checks that `as' does with prefixes,
-and will not work with all prefixes.
-
- Here is a list of instruction prefixes:
-
- * Section override prefixes `cs', `ds', `ss', `es', `fs', `gs'.
- These are automatically added by specifying using the
- SECTION:MEMORY-OPERAND form for memory references.
-
- * Operand/Address size prefixes `data16' and `addr16' change 32-bit
- operands/addresses into 16-bit operands/addresses, while `data32'
- and `addr32' change 16-bit ones (in a `.code16' section) into
- 32-bit operands/addresses. These prefixes _must_ appear on the
- same line of code as the instruction they modify. For example, in
- a 16-bit `.code16' section, you might write:
-
- addr32 jmpl *(%ebx)
-
- * The bus lock prefix `lock' inhibits interrupts during execution of
- the instruction it precedes. (This is only valid with certain
- instructions; see a 80386 manual for details).
-
- * The wait for coprocessor prefix `wait' waits for the coprocessor to
- complete the current instruction. This should never be needed for
- the 80386/80387 combination.
-
- * The `rep', `repe', and `repne' prefixes are added to string
- instructions to make them repeat `%ecx' times (`%cx' times if the
- current address size is 16-bits).
-
- * The `rex' family of prefixes is used by x86-64 to encode
- extensions to i386 instruction set. The `rex' prefix has four
- bits -- an operand size overwrite (`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.
-
- You may write the `rex' prefixes directly. The `rex64xyz'
- instruction emits `rex' prefix with all the bits set. By omitting
- the `64', `x', `y' or `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.
-
-\1f
-File: as.info, Node: i386-Memory, Next: i386-Jumps, Prev: i386-Prefixes, Up: i386-Dependent
-
-8.13.6 Memory References
-------------------------
-
-An Intel syntax indirect memory reference of the form
-
- SECTION:[BASE + INDEX*SCALE + DISP]
-
-is translated into the AT&T syntax
-
- SECTION:DISP(BASE, INDEX, SCALE)
-
-where BASE and INDEX are the optional 32-bit base and index registers,
-DISP is the optional displacement, and SCALE, taking the values 1, 2,
-4, and 8, multiplies INDEX to calculate the address of the operand. If
-no SCALE is specified, SCALE is taken to be 1. 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 _must_ be
-preceded by a `%'. If you specify a section override which coincides
-with the default section register, `as' does _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.
-
- Here are some examples of Intel and AT&T style memory references:
-
-AT&T: `-4(%ebp)', Intel: `[ebp - 4]'
- BASE is `%ebp'; DISP is `-4'. SECTION is missing, and the default
- section is used (`%ss' for addressing with `%ebp' as the base
- register). INDEX, SCALE are both missing.
-
-AT&T: `foo(,%eax,4)', Intel: `[foo + eax*4]'
- INDEX is `%eax' (scaled by a SCALE 4); DISP is `foo'. All other
- fields are missing. The section register here defaults to `%ds'.
-
-AT&T: `foo(,1)'; Intel `[foo]'
- This uses the value pointed to by `foo' as a memory operand. Note
- that BASE and INDEX are both missing, but there is only _one_ `,'.
- This is a syntactic exception.
-
-AT&T: `%gs:foo'; Intel `gs:foo'
- This selects the contents of the variable `foo' with section
- register SECTION being `%gs'.
-
- Absolute (as opposed to PC relative) call and jump operands must be
-prefixed with `*'. If no `*' is specified, `as' always chooses PC
-relative addressing for jump/call labels.
-
- Any instruction that has a memory operand, but no register operand,
-_must_ specify its size (byte, word, long, or quadruple) with an
-instruction mnemonic suffix (`b', `w', `l' or `q', respectively).
-
- The x86-64 architecture adds an RIP (instruction pointer relative)
-addressing. This addressing mode is specified by using `rip' as a base
-register. Only constant offsets are valid. For example:
-
-AT&T: `1234(%rip)', Intel: `[rip + 1234]'
- Points to the address 1234 bytes past the end of the current
- instruction.
-
-AT&T: `symbol(%rip)', Intel: `[rip + symbol]'
- Points to the `symbol' in RIP relative way, this is shorter than
- the default absolute addressing.
-
- Other addressing modes remain unchanged in x86-64 architecture,
-except registers used are 64-bit instead of 32-bit.
-
-\1f
-File: as.info, Node: i386-Jumps, Next: i386-Float, Prev: i386-Memory, Up: i386-Dependent
-
-8.13.7 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 `data16' instruction prefix), since the 80386
-insists upon masking `%eip' to 16 bits after the word displacement is
-added. (See also *note i386-Arch::)
-
- Note that the `jcxz', `jecxz', `loop', `loopz', `loope', `loopnz'
-and `loopne' instructions only come in byte displacements, so that if
-you use these instructions (`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 `jcxz foo' to
-
- jcxz cx_zero
- jmp cx_nonzero
- cx_zero: jmp foo
- cx_nonzero:
-
-\1f
-File: as.info, Node: i386-Float, Next: i386-SIMD, Prev: i386-Jumps, Up: i386-Dependent
-
-8.13.8 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.
-
- * Floating point constructors are `.float' or `.single', `.double',
- and `.tfloat' for 32-, 64-, and 80-bit formats. These correspond
- to instruction mnemonic suffixes `s', `l', and `t'. `t' stands for
- 80-bit (ten byte) real. The 80387 only supports this format via
- the `fldt' (load 80-bit real to stack top) and `fstpt' (store
- 80-bit real and pop stack) instructions.
-
- * Integer constructors are `.word', `.long' or `.int', and `.quad'
- for the 16-, 32-, and 64-bit integer formats. The corresponding
- instruction mnemonic suffixes are `s' (single), `l' (long), and
- `q' (quad). As with the 80-bit real format, the 64-bit `q' format
- is only present in the `fildq' (load quad integer to stack top)
- and `fistpq' (store quad integer and pop stack) instructions.
-
- Register to register operations should not use instruction mnemonic
-suffixes. `fstl %st, %st(1)' will give a warning, and be assembled as
-if you wrote `fst %st, %st(1)', since all register to register
-operations use 80-bit floating point operands. (Contrast this with
-`fstl %st, mem', which converts `%st' from 80-bit to 64-bit floating
-point format, then stores the result in the 4 byte location `mem')
-
-\1f
-File: as.info, Node: i386-SIMD, Next: i386-16bit, Prev: i386-Float, Up: i386-Dependent
-
-8.13.9 Intel's MMX and AMD's 3DNow! SIMD Operations
----------------------------------------------------
-
-`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.
-
- Currently, `as' does not support Intel's floating point SIMD, Katmai
-(KNI).
-
- The eight 64-bit MMX operands, also used by 3DNow!, are called
-`%mm0', `%mm1', ... `%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.
-
- See Intel and AMD documentation, keeping in mind that the operand
-order in instructions is reversed from the Intel syntax.
-
-\1f
-File: as.info, Node: i386-16bit, Next: i386-Arch, Prev: i386-SIMD, Up: i386-Dependent
-
-8.13.10 Writing 16-bit Code
----------------------------
-
-While `as' normally writes only "pure" 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 `.code16' or `.code16gcc' directive before
-the assembly language instructions to be run in 16-bit mode. You can
-switch `as' back to writing normal 32-bit code with the `.code32'
-directive.
-
- `.code16gcc' provides experimental support for generating 16-bit
-code from gcc, and differs from `.code16' in that `call', `ret',
-`enter', `leave', `push', `pop', `pusha', `popa', `pushf', and `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.
-`.code16gcc' also automatically adds address size prefixes where
-necessary to use the 32-bit addressing modes that gcc generates.
-
- The code which `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 _any_ 32-bit constructs which
-require `as' to output address or operand size prefixes.
-
- 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 `66 6a 04', which pushes the value
-`4' onto the stack, decrementing `%esp' by 2.
-
- pushw $4
-
- The same code in a 16-bit code section would generate the machine
-opcode bytes `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.
-
-\1f
-File: as.info, Node: i386-Bugs, Next: i386-Notes, Prev: i386-Arch, Up: i386-Dependent
-
-8.13.11 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.
-
- For example
-
- fsub %st,%st(3)
- results in `%st(3)' being updated to `%st - %st(3)' rather than the
-expected `%st(3) - %st'. This happens with all the non-commutative
-arithmetic floating point operations with two register operands where
-the source register is `%st' and the destination register is `%st(i)'.
-
-\1f
-File: as.info, Node: i386-Arch, Next: i386-Bugs, Prev: i386-16bit, Up: i386-Dependent
-
-8.13.12 Specifying CPU Architecture
------------------------------------
-
-`as' may be told to assemble for a particular CPU (sub-)architecture
-with the `.arch CPU_TYPE' directive. This directive enables a warning
-when gas detects an instruction that is not supported on the CPU
-specified. The choices for CPU_TYPE are:
-
-`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'
-
- Apart from the warning, there are only two other effects on `as'
-operation; Firstly, if you specify a CPU other than `i486', then shift
-by one instructions such as `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 `sarl %eax'. Secondly, if you specify
-`i8086', `i186', or `i286', _and_ `.code16' or `.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.
-
- Following the CPU architecture (but not a sub-architecture, which
-are those starting with a dot), you may specify `jumps' or `nojumps' to
-control automatic promotion of conditional jumps. `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.
-(*note i386-Jumps::) `nojumps' leaves external conditional jumps as
-byte offset jumps, and warns about file-local conditional jumps that
-`as' promotes. Unconditional jumps are treated as for `jumps'.
-
- For example
-
- .arch i8086,nojumps
-
-\1f
-File: as.info, Node: i386-Notes, Prev: i386-Bugs, Up: i386-Dependent
-
-8.13.13 Notes
--------------
-
-There is some trickery concerning the `mul' and `imul' instructions
-that deserves mention. The 16-, 32-, 64- and 128-bit expanding
-multiplies (base opcode `0xf6'; extension 4 for `mul' and 5 for `imul')
-can be output only in the one operand form. Thus, `imul %ebx, %eax'
-does _not_ select the expanding multiply; the expanding multiply would
-clobber the `%edx' register, and this would confuse `gcc' output. Use
-`imul %ebx' to get the 64-bit product in `%edx:%eax'.
-
- We have added a two operand form of `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 `%eax' by 69, for
-example, can be done with `imul $69, %eax' rather than `imul $69, %eax,
-%eax'.
-
-\1f
-File: as.info, Node: i860-Dependent, Next: i960-Dependent, Prev: i386-Dependent, Up: Machine Dependencies
-
-8.14 Intel i860 Dependent Features
-==================================
-
-* Menu:
-
-* Notes-i860:: i860 Notes
-* Options-i860:: i860 Command-line Options
-* Directives-i860:: i860 Machine Directives
-* Opcodes for i860:: i860 Opcodes
-
-\1f
-File: as.info, Node: Notes-i860, Next: Options-i860, Up: i860-Dependent
-
-8.14.1 i860 Notes
------------------
-
-This is a fairly complete i860 assembler which is compatible with the
-UNIX System V/860 Release 4 assembler. However, it does not currently
-support SVR4 PIC (i.e., `@GOT, @GOTOFF, @PLT').
-
- Like the SVR4/860 assembler, the output object format is ELF32.
-Currently, this is the only supported object format. If there is
-sufficient interest, other formats such as COFF may be implemented.
-
- Both the Intel and AT&T/SVR4 syntaxes are supported, with the latter
-being the default. One difference is that AT&T syntax requires the '%'
-prefix on register names while Intel syntax does not. Another
-difference is in the specification of relocatable expressions. The
-Intel syntax is `ha%expression' whereas the SVR4 syntax is
-`[expression]@ha' (and similarly for the "l" and "h" selectors).
-
-\1f
-File: as.info, Node: Options-i860, Next: Directives-i860, Prev: Notes-i860, Up: i860-Dependent
-
-8.14.2 i860 Command-line Options
---------------------------------
-
-8.14.2.1 SVR4 compatibility options
-...................................
-
-`-V'
- Print assembler version.
-
-`-Qy'
- Ignored.
-
-`-Qn'
- Ignored.
-
-8.14.2.2 Other options
-......................
-
-`-EL'
- Select little endian output (this is the default).
-
-`-EB'
- Select big endian output. Note that the i860 always reads
- instructions as little endian data, so this option only effects
- data and not instructions.
-
-`-mwarn-expand'
- Emit a warning message if any pseudo-instruction expansions
- occurred. For example, a `or' instruction with an immediate
- larger than 16-bits will be expanded into two instructions. This
- is a very undesirable feature to rely on, so this flag can help
- detect any code where it happens. One use of it, for instance, has
- been to find and eliminate any place where `gcc' may emit these
- pseudo-instructions.
-
-`-mxp'
- Enable support for the i860XP instructions and control registers.
- By default, this option is disabled so that only the base
- instruction set (i.e., i860XR) is supported.
-
-`-mintel-syntax'
- The i860 assembler defaults to AT&T/SVR4 syntax. This option
- enables the Intel syntax.
-
-\1f
-File: as.info, Node: Directives-i860, Next: Opcodes for i860, Prev: Options-i860, Up: i860-Dependent
-
-8.14.3 i860 Machine Directives
-------------------------------
-
-`.dual'
- Enter dual instruction mode. While this directive is supported, the
- preferred way to use dual instruction mode is to explicitly code
- the dual bit with the `d.' prefix.
-
-`.enddual'
- Exit dual instruction mode. While this directive is supported, the
- preferred way to use dual instruction mode is to explicitly code
- the dual bit with the `d.' prefix.
-
-`.atmp'
- Change the temporary register used when expanding pseudo
- operations. The default register is `r31'.
-
- The `.dual', `.enddual', and `.atmp' directives are available only
-in the Intel syntax mode.
-
- Both syntaxes allow for the standard `.align' directive. However,
-the Intel syntax additionally allows keywords for the alignment
-parameter: "`.align type'", where `type' is one of `.short', `.long',
-`.quad', `.single', `.double' representing alignments of 2, 4, 16, 4,
-and 8, respectively.
-
-\1f
-File: as.info, Node: Opcodes for i860, Prev: Directives-i860, Up: i860-Dependent
-
-8.14.4 i860 Opcodes
--------------------
-
-All of the Intel i860XR and i860XP machine instructions are supported.
-Please see either _i860 Microprocessor Programmer's Reference Manual_
-or _i860 Microprocessor Architecture_ for more information.
-
-8.14.4.1 Other instruction support (pseudo-instructions)
-........................................................
-
-For compatibility with some other i860 assemblers, a number of
-pseudo-instructions are supported. While these are supported, they are
-a very undesirable feature that should be avoided - in particular, when
-they result in an expansion to multiple actual i860 instructions. Below
-are the pseudo-instructions that result in expansions.
- * Load large immediate into general register:
-
- The pseudo-instruction `mov imm,%rn' (where the immediate does not
- fit within a signed 16-bit field) will be expanded into:
- orh large_imm@h,%r0,%rn
- or large_imm@l,%rn,%rn
-
- * Load/store with relocatable address expression:
-
- For example, the pseudo-instruction `ld.b addr_exp(%rx),%rn' will
- be expanded into:
- orh addr_exp@ha,%rx,%r31
- ld.l addr_exp@l(%r31),%rn
-
- The analogous expansions apply to `ld.x, st.x, fld.x, pfld.x,
- fst.x', and `pst.x' as well.
-
- * Signed large immediate with add/subtract:
-
- If any of the arithmetic operations `adds, addu, subs, subu' are
- used with an immediate larger than 16-bits (signed), then they
- will be expanded. For instance, the pseudo-instruction `adds
- large_imm,%rx,%rn' expands to:
- orh large_imm@h,%r0,%r31
- or large_imm@l,%r31,%r31
- adds %r31,%rx,%rn
-
- * Unsigned large immediate with logical operations:
-
- Logical operations (`or, andnot, or, xor') also result in
- expansions. The pseudo-instruction `or large_imm,%rx,%rn' results
- in:
- orh large_imm@h,%rx,%r31
- or large_imm@l,%r31,%rn
-
- Similarly for the others, except for `and' which expands to:
- andnot (-1 - large_imm)@h,%rx,%r31
- andnot (-1 - large_imm)@l,%r31,%rn
-
-\1f
-File: as.info, Node: i960-Dependent, Next: IA-64-Dependent, Prev: i860-Dependent, Up: Machine Dependencies
-
-8.15 Intel 80960 Dependent Features
-===================================
-
-* Menu:
-
-* Options-i960:: i960 Command-line Options
-* Floating Point-i960:: Floating Point
-* Directives-i960:: i960 Machine Directives
-* Opcodes for i960:: i960 Opcodes
-
-\1f
-File: as.info, Node: Options-i960, Next: Floating Point-i960, Up: i960-Dependent
-
-8.15.1 i960 Command-line Options
---------------------------------
-
-`-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC'
- Select the 80960 architecture. Instructions or features not
- supported by the selected architecture cause fatal errors.
-
- `-ACA' is equivalent to `-ACA_A'; `-AKC' is equivalent to `-AMC'.
- Synonyms are provided for compatibility with other tools.
-
- If you do not specify any of these options, `as' generates code
- for any instruction or feature that is supported by _some_ version
- of the 960 (even if this means mixing architectures!). In
- principle, `as' attempts to deduce the minimal sufficient
- processor type if none is specified; depending on the object code
- format, the processor type may be recorded in the object file. If
- it is critical that the `as' output match a specific architecture,
- specify that architecture explicitly.
-
-`-b'
- Add code to collect information about conditional branches taken,
- for later optimization using branch prediction bits. (The
- conditional branch instructions have branch prediction bits in the
- CA, CB, and CC architectures.) If BR represents a conditional
- branch instruction, the following represents the code generated by
- the assembler when `-b' is specified:
-
- call INCREMENT ROUTINE
- .word 0 # pre-counter
- Label: BR
- call INCREMENT ROUTINE
- .word 0 # post-counter
-
- The counter following a branch records the number of times that
- branch was _not_ taken; the difference between the two counters is
- the number of times the branch _was_ taken.
-
- A table of every such `Label' is also generated, so that the
- external postprocessor `gbr960' (supplied by Intel) can locate all
- the counters. This table is always labeled `__BRANCH_TABLE__';
- this is a local symbol to permit collecting statistics for many
- separate object files. The table is word aligned, and begins with
- a two-word header. The first word, initialized to 0, is used in
- maintaining linked lists of branch tables. The second word is a
- count of the number of entries in the table, which follow
- immediately: each is a word, pointing to one of the labels
- illustrated above.
-
- +------------+------------+------------+ ... +------------+
- | | | | | |
- | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N |
- | | | | | |
- +------------+------------+------------+ ... +------------+
-
- __BRANCH_TABLE__ layout
-
- The first word of the header is used to locate multiple branch
- tables, since each object file may contain one. Normally the links
- are maintained with a call to an initialization routine, placed at
- the beginning of each function in the file. The GNU C compiler
- generates these calls automatically when you give it a `-b' option.
- For further details, see the documentation of `gbr960'.
-
-`-no-relax'
- Normally, Compare-and-Branch instructions with targets that require
- displacements greater than 13 bits (or that have external targets)
- are replaced with the corresponding compare (or `chkbit') and
- branch instructions. You can use the `-no-relax' option to
- specify that `as' should generate errors instead, if the target
- displacement is larger than 13 bits.
-
- This option does not affect the Compare-and-Jump instructions; the
- code emitted for them is _always_ adjusted when necessary
- (depending on displacement size), regardless of whether you use
- `-no-relax'.
-
-\1f
-File: as.info, Node: Floating Point-i960, Next: Directives-i960, Prev: Options-i960, Up: i960-Dependent
-
-8.15.2 Floating Point
----------------------
-
-`as' generates IEEE floating-point numbers for the directives `.float',
-`.double', `.extended', and `.single'.
-
-\1f
-File: as.info, Node: Directives-i960, Next: Opcodes for i960, Prev: Floating Point-i960, Up: i960-Dependent
-
-8.15.3 i960 Machine Directives
-------------------------------
-
-`.bss SYMBOL, LENGTH, ALIGN'
- Reserve LENGTH bytes in the bss section for a local SYMBOL,
- aligned to the power of two specified by ALIGN. LENGTH and ALIGN
- must be positive absolute expressions. This directive differs
- from `.lcomm' only in that it permits you to specify an alignment.
- *Note `.lcomm': Lcomm.
-
-`.extended FLONUMS'
- `.extended' expects zero or more flonums, separated by commas; for
- each flonum, `.extended' emits an IEEE extended-format (80-bit)
- floating-point number.
-
-`.leafproc CALL-LAB, BAL-LAB'
- You can use the `.leafproc' directive in conjunction with the
- optimized `callj' instruction to enable faster calls of leaf
- procedures. If a procedure is known to call no other procedures,
- you may define an entry point that skips procedure prolog code
- (and that does not depend on system-supplied saved context), and
- declare it as the BAL-LAB using `.leafproc'. If the procedure
- also has an entry point that goes through the normal prolog, you
- can specify that entry point as CALL-LAB.
-
- A `.leafproc' declaration is meant for use in conjunction with the
- optimized call instruction `callj'; the directive records the data
- needed later to choose between converting the `callj' into a `bal'
- or a `call'.
-
- CALL-LAB is optional; if only one argument is present, or if the
- two arguments are identical, the single argument is assumed to be
- the `bal' entry point.
-
-`.sysproc NAME, INDEX'
- The `.sysproc' directive defines a name for a system procedure.
- After you define it using `.sysproc', you can use NAME to refer to
- the system procedure identified by INDEX when calling procedures
- with the optimized call instruction `callj'.
-
- Both arguments are required; INDEX must be between 0 and 31
- (inclusive).
-
-\1f
-File: as.info, Node: Opcodes for i960, Prev: Directives-i960, Up: i960-Dependent
-
-8.15.4 i960 Opcodes
--------------------
-
-All Intel 960 machine instructions are supported; *note i960
-Command-line Options: Options-i960. for a discussion of selecting the
-instruction subset for a particular 960 architecture.
-
- Some opcodes are processed beyond simply emitting a single
-corresponding instruction: `callj', and Compare-and-Branch or
-Compare-and-Jump instructions with target displacements larger than 13
-bits.
-
-* Menu:
-
-* callj-i960:: `callj'
-* Compare-and-branch-i960:: Compare-and-Branch
-
-\1f
-File: as.info, Node: callj-i960, Next: Compare-and-branch-i960, Up: Opcodes for i960
-
-8.15.4.1 `callj'
-................
-
-You can write `callj' to have the assembler or the linker determine the
-most appropriate form of subroutine call: `call', `bal', or `calls'.
-If the assembly source contains enough information--a `.leafproc' or
-`.sysproc' directive defining the operand--then `as' translates the
-`callj'; if not, it simply emits the `callj', leaving it for the linker
-to resolve.
-
-\1f
-File: as.info, Node: Compare-and-branch-i960, Prev: callj-i960, Up: Opcodes for i960
-
-8.15.4.2 Compare-and-Branch
-...........................
-
-The 960 architectures provide combined Compare-and-Branch instructions
-that permit you to store the branch target in the lower 13 bits of the
-instruction word itself. However, if you specify a branch target far
-enough away that its address won't fit in 13 bits, the assembler can
-either issue an error, or convert your Compare-and-Branch instruction
-into separate instructions to do the compare and the branch.
-
- Whether `as' gives an error or expands the instruction depends on
-two choices you can make: whether you use the `-no-relax' option, and
-whether you use a "Compare and Branch" instruction or a "Compare and
-Jump" instruction. The "Jump" instructions are _always_ expanded if
-necessary; the "Branch" instructions are expanded when necessary
-_unless_ you specify `-no-relax'--in which case `as' gives an error
-instead.
-
- These are the Compare-and-Branch instructions, their "Jump" variants,
-and the instruction pairs they may expand into:
-
- Compare and
- Branch Jump Expanded to
- ------ ------ ------------
- bbc chkbit; bno
- bbs chkbit; bo
- cmpibe cmpije cmpi; be
- cmpibg cmpijg cmpi; bg
- cmpibge cmpijge cmpi; bge
- cmpibl cmpijl cmpi; bl
- cmpible cmpijle cmpi; ble
- cmpibno cmpijno cmpi; bno
- cmpibne cmpijne cmpi; bne
- cmpibo cmpijo cmpi; bo
- cmpobe cmpoje cmpo; be
- cmpobg cmpojg cmpo; bg
- cmpobge cmpojge cmpo; bge
- cmpobl cmpojl cmpo; bl
- cmpoble cmpojle cmpo; ble
- cmpobne cmpojne cmpo; bne
-
-\1f
-File: as.info, Node: IA-64-Dependent, Next: IP2K-Dependent, Prev: i960-Dependent, Up: Machine Dependencies
-
-8.16 IA-64 Dependent Features
-=============================
-
-* Menu:
-
-* IA-64 Options:: Options
-* IA-64 Syntax:: Syntax
-* IA-64 Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: IA-64 Options, Next: IA-64 Syntax, Up: IA-64-Dependent
-
-8.16.1 Options
---------------
-
-`-mconstant-gp'
- This option instructs the assembler to mark the resulting object
- file as using the "constant GP" 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.
-
-`-mauto-pic'
- This option instructs the assembler to mark the resulting object
- file as using the "constant GP without function descriptor" data
- model. This model is like the "constant GP" 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.
-
-`-milp32'
-
-`-milp64'
-
-`-mlp64'
-
-`-mp64'
- These options select the data model. The assembler defaults to
- `-mlp64' (LP64 data model).
-
-`-mle'
-
-`-mbe'
- These options select the byte order. The `-mle' option selects
- little-endian byte order (default) and `-mbe' selects big-endian
- byte order. Note that IA-64 machine code always uses
- little-endian byte order.
-
-`-mtune=itanium1'
-
-`-mtune=itanium2'
- Tune for a particular IA-64 CPU, ITANIUM1 or ITANIUM2. The default
- is ITANIUM2.
-
-`-munwind-check=warning'
-
-`-munwind-check=error'
- These options control what the assembler will do when performing
- consistency checks on unwind directives. `-munwind-check=warning'
- will make the assembler issue a warning when an unwind directive
- check fails. This is the default. `-munwind-check=error' will
- make the assembler issue an error when an unwind directive check
- fails.
-
-`-mhint.b=ok'
-
-`-mhint.b=warning'
-
-`-mhint.b=error'
- These options control what the assembler will do when the `hint.b'
- instruction is used. `-mhint.b=ok' will make the assembler accept
- `hint.b'. `-mint.b=warning' will make the assembler issue a
- warning when `hint.b' is used. `-mhint.b=error' will make the
- assembler treat `hint.b' as an error, which is the default.
-
-`-x'
-
-`-xexplicit'
- These options turn on dependency violation checking.
-
-`-xauto'
- This option instructs the assembler to automatically insert stop
- bits where necessary to remove dependency violations. This is the
- default mode.
-
-`-xnone'
- This option turns off dependency violation checking.
-
-`-xdebug'
- This turns on debug output intended to help tracking down bugs in
- the dependency violation checker.
-
-`-xdebugn'
- This is a shortcut for -xnone -xdebug.
-
-`-xdebugx'
- This is a shortcut for -xexplicit -xdebug.
-
-
-\1f
-File: as.info, Node: IA-64 Syntax, Next: IA-64 Opcodes, Prev: IA-64 Options, Up: IA-64-Dependent
-
-8.16.2 Syntax
--------------
-
-The assembler syntax closely follows the IA-64 Assembly Language
-Reference Guide.
-
-* Menu:
-
-* IA-64-Chars:: Special Characters
-* IA-64-Regs:: Register Names
-* IA-64-Bits:: Bit Names
-
-\1f
-File: as.info, Node: IA-64-Chars, Next: IA-64-Regs, Up: IA-64 Syntax
-
-8.16.2.1 Special Characters
-...........................
-
-`//' is the line comment token.
-
- `;' can be used instead of a newline to separate statements.
-
-\1f
-File: as.info, Node: IA-64-Regs, Next: IA-64-Bits, Prev: IA-64-Chars, Up: IA-64 Syntax
-
-8.16.2.2 Register Names
-.......................
-
-The 128 integer registers are referred to as `rN'. The 128
-floating-point registers are referred to as `fN'. The 128 application
-registers are referred to as `arN'. The 128 control registers are
-referred to as `crN'. The 64 one-bit predicate registers are referred
-to as `pN'. The 8 branch registers are referred to as `bN'. In
-addition, the assembler defines a number of aliases: `gp' (`r1'), `sp'
-(`r12'), `rp' (`b0'), `ret0' (`r8'), `ret1' (`r9'), `ret2' (`r10'),
-`ret3' (`r9'), `fargN' (`f8+N'), and `fretN' (`f8+N').
-
- For convenience, the assembler also defines aliases for all named
-application and control registers. For example, `ar.bsp' refers to the
-register backing store pointer (`ar17'). Similarly, `cr.eoi' refers to
-the end-of-interrupt register (`cr67').
-
-\1f
-File: as.info, Node: IA-64-Bits, Prev: IA-64-Regs, Up: IA-64 Syntax
-
-8.16.2.3 IA-64 Processor-Status-Register (PSR) Bit Names
-........................................................
-
-The assembler defines bit masks for each of the bits in the IA-64
-processor status register. For example, `psr.ic' corresponds to a
-value of 0x2000. These masks are primarily intended for use with the
-`ssm'/`sum' and `rsm'/`rum' instructions, but they can be used anywhere
-else where an integer constant is expected.
-
-\1f
-File: as.info, Node: IA-64 Opcodes, Prev: IA-64 Syntax, Up: IA-64-Dependent
-
-8.16.3 Opcodes
---------------
-
-For detailed information on the IA-64 machine instruction set, see the
-IA-64 Architecture Handbook
-(http://developer.intel.com/design/itanium/arch_spec.htm).
-
-\1f
-File: as.info, Node: IP2K-Dependent, Next: M32C-Dependent, Prev: IA-64-Dependent, Up: Machine Dependencies
-
-8.17 IP2K Dependent Features
-============================
-
-* Menu:
-
-* IP2K-Opts:: IP2K Options
-
-\1f
-File: as.info, Node: IP2K-Opts, Up: IP2K-Dependent
-
-8.17.1 IP2K Options
--------------------
-
-The Ubicom IP2K version of `as' has a few machine dependent options:
-
-`-mip2022ext'
- `as' can assemble the extended IP2022 instructions, but it will
- only do so if this is specifically allowed via this command line
- option.
-
-`-mip2022'
- This option restores the assembler's default behaviour of not
- permitting the extended IP2022 instructions to be assembled.
-
-
-\1f
-File: as.info, Node: M32C-Dependent, Next: M32R-Dependent, Prev: IP2K-Dependent, Up: Machine Dependencies
-
-8.18 M32C Dependent Features
-============================
-
- `as' can assemble code for several different members of the Renesas
-M32C family. Normally the default is to assemble code for the M16C
-microprocessor. The `-m32c' option may be used to change the default
-to the M32C microprocessor.
-
-* Menu:
-
-* M32C-Opts:: M32C Options
-* M32C-Modifiers:: Symbolic Operand Modifiers
-
-\1f
-File: as.info, Node: M32C-Opts, Next: M32C-Modifiers, Up: M32C-Dependent
-
-8.18.1 M32C Options
--------------------
-
-The Renesas M32C version of `as' has two machine-dependent options:
-
-`-m32c'
- Assemble M32C instructions.
-
-`-m16c'
- Assemble M16C instructions (default).
-
-
-\1f
-File: as.info, Node: M32C-Modifiers, Prev: M32C-Opts, Up: M32C-Dependent
-
-8.18.2 Symbolic Operand Modifiers
----------------------------------
-
-The assembler supports several modifiers when using symbol addresses in
-M32C instruction operands. The general syntax is the following:
-
- %modifier(symbol)
-
-`%dsp8'
-`%dsp16'
- These modifiers override the assembler's assumptions about how big
- a symbol's address is. Normally, when it sees an operand like
- `sym[a0]' it assumes `sym' may require the widest displacement
- field (16 bits for `-m16c', 24 bits for `-m32c'). These modifiers
- tell it to assume the address will fit in an 8 or 16 bit
- (respectively) unsigned displacement. Note that, of course, if it
- doesn't actually fit you will get linker errors. Example:
-
- mov.w %dsp8(sym)[a0],r1
- mov.b #0,%dsp8(sym)[a0]
-
-`%hi8'
- This modifier allows you to load bits 16 through 23 of a 24 bit
- address into an 8 bit register. This is useful with, for example,
- the M16C `smovf' instruction, which expects a 20 bit address in
- `r1h' and `a0'. Example:
-
- mov.b #%hi8(sym),r1h
- mov.w #%lo16(sym),a0
- smovf.b
-
-`%lo16'
- Likewise, this modifier allows you to load bits 0 through 15 of a
- 24 bit address into a 16 bit register.
-
-`%hi16'
- This modifier allows you to load bits 16 through 31 of a 32 bit
- address into a 16 bit register. While the M32C family only has 24
- bits of address space, it does support addresses in pairs of 16 bit
- registers (like `a1a0' for the `lde' instruction). This modifier
- is for loading the upper half in such cases. Example:
-
- mov.w #%hi16(sym),a1
- mov.w #%lo16(sym),a0
- ...
- lde.w [a1a0],r1
-
-
-\1f
-File: as.info, Node: M32R-Dependent, Next: M68K-Dependent, Prev: M32C-Dependent, Up: Machine Dependencies
-
-8.19 M32R Dependent Features
-============================
-
-* Menu:
-
-* M32R-Opts:: M32R Options
-* M32R-Directives:: M32R Directives
-* M32R-Warnings:: M32R Warnings
-
-\1f
-File: as.info, Node: M32R-Opts, Next: M32R-Directives, Up: M32R-Dependent
-
-8.19.1 M32R Options
--------------------
-
-The Renease M32R version of `as' has a few machine dependent options:
-
-`-m32rx'
- `as' can assemble code for several different members of the
- Renesas M32R family. Normally the default is to assemble code for
- the M32R microprocessor. This option may be used to change the
- default to the M32RX microprocessor, which adds some more
- instructions to the basic M32R instruction set, and some
- additional parameters to some of the original instructions.
-
-`-m32r2'
- This option changes the target processor to the the M32R2
- microprocessor.
-
-`-m32r'
- This option can be used to restore the assembler's default
- behaviour of assembling for the M32R microprocessor. This can be
- useful if the default has been changed by a previous command line
- option.
-
-`-little'
- This option tells the assembler to produce little-endian code and
- data. The default is dependent upon how the toolchain was
- configured.
-
-`-EL'
- This is a synonym for _-little_.
-
-`-big'
- This option tells the assembler to produce big-endian code and
- data.
-
-`-EB'
- This is a synonum for _-big_.
-
-`-KPIC'
- This option specifies that the output of the assembler should be
- marked as position-independent code (PIC).
-
-`-parallel'
- This option tells the assembler to attempts to combine two
- sequential instructions into a single, parallel instruction, where
- it is legal to do so.
-
-`-no-parallel'
- This option disables a previously enabled _-parallel_ option.
-
-`-no-bitinst'
- This option disables the support for the extended bit-field
- instructions provided by the M32R2. If this support needs to be
- re-enabled the _-bitinst_ switch can be used to restore it.
-
-`-O'
- This option tells the assembler to attempt to optimize the
- instructions that it produces. This includes filling delay slots
- and converting sequential instructions into parallel ones. This
- option implies _-parallel_.
-
-`-warn-explicit-parallel-conflicts'
- Instructs `as' to produce warning messages when questionable
- parallel instructions are encountered. This option is enabled by
- default, but `gcc' disables it when it invokes `as' directly.
- Questionable instructions are those whose behaviour would be
- different if they were executed sequentially. For example the
- code fragment `mv r1, r2 || mv r3, r1' produces a different result
- from `mv r1, r2 \n mv r3, r1' since the former moves r1 into r3
- and then r2 into r1, whereas the later moves r2 into r1 and r3.
-
-`-Wp'
- This is a shorter synonym for the
- _-warn-explicit-parallel-conflicts_ option.
-
-`-no-warn-explicit-parallel-conflicts'
- Instructs `as' not to produce warning messages when questionable
- parallel instructions are encountered.
-
-`-Wnp'
- This is a shorter synonym for the
- _-no-warn-explicit-parallel-conflicts_ option.
-
-`-ignore-parallel-conflicts'
- This option tells the assembler's to stop checking parallel
- instructions for constraint violations. This ability is provided
- for hardware vendors testing chip designs and should not be used
- under normal circumstances.
-
-`-no-ignore-parallel-conflicts'
- This option restores the assembler's default behaviour of checking
- parallel instructions to detect constraint violations.
-
-`-Ip'
- This is a shorter synonym for the _-ignore-parallel-conflicts_
- option.
-
-`-nIp'
- This is a shorter synonym for the _-no-ignore-parallel-conflicts_
- option.
-
-`-warn-unmatched-high'
- This option tells the assembler to produce a warning message if a
- `.high' pseudo op is encountered without a matching `.low' pseudo
- op. The presence of such an unmatched pseudo op usually indicates
- a programming error.
-
-`-no-warn-unmatched-high'
- Disables a previously enabled _-warn-unmatched-high_ option.
-
-`-Wuh'
- This is a shorter synonym for the _-warn-unmatched-high_ option.
-
-`-Wnuh'
- This is a shorter synonym for the _-no-warn-unmatched-high_ option.
-
-
-\1f
-File: as.info, Node: M32R-Directives, Next: M32R-Warnings, Prev: M32R-Opts, Up: M32R-Dependent
-
-8.19.2 M32R Directives
-----------------------
-
-The Renease M32R version of `as' has a few architecture specific
-directives:
-
-`low EXPRESSION'
- The `low' directive computes the value of its expression and
- places the lower 16-bits of the result into the immediate-field of
- the instruction. For example:
-
- or3 r0, r0, #low(0x12345678) ; compute r0 = r0 | 0x5678
- add3, r0, r0, #low(fred) ; compute r0 = r0 + low 16-bits of address of fred
-
-`high EXPRESSION'
- The `high' directive computes the value of its expression and
- places the upper 16-bits of the result into the immediate-field of
- the instruction. For example:
-
- seth r0, #high(0x12345678) ; compute r0 = 0x12340000
- seth, r0, #high(fred) ; compute r0 = upper 16-bits of address of fred
-
-`shigh EXPRESSION'
- The `shigh' directive is very similar to the `high' directive. It
- also computes the value of its expression and places the upper
- 16-bits of the result into the immediate-field of the instruction.
- The difference is that `shigh' also checks to see if the lower
- 16-bits could be interpreted as a signed number, and if so it
- assumes that a borrow will occur from the upper-16 bits. To
- compensate for this the `shigh' directive pre-biases the upper 16
- bit value by adding one to it. For example:
-
- For example:
-
- seth r0, #shigh(0x12345678) ; compute r0 = 0x12340000
- seth r0, #shigh(0x00008000) ; compute r0 = 0x00010000
-
- In the second example the lower 16-bits are 0x8000. If these are
- treated as a signed value and sign extended to 32-bits then the
- value becomes 0xffff8000. If this value is then added to
- 0x00010000 then the result is 0x00008000.
-
- This behaviour is to allow for the different semantics of the
- `or3' and `add3' instructions. The `or3' instruction treats its
- 16-bit immediate argument as unsigned whereas the `add3' treats
- its 16-bit immediate as a signed value. So for example:
-
- seth r0, #shigh(0x00008000)
- add3 r0, r0, #low(0x00008000)
-
- Produces the correct result in r0, whereas:
-
- seth r0, #shigh(0x00008000)
- or3 r0, r0, #low(0x00008000)
-
- Stores 0xffff8000 into r0.
-
- Note - the `shigh' directive does not know where in the assembly
- source code the lower 16-bits of the value are going set, so it
- cannot check to make sure that an `or3' instruction is being used
- rather than an `add3' instruction. It is up to the programmer to
- make sure that correct directives are used.
-
-`.m32r'
- The directive performs a similar thing as the _-m32r_ command line
- option. It tells the assembler to only accept M32R instructions
- from now on. An instructions from later M32R architectures are
- refused.
-
-`.m32rx'
- The directive performs a similar thing as the _-m32rx_ command
- line option. It tells the assembler to start accepting the extra
- instructions in the M32RX ISA as well as the ordinary M32R ISA.
-
-`.m32r2'
- The directive performs a similar thing as the _-m32r2_ command
- line option. It tells the assembler to start accepting the extra
- instructions in the M32R2 ISA as well as the ordinary M32R ISA.
-
-`.little'
- The directive performs a similar thing as the _-little_ command
- line option. It tells the assembler to start producing
- little-endian code and data. This option should be used with care
- as producing mixed-endian binary files is fraught with danger.
-
-`.big'
- The directive performs a similar thing as the _-big_ command line
- option. It tells the assembler to start producing big-endian code
- and data. This option should be used with care as producing
- mixed-endian binary files is fraught with danger.
-
-
-\1f
-File: as.info, Node: M32R-Warnings, Prev: M32R-Directives, Up: M32R-Dependent
-
-8.19.3 M32R Warnings
---------------------
-
-There are several warning and error messages that can be produced by
-`as' which are specific to the M32R:
-
-`output of 1st instruction is the same as an input to 2nd instruction - is this intentional ?'
- This message is only produced if warnings for explicit parallel
- conflicts have been enabled. It indicates that the assembler has
- encountered a parallel instruction in which the destination
- register of the left hand instruction is used as an input register
- in the right hand instruction. For example in this code fragment
- `mv r1, r2 || neg r3, r1' register r1 is the destination of the
- move instruction and the input to the neg instruction.
-
-`output of 2nd instruction is the same as an input to 1st instruction - is this intentional ?'
- This message is only produced if warnings for explicit parallel
- conflicts have been enabled. It indicates that the assembler has
- encountered a parallel instruction in which the destination
- register of the right hand instruction is used as an input
- register in the left hand instruction. For example in this code
- fragment `mv r1, r2 || neg r2, r3' register r2 is the destination
- of the neg instruction and the input to the move instruction.
-
-`instruction `...' is for the M32RX only'
- This message is produced when the assembler encounters an
- instruction which is only supported by the M32Rx processor, and
- the `-m32rx' command line flag has not been specified to allow
- assembly of such instructions.
-
-`unknown instruction `...''
- This message is produced when the assembler encounters an
- instruction which it does not recognize.
-
-`only the NOP instruction can be issued in parallel on the m32r'
- This message is produced when the assembler encounters a parallel
- instruction which does not involve a NOP instruction and the
- `-m32rx' command line flag has not been specified. Only the M32Rx
- processor is able to execute two instructions in parallel.
-
-`instruction `...' cannot be executed in parallel.'
- This message is produced when the assembler encounters a parallel
- instruction which is made up of one or two instructions which
- cannot be executed in parallel.
-
-`Instructions share the same execution pipeline'
- This message is produced when the assembler encounters a parallel
- instruction whoes components both use the same execution pipeline.
-
-`Instructions write to the same destination register.'
- This message is produced when the assembler encounters a parallel
- instruction where both components attempt to modify the same
- register. For example these code fragments will produce this
- message: `mv r1, r2 || neg r1, r3' `jl r0 || mv r14, r1' `st r2,
- @-r1 || mv r1, r3' `mv r1, r2 || ld r0, @r1+' `cmp r1, r2 || addx
- r3, r4' (Both write to the condition bit)
-
-
-\1f
-File: as.info, Node: M68K-Dependent, Next: M68HC11-Dependent, Prev: M32R-Dependent, Up: Machine Dependencies
-
-8.20 M680x0 Dependent Features
-==============================
-
-* Menu:
-
-* M68K-Opts:: M680x0 Options
-* M68K-Syntax:: Syntax
-* M68K-Moto-Syntax:: Motorola Syntax
-* M68K-Float:: Floating Point
-* M68K-Directives:: 680x0 Machine Directives
-* M68K-opcodes:: Opcodes
-
-\1f
-File: as.info, Node: M68K-Opts, Next: M68K-Syntax, Up: M68K-Dependent
-
-8.20.1 M680x0 Options
----------------------
-
-The Motorola 680x0 version of `as' has a few machine dependent options:
-
-`-march=ARCHITECTURE'
- This option specifies a target architecture. The following
- architectures are recognized: `68000', `68010', `68020', `68030',
- `68040', `68060', `cpu32', `isaa', `isaaplus', `isab', `isac' and
- `cfv4e'.
-
-`-mcpu=CPU'
- This option specifies a target cpu. When used in conjunction with
- the `-march' option, the cpu must be within the specified
- architecture. Also, the generic features of the architecture are
- used for instruction generation, rather than those of the specific
- chip.
-
-`-m[no-]68851'
-
-`-m[no-]68881'
-
-`-m[no-]div'
-
-`-m[no-]usp'
-
-`-m[no-]float'
-
-`-m[no-]mac'
-
-`-m[no-]emac'
- Enable or disable various architecture specific features. If a
- chip or architecture by default supports an option (for instance
- `-march=isaaplus' includes the `-mdiv' option), explicitly
- disabling the option will override the default.
-
-`-l'
- You can use the `-l' option to shorten the size of references to
- undefined symbols. If you do not use the `-l' option, references
- to undefined symbols are wide enough for a full `long' (32 bits).
- (Since `as' cannot know where these symbols end up, `as' can only
- allocate space for the linker to fill in later. Since `as' does
- not know how far away these symbols are, it allocates as much
- space as it can.) If you use this option, the references are only
- one word wide (16 bits). This may be useful if you want the
- object file to be as small as possible, and you know that the
- relevant symbols are always less than 17 bits away.
-
-`--register-prefix-optional'
- For some configurations, especially those where the compiler
- normally does not prepend an underscore to the names of user
- variables, the assembler requires a `%' before any use of a
- register name. This is intended to let the assembler distinguish
- between C variables and functions named `a0' through `a7', and so
- on. The `%' is always accepted, but is not required for certain
- configurations, notably `sun3'. The `--register-prefix-optional'
- option may be used to permit omitting the `%' even for
- configurations for which it is normally required. If this is
- done, it will generally be impossible to refer to C variables and
- functions with the same names as register names.
-
-`--bitwise-or'
- Normally the character `|' is treated as a comment character, which
- means that it can not be used in expressions. The `--bitwise-or'
- option turns `|' into a normal character. In this mode, you must
- either use C style comments, or start comments with a `#' character
- at the beginning of a line.
-
-`--base-size-default-16 --base-size-default-32'
- If you use an addressing mode with a base register without
- specifying the size, `as' will normally use the full 32 bit value.
- For example, the addressing mode `%a0@(%d0)' is equivalent to
- `%a0@(%d0:l)'. You may use the `--base-size-default-16' option to
- tell `as' to default to using the 16 bit value. In this case,
- `%a0@(%d0)' is equivalent to `%a0@(%d0:w)'. You may use the
- `--base-size-default-32' option to restore the default behaviour.
-
-`--disp-size-default-16 --disp-size-default-32'
- If you use an addressing mode with a displacement, and the value
- of the displacement is not known, `as' will normally assume that
- the value is 32 bits. For example, if the symbol `disp' has not
- been defined, `as' will assemble the addressing mode
- `%a0@(disp,%d0)' as though `disp' is a 32 bit value. You may use
- the `--disp-size-default-16' option to tell `as' to instead assume
- that the displacement is 16 bits. In this case, `as' will
- assemble `%a0@(disp,%d0)' as though `disp' is a 16 bit value. You
- may use the `--disp-size-default-32' option to restore the default
- behaviour.
-
-`--pcrel'
- Always keep branches PC-relative. In the M680x0 architecture all
- branches are defined as PC-relative. However, on some processors
- they are limited to word displacements maximum. When `as' needs a
- long branch that is not available, it normally emits an absolute
- jump instead. This option disables this substitution. When this
- option is given and no long branches are available, only word
- branches will be emitted. An error message will be generated if a
- word branch cannot reach its target. This option has no effect on
- 68020 and other processors that have long branches. *note Branch
- Improvement: M68K-Branch.
-
-`-m68000'
- `as' can assemble code for several different members of the
- Motorola 680x0 family. The default depends upon how `as' was
- configured when it was built; normally, the default is to assemble
- code for the 68020 microprocessor. The following options may be
- used to change the default. These options control which
- instructions and addressing modes are permitted. The members of
- the 680x0 family are very similar. For detailed information about
- the differences, see the Motorola manuals.
-
- `-m68000'
- `-m68ec000'
- `-m68hc000'
- `-m68hc001'
- `-m68008'
- `-m68302'
- `-m68306'
- `-m68307'
- `-m68322'
- `-m68356'
- Assemble for the 68000. `-m68008', `-m68302', and so on are
- synonyms for `-m68000', since the chips are the same from the
- point of view of the assembler.
-
- `-m68010'
- Assemble for the 68010.
-
- `-m68020'
- `-m68ec020'
- Assemble for the 68020. This is normally the default.
-
- `-m68030'
- `-m68ec030'
- Assemble for the 68030.
-
- `-m68040'
- `-m68ec040'
- Assemble for the 68040.
-
- `-m68060'
- `-m68ec060'
- Assemble for the 68060.
-
- `-mcpu32'
- `-m68330'
- `-m68331'
- `-m68332'
- `-m68333'
- `-m68334'
- `-m68336'
- `-m68340'
- `-m68341'
- `-m68349'
- `-m68360'
- Assemble for the CPU32 family of chips.
-
- `-m5200'
-
- `-m5202'
-
- `-m5204'
-
- `-m5206'
-
- `-m5206e'
-
- `-m521x'
-
- `-m5249'
-
- `-m528x'
-
- `-m5307'
-
- `-m5407'
-
- `-m547x'
-
- `-m548x'
-
- `-mcfv4'
-
- `-mcfv4e'
- Assemble for the ColdFire family of chips.
-
- `-m68881'
- `-m68882'
- Assemble 68881 floating point instructions. This is the
- default for the 68020, 68030, and the CPU32. The 68040 and
- 68060 always support floating point instructions.
-
- `-mno-68881'
- Do not assemble 68881 floating point instructions. This is
- the default for 68000 and the 68010. The 68040 and 68060
- always support floating point instructions, even if this
- option is used.
-
- `-m68851'
- Assemble 68851 MMU instructions. This is the default for the
- 68020, 68030, and 68060. The 68040 accepts a somewhat
- different set of MMU instructions; `-m68851' and `-m68040'
- should not be used together.
-
- `-mno-68851'
- Do not assemble 68851 MMU instructions. This is the default
- for the 68000, 68010, and the CPU32. The 68040 accepts a
- somewhat different set of MMU instructions.
-
-\1f
-File: as.info, Node: M68K-Syntax, Next: M68K-Moto-Syntax, Prev: M68K-Opts, Up: M68K-Dependent
-
-8.20.2 Syntax
--------------
-
-This syntax for the Motorola 680x0 was developed at MIT.
-
- The 680x0 version of `as' uses instructions names and syntax
-compatible with the Sun assembler. Intervening periods are ignored;
-for example, `movl' is equivalent to `mov.l'.
-
- In the following table APC stands for any of the address registers
-(`%a0' through `%a7'), the program counter (`%pc'), the zero-address
-relative to the program counter (`%zpc'), a suppressed address register
-(`%za0' through `%za7'), or it may be omitted entirely. The use of
-SIZE means one of `w' or `l', and it may be omitted, along with the
-leading colon, unless a scale is also specified. The use of SCALE
-means one of `1', `2', `4', or `8', and it may always be omitted along
-with the leading colon.
-
- The following addressing modes are understood:
-"Immediate"
- `#NUMBER'
-
-"Data Register"
- `%d0' through `%d7'
-
-"Address Register"
- `%a0' through `%a7'
- `%a7' is also known as `%sp', i.e., the Stack Pointer. `%a6' is
- also known as `%fp', the Frame Pointer.
-
-"Address Register Indirect"
- `%a0@' through `%a7@'
-
-"Address Register Postincrement"
- `%a0@+' through `%a7@+'
-
-"Address Register Predecrement"
- `%a0@-' through `%a7@-'
-
-"Indirect Plus Offset"
- `APC@(NUMBER)'
-
-"Index"
- `APC@(NUMBER,REGISTER:SIZE:SCALE)'
-
- The NUMBER may be omitted.
-
-"Postindex"
- `APC@(NUMBER)@(ONUMBER,REGISTER:SIZE:SCALE)'
-
- The ONUMBER or the REGISTER, but not both, may be omitted.
-
-"Preindex"
- `APC@(NUMBER,REGISTER:SIZE:SCALE)@(ONUMBER)'
-
- The NUMBER may be omitted. Omitting the REGISTER produces the
- Postindex addressing mode.
-
-"Absolute"
- `SYMBOL', or `DIGITS', optionally followed by `:b', `:w', or `:l'.
-
-\1f
-File: as.info, Node: M68K-Moto-Syntax, Next: M68K-Float, Prev: M68K-Syntax, Up: M68K-Dependent
-
-8.20.3 Motorola Syntax
-----------------------
-
-The standard Motorola syntax for this chip differs from the syntax
-already discussed (*note Syntax: M68K-Syntax.). `as' can accept
-Motorola syntax for operands, even if MIT syntax is used for other
-operands in the same instruction. The two kinds of syntax are fully
-compatible.
-
- In the following table APC stands for any of the address registers
-(`%a0' through `%a7'), the program counter (`%pc'), the zero-address
-relative to the program counter (`%zpc'), or a suppressed address
-register (`%za0' through `%za7'). The use of SIZE means one of `w' or
-`l', and it may always be omitted along with the leading dot. The use
-of SCALE means one of `1', `2', `4', or `8', and it may always be
-omitted along with the leading asterisk.
-
- The following additional addressing modes are understood:
-
-"Address Register Indirect"
- `(%a0)' through `(%a7)'
- `%a7' is also known as `%sp', i.e., the Stack Pointer. `%a6' is
- also known as `%fp', the Frame Pointer.
-
-"Address Register Postincrement"
- `(%a0)+' through `(%a7)+'
-
-"Address Register Predecrement"
- `-(%a0)' through `-(%a7)'
-
-"Indirect Plus Offset"
- `NUMBER(%A0)' through `NUMBER(%A7)', or `NUMBER(%PC)'.
-
- The NUMBER may also appear within the parentheses, as in
- `(NUMBER,%A0)'. When used with the PC, the NUMBER may be omitted
- (with an address register, omitting the NUMBER produces Address
- Register Indirect mode).
-
-"Index"
- `NUMBER(APC,REGISTER.SIZE*SCALE)'
-
- The NUMBER may be omitted, or it may appear within the
- parentheses. The APC may be omitted. The REGISTER and the APC
- may appear in either order. If both APC and REGISTER are address
- registers, and the SIZE and SCALE are omitted, then the first
- register is taken as the base register, and the second as the
- index register.
-
-"Postindex"
- `([NUMBER,APC],REGISTER.SIZE*SCALE,ONUMBER)'
-
- The ONUMBER, or the REGISTER, or both, may be omitted. Either the
- NUMBER or the APC may be omitted, but not both.
-
-"Preindex"
- `([NUMBER,APC,REGISTER.SIZE*SCALE],ONUMBER)'
-
- The NUMBER, or the APC, or the REGISTER, or any two of them, may
- be omitted. The ONUMBER may be omitted. The REGISTER and the APC
- may appear in either order. If both APC and REGISTER are address
- registers, and the SIZE and SCALE are omitted, then the first
- register is taken as the base register, and the second as the
- index register.
-
-\1f
-File: as.info, Node: M68K-Float, Next: M68K-Directives, Prev: M68K-Moto-Syntax, Up: M68K-Dependent
-
-8.20.4 Floating Point
----------------------
-
-Packed decimal (P) format floating literals are not supported. Feel
-free to add the code!
-
- The floating point formats generated by directives are these.
-
-`.float'
- `Single' precision floating point constants.
-
-`.double'
- `Double' precision floating point constants.
-
-`.extend'
-`.ldouble'
- `Extended' precision (`long double') floating point constants.
-
-\1f
-File: as.info, Node: M68K-Directives, Next: M68K-opcodes, Prev: M68K-Float, Up: M68K-Dependent
-
-8.20.5 680x0 Machine Directives
--------------------------------
-
-In order to be compatible with the Sun assembler the 680x0 assembler
-understands the following directives.
-
-`.data1'
- This directive is identical to a `.data 1' directive.
-
-`.data2'
- This directive is identical to a `.data 2' directive.
-
-`.even'
- This directive is a special case of the `.align' directive; it
- aligns the output to an even byte boundary.
-
-`.skip'
- This directive is identical to a `.space' directive.
-
-`.arch NAME'
- Select the target architecture and extension features. Valid
- values for NAME are the same as for the `-march' command line
- option. This directive cannot be specified after any instructions
- have been assembled. If it is given multiple times, or in
- conjunction with the `-march' option, all uses must be for the
- same architecture and extension set.
-
-`.cpu NAME'
- Select the target cpu. Valid valuse for NAME are the same as for
- the `-mcpu' command line option. This directive cannot be
- specified after any instructions have been assembled. If it is
- given multiple times, or in conjunction with the `-mopt' option,
- all uses must be for the same cpu.
-
-
-\1f
-File: as.info, Node: M68K-opcodes, Prev: M68K-Directives, Up: M68K-Dependent
-
-8.20.6 Opcodes
---------------
-
-* Menu:
-
-* M68K-Branch:: Branch Improvement
-* M68K-Chars:: Special Characters
-
-\1f
-File: as.info, Node: M68K-Branch, Next: M68K-Chars, Up: M68K-opcodes
-
-8.20.6.1 Branch Improvement
-...........................
-
-Certain pseudo opcodes are permitted for branch instructions. They
-expand to the shortest branch instruction that reach the target.
-Generally these mnemonics are made by substituting `j' for `b' at the
-start of a Motorola mnemonic.
-
- The following table summarizes the pseudo-operations. A `*' flags
-cases that are more fully described after the table:
-
- Displacement
- +------------------------------------------------------------
- | 68020 68000/10, not PC-relative OK
- Pseudo-Op |BYTE WORD LONG ABSOLUTE LONG JUMP **
- +------------------------------------------------------------
- jbsr |bsrs bsrw bsrl jsr
- jra |bras braw bral jmp
- * jXX |bXXs bXXw bXXl bNXs;jmp
- * dbXX | N/A dbXXw dbXX;bras;bral dbXX;bras;jmp
- fjXX | N/A fbXXw fbXXl N/A
-
- XX: condition
- NX: negative of condition XX
- `*'--see full description below
- `**'--this expansion mode is disallowed by `--pcrel'
-
-`jbsr'
-`jra'
- These are the simplest jump pseudo-operations; they always map to
- one particular machine instruction, depending on the displacement
- to the branch target. This instruction will be a byte or word
- branch is that is sufficient. Otherwise, a long branch will be
- emitted if available. If no long branches are available and the
- `--pcrel' option is not given, an absolute long jump will be
- emitted instead. If no long branches are available, the `--pcrel'
- option is given, and a word branch cannot reach the target, an
- error message is generated.
-
- In addition to standard branch operands, `as' allows these
- pseudo-operations to have all operands that are allowed for jsr
- and jmp, substituting these instructions if the operand given is
- not valid for a branch instruction.
-
-`jXX'
- Here, `jXX' stands for an entire family of pseudo-operations,
- where XX is a conditional branch or condition-code test. The full
- list of pseudo-ops in this family is:
- jhi jls jcc jcs jne jeq jvc
- jvs jpl jmi jge jlt jgt jle
-
- Usually, each of these pseudo-operations expands to a single branch
- instruction. However, if a word branch is not sufficient, no long
- branches are available, and the `--pcrel' option is not given, `as'
- issues a longer code fragment in terms of NX, the opposite
- condition to XX. For example, under these conditions:
- jXX foo
- gives
- bNXs oof
- jmp foo
- oof:
-
-`dbXX'
- The full family of pseudo-operations covered here is
- dbhi dbls dbcc dbcs dbne dbeq dbvc
- dbvs dbpl dbmi dbge dblt dbgt dble
- dbf dbra dbt
-
- Motorola `dbXX' instructions allow word displacements only. When
- a word displacement is sufficient, each of these pseudo-operations
- expands to the corresponding Motorola instruction. When a word
- displacement is not sufficient and long branches are available,
- when the source reads `dbXX foo', `as' emits
- dbXX oo1
- bras oo2
- oo1:bral foo
- oo2:
-
- If, however, long branches are not available and the `--pcrel'
- option is not given, `as' emits
- dbXX oo1
- bras oo2
- oo1:jmp foo
- oo2:
-
-`fjXX'
- This family includes
- fjne fjeq fjge fjlt fjgt fjle fjf
- fjt fjgl fjgle fjnge fjngl fjngle fjngt
- fjnle fjnlt fjoge fjogl fjogt fjole fjolt
- fjor fjseq fjsf fjsne fjst fjueq fjuge
- fjugt fjule fjult fjun
-
- Each of these pseudo-operations always expands to a single Motorola
- coprocessor branch instruction, word or long. All Motorola
- coprocessor branch instructions allow both word and long
- displacements.
-
-
-\1f
-File: as.info, Node: M68K-Chars, Prev: M68K-Branch, Up: M68K-opcodes
-
-8.20.6.2 Special Characters
-...........................
-
-The immediate character is `#' for Sun compatibility. The line-comment
-character is `|' (unless the `--bitwise-or' option is used). If a `#'
-appears at the beginning of a line, it is treated as a comment unless
-it looks like `# line file', in which case it is treated normally.
-
-\1f
-File: as.info, Node: M68HC11-Dependent, Next: MIPS-Dependent, Prev: M68K-Dependent, Up: Machine Dependencies
-
-8.21 M68HC11 and M68HC12 Dependent Features
-===========================================
-
-* Menu:
-
-* M68HC11-Opts:: M68HC11 and M68HC12 Options
-* M68HC11-Syntax:: Syntax
-* M68HC11-Modifiers:: Symbolic Operand Modifiers
-* M68HC11-Directives:: Assembler Directives
-* M68HC11-Float:: Floating Point
-* M68HC11-opcodes:: Opcodes
-
-\1f
-File: as.info, Node: M68HC11-Opts, Next: M68HC11-Syntax, Up: M68HC11-Dependent
-
-8.21.1 M68HC11 and M68HC12 Options
-----------------------------------
-
-The Motorola 68HC11 and 68HC12 version of `as' have a few machine
-dependent options.
-
-`-m68hc11'
- This option switches the assembler in the M68HC11 mode. In this
- mode, the assembler only accepts 68HC11 operands and mnemonics. It
- produces code for the 68HC11.
-
-`-m68hc12'
- This option switches the assembler in the M68HC12 mode. In this
- mode, the assembler also accepts 68HC12 operands and mnemonics. It
- produces code for the 68HC12. A few 68HC11 instructions are
- replaced by some 68HC12 instructions as recommended by Motorola
- specifications.
-
-`-m68hcs12'
- This option switches the assembler in the M68HCS12 mode. This
- mode is similar to `-m68hc12' but specifies to assemble for the
- 68HCS12 series. The only difference is on the assembling of the
- `movb' and `movw' instruction when a PC-relative operand is used.
-
-`-mshort'
- This option controls the ABI and indicates to use a 16-bit integer
- ABI. It has no effect on the assembled instructions. This is the
- default.
-
-`-mlong'
- This option controls the ABI and indicates to use a 32-bit integer
- ABI.
-
-`-mshort-double'
- This option controls the ABI and indicates to use a 32-bit float
- ABI. This is the default.
-
-`-mlong-double'
- This option controls the ABI and indicates to use a 64-bit float
- ABI.
-
-`--strict-direct-mode'
- You can use the `--strict-direct-mode' option to disable the
- automatic translation of direct page mode addressing into extended
- mode when the instruction does not support direct mode. For
- example, the `clr' instruction does not support direct page mode
- addressing. When it is used with the direct page mode, `as' will
- ignore it and generate an absolute addressing. This option
- prevents `as' from doing this, and the wrong usage of the direct
- page mode will raise an error.
-
-`--short-branches'
- The `--short-branches' option turns off the translation of
- relative branches into absolute branches when the branch offset is
- out of range. By default `as' transforms the relative branch
- (`bsr', `bgt', `bge', `beq', `bne', `ble', `blt', `bhi', `bcc',
- `bls', `bcs', `bmi', `bvs', `bvs', `bra') into an absolute branch
- when the offset is out of the -128 .. 127 range. In that case,
- the `bsr' instruction is translated into a `jsr', the `bra'
- instruction is translated into a `jmp' and the conditional
- branches instructions are inverted and followed by a `jmp'. This
- option disables these translations and `as' will generate an error
- if a relative branch is out of range. This option does not affect
- the optimization associated to the `jbra', `jbsr' and `jbXX'
- pseudo opcodes.
-
-`--force-long-branches'
- The `--force-long-branches' option forces the translation of
- relative branches into absolute branches. This option does not
- affect the optimization associated to the `jbra', `jbsr' and
- `jbXX' pseudo opcodes.
-
-`--print-insn-syntax'
- You can use the `--print-insn-syntax' option to obtain the syntax
- description of the instruction when an error is detected.
-
-`--print-opcodes'
- The `--print-opcodes' option prints the list of all the
- instructions with their syntax. The first item of each line
- represents the instruction name and the rest of the line indicates
- the possible operands for that instruction. The list is printed in
- alphabetical order. Once the list is printed `as' exits.
-
-`--generate-example'
- The `--generate-example' option is similar to `--print-opcodes'
- but it generates an example for each instruction instead.
-
-\1f
-File: as.info, Node: M68HC11-Syntax, Next: M68HC11-Modifiers, Prev: M68HC11-Opts, Up: M68HC11-Dependent
-
-8.21.2 Syntax
--------------
-
-In the M68HC11 syntax, the instruction name comes first and it may be
-followed by one or several operands (up to three). Operands are
-separated by comma (`,'). In the normal mode, `as' will complain if too
-many operands are specified for a given instruction. In the MRI mode
-(turned on with `-M' option), it will treat them as comments. Example:
-
- inx
- lda #23
- bset 2,x #4
- brclr *bot #8 foo
-
- The following addressing modes are understood for 68HC11 and 68HC12:
-"Immediate"
- `#NUMBER'
-
-"Address Register"
- `NUMBER,X', `NUMBER,Y'
-
- The NUMBER may be omitted in which case 0 is assumed.
-
-"Direct Addressing mode"
- `*SYMBOL', or `*DIGITS'
-
-"Absolute"
- `SYMBOL', or `DIGITS'
-
- The M68HC12 has other more complex addressing modes. All of them are
-supported and they are represented below:
-
-"Constant Offset Indexed Addressing Mode"
- `NUMBER,REG'
-
- The NUMBER may be omitted in which case 0 is assumed. The
- register can be either `X', `Y', `SP' or `PC'. The assembler will
- use the smaller post-byte definition according to the constant
- value (5-bit constant offset, 9-bit constant offset or 16-bit
- constant offset). If the constant is not known by the assembler
- it will use the 16-bit constant offset post-byte and the value
- will be resolved at link time.
-
-"Offset Indexed Indirect"
- `[NUMBER,REG]'
-
- The register can be either `X', `Y', `SP' or `PC'.
-
-"Auto Pre-Increment/Pre-Decrement/Post-Increment/Post-Decrement"
- `NUMBER,-REG' `NUMBER,+REG' `NUMBER,REG-' `NUMBER,REG+'
-
- The number must be in the range `-8'..`+8' and must not be 0. The
- register can be either `X', `Y', `SP' or `PC'.
-
-"Accumulator Offset"
- `ACC,REG'
-
- The accumulator register can be either `A', `B' or `D'. The
- register can be either `X', `Y', `SP' or `PC'.
-
-"Accumulator D offset indexed-indirect"
- `[D,REG]'
-
- The register can be either `X', `Y', `SP' or `PC'.
-
-
- For example:
-
- ldab 1024,sp
- ldd [10,x]
- orab 3,+x
- stab -2,y-
- ldx a,pc
- sty [d,sp]
-
-\1f
-File: as.info, Node: M68HC11-Modifiers, Next: M68HC11-Directives, Prev: M68HC11-Syntax, Up: M68HC11-Dependent
-
-8.21.3 Symbolic Operand Modifiers
----------------------------------
-
-The assembler supports several modifiers when using symbol addresses in
-68HC11 and 68HC12 instruction operands. The general syntax is the
-following:
-
- %modifier(symbol)
-
-`%addr'
- This modifier indicates to the assembler and linker to use the
- 16-bit physical address corresponding to the symbol. This is
- intended to be used on memory window systems to map a symbol in
- the memory bank window. If the symbol is in a memory expansion
- part, the physical address corresponds to the symbol address
- within the memory bank window. If the symbol is not in a memory
- expansion part, this is the symbol address (using or not using the
- %addr modifier has no effect in that case).
-
-`%page'
- This modifier indicates to use the memory page number corresponding
- to the symbol. If the symbol is in a memory expansion part, its
- page number is computed by the linker as a number used to map the
- page containing the symbol in the memory bank window. If the
- symbol is not in a memory expansion part, the page number is 0.
-
-`%hi'
- This modifier indicates to use the 8-bit high part of the physical
- address of the symbol.
-
-`%lo'
- This modifier indicates to use the 8-bit low part of the physical
- address of the symbol.
-
-
- For example a 68HC12 call to a function `foo_example' stored in
-memory expansion part could be written as follows:
-
- call %addr(foo_example),%page(foo_example)
-
- and this is equivalent to
-
- call foo_example
-
- And for 68HC11 it could be written as follows:
-
- ldab #%page(foo_example)
- stab _page_switch
- jsr %addr(foo_example)
-
-\1f
-File: as.info, Node: M68HC11-Directives, Next: M68HC11-Float, Prev: M68HC11-Modifiers, Up: M68HC11-Dependent
-
-8.21.4 Assembler Directives
----------------------------
-
-The 68HC11 and 68HC12 version of `as' have the following specific
-assembler directives:
-
-`.relax'
- The relax directive is used by the `GNU Compiler' to emit a
- specific relocation to mark a group of instructions for linker
- relaxation. The sequence of instructions within the group must be
- known to the linker so that relaxation can be performed.
-
-`.mode [mshort|mlong|mshort-double|mlong-double]'
- This directive specifies the ABI. It overrides the `-mshort',
- `-mlong', `-mshort-double' and `-mlong-double' options.
-
-`.far SYMBOL'
- This directive marks the symbol as a `far' symbol meaning that it
- uses a `call/rtc' calling convention as opposed to `jsr/rts'.
- During a final link, the linker will identify references to the
- `far' symbol and will verify the proper calling convention.
-
-`.interrupt SYMBOL'
- This directive marks the symbol as an interrupt entry point. This
- information is then used by the debugger to correctly unwind the
- frame across interrupts.
-
-`.xrefb SYMBOL'
- This directive is defined for compatibility with the
- `Specification for Motorola 8 and 16-Bit Assembly Language Input
- Standard' and is ignored.
-
-
-\1f
-File: as.info, Node: M68HC11-Float, Next: M68HC11-opcodes, Prev: M68HC11-Directives, Up: M68HC11-Dependent
-
-8.21.5 Floating Point
----------------------
-
-Packed decimal (P) format floating literals are not supported. Feel
-free to add the code!
-
- The floating point formats generated by directives are these.
-
-`.float'
- `Single' precision floating point constants.
-
-`.double'
- `Double' precision floating point constants.
-
-`.extend'
-`.ldouble'
- `Extended' precision (`long double') floating point constants.
-
-\1f
-File: as.info, Node: M68HC11-opcodes, Prev: M68HC11-Float, Up: M68HC11-Dependent
-
-8.21.6 Opcodes
---------------
-
-* Menu:
-
-* M68HC11-Branch:: Branch Improvement
-
-\1f
-File: as.info, Node: M68HC11-Branch, Up: M68HC11-opcodes
-
-8.21.6.1 Branch Improvement
-...........................
-
-Certain pseudo opcodes are permitted for branch instructions. They
-expand to the shortest branch instruction that reach the target.
-Generally these mnemonics are made by prepending `j' to the start of
-Motorola mnemonic. These pseudo opcodes are not affected by the
-`--short-branches' or `--force-long-branches' options.
-
- The following table summarizes the pseudo-operations.
-
- Displacement Width
- +-------------------------------------------------------------+
- | Options |
- | --short-branches --force-long-branches |
- +--------------------------+----------------------------------+
- Op |BYTE WORD | BYTE WORD |
- +--------------------------+----------------------------------+
- bsr | bsr <pc-rel> <error> | jsr <abs> |
- bra | bra <pc-rel> <error> | jmp <abs> |
- jbsr | bsr <pc-rel> jsr <abs> | bsr <pc-rel> jsr <abs> |
- jbra | bra <pc-rel> jmp <abs> | bra <pc-rel> jmp <abs> |
- bXX | bXX <pc-rel> <error> | bNX +3; jmp <abs> |
- jbXX | bXX <pc-rel> bNX +3; | bXX <pc-rel> bNX +3; jmp <abs> |
- | jmp <abs> | |
- +--------------------------+----------------------------------+
- XX: condition
- NX: negative of condition XX
-
-`jbsr'
-`jbra'
- These are the simplest jump pseudo-operations; they always map to
- one particular machine instruction, depending on the displacement
- to the branch target.
-
-`jbXX'
- Here, `jbXX' stands for an entire family of pseudo-operations,
- where XX is a conditional branch or condition-code test. The full
- list of pseudo-ops in this family is:
- jbcc jbeq jbge jbgt jbhi jbvs jbpl jblo
- jbcs jbne jblt jble jbls jbvc jbmi
-
- For the cases of non-PC relative displacements and long
- displacements, `as' issues a longer code fragment in terms of NX,
- the opposite condition to XX. For example, for the non-PC
- relative case:
- jbXX foo
- gives
- bNXs oof
- jmp foo
- oof:
-
-
-\1f
-File: as.info, Node: MIPS-Dependent, Next: MMIX-Dependent, Prev: M68HC11-Dependent, Up: Machine Dependencies
-
-8.22 MIPS Dependent Features
-============================
-
- GNU `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 `MIPS RISC
-Architecture', by Kane and Heindrich (Prentice-Hall). For an overview
-of MIPS assembly conventions, see "Appendix D: Assembly Language
-Programming" in the same work.
-
-* Menu:
-
-* MIPS Opts:: Assembler options
-* MIPS Object:: ECOFF object code
-* MIPS Stabs:: Directives for debugging information
-* MIPS ISA:: Directives to override the ISA level
-* MIPS symbol sizes:: Directives to override the size of symbols
-* MIPS autoextend:: Directives for extending MIPS 16 bit instructions
-* MIPS insn:: Directive to mark data as an instruction
-* MIPS option stack:: Directives to save and restore options
-* MIPS ASE instruction generation overrides:: Directives to control
- generation of MIPS ASE instructions
-
-\1f
-File: as.info, Node: MIPS Opts, Next: MIPS Object, Up: MIPS-Dependent
-
-8.22.1 Assembler options
-------------------------
-
-The MIPS configurations of GNU `as' support these special options:
-
-`-G NUM'
- This option sets the largest size of an object that can be
- referenced implicitly with the `gp' register. It is only accepted
- for targets that use ECOFF format. The default value is 8.
-
-`-EB'
-`-EL'
- Any MIPS configuration of `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 `-EB'
- to select big-endian output, and `-EL' for little-endian.
-
-`-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.
-
-`-mvxworks-pic'
- Generate VxWorks PIC. This option tells the assembler to generate
- VxWorks-style position-independent macro expansions.
-
-`-mips1'
-`-mips2'
-`-mips3'
-`-mips4'
-`-mips5'
-`-mips32'
-`-mips32r2'
-`-mips64'
-`-mips64r2'
- Generate code for a particular MIPS Instruction Set Architecture
- level. `-mips1' corresponds to the R2000 and R3000 processors,
- `-mips2' to the R6000 processor, `-mips3' to the R4000 processor,
- and `-mips4' to the R8000 and R10000 processors. `-mips5',
- `-mips32', `-mips32r2', `-mips64', and `-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 *Note Directives to
- override the ISA level: MIPS ISA.
-
-`-mgp32'
-`-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. `-mgp32' controls the size
- of general-purpose registers and `-mfp32' controls the size of
- floating-point registers.
-
- The `.set gp=32' and `.set fp=32' directives allow the size of
- registers to be changed for parts of an object. The default value
- is restored by `.set gp=default' and `.set fp=default'.
-
- 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.
-
-`-mgp64'
-`-mfp64'
- Assume that 64-bit registers are available. This is provided in
- the interests of symmetry with `-mgp32' and `-mfp32'.
-
- The `.set gp=64' and `.set fp=64' directives allow the size of
- registers to be changed for parts of an object. The default value
- is restored by `.set gp=default' and `.set fp=default'.
-
-`-mips16'
-`-no-mips16'
- Generate code for the MIPS 16 processor. This is equivalent to
- putting `.set mips16' at the start of the assembly file.
- `-no-mips16' turns off this option.
-
-`-msmartmips'
-`-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
- `.set smartmips' at the start of the assembly file.
- `-mno-smartmips' turns off this option.
-
-`-mips3d'
-`-no-mips3d'
- Generate code for the MIPS-3D Application Specific Extension.
- This tells the assembler to accept MIPS-3D instructions.
- `-no-mips3d' turns off this option.
-
-`-mdmx'
-`-no-mdmx'
- Generate code for the MDMX Application Specific Extension. This
- tells the assembler to accept MDMX instructions. `-no-mdmx' turns
- off this option.
-
-`-mdsp'
-`-mno-dsp'
- Generate code for the DSP Release 1 Application Specific Extension.
- This tells the assembler to accept DSP Release 1 instructions.
- `-mno-dsp' turns off this option.
-
-`-mdspr2'
-`-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. `-mno-dspr2' turns off this option.
-
-`-mmt'
-`-mno-mt'
- Generate code for the MT Application Specific Extension. This
- tells the assembler to accept MT instructions. `-mno-mt' turns
- off this option.
-
-`-mfix7000'
-`-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.
-
-`-mfix-vr4120'
-`-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.
-
-`-mfix-vr4130'
-`-no-mfix-vr4130'
- Insert nops to work around the VR4130 `mflo'/`mfhi' errata.
-
-`-m4010'
-`-no-m4010'
- Generate code for the LSI R4010 chip. This tells the assembler to
- accept the R4010 specific instructions (`addciu', `ffc', etc.),
- and to not schedule `nop' instructions around accesses to the `HI'
- and `LO' registers. `-no-m4010' turns off this option.
-
-`-m4650'
-`-no-m4650'
- Generate code for the MIPS R4650 chip. This tells the assembler
- to accept the `mad' and `madu' instruction, and to not schedule
- `nop' instructions around accesses to the `HI' and `LO' registers.
- `-no-m4650' turns off this option.
-
-`-m3900'
-`-no-m3900'
-`-m4100'
-`-no-m4100'
- For each option `-mNNNN', generate code for the MIPS RNNNN chip.
- This tells the assembler to accept instructions specific to that
- chip, and to schedule for that chip's hazards.
-
-`-march=CPU'
- Generate code for a particular MIPS cpu. It is exactly equivalent
- to `-mCPU', except that there are more value of CPU understood.
- Valid CPU value are:
-
- 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, 24kf2_1, 24kf, 24kf1_1, 24kec, 24kef2_1,
- 24kef, 24kef1_1, 34kc, 34kf2_1, 34kf, 34kf1_1, 74kc, 74kf2_1,
- 74kf, 74kf1_1, 74kf3_2, 5kc, 5kf, 20kc, 25kf, sb1, sb1a
-
- For compatibility reasons, `Nx' and `Bfx' are accepted as synonyms
- for `Nf1_1'. These values are deprecated.
-
-`-mtune=CPU'
- Schedule and tune for a particular MIPS cpu. Valid CPU values are
- identical to `-march=CPU'.
-
-`-mabi=ABI'
- Record which ABI the source code uses. The recognized arguments
- are: `32', `n32', `o64', `64' and `eabi'.
-
-`-msym32'
-`-mno-sym32'
- Equivalent to adding `.set sym32' or `.set nosym32' to the
- beginning of the assembler input. *Note MIPS symbol sizes::.
-
-`-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 `as', there is no need for
- `-nocpp', because the GNU assembler itself never runs the C
- preprocessor.
-
-`--construct-floats'
-`--no-construct-floats'
- The `--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.
-
- By default `--construct-floats' is selected, allowing construction
- of these floating point constants.
-
-`--trap'
-`--no-break'
- `as' automatically macro expands certain division and
- multiplication instructions to check for overflow and division by
- zero. This option causes `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.
-
-`--break'
-`--no-trap'
- Generate code to take a break exception rather than a trap
- exception when an error is detected. This is the default.
-
-`-mpdr'
-`-mno-pdr'
- Control generation of `.pdr' sections. Off by default on IRIX, on
- elsewhere.
-
-`-mshared'
-`-mno-shared'
- When generating code using the Unix calling conventions (selected
- by `-KPIC' or `-mcall_shared'), gas will normally generate code
- which can go into a shared library. The `-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
- `.cpload' and `.cpsetup' pseudo-ops.
-
-\1f
-File: as.info, Node: MIPS Object, Next: MIPS Stabs, Prev: MIPS Opts, Up: MIPS-Dependent
-
-8.22.2 MIPS ECOFF object code
------------------------------
-
-Assembling for a MIPS ECOFF target supports some additional sections
-besides the usual `.text', `.data' and `.bss'. The additional sections
-are `.rdata', used for read-only data, `.sdata', used for small data,
-and `.sbss', used for small common objects.
-
- When assembling for ECOFF, the assembler uses the `$gp' (`$28')
-register to form the address of a "small object". Any object in the
-`.sdata' or `.sbss' sections is considered "small" in this sense. For
-external objects, or for objects in the `.bss' section, you can use the
-`gcc' `-G' option to control the size of objects addressed via `$gp';
-the default value is 8, meaning that a reference to any object eight
-bytes or smaller uses `$gp'. Passing `-G 0' to `as' prevents it from
-using the `$gp' register on the basis of object size (but the assembler
-uses `$gp' for objects in `.sdata' or `sbss' in any case). The size of
-an object in the `.bss' section is set by the `.comm' or `.lcomm'
-directive that defines it. The size of an external object may be set
-with the `.extern' directive. For example, `.extern sym,4' declares
-that the object at `sym' is 4 bytes in length, whie leaving `sym'
-otherwise undefined.
-
- Using small ECOFF objects requires linker support, and assumes that
-the `$gp' register is correctly initialized (normally done
-automatically by the startup code). MIPS ECOFF assembly code must not
-modify the `$gp' register.
-
-\1f
-File: as.info, Node: MIPS Stabs, Next: MIPS ISA, Prev: MIPS Object, Up: MIPS-Dependent
-
-8.22.3 Directives for debugging information
--------------------------------------------
-
-MIPS ECOFF `as' supports several directives used for generating
-debugging information which are not support by traditional MIPS
-assemblers. These are `.def', `.endef', `.dim', `.file', `.scl',
-`.size', `.tag', `.type', `.val', `.stabd', `.stabn', and `.stabs'.
-The debugging information generated by the three `.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!
-
-\1f
-File: as.info, Node: MIPS symbol sizes, Next: MIPS autoextend, Prev: MIPS ISA, Up: MIPS-Dependent
-
-8.22.4 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 `dla $4,sym' is usually:
-
- 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
-
- whereas the 32-bit expansion is simply:
-
- lui $4,%hi(sym)
- daddiu $4,$4,%lo(sym)
-
- 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.
-
- You can use the `.set sym32' directive to tell the assembler that,
-from this point on, all expressions of the form `SYMBOL' or `SYMBOL +
-OFFSET' have 32-bit values. For example:
-
- .set sym32
- dla $4,sym
- lw $4,sym+16
- sw $4,sym+0x8000($4)
-
- will cause the assembler to treat `sym', `sym+16' and `sym+0x8000'
-as 32-bit values. The handling of non-symbolic addresses is not
-affected.
-
- The directive `.set nosym32' ends a `.set sym32' block and reverts
-to the normal behavior. It is also possible to change the symbol size
-using the command-line options `-msym32' and `-mno-sym32'.
-
- These options and directives are always accepted, but at present,
-they have no effect for anything other than n64.
-
-\1f
-File: as.info, Node: MIPS ISA, Next: MIPS symbol sizes, Prev: MIPS Stabs, Up: MIPS-Dependent
-
-8.22.5 Directives to override the ISA level
--------------------------------------------
-
-GNU `as' supports an additional directive to change the MIPS
-Instruction Set Architecture level on the fly: `.set mipsN'. 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. `.set mipsN' affects not
-only which instructions are permitted, but also how certain macros are
-expanded. `.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!
-
- The `.set arch=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
-`-march' command line option are also selectable by this directive.
-The original value is restored by `.set arch=default'.
-
- The directive `.set mips16' puts the assembler into MIPS 16 mode, in
-which it will assemble instructions for the MIPS 16 processor. Use
-`.set nomips16' to return to normal 32 bit mode.
-
- Traditional MIPS assemblers do not support this directive.
-
-\1f
-File: as.info, Node: MIPS autoextend, Next: MIPS insn, Prev: MIPS symbol sizes, Up: MIPS-Dependent
-
-8.22.6 Directives for extending MIPS 16 bit instructions
---------------------------------------------------------
-
-By default, MIPS 16 instructions are automatically extended to 32 bits
-when necessary. The directive `.set noautoextend' will turn this off.
-When `.set noautoextend' is in effect, any 32 bit instruction must be
-explicitly extended with the `.e' modifier (e.g., `li.e $4,1000'). The
-directive `.set autoextend' may be used to once again automatically
-extend instructions when necessary.
-
- This directive is only meaningful when in MIPS 16 mode. Traditional
-MIPS assemblers do not support this directive.
-
-\1f
-File: as.info, Node: MIPS insn, Next: MIPS option stack, Prev: MIPS autoextend, Up: MIPS-Dependent
-
-8.22.7 Directive to mark data as an instruction
------------------------------------------------
-
-The `.insn' directive tells `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, `as' automatically
-adds 1 to the value, so that jumping to the loaded address will do the
-right thing.
-
-\1f
-File: as.info, Node: MIPS option stack, Next: MIPS ASE instruction generation overrides, Prev: MIPS insn, Up: MIPS-Dependent
-
-8.22.8 Directives to save and restore options
----------------------------------------------
-
-The directives `.set push' and `.set pop' may be used to save and
-restore the current settings for all the options which are controlled
-by `.set'. The `.set push' directive saves the current settings on a
-stack. The `.set pop' directive pops the stack and restores the
-settings.
-
- 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.
-
- Traditional MIPS assemblers do not support these directives.
-
-\1f
-File: as.info, Node: MIPS ASE instruction generation overrides, Prev: MIPS option stack, Up: MIPS-Dependent
-
-8.22.9 Directives to control generation of MIPS ASE instructions
-----------------------------------------------------------------
-
-The directive `.set mips3d' makes the assembler accept instructions
-from the MIPS-3D Application Specific Extension from that point on in
-the assembly. The `.set nomips3d' directive prevents MIPS-3D
-instructions from being accepted.
-
- The directive `.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 `.set nosmartmips'
-directive prevents SmartMIPS instructions from being accepted.
-
- The directive `.set mdmx' makes the assembler accept instructions
-from the MDMX Application Specific Extension from that point on in the
-assembly. The `.set nomdmx' directive prevents MDMX instructions from
-being accepted.
-
- The directive `.set dsp' makes the assembler accept instructions
-from the DSP Release 1 Application Specific Extension from that point
-on in the assembly. The `.set nodsp' directive prevents DSP Release 1
-instructions from being accepted.
-
- The directive `.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 `.set dsp'. The `.set
-nodspr2' directive prevents DSP Release 2 instructions from being
-accepted.
-
- The directive `.set mt' makes the assembler accept instructions from
-the MT Application Specific Extension from that point on in the
-assembly. The `.set nomt' directive prevents MT instructions from
-being accepted.
-
- Traditional MIPS assemblers do not support these directives.
-
-\1f
-File: as.info, Node: MMIX-Dependent, Next: MSP430-Dependent, Prev: MIPS-Dependent, Up: Machine Dependencies
-
-8.23 MMIX Dependent Features
-============================
-
-* Menu:
-
-* MMIX-Opts:: Command-line Options
-* MMIX-Expand:: Instruction expansion
-* MMIX-Syntax:: Syntax
-* MMIX-mmixal:: Differences to `mmixal' syntax and semantics
-
-\1f
-File: as.info, Node: MMIX-Opts, Next: MMIX-Expand, Up: MMIX-Dependent
-
-8.23.1 Command-line Options
----------------------------
-
-The MMIX version of `as' has some machine-dependent options.
-
- When `--fixed-special-register-names' is specified, only the register
-names specified in *Note MMIX-Regs:: are recognized in the instructions
-`PUT' and `GET'.
-
- You can use the `--globalize-symbols' to make all symbols global.
-This option is useful when splitting up a `mmixal' program into several
-files.
-
- The `--gnu-syntax' turns off most syntax compatibility with
-`mmixal'. Its usability is currently doubtful.
-
- The `--relax' option is not fully supported, but will eventually make
-the object file prepared for linker relaxation.
-
- If you want to avoid inadvertently calling a predefined symbol and
-would rather get an error, for example when using `as' with a compiler
-or other machine-generated code, specify `--no-predefined-syms'. This
-turns off built-in predefined definitions of all such symbols,
-including rounding-mode symbols, segment symbols, `BIT' symbols, and
-`TRAP' symbols used in `mmix' "system calls". It also turns off
-predefined special-register names, except when used in `PUT' and `GET'
-instructions.
-
- By default, some instructions are expanded to fit the size of the
-operand or an external symbol (*note MMIX-Expand::). By passing
-`--no-expand', no such expansion will be done, instead causing errors
-at link time if the operand does not fit.
-
- The `mmixal' documentation (*note mmixsite::) specifies that global
-registers allocated with the `GREG' directive (*note MMIX-greg::) and
-initialized to the same non-zero value, will refer to the same global
-register. This isn't strictly enforceable in `as' since the final
-addresses aren't known until link-time, but it will do an effort unless
-the `--no-merge-gregs' option is specified. (Register merging isn't
-yet implemented in `ld'.)
-
- `as' will warn every time it expands an instruction to fit an
-operand unless the option `-x' is specified. It is believed that this
-behaviour is more useful than just mimicking `mmixal''s behaviour, in
-which instructions are only expanded if the `-x' option is specified,
-and assembly fails otherwise, when an instruction needs to be expanded.
-It needs to be kept in mind that `mmixal' is both an assembler and
-linker, while `as' will expand instructions that at link stage can be
-contracted. (Though linker relaxation isn't yet implemented in `ld'.)
-The option `-x' also imples `--linker-allocated-gregs'.
-
- If instruction expansion is enabled, `as' can expand a `PUSHJ'
-instruction into a series of instructions. The shortest expansion is
-to not expand it, but just mark the call as redirectable to a stub,
-which `ld' creates at link-time, but only if the original `PUSHJ'
-instruction is found not to reach the target. The stub consists of the
-necessary instructions to form a jump to the target. This happens if
-`as' can assert that the `PUSHJ' instruction can reach such a stub.
-The option `--no-pushj-stubs' disables this shorter expansion, and the
-longer series of instructions is then created at assembly-time. The
-option `--no-stubs' is a synonym, intended for compatibility with
-future releases, where generation of stubs for other instructions may
-be implemented.
-
- Usually a two-operand-expression (*note GREG-base::) without a
-matching `GREG' directive is treated as an error by `as'. When the
-option `--linker-allocated-gregs' is in effect, they are instead passed
-through to the linker, which will allocate as many global registers as
-is needed.
-
-\1f
-File: as.info, Node: MMIX-Expand, Next: MMIX-Syntax, Prev: MMIX-Opts, Up: MMIX-Dependent
-
-8.23.2 Instruction expansion
-----------------------------
-
-When `as' encounters an instruction with an operand that is either not
-known or does not fit the operand size of the instruction, `as' (and
-`ld') will expand the instruction into a sequence of instructions
-semantically equivalent to the operand fitting the instruction.
-Expansion will take place for the following instructions:
-
-`GETA'
- Expands to a sequence of four instructions: `SETL', `INCML',
- `INCMH' and `INCH'. The operand must be a multiple of four.
-
-Conditional branches
- A branch instruction is turned into a branch with the complemented
- condition and prediction bit over five instructions; four
- instructions setting `$255' to the operand value, which like with
- `GETA' must be a multiple of four, and a final `GO $255,$255,0'.
-
-`PUSHJ'
- Similar to expansion for conditional branches; four instructions
- set `$255' to the operand value, followed by a `PUSHGO
- $255,$255,0'.
-
-`JMP'
- Similar to conditional branches and `PUSHJ'. The final instruction
- is `GO $255,$255,0'.
-
- The linker `ld' is expected to shrink these expansions for code
-assembled with `--relax' (though not currently implemented).
-
-\1f
-File: as.info, Node: MMIX-Syntax, Next: MMIX-mmixal, Prev: MMIX-Expand, Up: MMIX-Dependent
-
-8.23.3 Syntax
--------------
-
-The assembly syntax is supposed to be upward compatible with that
-described in Sections 1.3 and 1.4 of `The Art of Computer Programming,
-Volume 1'. Draft versions of those chapters as well as other MMIX
-information is located at
-`http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html'. Most code
-examples from the mmixal package located there should work unmodified
-when assembled and linked as single files, with a few noteworthy
-exceptions (*note MMIX-mmixal::).
-
- Before an instruction is emitted, the current location is aligned to
-the next four-byte boundary. If a label is defined at the beginning of
-the line, its value will be the aligned value.
-
- In addition to the traditional hex-prefix `0x', a hexadecimal number
-can also be specified by the prefix character `#'.
-
- After all operands to an MMIX instruction or directive have been
-specified, the rest of the line is ignored, treated as a comment.
-
-* Menu:
-
-* MMIX-Chars:: Special Characters
-* MMIX-Symbols:: Symbols
-* MMIX-Regs:: Register Names
-* MMIX-Pseudos:: Assembler Directives
-
-\1f
-File: as.info, Node: MMIX-Chars, Next: MMIX-Symbols, Up: MMIX-Syntax
-
-8.23.3.1 Special Characters
-...........................
-
-The characters `*' and `#' are line comment characters; each start a
-comment at the beginning of a line, but only at the beginning of a
-line. A `#' prefixes a hexadecimal number if found elsewhere on a line.
-
- Two other characters, `%' and `!', each start a comment anywhere on
-the line. Thus you can't use the `modulus' and `not' operators in
-expressions normally associated with these two characters.
-
- A `;' is a line separator, treated as a new-line, so separate
-instructions can be specified on a single line.
-
-\1f
-File: as.info, Node: MMIX-Symbols, Next: MMIX-Regs, Prev: MMIX-Chars, Up: MMIX-Syntax
-
-8.23.3.2 Symbols
-................
-
-The character `:' is permitted in identifiers. There are two
-exceptions to it being treated as any other symbol character: if a
-symbol begins with `:', it means that the symbol is in the global
-namespace and that the current prefix should not be prepended to that
-symbol (*note MMIX-prefix::). The `:' is then not considered part of
-the symbol. For a symbol in the label position (first on a line), a `:'
-at the end of a symbol is silently stripped off. A label is permitted,
-but not required, to be followed by a `:', as with many other assembly
-formats.
-
- The character `@' in an expression, is a synonym for `.', the
-current location.
-
- In addition to the common forward and backward local symbol formats
-(*note Symbol Names::), they can be specified with upper-case `B' and
-`F', as in `8B' and `9F'. A local label defined for the current
-position is written with a `H' appended to the number:
- 3H LDB $0,$1,2
- This and traditional local-label formats cannot be mixed: a label
-must be defined and referred to using the same format.
-
- There's a minor caveat: just as for the ordinary local symbols, the
-local symbols are translated into ordinary symbols using control
-characters are to hide the ordinal number of the symbol.
-Unfortunately, these symbols are not translated back in error messages.
-Thus you may see confusing error messages when local symbols are used.
-Control characters `\003' (control-C) and `\004' (control-D) are used
-for the MMIX-specific local-symbol syntax.
-
- The symbol `Main' is handled specially; it is always global.
-
- By defining the symbols `__.MMIX.start..text' and
-`__.MMIX.start..data', the address of respectively the `.text' and
-`.data' segments of the final program can be defined, though when
-linking more than one object file, the code or data in the object file
-containing the symbol is not guaranteed to be start at that position;
-just the final executable. *Note MMIX-loc::.
-
-\1f
-File: as.info, Node: MMIX-Regs, Next: MMIX-Pseudos, Prev: MMIX-Symbols, Up: MMIX-Syntax
-
-8.23.3.3 Register names
-.......................
-
-Local and global registers are specified as `$0' to `$255'. The
-recognized special register names are `rJ', `rA', `rB', `rC', `rD',
-`rE', `rF', `rG', `rH', `rI', `rK', `rL', `rM', `rN', `rO', `rP', `rQ',
-`rR', `rS', `rT', `rU', `rV', `rW', `rX', `rY', `rZ', `rBB', `rTT',
-`rWW', `rXX', `rYY' and `rZZ'. A leading `:' is optional for special
-register names.
-
- Local and global symbols can be equated to register names and used in
-place of ordinary registers.
-
- Similarly for special registers, local and global symbols can be
-used. Also, symbols equated from numbers and constant expressions are
-allowed in place of a special register, except when either of the
-options `--no-predefined-syms' and `--fixed-special-register-names' are
-specified. Then only the special register names above are allowed for
-the instructions having a special register operand; `GET' and `PUT'.
-
-\1f
-File: as.info, Node: MMIX-Pseudos, Prev: MMIX-Regs, Up: MMIX-Syntax
-
-8.23.3.4 Assembler Directives
-.............................
-
-`LOC'
- The `LOC' directive sets the current location to the value of the
- operand field, which may include changing sections. If the
- operand is a constant, the section is set to either `.data' if the
- value is `0x2000000000000000' or larger, else it is set to `.text'.
- Within a section, the current location may only be changed to
- monotonically higher addresses. A LOC expression must be a
- previously defined symbol or a "pure" constant.
-
- An example, which sets the label PREV to the current location, and
- updates the current location to eight bytes forward:
- prev LOC @+8
-
- When a LOC has a constant as its operand, a symbol
- `__.MMIX.start..text' or `__.MMIX.start..data' is defined
- depending on the address as mentioned above. Each such symbol is
- interpreted as special by the linker, locating the section at that
- address. Note that if multiple files are linked, the first object
- file with that section will be mapped to that address (not
- necessarily the file with the LOC definition).
-
-`LOCAL'
- Example:
- LOCAL external_symbol
- LOCAL 42
- .local asymbol
-
- This directive-operation generates a link-time assertion that the
- operand does not correspond to a global register. The operand is
- an expression that at link-time resolves to a register symbol or a
- number. A number is treated as the register having that number.
- There is one restriction on the use of this directive: the
- pseudo-directive must be placed in a section with contents, code
- or data.
-
-`IS'
- The `IS' directive:
- asymbol IS an_expression
- sets the symbol `asymbol' to `an_expression'. A symbol may not be
- set more than once using this directive. Local labels may be set
- using this directive, for example:
- 5H IS @+4
-
-`GREG'
- This directive reserves a global register, gives it an initial
- value and optionally gives it a symbolic name. Some examples:
-
- areg GREG
- breg GREG data_value
- GREG data_buffer
- .greg creg, another_data_value
-
- The symbolic register name can be used in place of a (non-special)
- register. If a value isn't provided, it defaults to zero. Unless
- the option `--no-merge-gregs' is specified, non-zero registers
- allocated with this directive may be eliminated by `as'; another
- register with the same value used in its place. Any of the
- instructions `CSWAP', `GO', `LDA', `LDBU', `LDB', `LDHT', `LDOU',
- `LDO', `LDSF', `LDTU', `LDT', `LDUNC', `LDVTS', `LDWU', `LDW',
- `PREGO', `PRELD', `PREST', `PUSHGO', `STBU', `STB', `STCO', `STHT',
- `STOU', `STSF', `STTU', `STT', `STUNC', `SYNCD', `SYNCID', can
- have a value nearby an initial value in place of its second and
- third operands. Here, "nearby" is defined as within the range
- 0...255 from the initial value of such an allocated register.
-
- buffer1 BYTE 0,0,0,0,0
- buffer2 BYTE 0,0,0,0,0
- ...
- GREG buffer1
- LDOU $42,buffer2
- In the example above, the `Y' field of the `LDOUI' instruction
- (LDOU with a constant Z) will be replaced with the global register
- allocated for `buffer1', and the `Z' field will have the value 5,
- the offset from `buffer1' to `buffer2'. The result is equivalent
- to this code:
- buffer1 BYTE 0,0,0,0,0
- buffer2 BYTE 0,0,0,0,0
- ...
- tmpreg GREG buffer1
- LDOU $42,tmpreg,(buffer2-buffer1)
-
- Global registers allocated with this directive are allocated in
- order higher-to-lower within a file. Other than that, the exact
- order of register allocation and elimination is undefined. For
- example, the order is undefined when more than one file with such
- directives are linked together. With the options `-x' and
- `--linker-allocated-gregs', `GREG' directives for two-operand
- cases like the one mentioned above can be omitted. Sufficient
- global registers will then be allocated by the linker.
-
-`BYTE'
- The `BYTE' directive takes a series of operands separated by a
- comma. If an operand is a string (*note Strings::), each
- character of that string is emitted as a byte. Other operands
- must be constant expressions without forward references, in the
- range 0...255. If you need operands having expressions with
- forward references, use `.byte' (*note Byte::). An operand can be
- omitted, defaulting to a zero value.
-
-`WYDE'
-`TETRA'
-`OCTA'
- The directives `WYDE', `TETRA' and `OCTA' emit constants of two,
- four and eight bytes size respectively. Before anything else
- happens for the directive, the current location is aligned to the
- respective constant-size boundary. If a label is defined at the
- beginning of the line, its value will be that after the alignment.
- A single operand can be omitted, defaulting to a zero value
- emitted for the directive. Operands can be expressed as strings
- (*note Strings::), in which case each character in the string is
- emitted as a separate constant of the size indicated by the
- directive.
-
-`PREFIX'
- The `PREFIX' directive sets a symbol name prefix to be prepended to
- all symbols (except local symbols, *note MMIX-Symbols::), that are
- not prefixed with `:', until the next `PREFIX' directive. Such
- prefixes accumulate. For example,
- PREFIX a
- PREFIX b
- c IS 0
- defines a symbol `abc' with the value 0.
-
-`BSPEC'
-`ESPEC'
- A pair of `BSPEC' and `ESPEC' directives delimit a section of
- special contents (without specified semantics). Example:
- BSPEC 42
- TETRA 1,2,3
- ESPEC
- The single operand to `BSPEC' must be number in the range 0...255.
- The `BSPEC' number 80 is used by the GNU binutils implementation.
-
-\1f
-File: as.info, Node: MMIX-mmixal, Prev: MMIX-Syntax, Up: MMIX-Dependent
-
-8.23.4 Differences to `mmixal'
-------------------------------
-
-The binutils `as' and `ld' combination has a few differences in
-function compared to `mmixal' (*note mmixsite::).
-
- The replacement of a symbol with a GREG-allocated register (*note
-GREG-base::) is not handled the exactly same way in `as' as in
-`mmixal'. This is apparent in the `mmixal' example file `inout.mms',
-where different registers with different offsets, eventually yielding
-the same address, are used in the first instruction. This type of
-difference should however not affect the function of any program unless
-it has specific assumptions about the allocated register number.
-
- Line numbers (in the `mmo' object format) are currently not
-supported.
-
- Expression operator precedence is not that of mmixal: operator
-precedence is that of the C programming language. It's recommended to
-use parentheses to explicitly specify wanted operator precedence
-whenever more than one type of operators are used.
-
- The serialize unary operator `&', the fractional division operator
-`//', the logical not operator `!' and the modulus operator `%' are not
-available.
-
- Symbols are not global by default, unless the option
-`--globalize-symbols' is passed. Use the `.global' directive to
-globalize symbols (*note Global::).
-
- Operand syntax is a bit stricter with `as' than `mmixal'. For
-example, you can't say `addu 1,2,3', instead you must write `addu
-$1,$2,3'.
-
- You can't LOC to a lower address than those already visited (i.e.,
-"backwards").
-
- A LOC directive must come before any emitted code.
-
- Predefined symbols are visible as file-local symbols after use. (In
-the ELF file, that is--the linked mmo file has no notion of a file-local
-symbol.)
-
- Some mapping of constant expressions to sections in LOC expressions
-is attempted, but that functionality is easily confused and should be
-avoided unless compatibility with `mmixal' is required. A LOC
-expression to `0x2000000000000000' or higher, maps to the `.data'
-section and lower addresses map to the `.text' section (*note
-MMIX-loc::).
-
- The code and data areas are each contiguous. Sparse programs with
-far-away LOC directives will take up the same amount of space as a
-contiguous program with zeros filled in the gaps between the LOC
-directives. If you need sparse programs, you might try and get the
-wanted effect with a linker script and splitting up the code parts into
-sections (*note Section::). Assembly code for this, to be compatible
-with `mmixal', would look something like:
- .if 0
- LOC away_expression
- .else
- .section away,"ax"
- .fi
- `as' will not execute the LOC directive and `mmixal' ignores the
-lines with `.'. This construct can be used generally to help
-compatibility.
-
- Symbols can't be defined twice-not even to the same value.
-
- Instruction mnemonics are recognized case-insensitive, though the
-`IS' and `GREG' pseudo-operations must be specified in upper-case
-characters.
-
- There's no unicode support.
-
- The following is a list of programs in `mmix.tar.gz', available at
-`http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html', last
-checked with the version dated 2001-08-25 (md5sum
-c393470cfc86fac040487d22d2bf0172) that assemble with `mmixal' but do
-not assemble with `as':
-
-`silly.mms'
- LOC to a previous address.
-
-`sim.mms'
- Redefines symbol `Done'.
-
-`test.mms'
- Uses the serial operator `&'.
-
-\1f
-File: as.info, Node: MSP430-Dependent, Next: SH-Dependent, Prev: MMIX-Dependent, Up: Machine Dependencies
-
-8.24 MSP 430 Dependent Features
-===============================
-
-* Menu:
-
-* MSP430 Options:: Options
-* MSP430 Syntax:: Syntax
-* MSP430 Floating Point:: Floating Point
-* MSP430 Directives:: MSP 430 Machine Directives
-* MSP430 Opcodes:: Opcodes
-* MSP430 Profiling Capability:: Profiling Capability
-
-\1f
-File: as.info, Node: MSP430 Options, Next: MSP430 Syntax, Up: MSP430-Dependent
-
-8.24.1 Options
---------------
-
-`-m'
- select the mpu arch. Currently has no effect.
-
-`-mP'
- enables polymorph instructions handler.
-
-`-mQ'
- enables relaxation at assembly time. DANGEROUS!
-
-
-\1f
-File: as.info, Node: MSP430 Syntax, Next: MSP430 Floating Point, Prev: MSP430 Options, Up: MSP430-Dependent
-
-8.24.2 Syntax
--------------
-
-* Menu:
-
-* MSP430-Macros:: Macros
-* MSP430-Chars:: Special Characters
-* MSP430-Regs:: Register Names
-* MSP430-Ext:: Assembler Extensions
-
-\1f
-File: as.info, Node: MSP430-Macros, Next: MSP430-Chars, Up: MSP430 Syntax
-
-8.24.2.1 Macros
-...............
-
-The macro syntax used on the MSP 430 is like that described in the MSP
-430 Family Assembler Specification. Normal `as' macros should still
-work.
-
- Additional built-in macros are:
-
-`llo(exp)'
- Extracts least significant word from 32-bit expression 'exp'.
-
-`lhi(exp)'
- Extracts most significant word from 32-bit expression 'exp'.
-
-`hlo(exp)'
- Extracts 3rd word from 64-bit expression 'exp'.
-
-`hhi(exp)'
- Extracts 4rd word from 64-bit expression 'exp'.
-
-
- They normally being used as an immediate source operand.
- mov #llo(1), r10 ; == mov #1, r10
- mov #lhi(1), r10 ; == mov #0, r10
-
-\1f
-File: as.info, Node: MSP430-Chars, Next: MSP430-Regs, Prev: MSP430-Macros, Up: MSP430 Syntax
-
-8.24.2.2 Special Characters
-...........................
-
-`;' is the line comment character.
-
- The character `$' in jump instructions indicates current location and
-implemented only for TI syntax compatibility.
-
-\1f
-File: as.info, Node: MSP430-Regs, Next: MSP430-Ext, Prev: MSP430-Chars, Up: MSP430 Syntax
-
-8.24.2.3 Register Names
-.......................
-
-General-purpose registers are represented by predefined symbols of the
-form `rN' (for global registers), where N represents a number between
-`0' and `15'. The leading letters may be in either upper or lower
-case; for example, `r13' and `R7' are both valid register names.
-
- Register names `PC', `SP' and `SR' cannot be used as register names
-and will be treated as variables. Use `r0', `r1', and `r2' instead.
-
-\1f
-File: as.info, Node: MSP430-Ext, Prev: MSP430-Regs, Up: MSP430 Syntax
-
-8.24.2.4 Assembler Extensions
-.............................
-
-`@rN'
- As destination operand being treated as `0(rn)'
-
-`0(rN)'
- As source operand being treated as `@rn'
-
-`jCOND +N'
- Skips next N bytes followed by jump instruction and equivalent to
- `jCOND $+N+2'
-
-
- Also, there are some instructions, which cannot be found in other
-assemblers. These are branch instructions, which has different opcodes
-upon jump distance. They all got PC relative addressing mode.
-
-`beq label'
- A polymorph instruction which is `jeq label' in case if jump
- distance within allowed range for cpu's jump instruction. If not,
- this unrolls into a sequence of
- jne $+6
- br label
-
-`bne label'
- A polymorph instruction which is `jne label' or `jeq +4; br label'
-
-`blt label'
- A polymorph instruction which is `jl label' or `jge +4; br label'
-
-`bltn label'
- A polymorph instruction which is `jn label' or `jn +2; jmp +4; br
- label'
-
-`bltu label'
- A polymorph instruction which is `jlo label' or `jhs +2; br label'
-
-`bge label'
- A polymorph instruction which is `jge label' or `jl +4; br label'
-
-`bgeu label'
- A polymorph instruction which is `jhs label' or `jlo +4; br label'
-
-`bgt label'
- A polymorph instruction which is `jeq +2; jge label' or `jeq +6;
- jl +4; br label'
-
-`bgtu label'
- A polymorph instruction which is `jeq +2; jhs label' or `jeq +6;
- jlo +4; br label'
-
-`bleu label'
- A polymorph instruction which is `jeq label; jlo label' or `jeq
- +2; jhs +4; br label'
-
-`ble label'
- A polymorph instruction which is `jeq label; jl label' or `jeq
- +2; jge +4; br label'
-
-`jump label'
- A polymorph instruction which is `jmp label' or `br label'
-
-\1f
-File: as.info, Node: MSP430 Floating Point, Next: MSP430 Directives, Prev: MSP430 Syntax, Up: MSP430-Dependent
-
-8.24.3 Floating Point
----------------------
-
-The MSP 430 family uses IEEE 32-bit floating-point numbers.
-
-\1f
-File: as.info, Node: MSP430 Directives, Next: MSP430 Opcodes, Prev: MSP430 Floating Point, Up: MSP430-Dependent
-
-8.24.4 MSP 430 Machine Directives
----------------------------------
-
-`.file'
- This directive is ignored; it is accepted for compatibility with
- other MSP 430 assemblers.
-
- _Warning:_ in other versions of the GNU assembler, `.file' is
- used for the directive called `.app-file' in the MSP 430
- support.
-
-`.line'
- This directive is ignored; it is accepted for compatibility with
- other MSP 430 assemblers.
-
-`.arch'
- Currently this directive is ignored; it is accepted for
- compatibility with other MSP 430 assemblers.
-
-`.profiler'
- This directive instructs assembler to add new profile entry to the
- object file.
-
-
-\1f
-File: as.info, Node: MSP430 Opcodes, Next: MSP430 Profiling Capability, Prev: MSP430 Directives, Up: MSP430-Dependent
-
-8.24.5 Opcodes
---------------
-
-`as' implements all the standard MSP 430 opcodes. No additional
-pseudo-instructions are needed on this family.
-
- For information on the 430 machine instruction set, see `MSP430
-User's Manual, document slau049d', Texas Instrument, Inc.
-
-\1f
-File: as.info, Node: MSP430 Profiling Capability, Prev: MSP430 Opcodes, Up: MSP430-Dependent
-
-8.24.6 Profiling Capability
----------------------------
-
-It is a performance hit to use gcc's profiling approach for this tiny
-target. Even more - jtag hardware facility does not perform any
-profiling functions. However we've got gdb's built-in simulator where
-we can do anything.
-
- We define new section `.profiler' which holds all profiling
-information. We define new pseudo operation `.profiler' which will
-instruct assembler to add new profile entry to the object file. Profile
-should take place at the present address.
-
- Pseudo operation format:
-
- `.profiler flags,function_to_profile [, cycle_corrector, extra]'
-
- where:
-
- `flags' is a combination of the following characters:
-
- `s'
- function entry
-
- `x'
- function exit
-
- `i'
- function is in init section
-
- `f'
- function is in fini section
-
- `l'
- library call
-
- `c'
- libc standard call
-
- `d'
- stack value demand
-
- `I'
- interrupt service routine
-
- `P'
- prologue start
-
- `p'
- prologue end
-
- `E'
- epilogue start
-
- `e'
- epilogue end
-
- `j'
- long jump / sjlj unwind
-
- `a'
- an arbitrary code fragment
-
- `t'
- extra parameter saved (a constant value like frame size)
-
-`function_to_profile'
- a function address
-
-`cycle_corrector'
- a value which should be added to the cycle counter, zero if
- omitted.
-
-`extra'
- any extra parameter, zero if omitted.
-
-
- For example:
- .global fxx
- .type fxx,@function
- fxx:
- .LFrameOffset_fxx=0x08
- .profiler "scdP", fxx ; function entry.
- ; we also demand stack value to be saved
- push r11
- push r10
- push r9
- push r8
- .profiler "cdpt",fxx,0, .LFrameOffset_fxx ; check stack value at this point
- ; (this is a prologue end)
- ; note, that spare var filled with
- ; the farme size
- mov r15,r8
- ...
- .profiler cdE,fxx ; check stack
- pop r8
- pop r9
- pop r10
- pop r11
- .profiler xcde,fxx,3 ; exit adds 3 to the cycle counter
- ret ; cause 'ret' insn takes 3 cycles
-
-\1f
-File: as.info, Node: PDP-11-Dependent, Next: PJ-Dependent, Prev: SH64-Dependent, Up: Machine Dependencies
-
-8.25 PDP-11 Dependent Features
-==============================
-
-* Menu:
-
-* PDP-11-Options:: Options
-* PDP-11-Pseudos:: Assembler Directives
-* PDP-11-Syntax:: DEC Syntax versus BSD Syntax
-* PDP-11-Mnemonics:: Instruction Naming
-* PDP-11-Synthetic:: Synthetic Instructions
-
-\1f
-File: as.info, Node: PDP-11-Options, Next: PDP-11-Pseudos, Up: PDP-11-Dependent
-
-8.25.1 Options
---------------
-
-The PDP-11 version of `as' has a rich set of machine dependent options.
-
-8.25.1.1 Code Generation Options
-................................
-
-`-mpic | -mno-pic'
- Generate position-independent (or position-dependent) code.
-
- The default is to generate position-independent code.
-
-8.25.1.2 Instruction Set Extension Options
-..........................................
-
-These options enables or disables the use of extensions over the base
-line instruction set as introduced by the first PDP-11 CPU: the KA11.
-Most options come in two variants: a `-m'EXTENSION that enables
-EXTENSION, and a `-mno-'EXTENSION that disables EXTENSION.
-
- The default is to enable all extensions.
-
-`-mall | -mall-extensions'
- Enable all instruction set extensions.
-
-`-mno-extensions'
- Disable all instruction set extensions.
-
-`-mcis | -mno-cis'
- Enable (or disable) the use of the commercial instruction set,
- which consists of these instructions: `ADDNI', `ADDN', `ADDPI',
- `ADDP', `ASHNI', `ASHN', `ASHPI', `ASHP', `CMPCI', `CMPC',
- `CMPNI', `CMPN', `CMPPI', `CMPP', `CVTLNI', `CVTLN', `CVTLPI',
- `CVTLP', `CVTNLI', `CVTNL', `CVTNPI', `CVTNP', `CVTPLI', `CVTPL',
- `CVTPNI', `CVTPN', `DIVPI', `DIVP', `L2DR', `L3DR', `LOCCI',
- `LOCC', `MATCI', `MATC', `MOVCI', `MOVC', `MOVRCI', `MOVRC',
- `MOVTCI', `MOVTC', `MULPI', `MULP', `SCANCI', `SCANC', `SKPCI',
- `SKPC', `SPANCI', `SPANC', `SUBNI', `SUBN', `SUBPI', and `SUBP'.
-
-`-mcsm | -mno-csm'
- Enable (or disable) the use of the `CSM' instruction.
-
-`-meis | -mno-eis'
- Enable (or disable) the use of the extended instruction set, which
- consists of these instructions: `ASHC', `ASH', `DIV', `MARK',
- `MUL', `RTT', `SOB' `SXT', and `XOR'.
-
-`-mfis | -mkev11'
-`-mno-fis | -mno-kev11'
- Enable (or disable) the use of the KEV11 floating-point
- instructions: `FADD', `FDIV', `FMUL', and `FSUB'.
-
-`-mfpp | -mfpu | -mfp-11'
-`-mno-fpp | -mno-fpu | -mno-fp-11'
- Enable (or disable) the use of FP-11 floating-point instructions:
- `ABSF', `ADDF', `CFCC', `CLRF', `CMPF', `DIVF', `LDCFF', `LDCIF',
- `LDEXP', `LDF', `LDFPS', `MODF', `MULF', `NEGF', `SETD', `SETF',
- `SETI', `SETL', `STCFF', `STCFI', `STEXP', `STF', `STFPS', `STST',
- `SUBF', and `TSTF'.
-
-`-mlimited-eis | -mno-limited-eis'
- Enable (or disable) the use of the limited extended instruction
- set: `MARK', `RTT', `SOB', `SXT', and `XOR'.
-
- The -mno-limited-eis options also implies -mno-eis.
-
-`-mmfpt | -mno-mfpt'
- Enable (or disable) the use of the `MFPT' instruction.
-
-`-mmultiproc | -mno-multiproc'
- Enable (or disable) the use of multiprocessor instructions:
- `TSTSET' and `WRTLCK'.
-
-`-mmxps | -mno-mxps'
- Enable (or disable) the use of the `MFPS' and `MTPS' instructions.
-
-`-mspl | -mno-spl'
- Enable (or disable) the use of the `SPL' instruction.
-
- Enable (or disable) the use of the microcode instructions: `LDUB',
- `MED', and `XFC'.
-
-8.25.1.3 CPU Model Options
-..........................
-
-These options enable the instruction set extensions supported by a
-particular CPU, and disables all other extensions.
-
-`-mka11'
- KA11 CPU. Base line instruction set only.
-
-`-mkb11'
- KB11 CPU. Enable extended instruction set and `SPL'.
-
-`-mkd11a'
- KD11-A CPU. Enable limited extended instruction set.
-
-`-mkd11b'
- KD11-B CPU. Base line instruction set only.
-
-`-mkd11d'
- KD11-D CPU. Base line instruction set only.
-
-`-mkd11e'
- KD11-E CPU. Enable extended instruction set, `MFPS', and `MTPS'.
-
-`-mkd11f | -mkd11h | -mkd11q'
- KD11-F, KD11-H, or KD11-Q CPU. Enable limited extended
- instruction set, `MFPS', and `MTPS'.
-
-`-mkd11k'
- KD11-K CPU. Enable extended instruction set, `LDUB', `MED',
- `MFPS', `MFPT', `MTPS', and `XFC'.
-
-`-mkd11z'
- KD11-Z CPU. Enable extended instruction set, `CSM', `MFPS',
- `MFPT', `MTPS', and `SPL'.
-
-`-mf11'
- F11 CPU. Enable extended instruction set, `MFPS', `MFPT', and
- `MTPS'.
-
-`-mj11'
- J11 CPU. Enable extended instruction set, `CSM', `MFPS', `MFPT',
- `MTPS', `SPL', `TSTSET', and `WRTLCK'.
-
-`-mt11'
- T11 CPU. Enable limited extended instruction set, `MFPS', and
- `MTPS'.
-
-8.25.1.4 Machine Model Options
-..............................
-
-These options enable the instruction set extensions supported by a
-particular machine model, and disables all other extensions.
-
-`-m11/03'
- Same as `-mkd11f'.
-
-`-m11/04'
- Same as `-mkd11d'.
-
-`-m11/05 | -m11/10'
- Same as `-mkd11b'.
-
-`-m11/15 | -m11/20'
- Same as `-mka11'.
-
-`-m11/21'
- Same as `-mt11'.
-
-`-m11/23 | -m11/24'
- Same as `-mf11'.
-
-`-m11/34'
- Same as `-mkd11e'.
-
-`-m11/34a'
- Ame as `-mkd11e' `-mfpp'.
-
-`-m11/35 | -m11/40'
- Same as `-mkd11a'.
-
-`-m11/44'
- Same as `-mkd11z'.
-
-`-m11/45 | -m11/50 | -m11/55 | -m11/70'
- Same as `-mkb11'.
-
-`-m11/53 | -m11/73 | -m11/83 | -m11/84 | -m11/93 | -m11/94'
- Same as `-mj11'.
-
-`-m11/60'
- Same as `-mkd11k'.
-
-\1f
-File: as.info, Node: PDP-11-Pseudos, Next: PDP-11-Syntax, Prev: PDP-11-Options, Up: PDP-11-Dependent
-
-8.25.2 Assembler Directives
----------------------------
-
-The PDP-11 version of `as' has a few machine dependent assembler
-directives.
-
-`.bss'
- Switch to the `bss' section.
-
-`.even'
- Align the location counter to an even number.
-
-\1f
-File: as.info, Node: PDP-11-Syntax, Next: PDP-11-Mnemonics, Prev: PDP-11-Pseudos, Up: PDP-11-Dependent
-
-8.25.3 PDP-11 Assembly Language Syntax
---------------------------------------
-
-`as' supports both DEC syntax and BSD syntax. The only difference is
-that in DEC syntax, a `#' character is used to denote an immediate
-constants, while in BSD syntax the character for this purpose is `$'.
-
- general-purpose registers are named `r0' through `r7'. Mnemonic
-alternatives for `r6' and `r7' are `sp' and `pc', respectively.
-
- Floating-point registers are named `ac0' through `ac3', or
-alternatively `fr0' through `fr3'.
-
- Comments are started with a `#' or a `/' character, and extend to
-the end of the line. (FIXME: clash with immediates?)
-
-\1f
-File: as.info, Node: PDP-11-Mnemonics, Next: PDP-11-Synthetic, Prev: PDP-11-Syntax, Up: PDP-11-Dependent
-
-8.25.4 Instruction Naming
--------------------------
-
-Some instructions have alternative names.
-
-`BCC'
- `BHIS'
-
-`BCS'
- `BLO'
-
-`L2DR'
- `L2D'
-
-`L3DR'
- `L3D'
-
-`SYS'
- `TRAP'
-
-\1f
-File: as.info, Node: PDP-11-Synthetic, Prev: PDP-11-Mnemonics, Up: PDP-11-Dependent
-
-8.25.5 Synthetic Instructions
------------------------------
-
-The `JBR' and `J'CC synthetic instructions are not supported yet.
-
-\1f
-File: as.info, Node: PJ-Dependent, Next: PPC-Dependent, Prev: PDP-11-Dependent, Up: Machine Dependencies
-
-8.26 picoJava Dependent Features
-================================
-
-* Menu:
-
-* PJ Options:: Options
-
-\1f
-File: as.info, Node: PJ Options, Up: PJ-Dependent
-
-8.26.1 Options
---------------
-
-`as' has two additional command-line options for the picoJava
-architecture.
-`-ml'
- This option selects little endian data output.
-
-`-mb'
- This option selects big endian data output.
-
-\1f
-File: as.info, Node: PPC-Dependent, Next: Sparc-Dependent, Prev: PJ-Dependent, Up: Machine Dependencies
-
-8.27 PowerPC Dependent Features
-===============================
-
-* Menu:
-
-* PowerPC-Opts:: Options
-* PowerPC-Pseudo:: PowerPC Assembler Directives
-
-\1f
-File: as.info, Node: PowerPC-Opts, Next: PowerPC-Pseudo, Up: PPC-Dependent
-
-8.27.1 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.
-
- The following table lists all available PowerPC options.
-
-`-mpwrx | -mpwr2'
- Generate code for POWER/2 (RIOS2).
-
-`-mpwr'
- Generate code for POWER (RIOS1)
-
-`-m601'
- Generate code for PowerPC 601.
-
-`-mppc, -mppc32, -m603, -m604'
- Generate code for PowerPC 603/604.
-
-`-m403, -m405'
- Generate code for PowerPC 403/405.
-
-`-m440'
- Generate code for PowerPC 440. BookE and some 405 instructions.
-
-`-m7400, -m7410, -m7450, -m7455'
- Generate code for PowerPC 7400/7410/7450/7455.
-
-`-mppc64, -m620'
- Generate code for PowerPC 620/625/630.
-
-`-me500, -me500x2'
- Generate code for Motorola e500 core complex.
-
-`-mspe'
- Generate code for Motorola SPE instructions.
-
-`-mppc64bridge'
- Generate code for PowerPC 64, including bridge insns.
-
-`-mbooke64'
- Generate code for 64-bit BookE.
-
-`-mbooke, mbooke32'
- Generate code for 32-bit BookE.
-
-`-me300'
- Generate code for PowerPC e300 family.
-
-`-maltivec'
- Generate code for processors with AltiVec instructions.
-
-`-mpower4'
- Generate code for Power4 architecture.
-
-`-mpower5'
- Generate code for Power5 architecture.
-
-`-mpower6'
- Generate code for Power6 architecture.
-
-`-mcell'
- Generate code for Cell Broadband Engine architecture.
-
-`-mcom'
- Generate code Power/PowerPC common instructions.
-
-`-many'
- Generate code for any architecture (PWR/PWRX/PPC).
-
-`-mregnames'
- Allow symbolic names for registers.
-
-`-mno-regnames'
- Do not allow symbolic names for registers.
-
-`-mrelocatable'
- Support for GCC's -mrelocatable option.
-
-`-mrelocatable-lib'
- Support for GCC's -mrelocatable-lib option.
-
-`-memb'
- Set PPC_EMB bit in ELF flags.
-
-`-mlittle, -mlittle-endian'
- Generate code for a little endian machine.
-
-`-mbig, -mbig-endian'
- Generate code for a big endian machine.
-
-`-msolaris'
- Generate code for Solaris.
-
-`-mno-solaris'
- Do not generate code for Solaris.
-
-\1f
-File: as.info, Node: PowerPC-Pseudo, Prev: PowerPC-Opts, Up: PPC-Dependent
-
-8.27.2 PowerPC Assembler Directives
------------------------------------
-
-A number of assembler directives are available for PowerPC. The
-following table is far from complete.
-
-`.machine "string"'
- This directive allows you to change the machine for which code is
- generated. `"string"' may be any of the -m cpu selection options
- (without the -m) enclosed in double quotes, `"push"', or `"pop"'.
- `.machine "push"' saves the currently selected cpu, which may be
- restored with `.machine "pop"'.
-
-\1f
-File: as.info, Node: SH-Dependent, Next: SH64-Dependent, Prev: MSP430-Dependent, Up: Machine Dependencies
-
-8.28 Renesas / SuperH SH Dependent Features
-===========================================
-
-* Menu:
-
-* SH Options:: Options
-* SH Syntax:: Syntax
-* SH Floating Point:: Floating Point
-* SH Directives:: SH Machine Directives
-* SH Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: SH Options, Next: SH Syntax, Up: SH-Dependent
-
-8.28.1 Options
---------------
-
-`as' has following command-line options for the Renesas (formerly
-Hitachi) / SuperH SH family.
-
-`--little'
- Generate little endian code.
-
-`--big'
- Generate big endian code.
-
-`--relax'
- Alter jump instructions for long displacements.
-
-`--small'
- Align sections to 4 byte boundaries, not 16.
-
-`--dsp'
- Enable sh-dsp insns, and disable sh3e / sh4 insns.
-
-`--renesas'
- Disable optimization with section symbol for compatibility with
- Renesas assembler.
-
-`--allow-reg-prefix'
- Allow '$' as a register name prefix.
-
-`--isa=sh4 | sh4a'
- Specify the sh4 or sh4a instruction set.
-
-`--isa=dsp'
- Enable sh-dsp insns, and disable sh3e / sh4 insns.
-
-`--isa=fp'
- Enable sh2e, sh3e, sh4, and sh4a insn sets.
-
-`--isa=all'
- Enable sh1, sh2, sh2e, sh3, sh3e, sh4, sh4a, and sh-dsp insn sets.
-
-
-\1f
-File: as.info, Node: SH Syntax, Next: SH Floating Point, Prev: SH Options, Up: SH-Dependent
-
-8.28.2 Syntax
--------------
-
-* Menu:
-
-* SH-Chars:: Special Characters
-* SH-Regs:: Register Names
-* SH-Addressing:: Addressing Modes
-
-\1f
-File: as.info, Node: SH-Chars, Next: SH-Regs, Up: SH Syntax
-
-8.28.2.1 Special Characters
-...........................
-
-`!' is the line comment character.
-
- You can use `;' instead of a newline to separate statements.
-
- Since `$' has no special meaning, you may use it in symbol names.
-
-\1f
-File: as.info, Node: SH-Regs, Next: SH-Addressing, Prev: SH-Chars, Up: SH Syntax
-
-8.28.2.2 Register Names
-.......................
-
-You can use the predefined symbols `r0', `r1', `r2', `r3', `r4', `r5',
-`r6', `r7', `r8', `r9', `r10', `r11', `r12', `r13', `r14', and `r15' to
-refer to the SH registers.
-
- The SH also has these control registers:
-
-`pr'
- procedure register (holds return address)
-
-`pc'
- program counter
-
-`mach'
-`macl'
- high and low multiply accumulator registers
-
-`sr'
- status register
-
-`gbr'
- global base register
-
-`vbr'
- vector base register (for interrupt vectors)
-
-\1f
-File: as.info, Node: SH-Addressing, Prev: SH-Regs, Up: SH Syntax
-
-8.28.2.3 Addressing Modes
-.........................
-
-`as' understands the following addressing modes for the SH. `RN' in
-the following refers to any of the numbered registers, but _not_ the
-control registers.
-
-`RN'
- Register direct
-
-`@RN'
- Register indirect
-
-`@-RN'
- Register indirect with pre-decrement
-
-`@RN+'
- Register indirect with post-increment
-
-`@(DISP, RN)'
- Register indirect with displacement
-
-`@(R0, RN)'
- Register indexed
-
-`@(DISP, GBR)'
- `GBR' offset
-
-`@(R0, GBR)'
- GBR indexed
-
-`ADDR'
-`@(DISP, PC)'
- PC relative address (for branch or for addressing memory). The
- `as' implementation allows you to use the simpler form ADDR
- anywhere a PC relative address is called for; the alternate form
- is supported for compatibility with other assemblers.
-
-`#IMM'
- Immediate data
-
-\1f
-File: as.info, Node: SH Floating Point, Next: SH Directives, Prev: SH Syntax, Up: SH-Dependent
-
-8.28.3 Floating Point
----------------------
-
-SH2E, SH3E and SH4 groups have on-chip floating-point unit (FPU). Other
-SH groups can use `.float' directive to generate IEEE floating-point
-numbers.
-
- SH2E and SH3E support single-precision floating point calculations as
-well as entirely PCAPI compatible emulation of double-precision
-floating point calculations. SH2E and SH3E instructions are a subset of
-the floating point calculations conforming to the IEEE754 standard.
-
- In addition to single-precision and double-precision floating-point
-operation capability, the on-chip FPU of SH4 has a 128-bit graphic
-engine that enables 32-bit floating-point data to be processed 128 bits
-at a time. It also supports 4 * 4 array operations and inner product
-operations. Also, a superscalar architecture is employed that enables
-simultaneous execution of two instructions (including FPU
-instructions), providing performance of up to twice that of
-conventional architectures at the same frequency.
-
-\1f
-File: as.info, Node: SH Directives, Next: SH Opcodes, Prev: SH Floating Point, Up: SH-Dependent
-
-8.28.4 SH Machine Directives
-----------------------------
-
-`uaword'
-`ualong'
- `as' will issue a warning when a misaligned `.word' or `.long'
- directive is used. You may use `.uaword' or `.ualong' to indicate
- that the value is intentionally misaligned.
-
-\1f
-File: as.info, Node: SH Opcodes, Prev: SH Directives, Up: SH-Dependent
-
-8.28.5 Opcodes
---------------
-
-For detailed information on the SH machine instruction set, see
-`SH-Microcomputer User's Manual' (Renesas) or `SH-4 32-bit CPU Core
-Architecture' (SuperH) and `SuperH (SH) 64-Bit RISC Series' (SuperH).
-
- `as' implements all the standard SH opcodes. No additional
-pseudo-instructions are needed on this family. Note, however, that
-because `as' supports a simpler form of PC-relative addressing, you may
-simply write (for example)
-
- mov.l bar,r0
-
-where other assemblers might require an explicit displacement to `bar'
-from the program counter:
-
- mov.l @(DISP, PC)
-
- Here is a summary of SH opcodes:
-
- Legend:
- Rn a numbered register
- Rm another numbered register
- #imm immediate data
- disp displacement
- disp8 8-bit displacement
- disp12 12-bit displacement
-
- add #imm,Rn lds.l @Rn+,PR
- add Rm,Rn mac.w @Rm+,@Rn+
- addc Rm,Rn mov #imm,Rn
- addv Rm,Rn mov Rm,Rn
- and #imm,R0 mov.b Rm,@(R0,Rn)
- and Rm,Rn mov.b Rm,@-Rn
- and.b #imm,@(R0,GBR) mov.b Rm,@Rn
- bf disp8 mov.b @(disp,Rm),R0
- bra disp12 mov.b @(disp,GBR),R0
- bsr disp12 mov.b @(R0,Rm),Rn
- bt disp8 mov.b @Rm+,Rn
- clrmac mov.b @Rm,Rn
- clrt mov.b R0,@(disp,Rm)
- cmp/eq #imm,R0 mov.b R0,@(disp,GBR)
- cmp/eq Rm,Rn mov.l Rm,@(disp,Rn)
- cmp/ge Rm,Rn mov.l Rm,@(R0,Rn)
- cmp/gt Rm,Rn mov.l Rm,@-Rn
- cmp/hi Rm,Rn mov.l Rm,@Rn
- cmp/hs Rm,Rn mov.l @(disp,Rn),Rm
- cmp/pl Rn mov.l @(disp,GBR),R0
- cmp/pz Rn mov.l @(disp,PC),Rn
- cmp/str Rm,Rn mov.l @(R0,Rm),Rn
- div0s Rm,Rn mov.l @Rm+,Rn
- div0u mov.l @Rm,Rn
- div1 Rm,Rn mov.l R0,@(disp,GBR)
- exts.b Rm,Rn mov.w Rm,@(R0,Rn)
- exts.w Rm,Rn mov.w Rm,@-Rn
- extu.b Rm,Rn mov.w Rm,@Rn
- extu.w Rm,Rn mov.w @(disp,Rm),R0
- jmp @Rn mov.w @(disp,GBR),R0
- jsr @Rn mov.w @(disp,PC),Rn
- ldc Rn,GBR mov.w @(R0,Rm),Rn
- ldc Rn,SR mov.w @Rm+,Rn
- ldc Rn,VBR mov.w @Rm,Rn
- ldc.l @Rn+,GBR mov.w R0,@(disp,Rm)
- ldc.l @Rn+,SR mov.w R0,@(disp,GBR)
- ldc.l @Rn+,VBR mova @(disp,PC),R0
- lds Rn,MACH movt Rn
- lds Rn,MACL muls Rm,Rn
- lds Rn,PR mulu Rm,Rn
- lds.l @Rn+,MACH neg Rm,Rn
- lds.l @Rn+,MACL negc Rm,Rn
-
- nop stc VBR,Rn
- not Rm,Rn stc.l GBR,@-Rn
- or #imm,R0 stc.l SR,@-Rn
- or Rm,Rn stc.l VBR,@-Rn
- or.b #imm,@(R0,GBR) sts MACH,Rn
- rotcl Rn sts MACL,Rn
- rotcr Rn sts PR,Rn
- rotl Rn sts.l MACH,@-Rn
- rotr Rn sts.l MACL,@-Rn
- rte sts.l PR,@-Rn
- rts sub Rm,Rn
- sett subc Rm,Rn
- shal Rn subv Rm,Rn
- shar Rn swap.b Rm,Rn
- shll Rn swap.w Rm,Rn
- shll16 Rn tas.b @Rn
- shll2 Rn trapa #imm
- shll8 Rn tst #imm,R0
- shlr Rn tst Rm,Rn
- shlr16 Rn tst.b #imm,@(R0,GBR)
- shlr2 Rn xor #imm,R0
- shlr8 Rn xor Rm,Rn
- sleep xor.b #imm,@(R0,GBR)
- stc GBR,Rn xtrct Rm,Rn
- stc SR,Rn
-
-\1f
-File: as.info, Node: SH64-Dependent, Next: PDP-11-Dependent, Prev: SH-Dependent, Up: Machine Dependencies
-
-8.29 SuperH SH64 Dependent Features
-===================================
-
-* Menu:
-
-* SH64 Options:: Options
-* SH64 Syntax:: Syntax
-* SH64 Directives:: SH64 Machine Directives
-* SH64 Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: SH64 Options, Next: SH64 Syntax, Up: SH64-Dependent
-
-8.29.1 Options
---------------
-
-`-isa=sh4 | sh4a'
- Specify the sh4 or sh4a instruction set.
-
-`-isa=dsp'
- Enable sh-dsp insns, and disable sh3e / sh4 insns.
-
-`-isa=fp'
- Enable sh2e, sh3e, sh4, and sh4a insn sets.
-
-`-isa=all'
- Enable sh1, sh2, sh2e, sh3, sh3e, sh4, sh4a, and sh-dsp insn sets.
-
-`-isa=shmedia | -isa=shcompact'
- Specify the default instruction set. `SHmedia' specifies the
- 32-bit opcodes, and `SHcompact' specifies the 16-bit opcodes
- compatible with previous SH families. The default depends on the
- ABI selected; the default for the 64-bit ABI is SHmedia, and the
- default for the 32-bit ABI is SHcompact. If neither the ABI nor
- the ISA is specified, the default is 32-bit SHcompact.
-
- Note that the `.mode' pseudo-op is not permitted if the ISA is not
- specified on the command line.
-
-`-abi=32 | -abi=64'
- Specify the default ABI. If the ISA is specified and the ABI is
- not, the default ABI depends on the ISA, with SHmedia defaulting
- to 64-bit and SHcompact defaulting to 32-bit.
-
- Note that the `.abi' pseudo-op is not permitted if the ABI is not
- specified on the command line. When the ABI is specified on the
- command line, any `.abi' pseudo-ops in the source must match it.
-
-`-shcompact-const-crange'
- Emit code-range descriptors for constants in SHcompact code
- sections.
-
-`-no-mix'
- Disallow SHmedia code in the same section as constants and
- SHcompact code.
-
-`-no-expand'
- Do not expand MOVI, PT, PTA or PTB instructions.
-
-`-expand-pt32'
- With -abi=64, expand PT, PTA and PTB instructions to 32 bits only.
-
-
-\1f
-File: as.info, Node: SH64 Syntax, Next: SH64 Directives, Prev: SH64 Options, Up: SH64-Dependent
-
-8.29.2 Syntax
--------------
-
-* Menu:
-
-* SH64-Chars:: Special Characters
-* SH64-Regs:: Register Names
-* SH64-Addressing:: Addressing Modes
-
-\1f
-File: as.info, Node: SH64-Chars, Next: SH64-Regs, Up: SH64 Syntax
-
-8.29.2.1 Special Characters
-...........................
-
-`!' is the line comment character.
-
- You can use `;' instead of a newline to separate statements.
-
- Since `$' has no special meaning, you may use it in symbol names.
-
-\1f
-File: as.info, Node: SH64-Regs, Next: SH64-Addressing, Prev: SH64-Chars, Up: SH64 Syntax
-
-8.29.2.2 Register Names
-.......................
-
-You can use the predefined symbols `r0' through `r63' to refer to the
-SH64 general registers, `cr0' through `cr63' for control registers,
-`tr0' through `tr7' for target address registers, `fr0' through `fr63'
-for single-precision floating point registers, `dr0' through `dr62'
-(even numbered registers only) for double-precision floating point
-registers, `fv0' through `fv60' (multiples of four only) for
-single-precision floating point vectors, `fp0' through `fp62' (even
-numbered registers only) for single-precision floating point pairs,
-`mtrx0' through `mtrx48' (multiples of 16 only) for 4x4 matrices of
-single-precision floating point registers, `pc' for the program
-counter, and `fpscr' for the floating point status and control register.
-
- You can also refer to the control registers by the mnemonics `sr',
-`ssr', `pssr', `intevt', `expevt', `pexpevt', `tra', `spc', `pspc',
-`resvec', `vbr', `tea', `dcr', `kcr0', `kcr1', `ctc', and `usr'.
-
-\1f
-File: as.info, Node: SH64-Addressing, Prev: SH64-Regs, Up: SH64 Syntax
-
-8.29.2.3 Addressing Modes
-.........................
-
-SH64 operands consist of either a register or immediate value. The
-immediate value can be a constant or label reference (or portion of a
-label reference), as in this example:
-
- movi 4,r2
- pt function, tr4
- movi (function >> 16) & 65535,r0
- shori function & 65535, r0
- ld.l r0,4,r0
-
- Instruction label references can reference labels in either SHmedia
-or SHcompact. To differentiate between the two, labels in SHmedia
-sections will always have the least significant bit set (i.e. they will
-be odd), which SHcompact labels will have the least significant bit
-reset (i.e. they will be even). If you need to reference the actual
-address of a label, you can use the `datalabel' modifier, as in this
-example:
-
- .long function
- .long datalabel function
-
- In that example, the first longword may or may not have the least
-significant bit set depending on whether the label is an SHmedia label
-or an SHcompact label. The second longword will be the actual address
-of the label, regardless of what type of label it is.
-
-\1f
-File: as.info, Node: SH64 Directives, Next: SH64 Opcodes, Prev: SH64 Syntax, Up: SH64-Dependent
-
-8.29.3 SH64 Machine Directives
-------------------------------
-
-In addition to the SH directives, the SH64 provides the following
-directives:
-
-`.mode [shmedia|shcompact]'
-`.isa [shmedia|shcompact]'
- Specify the ISA for the following instructions (the two directives
- are equivalent). Note that programs such as `objdump' rely on
- symbolic labels to determine when such mode switches occur (by
- checking the least significant bit of the label's address), so
- such mode/isa changes should always be followed by a label (in
- practice, this is true anyway). Note that you cannot use these
- directives if you didn't specify an ISA on the command line.
-
-`.abi [32|64]'
- Specify the ABI for the following instructions. Note that you
- cannot use this directive unless you specified an ABI on the
- command line, and the ABIs specified must match.
-
-`.uaquad'
- Like .uaword and .ualong, this allows you to specify an
- intentionally unaligned quadword (64 bit word).
-
-
-\1f
-File: as.info, Node: SH64 Opcodes, Prev: SH64 Directives, Up: SH64-Dependent
-
-8.29.4 Opcodes
---------------
-
-For detailed information on the SH64 machine instruction set, see
-`SuperH 64 bit RISC Series Architecture Manual' (SuperH, Inc.).
-
- `as' implements all the standard SH64 opcodes. In addition, the
-following pseudo-opcodes may be expanded into one or more alternate
-opcodes:
-
-`movi'
- If the value doesn't fit into a standard `movi' opcode, `as' will
- replace the `movi' with a sequence of `movi' and `shori' opcodes.
-
-`pt'
- This expands to a sequence of `movi' and `shori' opcode, followed
- by a `ptrel' opcode, or to a `pta' or `ptb' opcode, depending on
- the label referenced.
-
-
-\1f
-File: as.info, Node: Sparc-Dependent, Next: TIC54X-Dependent, Prev: PPC-Dependent, Up: Machine Dependencies
-
-8.30 SPARC Dependent Features
-=============================
-
-* Menu:
-
-* Sparc-Opts:: Options
-* Sparc-Aligned-Data:: Option to enforce aligned data
-* Sparc-Float:: Floating Point
-* Sparc-Directives:: Sparc Machine Directives
-
-\1f
-File: as.info, Node: Sparc-Opts, Next: Sparc-Aligned-Data, Up: Sparc-Dependent
-
-8.30.1 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.
-
- By default, `as' assumes the core instruction set (SPARC v6), but
-"bumps" the architecture level as needed: it switches to successively
-higher architectures as it encounters instructions that only exist in
-the higher levels.
-
- If not configured for SPARC v9 (`sparc64-*-*') GAS will not bump
-passed sparclite by default, an option must be passed to enable the v9
-instructions.
-
- GAS treats sparclite as being compatible with v8, unless an
-architecture is explicitly requested. SPARC v9 is always incompatible
-with sparclite.
-
-`-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite'
-`-Av8plus | -Av8plusa | -Av9 | -Av9a'
- Use one of the `-A' options to select one of the SPARC
- architectures explicitly. If you select an architecture
- explicitly, `as' reports a fatal error if it encounters an
- instruction or feature requiring an incompatible or higher level.
-
- `-Av8plus' and `-Av8plusa' select a 32 bit environment.
-
- `-Av9' and `-Av9a' select a 64 bit environment and are not
- available unless GAS is explicitly configured with 64 bit
- environment support.
-
- `-Av8plusa' and `-Av9a' enable the SPARC V9 instruction set with
- UltraSPARC extensions.
-
-`-xarch=v8plus | -xarch=v8plusa'
- For compatibility with the Solaris v9 assembler. These options are
- equivalent to -Av8plus and -Av8plusa, respectively.
-
-`-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).
-
-`-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.
-
-\1f
-File: as.info, Node: Sparc-Aligned-Data, Next: Sparc-Float, Prev: Sparc-Opts, Up: Sparc-Dependent
-
-8.30.2 Enforcing aligned data
------------------------------
-
-SPARC GAS normally permits data to be misaligned. For example, it
-permits the `.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.
-
- You can use the `--enforce-aligned-data' option to make SPARC GAS
-also issue an error about misaligned data, just as the SunOS and Solaris
-assemblers do.
-
- The `--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 `packed' attribute). You
-may have to assemble with GAS in order to initialize packed data
-structures in your own code.
-
-\1f
-File: as.info, Node: Sparc-Float, Next: Sparc-Directives, Prev: Sparc-Aligned-Data, Up: Sparc-Dependent
-
-8.30.3 Floating Point
----------------------
-
-The Sparc uses IEEE floating-point numbers.
-
-\1f
-File: as.info, Node: Sparc-Directives, Prev: Sparc-Float, Up: Sparc-Dependent
-
-8.30.4 Sparc Machine Directives
--------------------------------
-
-The Sparc version of `as' supports the following additional machine
-directives:
-
-`.align'
- This must be followed by the desired alignment in bytes.
-
-`.common'
- This must be followed by a symbol name, a positive number, and
- `"bss"'. This behaves somewhat like `.comm', but the syntax is
- different.
-
-`.half'
- This is functionally identical to `.short'.
-
-`.nword'
- On the Sparc, the `.nword' directive produces native word sized
- value, ie. if assembling with -32 it is equivalent to `.word', if
- assembling with -64 it is equivalent to `.xword'.
-
-`.proc'
- This directive is ignored. Any text following it on the same line
- is also ignored.
-
-`.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 `#scratch', it is a scratch register, if it is `#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.
-
-`.reserve'
- This must be followed by a symbol name, a positive number, and
- `"bss"'. This behaves somewhat like `.lcomm', but the syntax is
- different.
-
-`.seg'
- This must be followed by `"text"', `"data"', or `"data1"'. It
- behaves like `.text', `.data', or `.data 1'.
-
-`.skip'
- This is functionally identical to the `.space' directive.
-
-`.word'
- On the Sparc, the `.word' directive produces 32 bit values,
- instead of the 16 bit values it produces on many other machines.
-
-`.xword'
- On the Sparc V9 processor, the `.xword' directive produces 64 bit
- values.
-
-\1f
-File: as.info, Node: TIC54X-Dependent, Next: V850-Dependent, Prev: Sparc-Dependent, Up: Machine Dependencies
-
-8.31 TIC54X Dependent Features
-==============================
-
-* Menu:
-
-* TIC54X-Opts:: Command-line Options
-* TIC54X-Block:: Blocking
-* TIC54X-Env:: Environment Settings
-* TIC54X-Constants:: Constants Syntax
-* TIC54X-Subsyms:: String Substitution
-* TIC54X-Locals:: Local Label Syntax
-* TIC54X-Builtins:: Builtin Assembler Math Functions
-* TIC54X-Ext:: Extended Addressing Support
-* TIC54X-Directives:: Directives
-* TIC54X-Macros:: Macro Features
-* TIC54X-MMRegs:: Memory-mapped Registers
-
-\1f
-File: as.info, Node: TIC54X-Opts, Next: TIC54X-Block, Up: TIC54X-Dependent
-
-8.31.1 Options
---------------
-
-The TMS320C54X version of `as' has a few machine-dependent options.
-
- You can use the `-mfar-mode' option to enable extended addressing
-mode. All addresses will be assumed to be > 16 bits, and the
-appropriate relocation types will be used. This option is equivalent
-to using the `.far_mode' directive in the assembly code. If you do not
-use the `-mfar-mode' option, all references will be assumed to be 16
-bits. This option may be abbreviated to `-mf'.
-
- You can use the `-mcpu' option to specify a particular CPU. This
-option is equivalent to using the `.version' directive in the assembly
-code. For recognized CPU codes, see *Note `.version':
-TIC54X-Directives. The default CPU version is `542'.
-
- You can use the `-merrors-to-file' option to redirect error output
-to a file (this provided for those deficient environments which don't
-provide adequate output redirection). This option may be abbreviated to
-`-me'.
-
-\1f
-File: as.info, Node: TIC54X-Block, Next: TIC54X-Env, Prev: TIC54X-Opts, Up: TIC54X-Dependent
-
-8.31.2 Blocking
----------------
-
-A blocked section or memory block is guaranteed not to cross the
-blocking boundary (usually a page, or 128 words) if it is smaller than
-the blocking size, or to start on a page boundary if it is larger than
-the blocking size.
-
-\1f
-File: as.info, Node: TIC54X-Env, Next: TIC54X-Constants, Prev: TIC54X-Block, Up: TIC54X-Dependent
-
-8.31.3 Environment Settings
----------------------------
-
-`C54XDSP_DIR' and `A_DIR' are semicolon-separated paths which are added
-to the list of directories normally searched for source and include
-files. `C54XDSP_DIR' will override `A_DIR'.
-
-\1f
-File: as.info, Node: TIC54X-Constants, Next: TIC54X-Subsyms, Prev: TIC54X-Env, Up: TIC54X-Dependent
-
-8.31.4 Constants Syntax
------------------------
-
-The TIC54X version of `as' allows the following additional constant
-formats, using a suffix to indicate the radix:
-
- Binary `000000B, 011000b'
- Octal `10Q, 224q'
- Hexadecimal `45h, 0FH'
-
-\1f
-File: as.info, Node: TIC54X-Subsyms, Next: TIC54X-Locals, Prev: TIC54X-Constants, Up: TIC54X-Dependent
-
-8.31.5 String Substitution
---------------------------
-
-A subset of allowable symbols (which we'll call subsyms) may be assigned
-arbitrary string values. This is roughly equivalent to C preprocessor
-#define macros. When `as' encounters one of these symbols, the symbol
-is replaced in the input stream by its string value. Subsym names
-*must* begin with a letter.
-
- Subsyms may be defined using the `.asg' and `.eval' directives
-(*Note `.asg': TIC54X-Directives, *Note `.eval': TIC54X-Directives.
-
- Expansion is recursive until a previously encountered symbol is
-seen, at which point substitution stops.
-
- In this example, x is replaced with SYM2; SYM2 is replaced with
-SYM1, and SYM1 is replaced with x. At this point, x has already been
-encountered and the substitution stops.
-
- .asg "x",SYM1
- .asg "SYM1",SYM2
- .asg "SYM2",x
- add x,a ; final code assembled is "add x, a"
-
- Macro parameters are converted to subsyms; a side effect of this is
-the normal `as' '\ARG' dereferencing syntax is unnecessary. Subsyms
-defined within a macro will have global scope, unless the `.var'
-directive is used to identify the subsym as a local macro variable
-*note `.var': TIC54X-Directives.
-
- Substitution may be forced in situations where replacement might be
-ambiguous by placing colons on either side of the subsym. The following
-code:
-
- .eval "10",x
- LAB:X: add #x, a
-
- When assembled becomes:
-
- LAB10 add #10, a
-
- Smaller parts of the string assigned to a subsym may be accessed with
-the following syntax:
-
-``:SYMBOL(CHAR_INDEX):''
- Evaluates to a single-character string, the character at
- CHAR_INDEX.
-
-``:SYMBOL(START,LENGTH):''
- Evaluates to a substring of SYMBOL beginning at START with length
- LENGTH.
-
-\1f
-File: as.info, Node: TIC54X-Locals, Next: TIC54X-Builtins, Prev: TIC54X-Subsyms, Up: TIC54X-Dependent
-
-8.31.6 Local Labels
--------------------
-
-Local labels may be defined in two ways:
-
- * $N, where N is a decimal number between 0 and 9
-
- * LABEL?, where LABEL is any legal symbol name.
-
- Local labels thus defined may be redefined or automatically
-generated. The scope of a local label is based on when it may be
-undefined or reset. This happens when one of the following situations
-is encountered:
-
- * .newblock directive *note `.newblock': TIC54X-Directives.
-
- * The current section is changed (.sect, .text, or .data)
-
- * Entering or leaving an included file
-
- * The macro scope where the label was defined is exited
-
-\1f
-File: as.info, Node: TIC54X-Builtins, Next: TIC54X-Ext, Prev: TIC54X-Locals, Up: TIC54X-Dependent
-
-8.31.7 Math Builtins
---------------------
-
-The following built-in functions may be used to generate a
-floating-point value. All return a floating-point value except `$cvi',
-`$int', and `$sgn', which return an integer value.
-
-``$acos(EXPR)''
- Returns the floating point arccosine of EXPR.
-
-``$asin(EXPR)''
- Returns the floating point arcsine of EXPR.
-
-``$atan(EXPR)''
- Returns the floating point arctangent of EXPR.
-
-``$atan2(EXPR1,EXPR2)''
- Returns the floating point arctangent of EXPR1 / EXPR2.
-
-``$ceil(EXPR)''
- Returns the smallest integer not less than EXPR as floating point.
-
-``$cosh(EXPR)''
- Returns the floating point hyperbolic cosine of EXPR.
-
-``$cos(EXPR)''
- Returns the floating point cosine of EXPR.
-
-``$cvf(EXPR)''
- Returns the integer value EXPR converted to floating-point.
-
-``$cvi(EXPR)''
- Returns the floating point value EXPR converted to integer.
-
-``$exp(EXPR)''
- Returns the floating point value e ^ EXPR.
-
-``$fabs(EXPR)''
- Returns the floating point absolute value of EXPR.
-
-``$floor(EXPR)''
- Returns the largest integer that is not greater than EXPR as
- floating point.
-
-``$fmod(EXPR1,EXPR2)''
- Returns the floating point remainder of EXPR1 / EXPR2.
-
-``$int(EXPR)''
- Returns 1 if EXPR evaluates to an integer, zero otherwise.
-
-``$ldexp(EXPR1,EXPR2)''
- Returns the floating point value EXPR1 * 2 ^ EXPR2.
-
-``$log10(EXPR)''
- Returns the base 10 logarithm of EXPR.
-
-``$log(EXPR)''
- Returns the natural logarithm of EXPR.
-
-``$max(EXPR1,EXPR2)''
- Returns the floating point maximum of EXPR1 and EXPR2.
-
-``$min(EXPR1,EXPR2)''
- Returns the floating point minimum of EXPR1 and EXPR2.
-
-``$pow(EXPR1,EXPR2)''
- Returns the floating point value EXPR1 ^ EXPR2.
-
-``$round(EXPR)''
- Returns the nearest integer to EXPR as a floating point number.
-
-``$sgn(EXPR)''
- Returns -1, 0, or 1 based on the sign of EXPR.
-
-``$sin(EXPR)''
- Returns the floating point sine of EXPR.
-
-``$sinh(EXPR)''
- Returns the floating point hyperbolic sine of EXPR.
-
-``$sqrt(EXPR)''
- Returns the floating point square root of EXPR.
-
-``$tan(EXPR)''
- Returns the floating point tangent of EXPR.
-
-``$tanh(EXPR)''
- Returns the floating point hyperbolic tangent of EXPR.
-
-``$trunc(EXPR)''
- Returns the integer value of EXPR truncated towards zero as
- floating point.
-
-
-\1f
-File: as.info, Node: TIC54X-Ext, Next: TIC54X-Directives, Prev: TIC54X-Builtins, Up: TIC54X-Dependent
-
-8.31.8 Extended Addressing
---------------------------
-
-The `LDX' pseudo-op is provided for loading the extended addressing bits
-of a label or address. For example, if an address `_label' resides in
-extended program memory, the value of `_label' may be loaded as follows:
- ldx #_label,16,a ; loads extended bits of _label
- or #_label,a ; loads lower 16 bits of _label
- bacc a ; full address is in accumulator A
-
-\1f
-File: as.info, Node: TIC54X-Directives, Next: TIC54X-Macros, Prev: TIC54X-Ext, Up: TIC54X-Dependent
-
-8.31.9 Directives
------------------
-
-`.align [SIZE]'
-`.even'
- Align the section program counter on the next boundary, based on
- SIZE. SIZE may be any power of 2. `.even' is equivalent to
- `.align' with a SIZE of 2.
- `1'
- Align SPC to word boundary
-
- `2'
- Align SPC to longword boundary (same as .even)
-
- `128'
- Align SPC to page boundary
-
-`.asg STRING, NAME'
- Assign NAME the string STRING. String replacement is performed on
- STRING before assignment.
-
-`.eval STRING, NAME'
- Evaluate the contents of string STRING and assign the result as a
- string to the subsym NAME. String replacement is performed on
- STRING before assignment.
-
-`.bss SYMBOL, SIZE [, [BLOCKING_FLAG] [,ALIGNMENT_FLAG]]'
- Reserve space for SYMBOL in the .bss section. SIZE is in words.
- If present, BLOCKING_FLAG indicates the allocated space should be
- aligned on a page boundary if it would otherwise cross a page
- boundary. If present, ALIGNMENT_FLAG causes the assembler to
- allocate SIZE on a long word boundary.
-
-`.byte VALUE [,...,VALUE_N]'
-`.ubyte VALUE [,...,VALUE_N]'
-`.char VALUE [,...,VALUE_N]'
-`.uchar VALUE [,...,VALUE_N]'
- Place one or more bytes into consecutive words of the current
- section. The upper 8 bits of each word is zero-filled. If a
- label is used, it points to the word allocated for the first byte
- encountered.
-
-`.clink ["SECTION_NAME"]'
- Set STYP_CLINK flag for this section, which indicates to the
- linker that if no symbols from this section are referenced, the
- section should not be included in the link. If SECTION_NAME is
- omitted, the current section is used.
-
-`.c_mode'
- TBD.
-
-`.copy "FILENAME" | FILENAME'
-`.include "FILENAME" | FILENAME'
- Read source statements from FILENAME. The normal include search
- path is used. Normally .copy will cause statements from the
- included file to be printed in the assembly listing and .include
- will not, but this distinction is not currently implemented.
-
-`.data'
- Begin assembling code into the .data section.
-
-`.double VALUE [,...,VALUE_N]'
-`.ldouble VALUE [,...,VALUE_N]'
-`.float VALUE [,...,VALUE_N]'
-`.xfloat VALUE [,...,VALUE_N]'
- Place an IEEE single-precision floating-point representation of
- one or more floating-point values into the current section. All
- but `.xfloat' align the result on a longword boundary. Values are
- stored most-significant word first.
-
-`.drlist'
-`.drnolist'
- Control printing of directives to the listing file. Ignored.
-
-`.emsg STRING'
-`.mmsg STRING'
-`.wmsg STRING'
- Emit a user-defined error, message, or warning, respectively.
-
-`.far_mode'
- Use extended addressing when assembling statements. This should
- appear only once per file, and is equivalent to the -mfar-mode
- option *note `-mfar-mode': TIC54X-Opts.
-
-`.fclist'
-`.fcnolist'
- Control printing of false conditional blocks to the listing file.
-
-`.field VALUE [,SIZE]'
- Initialize a bitfield of SIZE bits in the current section. If
- VALUE is relocatable, then SIZE must be 16. SIZE defaults to 16
- bits. If VALUE does not fit into SIZE bits, the value will be
- truncated. Successive `.field' directives will pack starting at
- the current word, filling the most significant bits first, and
- aligning to the start of the next word if the field size does not
- fit into the space remaining in the current word. A `.align'
- directive with an operand of 1 will force the next `.field'
- directive to begin packing into a new word. If a label is used, it
- points to the word that contains the specified field.
-
-`.global SYMBOL [,...,SYMBOL_N]'
-`.def SYMBOL [,...,SYMBOL_N]'
-`.ref SYMBOL [,...,SYMBOL_N]'
- `.def' nominally identifies a symbol defined in the current file
- and available to other files. `.ref' identifies a symbol used in
- the current file but defined elsewhere. Both map to the standard
- `.global' directive.
-
-`.half VALUE [,...,VALUE_N]'
-`.uhalf VALUE [,...,VALUE_N]'
-`.short VALUE [,...,VALUE_N]'
-`.ushort VALUE [,...,VALUE_N]'
-`.int VALUE [,...,VALUE_N]'
-`.uint VALUE [,...,VALUE_N]'
-`.word VALUE [,...,VALUE_N]'
-`.uword VALUE [,...,VALUE_N]'
- Place one or more values into consecutive words of the current
- section. If a label is used, it points to the word allocated for
- the first value encountered.
-
-`.label SYMBOL'
- Define a special SYMBOL to refer to the load time address of the
- current section program counter.
-
-`.length'
-`.width'
- Set the page length and width of the output listing file. Ignored.
-
-`.list'
-`.nolist'
- Control whether the source listing is printed. Ignored.
-
-`.long VALUE [,...,VALUE_N]'
-`.ulong VALUE [,...,VALUE_N]'
-`.xlong VALUE [,...,VALUE_N]'
- Place one or more 32-bit values into consecutive words in the
- current section. The most significant word is stored first.
- `.long' and `.ulong' align the result on a longword boundary;
- `xlong' does not.
-
-`.loop [COUNT]'
-`.break [CONDITION]'
-`.endloop'
- Repeatedly assemble a block of code. `.loop' begins the block, and
- `.endloop' marks its termination. COUNT defaults to 1024, and
- indicates the number of times the block should be repeated.
- `.break' terminates the loop so that assembly begins after the
- `.endloop' directive. The optional CONDITION will cause the loop
- to terminate only if it evaluates to zero.
-
-`MACRO_NAME .macro [PARAM1][,...PARAM_N]'
-`[.mexit]'
-`.endm'
- See the section on macros for more explanation (*Note
- TIC54X-Macros::.
-
-`.mlib "FILENAME" | FILENAME'
- Load the macro library FILENAME. FILENAME must be an archived
- library (BFD ar-compatible) of text files, expected to contain
- only macro definitions. The standard include search path is used.
-
-`.mlist'
-
-`.mnolist'
- Control whether to include macro and loop block expansions in the
- listing output. Ignored.
-
-`.mmregs'
- Define global symbolic names for the 'c54x registers. Supposedly
- equivalent to executing `.set' directives for each register with
- its memory-mapped value, but in reality is provided only for
- compatibility and does nothing.
-
-`.newblock'
- This directive resets any TIC54X local labels currently defined.
- Normal `as' local labels are unaffected.
-
-`.option OPTION_LIST'
- Set listing options. Ignored.
-
-`.sblock "SECTION_NAME" | SECTION_NAME [,"NAME_N" | NAME_N]'
- Designate SECTION_NAME for blocking. Blocking guarantees that a
- section will start on a page boundary (128 words) if it would
- otherwise cross a page boundary. Only initialized sections may be
- designated with this directive. See also *Note TIC54X-Block::.
-
-`.sect "SECTION_NAME"'
- Define a named initialized section and make it the current section.
-
-`SYMBOL .set "VALUE"'
-`SYMBOL .equ "VALUE"'
- Equate a constant VALUE to a SYMBOL, which is placed in the symbol
- table. SYMBOL may not be previously defined.
-
-`.space SIZE_IN_BITS'
-`.bes SIZE_IN_BITS'
- Reserve the given number of bits in the current section and
- zero-fill them. If a label is used with `.space', it points to the
- *first* word reserved. With `.bes', the label points to the
- *last* word reserved.
-
-`.sslist'
-`.ssnolist'
- Controls the inclusion of subsym replacement in the listing
- output. Ignored.
-
-`.string "STRING" [,...,"STRING_N"]'
-`.pstring "STRING" [,...,"STRING_N"]'
- Place 8-bit characters from STRING into the current section.
- `.string' zero-fills the upper 8 bits of each word, while
- `.pstring' puts two characters into each word, filling the
- most-significant bits first. Unused space is zero-filled. If a
- label is used, it points to the first word initialized.
-
-`[STAG] .struct [OFFSET]'
-`[NAME_1] element [COUNT_1]'
-`[NAME_2] element [COUNT_2]'
-`[TNAME] .tag STAGX [TCOUNT]'
-`...'
-`[NAME_N] element [COUNT_N]'
-`[SSIZE] .endstruct'
-`LABEL .tag [STAG]'
- Assign symbolic offsets to the elements of a structure. STAG
- defines a symbol to use to reference the structure. OFFSET
- indicates a starting value to use for the first element
- encountered; otherwise it defaults to zero. Each element can have
- a named offset, NAME, which is a symbol assigned the value of the
- element's offset into the structure. If STAG is missing, these
- become global symbols. COUNT adjusts the offset that many times,
- as if `element' were an array. `element' may be one of `.byte',
- `.word', `.long', `.float', or any equivalent of those, and the
- structure offset is adjusted accordingly. `.field' and `.string'
- are also allowed; the size of `.field' is one bit, and `.string'
- is considered to be one word in size. Only element descriptors,
- structure/union tags, `.align' and conditional assembly directives
- are allowed within `.struct'/`.endstruct'. `.align' aligns member
- offsets to word boundaries only. SSIZE, if provided, will always
- be assigned the size of the structure.
-
- The `.tag' directive, in addition to being used to define a
- structure/union element within a structure, may be used to apply a
- structure to a symbol. Once applied to LABEL, the individual
- structure elements may be applied to LABEL to produce the desired
- offsets using LABEL as the structure base.
-
-`.tab'
- Set the tab size in the output listing. Ignored.
-
-`[UTAG] .union'
-`[NAME_1] element [COUNT_1]'
-`[NAME_2] element [COUNT_2]'
-`[TNAME] .tag UTAGX[,TCOUNT]'
-`...'
-`[NAME_N] element [COUNT_N]'
-`[USIZE] .endstruct'
-`LABEL .tag [UTAG]'
- Similar to `.struct', but the offset after each element is reset to
- zero, and the USIZE is set to the maximum of all defined elements.
- Starting offset for the union is always zero.
-
-`[SYMBOL] .usect "SECTION_NAME", SIZE, [,[BLOCKING_FLAG] [,ALIGNMENT_FLAG]]'
- Reserve space for variables in a named, uninitialized section
- (similar to .bss). `.usect' allows definitions sections
- independent of .bss. SYMBOL points to the first location reserved
- by this allocation. The symbol may be used as a variable name.
- SIZE is the allocated size in words. BLOCKING_FLAG indicates
- whether to block this section on a page boundary (128 words)
- (*note TIC54X-Block::). ALIGNMENT FLAG indicates whether the
- section should be longword-aligned.
-
-`.var SYM[,..., SYM_N]'
- Define a subsym to be a local variable within a macro. See *Note
- TIC54X-Macros::.
-
-`.version VERSION'
- Set which processor to build instructions for. Though the
- following values are accepted, the op is ignored.
- `541'
- `542'
- `543'
- `545'
- `545LP'
- `546LP'
- `548'
- `549'
-
-\1f
-File: as.info, Node: TIC54X-Macros, Next: TIC54X-MMRegs, Prev: TIC54X-Directives, Up: TIC54X-Dependent
-
-8.31.10 Macros
---------------
-
-Macros do not require explicit dereferencing of arguments (i.e., \ARG).
-
- During macro expansion, the macro parameters are converted to
-subsyms. If the number of arguments passed the macro invocation
-exceeds the number of parameters defined, the last parameter is
-assigned the string equivalent of all remaining arguments. If fewer
-arguments are given than parameters, the missing parameters are
-assigned empty strings. To include a comma in an argument, you must
-enclose the argument in quotes.
-
- The following built-in subsym functions allow examination of the
-string value of subsyms (or ordinary strings). The arguments are
-strings unless otherwise indicated (subsyms passed as args will be
-replaced by the strings they represent).
-``$symlen(STR)''
- Returns the length of STR.
-
-``$symcmp(STR1,STR2)''
- Returns 0 if STR1 == STR2, non-zero otherwise.
-
-``$firstch(STR,CH)''
- Returns index of the first occurrence of character constant CH in
- STR.
-
-``$lastch(STR,CH)''
- Returns index of the last occurrence of character constant CH in
- STR.
-
-``$isdefed(SYMBOL)''
- Returns zero if the symbol SYMBOL is not in the symbol table,
- non-zero otherwise.
-
-``$ismember(SYMBOL,LIST)''
- Assign the first member of comma-separated string LIST to SYMBOL;
- LIST is reassigned the remainder of the list. Returns zero if
- LIST is a null string. Both arguments must be subsyms.
-
-``$iscons(EXPR)''
- Returns 1 if string EXPR is binary, 2 if octal, 3 if hexadecimal,
- 4 if a character, 5 if decimal, and zero if not an integer.
-
-``$isname(NAME)''
- Returns 1 if NAME is a valid symbol name, zero otherwise.
-
-``$isreg(REG)''
- Returns 1 if REG is a valid predefined register name (AR0-AR7
- only).
-
-``$structsz(STAG)''
- Returns the size of the structure or union represented by STAG.
-
-``$structacc(STAG)''
- Returns the reference point of the structure or union represented
- by STAG. Always returns zero.
-
-
-\1f
-File: as.info, Node: TIC54X-MMRegs, Prev: TIC54X-Macros, Up: TIC54X-Dependent
-
-8.31.11 Memory-mapped Registers
--------------------------------
-
-The following symbols are recognized as memory-mapped registers:
-
-
-\1f
-File: as.info, Node: Z80-Dependent, Next: Z8000-Dependent, Prev: Xtensa-Dependent, Up: Machine Dependencies
-
-8.32 Z80 Dependent Features
-===========================
-
-* Menu:
-
-* Z80 Options:: Options
-* Z80 Syntax:: Syntax
-* Z80 Floating Point:: Floating Point
-* Z80 Directives:: Z80 Machine Directives
-* Z80 Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: Z80 Options, Next: Z80 Syntax, Up: Z80-Dependent
-
-8.32.1 Options
---------------
-
-The Zilog Z80 and Ascii R800 version of `as' have a few machine
-dependent options.
-`-z80'
- Produce code for the Z80 processor. There are additional options to
- request warnings and error messages for undocumented instructions.
-
-`-ignore-undocumented-instructions'
-`-Wnud'
- Silently assemble undocumented Z80-instructions that have been
- adopted as documented R800-instructions.
-
-`-ignore-unportable-instructions'
-`-Wnup'
- Silently assemble all undocumented Z80-instructions.
-
-`-warn-undocumented-instructions'
-`-Wud'
- Issue warnings for undocumented Z80-instructions that work on
- R800, do not assemble other undocumented instructions without
- warning.
-
-`-warn-unportable-instructions'
-`-Wup'
- Issue warnings for other undocumented Z80-instructions, do not
- treat any undocumented instructions as errors.
-
-`-forbid-undocumented-instructions'
-`-Fud'
- Treat all undocumented z80-instructions as errors.
-
-`-forbid-unportable-instructions'
-`-Fup'
- Treat undocumented z80-instructions that do not work on R800 as
- errors.
-
-`-r800'
- Produce code for the R800 processor. The assembler does not support
- undocumented instructions for the R800. In line with common
- practice, `as' uses Z80 instruction names for the R800 processor,
- as far as they exist.
-
-\1f
-File: as.info, Node: Z80 Syntax, Next: Z80 Floating Point, Prev: Z80 Options, Up: Z80-Dependent
-
-8.32.2 Syntax
--------------
-
-The assembler syntax closely follows the 'Z80 family CPU User Manual' by
-Zilog. In expressions a single `=' may be used as "is equal to"
-comparison operator.
-
- Suffices can be used to indicate the radix of integer constants; `H'
-or `h' for hexadecimal, `D' or `d' for decimal, `Q', `O', `q' or `o'
-for octal, and `B' for binary.
-
- The suffix `b' denotes a backreference to local label.
-
-* Menu:
-
-* Z80-Chars:: Special Characters
-* Z80-Regs:: Register Names
-* Z80-Case:: Case Sensitivity
-
-\1f
-File: as.info, Node: Z80-Chars, Next: Z80-Regs, Up: Z80 Syntax
-
-8.32.2.1 Special Characters
-...........................
-
-The semicolon `;' is the line comment character;
-
- The dollar sign `$' can be used as a prefix for hexadecimal numbers
-and as a symbol denoting the current location counter.
-
- A backslash `\' is an ordinary character for the Z80 assembler.
-
- The single quote `'' must be followed by a closing quote. If there
-is one character in between, it is a character constant, otherwise it is
-a string constant.
-
-\1f
-File: as.info, Node: Z80-Regs, Next: Z80-Case, Prev: Z80-Chars, Up: Z80 Syntax
-
-8.32.2.2 Register Names
-.......................
-
-The registers are referred to with the letters assigned to them by
-Zilog. In addition `as' recognizes `ixl' and `ixh' as the least and
-most significant octet in `ix', and similarly `iyl' and `iyh' as parts
-of `iy'.
-
-\1f
-File: as.info, Node: Z80-Case, Prev: Z80-Regs, Up: Z80 Syntax
-
-8.32.2.3 Case Sensitivity
-.........................
-
-Upper and lower case are equivalent in register names, opcodes,
-condition codes and assembler directives. The case of letters is
-significant in labels and symbol names. The case is also important to
-distinguish the suffix `b' for a backward reference to a local label
-from the suffix `B' for a number in binary notation.
-
-\1f
-File: as.info, Node: Z80 Floating Point, Next: Z80 Directives, Prev: Z80 Syntax, Up: Z80-Dependent
-
-8.32.3 Floating Point
----------------------
-
-Floating-point numbers are not supported.
-
-\1f
-File: as.info, Node: Z80 Directives, Next: Z80 Opcodes, Prev: Z80 Floating Point, Up: Z80-Dependent
-
-8.32.4 Z80 Assembler Directives
--------------------------------
-
-`as' for the Z80 supports some additional directives for compatibility
-with other assemblers.
-
- These are the additional directives in `as' for the Z80:
-
-`db EXPRESSION|STRING[,EXPRESSION|STRING...]'
-`defb EXPRESSION|STRING[,EXPRESSION|STRING...]'
- For each STRING the characters are copied to the object file, for
- each other EXPRESSION the value is stored in one byte. A warning
- is issued in case of an overflow.
-
-`dw EXPRESSION[,EXPRESSION...]'
-`defw EXPRESSION[,EXPRESSION...]'
- For each EXPRESSION the value is stored in two bytes, ignoring
- overflow.
-
-`d24 EXPRESSION[,EXPRESSION...]'
-`def24 EXPRESSION[,EXPRESSION...]'
- For each EXPRESSION the value is stored in three bytes, ignoring
- overflow.
-
-`d32 EXPRESSION[,EXPRESSION...]'
-`def32 EXPRESSION[,EXPRESSION...]'
- For each EXPRESSION the value is stored in four bytes, ignoring
- overflow.
-
-`ds COUNT[, VALUE]'
-`defs COUNT[, VALUE]'
- Fill COUNT bytes in the object file with VALUE, if VALUE is
- omitted it defaults to zero.
-
-`SYMBOL equ EXPRESSION'
-`SYMBOL defl EXPRESSION'
- These directives set the value of SYMBOL to EXPRESSION. If `equ'
- is used, it is an error if SYMBOL is already defined. Symbols
- defined with `equ' are not protected from redefinition.
-
-`set'
- This is a normal instruction on Z80, and not an assembler
- directive.
-
-`psect NAME'
- A synonym for *Note Section::, no second argument should be given.
-
-
-\1f
-File: as.info, Node: Z80 Opcodes, Prev: Z80 Directives, Up: Z80-Dependent
-
-8.32.5 Opcodes
---------------
-
-In line with common practice, Z80 mnemonics are used for both the Z80
-and the R800.
-
- In many instructions it is possible to use one of the half index
-registers (`ixl',`ixh',`iyl',`iyh') in stead of an 8-bit general
-purpose register. This yields instructions that are documented on the
-R800 and undocumented on the Z80. Similarly `in f,(c)' is documented
-on the R800 and undocumented on the Z80.
-
- The assembler also supports the following undocumented
-Z80-instructions, that have not been adopted in the R800 instruction
-set:
-`out (c),0'
- Sends zero to the port pointed to by register c.
-
-`sli M'
- Equivalent to `M = (M<<1)+1', the operand M can be any operand
- that is valid for `sla'. One can use `sll' as a synonym for `sli'.
-
-`OP (ix+D), R'
- This is equivalent to
-
- ld R, (ix+D)
- OPC R
- ld (ix+D), R
-
- The operation `OPC' may be any of `res B,', `set B,', `rl', `rlc',
- `rr', `rrc', `sla', `sli', `sra' and `srl', and the register `R'
- may be any of `a', `b', `c', `d', `e', `h' and `l'.
-
-`OPC (iy+D), R'
- As above, but with `iy' instead of `ix'.
-
- The web site at `http://www.z80.info' is a good starting place to
-find more information on programming the Z80.
-
-\1f
-File: as.info, Node: Z8000-Dependent, Next: Vax-Dependent, Prev: Z80-Dependent, Up: Machine Dependencies
-
-8.33 Z8000 Dependent Features
-=============================
-
- The Z8000 as supports both members of the Z8000 family: the
-unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with
-24 bit addresses.
-
- When the assembler is in unsegmented mode (specified with the
-`unsegm' directive), an address takes up one word (16 bit) sized
-register. When the assembler is in segmented mode (specified with the
-`segm' directive), a 24-bit address takes up a long (32 bit) register.
-*Note Assembler Directives for the Z8000: Z8000 Directives, for a list
-of other Z8000 specific assembler directives.
-
-* Menu:
-
-* Z8000 Options:: Command-line options for the Z8000
-* Z8000 Syntax:: Assembler syntax for the Z8000
-* Z8000 Directives:: Special directives for the Z8000
-* Z8000 Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: Z8000 Options, Next: Z8000 Syntax, Up: Z8000-Dependent
-
-8.33.1 Options
---------------
-
-`-z8001'
- Generate segmented code by default.
-
-`-z8002'
- Generate unsegmented code by default.
-
-\1f
-File: as.info, Node: Z8000 Syntax, Next: Z8000 Directives, Prev: Z8000 Options, Up: Z8000-Dependent
-
-8.33.2 Syntax
--------------
-
-* Menu:
-
-* Z8000-Chars:: Special Characters
-* Z8000-Regs:: Register Names
-* Z8000-Addressing:: Addressing Modes
-
-\1f
-File: as.info, Node: Z8000-Chars, Next: Z8000-Regs, Up: Z8000 Syntax
-
-8.33.2.1 Special Characters
-...........................
-
-`!' is the line comment character.
-
- You can use `;' instead of a newline to separate statements.
-
-\1f
-File: as.info, Node: Z8000-Regs, Next: Z8000-Addressing, Prev: Z8000-Chars, Up: Z8000 Syntax
-
-8.33.2.2 Register Names
-.......................
-
-The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer
-to different sized groups of registers by register number, with the
-prefix `r' for 16 bit registers, `rr' for 32 bit registers and `rq' for
-64 bit registers. You can also refer to the contents of the first
-eight (of the sixteen 16 bit registers) by bytes. They are named `rlN'
-and `rhN'.
-
-_byte registers_
- rl0 rh0 rl1 rh1 rl2 rh2 rl3 rh3
- rl4 rh4 rl5 rh5 rl6 rh6 rl7 rh7
-
-_word registers_
- r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15
-
-_long word registers_
- rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14
-
-_quad word registers_
- rq0 rq4 rq8 rq12
-
-\1f
-File: as.info, Node: Z8000-Addressing, Prev: Z8000-Regs, Up: Z8000 Syntax
-
-8.33.2.3 Addressing Modes
-.........................
-
-as understands the following addressing modes for the Z8000:
-
-`rlN'
-`rhN'
-`rN'
-`rrN'
-`rqN'
- Register direct: 8bit, 16bit, 32bit, and 64bit registers.
-
-`@rN'
-`@rrN'
- Indirect register: @rrN in segmented mode, @rN in unsegmented
- mode.
-
-`ADDR'
- Direct: the 16 bit or 24 bit address (depending on whether the
- assembler is in segmented or unsegmented mode) of the operand is
- in the instruction.
-
-`address(rN)'
- Indexed: the 16 or 24 bit address is added to the 16 bit register
- to produce the final address in memory of the operand.
-
-`rN(#IMM)'
-`rrN(#IMM)'
- Base Address: the 16 or 24 bit register is added to the 16 bit sign
- extended immediate displacement to produce the final address in
- memory of the operand.
-
-`rN(rM)'
-`rrN(rM)'
- Base Index: the 16 or 24 bit register rN or rrN is added to the
- sign extended 16 bit index register rM to produce the final
- address in memory of the operand.
-
-`#XX'
- Immediate data XX.
-
-\1f
-File: as.info, Node: Z8000 Directives, Next: Z8000 Opcodes, Prev: Z8000 Syntax, Up: Z8000-Dependent
-
-8.33.3 Assembler Directives for the Z8000
------------------------------------------
-
-The Z8000 port of as includes additional assembler directives, for
-compatibility with other Z8000 assemblers. These do not begin with `.'
-(unlike the ordinary as directives).
-
-`segm'
-`.z8001'
- Generate code for the segmented Z8001.
-
-`unsegm'
-`.z8002'
- Generate code for the unsegmented Z8002.
-
-`name'
- Synonym for `.file'
-
-`global'
- Synonym for `.global'
-
-`wval'
- Synonym for `.word'
-
-`lval'
- Synonym for `.long'
-
-`bval'
- Synonym for `.byte'
-
-`sval'
- Assemble a string. `sval' expects one string literal, delimited by
- single quotes. It assembles each byte of the string into
- consecutive addresses. You can use the escape sequence `%XX'
- (where XX represents a two-digit hexadecimal number) to represent
- the character whose ASCII value is XX. Use this feature to
- describe single quote and other characters that may not appear in
- string literals as themselves. For example, the C statement
- `char *a = "he said \"it's 50% off\"";' is represented in Z8000
- assembly language (shown with the assembler output in hex at the
- left) as
-
- 68652073 sval 'he said %22it%27s 50%25 off%22%00'
- 61696420
- 22697427
- 73203530
- 25206F66
- 662200
-
-`rsect'
- synonym for `.section'
-
-`block'
- synonym for `.space'
-
-`even'
- special case of `.align'; aligns output to even byte boundary.
-
-\1f
-File: as.info, Node: Z8000 Opcodes, Prev: Z8000 Directives, Up: Z8000-Dependent
-
-8.33.4 Opcodes
---------------
-
-For detailed information on the Z8000 machine instruction set, see
-`Z8000 Technical Manual'.
-
- The following table summarizes the opcodes and their arguments:
-
- rs 16 bit source register
- rd 16 bit destination register
- rbs 8 bit source register
- rbd 8 bit destination register
- rrs 32 bit source register
- rrd 32 bit destination register
- rqs 64 bit source register
- rqd 64 bit destination register
- addr 16/24 bit address
- imm immediate data
-
- adc rd,rs clrb addr cpsir @rd,@rs,rr,cc
- adcb rbd,rbs clrb addr(rd) cpsirb @rd,@rs,rr,cc
- add rd,@rs clrb rbd dab rbd
- add rd,addr com @rd dbjnz rbd,disp7
- add rd,addr(rs) com addr dec @rd,imm4m1
- add rd,imm16 com addr(rd) dec addr(rd),imm4m1
- add rd,rs com rd dec addr,imm4m1
- addb rbd,@rs comb @rd dec rd,imm4m1
- addb rbd,addr comb addr decb @rd,imm4m1
- addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1
- addb rbd,imm8 comb rbd decb addr,imm4m1
- addb rbd,rbs comflg flags decb rbd,imm4m1
- addl rrd,@rs cp @rd,imm16 di i2
- addl rrd,addr cp addr(rd),imm16 div rrd,@rs
- addl rrd,addr(rs) cp addr,imm16 div rrd,addr
- addl rrd,imm32 cp rd,@rs div rrd,addr(rs)
- addl rrd,rrs cp rd,addr div rrd,imm16
- and rd,@rs cp rd,addr(rs) div rrd,rs
- and rd,addr cp rd,imm16 divl rqd,@rs
- and rd,addr(rs) cp rd,rs divl rqd,addr
- and rd,imm16 cpb @rd,imm8 divl rqd,addr(rs)
- and rd,rs cpb addr(rd),imm8 divl rqd,imm32
- andb rbd,@rs cpb addr,imm8 divl rqd,rrs
- andb rbd,addr cpb rbd,@rs djnz rd,disp7
- andb rbd,addr(rs) cpb rbd,addr ei i2
- andb rbd,imm8 cpb rbd,addr(rs) ex rd,@rs
- andb rbd,rbs cpb rbd,imm8 ex rd,addr
- bit @rd,imm4 cpb rbd,rbs ex rd,addr(rs)
- bit addr(rd),imm4 cpd rd,@rs,rr,cc ex rd,rs
- bit addr,imm4 cpdb rbd,@rs,rr,cc exb rbd,@rs
- bit rd,imm4 cpdr rd,@rs,rr,cc exb rbd,addr
- bit rd,rs cpdrb rbd,@rs,rr,cc exb rbd,addr(rs)
- bitb @rd,imm4 cpi rd,@rs,rr,cc exb rbd,rbs
- bitb addr(rd),imm4 cpib rbd,@rs,rr,cc ext0e imm8
- bitb addr,imm4 cpir rd,@rs,rr,cc ext0f imm8
- bitb rbd,imm4 cpirb rbd,@rs,rr,cc ext8e imm8
- bitb rbd,rs cpl rrd,@rs ext8f imm8
- bpt cpl rrd,addr exts rrd
- call @rd cpl rrd,addr(rs) extsb rd
- call addr cpl rrd,imm32 extsl rqd
- call addr(rd) cpl rrd,rrs halt
- calr disp12 cpsd @rd,@rs,rr,cc in rd,@rs
- clr @rd cpsdb @rd,@rs,rr,cc in rd,imm16
- clr addr cpsdr @rd,@rs,rr,cc inb rbd,@rs
- clr addr(rd) cpsdrb @rd,@rs,rr,cc inb rbd,imm16
- clr rd cpsi @rd,@rs,rr,cc inc @rd,imm4m1
- clrb @rd cpsib @rd,@rs,rr,cc inc addr(rd),imm4m1
- inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs)
- inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16
- incb @rd,imm4m1 ldb rd(rx),rbs mult rrd,rs
- incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@rs
- incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr
- incb rbd,imm4m1 ldd @rs,@rd,rr multl rqd,addr(rs)
- ind @rd,@rs,ra lddb @rs,@rd,rr multl rqd,imm32
- indb @rd,@rs,rba lddr @rs,@rd,rr multl rqd,rrs
- inib @rd,@rs,ra lddrb @rs,@rd,rr neg @rd
- inibr @rd,@rs,ra ldi @rd,@rs,rr neg addr
- iret ldib @rd,@rs,rr neg addr(rd)
- jp cc,@rd ldir @rd,@rs,rr neg rd
- jp cc,addr ldirb @rd,@rs,rr negb @rd
- jp cc,addr(rd) ldk rd,imm4 negb addr
- jr cc,disp8 ldl @rd,rrs negb addr(rd)
- ld @rd,imm16 ldl addr(rd),rrs negb rbd
- ld @rd,rs ldl addr,rrs nop
- ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@rs
- ld addr(rd),rs ldl rd(rx),rrs or rd,addr
- ld addr,imm16 ldl rrd,@rs or rd,addr(rs)
- ld addr,rs ldl rrd,addr or rd,imm16
- ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs
- ld rd(rx),rs ldl rrd,imm32 orb rbd,@rs
- ld rd,@rs ldl rrd,rrs orb rbd,addr
- ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs)
- ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8
- ld rd,imm16 ldm @rd,rs,n orb rbd,rbs
- ld rd,rs ldm addr(rd),rs,n out @rd,rs
- ld rd,rs(imm16) ldm addr,rs,n out imm16,rs
- ld rd,rs(rx) ldm rd,@rs,n outb @rd,rbs
- lda rd,addr ldm rd,addr(rs),n outb imm16,rbs
- lda rd,addr(rs) ldm rd,addr,n outd @rd,@rs,ra
- lda rd,rs(imm16) ldps @rs outdb @rd,@rs,rba
- lda rd,rs(rx) ldps addr outib @rd,@rs,ra
- ldar rd,disp16 ldps addr(rs) outibr @rd,@rs,ra
- ldb @rd,imm8 ldr disp16,rs pop @rd,@rs
- ldb @rd,rbs ldr rd,disp16 pop addr(rd),@rs
- ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@rs
- ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@rs
- ldb addr,imm8 ldrl disp16,rrs popl @rd,@rs
- ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@rs
- ldb rbd,@rs mbit popl addr,@rs
- ldb rbd,addr mreq rd popl rrd,@rs
- ldb rbd,addr(rs) mres push @rd,@rs
- ldb rbd,imm8 mset push @rd,addr
- ldb rbd,rbs mult rrd,@rs push @rd,addr(rs)
- ldb rbd,rs(imm16) mult rrd,addr push @rd,imm16
- push @rd,rs set addr,imm4 subl rrd,imm32
- pushl @rd,@rs set rd,imm4 subl rrd,rrs
- pushl @rd,addr set rd,rs tcc cc,rd
- pushl @rd,addr(rs) setb @rd,imm4 tccb cc,rbd
- pushl @rd,rrs setb addr(rd),imm4 test @rd
- res @rd,imm4 setb addr,imm4 test addr
- res addr(rd),imm4 setb rbd,imm4 test addr(rd)
- res addr,imm4 setb rbd,rs test rd
- res rd,imm4 setflg imm4 testb @rd
- res rd,rs sinb rbd,imm16 testb addr
- resb @rd,imm4 sinb rd,imm16 testb addr(rd)
- resb addr(rd),imm4 sind @rd,@rs,ra testb rbd
- resb addr,imm4 sindb @rd,@rs,rba testl @rd
- resb rbd,imm4 sinib @rd,@rs,ra testl addr
- resb rbd,rs sinibr @rd,@rs,ra testl addr(rd)
- resflg imm4 sla rd,imm8 testl rrd
- ret cc slab rbd,imm8 trdb @rd,@rs,rba
- rl rd,imm1or2 slal rrd,imm8 trdrb @rd,@rs,rba
- rlb rbd,imm1or2 sll rd,imm8 trib @rd,@rs,rbr
- rlc rd,imm1or2 sllb rbd,imm8 trirb @rd,@rs,rbr
- rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @ra,@rb,rbr
- rldb rbb,rba sout imm16,rs trtib @ra,@rb,rr
- rr rd,imm1or2 soutb imm16,rbs trtirb @ra,@rb,rbr
- rrb rbd,imm1or2 soutd @rd,@rs,ra trtrb @ra,@rb,rbr
- rrc rd,imm1or2 soutdb @rd,@rs,rba tset @rd
- rrcb rbd,imm1or2 soutib @rd,@rs,ra tset addr
- rrdb rbb,rba soutibr @rd,@rs,ra tset addr(rd)
- rsvd36 sra rd,imm8 tset rd
- rsvd38 srab rbd,imm8 tsetb @rd
- rsvd78 sral rrd,imm8 tsetb addr
- rsvd7e srl rd,imm8 tsetb addr(rd)
- rsvd9d srlb rbd,imm8 tsetb rbd
- rsvd9f srll rrd,imm8 xor rd,@rs
- rsvdb9 sub rd,@rs xor rd,addr
- rsvdbf sub rd,addr xor rd,addr(rs)
- sbc rd,rs sub rd,addr(rs) xor rd,imm16
- sbcb rbd,rbs sub rd,imm16 xor rd,rs
- sc imm8 sub rd,rs xorb rbd,@rs
- sda rd,rs subb rbd,@rs xorb rbd,addr
- sdab rbd,rs subb rbd,addr xorb rbd,addr(rs)
- sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8
- sdl rd,rs subb rbd,imm8 xorb rbd,rbs
- sdlb rbd,rs subb rbd,rbs xorb rbd,rbs
- sdll rrd,rs subl rrd,@rs
- set @rd,imm4 subl rrd,addr
- set addr(rd),imm4 subl rrd,addr(rs)
-
-\1f
-File: as.info, Node: Vax-Dependent, Prev: Z8000-Dependent, Up: Machine Dependencies
-
-8.34 VAX Dependent Features
-===========================
-
-* Menu:
-
-* VAX-Opts:: VAX Command-Line Options
-* VAX-float:: VAX Floating Point
-* VAX-directives:: Vax Machine Directives
-* VAX-opcodes:: VAX Opcodes
-* VAX-branch:: VAX Branch Improvement
-* VAX-operands:: VAX Operands
-* VAX-no:: Not Supported on VAX
-
-\1f
-File: as.info, Node: VAX-Opts, Next: VAX-float, Up: Vax-Dependent
-
-8.34.1 VAX Command-Line Options
--------------------------------
-
-The Vax version of `as' accepts any of the following options, gives a
-warning message that the option was ignored and proceeds. These
-options are for compatibility with scripts designed for other people's
-assemblers.
-
-``-D' (Debug)'
-``-S' (Symbol Table)'
-``-T' (Token Trace)'
- These are obsolete options used to debug old assemblers.
-
-``-d' (Displacement size for JUMPs)'
- This option expects a number following the `-d'. Like options
- that expect filenames, the number may immediately follow the `-d'
- (old standard) or constitute the whole of the command line
- argument that follows `-d' (GNU standard).
-
-``-V' (Virtualize Interpass Temporary File)'
- Some other assemblers use a temporary file. This option commanded
- them to keep the information in active memory rather than in a
- disk file. `as' always does this, so this option is redundant.
-
-``-J' (JUMPify Longer Branches)'
- Many 32-bit computers permit a variety of branch instructions to
- do the same job. Some of these instructions are short (and fast)
- but have a limited range; others are long (and slow) but can
- branch anywhere in virtual memory. Often there are 3 flavors of
- branch: short, medium and long. Some other assemblers would emit
- short and medium branches, unless told by this option to emit
- short and long branches.
-
-``-t' (Temporary File Directory)'
- Some other assemblers may use a temporary file, and this option
- takes a filename being the directory to site the temporary file.
- Since `as' does not use a temporary disk file, this option makes
- no difference. `-t' needs exactly one filename.
-
- The Vax version of the assembler accepts additional options when
-compiled for VMS:
-
-`-h N'
- External symbol or section (used for global variables) names are
- not case sensitive on VAX/VMS and always mapped to upper case.
- This is contrary to the C language definition which explicitly
- distinguishes upper and lower case. To implement a standard
- conforming C compiler, names must be changed (mapped) to preserve
- the case information. The default mapping is to convert all lower
- case characters to uppercase and adding an underscore followed by
- a 6 digit hex value, representing a 24 digit binary value. The
- one digits in the binary value represent which characters are
- uppercase in the original symbol name.
-
- The `-h N' option determines how we map names. This takes several
- values. No `-h' switch at all allows case hacking as described
- above. A value of zero (`-h0') implies names should be upper
- case, and inhibits the case hack. A value of 2 (`-h2') implies
- names should be all lower case, with no case hack. A value of 3
- (`-h3') implies that case should be preserved. The value 1 is
- unused. The `-H' option directs `as' to display every mapped
- symbol during assembly.
-
- Symbols whose names include a dollar sign `$' are exceptions to the
- general name mapping. These symbols are normally only used to
- reference VMS library names. Such symbols are always mapped to
- upper case.
-
-`-+'
- The `-+' option causes `as' to truncate any symbol name larger
- than 31 characters. The `-+' option also prevents some code
- following the `_main' symbol normally added to make the object
- file compatible with Vax-11 "C".
-
-`-1'
- This option is ignored for backward compatibility with `as'
- version 1.x.
-
-`-H'
- The `-H' option causes `as' to print every symbol which was
- changed by case mapping.
-
-\1f
-File: as.info, Node: VAX-float, Next: VAX-directives, Prev: VAX-Opts, Up: Vax-Dependent
-
-8.34.2 VAX Floating Point
--------------------------
-
-Conversion of flonums to floating point is correct, and compatible with
-previous assemblers. Rounding is towards zero if the remainder is
-exactly half the least significant bit.
-
- `D', `F', `G' and `H' floating point formats are understood.
-
- Immediate floating literals (_e.g._ `S`$6.9') are rendered
-correctly. Again, rounding is towards zero in the boundary case.
-
- The `.float' directive produces `f' format numbers. The `.double'
-directive produces `d' format numbers.
-
-\1f
-File: as.info, Node: VAX-directives, Next: VAX-opcodes, Prev: VAX-float, Up: Vax-Dependent
-
-8.34.3 Vax Machine Directives
------------------------------
-
-The Vax version of the assembler supports four directives for
-generating Vax floating point constants. They are described in the
-table below.
-
-`.dfloat'
- This expects zero or more flonums, separated by commas, and
- assembles Vax `d' format 64-bit floating point constants.
-
-`.ffloat'
- This expects zero or more flonums, separated by commas, and
- assembles Vax `f' format 32-bit floating point constants.
-
-`.gfloat'
- This expects zero or more flonums, separated by commas, and
- assembles Vax `g' format 64-bit floating point constants.
-
-`.hfloat'
- This expects zero or more flonums, separated by commas, and
- assembles Vax `h' format 128-bit floating point constants.
-
-
-\1f
-File: as.info, Node: VAX-opcodes, Next: VAX-branch, Prev: VAX-directives, Up: Vax-Dependent
-
-8.34.4 VAX Opcodes
-------------------
-
-All DEC mnemonics are supported. Beware that `case...' instructions
-have exactly 3 operands. The dispatch table that follows the `case...'
-instruction should be made with `.word' statements. This is compatible
-with all unix assemblers we know of.
-
-\1f
-File: as.info, Node: VAX-branch, Next: VAX-operands, Prev: VAX-opcodes, Up: Vax-Dependent
-
-8.34.5 VAX Branch Improvement
------------------------------
-
-Certain pseudo opcodes are permitted. They are for branch
-instructions. They expand to the shortest branch instruction that
-reaches the target. Generally these mnemonics are made by substituting
-`j' for `b' at the start of a DEC mnemonic. This feature is included
-both for compatibility and to help compilers. If you do not need this
-feature, avoid these opcodes. Here are the mnemonics, and the code
-they can expand into.
-
-`jbsb'
- `Jsb' is already an instruction mnemonic, so we chose `jbsb'.
- (byte displacement)
- `bsbb ...'
-
- (word displacement)
- `bsbw ...'
-
- (long displacement)
- `jsb ...'
-
-`jbr'
-`jr'
- Unconditional branch.
- (byte displacement)
- `brb ...'
-
- (word displacement)
- `brw ...'
-
- (long displacement)
- `jmp ...'
-
-`jCOND'
- COND may be any one of the conditional branches `neq', `nequ',
- `eql', `eqlu', `gtr', `geq', `lss', `gtru', `lequ', `vc', `vs',
- `gequ', `cc', `lssu', `cs'. COND may also be one of the bit tests
- `bs', `bc', `bss', `bcs', `bsc', `bcc', `bssi', `bcci', `lbs',
- `lbc'. NOTCOND is the opposite condition to COND.
- (byte displacement)
- `bCOND ...'
-
- (word displacement)
- `bNOTCOND foo ; brw ... ; foo:'
-
- (long displacement)
- `bNOTCOND foo ; jmp ... ; foo:'
-
-`jacbX'
- X may be one of `b d f g h l w'.
- (word displacement)
- `OPCODE ...'
-
- (long displacement)
- OPCODE ..., foo ;
- brb bar ;
- foo: jmp ... ;
- bar:
-
-`jaobYYY'
- YYY may be one of `lss leq'.
-
-`jsobZZZ'
- ZZZ may be one of `geq gtr'.
- (byte displacement)
- `OPCODE ...'
-
- (word displacement)
- OPCODE ..., foo ;
- brb bar ;
- foo: brw DESTINATION ;
- bar:
-
- (long displacement)
- OPCODE ..., foo ;
- brb bar ;
- foo: jmp DESTINATION ;
- bar:
-
-`aobleq'
-`aoblss'
-`sobgeq'
-`sobgtr'
-
- (byte displacement)
- `OPCODE ...'
-
- (word displacement)
- OPCODE ..., foo ;
- brb bar ;
- foo: brw DESTINATION ;
- bar:
-
- (long displacement)
- OPCODE ..., foo ;
- brb bar ;
- foo: jmp DESTINATION ;
- bar:
-
-\1f
-File: as.info, Node: VAX-operands, Next: VAX-no, Prev: VAX-branch, Up: Vax-Dependent
-
-8.34.6 VAX Operands
--------------------
-
-The immediate character is `$' for Unix compatibility, not `#' as DEC
-writes it.
-
- The indirect character is `*' for Unix compatibility, not `@' as DEC
-writes it.
-
- The displacement sizing character is ``' (an accent grave) for Unix
-compatibility, not `^' as DEC writes it. The letter preceding ``' may
-have either case. `G' is not understood, but all other letters (`b i l
-s w') are understood.
-
- Register names understood are `r0 r1 r2 ... r15 ap fp sp pc'. Upper
-and lower case letters are equivalent.
-
- For instance
- tstb *w`$4(r5)
-
- Any expression is permitted in an operand. Operands are comma
-separated.
-
-\1f
-File: as.info, Node: VAX-no, Prev: VAX-operands, Up: Vax-Dependent
-
-8.34.7 Not Supported on VAX
----------------------------
-
-Vax bit fields can not be assembled with `as'. Someone can add the
-required code if they really need it.
-
-\1f
-File: as.info, Node: V850-Dependent, Next: Xtensa-Dependent, Prev: TIC54X-Dependent, Up: Machine Dependencies
-
-8.35 v850 Dependent Features
-============================
-
-* Menu:
-
-* V850 Options:: Options
-* V850 Syntax:: Syntax
-* V850 Floating Point:: Floating Point
-* V850 Directives:: V850 Machine Directives
-* V850 Opcodes:: Opcodes
-
-\1f
-File: as.info, Node: V850 Options, Next: V850 Syntax, Up: V850-Dependent
-
-8.35.1 Options
---------------
-
-`as' supports the following additional command-line options for the
-V850 processor family:
-
-`-wsigned_overflow'
- Causes warnings to be produced when signed immediate values
- overflow the space available for then within their opcodes. By
- default this option is disabled as it is possible to receive
- spurious warnings due to using exact bit patterns as immediate
- constants.
-
-`-wunsigned_overflow'
- Causes warnings to be produced when unsigned immediate values
- overflow the space available for then within their opcodes. By
- default this option is disabled as it is possible to receive
- spurious warnings due to using exact bit patterns as immediate
- constants.
-
-`-mv850'
- Specifies that the assembled code should be marked as being
- targeted at the V850 processor. This allows the linker to detect
- attempts to link such code with code assembled for other
- processors.
-
-`-mv850e'
- Specifies that the assembled code should be marked as being
- targeted at the V850E processor. This allows the linker to detect
- attempts to link such code with code assembled for other
- processors.
-
-`-mv850e1'
- Specifies that the assembled code should be marked as being
- targeted at the V850E1 processor. This allows the linker to
- detect attempts to link such code with code assembled for other
- processors.
-
-`-mv850any'
- Specifies that the assembled code should be marked as being
- targeted at the V850 processor but support instructions that are
- specific to the extended variants of the process. This allows the
- production of binaries that contain target specific code, but
- which are also intended to be used in a generic fashion. For
- example libgcc.a contains generic routines used by the code
- produced by GCC for all versions of the v850 architecture,
- together with support routines only used by the V850E architecture.
-
-`-mrelax'
- Enables relaxation. This allows the .longcall and .longjump pseudo
- ops to be used in the assembler source code. These ops label
- sections of code which are either a long function call or a long
- branch. The assembler will then flag these sections of code and
- the linker will attempt to relax them.
-
-
-\1f
-File: as.info, Node: V850 Syntax, Next: V850 Floating Point, Prev: V850 Options, Up: V850-Dependent
-
-8.35.2 Syntax
--------------
-
-* Menu:
-
-* V850-Chars:: Special Characters
-* V850-Regs:: Register Names
-
-\1f
-File: as.info, Node: V850-Chars, Next: V850-Regs, Up: V850 Syntax
-
-8.35.2.1 Special Characters
-...........................
-
-`#' is the line comment character.
-
-\1f
-File: as.info, Node: V850-Regs, Prev: V850-Chars, Up: V850 Syntax
-
-8.35.2.2 Register Names
-.......................
-
-`as' supports the following names for registers:
-`general register 0'
- r0, zero
-
-`general register 1'
- r1
-
-`general register 2'
- r2, hp
-
-`general register 3'
- r3, sp
-
-`general register 4'
- r4, gp
-
-`general register 5'
- r5, tp
-
-`general register 6'
- r6
-
-`general register 7'
- r7
-
-`general register 8'
- r8
-
-`general register 9'
- r9
-
-`general register 10'
- r10
-
-`general register 11'
- r11
-
-`general register 12'
- r12
-
-`general register 13'
- r13
-
-`general register 14'
- r14
-
-`general register 15'
- r15
-
-`general register 16'
- r16
-
-`general register 17'
- r17
-
-`general register 18'
- r18
-
-`general register 19'
- r19
-
-`general register 20'
- r20
-
-`general register 21'
- r21
-
-`general register 22'
- r22
-
-`general register 23'
- r23
-
-`general register 24'
- r24
-
-`general register 25'
- r25
-
-`general register 26'
- r26
-
-`general register 27'
- r27
-
-`general register 28'
- r28
-
-`general register 29'
- r29
-
-`general register 30'
- r30, ep
-
-`general register 31'
- r31, lp
-
-`system register 0'
- eipc
-
-`system register 1'
- eipsw
-
-`system register 2'
- fepc
-
-`system register 3'
- fepsw
-
-`system register 4'
- ecr
-
-`system register 5'
- psw
-
-`system register 16'
- ctpc
-
-`system register 17'
- ctpsw
-
-`system register 18'
- dbpc
-
-`system register 19'
- dbpsw
-
-`system register 20'
- ctbp
-
-\1f
-File: as.info, Node: V850 Floating Point, Next: V850 Directives, Prev: V850 Syntax, Up: V850-Dependent
-
-8.35.3 Floating Point
----------------------
-
-The V850 family uses IEEE floating-point numbers.
-
-\1f
-File: as.info, Node: V850 Directives, Next: V850 Opcodes, Prev: V850 Floating Point, Up: V850-Dependent
-
-8.35.4 V850 Machine Directives
-------------------------------
-
-`.offset <EXPRESSION>'
- Moves the offset into the current section to the specified amount.
-
-`.section "name", <type>'
- This is an extension to the standard .section directive. It sets
- the current section to be <type> and creates an alias for this
- section called "name".
-
-`.v850'
- Specifies that the assembled code should be marked as being
- targeted at the V850 processor. This allows the linker to detect
- attempts to link such code with code assembled for other
- processors.
-
-`.v850e'
- Specifies that the assembled code should be marked as being
- targeted at the V850E processor. This allows the linker to detect
- attempts to link such code with code assembled for other
- processors.
-
-`.v850e1'
- Specifies that the assembled code should be marked as being
- targeted at the V850E1 processor. This allows the linker to
- detect attempts to link such code with code assembled for other
- processors.
-
-
-\1f
-File: as.info, Node: V850 Opcodes, Prev: V850 Directives, Up: V850-Dependent
-
-8.35.5 Opcodes
---------------
-
-`as' implements all the standard V850 opcodes.
-
- `as' also implements the following pseudo ops:
-
-`hi0()'
- Computes the higher 16 bits of the given expression and stores it
- into the immediate operand field of the given instruction. For
- example:
-
- `mulhi hi0(here - there), r5, r6'
-
- computes the difference between the address of labels 'here' and
- 'there', takes the upper 16 bits of this difference, shifts it
- down 16 bits and then multiplies it by the lower 16 bits in
- register 5, putting the result into register 6.
-
-`lo()'
- Computes the lower 16 bits of the given expression and stores it
- into the immediate operand field of the given instruction. For
- example:
-
- `addi lo(here - there), r5, r6'
-
- computes the difference between the address of labels 'here' and
- 'there', takes the lower 16 bits of this difference and adds it to
- register 5, putting the result into register 6.
-
-`hi()'
- Computes the higher 16 bits of the given expression and then adds
- the value of the most significant bit of the lower 16 bits of the
- expression and stores the result into the immediate operand field
- of the given instruction. For example the following code can be
- used to compute the address of the label 'here' and store it into
- register 6:
-
- `movhi hi(here), r0, r6' `movea lo(here), r6, r6'
-
- The reason for this special behaviour is that movea performs a sign
- extension on its immediate operand. So for example if the address
- of 'here' was 0xFFFFFFFF then without the special behaviour of the
- hi() pseudo-op the movhi instruction would put 0xFFFF0000 into r6,
- then the movea instruction would takes its immediate operand,
- 0xFFFF, sign extend it to 32 bits, 0xFFFFFFFF, and then add it
- into r6 giving 0xFFFEFFFF which is wrong (the fifth nibble is E).
- With the hi() pseudo op adding in the top bit of the lo() pseudo
- op, the movhi instruction actually stores 0 into r6 (0xFFFF + 1 =
- 0x0000), so that the movea instruction stores 0xFFFFFFFF into r6 -
- the right value.
-
-`hilo()'
- Computes the 32 bit value of the given expression and stores it
- into the immediate operand field of the given instruction (which
- must be a mov instruction). For example:
-
- `mov hilo(here), r6'
-
- computes the absolute address of label 'here' and puts the result
- into register 6.
-
-`sdaoff()'
- Computes the offset of the named variable from the start of the
- Small Data Area (whoes address is held in register 4, the GP
- register) and stores the result as a 16 bit signed value in the
- immediate operand field of the given instruction. For example:
-
- `ld.w sdaoff(_a_variable)[gp],r6'
-
- loads the contents of the location pointed to by the label
- '_a_variable' into register 6, provided that the label is located
- somewhere within +/- 32K of the address held in the GP register.
- [Note the linker assumes that the GP register contains a fixed
- address set to the address of the label called '__gp'. This can
- either be set up automatically by the linker, or specifically set
- by using the `--defsym __gp=<value>' command line option].
-
-`tdaoff()'
- Computes the offset of the named variable from the start of the
- Tiny Data Area (whoes address is held in register 30, the EP
- register) and stores the result as a 4,5, 7 or 8 bit unsigned
- value in the immediate operand field of the given instruction.
- For example:
-
- `sld.w tdaoff(_a_variable)[ep],r6'
-
- loads the contents of the location pointed to by the label
- '_a_variable' into register 6, provided that the label is located
- somewhere within +256 bytes of the address held in the EP
- register. [Note the linker assumes that the EP register contains
- a fixed address set to the address of the label called '__ep'.
- This can either be set up automatically by the linker, or
- specifically set by using the `--defsym __ep=<value>' command line
- option].
-
-`zdaoff()'
- Computes the offset of the named variable from address 0 and
- stores the result as a 16 bit signed value in the immediate
- operand field of the given instruction. For example:
-
- `movea zdaoff(_a_variable),zero,r6'
-
- puts the address of the label '_a_variable' into register 6,
- assuming that the label is somewhere within the first 32K of
- memory. (Strictly speaking it also possible to access the last
- 32K of memory as well, as the offsets are signed).
-
-`ctoff()'
- Computes the offset of the named variable from the start of the
- Call Table Area (whoes address is helg in system register 20, the
- CTBP register) and stores the result a 6 or 16 bit unsigned value
- in the immediate field of then given instruction or piece of data.
- For example:
-
- `callt ctoff(table_func1)'
-
- will put the call the function whoes address is held in the call
- table at the location labeled 'table_func1'.
-
-`.longcall `name''
- Indicates that the following sequence of instructions is a long
- call to function `name'. The linker will attempt to shorten this
- call sequence if `name' is within a 22bit offset of the call. Only
- valid if the `-mrelax' command line switch has been enabled.
-
-`.longjump `name''
- Indicates that the following sequence of instructions is a long
- jump to label `name'. The linker will attempt to shorten this code
- sequence if `name' is within a 22bit offset of the jump. Only
- valid if the `-mrelax' command line switch has been enabled.
-
-
- For information on the V850 instruction set, see `V850 Family
-32-/16-Bit single-Chip Microcontroller Architecture Manual' from NEC.
-Ltd.
-
-\1f
-File: as.info, Node: Xtensa-Dependent, Next: Z80-Dependent, Prev: V850-Dependent, Up: Machine Dependencies
-
-8.36 Xtensa Dependent Features
-==============================
-
- This chapter covers features of the GNU assembler that are specific
-to the Xtensa architecture. For details about the Xtensa instruction
-set, please consult the `Xtensa Instruction Set Architecture (ISA)
-Reference Manual'.
-
-* Menu:
-
-* Xtensa Options:: Command-line Options.
-* Xtensa Syntax:: Assembler Syntax for Xtensa Processors.
-* Xtensa Optimizations:: Assembler Optimizations.
-* Xtensa Relaxation:: Other Automatic Transformations.
-* Xtensa Directives:: Directives for Xtensa Processors.
-
-\1f
-File: as.info, Node: Xtensa Options, Next: Xtensa Syntax, Up: Xtensa-Dependent
-
-8.36.1 Command Line Options
----------------------------
-
-The Xtensa version of the GNU assembler supports these special options:
-
-`--text-section-literals | --no-text-section-literals'
- Control the treatment of literal pools. The default is
- `--no-text-section-literals', which places literals in separate
- sections in the output file. This allows the literal pool to be
- placed in a data RAM/ROM. With `--text-section-literals', the
- literals are interspersed in the text section in order to keep
- them as close as possible to their references. This may be
- necessary for large assembly files, where the literals would
- otherwise be out of range of the `L32R' instructions in the text
- section. These options only affect literals referenced via
- PC-relative `L32R' instructions; literals for absolute mode `L32R'
- instructions are handled separately. *Note literal: Literal
- Directive.
-
-`--absolute-literals | --no-absolute-literals'
- Indicate to the assembler whether `L32R' instructions use absolute
- or PC-relative addressing. If the processor includes the absolute
- addressing option, the default is to use absolute `L32R'
- relocations. Otherwise, only the PC-relative `L32R' relocations
- can be used.
-
-`--target-align | --no-target-align'
- Enable or disable automatic alignment to reduce branch penalties
- at some expense in code size. *Note Automatic Instruction
- Alignment: Xtensa Automatic Alignment. This optimization is
- enabled by default. Note that the assembler will always align
- instructions like `LOOP' that have fixed alignment requirements.
-
-`--longcalls | --no-longcalls'
- Enable or disable transformation of call instructions to allow
- calls across a greater range of addresses. *Note Function Call
- Relaxation: Xtensa Call Relaxation. This option should be used
- when call targets can potentially be out of range. It may degrade
- both code size and performance, but the linker can generally
- optimize away the unnecessary overhead when a call ends up within
- range. The default is `--no-longcalls'.
-
-`--transform | --no-transform'
- Enable or disable all assembler transformations of Xtensa
- instructions, including both relaxation and optimization. The
- default is `--transform'; `--no-transform' should only be used in
- the rare cases when the instructions must be exactly as specified
- in the assembly source. Using `--no-transform' causes out of range
- instruction operands to be errors.
-
-`--rename-section OLDNAME=NEWNAME'
- Rename the OLDNAME section to NEWNAME. This option can be used
- multiple times to rename multiple sections.
-
-\1f
-File: as.info, Node: Xtensa Syntax, Next: Xtensa Optimizations, Prev: Xtensa Options, Up: Xtensa-Dependent
-
-8.36.2 Assembler Syntax
------------------------
-
-Block comments are delimited by `/*' and `*/'. End of line comments
-may be introduced with either `#' or `//'.
-
- Instructions consist of a leading opcode or macro name followed by
-whitespace and an optional comma-separated list of operands:
-
- OPCODE [OPERAND, ...]
-
- Instructions must be separated by a newline or semicolon.
-
- FLIX instructions, which bundle multiple opcodes together in a single
-instruction, are specified by enclosing the bundled opcodes inside
-braces:
-
- {
- [FORMAT]
- OPCODE0 [OPERANDS]
- OPCODE1 [OPERANDS]
- OPCODE2 [OPERANDS]
- ...
- }
-
- The opcodes in a FLIX instruction are listed in the same order as the
-corresponding instruction slots in the TIE format declaration.
-Directives and labels are not allowed inside the braces of a FLIX
-instruction. A particular TIE format name can optionally be specified
-immediately after the opening brace, but this is usually unnecessary.
-The assembler will automatically search for a format that can encode the
-specified opcodes, so the format name need only be specified in rare
-cases where there is more than one applicable format and where it
-matters which of those formats is used. A FLIX instruction can also be
-specified on a single line by separating the opcodes with semicolons:
-
- { [FORMAT;] OPCODE0 [OPERANDS]; OPCODE1 [OPERANDS]; OPCODE2 [OPERANDS]; ... }
-
- The assembler can automatically bundle opcodes into FLIX
-instructions. It encodes the opcodes in order, one at a time, choosing
-the smallest format where each opcode can be encoded and filling unused
-instruction slots with no-ops.
-
-* Menu:
-
-* Xtensa Opcodes:: Opcode Naming Conventions.
-* Xtensa Registers:: Register Naming.
-
-\1f
-File: as.info, Node: Xtensa Opcodes, Next: Xtensa Registers, Up: Xtensa Syntax
-
-8.36.2.1 Opcode Names
-.....................
-
-See the `Xtensa Instruction Set Architecture (ISA) Reference Manual'
-for a complete list of opcodes and descriptions of their semantics.
-
- If an opcode name is prefixed with an underscore character (`_'),
-`as' will not transform that instruction in any way. The underscore
-prefix disables both optimization (*note Xtensa Optimizations: Xtensa
-Optimizations.) and relaxation (*note Xtensa Relaxation: Xtensa
-Relaxation.) for that particular instruction. Only use the underscore
-prefix when it is essential to select the exact opcode produced by the
-assembler. Using this feature unnecessarily makes the code less
-efficient by disabling assembler optimization and less flexible by
-disabling relaxation.
-
- Note that this special handling of underscore prefixes only applies
-to Xtensa opcodes, not to either built-in macros or user-defined macros.
-When an underscore prefix is used with a macro (e.g., `_MOV'), it
-refers to a different macro. The assembler generally provides built-in
-macros both with and without the underscore prefix, where the underscore
-versions behave as if the underscore carries through to the instructions
-in the macros. For example, `_MOV' may expand to `_MOV.N'.
-
- The underscore prefix only applies to individual instructions, not to
-series of instructions. For example, if a series of instructions have
-underscore prefixes, the assembler will not transform the individual
-instructions, but it may insert other instructions between them (e.g.,
-to align a `LOOP' instruction). To prevent the assembler from
-modifying a series of instructions as a whole, use the `no-transform'
-directive. *Note transform: Transform Directive.
-
-\1f
-File: as.info, Node: Xtensa Registers, Prev: Xtensa Opcodes, Up: Xtensa Syntax
-
-8.36.2.2 Register Names
-.......................
-
-The assembly syntax for a register file entry is the "short" name for a
-TIE register file followed by the index into that register file. For
-example, the general-purpose `AR' register file has a short name of
-`a', so these registers are named `a0'...`a15'. As a special feature,
-`sp' is also supported as a synonym for `a1'. Additional registers may
-be added by processor configuration options and by designer-defined TIE
-extensions. An initial `$' character is optional in all register names.
-
-\1f
-File: as.info, Node: Xtensa Optimizations, Next: Xtensa Relaxation, Prev: Xtensa Syntax, Up: Xtensa-Dependent
-
-8.36.3 Xtensa Optimizations
----------------------------
-
-The optimizations currently supported by `as' are generation of density
-instructions where appropriate and automatic branch target alignment.
-
-* Menu:
-
-* Density Instructions:: Using Density Instructions.
-* Xtensa Automatic Alignment:: Automatic Instruction Alignment.
-
-\1f
-File: as.info, Node: Density Instructions, Next: Xtensa Automatic Alignment, Up: Xtensa Optimizations
-
-8.36.3.1 Using Density Instructions
-...................................
-
-The Xtensa instruction set has a code density option that provides
-16-bit versions of some of the most commonly used opcodes. Use of these
-opcodes can significantly reduce code size. When possible, the
-assembler automatically translates instructions from the core Xtensa
-instruction set into equivalent instructions from the Xtensa code
-density option. This translation can be disabled by using underscore
-prefixes (*note Opcode Names: Xtensa Opcodes.), by using the
-`--no-transform' command-line option (*note Command Line Options:
-Xtensa Options.), or by using the `no-transform' directive (*note
-transform: Transform Directive.).
-
- It is a good idea _not_ to use the density instructions directly.
-The assembler will automatically select dense instructions where
-possible. If you later need to use an Xtensa processor without the code
-density option, the same assembly code will then work without
-modification.
-
-\1f
-File: as.info, Node: Xtensa Automatic Alignment, Prev: Density Instructions, Up: Xtensa Optimizations
-
-8.36.3.2 Automatic Instruction Alignment
-........................................
-
-The Xtensa assembler will automatically align certain instructions, both
-to optimize performance and to satisfy architectural requirements.
-
- As an optimization to improve performance, the assembler attempts to
-align branch targets so they do not cross instruction fetch boundaries.
-(Xtensa processors can be configured with either 32-bit or 64-bit
-instruction fetch widths.) An instruction immediately following a call
-is treated as a branch target in this context, because it will be the
-target of a return from the call. This alignment has the potential to
-reduce branch penalties at some expense in code size. The assembler
-will not attempt to align labels with the prefixes `.Ln' and `.LM',
-since these labels are used for debugging information and are not
-typically branch targets. This optimization is enabled by default.
-You can disable it with the `--no-target-align' command-line option
-(*note Command Line Options: Xtensa Options.).
-
- The target alignment optimization is done without adding instructions
-that could increase the execution time of the program. If there are
-density instructions in the code preceding a target, the assembler can
-change the target alignment by widening some of those instructions to
-the equivalent 24-bit instructions. Extra bytes of padding can be
-inserted immediately following unconditional jump and return
-instructions. This approach is usually successful in aligning many,
-but not all, branch targets.
-
- The `LOOP' family of instructions must be aligned such that the
-first instruction in the loop body does not cross an instruction fetch
-boundary (e.g., with a 32-bit fetch width, a `LOOP' instruction must be
-on either a 1 or 2 mod 4 byte boundary). The assembler knows about
-this restriction and inserts the minimal number of 2 or 3 byte no-op
-instructions to satisfy it. When no-op instructions are added, any
-label immediately preceding the original loop will be moved in order to
-refer to the loop instruction, not the newly generated no-op
-instruction. To preserve binary compatibility across processors with
-different fetch widths, the assembler conservatively assumes a 32-bit
-fetch width when aligning `LOOP' instructions (except if the first
-instruction in the loop is a 64-bit instruction).
-
- Previous versions of the assembler automatically aligned `ENTRY'
-instructions to 4-byte boundaries, but that alignment is now the
-programmer's responsibility.
-
-\1f
-File: as.info, Node: Xtensa Relaxation, Next: Xtensa Directives, Prev: Xtensa Optimizations, Up: Xtensa-Dependent
-
-8.36.4 Xtensa Relaxation
-------------------------
-
-When an instruction operand is outside the range allowed for that
-particular instruction field, `as' can transform the code to use a
-functionally-equivalent instruction or sequence of instructions. This
-process is known as "relaxation". This is typically done for branch
-instructions because the distance of the branch targets is not known
-until assembly-time. The Xtensa assembler offers branch relaxation and
-also extends this concept to function calls, `MOVI' instructions and
-other instructions with immediate fields.
-
-* Menu:
-
-* Xtensa Branch Relaxation:: Relaxation of Branches.
-* Xtensa Call Relaxation:: Relaxation of Function Calls.
-* Xtensa Immediate Relaxation:: Relaxation of other Immediate Fields.
-
-\1f
-File: as.info, Node: Xtensa Branch Relaxation, Next: Xtensa Call Relaxation, Up: Xtensa Relaxation
-
-8.36.4.1 Conditional Branch Relaxation
-......................................
-
-When the target of a branch is too far away from the branch itself,
-i.e., when the offset from the branch to the target is too large to fit
-in the immediate field of the branch instruction, it may be necessary to
-replace the branch with a branch around a jump. For example,
-
- beqz a2, L
-
- may result in:
-
- bnez.n a2, M
- j L
- M:
-
- (The `BNEZ.N' instruction would be used in this example only if the
-density option is available. Otherwise, `BNEZ' would be used.)
-
- This relaxation works well because the unconditional jump instruction
-has a much larger offset range than the various conditional branches.
-However, an error will occur if a branch target is beyond the range of a
-jump instruction. `as' cannot relax unconditional jumps. Similarly,
-an error will occur if the original input contains an unconditional
-jump to a target that is out of range.
-
- Branch relaxation is enabled by default. It can be disabled by using
-underscore prefixes (*note Opcode Names: Xtensa Opcodes.), the
-`--no-transform' command-line option (*note Command Line Options:
-Xtensa Options.), or the `no-transform' directive (*note transform:
-Transform Directive.).
-
-\1f
-File: as.info, Node: Xtensa Call Relaxation, Next: Xtensa Immediate Relaxation, Prev: Xtensa Branch Relaxation, Up: Xtensa Relaxation
-
-8.36.4.2 Function Call Relaxation
-.................................
-
-Function calls may require relaxation because the Xtensa immediate call
-instructions (`CALL0', `CALL4', `CALL8' and `CALL12') provide a
-PC-relative offset of only 512 Kbytes in either direction. For larger
-programs, it may be necessary to use indirect calls (`CALLX0',
-`CALLX4', `CALLX8' and `CALLX12') where the target address is specified
-in a register. The Xtensa assembler can automatically relax immediate
-call instructions into indirect call instructions. This relaxation is
-done by loading the address of the called function into the callee's
-return address register and then using a `CALLX' instruction. So, for
-example:
-
- call8 func
-
- might be relaxed to:
-
- .literal .L1, func
- l32r a8, .L1
- callx8 a8
-
- Because the addresses of targets of function calls are not generally
-known until link-time, the assembler must assume the worst and relax all
-the calls to functions in other source files, not just those that really
-will be out of range. The linker can recognize calls that were
-unnecessarily relaxed, and it will remove the overhead introduced by the
-assembler for those cases where direct calls are sufficient.
-
- Call relaxation is disabled by default because it can have a negative
-effect on both code size and performance, although the linker can
-usually eliminate the unnecessary overhead. If a program is too large
-and some of the calls are out of range, function call relaxation can be
-enabled using the `--longcalls' command-line option or the `longcalls'
-directive (*note longcalls: Longcalls Directive.).
-
-\1f
-File: as.info, Node: Xtensa Immediate Relaxation, Prev: Xtensa Call Relaxation, Up: Xtensa Relaxation
-
-8.36.4.3 Other Immediate Field Relaxation
-.........................................
-
-The assembler normally performs the following other relaxations. They
-can be disabled by using underscore prefixes (*note Opcode Names:
-Xtensa Opcodes.), the `--no-transform' command-line option (*note
-Command Line Options: Xtensa Options.), or the `no-transform' directive
-(*note transform: Transform Directive.).
-
- The `MOVI' machine instruction can only materialize values in the
-range from -2048 to 2047. Values outside this range are best
-materialized with `L32R' instructions. Thus:
-
- movi a0, 100000
-
- is assembled into the following machine code:
-
- .literal .L1, 100000
- l32r a0, .L1
-
- The `L8UI' machine instruction can only be used with immediate
-offsets in the range from 0 to 255. The `L16SI' and `L16UI' machine
-instructions can only be used with offsets from 0 to 510. The `L32I'
-machine instruction can only be used with offsets from 0 to 1020. A
-load offset outside these ranges can be materialized with an `L32R'
-instruction if the destination register of the load is different than
-the source address register. For example:
-
- l32i a1, a0, 2040
-
- is translated to:
-
- .literal .L1, 2040
- l32r a1, .L1
- addi a1, a0, a1
- l32i a1, a1, 0
-
-If the load destination and source address register are the same, an
-out-of-range offset causes an error.
-
- The Xtensa `ADDI' instruction only allows immediate operands in the
-range from -128 to 127. There are a number of alternate instruction
-sequences for the `ADDI' operation. First, if the immediate is 0, the
-`ADDI' will be turned into a `MOV.N' instruction (or the equivalent
-`OR' instruction if the code density option is not available). If the
-`ADDI' immediate is outside of the range -128 to 127, but inside the
-range -32896 to 32639, an `ADDMI' instruction or `ADDMI'/`ADDI'
-sequence will be used. Finally, if the immediate is outside of this
-range and a free register is available, an `L32R'/`ADD' sequence will
-be used with a literal allocated from the literal pool.
-
- For example:
-
- addi a5, a6, 0
- addi a5, a6, 512
- addi a5, a6, 513
- addi a5, a6, 50000
-
- is assembled into the following:
-
- .literal .L1, 50000
- mov.n a5, a6
- addmi a5, a6, 0x200
- addmi a5, a6, 0x200
- addi a5, a5, 1
- l32r a5, .L1
- add a5, a6, a5
-
-\1f
-File: as.info, Node: Xtensa Directives, Prev: Xtensa Relaxation, Up: Xtensa-Dependent
-
-8.36.5 Directives
------------------
-
-The Xtensa assembler supports a region-based directive syntax:
-
- .begin DIRECTIVE [OPTIONS]
- ...
- .end DIRECTIVE
-
- All the Xtensa-specific directives that apply to a region of code use
-this syntax.
-
- The directive applies to code between the `.begin' and the `.end'.
-The state of the option after the `.end' reverts to what it was before
-the `.begin'. A nested `.begin'/`.end' region can further change the
-state of the directive without having to be aware of its outer state.
-For example, consider:
-
- .begin no-transform
- L: add a0, a1, a2
- .begin transform
- M: add a0, a1, a2
- .end transform
- N: add a0, a1, a2
- .end no-transform
-
- The `ADD' opcodes at `L' and `N' in the outer `no-transform' region
-both result in `ADD' machine instructions, but the assembler selects an
-`ADD.N' instruction for the `ADD' at `M' in the inner `transform'
-region.
-
- The advantage of this style is that it works well inside macros
-which can preserve the context of their callers.
-
- The following directives are available:
-
-* Menu:
-
-* Schedule Directive:: Enable instruction scheduling.
-* Longcalls Directive:: Use Indirect Calls for Greater Range.
-* Transform Directive:: Disable All Assembler Transformations.
-* Literal Directive:: Intermix Literals with Instructions.
-* Literal Position Directive:: Specify Inline Literal Pool Locations.
-* Literal Prefix Directive:: Specify Literal Section Name Prefix.
-* Absolute Literals Directive:: Control PC-Relative vs. Absolute Literals.
-
-\1f
-File: as.info, Node: Schedule Directive, Next: Longcalls Directive, Up: Xtensa Directives
-
-8.36.5.1 schedule
-.................
-
-The `schedule' directive is recognized only for compatibility with
-Tensilica's assembler.
-
- .begin [no-]schedule
- .end [no-]schedule
-
- This directive is ignored and has no effect on `as'.
-
-\1f
-File: as.info, Node: Longcalls Directive, Next: Transform Directive, Prev: Schedule Directive, Up: Xtensa Directives
-
-8.36.5.2 longcalls
-..................
-
-The `longcalls' directive enables or disables function call relaxation.
-*Note Function Call Relaxation: Xtensa Call Relaxation.
-
- .begin [no-]longcalls
- .end [no-]longcalls
-
- Call relaxation is disabled by default unless the `--longcalls'
-command-line option is specified. The `longcalls' directive overrides
-the default determined by the command-line options.
-
-\1f
-File: as.info, Node: Transform Directive, Next: Literal Directive, Prev: Longcalls Directive, Up: Xtensa Directives
-
-8.36.5.3 transform
-..................
-
-This directive enables or disables all assembler transformation,
-including relaxation (*note Xtensa Relaxation: Xtensa Relaxation.) and
-optimization (*note Xtensa Optimizations: Xtensa Optimizations.).
-
- .begin [no-]transform
- .end [no-]transform
-
- Transformations are enabled by default unless the `--no-transform'
-option is used. The `transform' directive overrides the default
-determined by the command-line options. An underscore opcode prefix,
-disabling transformation of that opcode, always takes precedence over
-both directives and command-line flags.
-
-\1f
-File: as.info, Node: Literal Directive, Next: Literal Position Directive, Prev: Transform Directive, Up: Xtensa Directives
-
-8.36.5.4 literal
-................
-
-The `.literal' directive is used to define literal pool data, i.e.,
-read-only 32-bit data accessed via `L32R' instructions.
-
- .literal LABEL, VALUE[, VALUE...]
-
- This directive is similar to the standard `.word' directive, except
-that the actual location of the literal data is determined by the
-assembler and linker, not by the position of the `.literal' directive.
-Using this directive gives the assembler freedom to locate the literal
-data in the most appropriate place and possibly to combine identical
-literals. For example, the code:
-
- entry sp, 40
- .literal .L1, sym
- l32r a4, .L1
-
- can be used to load a pointer to the symbol `sym' into register
-`a4'. The value of `sym' will not be placed between the `ENTRY' and
-`L32R' instructions; instead, the assembler puts the data in a literal
-pool.
-
- Literal pools are placed by default in separate literal sections;
-however, when using the `--text-section-literals' option (*note Command
-Line Options: Xtensa Options.), the literal pools for PC-relative mode
-`L32R' instructions are placed in the current section.(1) These text
-section literal pools are created automatically before `ENTRY'
-instructions and manually after `.literal_position' directives (*note
-literal_position: Literal Position Directive.). If there are no
-preceding `ENTRY' instructions, explicit `.literal_position' directives
-must be used to place the text section literal pools; otherwise, `as'
-will report an error.
-
- When literals are placed in separate sections, the literal section
-names are derived from the names of the sections where the literals are
-defined. The base literal section names are `.literal' for PC-relative
-mode `L32R' instructions and `.lit4' for absolute mode `L32R'
-instructions (*note absolute-literals: Absolute Literals Directive.).
-These base names are used for literals defined in the default `.text'
-section. For literals defined in other sections or within the scope of
-a `literal_prefix' directive (*note literal_prefix: Literal Prefix
-Directive.), the following rules determine the literal section name:
-
- 1. If the current section is a member of a section group, the literal
- section name includes the group name as a suffix to the base
- `.literal' or `.lit4' name, with a period to separate the base
- name and group name. The literal section is also made a member of
- the group.
-
- 2. If the current section name (or `literal_prefix' value) begins with
- "`.gnu.linkonce.KIND.'", the literal section name is formed by
- replacing "`.KIND'" with the base `.literal' or `.lit4' name. For
- example, for literals defined in a section named
- `.gnu.linkonce.t.func', the literal section will be
- `.gnu.linkonce.literal.func' or `.gnu.linkonce.lit4.func'.
-
- 3. If the current section name (or `literal_prefix' value) ends with
- `.text', the literal section name is formed by replacing that
- suffix with the base `.literal' or `.lit4' name. For example, for
- literals defined in a section named `.iram0.text', the literal
- section will be `.iram0.literal' or `.iram0.lit4'.
-
- 4. If none of the preceding conditions apply, the literal section
- name is formed by adding the base `.literal' or `.lit4' name as a
- suffix to the current section name (or `literal_prefix' value).
-
- ---------- Footnotes ----------
-
- (1) Literals for the `.init' and `.fini' sections are always placed
-in separate sections, even when `--text-section-literals' is enabled.
-
-\1f
-File: as.info, Node: Literal Position Directive, Next: Literal Prefix Directive, Prev: Literal Directive, Up: Xtensa Directives
-
-8.36.5.5 literal_position
-.........................
-
-When using `--text-section-literals' to place literals inline in the
-section being assembled, the `.literal_position' directive can be used
-to mark a potential location for a literal pool.
-
- .literal_position
-
- The `.literal_position' directive is ignored when the
-`--text-section-literals' option is not used or when `L32R'
-instructions use the absolute addressing mode.
-
- The assembler will automatically place text section literal pools
-before `ENTRY' instructions, so the `.literal_position' directive is
-only needed to specify some other location for a literal pool. You may
-need to add an explicit jump instruction to skip over an inline literal
-pool.
-
- For example, an interrupt vector does not begin with an `ENTRY'
-instruction so the assembler will be unable to automatically find a good
-place to put a literal pool. Moreover, the code for the interrupt
-vector must be at a specific starting address, so the literal pool
-cannot come before the start of the code. The literal pool for the
-vector must be explicitly positioned in the middle of the vector (before
-any uses of the literals, due to the negative offsets used by
-PC-relative `L32R' instructions). The `.literal_position' directive
-can be used to do this. In the following code, the literal for `M'
-will automatically be aligned correctly and is placed after the
-unconditional jump.
-
- .global M
- code_start:
- j continue
- .literal_position
- .align 4
- continue:
- movi a4, M
-
-\1f
-File: as.info, Node: Literal Prefix Directive, Next: Absolute Literals Directive, Prev: Literal Position Directive, Up: Xtensa Directives
-
-8.36.5.6 literal_prefix
-.......................
-
-The `literal_prefix' directive allows you to override the default
-literal section names, which are derived from the names of the sections
-where the literals are defined.
-
- .begin literal_prefix [NAME]
- .end literal_prefix
-
- For literals defined within the delimited region, the literal section
-names are derived from the NAME argument instead of the name of the
-current section. The rules used to derive the literal section names do
-not change. *Note literal: Literal Directive. If the NAME argument is
-omitted, the literal sections revert to the defaults. This directive
-has no effect when using the `--text-section-literals' option (*note
-Command Line Options: Xtensa Options.).
-
-\1f
-File: as.info, Node: Absolute Literals Directive, Prev: Literal Prefix Directive, Up: Xtensa Directives
-
-8.36.5.7 absolute-literals
-..........................
-
-The `absolute-literals' and `no-absolute-literals' directives control
-the absolute vs. PC-relative mode for `L32R' instructions. These are
-relevant only for Xtensa configurations that include the absolute
-addressing option for `L32R' instructions.
-
- .begin [no-]absolute-literals
- .end [no-]absolute-literals
-
- These directives do not change the `L32R' mode--they only cause the
-assembler to emit the appropriate kind of relocation for `L32R'
-instructions and to place the literal values in the appropriate section.
-To change the `L32R' mode, the program must write the `LITBASE' special
-register. It is the programmer's responsibility to keep track of the
-mode and indicate to the assembler which mode is used in each region of
-code.
-
- If the Xtensa configuration includes the absolute `L32R' addressing
-option, the default is to assume absolute `L32R' addressing unless the
-`--no-absolute-literals' command-line option is specified. Otherwise,
-the default is to assume PC-relative `L32R' addressing. The
-`absolute-literals' directive can then be used to override the default
-determined by the command-line options.
-
-\1f
-File: as.info, Node: Reporting Bugs, Next: Acknowledgements, Prev: Machine Dependencies, Up: Top
-
-9 Reporting Bugs
-****************
-
-Your bug reports play an essential role in making `as' reliable.
-
- 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 `as' work
-better. Bug reports are your contribution to the maintenance of `as'.
-
- In order for a bug report to serve its purpose, you must include the
-information that enables us to fix the bug.
-
-* Menu:
-
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-
-\1f
-File: as.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs
-
-9.1 Have You Found a Bug?
-=========================
-
-If you are not sure whether you have found a bug, here are some
-guidelines:
-
- * If the assembler gets a fatal signal, for any input whatever, that
- is a `as' bug. Reliable assemblers never crash.
-
- * If `as' produces an error message for valid input, that is a bug.
-
- * If `as' does not produce an error message for invalid input, that
- is a bug. However, you should note that your idea of "invalid
- input" might be our idea of "an extension" or "support for
- traditional practice".
-
- * If you are an experienced user of assemblers, your suggestions for
- improvement of `as' are welcome in any case.
-
-\1f
-File: as.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
-
-9.2 How to Report Bugs
-======================
-
-A number of companies and individuals offer support for GNU products.
-If you obtained `as' from a support organization, we recommend you
-contact that organization first.
-
- You can find contact information for many support companies and
-individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
-
- In any event, we also recommend that you send bug reports for `as'
-to `http://www.sourceware.org/bugzilla/'.
-
- The fundamental principle of reporting bugs usefully is this:
-*report all the facts*. If you are not sure whether to state a fact or
-leave it out, state it!
-
- 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.
-
- 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.
-
- Sometimes people give a few sketchy facts and ask, "Does this ring a
-bell?" 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.
-
- To enable us to fix the bug, you should include all these things:
-
- * The version of `as'. `as' announces it if you start it with the
- `--version' argument.
-
- Without this, we will not know whether there is any point in
- looking for the bug in the current version of `as'.
-
- * Any patches you may have applied to the `as' source.
-
- * The type of machine you are using, and the operating system name
- and version number.
-
- * What compiler (and its version) was used to compile `as'--e.g.
- "`gcc-2.7'".
-
- * 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.
-
- If we were to try to guess the arguments, we would probably guess
- wrong and then we might not encounter the bug.
-
- * 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 `-S'
- option. If you are using `gcc', use the options `-v
- --save-temps'; this will save the assembler source in a file with
- an extension of `.s', and also show you exactly how `as' is being
- run.
-
- * A description of what behavior you observe that you believe is
- incorrect. For example, "It gets a fatal signal."
-
- Of course, if the bug is that `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.
-
- 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 `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.
-
- * If you wish to suggest changes to the `as' source, send us context
- diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
- Always send diffs from the old file to the new file. If you even
- discuss something in the `as' source, refer to it by context, not
- by line number.
-
- The line numbers in our development sources will not match those
- in your sources. Your line numbers would convey no useful
- information to us.
-
- Here are some things that are not necessary:
-
- * A description of the envelope of the bug.
-
- 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.
-
- 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.
-
- Of course, if you can find a simpler example to report _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.
-
- 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.
-
- * A patch for the bug.
-
- 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.
-
- Sometimes with a program as complicated as `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.
-
- 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.
-
- * A guess about what the bug is or what it depends on.
-
- Such guesses are usually wrong. Even we cannot guess right about
- such things without first using the debugger to find the facts.
-
-\1f
-File: as.info, Node: Acknowledgements, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top
-
-10 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 `raeburn@cygnus.com').
-
- Dean Elsner wrote the original GNU assembler for the VAX.(1)
-
- 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 `messages.c',
-`input-file.c', `write.c'.
-
- 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 "know" assertions and made them work,
-much other reorganization, cleanup, and lint.
-
- Ken Raeburn wrote the high-level BFD interface code to replace most
-of the code in format-specific I/O modules.
-
- The original VMS support was contributed by David L. Kashtan. Eric
-Youngdale has done much work with it since.
-
- The Intel 80386 machine description was written by Eliot Dresselhaus.
-
- Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
-
- The Motorola 88k machine description was contributed by Devon Bowen
-of Buffalo University and Torbjorn Granlund of the Swedish Institute of
-Computer Science.
-
- Keith Knowles at the Open Software Foundation wrote the original
-MIPS back end (`tc-mips.c', `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.
-
- 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.
-
- John Gilmore built the AMD 29000 support, added `.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., `jsr'), while
-synthetic instructions remained shrinkable (`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.
-
- 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.
-
- Steve Chamberlain made GAS able to generate listings.
-
- Hewlett-Packard contributed support for the HP9000/300.
-
- 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.
-
- 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).
-
- Linas Vepstas added GAS support for the ESA/390 "IBM 370"
-architecture.
-
- Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote
-GAS and BFD support for openVMS/Alpha.
-
- Timothy Wall, Michael Hayes, and Greg Smart contributed to the
-various tic* flavors.
-
- David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from
-Tensilica, Inc. added support for Xtensa processors.
-
- Several engineers at Cygnus Support have also provided many small
-bug fixes and configuration enhancements.
-
- 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.
-
- ---------- Footnotes ----------
-
- (1) Any more details?
-
-\1f
-File: as.info, Node: GNU Free Documentation License, Next: AS Index, Prev: Acknowledgements, Up: Top
-
-Appendix A GNU Free Documentation License
-*****************************************
-
- Version 1.1, March 2000
-
- Copyright (C) 2000, 2003 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.
-
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone
- the effective freedom to copy and redistribute it, with or without
- modifying it, either commercially or noncommercially. Secondarily,
- this License preserves for the author and publisher a way to get
- credit for their work, while not being considered responsible for
- modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to
- software manuals; it can be used for any textual work, regardless
- of subject matter or whether it is published as a printed book.
- We recommend this License principally for works whose purpose is
- instruction or reference.
-
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be distributed
- under the terms of this License. The "Document", below, refers to
- any such manual or work. Any member of the public is a licensee,
- and is addressed as "you."
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter
- section of the Document that deals exclusively with the
- relationship of the publishers or authors of the Document to the
- Document's overall subject (or to related matters) and contains
- nothing that could fall directly within that overall subject.
- (For example, if the Document is in part a textbook of
- mathematics, a Secondary Section may not explain any mathematics.)
- The relationship could be a matter of historical connection with
- the subject or with related matters, or of legal, commercial,
- philosophical, ethical or political position regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, whose contents can be viewed and edited directly
- and straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup has been designed
- to thwart or discourage subsequent modification by readers is not
- Transparent. A copy that is not "Transparent" is called "Opaque."
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human modification.
- Opaque formats include PostScript, PDF, proprietary formats that
- can be read and edited only by proprietary word processors, SGML
- or XML for which the DTD and/or processing tools are not generally
- available, and the machine-generated HTML produced by some word
- processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, "Title
- Page" means the text near the most prominent appearance of the
- work's title, preceding the beginning of the body of the text.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow
- the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more than
- 100, and the Document's license notice requires Cover Texts, you
- must enclose the copies in covers that carry, clearly and legibly,
- all these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the
- title equally prominent and visible. You may add other material
- on the covers in addition. Copying with changes limited to the
- covers, as long as they preserve the title of the Document and
- satisfy these conditions, can be treated as verbatim copying in
- other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy, or
- state in or with each Opaque copy a publicly-accessible
- computer-network location containing a complete Transparent copy
- of the Document, free of added material, which the general
- network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with
- the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version to
- whoever possesses a copy of it. In addition, you must do these
- things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title
- as a previous version if the original publisher of that version
- gives permission.
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it
- has less than five).
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page.
- If there is no section entitled "History" in the Document,
- create one stating the title, year, authors, and publisher of
- the Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in the
- "History" section. You may omit a network location for a work
- that was published at least four years before the Document
- itself, or if the original publisher of the version it refers
- to gives permission.
- K. In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
- M. Delete any section entitled "Endorsements." Such a section
- may not be included in the Modified Version.
- N. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do this,
- add their titles to the list of Invariant Sections in the Modified
- Version's license notice. These titles must be distinct from any
- other section titles.
-
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties-for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition
- of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If the
- Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same entity
- you are acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section
- entitled "History"; likewise combine any sections entitled
- "Acknowledgements", and any sections entitled "Dedications." You
- must delete all sections entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow
- this License in all other respects regarding verbatim copying of
- that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of
- a storage or distribution medium, does not as a whole count as a
- Modified Version of the Document, provided no compilation
- copyright is claimed for the compilation. Such a compilation is
- called an "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document, on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may be
- placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License provided that you also include the
- original English version of this License. In case of a
- disagreement between the translation and the original English
- version of this License, the original English version will prevail.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-====================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.1
- or any later version published by the Free Software Foundation;
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License."
-
- If you have no Invariant Sections, write "with no Invariant Sections"
-instead of saying which ones are invariant. If you have no Front-Cover
-Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
-LIST"; likewise for Back-Cover Texts.
-
- If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License, to
-permit their use in free software.
-
-\1f
-File: as.info, Node: AS Index, Prev: GNU Free Documentation License, Up: Top
-
-AS Index
-********
-
-\0\b[index\0\b]
-* Menu:
-
-* #: Comments. (line 38)
-* #APP: Preprocessing. (line 27)
-* #NO_APP: Preprocessing. (line 27)
-* $ in symbol names <1>: SH64-Chars. (line 10)
-* $ in symbol names <2>: SH-Chars. (line 10)
-* $ in symbol names <3>: D30V-Chars. (line 63)
-* $ in symbol names: D10V-Chars. (line 46)
-* $a: ARM Mapping Symbols. (line 9)
-* $acos math builtin, TIC54X: TIC54X-Builtins. (line 10)
-* $asin math builtin, TIC54X: TIC54X-Builtins. (line 13)
-* $atan math builtin, TIC54X: TIC54X-Builtins. (line 16)
-* $atan2 math builtin, TIC54X: TIC54X-Builtins. (line 19)
-* $ceil math builtin, TIC54X: TIC54X-Builtins. (line 22)
-* $cos math builtin, TIC54X: TIC54X-Builtins. (line 28)
-* $cosh math builtin, TIC54X: TIC54X-Builtins. (line 25)
-* $cvf math builtin, TIC54X: TIC54X-Builtins. (line 31)
-* $cvi math builtin, TIC54X: TIC54X-Builtins. (line 34)
-* $d: ARM Mapping Symbols. (line 15)
-* $exp math builtin, TIC54X: TIC54X-Builtins. (line 37)
-* $fabs math builtin, TIC54X: TIC54X-Builtins. (line 40)
-* $firstch subsym builtin, TIC54X: TIC54X-Macros. (line 26)
-* $floor math builtin, TIC54X: TIC54X-Builtins. (line 43)
-* $fmod math builtin, TIC54X: TIC54X-Builtins. (line 47)
-* $int math builtin, TIC54X: TIC54X-Builtins. (line 50)
-* $iscons subsym builtin, TIC54X: TIC54X-Macros. (line 43)
-* $isdefed subsym builtin, TIC54X: TIC54X-Macros. (line 34)
-* $ismember subsym builtin, TIC54X: TIC54X-Macros. (line 38)
-* $isname subsym builtin, TIC54X: TIC54X-Macros. (line 47)
-* $isreg subsym builtin, TIC54X: TIC54X-Macros. (line 50)
-* $lastch subsym builtin, TIC54X: TIC54X-Macros. (line 30)
-* $ldexp math builtin, TIC54X: TIC54X-Builtins. (line 53)
-* $log math builtin, TIC54X: TIC54X-Builtins. (line 59)
-* $log10 math builtin, TIC54X: TIC54X-Builtins. (line 56)
-* $max math builtin, TIC54X: TIC54X-Builtins. (line 62)
-* $min math builtin, TIC54X: TIC54X-Builtins. (line 65)
-* $pow math builtin, TIC54X: TIC54X-Builtins. (line 68)
-* $round math builtin, TIC54X: TIC54X-Builtins. (line 71)
-* $sgn math builtin, TIC54X: TIC54X-Builtins. (line 74)
-* $sin math builtin, TIC54X: TIC54X-Builtins. (line 77)
-* $sinh math builtin, TIC54X: TIC54X-Builtins. (line 80)
-* $sqrt math builtin, TIC54X: TIC54X-Builtins. (line 83)
-* $structacc subsym builtin, TIC54X: TIC54X-Macros. (line 57)
-* $structsz subsym builtin, TIC54X: TIC54X-Macros. (line 54)
-* $symcmp subsym builtin, TIC54X: TIC54X-Macros. (line 23)
-* $symlen subsym builtin, TIC54X: TIC54X-Macros. (line 20)
-* $t: ARM Mapping Symbols. (line 12)
-* $tan math builtin, TIC54X: TIC54X-Builtins. (line 86)
-* $tanh math builtin, TIC54X: TIC54X-Builtins. (line 89)
-* $trunc math builtin, TIC54X: TIC54X-Builtins. (line 92)
-* -+ option, VAX/VMS: VAX-Opts. (line 71)
-* --: Command Line. (line 10)
-* --32 option, i386: i386-Options. (line 8)
-* --32 option, x86-64: i386-Options. (line 8)
-* --64 option, i386: i386-Options. (line 8)
-* --64 option, x86-64: i386-Options. (line 8)
-* --absolute-literals: Xtensa Options. (line 23)
-* --allow-reg-prefix: SH Options. (line 9)
-* --alternate: alternate. (line 6)
-* --base-size-default-16: M68K-Opts. (line 71)
-* --base-size-default-32: M68K-Opts. (line 71)
-* --big: SH Options. (line 9)
-* --bitwise-or option, M680x0: M68K-Opts. (line 64)
-* --disp-size-default-16: M68K-Opts. (line 80)
-* --disp-size-default-32: M68K-Opts. (line 80)
-* --divide option, i386: i386-Options. (line 24)
-* --dsp: SH Options. (line 9)
-* --emulation=crisaout command line option, CRIS: CRIS-Opts. (line 9)
-* --emulation=criself command line option, CRIS: CRIS-Opts. (line 9)
-* --enforce-aligned-data: Sparc-Aligned-Data. (line 11)
-* --fatal-warnings: W. (line 16)
-* --fixed-special-register-names command line option, MMIX: MMIX-Opts.
- (line 8)
-* --force-long-branches: M68HC11-Opts. (line 69)
-* --generate-example: M68HC11-Opts. (line 86)
-* --globalize-symbols command line option, MMIX: MMIX-Opts. (line 12)
-* --gnu-syntax command line option, MMIX: MMIX-Opts. (line 16)
-* --hash-size=NUMBER: Overview. (line 307)
-* --linker-allocated-gregs command line option, MMIX: MMIX-Opts.
- (line 67)
-* --listing-cont-lines: listing. (line 34)
-* --listing-lhs-width: listing. (line 16)
-* --listing-lhs-width2: listing. (line 21)
-* --listing-rhs-width: listing. (line 28)
-* --little: SH Options. (line 9)
-* --longcalls: Xtensa Options. (line 37)
-* --march=ARCHITECTURE command line option, CRIS: CRIS-Opts. (line 33)
-* --MD: MD. (line 6)
-* --mul-bug-abort command line option, CRIS: CRIS-Opts. (line 61)
-* --no-absolute-literals: Xtensa Options. (line 23)
-* --no-expand command line option, MMIX: MMIX-Opts. (line 31)
-* --no-longcalls: Xtensa Options. (line 37)
-* --no-merge-gregs command line option, MMIX: MMIX-Opts. (line 36)
-* --no-mul-bug-abort command line option, CRIS: CRIS-Opts. (line 61)
-* --no-predefined-syms command line option, MMIX: MMIX-Opts. (line 22)
-* --no-pushj-stubs command line option, MMIX: MMIX-Opts. (line 54)
-* --no-stubs command line option, MMIX: MMIX-Opts. (line 54)
-* --no-target-align: Xtensa Options. (line 30)
-* --no-text-section-literals: Xtensa Options. (line 9)
-* --no-transform: Xtensa Options. (line 46)
-* --no-underscore command line option, CRIS: CRIS-Opts. (line 15)
-* --no-warn: W. (line 11)
-* --pcrel: M68K-Opts. (line 92)
-* --pic command line option, CRIS: CRIS-Opts. (line 27)
-* --print-insn-syntax: M68HC11-Opts. (line 75)
-* --print-opcodes: M68HC11-Opts. (line 79)
-* --register-prefix-optional option, M680x0: M68K-Opts. (line 51)
-* --relax: SH Options. (line 9)
-* --relax command line option, MMIX: MMIX-Opts. (line 19)
-* --rename-section: Xtensa Options. (line 54)
-* --renesas: SH Options. (line 9)
-* --short-branches: M68HC11-Opts. (line 54)
-* --small: SH Options. (line 9)
-* --statistics: statistics. (line 6)
-* --strict-direct-mode: M68HC11-Opts. (line 44)
-* --target-align: Xtensa Options. (line 30)
-* --text-section-literals: Xtensa Options. (line 9)
-* --traditional-format: traditional-format. (line 6)
-* --transform: Xtensa Options. (line 46)
-* --underscore command line option, CRIS: CRIS-Opts. (line 15)
-* --warn: W. (line 19)
-* -1 option, VAX/VMS: VAX-Opts. (line 77)
-* -32addr command line option, Alpha: Alpha Options. (line 50)
-* -a: a. (line 6)
-* -A options, i960: Options-i960. (line 6)
-* -ac: a. (line 6)
-* -ad: a. (line 6)
-* -ah: a. (line 6)
-* -al: a. (line 6)
-* -an: a. (line 6)
-* -as: a. (line 6)
-* -Asparclet: Sparc-Opts. (line 25)
-* -Asparclite: Sparc-Opts. (line 25)
-* -Av6: Sparc-Opts. (line 25)
-* -Av8: Sparc-Opts. (line 25)
-* -Av9: Sparc-Opts. (line 25)
-* -Av9a: Sparc-Opts. (line 25)
-* -b option, i960: Options-i960. (line 22)
-* -big option, M32R: M32R-Opts. (line 35)
-* -construct-floats: MIPS Opts. (line 195)
-* -D: D. (line 6)
-* -D, ignored on VAX: VAX-Opts. (line 11)
-* -d, VAX option: VAX-Opts. (line 16)
-* -eabi= command line option, ARM: ARM Options. (line 107)
-* -EB command line option, ARC: ARC Options. (line 31)
-* -EB command line option, ARM: ARM Options. (line 112)
-* -EB option (MIPS): MIPS Opts. (line 13)
-* -EB option, M32R: M32R-Opts. (line 39)
-* -EL command line option, ARC: ARC Options. (line 35)
-* -EL command line option, ARM: ARM Options. (line 116)
-* -EL option (MIPS): MIPS Opts. (line 13)
-* -EL option, M32R: M32R-Opts. (line 32)
-* -f: f. (line 6)
-* -F command line option, Alpha: Alpha Options. (line 50)
-* -G command line option, Alpha: Alpha Options. (line 46)
-* -g command line option, Alpha: Alpha Options. (line 40)
-* -G option (MIPS): MIPS Opts. (line 8)
-* -H option, VAX/VMS: VAX-Opts. (line 81)
-* -h option, VAX/VMS: VAX-Opts. (line 45)
-* -I PATH: I. (line 6)
-* -ignore-parallel-conflicts option, M32RX: M32R-Opts. (line 87)
-* -Ip option, M32RX: M32R-Opts. (line 97)
-* -J, ignored on VAX: VAX-Opts. (line 27)
-* -K: K. (line 6)
-* -k command line option, ARM: ARM Options. (line 120)
-* -KPIC option, M32R: M32R-Opts. (line 42)
-* -KPIC option, MIPS: MIPS Opts. (line 21)
-* -L: L. (line 6)
-* -l option, M680x0: M68K-Opts. (line 39)
-* -little option, M32R: M32R-Opts. (line 27)
-* -M: M. (line 6)
-* -m11/03: PDP-11-Options. (line 140)
-* -m11/04: PDP-11-Options. (line 143)
-* -m11/05: PDP-11-Options. (line 146)
-* -m11/10: PDP-11-Options. (line 146)
-* -m11/15: PDP-11-Options. (line 149)
-* -m11/20: PDP-11-Options. (line 149)
-* -m11/21: PDP-11-Options. (line 152)
-* -m11/23: PDP-11-Options. (line 155)
-* -m11/24: PDP-11-Options. (line 155)
-* -m11/34: PDP-11-Options. (line 158)
-* -m11/34a: PDP-11-Options. (line 161)
-* -m11/35: PDP-11-Options. (line 164)
-* -m11/40: PDP-11-Options. (line 164)
-* -m11/44: PDP-11-Options. (line 167)
-* -m11/45: PDP-11-Options. (line 170)
-* -m11/50: PDP-11-Options. (line 170)
-* -m11/53: PDP-11-Options. (line 173)
-* -m11/55: PDP-11-Options. (line 170)
-* -m11/60: PDP-11-Options. (line 176)
-* -m11/70: PDP-11-Options. (line 170)
-* -m11/73: PDP-11-Options. (line 173)
-* -m11/83: PDP-11-Options. (line 173)
-* -m11/84: PDP-11-Options. (line 173)
-* -m11/93: PDP-11-Options. (line 173)
-* -m11/94: PDP-11-Options. (line 173)
-* -m16c option, M16C: M32C-Opts. (line 12)
-* -m32c option, M32C: M32C-Opts. (line 9)
-* -m32r option, M32R: M32R-Opts. (line 21)
-* -m32rx option, M32R2: M32R-Opts. (line 17)
-* -m32rx option, M32RX: M32R-Opts. (line 9)
-* -m68000 and related options: M68K-Opts. (line 104)
-* -m68hc11: M68HC11-Opts. (line 9)
-* -m68hc12: M68HC11-Opts. (line 14)
-* -m68hcs12: M68HC11-Opts. (line 21)
-* -m[no-]68851 command line option, M680x0: M68K-Opts. (line 21)
-* -m[no-]68881 command line option, M680x0: M68K-Opts. (line 21)
-* -m[no-]div command line option, M680x0: M68K-Opts. (line 21)
-* -m[no-]emac command line option, M680x0: M68K-Opts. (line 21)
-* -m[no-]float command line option, M680x0: M68K-Opts. (line 21)
-* -m[no-]mac command line option, M680x0: M68K-Opts. (line 21)
-* -m[no-]usp command line option, M680x0: M68K-Opts. (line 21)
-* -mall: PDP-11-Options. (line 26)
-* -mall-extensions: PDP-11-Options. (line 26)
-* -mall-opcodes command line option, AVR: AVR Options. (line 43)
-* -mapcs command line option, ARM: ARM Options. (line 80)
-* -mapcs-float command line option, ARM: ARM Options. (line 93)
-* -mapcs-reentrant command line option, ARM: ARM Options. (line 98)
-* -marc[5|6|7|8] command line option, ARC: ARC Options. (line 6)
-* -march= command line option, ARM: ARM Options. (line 37)
-* -march= command line option, M680x0: M68K-Opts. (line 8)
-* -march= option, i386: i386-Options. (line 31)
-* -march= option, x86-64: i386-Options. (line 31)
-* -matpcs command line option, ARM: ARM Options. (line 85)
-* -mcis: PDP-11-Options. (line 32)
-* -mconstant-gp command line option, IA-64: IA-64 Options. (line 6)
-* -mCPU command line option, Alpha: Alpha Options. (line 6)
-* -mcpu option, cpu: TIC54X-Opts. (line 15)
-* -mcpu= command line option, ARM: ARM Options. (line 6)
-* -mcpu= command line option, M680x0: M68K-Opts. (line 14)
-* -mcsm: PDP-11-Options. (line 43)
-* -mdebug command line option, Alpha: Alpha Options. (line 25)
-* -me option, stderr redirect: TIC54X-Opts. (line 20)
-* -meis: PDP-11-Options. (line 46)
-* -merrors-to-file option, stderr redirect: TIC54X-Opts. (line 20)
-* -mf option, far-mode: TIC54X-Opts. (line 8)
-* -mf11: PDP-11-Options. (line 122)
-* -mfar-mode option, far-mode: TIC54X-Opts. (line 8)
-* -mfis: PDP-11-Options. (line 51)
-* -mfloat-abi= command line option, ARM: ARM Options. (line 102)
-* -mfp-11: PDP-11-Options. (line 56)
-* -mfpp: PDP-11-Options. (line 56)
-* -mfpu: PDP-11-Options. (line 56)
-* -mfpu= command line option, ARM: ARM Options. (line 52)
-* -mip2022 option, IP2K: IP2K-Opts. (line 14)
-* -mip2022ext option, IP2022: IP2K-Opts. (line 9)
-* -mj11: PDP-11-Options. (line 126)
-* -mka11: PDP-11-Options. (line 92)
-* -mkb11: PDP-11-Options. (line 95)
-* -mkd11a: PDP-11-Options. (line 98)
-* -mkd11b: PDP-11-Options. (line 101)
-* -mkd11d: PDP-11-Options. (line 104)
-* -mkd11e: PDP-11-Options. (line 107)
-* -mkd11f: PDP-11-Options. (line 110)
-* -mkd11h: PDP-11-Options. (line 110)
-* -mkd11k: PDP-11-Options. (line 114)
-* -mkd11q: PDP-11-Options. (line 110)
-* -mkd11z: PDP-11-Options. (line 118)
-* -mkev11: PDP-11-Options. (line 51)
-* -mlimited-eis: PDP-11-Options. (line 64)
-* -mlong: M68HC11-Opts. (line 32)
-* -mlong-double: M68HC11-Opts. (line 40)
-* -mmcu= command line option, AVR: AVR Options. (line 6)
-* -mmfpt: PDP-11-Options. (line 70)
-* -mmicrocode: PDP-11-Options. (line 83)
-* -mmutiproc: PDP-11-Options. (line 73)
-* -mmxps: PDP-11-Options. (line 77)
-* -mno-cis: PDP-11-Options. (line 32)
-* -mno-csm: PDP-11-Options. (line 43)
-* -mno-eis: PDP-11-Options. (line 46)
-* -mno-extensions: PDP-11-Options. (line 29)
-* -mno-fis: PDP-11-Options. (line 51)
-* -mno-fp-11: PDP-11-Options. (line 56)
-* -mno-fpp: PDP-11-Options. (line 56)
-* -mno-fpu: PDP-11-Options. (line 56)
-* -mno-kev11: PDP-11-Options. (line 51)
-* -mno-limited-eis: PDP-11-Options. (line 64)
-* -mno-mfpt: PDP-11-Options. (line 70)
-* -mno-microcode: PDP-11-Options. (line 83)
-* -mno-mutiproc: PDP-11-Options. (line 73)
-* -mno-mxps: PDP-11-Options. (line 77)
-* -mno-pic: PDP-11-Options. (line 11)
-* -mno-skip-bug command line option, AVR: AVR Options. (line 46)
-* -mno-spl: PDP-11-Options. (line 80)
-* -mno-sym32: MIPS Opts. (line 183)
-* -mno-wrap command line option, AVR: AVR Options. (line 49)
-* -mpic: PDP-11-Options. (line 11)
-* -mrelax command line option, V850: V850 Options. (line 51)
-* -mshort: M68HC11-Opts. (line 27)
-* -mshort-double: M68HC11-Opts. (line 36)
-* -mspl: PDP-11-Options. (line 80)
-* -msym32: MIPS Opts. (line 183)
-* -mt11: PDP-11-Options. (line 130)
-* -mthumb command line option, ARM: ARM Options. (line 71)
-* -mthumb-interwork command line option, ARM: ARM Options. (line 76)
-* -mtune= option, i386: i386-Options. (line 43)
-* -mtune= option, x86-64: i386-Options. (line 43)
-* -mv850 command line option, V850: V850 Options. (line 23)
-* -mv850any command line option, V850: V850 Options. (line 41)
-* -mv850e command line option, V850: V850 Options. (line 29)
-* -mv850e1 command line option, V850: V850 Options. (line 35)
-* -mvxworks-pic option, MIPS: MIPS Opts. (line 26)
-* -N command line option, CRIS: CRIS-Opts. (line 57)
-* -nIp option, M32RX: M32R-Opts. (line 101)
-* -no-bitinst, M32R2: M32R-Opts. (line 54)
-* -no-construct-floats: MIPS Opts. (line 195)
-* -no-ignore-parallel-conflicts option, M32RX: M32R-Opts. (line 93)
-* -no-mdebug command line option, Alpha: Alpha Options. (line 25)
-* -no-parallel option, M32RX: M32R-Opts. (line 51)
-* -no-relax option, i960: Options-i960. (line 66)
-* -no-warn-explicit-parallel-conflicts option, M32RX: M32R-Opts.
- (line 79)
-* -no-warn-unmatched-high option, M32R: M32R-Opts. (line 111)
-* -nocpp ignored (MIPS): MIPS Opts. (line 186)
-* -o: o. (line 6)
-* -O option, M32RX: M32R-Opts. (line 59)
-* -parallel option, M32RX: M32R-Opts. (line 46)
-* -R: R. (line 6)
-* -r800 command line option, Z80: Z80 Options. (line 41)
-* -relax command line option, Alpha: Alpha Options. (line 32)
-* -S, ignored on VAX: VAX-Opts. (line 11)
-* -t, ignored on VAX: VAX-Opts. (line 36)
-* -T, ignored on VAX: VAX-Opts. (line 11)
-* -v: v. (line 6)
-* -V, redundant on VAX: VAX-Opts. (line 22)
-* -version: v. (line 6)
-* -W: W. (line 11)
-* -warn-explicit-parallel-conflicts option, M32RX: M32R-Opts. (line 65)
-* -warn-unmatched-high option, M32R: M32R-Opts. (line 105)
-* -Wnp option, M32RX: M32R-Opts. (line 83)
-* -Wnuh option, M32RX: M32R-Opts. (line 117)
-* -Wp option, M32RX: M32R-Opts. (line 75)
-* -wsigned_overflow command line option, V850: V850 Options. (line 9)
-* -Wuh option, M32RX: M32R-Opts. (line 114)
-* -wunsigned_overflow command line option, V850: V850 Options.
- (line 16)
-* -x command line option, MMIX: MMIX-Opts. (line 44)
-* -z80 command line option, Z80: Z80 Options. (line 8)
-* -z8001 command line option, Z8000: Z8000 Options. (line 6)
-* -z8002 command line option, Z8000: Z8000 Options. (line 9)
-* . (symbol): Dot. (line 6)
-* .arch directive, ARM: ARM Directives. (line 210)
-* .big directive, M32RX: M32R-Directives. (line 88)
-* .cantunwind directive, ARM: ARM Directives. (line 114)
-* .cpu directive, ARM: ARM Directives. (line 206)
-* .eabi_attribute directive, ARM: ARM Directives. (line 224)
-* .fnend directive, ARM: ARM Directives. (line 105)
-* .fnstart directive, ARM: ARM Directives. (line 102)
-* .fpu directive, ARM: ARM Directives. (line 220)
-* .handlerdata directive, ARM: ARM Directives. (line 125)
-* .insn: MIPS insn. (line 6)
-* .little directive, M32RX: M32R-Directives. (line 82)
-* .ltorg directive, ARM: ARM Directives. (line 85)
-* .m32r directive, M32R: M32R-Directives. (line 66)
-* .m32r2 directive, M32R2: M32R-Directives. (line 77)
-* .m32rx directive, M32RX: M32R-Directives. (line 72)
-* .movsp directive, ARM: ARM Directives. (line 180)
-* .o: Object. (line 6)
-* .object_arch directive, ARM: ARM Directives. (line 214)
-* .pad directive, ARM: ARM Directives. (line 175)
-* .param on HPPA: HPPA Directives. (line 19)
-* .personality directive, ARM: ARM Directives. (line 118)
-* .personalityindex directive, ARM: ARM Directives. (line 121)
-* .pool directive, ARM: ARM Directives. (line 99)
-* .save directive, ARM: ARM Directives. (line 134)
-* .set arch=CPU: MIPS ISA. (line 18)
-* .set autoextend: MIPS autoextend. (line 6)
-* .set dsp: MIPS ASE instruction generation overrides.
- (line 21)
-* .set dspr2: MIPS ASE instruction generation overrides.
- (line 26)
-* .set mdmx: MIPS ASE instruction generation overrides.
- (line 16)
-* .set mips3d: MIPS ASE instruction generation overrides.
- (line 6)
-* .set mipsN: MIPS ISA. (line 6)
-* .set mt: MIPS ASE instruction generation overrides.
- (line 32)
-* .set noautoextend: MIPS autoextend. (line 6)
-* .set nodsp: MIPS ASE instruction generation overrides.
- (line 21)
-* .set nodspr2: MIPS ASE instruction generation overrides.
- (line 26)
-* .set nomdmx: MIPS ASE instruction generation overrides.
- (line 16)
-* .set nomips3d: MIPS ASE instruction generation overrides.
- (line 6)
-* .set nomt: MIPS ASE instruction generation overrides.
- (line 32)
-* .set nosmartmips: MIPS ASE instruction generation overrides.
- (line 11)
-* .set nosym32: MIPS symbol sizes. (line 6)
-* .set pop: MIPS option stack. (line 6)
-* .set push: MIPS option stack. (line 6)
-* .set smartmips: MIPS ASE instruction generation overrides.
- (line 11)
-* .set sym32: MIPS symbol sizes. (line 6)
-* .setfp directive, ARM: ARM Directives. (line 185)
-* .unwind_raw directive, ARM: ARM Directives. (line 199)
-* .v850 directive, V850: V850 Directives. (line 14)
-* .v850e directive, V850: V850 Directives. (line 20)
-* .v850e1 directive, V850: V850 Directives. (line 26)
-* .vsave directive, ARM: ARM Directives. (line 158)
-* .z8001: Z8000 Directives. (line 11)
-* .z8002: Z8000 Directives. (line 15)
-* 16-bit code, i386: i386-16bit. (line 6)
-* 2byte directive, ARC: ARC Directives. (line 9)
-* 3byte directive, ARC: ARC Directives. (line 12)
-* 3DNow!, i386: i386-SIMD. (line 6)
-* 3DNow!, x86-64: i386-SIMD. (line 6)
-* 430 support: MSP430-Dependent. (line 6)
-* 4byte directive, ARC: ARC Directives. (line 15)
-* : (label): Statements. (line 30)
-* @word modifier, D10V: D10V-Word. (line 6)
-* \" (doublequote character): Strings. (line 43)
-* \\ (\ character): Strings. (line 40)
-* \b (backspace character): Strings. (line 15)
-* \DDD (octal character code): Strings. (line 30)
-* \f (formfeed character): Strings. (line 18)
-* \n (newline character): Strings. (line 21)
-* \r (carriage return character): Strings. (line 24)
-* \t (tab): Strings. (line 27)
-* \XD... (hex character code): Strings. (line 36)
-* _ opcode prefix: Xtensa Opcodes. (line 9)
-* a.out: Object. (line 6)
-* a.out symbol attributes: a.out Symbols. (line 6)
-* A_DIR environment variable, TIC54X: TIC54X-Env. (line 6)
-* ABI options, SH64: SH64 Options. (line 29)
-* ABORT directive: ABORT (COFF). (line 6)
-* abort directive: Abort. (line 6)
-* absolute section: Ld Sections. (line 29)
-* absolute-literals directive: Absolute Literals Directive.
- (line 6)
-* ADDI instructions, relaxation: Xtensa Immediate Relaxation.
- (line 43)
-* addition, permitted arguments: Infix Ops. (line 44)
-* addresses: Expressions. (line 6)
-* addresses, format of: Secs Background. (line 68)
-* addressing modes, D10V: D10V-Addressing. (line 6)
-* addressing modes, D30V: D30V-Addressing. (line 6)
-* addressing modes, H8/300: H8/300-Addressing. (line 6)
-* addressing modes, M680x0: M68K-Syntax. (line 21)
-* addressing modes, M68HC11: M68HC11-Syntax. (line 17)
-* addressing modes, SH: SH-Addressing. (line 6)
-* addressing modes, SH64: SH64-Addressing. (line 6)
-* addressing modes, Z8000: Z8000-Addressing. (line 6)
-* ADR reg,<label> pseudo op, ARM: ARM Opcodes. (line 25)
-* ADRL reg,<label> pseudo op, ARM: ARM Opcodes. (line 35)
-* advancing location counter: Org. (line 6)
-* align directive: Align. (line 6)
-* align directive, ARM: ARM Directives. (line 6)
-* align directive, SPARC: Sparc-Directives. (line 9)
-* align directive, TIC54X: TIC54X-Directives. (line 6)
-* alignment of branch targets: Xtensa Automatic Alignment.
- (line 6)
-* alignment of LOOP instructions: Xtensa Automatic Alignment.
- (line 6)
-* Alpha floating point (IEEE): Alpha Floating Point.
- (line 6)
-* Alpha line comment character: Alpha-Chars. (line 6)
-* Alpha line separator: Alpha-Chars. (line 8)
-* Alpha notes: Alpha Notes. (line 6)
-* Alpha options: Alpha Options. (line 6)
-* Alpha registers: Alpha-Regs. (line 6)
-* Alpha relocations: Alpha-Relocs. (line 6)
-* Alpha support: Alpha-Dependent. (line 6)
-* Alpha Syntax: Alpha Options. (line 54)
-* Alpha-only directives: Alpha Directives. (line 10)
-* altered difference tables: Word. (line 12)
-* alternate syntax for the 680x0: M68K-Moto-Syntax. (line 6)
-* ARC floating point (IEEE): ARC Floating Point. (line 6)
-* ARC machine directives: ARC Directives. (line 6)
-* ARC opcodes: ARC Opcodes. (line 6)
-* ARC options (none): ARC Options. (line 6)
-* ARC register names: ARC-Regs. (line 6)
-* ARC special characters: ARC-Chars. (line 6)
-* ARC support: ARC-Dependent. (line 6)
-* arc5 arc5, ARC: ARC Options. (line 10)
-* arc6 arc6, ARC: ARC Options. (line 13)
-* arc7 arc7, ARC: ARC Options. (line 21)
-* arc8 arc8, ARC: ARC Options. (line 24)
-* arch directive, i386: i386-Arch. (line 6)
-* arch directive, M680x0: M68K-Directives. (line 22)
-* arch directive, x86-64: i386-Arch. (line 6)
-* architecture options, i960: Options-i960. (line 6)
-* architecture options, IP2022: IP2K-Opts. (line 9)
-* architecture options, IP2K: IP2K-Opts. (line 14)
-* architecture options, M16C: M32C-Opts. (line 12)
-* architecture options, M32C: M32C-Opts. (line 9)
-* architecture options, M32R: M32R-Opts. (line 21)
-* architecture options, M32R2: M32R-Opts. (line 17)
-* architecture options, M32RX: M32R-Opts. (line 9)
-* architecture options, M680x0: M68K-Opts. (line 104)
-* Architecture variant option, CRIS: CRIS-Opts. (line 33)
-* architectures, PowerPC: PowerPC-Opts. (line 6)
-* architectures, SPARC: Sparc-Opts. (line 6)
-* arguments for addition: Infix Ops. (line 44)
-* arguments for subtraction: Infix Ops. (line 49)
-* arguments in expressions: Arguments. (line 6)
-* arithmetic functions: Operators. (line 6)
-* arithmetic operands: Arguments. (line 6)
-* ARM data relocations: ARM-Relocations. (line 6)
-* arm directive, ARM: ARM Directives. (line 60)
-* ARM floating point (IEEE): ARM Floating Point. (line 6)
-* ARM identifiers: ARM-Chars. (line 15)
-* ARM immediate character: ARM-Chars. (line 13)
-* ARM line comment character: ARM-Chars. (line 6)
-* ARM line separator: ARM-Chars. (line 10)
-* ARM machine directives: ARM Directives. (line 6)
-* ARM opcodes: ARM Opcodes. (line 6)
-* ARM options (none): ARM Options. (line 6)
-* ARM register names: ARM-Regs. (line 6)
-* ARM support: ARM-Dependent. (line 6)
-* ascii directive: Ascii. (line 6)
-* asciz directive: Asciz. (line 6)
-* asg directive, TIC54X: TIC54X-Directives. (line 20)
-* assembler bugs, reporting: Bug Reporting. (line 6)
-* assembler crash: Bug Criteria. (line 9)
-* assembler directive .arch, CRIS: CRIS-Pseudos. (line 45)
-* assembler directive .dword, CRIS: CRIS-Pseudos. (line 12)
-* assembler directive .far, M68HC11: M68HC11-Directives. (line 20)
-* assembler directive .interrupt, M68HC11: M68HC11-Directives.
- (line 26)
-* assembler directive .mode, M68HC11: M68HC11-Directives. (line 16)
-* assembler directive .relax, M68HC11: M68HC11-Directives. (line 10)
-* assembler directive .syntax, CRIS: CRIS-Pseudos. (line 17)
-* assembler directive .xrefb, M68HC11: M68HC11-Directives. (line 31)
-* assembler directive BSPEC, MMIX: MMIX-Pseudos. (line 131)
-* assembler directive BYTE, MMIX: MMIX-Pseudos. (line 97)
-* assembler directive ESPEC, MMIX: MMIX-Pseudos. (line 131)
-* assembler directive GREG, MMIX: MMIX-Pseudos. (line 50)
-* assembler directive IS, MMIX: MMIX-Pseudos. (line 42)
-* assembler directive LOC, MMIX: MMIX-Pseudos. (line 7)
-* assembler directive LOCAL, MMIX: MMIX-Pseudos. (line 28)
-* assembler directive OCTA, MMIX: MMIX-Pseudos. (line 108)
-* assembler directive PREFIX, MMIX: MMIX-Pseudos. (line 120)
-* assembler directive TETRA, MMIX: MMIX-Pseudos. (line 108)
-* assembler directive WYDE, MMIX: MMIX-Pseudos. (line 108)
-* assembler directives, CRIS: CRIS-Pseudos. (line 6)
-* assembler directives, M68HC11: M68HC11-Directives. (line 6)
-* assembler directives, M68HC12: M68HC11-Directives. (line 6)
-* assembler directives, MMIX: MMIX-Pseudos. (line 6)
-* assembler internal logic error: As Sections. (line 13)
-* assembler version: v. (line 6)
-* assembler, and linker: Secs Background. (line 10)
-* assembly listings, enabling: a. (line 6)
-* assigning values to symbols <1>: Equ. (line 6)
-* assigning values to symbols: Setting Symbols. (line 6)
-* atmp directive, i860: Directives-i860. (line 16)
-* att_syntax pseudo op, i386: i386-Syntax. (line 6)
-* att_syntax pseudo op, x86-64: i386-Syntax. (line 6)
-* attributes, symbol: Symbol Attributes. (line 6)
-* auxiliary attributes, COFF symbols: COFF Symbols. (line 19)
-* auxiliary symbol information, COFF: Dim. (line 6)
-* Av7: Sparc-Opts. (line 25)
-* AVR line comment character: AVR-Chars. (line 6)
-* AVR line separator: AVR-Chars. (line 10)
-* AVR modifiers: AVR-Modifiers. (line 6)
-* AVR opcode summary: AVR Opcodes. (line 6)
-* AVR options (none): AVR Options. (line 6)
-* AVR register names: AVR-Regs. (line 6)
-* AVR support: AVR-Dependent. (line 6)
-* backslash (\\): Strings. (line 40)
-* backspace (\b): Strings. (line 15)
-* balign directive: Balign. (line 6)
-* balignl directive: Balign. (line 27)
-* balignw directive: Balign. (line 27)
-* bes directive, TIC54X: TIC54X-Directives. (line 197)
-* BFIN directives: BFIN Directives. (line 6)
-* BFIN syntax: BFIN Syntax. (line 6)
-* big endian output, MIPS: Overview. (line 616)
-* big endian output, PJ: Overview. (line 523)
-* big-endian output, MIPS: MIPS Opts. (line 13)
-* bignums: Bignums. (line 6)
-* binary constants, TIC54X: TIC54X-Constants. (line 8)
-* binary files, including: Incbin. (line 6)
-* binary integers: Integers. (line 6)
-* bit names, IA-64: IA-64-Bits. (line 6)
-* bitfields, not supported on VAX: VAX-no. (line 6)
-* Blackfin support: BFIN-Dependent. (line 6)
-* block: Z8000 Directives. (line 55)
-* branch improvement, M680x0: M68K-Branch. (line 6)
-* branch improvement, M68HC11: M68HC11-Branch. (line 6)
-* branch improvement, VAX: VAX-branch. (line 6)
-* branch instructions, relaxation: Xtensa Branch Relaxation.
- (line 6)
-* branch recording, i960: Options-i960. (line 22)
-* branch statistics table, i960: Options-i960. (line 40)
-* branch target alignment: Xtensa Automatic Alignment.
- (line 6)
-* break directive, TIC54X: TIC54X-Directives. (line 143)
-* BSD syntax: PDP-11-Syntax. (line 6)
-* bss directive, i960: Directives-i960. (line 6)
-* bss directive, TIC54X: TIC54X-Directives. (line 29)
-* bss section <1>: bss. (line 6)
-* bss section: Ld Sections. (line 20)
-* bug criteria: Bug Criteria. (line 6)
-* bug reports: Bug Reporting. (line 6)
-* bugs in assembler: Reporting Bugs. (line 6)
-* Built-in symbols, CRIS: CRIS-Symbols. (line 6)
-* builtin math functions, TIC54X: TIC54X-Builtins. (line 6)
-* builtin subsym functions, TIC54X: TIC54X-Macros. (line 16)
-* bus lock prefixes, i386: i386-Prefixes. (line 36)
-* bval: Z8000 Directives. (line 30)
-* byte directive: Byte. (line 6)
-* byte directive, TIC54X: TIC54X-Directives. (line 36)
-* C54XDSP_DIR environment variable, TIC54X: TIC54X-Env. (line 6)
-* c_mode directive, TIC54X: TIC54X-Directives. (line 51)
-* call instructions, i386: i386-Mnemonics. (line 51)
-* call instructions, relaxation: Xtensa Call Relaxation.
- (line 6)
-* call instructions, x86-64: i386-Mnemonics. (line 51)
-* callj, i960 pseudo-opcode: callj-i960. (line 6)
-* carriage return (\r): Strings. (line 24)
-* case sensitivity, Z80: Z80-Case. (line 6)
-* cfi_endproc directive: CFI directives. (line 16)
-* cfi_startproc directive: CFI directives. (line 6)
-* char directive, TIC54X: TIC54X-Directives. (line 36)
-* character constant, Z80: Z80-Chars. (line 13)
-* character constants: Characters. (line 6)
-* character escape codes: Strings. (line 15)
-* character escapes, Z80: Z80-Chars. (line 11)
-* character, single: Chars. (line 6)
-* characters used in symbols: Symbol Intro. (line 6)
-* clink directive, TIC54X: TIC54X-Directives. (line 45)
-* code directive, ARM: ARM Directives. (line 53)
-* code16 directive, i386: i386-16bit. (line 6)
-* code16gcc directive, i386: i386-16bit. (line 6)
-* code32 directive, i386: i386-16bit. (line 6)
-* code64 directive, i386: i386-16bit. (line 6)
-* code64 directive, x86-64: i386-16bit. (line 6)
-* COFF auxiliary symbol information: Dim. (line 6)
-* COFF structure debugging: Tag. (line 6)
-* COFF symbol attributes: COFF Symbols. (line 6)
-* COFF symbol descriptor: Desc. (line 6)
-* COFF symbol storage class: Scl. (line 6)
-* COFF symbol type: Type. (line 11)
-* COFF symbols, debugging: Def. (line 6)
-* COFF value attribute: Val. (line 6)
-* COMDAT: Linkonce. (line 6)
-* comm directive: Comm. (line 6)
-* command line conventions: Command Line. (line 6)
-* command line options, V850: V850 Options. (line 9)
-* command-line options ignored, VAX: VAX-Opts. (line 6)
-* comments: Comments. (line 6)
-* comments, M680x0: M68K-Chars. (line 6)
-* comments, removed by preprocessor: Preprocessing. (line 11)
-* common directive, SPARC: Sparc-Directives. (line 12)
-* common sections: Linkonce. (line 6)
-* common variable storage: bss. (line 6)
-* compare and jump expansions, i960: Compare-and-branch-i960.
- (line 13)
-* compare/branch instructions, i960: Compare-and-branch-i960.
- (line 6)
-* comparison expressions: Infix Ops. (line 55)
-* conditional assembly: If. (line 6)
-* constant, single character: Chars. (line 6)
-* constants: Constants. (line 6)
-* constants, bignum: Bignums. (line 6)
-* constants, character: Characters. (line 6)
-* constants, converted by preprocessor: Preprocessing. (line 14)
-* constants, floating point: Flonums. (line 6)
-* constants, integer: Integers. (line 6)
-* constants, number: Numbers. (line 6)
-* constants, string: Strings. (line 6)
-* constants, TIC54X: TIC54X-Constants. (line 6)
-* conversion instructions, i386: i386-Mnemonics. (line 32)
-* conversion instructions, x86-64: i386-Mnemonics. (line 32)
-* coprocessor wait, i386: i386-Prefixes. (line 40)
-* copy directive, TIC54X: TIC54X-Directives. (line 54)
-* cpu directive, M680x0: M68K-Directives. (line 30)
-* CR16 Operand Qualifiers: CR16 Operand Qualifiers.
- (line 6)
-* CR16 support: CR16-Dependent. (line 6)
-* crash of assembler: Bug Criteria. (line 9)
-* CRIS --emulation=crisaout command line option: CRIS-Opts. (line 9)
-* CRIS --emulation=criself command line option: CRIS-Opts. (line 9)
-* CRIS --march=ARCHITECTURE command line option: CRIS-Opts. (line 33)
-* CRIS --mul-bug-abort command line option: CRIS-Opts. (line 61)
-* CRIS --no-mul-bug-abort command line option: CRIS-Opts. (line 61)
-* CRIS --no-underscore command line option: CRIS-Opts. (line 15)
-* CRIS --pic command line option: CRIS-Opts. (line 27)
-* CRIS --underscore command line option: CRIS-Opts. (line 15)
-* CRIS -N command line option: CRIS-Opts. (line 57)
-* CRIS architecture variant option: CRIS-Opts. (line 33)
-* CRIS assembler directive .arch: CRIS-Pseudos. (line 45)
-* CRIS assembler directive .dword: CRIS-Pseudos. (line 12)
-* CRIS assembler directive .syntax: CRIS-Pseudos. (line 17)
-* CRIS assembler directives: CRIS-Pseudos. (line 6)
-* CRIS built-in symbols: CRIS-Symbols. (line 6)
-* CRIS instruction expansion: CRIS-Expand. (line 6)
-* CRIS line comment characters: CRIS-Chars. (line 6)
-* CRIS options: CRIS-Opts. (line 6)
-* CRIS position-independent code: CRIS-Opts. (line 27)
-* CRIS pseudo-op .arch: CRIS-Pseudos. (line 45)
-* CRIS pseudo-op .dword: CRIS-Pseudos. (line 12)
-* CRIS pseudo-op .syntax: CRIS-Pseudos. (line 17)
-* CRIS pseudo-ops: CRIS-Pseudos. (line 6)
-* CRIS register names: CRIS-Regs. (line 6)
-* CRIS support: CRIS-Dependent. (line 6)
-* CRIS symbols in position-independent code: CRIS-Pic. (line 6)
-* ctbp register, V850: V850-Regs. (line 131)
-* ctoff pseudo-op, V850: V850 Opcodes. (line 111)
-* ctpc register, V850: V850-Regs. (line 119)
-* ctpsw register, V850: V850-Regs. (line 122)
-* current address: Dot. (line 6)
-* current address, advancing: Org. (line 6)
-* D10V @word modifier: D10V-Word. (line 6)
-* D10V addressing modes: D10V-Addressing. (line 6)
-* D10V floating point: D10V-Float. (line 6)
-* D10V line comment character: D10V-Chars. (line 6)
-* D10V opcode summary: D10V-Opcodes. (line 6)
-* D10V optimization: Overview. (line 401)
-* D10V options: D10V-Opts. (line 6)
-* D10V registers: D10V-Regs. (line 6)
-* D10V size modifiers: D10V-Size. (line 6)
-* D10V sub-instruction ordering: D10V-Chars. (line 6)
-* D10V sub-instructions: D10V-Subs. (line 6)
-* D10V support: D10V-Dependent. (line 6)
-* D10V syntax: D10V-Syntax. (line 6)
-* D30V addressing modes: D30V-Addressing. (line 6)
-* D30V floating point: D30V-Float. (line 6)
-* D30V Guarded Execution: D30V-Guarded. (line 6)
-* D30V line comment character: D30V-Chars. (line 6)
-* D30V nops: Overview. (line 409)
-* D30V nops after 32-bit multiply: Overview. (line 412)
-* D30V opcode summary: D30V-Opcodes. (line 6)
-* D30V optimization: Overview. (line 406)
-* D30V options: D30V-Opts. (line 6)
-* D30V registers: D30V-Regs. (line 6)
-* D30V size modifiers: D30V-Size. (line 6)
-* D30V sub-instruction ordering: D30V-Chars. (line 6)
-* D30V sub-instructions: D30V-Subs. (line 6)
-* D30V support: D30V-Dependent. (line 6)
-* D30V syntax: D30V-Syntax. (line 6)
-* data alignment on SPARC: Sparc-Aligned-Data. (line 6)
-* data and text sections, joining: R. (line 6)
-* data directive: Data. (line 6)
-* data directive, TIC54X: TIC54X-Directives. (line 61)
-* data relocations, ARM: ARM-Relocations. (line 6)
-* data section: Ld Sections. (line 9)
-* data1 directive, M680x0: M68K-Directives. (line 9)
-* data2 directive, M680x0: M68K-Directives. (line 12)
-* datalabel, SH64: SH64-Addressing. (line 16)
-* dbpc register, V850: V850-Regs. (line 125)
-* dbpsw register, V850: V850-Regs. (line 128)
-* debuggers, and symbol order: Symbols. (line 10)
-* debugging COFF symbols: Def. (line 6)
-* DEC syntax: PDP-11-Syntax. (line 6)
-* decimal integers: Integers. (line 12)
-* def directive: Def. (line 6)
-* def directive, TIC54X: TIC54X-Directives. (line 103)
-* density instructions: Density Instructions.
- (line 6)
-* dependency tracking: MD. (line 6)
-* deprecated directives: Deprecated. (line 6)
-* desc directive: Desc. (line 6)
-* descriptor, of a.out symbol: Symbol Desc. (line 6)
-* dfloat directive, VAX: VAX-directives. (line 10)
-* difference tables altered: Word. (line 12)
-* difference tables, warning: K. (line 6)
-* differences, mmixal: MMIX-mmixal. (line 6)
-* dim directive: Dim. (line 6)
-* directives and instructions: Statements. (line 19)
-* directives for PowerPC: PowerPC-Pseudo. (line 6)
-* directives, BFIN: BFIN Directives. (line 6)
-* directives, M32R: M32R-Directives. (line 6)
-* directives, M680x0: M68K-Directives. (line 6)
-* directives, machine independent: Pseudo Ops. (line 6)
-* directives, Xtensa: Xtensa Directives. (line 6)
-* directives, Z8000: Z8000 Directives. (line 6)
-* displacement sizing character, VAX: VAX-operands. (line 12)
-* dn and qn directives, ARM: ARM Directives. (line 29)
-* dollar local symbols: Symbol Names. (line 105)
-* dot (symbol): Dot. (line 6)
-* double directive: Double. (line 6)
-* double directive, i386: i386-Float. (line 14)
-* double directive, M680x0: M68K-Float. (line 14)
-* double directive, M68HC11: M68HC11-Float. (line 14)
-* double directive, TIC54X: TIC54X-Directives. (line 64)
-* double directive, VAX: VAX-float. (line 15)
-* double directive, x86-64: i386-Float. (line 14)
-* doublequote (\"): Strings. (line 43)
-* drlist directive, TIC54X: TIC54X-Directives. (line 73)
-* drnolist directive, TIC54X: TIC54X-Directives. (line 73)
-* dual directive, i860: Directives-i860. (line 6)
-* ECOFF sections: MIPS Object. (line 6)
-* ecr register, V850: V850-Regs. (line 113)
-* eight-byte integer: Quad. (line 9)
-* eipc register, V850: V850-Regs. (line 101)
-* eipsw register, V850: V850-Regs. (line 104)
-* eject directive: Eject. (line 6)
-* ELF symbol type: Type. (line 22)
-* else directive: Else. (line 6)
-* elseif directive: Elseif. (line 6)
-* empty expressions: Empty Exprs. (line 6)
-* emsg directive, TIC54X: TIC54X-Directives. (line 77)
-* emulation: Overview. (line 719)
-* end directive: End. (line 6)
-* enddual directive, i860: Directives-i860. (line 11)
-* endef directive: Endef. (line 6)
-* endfunc directive: Endfunc. (line 6)
-* endianness, MIPS: Overview. (line 616)
-* endianness, PJ: Overview. (line 523)
-* endif directive: Endif. (line 6)
-* endloop directive, TIC54X: TIC54X-Directives. (line 143)
-* endm directive: Macro. (line 138)
-* endm directive, TIC54X: TIC54X-Directives. (line 153)
-* endstruct directive, TIC54X: TIC54X-Directives. (line 217)
-* endunion directive, TIC54X: TIC54X-Directives. (line 251)
-* environment settings, TIC54X: TIC54X-Env. (line 6)
-* EOF, newline must precede: Statements. (line 13)
-* ep register, V850: V850-Regs. (line 95)
-* equ directive: Equ. (line 6)
-* equ directive, TIC54X: TIC54X-Directives. (line 192)
-* equiv directive: Equiv. (line 6)
-* eqv directive: Eqv. (line 6)
-* err directive: Err. (line 6)
-* error directive: Error. (line 6)
-* error messages: Errors. (line 6)
-* error on valid input: Bug Criteria. (line 12)
-* errors, caused by warnings: W. (line 16)
-* errors, continuing after: Z. (line 6)
-* ESA/390 floating point (IEEE): ESA/390 Floating Point.
- (line 6)
-* ESA/390 support: ESA/390-Dependent. (line 6)
-* ESA/390 Syntax: ESA/390 Options. (line 8)
-* ESA/390-only directives: ESA/390 Directives. (line 12)
-* escape codes, character: Strings. (line 15)
-* eval directive, TIC54X: TIC54X-Directives. (line 24)
-* even: Z8000 Directives. (line 58)
-* even directive, M680x0: M68K-Directives. (line 15)
-* even directive, TIC54X: TIC54X-Directives. (line 6)
-* exitm directive: Macro. (line 141)
-* expr (internal section): As Sections. (line 17)
-* expression arguments: Arguments. (line 6)
-* expressions: Expressions. (line 6)
-* expressions, comparison: Infix Ops. (line 55)
-* expressions, empty: Empty Exprs. (line 6)
-* expressions, integer: Integer Exprs. (line 6)
-* extAuxRegister directive, ARC: ARC Directives. (line 18)
-* extCondCode directive, ARC: ARC Directives. (line 41)
-* extCoreRegister directive, ARC: ARC Directives. (line 53)
-* extend directive M680x0: M68K-Float. (line 17)
-* extend directive M68HC11: M68HC11-Float. (line 17)
-* extended directive, i960: Directives-i960. (line 13)
-* extern directive: Extern. (line 6)
-* extInstruction directive, ARC: ARC Directives. (line 78)
-* fail directive: Fail. (line 6)
-* far_mode directive, TIC54X: TIC54X-Directives. (line 82)
-* faster processing (-f): f. (line 6)
-* fatal signal: Bug Criteria. (line 9)
-* fclist directive, TIC54X: TIC54X-Directives. (line 87)
-* fcnolist directive, TIC54X: TIC54X-Directives. (line 87)
-* fepc register, V850: V850-Regs. (line 107)
-* fepsw register, V850: V850-Regs. (line 110)
-* ffloat directive, VAX: VAX-directives. (line 14)
-* field directive, TIC54X: TIC54X-Directives. (line 91)
-* file directive <1>: File. (line 6)
-* file directive: LNS directives. (line 6)
-* file directive, MSP 430: MSP430 Directives. (line 6)
-* file name, logical: File. (line 6)
-* files, including: Include. (line 6)
-* files, input: Input Files. (line 6)
-* fill directive: Fill. (line 6)
-* filling memory <1>: Space. (line 6)
-* filling memory: Skip. (line 6)
-* FLIX syntax: Xtensa Syntax. (line 6)
-* float directive: Float. (line 6)
-* float directive, i386: i386-Float. (line 14)
-* float directive, M680x0: M68K-Float. (line 11)
-* float directive, M68HC11: M68HC11-Float. (line 11)
-* float directive, TIC54X: TIC54X-Directives. (line 64)
-* float directive, VAX: VAX-float. (line 15)
-* float directive, x86-64: i386-Float. (line 14)
-* floating point numbers: Flonums. (line 6)
-* floating point numbers (double): Double. (line 6)
-* floating point numbers (single) <1>: Single. (line 6)
-* floating point numbers (single): Float. (line 6)
-* floating point, Alpha (IEEE): Alpha Floating Point.
- (line 6)
-* floating point, ARC (IEEE): ARC Floating Point. (line 6)
-* floating point, ARM (IEEE): ARM Floating Point. (line 6)
-* floating point, D10V: D10V-Float. (line 6)
-* floating point, D30V: D30V-Float. (line 6)
-* floating point, ESA/390 (IEEE): ESA/390 Floating Point.
- (line 6)
-* floating point, H8/300 (IEEE): H8/300 Floating Point.
- (line 6)
-* floating point, HPPA (IEEE): HPPA Floating Point. (line 6)
-* floating point, i386: i386-Float. (line 6)
-* floating point, i960 (IEEE): Floating Point-i960. (line 6)
-* floating point, M680x0: M68K-Float. (line 6)
-* floating point, M68HC11: M68HC11-Float. (line 6)
-* floating point, MSP 430 (IEEE): MSP430 Floating Point.
- (line 6)
-* floating point, SH (IEEE): SH Floating Point. (line 6)
-* floating point, SPARC (IEEE): Sparc-Float. (line 6)
-* floating point, V850 (IEEE): V850 Floating Point. (line 6)
-* floating point, VAX: VAX-float. (line 6)
-* floating point, x86-64: i386-Float. (line 6)
-* floating point, Z80: Z80 Floating Point. (line 6)
-* flonums: Flonums. (line 6)
-* force_thumb directive, ARM: ARM Directives. (line 63)
-* format of error messages: Errors. (line 24)
-* format of warning messages: Errors. (line 12)
-* formfeed (\f): Strings. (line 18)
-* func directive: Func. (line 6)
-* functions, in expressions: Operators. (line 6)
-* gbr960, i960 postprocessor: Options-i960. (line 40)
-* gfloat directive, VAX: VAX-directives. (line 18)
-* global: Z8000 Directives. (line 21)
-* global directive: Global. (line 6)
-* global directive, TIC54X: TIC54X-Directives. (line 103)
-* gp register, MIPS: MIPS Object. (line 11)
-* gp register, V850: V850-Regs. (line 17)
-* grouping data: Sub-Sections. (line 6)
-* H8/300 addressing modes: H8/300-Addressing. (line 6)
-* H8/300 floating point (IEEE): H8/300 Floating Point.
- (line 6)
-* H8/300 line comment character: H8/300-Chars. (line 6)
-* H8/300 line separator: H8/300-Chars. (line 8)
-* H8/300 machine directives (none): H8/300 Directives. (line 6)
-* H8/300 opcode summary: H8/300 Opcodes. (line 6)
-* H8/300 options (none): H8/300 Options. (line 6)
-* H8/300 registers: H8/300-Regs. (line 6)
-* H8/300 size suffixes: H8/300 Opcodes. (line 163)
-* H8/300 support: H8/300-Dependent. (line 6)
-* H8/300H, assembling for: H8/300 Directives. (line 8)
-* half directive, ARC: ARC Directives. (line 156)
-* half directive, SPARC: Sparc-Directives. (line 17)
-* half directive, TIC54X: TIC54X-Directives. (line 111)
-* hex character code (\XD...): Strings. (line 36)
-* hexadecimal integers: Integers. (line 15)
-* hexadecimal prefix, Z80: Z80-Chars. (line 8)
-* hfloat directive, VAX: VAX-directives. (line 22)
-* hi pseudo-op, V850: V850 Opcodes. (line 33)
-* hi0 pseudo-op, V850: V850 Opcodes. (line 10)
-* hidden directive: Hidden. (line 6)
-* high directive, M32R: M32R-Directives. (line 18)
-* hilo pseudo-op, V850: V850 Opcodes. (line 55)
-* HPPA directives not supported: HPPA Directives. (line 11)
-* HPPA floating point (IEEE): HPPA Floating Point. (line 6)
-* HPPA Syntax: HPPA Options. (line 8)
-* HPPA-only directives: HPPA Directives. (line 24)
-* hword directive: hword. (line 6)
-* i370 support: ESA/390-Dependent. (line 6)
-* i386 16-bit code: i386-16bit. (line 6)
-* i386 arch directive: i386-Arch. (line 6)
-* i386 att_syntax pseudo op: i386-Syntax. (line 6)
-* i386 conversion instructions: i386-Mnemonics. (line 32)
-* i386 floating point: i386-Float. (line 6)
-* i386 immediate operands: i386-Syntax. (line 15)
-* i386 instruction naming: i386-Mnemonics. (line 6)
-* i386 instruction prefixes: i386-Prefixes. (line 6)
-* i386 intel_syntax pseudo op: i386-Syntax. (line 6)
-* i386 jump optimization: i386-Jumps. (line 6)
-* i386 jump, call, return: i386-Syntax. (line 38)
-* i386 jump/call operands: i386-Syntax. (line 15)
-* i386 memory references: i386-Memory. (line 6)
-* i386 mul, imul instructions: i386-Notes. (line 6)
-* i386 options: i386-Options. (line 6)
-* i386 register operands: i386-Syntax. (line 15)
-* i386 registers: i386-Regs. (line 6)
-* i386 sections: i386-Syntax. (line 44)
-* i386 size suffixes: i386-Syntax. (line 29)
-* i386 source, destination operands: i386-Syntax. (line 22)
-* i386 support: i386-Dependent. (line 6)
-* i386 syntax compatibility: i386-Syntax. (line 6)
-* i80306 support: i386-Dependent. (line 6)
-* i860 machine directives: Directives-i860. (line 6)
-* i860 opcodes: Opcodes for i860. (line 6)
-* i860 support: i860-Dependent. (line 6)
-* i960 architecture options: Options-i960. (line 6)
-* i960 branch recording: Options-i960. (line 22)
-* i960 callj pseudo-opcode: callj-i960. (line 6)
-* i960 compare and jump expansions: Compare-and-branch-i960.
- (line 13)
-* i960 compare/branch instructions: Compare-and-branch-i960.
- (line 6)
-* i960 floating point (IEEE): Floating Point-i960. (line 6)
-* i960 machine directives: Directives-i960. (line 6)
-* i960 opcodes: Opcodes for i960. (line 6)
-* i960 options: Options-i960. (line 6)
-* i960 support: i960-Dependent. (line 6)
-* IA-64 line comment character: IA-64-Chars. (line 6)
-* IA-64 line separator: IA-64-Chars. (line 8)
-* IA-64 options: IA-64 Options. (line 6)
-* IA-64 Processor-status-Register bit names: IA-64-Bits. (line 6)
-* IA-64 registers: IA-64-Regs. (line 6)
-* IA-64 support: IA-64-Dependent. (line 6)
-* IA-64 Syntax: IA-64 Options. (line 96)
-* ident directive: Ident. (line 6)
-* identifiers, ARM: ARM-Chars. (line 15)
-* identifiers, MSP 430: MSP430-Chars. (line 8)
-* if directive: If. (line 6)
-* ifb directive: If. (line 21)
-* ifc directive: If. (line 25)
-* ifdef directive: If. (line 16)
-* ifeq directive: If. (line 33)
-* ifeqs directive: If. (line 36)
-* ifge directive: If. (line 40)
-* ifgt directive: If. (line 44)
-* ifle directive: If. (line 48)
-* iflt directive: If. (line 52)
-* ifnb directive: If. (line 56)
-* ifnc directive: If. (line 61)
-* ifndef directive: If. (line 65)
-* ifne directive: If. (line 72)
-* ifnes directive: If. (line 76)
-* ifnotdef directive: If. (line 65)
-* immediate character, ARM: ARM-Chars. (line 13)
-* immediate character, M680x0: M68K-Chars. (line 6)
-* immediate character, VAX: VAX-operands. (line 6)
-* immediate fields, relaxation: Xtensa Immediate Relaxation.
- (line 6)
-* immediate operands, i386: i386-Syntax. (line 15)
-* immediate operands, x86-64: i386-Syntax. (line 15)
-* imul instruction, i386: i386-Notes. (line 6)
-* imul instruction, x86-64: i386-Notes. (line 6)
-* incbin directive: Incbin. (line 6)
-* include directive: Include. (line 6)
-* include directive search path: I. (line 6)
-* indirect character, VAX: VAX-operands. (line 9)
-* infix operators: Infix Ops. (line 6)
-* inhibiting interrupts, i386: i386-Prefixes. (line 36)
-* input: Input Files. (line 6)
-* input file linenumbers: Input Files. (line 35)
-* instruction expansion, CRIS: CRIS-Expand. (line 6)
-* instruction expansion, MMIX: MMIX-Expand. (line 6)
-* instruction naming, i386: i386-Mnemonics. (line 6)
-* instruction naming, x86-64: i386-Mnemonics. (line 6)
-* instruction prefixes, i386: i386-Prefixes. (line 6)
-* instruction set, M680x0: M68K-opcodes. (line 6)
-* instruction set, M68HC11: M68HC11-opcodes. (line 6)
-* instruction summary, AVR: AVR Opcodes. (line 6)
-* instruction summary, D10V: D10V-Opcodes. (line 6)
-* instruction summary, D30V: D30V-Opcodes. (line 6)
-* instruction summary, H8/300: H8/300 Opcodes. (line 6)
-* instruction summary, SH: SH Opcodes. (line 6)
-* instruction summary, SH64: SH64 Opcodes. (line 6)
-* instruction summary, Z8000: Z8000 Opcodes. (line 6)
-* instructions and directives: Statements. (line 19)
-* int directive: Int. (line 6)
-* int directive, H8/300: H8/300 Directives. (line 6)
-* int directive, i386: i386-Float. (line 21)
-* int directive, TIC54X: TIC54X-Directives. (line 111)
-* int directive, x86-64: i386-Float. (line 21)
-* integer expressions: Integer Exprs. (line 6)
-* integer, 16-byte: Octa. (line 6)
-* integer, 8-byte: Quad. (line 9)
-* integers: Integers. (line 6)
-* integers, 16-bit: hword. (line 6)
-* integers, 32-bit: Int. (line 6)
-* integers, binary: Integers. (line 6)
-* integers, decimal: Integers. (line 12)
-* integers, hexadecimal: Integers. (line 15)
-* integers, octal: Integers. (line 9)
-* integers, one byte: Byte. (line 6)
-* intel_syntax pseudo op, i386: i386-Syntax. (line 6)
-* intel_syntax pseudo op, x86-64: i386-Syntax. (line 6)
-* internal assembler sections: As Sections. (line 6)
-* internal directive: Internal. (line 6)
-* invalid input: Bug Criteria. (line 14)
-* invocation summary: Overview. (line 6)
-* IP2K architecture options: IP2K-Opts. (line 9)
-* IP2K options: IP2K-Opts. (line 6)
-* IP2K support: IP2K-Dependent. (line 6)
-* irp directive: Irp. (line 6)
-* irpc directive: Irpc. (line 6)
-* ISA options, SH64: SH64 Options. (line 6)
-* joining text and data sections: R. (line 6)
-* jump instructions, i386: i386-Mnemonics. (line 51)
-* jump instructions, x86-64: i386-Mnemonics. (line 51)
-* jump optimization, i386: i386-Jumps. (line 6)
-* jump optimization, x86-64: i386-Jumps. (line 6)
-* jump/call operands, i386: i386-Syntax. (line 15)
-* jump/call operands, x86-64: i386-Syntax. (line 15)
-* L16SI instructions, relaxation: Xtensa Immediate Relaxation.
- (line 23)
-* L16UI instructions, relaxation: Xtensa Immediate Relaxation.
- (line 23)
-* L32I instructions, relaxation: Xtensa Immediate Relaxation.
- (line 23)
-* L8UI instructions, relaxation: Xtensa Immediate Relaxation.
- (line 23)
-* label (:): Statements. (line 30)
-* label directive, TIC54X: TIC54X-Directives. (line 123)
-* labels: Labels. (line 6)
-* lcomm directive: Lcomm. (line 6)
-* ld: Object. (line 15)
-* ldouble directive M680x0: M68K-Float. (line 17)
-* ldouble directive M68HC11: M68HC11-Float. (line 17)
-* ldouble directive, TIC54X: TIC54X-Directives. (line 64)
-* LDR reg,=<label> pseudo op, ARM: ARM Opcodes. (line 15)
-* leafproc directive, i960: Directives-i960. (line 18)
-* length directive, TIC54X: TIC54X-Directives. (line 127)
-* length of symbols: Symbol Intro. (line 14)
-* lflags directive (ignored): Lflags. (line 6)
-* line comment character: Comments. (line 19)
-* line comment character, Alpha: Alpha-Chars. (line 6)
-* line comment character, ARM: ARM-Chars. (line 6)
-* line comment character, AVR: AVR-Chars. (line 6)
-* line comment character, D10V: D10V-Chars. (line 6)
-* line comment character, D30V: D30V-Chars. (line 6)
-* line comment character, H8/300: H8/300-Chars. (line 6)
-* line comment character, IA-64: IA-64-Chars. (line 6)
-* line comment character, M680x0: M68K-Chars. (line 6)
-* line comment character, MSP 430: MSP430-Chars. (line 6)
-* line comment character, SH: SH-Chars. (line 6)
-* line comment character, SH64: SH64-Chars. (line 6)
-* line comment character, V850: V850-Chars. (line 6)
-* line comment character, Z80: Z80-Chars. (line 6)
-* line comment character, Z8000: Z8000-Chars. (line 6)
-* line comment characters, CRIS: CRIS-Chars. (line 6)
-* line comment characters, MMIX: MMIX-Chars. (line 6)
-* line directive: Line. (line 6)
-* line directive, MSP 430: MSP430 Directives. (line 14)
-* line numbers, in input files: Input Files. (line 35)
-* line numbers, in warnings/errors: Errors. (line 16)
-* line separator character: Statements. (line 6)
-* line separator, Alpha: Alpha-Chars. (line 8)
-* line separator, ARM: ARM-Chars. (line 10)
-* line separator, AVR: AVR-Chars. (line 10)
-* line separator, H8/300: H8/300-Chars. (line 8)
-* line separator, IA-64: IA-64-Chars. (line 8)
-* line separator, SH: SH-Chars. (line 8)
-* line separator, SH64: SH64-Chars. (line 8)
-* line separator, Z8000: Z8000-Chars. (line 8)
-* lines starting with #: Comments. (line 38)
-* linker: Object. (line 15)
-* linker, and assembler: Secs Background. (line 10)
-* linkonce directive: Linkonce. (line 6)
-* list directive: List. (line 6)
-* list directive, TIC54X: TIC54X-Directives. (line 131)
-* listing control, turning off: Nolist. (line 6)
-* listing control, turning on: List. (line 6)
-* listing control: new page: Eject. (line 6)
-* listing control: paper size: Psize. (line 6)
-* listing control: subtitle: Sbttl. (line 6)
-* listing control: title line: Title. (line 6)
-* listings, enabling: a. (line 6)
-* literal directive: Literal Directive. (line 6)
-* literal_position directive: Literal Position Directive.
- (line 6)
-* literal_prefix directive: Literal Prefix Directive.
- (line 6)
-* little endian output, MIPS: Overview. (line 619)
-* little endian output, PJ: Overview. (line 526)
-* little-endian output, MIPS: MIPS Opts. (line 13)
-* ln directive: Ln. (line 6)
-* lo pseudo-op, V850: V850 Opcodes. (line 22)
-* loc directive: LNS directives. (line 19)
-* loc_mark_blocks directive: LNS directives. (line 50)
-* local common symbols: Lcomm. (line 6)
-* local labels: Symbol Names. (line 35)
-* local symbol names: Symbol Names. (line 22)
-* local symbols, retaining in output: L. (line 6)
-* location counter: Dot. (line 6)
-* location counter, advancing: Org. (line 6)
-* location counter, Z80: Z80-Chars. (line 8)
-* logical file name: File. (line 6)
-* logical line number: Line. (line 6)
-* logical line numbers: Comments. (line 38)
-* long directive: Long. (line 6)
-* long directive, ARC: ARC Directives. (line 159)
-* long directive, i386: i386-Float. (line 21)
-* long directive, TIC54X: TIC54X-Directives. (line 135)
-* long directive, x86-64: i386-Float. (line 21)
-* longcall pseudo-op, V850: V850 Opcodes. (line 123)
-* longcalls directive: Longcalls Directive. (line 6)
-* longjump pseudo-op, V850: V850 Opcodes. (line 129)
-* loop directive, TIC54X: TIC54X-Directives. (line 143)
-* LOOP instructions, alignment: Xtensa Automatic Alignment.
- (line 6)
-* low directive, M32R: M32R-Directives. (line 9)
-* lp register, V850: V850-Regs. (line 98)
-* lval: Z8000 Directives. (line 27)
-* M16C architecture option: M32C-Opts. (line 12)
-* M32C architecture option: M32C-Opts. (line 9)
-* M32C modifiers: M32C-Modifiers. (line 6)
-* M32C options: M32C-Opts. (line 6)
-* M32C support: M32C-Dependent. (line 6)
-* M32R architecture options: M32R-Opts. (line 9)
-* M32R directives: M32R-Directives. (line 6)
-* M32R options: M32R-Opts. (line 6)
-* M32R support: M32R-Dependent. (line 6)
-* M32R warnings: M32R-Warnings. (line 6)
-* M680x0 addressing modes: M68K-Syntax. (line 21)
-* M680x0 architecture options: M68K-Opts. (line 104)
-* M680x0 branch improvement: M68K-Branch. (line 6)
-* M680x0 directives: M68K-Directives. (line 6)
-* M680x0 floating point: M68K-Float. (line 6)
-* M680x0 immediate character: M68K-Chars. (line 6)
-* M680x0 line comment character: M68K-Chars. (line 6)
-* M680x0 opcodes: M68K-opcodes. (line 6)
-* M680x0 options: M68K-Opts. (line 6)
-* M680x0 pseudo-opcodes: M68K-Branch. (line 6)
-* M680x0 size modifiers: M68K-Syntax. (line 8)
-* M680x0 support: M68K-Dependent. (line 6)
-* M680x0 syntax: M68K-Syntax. (line 8)
-* M68HC11 addressing modes: M68HC11-Syntax. (line 17)
-* M68HC11 and M68HC12 support: M68HC11-Dependent. (line 6)
-* M68HC11 assembler directive .far: M68HC11-Directives. (line 20)
-* M68HC11 assembler directive .interrupt: M68HC11-Directives. (line 26)
-* M68HC11 assembler directive .mode: M68HC11-Directives. (line 16)
-* M68HC11 assembler directive .relax: M68HC11-Directives. (line 10)
-* M68HC11 assembler directive .xrefb: M68HC11-Directives. (line 31)
-* M68HC11 assembler directives: M68HC11-Directives. (line 6)
-* M68HC11 branch improvement: M68HC11-Branch. (line 6)
-* M68HC11 floating point: M68HC11-Float. (line 6)
-* M68HC11 modifiers: M68HC11-Modifiers. (line 6)
-* M68HC11 opcodes: M68HC11-opcodes. (line 6)
-* M68HC11 options: M68HC11-Opts. (line 6)
-* M68HC11 pseudo-opcodes: M68HC11-Branch. (line 6)
-* M68HC11 syntax: M68HC11-Syntax. (line 6)
-* M68HC12 assembler directives: M68HC11-Directives. (line 6)
-* machine dependencies: Machine Dependencies.
- (line 6)
-* machine directives, ARC: ARC Directives. (line 6)
-* machine directives, ARM: ARM Directives. (line 6)
-* machine directives, H8/300 (none): H8/300 Directives. (line 6)
-* machine directives, i860: Directives-i860. (line 6)
-* machine directives, i960: Directives-i960. (line 6)
-* machine directives, MSP 430: MSP430 Directives. (line 6)
-* machine directives, SH: SH Directives. (line 6)
-* machine directives, SH64: SH64 Directives. (line 9)
-* machine directives, SPARC: Sparc-Directives. (line 6)
-* machine directives, TIC54X: TIC54X-Directives. (line 6)
-* machine directives, V850: V850 Directives. (line 6)
-* machine directives, VAX: VAX-directives. (line 6)
-* machine independent directives: Pseudo Ops. (line 6)
-* machine instructions (not covered): Manual. (line 14)
-* machine-independent syntax: Syntax. (line 6)
-* macro directive: Macro. (line 28)
-* macro directive, TIC54X: TIC54X-Directives. (line 153)
-* macros: Macro. (line 6)
-* macros, count executed: Macro. (line 143)
-* Macros, MSP 430: MSP430-Macros. (line 6)
-* macros, TIC54X: TIC54X-Macros. (line 6)
-* make rules: MD. (line 6)
-* manual, structure and purpose: Manual. (line 6)
-* math builtins, TIC54X: TIC54X-Builtins. (line 6)
-* Maximum number of continuation lines: listing. (line 34)
-* memory references, i386: i386-Memory. (line 6)
-* memory references, x86-64: i386-Memory. (line 6)
-* memory-mapped registers, TIC54X: TIC54X-MMRegs. (line 6)
-* merging text and data sections: R. (line 6)
-* messages from assembler: Errors. (line 6)
-* minus, permitted arguments: Infix Ops. (line 49)
-* MIPS architecture options: MIPS Opts. (line 29)
-* MIPS big-endian output: MIPS Opts. (line 13)
-* MIPS CPU override: MIPS ISA. (line 18)
-* MIPS debugging directives: MIPS Stabs. (line 6)
-* MIPS DSP Release 1 instruction generation override: MIPS ASE instruction generation overrides.
- (line 21)
-* MIPS DSP Release 2 instruction generation override: MIPS ASE instruction generation overrides.
- (line 26)
-* MIPS ECOFF sections: MIPS Object. (line 6)
-* MIPS endianness: Overview. (line 616)
-* MIPS ISA: Overview. (line 622)
-* MIPS ISA override: MIPS ISA. (line 6)
-* MIPS little-endian output: MIPS Opts. (line 13)
-* MIPS MDMX instruction generation override: MIPS ASE instruction generation overrides.
- (line 16)
-* MIPS MIPS-3D instruction generation override: MIPS ASE instruction generation overrides.
- (line 6)
-* MIPS MT instruction generation override: MIPS ASE instruction generation overrides.
- (line 32)
-* MIPS option stack: MIPS option stack. (line 6)
-* MIPS processor: MIPS-Dependent. (line 6)
-* MIT: M68K-Syntax. (line 6)
-* mlib directive, TIC54X: TIC54X-Directives. (line 159)
-* mlist directive, TIC54X: TIC54X-Directives. (line 164)
-* MMIX assembler directive BSPEC: MMIX-Pseudos. (line 131)
-* MMIX assembler directive BYTE: MMIX-Pseudos. (line 97)
-* MMIX assembler directive ESPEC: MMIX-Pseudos. (line 131)
-* MMIX assembler directive GREG: MMIX-Pseudos. (line 50)
-* MMIX assembler directive IS: MMIX-Pseudos. (line 42)
-* MMIX assembler directive LOC: MMIX-Pseudos. (line 7)
-* MMIX assembler directive LOCAL: MMIX-Pseudos. (line 28)
-* MMIX assembler directive OCTA: MMIX-Pseudos. (line 108)
-* MMIX assembler directive PREFIX: MMIX-Pseudos. (line 120)
-* MMIX assembler directive TETRA: MMIX-Pseudos. (line 108)
-* MMIX assembler directive WYDE: MMIX-Pseudos. (line 108)
-* MMIX assembler directives: MMIX-Pseudos. (line 6)
-* MMIX line comment characters: MMIX-Chars. (line 6)
-* MMIX options: MMIX-Opts. (line 6)
-* MMIX pseudo-op BSPEC: MMIX-Pseudos. (line 131)
-* MMIX pseudo-op BYTE: MMIX-Pseudos. (line 97)
-* MMIX pseudo-op ESPEC: MMIX-Pseudos. (line 131)
-* MMIX pseudo-op GREG: MMIX-Pseudos. (line 50)
-* MMIX pseudo-op IS: MMIX-Pseudos. (line 42)
-* MMIX pseudo-op LOC: MMIX-Pseudos. (line 7)
-* MMIX pseudo-op LOCAL: MMIX-Pseudos. (line 28)
-* MMIX pseudo-op OCTA: MMIX-Pseudos. (line 108)
-* MMIX pseudo-op PREFIX: MMIX-Pseudos. (line 120)
-* MMIX pseudo-op TETRA: MMIX-Pseudos. (line 108)
-* MMIX pseudo-op WYDE: MMIX-Pseudos. (line 108)
-* MMIX pseudo-ops: MMIX-Pseudos. (line 6)
-* MMIX register names: MMIX-Regs. (line 6)
-* MMIX support: MMIX-Dependent. (line 6)
-* mmixal differences: MMIX-mmixal. (line 6)
-* mmregs directive, TIC54X: TIC54X-Directives. (line 170)
-* mmsg directive, TIC54X: TIC54X-Directives. (line 77)
-* MMX, i386: i386-SIMD. (line 6)
-* MMX, x86-64: i386-SIMD. (line 6)
-* mnemonic suffixes, i386: i386-Syntax. (line 29)
-* mnemonic suffixes, x86-64: i386-Syntax. (line 29)
-* mnemonics for opcodes, VAX: VAX-opcodes. (line 6)
-* mnemonics, AVR: AVR Opcodes. (line 6)
-* mnemonics, D10V: D10V-Opcodes. (line 6)
-* mnemonics, D30V: D30V-Opcodes. (line 6)
-* mnemonics, H8/300: H8/300 Opcodes. (line 6)
-* mnemonics, SH: SH Opcodes. (line 6)
-* mnemonics, SH64: SH64 Opcodes. (line 6)
-* mnemonics, Z8000: Z8000 Opcodes. (line 6)
-* mnolist directive, TIC54X: TIC54X-Directives. (line 164)
-* Motorola syntax for the 680x0: M68K-Moto-Syntax. (line 6)
-* MOVI instructions, relaxation: Xtensa Immediate Relaxation.
- (line 12)
-* MOVW and MOVT relocations, ARM: ARM-Relocations. (line 20)
-* MRI compatibility mode: M. (line 6)
-* mri directive: MRI. (line 6)
-* MRI mode, temporarily: MRI. (line 6)
-* MSP 430 floating point (IEEE): MSP430 Floating Point.
- (line 6)
-* MSP 430 identifiers: MSP430-Chars. (line 8)
-* MSP 430 line comment character: MSP430-Chars. (line 6)
-* MSP 430 machine directives: MSP430 Directives. (line 6)
-* MSP 430 macros: MSP430-Macros. (line 6)
-* MSP 430 opcodes: MSP430 Opcodes. (line 6)
-* MSP 430 options (none): MSP430 Options. (line 6)
-* MSP 430 profiling capability: MSP430 Profiling Capability.
- (line 6)
-* MSP 430 register names: MSP430-Regs. (line 6)
-* MSP 430 support: MSP430-Dependent. (line 6)
-* MSP430 Assembler Extensions: MSP430-Ext. (line 6)
-* mul instruction, i386: i386-Notes. (line 6)
-* mul instruction, x86-64: i386-Notes. (line 6)
-* name: Z8000 Directives. (line 18)
-* named section: Section. (line 6)
-* named sections: Ld Sections. (line 8)
-* names, symbol: Symbol Names. (line 6)
-* naming object file: o. (line 6)
-* new page, in listings: Eject. (line 6)
-* newblock directive, TIC54X: TIC54X-Directives. (line 176)
-* newline (\n): Strings. (line 21)
-* newline, required at file end: Statements. (line 13)
-* no-absolute-literals directive: Absolute Literals Directive.
- (line 6)
-* no-longcalls directive: Longcalls Directive. (line 6)
-* no-schedule directive: Schedule Directive. (line 6)
-* no-transform directive: Transform Directive. (line 6)
-* nolist directive: Nolist. (line 6)
-* nolist directive, TIC54X: TIC54X-Directives. (line 131)
-* NOP pseudo op, ARM: ARM Opcodes. (line 9)
-* notes for Alpha: Alpha Notes. (line 6)
-* null-terminated strings: Asciz. (line 6)
-* number constants: Numbers. (line 6)
-* number of macros executed: Macro. (line 143)
-* numbered subsections: Sub-Sections. (line 6)
-* numbers, 16-bit: hword. (line 6)
-* numeric values: Expressions. (line 6)
-* nword directive, SPARC: Sparc-Directives. (line 20)
-* object file: Object. (line 6)
-* object file format: Object Formats. (line 6)
-* object file name: o. (line 6)
-* object file, after errors: Z. (line 6)
-* obsolescent directives: Deprecated. (line 6)
-* octa directive: Octa. (line 6)
-* octal character code (\DDD): Strings. (line 30)
-* octal integers: Integers. (line 9)
-* offset directive, V850: V850 Directives. (line 6)
-* opcode mnemonics, VAX: VAX-opcodes. (line 6)
-* opcode names, Xtensa: Xtensa Opcodes. (line 6)
-* opcode summary, AVR: AVR Opcodes. (line 6)
-* opcode summary, D10V: D10V-Opcodes. (line 6)
-* opcode summary, D30V: D30V-Opcodes. (line 6)
-* opcode summary, H8/300: H8/300 Opcodes. (line 6)
-* opcode summary, SH: SH Opcodes. (line 6)
-* opcode summary, SH64: SH64 Opcodes. (line 6)
-* opcode summary, Z8000: Z8000 Opcodes. (line 6)
-* opcodes for ARC: ARC Opcodes. (line 6)
-* opcodes for ARM: ARM Opcodes. (line 6)
-* opcodes for MSP 430: MSP430 Opcodes. (line 6)
-* opcodes for V850: V850 Opcodes. (line 6)
-* opcodes, i860: Opcodes for i860. (line 6)
-* opcodes, i960: Opcodes for i960. (line 6)
-* opcodes, M680x0: M68K-opcodes. (line 6)
-* opcodes, M68HC11: M68HC11-opcodes. (line 6)
-* operand delimiters, i386: i386-Syntax. (line 15)
-* operand delimiters, x86-64: i386-Syntax. (line 15)
-* operand notation, VAX: VAX-operands. (line 6)
-* operands in expressions: Arguments. (line 6)
-* operator precedence: Infix Ops. (line 11)
-* operators, in expressions: Operators. (line 6)
-* operators, permitted arguments: Infix Ops. (line 6)
-* optimization, D10V: Overview. (line 401)
-* optimization, D30V: Overview. (line 406)
-* optimizations: Xtensa Optimizations.
- (line 6)
-* option directive, ARC: ARC Directives. (line 162)
-* option directive, TIC54X: TIC54X-Directives. (line 180)
-* option summary: Overview. (line 6)
-* options for Alpha: Alpha Options. (line 6)
-* options for ARC (none): ARC Options. (line 6)
-* options for ARM (none): ARM Options. (line 6)
-* options for AVR (none): AVR Options. (line 6)
-* options for i386: i386-Options. (line 6)
-* options for IA-64: IA-64 Options. (line 6)
-* options for MSP430 (none): MSP430 Options. (line 6)
-* options for PDP-11: PDP-11-Options. (line 6)
-* options for PowerPC: PowerPC-Opts. (line 6)
-* options for SPARC: Sparc-Opts. (line 6)
-* options for V850 (none): V850 Options. (line 6)
-* options for VAX/VMS: VAX-Opts. (line 42)
-* options for x86-64: i386-Options. (line 6)
-* options for Z80: Z80 Options. (line 6)
-* options, all versions of assembler: Invoking. (line 6)
-* options, command line: Command Line. (line 13)
-* options, CRIS: CRIS-Opts. (line 6)
-* options, D10V: D10V-Opts. (line 6)
-* options, D30V: D30V-Opts. (line 6)
-* options, H8/300 (none): H8/300 Options. (line 6)
-* options, i960: Options-i960. (line 6)
-* options, IP2K: IP2K-Opts. (line 6)
-* options, M32C: M32C-Opts. (line 6)
-* options, M32R: M32R-Opts. (line 6)
-* options, M680x0: M68K-Opts. (line 6)
-* options, M68HC11: M68HC11-Opts. (line 6)
-* options, MMIX: MMIX-Opts. (line 6)
-* options, PJ: PJ Options. (line 6)
-* options, SH: SH Options. (line 6)
-* options, SH64: SH64 Options. (line 6)
-* options, TIC54X: TIC54X-Opts. (line 6)
-* options, Z8000: Z8000 Options. (line 6)
-* org directive: Org. (line 6)
-* other attribute, of a.out symbol: Symbol Other. (line 6)
-* output file: Object. (line 6)
-* p2align directive: P2align. (line 6)
-* p2alignl directive: P2align. (line 28)
-* p2alignw directive: P2align. (line 28)
-* padding the location counter: Align. (line 6)
-* padding the location counter given a power of two: P2align. (line 6)
-* padding the location counter given number of bytes: Balign. (line 6)
-* page, in listings: Eject. (line 6)
-* paper size, for listings: Psize. (line 6)
-* paths for .include: I. (line 6)
-* patterns, writing in memory: Fill. (line 6)
-* PDP-11 comments: PDP-11-Syntax. (line 16)
-* PDP-11 floating-point register syntax: PDP-11-Syntax. (line 13)
-* PDP-11 general-purpose register syntax: PDP-11-Syntax. (line 10)
-* PDP-11 instruction naming: PDP-11-Mnemonics. (line 6)
-* PDP-11 support: PDP-11-Dependent. (line 6)
-* PDP-11 syntax: PDP-11-Syntax. (line 6)
-* PIC code generation for ARM: ARM Options. (line 120)
-* PIC code generation for M32R: M32R-Opts. (line 42)
-* PIC selection, MIPS: MIPS Opts. (line 21)
-* PJ endianness: Overview. (line 523)
-* PJ options: PJ Options. (line 6)
-* PJ support: PJ-Dependent. (line 6)
-* plus, permitted arguments: Infix Ops. (line 44)
-* popsection directive: PopSection. (line 6)
-* Position-independent code, CRIS: CRIS-Opts. (line 27)
-* Position-independent code, symbols in, CRIS: CRIS-Pic. (line 6)
-* PowerPC architectures: PowerPC-Opts. (line 6)
-* PowerPC directives: PowerPC-Pseudo. (line 6)
-* PowerPC options: PowerPC-Opts. (line 6)
-* PowerPC support: PPC-Dependent. (line 6)
-* precedence of operators: Infix Ops. (line 11)
-* precision, floating point: Flonums. (line 6)
-* prefix operators: Prefix Ops. (line 6)
-* prefixes, i386: i386-Prefixes. (line 6)
-* preprocessing: Preprocessing. (line 6)
-* preprocessing, turning on and off: Preprocessing. (line 27)
-* previous directive: Previous. (line 6)
-* primary attributes, COFF symbols: COFF Symbols. (line 13)
-* print directive: Print. (line 6)
-* proc directive, SPARC: Sparc-Directives. (line 25)
-* profiler directive, MSP 430: MSP430 Directives. (line 22)
-* profiling capability for MSP 430: MSP430 Profiling Capability.
- (line 6)
-* protected directive: Protected. (line 6)
-* pseudo-op .arch, CRIS: CRIS-Pseudos. (line 45)
-* pseudo-op .dword, CRIS: CRIS-Pseudos. (line 12)
-* pseudo-op .syntax, CRIS: CRIS-Pseudos. (line 17)
-* pseudo-op BSPEC, MMIX: MMIX-Pseudos. (line 131)
-* pseudo-op BYTE, MMIX: MMIX-Pseudos. (line 97)
-* pseudo-op ESPEC, MMIX: MMIX-Pseudos. (line 131)
-* pseudo-op GREG, MMIX: MMIX-Pseudos. (line 50)
-* pseudo-op IS, MMIX: MMIX-Pseudos. (line 42)
-* pseudo-op LOC, MMIX: MMIX-Pseudos. (line 7)
-* pseudo-op LOCAL, MMIX: MMIX-Pseudos. (line 28)
-* pseudo-op OCTA, MMIX: MMIX-Pseudos. (line 108)
-* pseudo-op PREFIX, MMIX: MMIX-Pseudos. (line 120)
-* pseudo-op TETRA, MMIX: MMIX-Pseudos. (line 108)
-* pseudo-op WYDE, MMIX: MMIX-Pseudos. (line 108)
-* pseudo-opcodes, M680x0: M68K-Branch. (line 6)
-* pseudo-opcodes, M68HC11: M68HC11-Branch. (line 6)
-* pseudo-ops for branch, VAX: VAX-branch. (line 6)
-* pseudo-ops, CRIS: CRIS-Pseudos. (line 6)
-* pseudo-ops, machine independent: Pseudo Ops. (line 6)
-* pseudo-ops, MMIX: MMIX-Pseudos. (line 6)
-* psize directive: Psize. (line 6)
-* PSR bits: IA-64-Bits. (line 6)
-* pstring directive, TIC54X: TIC54X-Directives. (line 209)
-* psw register, V850: V850-Regs. (line 116)
-* purgem directive: Purgem. (line 6)
-* purpose of GNU assembler: GNU Assembler. (line 12)
-* pushsection directive: PushSection. (line 6)
-* quad directive: Quad. (line 6)
-* quad directive, i386: i386-Float. (line 21)
-* quad directive, x86-64: i386-Float. (line 21)
-* real-mode code, i386: i386-16bit. (line 6)
-* ref directive, TIC54X: TIC54X-Directives. (line 103)
-* register directive, SPARC: Sparc-Directives. (line 29)
-* register names, Alpha: Alpha-Regs. (line 6)
-* register names, ARC: ARC-Regs. (line 6)
-* register names, ARM: ARM-Regs. (line 6)
-* register names, AVR: AVR-Regs. (line 6)
-* register names, CRIS: CRIS-Regs. (line 6)
-* register names, H8/300: H8/300-Regs. (line 6)
-* register names, IA-64: IA-64-Regs. (line 6)
-* register names, MMIX: MMIX-Regs. (line 6)
-* register names, MSP 430: MSP430-Regs. (line 6)
-* register names, V850: V850-Regs. (line 6)
-* register names, VAX: VAX-operands. (line 17)
-* register names, Xtensa: Xtensa Registers. (line 6)
-* register names, Z80: Z80-Regs. (line 6)
-* register operands, i386: i386-Syntax. (line 15)
-* register operands, x86-64: i386-Syntax. (line 15)
-* registers, D10V: D10V-Regs. (line 6)
-* registers, D30V: D30V-Regs. (line 6)
-* registers, i386: i386-Regs. (line 6)
-* registers, SH: SH-Regs. (line 6)
-* registers, SH64: SH64-Regs. (line 6)
-* registers, TIC54X memory-mapped: TIC54X-MMRegs. (line 6)
-* registers, x86-64: i386-Regs. (line 6)
-* registers, Z8000: Z8000-Regs. (line 6)
-* relaxation: Xtensa Relaxation. (line 6)
-* relaxation of ADDI instructions: Xtensa Immediate Relaxation.
- (line 43)
-* relaxation of branch instructions: Xtensa Branch Relaxation.
- (line 6)
-* relaxation of call instructions: Xtensa Call Relaxation.
- (line 6)
-* relaxation of immediate fields: Xtensa Immediate Relaxation.
- (line 6)
-* relaxation of L16SI instructions: Xtensa Immediate Relaxation.
- (line 23)
-* relaxation of L16UI instructions: Xtensa Immediate Relaxation.
- (line 23)
-* relaxation of L32I instructions: Xtensa Immediate Relaxation.
- (line 23)
-* relaxation of L8UI instructions: Xtensa Immediate Relaxation.
- (line 23)
-* relaxation of MOVI instructions: Xtensa Immediate Relaxation.
- (line 12)
-* reloc directive: Reloc. (line 6)
-* relocation: Sections. (line 6)
-* relocation example: Ld Sections. (line 40)
-* relocations, Alpha: Alpha-Relocs. (line 6)
-* repeat prefixes, i386: i386-Prefixes. (line 44)
-* reporting bugs in assembler: Reporting Bugs. (line 6)
-* rept directive: Rept. (line 6)
-* req directive, ARM: ARM Directives. (line 13)
-* reserve directive, SPARC: Sparc-Directives. (line 39)
-* return instructions, i386: i386-Syntax. (line 38)
-* return instructions, x86-64: i386-Syntax. (line 38)
-* REX prefixes, i386: i386-Prefixes. (line 46)
-* rsect: Z8000 Directives. (line 52)
-* sblock directive, TIC54X: TIC54X-Directives. (line 183)
-* sbttl directive: Sbttl. (line 6)
-* schedule directive: Schedule Directive. (line 6)
-* scl directive: Scl. (line 6)
-* sdaoff pseudo-op, V850: V850 Opcodes. (line 65)
-* search path for .include: I. (line 6)
-* sect directive, MSP 430: MSP430 Directives. (line 18)
-* sect directive, TIC54X: TIC54X-Directives. (line 189)
-* section directive (COFF version): Section. (line 16)
-* section directive (ELF version): Section. (line 67)
-* section directive, V850: V850 Directives. (line 9)
-* section override prefixes, i386: i386-Prefixes. (line 23)
-* Section Stack <1>: SubSection. (line 6)
-* Section Stack <2>: Section. (line 62)
-* Section Stack <3>: PushSection. (line 6)
-* Section Stack <4>: PopSection. (line 6)
-* Section Stack: Previous. (line 6)
-* section-relative addressing: Secs Background. (line 68)
-* sections: Sections. (line 6)
-* sections in messages, internal: As Sections. (line 6)
-* sections, i386: i386-Syntax. (line 44)
-* sections, named: Ld Sections. (line 8)
-* sections, x86-64: i386-Syntax. (line 44)
-* seg directive, SPARC: Sparc-Directives. (line 44)
-* segm: Z8000 Directives. (line 10)
-* set directive: Set. (line 6)
-* set directive, TIC54X: TIC54X-Directives. (line 192)
-* SH addressing modes: SH-Addressing. (line 6)
-* SH floating point (IEEE): SH Floating Point. (line 6)
-* SH line comment character: SH-Chars. (line 6)
-* SH line separator: SH-Chars. (line 8)
-* SH machine directives: SH Directives. (line 6)
-* SH opcode summary: SH Opcodes. (line 6)
-* SH options: SH Options. (line 6)
-* SH registers: SH-Regs. (line 6)
-* SH support: SH-Dependent. (line 6)
-* SH64 ABI options: SH64 Options. (line 29)
-* SH64 addressing modes: SH64-Addressing. (line 6)
-* SH64 ISA options: SH64 Options. (line 6)
-* SH64 line comment character: SH64-Chars. (line 6)
-* SH64 line separator: SH64-Chars. (line 8)
-* SH64 machine directives: SH64 Directives. (line 9)
-* SH64 opcode summary: SH64 Opcodes. (line 6)
-* SH64 options: SH64 Options. (line 6)
-* SH64 registers: SH64-Regs. (line 6)
-* SH64 support: SH64-Dependent. (line 6)
-* shigh directive, M32R: M32R-Directives. (line 26)
-* short directive: Short. (line 6)
-* short directive, ARC: ARC Directives. (line 171)
-* short directive, TIC54X: TIC54X-Directives. (line 111)
-* SIMD, i386: i386-SIMD. (line 6)
-* SIMD, x86-64: i386-SIMD. (line 6)
-* single character constant: Chars. (line 6)
-* single directive: Single. (line 6)
-* single directive, i386: i386-Float. (line 14)
-* single directive, x86-64: i386-Float. (line 14)
-* single quote, Z80: Z80-Chars. (line 13)
-* sixteen bit integers: hword. (line 6)
-* sixteen byte integer: Octa. (line 6)
-* size directive (COFF version): Size. (line 11)
-* size directive (ELF version): Size. (line 19)
-* size modifiers, D10V: D10V-Size. (line 6)
-* size modifiers, D30V: D30V-Size. (line 6)
-* size modifiers, M680x0: M68K-Syntax. (line 8)
-* size prefixes, i386: i386-Prefixes. (line 27)
-* size suffixes, H8/300: H8/300 Opcodes. (line 163)
-* sizes operands, i386: i386-Syntax. (line 29)
-* sizes operands, x86-64: i386-Syntax. (line 29)
-* skip directive: Skip. (line 6)
-* skip directive, M680x0: M68K-Directives. (line 19)
-* skip directive, SPARC: Sparc-Directives. (line 48)
-* sleb128 directive: Sleb128. (line 6)
-* small objects, MIPS ECOFF: MIPS Object. (line 11)
-* SmartMIPS instruction generation override: MIPS ASE instruction generation overrides.
- (line 11)
-* SOM symbol attributes: SOM Symbols. (line 6)
-* source program: Input Files. (line 6)
-* source, destination operands; i386: i386-Syntax. (line 22)
-* source, destination operands; x86-64: i386-Syntax. (line 22)
-* sp register: Xtensa Registers. (line 6)
-* sp register, V850: V850-Regs. (line 14)
-* space directive: Space. (line 6)
-* space directive, TIC54X: TIC54X-Directives. (line 197)
-* space used, maximum for assembly: statistics. (line 6)
-* SPARC architectures: Sparc-Opts. (line 6)
-* SPARC data alignment: Sparc-Aligned-Data. (line 6)
-* SPARC floating point (IEEE): Sparc-Float. (line 6)
-* SPARC machine directives: Sparc-Directives. (line 6)
-* SPARC options: Sparc-Opts. (line 6)
-* SPARC support: Sparc-Dependent. (line 6)
-* special characters, ARC: ARC-Chars. (line 6)
-* special characters, M680x0: M68K-Chars. (line 6)
-* special purpose registers, MSP 430: MSP430-Regs. (line 11)
-* sslist directive, TIC54X: TIC54X-Directives. (line 204)
-* ssnolist directive, TIC54X: TIC54X-Directives. (line 204)
-* stabd directive: Stab. (line 38)
-* stabn directive: Stab. (line 48)
-* stabs directive: Stab. (line 51)
-* stabX directives: Stab. (line 6)
-* standard assembler sections: Secs Background. (line 27)
-* standard input, as input file: Command Line. (line 10)
-* statement separator character: Statements. (line 6)
-* statement separator, Alpha: Alpha-Chars. (line 8)
-* statement separator, ARM: ARM-Chars. (line 10)
-* statement separator, AVR: AVR-Chars. (line 10)
-* statement separator, H8/300: H8/300-Chars. (line 8)
-* statement separator, IA-64: IA-64-Chars. (line 8)
-* statement separator, SH: SH-Chars. (line 8)
-* statement separator, SH64: SH64-Chars. (line 8)
-* statement separator, Z8000: Z8000-Chars. (line 8)
-* statements, structure of: Statements. (line 6)
-* statistics, about assembly: statistics. (line 6)
-* stopping the assembly: Abort. (line 6)
-* string constants: Strings. (line 6)
-* string directive: String. (line 6)
-* string directive on HPPA: HPPA Directives. (line 137)
-* string directive, TIC54X: TIC54X-Directives. (line 209)
-* string literals: Ascii. (line 6)
-* string, copying to object file: String. (line 6)
-* struct directive: Struct. (line 6)
-* struct directive, TIC54X: TIC54X-Directives. (line 217)
-* structure debugging, COFF: Tag. (line 6)
-* sub-instruction ordering, D10V: D10V-Chars. (line 6)
-* sub-instruction ordering, D30V: D30V-Chars. (line 6)
-* sub-instructions, D10V: D10V-Subs. (line 6)
-* sub-instructions, D30V: D30V-Subs. (line 6)
-* subexpressions: Arguments. (line 24)
-* subsection directive: SubSection. (line 6)
-* subsym builtins, TIC54X: TIC54X-Macros. (line 16)
-* subtitles for listings: Sbttl. (line 6)
-* subtraction, permitted arguments: Infix Ops. (line 49)
-* summary of options: Overview. (line 6)
-* support: HPPA-Dependent. (line 6)
-* supporting files, including: Include. (line 6)
-* suppressing warnings: W. (line 11)
-* sval: Z8000 Directives. (line 33)
-* symbol attributes: Symbol Attributes. (line 6)
-* symbol attributes, a.out: a.out Symbols. (line 6)
-* symbol attributes, COFF: COFF Symbols. (line 6)
-* symbol attributes, SOM: SOM Symbols. (line 6)
-* symbol descriptor, COFF: Desc. (line 6)
-* symbol modifiers <1>: M68HC11-Modifiers. (line 12)
-* symbol modifiers <2>: M32C-Modifiers. (line 11)
-* symbol modifiers: AVR-Modifiers. (line 12)
-* symbol names: Symbol Names. (line 6)
-* symbol names, $ in <1>: SH64-Chars. (line 10)
-* symbol names, $ in <2>: SH-Chars. (line 10)
-* symbol names, $ in <3>: D30V-Chars. (line 63)
-* symbol names, $ in: D10V-Chars. (line 46)
-* symbol names, local: Symbol Names. (line 22)
-* symbol names, temporary: Symbol Names. (line 35)
-* symbol storage class (COFF): Scl. (line 6)
-* symbol type: Symbol Type. (line 6)
-* symbol type, COFF: Type. (line 11)
-* symbol type, ELF: Type. (line 22)
-* symbol value: Symbol Value. (line 6)
-* symbol value, setting: Set. (line 6)
-* symbol values, assigning: Setting Symbols. (line 6)
-* symbol versioning: Symver. (line 6)
-* symbol, common: Comm. (line 6)
-* symbol, making visible to linker: Global. (line 6)
-* symbolic debuggers, information for: Stab. (line 6)
-* symbols: Symbols. (line 6)
-* Symbols in position-independent code, CRIS: CRIS-Pic. (line 6)
-* symbols with uppercase, VAX/VMS: VAX-Opts. (line 42)
-* symbols, assigning values to: Equ. (line 6)
-* Symbols, built-in, CRIS: CRIS-Symbols. (line 6)
-* Symbols, CRIS, built-in: CRIS-Symbols. (line 6)
-* symbols, local common: Lcomm. (line 6)
-* symver directive: Symver. (line 6)
-* syntax compatibility, i386: i386-Syntax. (line 6)
-* syntax compatibility, x86-64: i386-Syntax. (line 6)
-* syntax, AVR: AVR-Modifiers. (line 6)
-* syntax, BFIN: BFIN Syntax. (line 6)
-* syntax, D10V: D10V-Syntax. (line 6)
-* syntax, D30V: D30V-Syntax. (line 6)
-* syntax, M32C: M32C-Modifiers. (line 6)
-* syntax, M680x0: M68K-Syntax. (line 8)
-* syntax, M68HC11 <1>: M68HC11-Modifiers. (line 6)
-* syntax, M68HC11: M68HC11-Syntax. (line 6)
-* syntax, machine-independent: Syntax. (line 6)
-* syntax, Xtensa assembler: Xtensa Syntax. (line 6)
-* sysproc directive, i960: Directives-i960. (line 37)
-* tab (\t): Strings. (line 27)
-* tab directive, TIC54X: TIC54X-Directives. (line 248)
-* tag directive: Tag. (line 6)
-* tag directive, TIC54X: TIC54X-Directives. (line 217)
-* tdaoff pseudo-op, V850: V850 Opcodes. (line 81)
-* temporary symbol names: Symbol Names. (line 35)
-* text and data sections, joining: R. (line 6)
-* text directive: Text. (line 6)
-* text section: Ld Sections. (line 9)
-* tfloat directive, i386: i386-Float. (line 14)
-* tfloat directive, x86-64: i386-Float. (line 14)
-* thumb directive, ARM: ARM Directives. (line 57)
-* Thumb support: ARM-Dependent. (line 6)
-* thumb_func directive, ARM: ARM Directives. (line 67)
-* thumb_set directive, ARM: ARM Directives. (line 78)
-* TIC54X builtin math functions: TIC54X-Builtins. (line 6)
-* TIC54X machine directives: TIC54X-Directives. (line 6)
-* TIC54X memory-mapped registers: TIC54X-MMRegs. (line 6)
-* TIC54X options: TIC54X-Opts. (line 6)
-* TIC54X subsym builtins: TIC54X-Macros. (line 16)
-* TIC54X support: TIC54X-Dependent. (line 6)
-* TIC54X-specific macros: TIC54X-Macros. (line 6)
-* time, total for assembly: statistics. (line 6)
-* title directive: Title. (line 6)
-* tp register, V850: V850-Regs. (line 20)
-* transform directive: Transform Directive. (line 6)
-* trusted compiler: f. (line 6)
-* turning preprocessing on and off: Preprocessing. (line 27)
-* type directive (COFF version): Type. (line 11)
-* type directive (ELF version): Type. (line 22)
-* type of a symbol: Symbol Type. (line 6)
-* ualong directive, SH: SH Directives. (line 6)
-* uaword directive, SH: SH Directives. (line 6)
-* ubyte directive, TIC54X: TIC54X-Directives. (line 36)
-* uchar directive, TIC54X: TIC54X-Directives. (line 36)
-* uhalf directive, TIC54X: TIC54X-Directives. (line 111)
-* uint directive, TIC54X: TIC54X-Directives. (line 111)
-* uleb128 directive: Uleb128. (line 6)
-* ulong directive, TIC54X: TIC54X-Directives. (line 135)
-* undefined section: Ld Sections. (line 36)
-* union directive, TIC54X: TIC54X-Directives. (line 251)
-* unreq directive, ARM: ARM Directives. (line 18)
-* unsegm: Z8000 Directives. (line 14)
-* usect directive, TIC54X: TIC54X-Directives. (line 263)
-* ushort directive, TIC54X: TIC54X-Directives. (line 111)
-* uword directive, TIC54X: TIC54X-Directives. (line 111)
-* V850 command line options: V850 Options. (line 9)
-* V850 floating point (IEEE): V850 Floating Point. (line 6)
-* V850 line comment character: V850-Chars. (line 6)
-* V850 machine directives: V850 Directives. (line 6)
-* V850 opcodes: V850 Opcodes. (line 6)
-* V850 options (none): V850 Options. (line 6)
-* V850 register names: V850-Regs. (line 6)
-* V850 support: V850-Dependent. (line 6)
-* val directive: Val. (line 6)
-* value attribute, COFF: Val. (line 6)
-* value of a symbol: Symbol Value. (line 6)
-* var directive, TIC54X: TIC54X-Directives. (line 273)
-* VAX bitfields not supported: VAX-no. (line 6)
-* VAX branch improvement: VAX-branch. (line 6)
-* VAX command-line options ignored: VAX-Opts. (line 6)
-* VAX displacement sizing character: VAX-operands. (line 12)
-* VAX floating point: VAX-float. (line 6)
-* VAX immediate character: VAX-operands. (line 6)
-* VAX indirect character: VAX-operands. (line 9)
-* VAX machine directives: VAX-directives. (line 6)
-* VAX opcode mnemonics: VAX-opcodes. (line 6)
-* VAX operand notation: VAX-operands. (line 6)
-* VAX register names: VAX-operands. (line 17)
-* VAX support: Vax-Dependent. (line 6)
-* Vax-11 C compatibility: VAX-Opts. (line 42)
-* VAX/VMS options: VAX-Opts. (line 42)
-* version directive: Version. (line 6)
-* version directive, TIC54X: TIC54X-Directives. (line 277)
-* version of assembler: v. (line 6)
-* versions of symbols: Symver. (line 6)
-* visibility <1>: Protected. (line 6)
-* visibility <2>: Internal. (line 6)
-* visibility: Hidden. (line 6)
-* VMS (VAX) options: VAX-Opts. (line 42)
-* vtable_entry directive: VTableEntry. (line 6)
-* vtable_inherit directive: VTableInherit. (line 6)
-* warning directive: Warning. (line 6)
-* warning for altered difference tables: K. (line 6)
-* warning messages: Errors. (line 6)
-* warnings, causing error: W. (line 16)
-* warnings, M32R: M32R-Warnings. (line 6)
-* warnings, suppressing: W. (line 11)
-* warnings, switching on: W. (line 19)
-* weak directive: Weak. (line 6)
-* weakref directive: Weakref. (line 6)
-* whitespace: Whitespace. (line 6)
-* whitespace, removed by preprocessor: Preprocessing. (line 7)
-* wide floating point directives, VAX: VAX-directives. (line 10)
-* width directive, TIC54X: TIC54X-Directives. (line 127)
-* Width of continuation lines of disassembly output: listing. (line 21)
-* Width of first line disassembly output: listing. (line 16)
-* Width of source line output: listing. (line 28)
-* wmsg directive, TIC54X: TIC54X-Directives. (line 77)
-* word directive: Word. (line 6)
-* word directive, ARC: ARC Directives. (line 174)
-* word directive, H8/300: H8/300 Directives. (line 6)
-* word directive, i386: i386-Float. (line 21)
-* word directive, SPARC: Sparc-Directives. (line 51)
-* word directive, TIC54X: TIC54X-Directives. (line 111)
-* word directive, x86-64: i386-Float. (line 21)
-* writing patterns in memory: Fill. (line 6)
-* wval: Z8000 Directives. (line 24)
-* x86-64 arch directive: i386-Arch. (line 6)
-* x86-64 att_syntax pseudo op: i386-Syntax. (line 6)
-* x86-64 conversion instructions: i386-Mnemonics. (line 32)
-* x86-64 floating point: i386-Float. (line 6)
-* x86-64 immediate operands: i386-Syntax. (line 15)
-* x86-64 instruction naming: i386-Mnemonics. (line 6)
-* x86-64 intel_syntax pseudo op: i386-Syntax. (line 6)
-* x86-64 jump optimization: i386-Jumps. (line 6)
-* x86-64 jump, call, return: i386-Syntax. (line 38)
-* x86-64 jump/call operands: i386-Syntax. (line 15)
-* x86-64 memory references: i386-Memory. (line 6)
-* x86-64 options: i386-Options. (line 6)
-* x86-64 register operands: i386-Syntax. (line 15)
-* x86-64 registers: i386-Regs. (line 6)
-* x86-64 sections: i386-Syntax. (line 44)
-* x86-64 size suffixes: i386-Syntax. (line 29)
-* x86-64 source, destination operands: i386-Syntax. (line 22)
-* x86-64 support: i386-Dependent. (line 6)
-* x86-64 syntax compatibility: i386-Syntax. (line 6)
-* xfloat directive, TIC54X: TIC54X-Directives. (line 64)
-* xlong directive, TIC54X: TIC54X-Directives. (line 135)
-* Xtensa architecture: Xtensa-Dependent. (line 6)
-* Xtensa assembler syntax: Xtensa Syntax. (line 6)
-* Xtensa directives: Xtensa Directives. (line 6)
-* Xtensa opcode names: Xtensa Opcodes. (line 6)
-* Xtensa register names: Xtensa Registers. (line 6)
-* xword directive, SPARC: Sparc-Directives. (line 55)
-* Z80 $: Z80-Chars. (line 8)
-* Z80 ': Z80-Chars. (line 13)
-* Z80 floating point: Z80 Floating Point. (line 6)
-* Z80 line comment character: Z80-Chars. (line 6)
-* Z80 options: Z80 Options. (line 6)
-* Z80 registers: Z80-Regs. (line 6)
-* Z80 support: Z80-Dependent. (line 6)
-* Z80 Syntax: Z80 Options. (line 47)
-* Z80, \: Z80-Chars. (line 11)
-* Z80, case sensitivity: Z80-Case. (line 6)
-* Z80-only directives: Z80 Directives. (line 9)
-* Z800 addressing modes: Z8000-Addressing. (line 6)
-* Z8000 directives: Z8000 Directives. (line 6)
-* Z8000 line comment character: Z8000-Chars. (line 6)
-* Z8000 line separator: Z8000-Chars. (line 8)
-* Z8000 opcode summary: Z8000 Opcodes. (line 6)
-* Z8000 options: Z8000 Options. (line 6)
-* Z8000 registers: Z8000-Regs. (line 6)
-* Z8000 support: Z8000-Dependent. (line 6)
-* zdaoff pseudo-op, V850: V850 Opcodes. (line 99)
-* zero register, V850: V850-Regs. (line 7)
-* zero-terminated strings: Asciz. (line 6)
-
-
-\1f
-Tag Table:
-Node: Top\7f758
-Node: Overview\7f1696
-Node: Manual\7f29138
-Node: GNU Assembler\7f30082
-Node: Object Formats\7f31253
-Node: Command Line\7f31705
-Node: Input Files\7f32792
-Node: Object\7f34773
-Node: Errors\7f35669
-Node: Invoking\7f36864
-Node: a\7f38818
-Node: alternate\7f40593
-Node: D\7f40765
-Node: f\7f40998
-Node: I\7f41506
-Node: K\7f42050
-Node: L\7f42354
-Node: listing\7f43093
-Node: M\7f44752
-Node: MD\7f49153
-Node: o\7f49579
-Node: R\7f50034
-Node: statistics\7f51064
-Node: traditional-format\7f51471
-Node: v\7f51944
-Node: W\7f52219
-Node: Z\7f53126
-Node: Syntax\7f53648
-Node: Preprocessing\7f54239
-Node: Whitespace\7f55802
-Node: Comments\7f56198
-Node: Symbol Intro\7f58351
-Node: Statements\7f59041
-Node: Constants\7f60962
-Node: Characters\7f61593
-Node: Strings\7f62095
-Node: Chars\7f64261
-Node: Numbers\7f65015
-Node: Integers\7f65555
-Node: Bignums\7f66211
-Node: Flonums\7f66567
-Node: Sections\7f68314
-Node: Secs Background\7f68692
-Node: Ld Sections\7f73731
-Node: As Sections\7f76115
-Node: Sub-Sections\7f77025
-Node: bss\7f80170
-Node: Symbols\7f81120
-Node: Labels\7f81768
-Node: Setting Symbols\7f82499
-Node: Symbol Names\7f82995
-Node: Dot\7f88058
-Node: Symbol Attributes\7f88505
-Node: Symbol Value\7f89242
-Node: Symbol Type\7f90287
-Node: a.out Symbols\7f90675
-Node: Symbol Desc\7f90937
-Node: Symbol Other\7f91232
-Node: COFF Symbols\7f91401
-Node: SOM Symbols\7f92074
-Node: Expressions\7f92516
-Node: Empty Exprs\7f93265
-Node: Integer Exprs\7f93612
-Node: Arguments\7f94007
-Node: Operators\7f95113
-Node: Prefix Ops\7f95448
-Node: Infix Ops\7f95776
-Node: Pseudo Ops\7f98166
-Node: Abort\7f103439
-Node: ABORT (COFF)\7f103851
-Node: Align\7f104059
-Node: Ascii\7f106348
-Node: Asciz\7f106657
-Node: Balign\7f106902
-Node: Byte\7f108765
-Node: Comm\7f109003
-Node: CFI directives\7f110377
-Node: LNS directives\7f114971
-Node: Data\7f117046
-Node: Def\7f117373
-Node: Desc\7f117605
-Node: Dim\7f118105
-Node: Double\7f118362
-Node: Eject\7f118700
-Node: Else\7f118875
-Node: Elseif\7f119175
-Node: End\7f119469
-Node: Endef\7f119684
-Node: Endfunc\7f119861
-Node: Endif\7f120036
-Node: Equ\7f120297
-Node: Equiv\7f120811
-Node: Eqv\7f121367
-Node: Err\7f121731
-Node: Error\7f122042
-Node: Exitm\7f122487
-Node: Extern\7f122656
-Node: Fail\7f122917
-Node: File\7f123362
-Node: Fill\7f123839
-Node: Float\7f124803
-Node: Func\7f125145
-Node: Global\7f125735
-Node: Hidden\7f126485
-Node: hword\7f127064
-Node: Ident\7f127392
-Node: If\7f127966
-Node: Incbin\7f131025
-Node: Include\7f131720
-Node: Int\7f132271
-Node: Internal\7f132652
-Node: Irp\7f133300
-Node: Irpc\7f134179
-Node: Lcomm\7f135096
-Node: Lflags\7f135844
-Node: Line\7f136038
-Node: Linkonce\7f136957
-Node: Ln\7f138186
-Node: MRI\7f138347
-Node: List\7f138685
-Node: Long\7f139293
-Node: Macro\7f139480
-Node: Altmacro\7f145402
-Node: Noaltmacro\7f146733
-Node: Nolist\7f146902
-Node: Octa\7f147332
-Node: Org\7f147666
-Node: P2align\7f148949
-Node: Previous\7f150877
-Node: PopSection\7f151571
-Node: Print\7f152079
-Node: Protected\7f152308
-Node: Psize\7f152955
-Node: Purgem\7f153639
-Node: PushSection\7f153860
-Node: Quad\7f154417
-Node: Reloc\7f154873
-Node: Rept\7f155634
-Node: Sbttl\7f156048
-Node: Scl\7f156413
-Node: Section\7f156754
-Node: Set\7f161891
-Node: Short\7f162528
-Node: Single\7f162849
-Node: Size\7f163194
-Node: Sleb128\7f163866
-Node: Skip\7f164188
-Node: Space\7f164510
-Node: Stab\7f165151
-Node: String\7f167155
-Node: Struct\7f167583
-Node: SubSection\7f168308
-Node: Symver\7f168871
-Node: Tag\7f171264
-Node: Text\7f171646
-Node: Title\7f171967
-Node: Type\7f172348
-Node: Uleb128\7f173814
-Node: Val\7f174138
-Node: Version\7f174388
-Node: VTableEntry\7f174663
-Node: VTableInherit\7f174953
-Node: Warning\7f175403
-Node: Weak\7f175637
-Node: Weakref\7f176306
-Node: Word\7f177271
-Node: Deprecated\7f179117
-Node: Machine Dependencies\7f179352
-Node: Alpha-Dependent\7f182229
-Node: Alpha Notes\7f182643
-Node: Alpha Options\7f182924
-Node: Alpha Syntax\7f185122
-Node: Alpha-Chars\7f185591
-Node: Alpha-Regs\7f185822
-Node: Alpha-Relocs\7f186209
-Node: Alpha Floating Point\7f192467
-Node: Alpha Directives\7f192689
-Node: Alpha Opcodes\7f198212
-Node: ARC-Dependent\7f198507
-Node: ARC Options\7f198890
-Node: ARC Syntax\7f199959
-Node: ARC-Chars\7f200191
-Node: ARC-Regs\7f200323
-Node: ARC Floating Point\7f200447
-Node: ARC Directives\7f200758
-Node: ARC Opcodes\7f206729
-Node: ARM-Dependent\7f206955
-Node: ARM Options\7f207381
-Node: ARM Syntax\7f213177
-Node: ARM-Chars\7f213446
-Node: ARM-Regs\7f213970
-Node: ARM Floating Point\7f214179
-Node: ARM-Relocations\7f214378
-Node: ARM Directives\7f215331
-Node: ARM Opcodes\7f223717
-Node: ARM Mapping Symbols\7f225805
-Node: AVR-Dependent\7f226584
-Node: AVR Options\7f226870
-Node: AVR Syntax\7f229076
-Node: AVR-Chars\7f229363
-Node: AVR-Regs\7f229769
-Node: AVR-Modifiers\7f230348
-Node: AVR Opcodes\7f232408
-Node: BFIN-Dependent\7f237654
-Node: BFIN Syntax\7f237908
-Node: BFIN Directives\7f243604
-Node: CR16-Dependent\7f244011
-Node: CR16 Operand Qualifiers\7f244255
-Node: CRIS-Dependent\7f246021
-Node: CRIS-Opts\7f246367
-Ref: march-option\7f247985
-Node: CRIS-Expand\7f249802
-Node: CRIS-Symbols\7f250985
-Node: CRIS-Syntax\7f252154
-Node: CRIS-Chars\7f252490
-Node: CRIS-Pic\7f253041
-Ref: crispic\7f253237
-Node: CRIS-Regs\7f256777
-Node: CRIS-Pseudos\7f257194
-Ref: crisnous\7f257970
-Node: D10V-Dependent\7f259252
-Node: D10V-Opts\7f259603
-Node: D10V-Syntax\7f260566
-Node: D10V-Size\7f261095
-Node: D10V-Subs\7f262068
-Node: D10V-Chars\7f263103
-Node: D10V-Regs\7f264707
-Node: D10V-Addressing\7f265752
-Node: D10V-Word\7f266438
-Node: D10V-Float\7f266953
-Node: D10V-Opcodes\7f267264
-Node: D30V-Dependent\7f267657
-Node: D30V-Opts\7f268010
-Node: D30V-Syntax\7f268685
-Node: D30V-Size\7f269217
-Node: D30V-Subs\7f270188
-Node: D30V-Chars\7f271223
-Node: D30V-Guarded\7f273521
-Node: D30V-Regs\7f274201
-Node: D30V-Addressing\7f275340
-Node: D30V-Float\7f276008
-Node: D30V-Opcodes\7f276319
-Node: H8/300-Dependent\7f276712
-Node: H8/300 Options\7f277124
-Node: H8/300 Syntax\7f277335
-Node: H8/300-Chars\7f277636
-Node: H8/300-Regs\7f277935
-Node: H8/300-Addressing\7f278854
-Node: H8/300 Floating Point\7f279895
-Node: H8/300 Directives\7f280222
-Node: H8/300 Opcodes\7f281350
-Node: HPPA-Dependent\7f289672
-Node: HPPA Notes\7f290107
-Node: HPPA Options\7f290865
-Node: HPPA Syntax\7f291060
-Node: HPPA Floating Point\7f292330
-Node: HPPA Directives\7f292536
-Node: HPPA Opcodes\7f301222
-Node: ESA/390-Dependent\7f301481
-Node: ESA/390 Notes\7f301941
-Node: ESA/390 Options\7f302732
-Node: ESA/390 Syntax\7f302942
-Node: ESA/390 Floating Point\7f305115
-Node: ESA/390 Directives\7f305394
-Node: ESA/390 Opcodes\7f308683
-Node: i386-Dependent\7f308945
-Node: i386-Options\7f310013
-Node: i386-Syntax\7f312018
-Node: i386-Mnemonics\7f314432
-Node: i386-Regs\7f316897
-Node: i386-Prefixes\7f318942
-Node: i386-Memory\7f321702
-Node: i386-Jumps\7f324639
-Node: i386-Float\7f325760
-Node: i386-SIMD\7f327589
-Node: i386-16bit\7f328698
-Node: i386-Bugs\7f330738
-Node: i386-Arch\7f331492
-Node: i386-Notes\7f333754
-Node: i860-Dependent\7f334612
-Node: Notes-i860\7f335008
-Node: Options-i860\7f335913
-Node: Directives-i860\7f337276
-Node: Opcodes for i860\7f338345
-Node: i960-Dependent\7f340512
-Node: Options-i960\7f340915
-Node: Floating Point-i960\7f344800
-Node: Directives-i960\7f345068
-Node: Opcodes for i960\7f347102
-Node: callj-i960\7f347719
-Node: Compare-and-branch-i960\7f348208
-Node: IA-64-Dependent\7f350112
-Node: IA-64 Options\7f350413
-Node: IA-64 Syntax\7f353573
-Node: IA-64-Chars\7f353936
-Node: IA-64-Regs\7f354166
-Node: IA-64-Bits\7f355092
-Node: IA-64 Opcodes\7f355601
-Node: IP2K-Dependent\7f355873
-Node: IP2K-Opts\7f356101
-Node: M32C-Dependent\7f356581
-Node: M32C-Opts\7f357105
-Node: M32C-Modifiers\7f357389
-Node: M32R-Dependent\7f359176
-Node: M32R-Opts\7f359497
-Node: M32R-Directives\7f363664
-Node: M32R-Warnings\7f367639
-Node: M68K-Dependent\7f370645
-Node: M68K-Opts\7f371112
-Node: M68K-Syntax\7f378504
-Node: M68K-Moto-Syntax\7f380344
-Node: M68K-Float\7f382934
-Node: M68K-Directives\7f383454
-Node: M68K-opcodes\7f384782
-Node: M68K-Branch\7f385008
-Node: M68K-Chars\7f389206
-Node: M68HC11-Dependent\7f389619
-Node: M68HC11-Opts\7f390150
-Node: M68HC11-Syntax\7f393971
-Node: M68HC11-Modifiers\7f396185
-Node: M68HC11-Directives\7f398013
-Node: M68HC11-Float\7f399389
-Node: M68HC11-opcodes\7f399917
-Node: M68HC11-Branch\7f400099
-Node: MIPS-Dependent\7f402548
-Node: MIPS Opts\7f403638
-Node: MIPS Object\7f412681
-Node: MIPS Stabs\7f414247
-Node: MIPS symbol sizes\7f414969
-Node: MIPS ISA\7f416638
-Node: MIPS autoextend\7f418112
-Node: MIPS insn\7f418842
-Node: MIPS option stack\7f419339
-Node: MIPS ASE instruction generation overrides\7f420113
-Node: MMIX-Dependent\7f421899
-Node: MMIX-Opts\7f422279
-Node: MMIX-Expand\7f425883
-Node: MMIX-Syntax\7f427198
-Ref: mmixsite\7f427555
-Node: MMIX-Chars\7f428396
-Node: MMIX-Symbols\7f429050
-Node: MMIX-Regs\7f431118
-Node: MMIX-Pseudos\7f432143
-Ref: MMIX-loc\7f432284
-Ref: MMIX-local\7f433364
-Ref: MMIX-is\7f433896
-Ref: MMIX-greg\7f434167
-Ref: GREG-base\7f435086
-Ref: MMIX-byte\7f436403
-Ref: MMIX-constants\7f436874
-Ref: MMIX-prefix\7f437520
-Ref: MMIX-spec\7f437894
-Node: MMIX-mmixal\7f438228
-Node: MSP430-Dependent\7f441726
-Node: MSP430 Options\7f442192
-Node: MSP430 Syntax\7f442478
-Node: MSP430-Macros\7f442794
-Node: MSP430-Chars\7f443525
-Node: MSP430-Regs\7f443838
-Node: MSP430-Ext\7f444398
-Node: MSP430 Floating Point\7f446219
-Node: MSP430 Directives\7f446443
-Node: MSP430 Opcodes\7f447234
-Node: MSP430 Profiling Capability\7f447629
-Node: PDP-11-Dependent\7f449958
-Node: PDP-11-Options\7f450347
-Node: PDP-11-Pseudos\7f455418
-Node: PDP-11-Syntax\7f455763
-Node: PDP-11-Mnemonics\7f456515
-Node: PDP-11-Synthetic\7f456817
-Node: PJ-Dependent\7f457035
-Node: PJ Options\7f457260
-Node: PPC-Dependent\7f457537
-Node: PowerPC-Opts\7f457824
-Node: PowerPC-Pseudo\7f460156
-Node: SH-Dependent\7f460755
-Node: SH Options\7f461167
-Node: SH Syntax\7f462095
-Node: SH-Chars\7f462368
-Node: SH-Regs\7f462662
-Node: SH-Addressing\7f463276
-Node: SH Floating Point\7f464185
-Node: SH Directives\7f465279
-Node: SH Opcodes\7f465649
-Node: SH64-Dependent\7f469971
-Node: SH64 Options\7f470334
-Node: SH64 Syntax\7f472051
-Node: SH64-Chars\7f472334
-Node: SH64-Regs\7f472634
-Node: SH64-Addressing\7f473730
-Node: SH64 Directives\7f474913
-Node: SH64 Opcodes\7f476023
-Node: Sparc-Dependent\7f476739
-Node: Sparc-Opts\7f477124
-Node: Sparc-Aligned-Data\7f479381
-Node: Sparc-Float\7f480236
-Node: Sparc-Directives\7f480437
-Node: TIC54X-Dependent\7f482397
-Node: TIC54X-Opts\7f483123
-Node: TIC54X-Block\7f484166
-Node: TIC54X-Env\7f484526
-Node: TIC54X-Constants\7f484874
-Node: TIC54X-Subsyms\7f485276
-Node: TIC54X-Locals\7f487185
-Node: TIC54X-Builtins\7f487929
-Node: TIC54X-Ext\7f490400
-Node: TIC54X-Directives\7f490971
-Node: TIC54X-Macros\7f501873
-Node: TIC54X-MMRegs\7f503984
-Node: Z80-Dependent\7f504200
-Node: Z80 Options\7f504588
-Node: Z80 Syntax\7f506011
-Node: Z80-Chars\7f506683
-Node: Z80-Regs\7f507217
-Node: Z80-Case\7f507569
-Node: Z80 Floating Point\7f508014
-Node: Z80 Directives\7f508208
-Node: Z80 Opcodes\7f509833
-Node: Z8000-Dependent\7f511177
-Node: Z8000 Options\7f512138
-Node: Z8000 Syntax\7f512355
-Node: Z8000-Chars\7f512645
-Node: Z8000-Regs\7f512878
-Node: Z8000-Addressing\7f513668
-Node: Z8000 Directives\7f514785
-Node: Z8000 Opcodes\7f516394
-Node: Vax-Dependent\7f526336
-Node: VAX-Opts\7f526853
-Node: VAX-float\7f530588
-Node: VAX-directives\7f531220
-Node: VAX-opcodes\7f532081
-Node: VAX-branch\7f532470
-Node: VAX-operands\7f534977
-Node: VAX-no\7f535740
-Node: V850-Dependent\7f535977
-Node: V850 Options\7f536375
-Node: V850 Syntax\7f538764
-Node: V850-Chars\7f539004
-Node: V850-Regs\7f539169
-Node: V850 Floating Point\7f540737
-Node: V850 Directives\7f540943
-Node: V850 Opcodes\7f542086
-Node: Xtensa-Dependent\7f547978
-Node: Xtensa Options\7f548707
-Node: Xtensa Syntax\7f551517
-Node: Xtensa Opcodes\7f553406
-Node: Xtensa Registers\7f555200
-Node: Xtensa Optimizations\7f555833
-Node: Density Instructions\7f556285
-Node: Xtensa Automatic Alignment\7f557387
-Node: Xtensa Relaxation\7f560008
-Node: Xtensa Branch Relaxation\7f560916
-Node: Xtensa Call Relaxation\7f562288
-Node: Xtensa Immediate Relaxation\7f564074
-Node: Xtensa Directives\7f566649
-Node: Schedule Directive\7f568358
-Node: Longcalls Directive\7f568698
-Node: Transform Directive\7f569242
-Node: Literal Directive\7f569984
-Ref: Literal Directive-Footnote-1\7f573523
-Node: Literal Position Directive\7f573665
-Node: Literal Prefix Directive\7f575364
-Node: Absolute Literals Directive\7f576262
-Node: Reporting Bugs\7f577569
-Node: Bug Criteria\7f578293
-Node: Bug Reporting\7f579058
-Node: Acknowledgements\7f585705
-Ref: Acknowledgements-Footnote-1\7f590603
-Node: GNU Free Documentation License\7f590629
-Node: AS Index\7f610359
-\1f
-End Tag Table
+++ /dev/null
-This is gprof.info, produced by makeinfo version 4.8 from gprof.texi.
-
-START-INFO-DIR-ENTRY
-* gprof: (gprof). Profiling your program's execution
-END-INFO-DIR-ENTRY
-
- This file documents the gprof profiler of the GNU system.
-
- Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001, 2003, 2007 Free
-Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-\1f
-File: gprof.info, Node: Top, Next: Introduction, Up: (dir)
-
-Profiling a Program: Where Does It Spend Its Time?
-**************************************************
-
-This manual describes the GNU profiler, `gprof', and how you can use it
-to determine which parts of a program are taking most of the execution
-time. We assume that you know how to write, compile, and execute
-programs. GNU `gprof' was written by Jay Fenlason.
-
- This manual is for `gprof' (GNU Binutils) version 2.17.90.
-
- 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".
-
-* Menu:
-
-* Introduction:: What profiling means, and why it is useful.
-
-* Compiling:: How to compile your program for profiling.
-* Executing:: Executing your program to generate profile data
-* Invoking:: How to run `gprof', and its options
-
-* Output:: Interpreting `gprof''s output
-
-* Inaccuracy:: Potential problems you should be aware of
-* How do I?:: Answers to common questions
-* Incompatibilities:: (between GNU `gprof' and Unix `gprof'.)
-* Details:: Details of how profiling is done
-* GNU Free Documentation License:: GNU Free Documentation License
-
-\1f
-File: gprof.info, Node: Introduction, Next: Compiling, Prev: Top, Up: Top
-
-1 Introduction to Profiling
-***************************
-
-Profiling allows you to learn where your program spent its time and
-which functions called which other functions while it was executing.
-This information can show you which pieces of your program are slower
-than you expected, and might be candidates for rewriting to make your
-program execute faster. It can also tell you which functions are being
-called more or less often than you expected. This may help you spot
-bugs that had otherwise been unnoticed.
-
- Since the profiler uses information collected during the actual
-execution of your program, it can be used on programs that are too
-large or too complex to analyze by reading the source. However, how
-your program is run will affect the information that shows up in the
-profile data. If you don't use some feature of your program while it
-is being profiled, no profile information will be generated for that
-feature.
-
- Profiling has several steps:
-
- * You must compile and link your program with profiling enabled.
- *Note Compiling a Program for Profiling: Compiling.
-
- * You must execute your program to generate a profile data file.
- *Note Executing the Program: Executing.
-
- * You must run `gprof' to analyze the profile data. *Note `gprof'
- Command Summary: Invoking.
-
- The next three chapters explain these steps in greater detail.
-
- Several forms of output are available from the analysis.
-
- The "flat profile" shows how much time your program spent in each
-function, and how many times that function was called. If you simply
-want to know which functions burn most of the cycles, it is stated
-concisely here. *Note The Flat Profile: Flat Profile.
-
- The "call graph" shows, for each function, which functions called
-it, which other functions it called, and how many times. There is also
-an estimate of how much time was spent in the subroutines of each
-function. This can suggest places where you might try to eliminate
-function calls that use a lot of time. *Note The Call Graph: Call
-Graph.
-
- The "annotated source" listing is a copy of the program's source
-code, labeled with the number of times each line of the program was
-executed. *Note The Annotated Source Listing: Annotated Source.
-
- To better understand how profiling works, you may wish to read a
-description of its implementation. *Note Implementation of Profiling:
-Implementation.
-
-\1f
-File: gprof.info, Node: Compiling, Next: Executing, Prev: Introduction, Up: Top
-
-2 Compiling a Program for Profiling
-***********************************
-
-The first step in generating profile information for your program is to
-compile and link it with profiling enabled.
-
- To compile a source file for profiling, specify the `-pg' option when
-you run the compiler. (This is in addition to the options you normally
-use.)
-
- To link the program for profiling, if you use a compiler such as `cc'
-to do the linking, simply specify `-pg' in addition to your usual
-options. The same option, `-pg', alters either compilation or linking
-to do what is necessary for profiling. Here are examples:
-
- cc -g -c myprog.c utils.c -pg
- cc -o myprog myprog.o utils.o -pg
-
- The `-pg' option also works with a command that both compiles and
-links:
-
- cc -o myprog myprog.c utils.c -g -pg
-
- Note: The `-pg' option must be part of your compilation options as
-well as your link options. If it is not then no call-graph data will
-be gathered and when you run `gprof' you will get an error message like
-this:
-
- gprof: gmon.out file is missing call-graph data
-
- If you add the `-Q' switch to suppress the printing of the call
-graph data you will still be able to see the time samples:
-
- Flat profile:
-
- Each sample counts as 0.01 seconds.
- % cumulative self self total
- time seconds seconds calls Ts/call Ts/call name
- 44.12 0.07 0.07 zazLoop
- 35.29 0.14 0.06 main
- 20.59 0.17 0.04 bazMillion
-
- If you run the linker `ld' directly instead of through a compiler
-such as `cc', you may have to specify a profiling startup file
-`gcrt0.o' as the first input file instead of the usual startup file
-`crt0.o'. In addition, you would probably want to specify the
-profiling C library, `libc_p.a', by writing `-lc_p' instead of the
-usual `-lc'. This is not absolutely necessary, but doing this gives
-you number-of-calls information for standard library functions such as
-`read' and `open'. For example:
-
- ld -o myprog /lib/gcrt0.o myprog.o utils.o -lc_p
-
- If you compile only some of the modules of the program with `-pg',
-you can still profile the program, but you won't get complete
-information about the modules that were compiled without `-pg'. The
-only information you get for the functions in those modules is the
-total time spent in them; there is no record of how many times they
-were called, or from where. This will not affect the flat profile
-(except that the `calls' field for the functions will be blank), but
-will greatly reduce the usefulness of the call graph.
-
- If you wish to perform line-by-line profiling you should use the
-`gcov' tool instead of `gprof'. See that tool's manual or info pages
-for more details of how to do this.
-
- Note, older versions of `gcc' produce line-by-line profiling
-information that works with `gprof' rather than `gcov' so there is
-still support for displaying this kind of information in `gprof'. *Note
-Line-by-line Profiling: Line-by-line.
-
- It also worth noting that `gcc' implements a
-`-finstrument-functions' command line option which will insert calls to
-special user supplied instrumentation routines at the entry and exit of
-every function in their program. This can be used to implement an
-alternative profiling scheme.
-
-\1f
-File: gprof.info, Node: Executing, Next: Invoking, Prev: Compiling, Up: Top
-
-3 Executing the Program
-***********************
-
-Once the program is compiled for profiling, you must run it in order to
-generate the information that `gprof' needs. Simply run the program as
-usual, using the normal arguments, file names, etc. The program should
-run normally, producing the same output as usual. It will, however, run
-somewhat slower than normal because of the time spent collecting and
-writing the profile data.
-
- The way you run the program--the arguments and input that you give
-it--may have a dramatic effect on what the profile information shows.
-The profile data will describe the parts of the program that were
-activated for the particular input you use. For example, if the first
-command you give to your program is to quit, the profile data will show
-the time used in initialization and in cleanup, but not much else.
-
- Your program will write the profile data into a file called
-`gmon.out' just before exiting. If there is already a file called
-`gmon.out', its contents are overwritten. There is currently no way to
-tell the program to write the profile data under a different name, but
-you can rename the file afterwards if you are concerned that it may be
-overwritten.
-
- In order to write the `gmon.out' file properly, your program must
-exit normally: by returning from `main' or by calling `exit'. Calling
-the low-level function `_exit' does not write the profile data, and
-neither does abnormal termination due to an unhandled signal.
-
- The `gmon.out' file is written in the program's _current working
-directory_ at the time it exits. This means that if your program calls
-`chdir', the `gmon.out' file will be left in the last directory your
-program `chdir''d to. If you don't have permission to write in this
-directory, the file is not written, and you will get an error message.
-
- Older versions of the GNU profiling library may also write a file
-called `bb.out'. This file, if present, contains an human-readable
-listing of the basic-block execution counts. Unfortunately, the
-appearance of a human-readable `bb.out' means the basic-block counts
-didn't get written into `gmon.out'. The Perl script `bbconv.pl',
-included with the `gprof' source distribution, will convert a `bb.out'
-file into a format readable by `gprof'. Invoke it like this:
-
- bbconv.pl < bb.out > BH-DATA
-
- This translates the information in `bb.out' into a form that `gprof'
-can understand. But you still need to tell `gprof' about the existence
-of this translated information. To do that, include BB-DATA on the
-`gprof' command line, _along with `gmon.out'_, like this:
-
- gprof OPTIONS EXECUTABLE-FILE gmon.out BB-DATA [YET-MORE-PROFILE-DATA-FILES...] [> OUTFILE]
-
-\1f
-File: gprof.info, Node: Invoking, Next: Output, Prev: Executing, Up: Top
-
-4 `gprof' Command Summary
-*************************
-
-After you have a profile data file `gmon.out', you can run `gprof' to
-interpret the information in it. The `gprof' program prints a flat
-profile and a call graph on standard output. Typically you would
-redirect the output of `gprof' into a file with `>'.
-
- You run `gprof' like this:
-
- gprof OPTIONS [EXECUTABLE-FILE [PROFILE-DATA-FILES...]] [> OUTFILE]
-
-Here square-brackets indicate optional arguments.
-
- If you omit the executable file name, the file `a.out' is used. If
-you give no profile data file name, the file `gmon.out' is used. If
-any file is not in the proper format, or if the profile data file does
-not appear to belong to the executable file, an error message is
-printed.
-
- You can give more than one profile data file by entering all their
-names after the executable file name; then the statistics in all the
-data files are summed together.
-
- The order of these options does not matter.
-
-* Menu:
-
-* Output Options:: Controlling `gprof''s output style
-* Analysis Options:: Controlling how `gprof' analyzes its data
-* Miscellaneous Options::
-* Deprecated Options:: Options you no longer need to use, but which
- have been retained for compatibility
-* Symspecs:: Specifying functions to include or exclude
-
-\1f
-File: gprof.info, Node: Output Options, Next: Analysis Options, Up: Invoking
-
-4.1 Output Options
-==================
-
-These options specify which of several output formats `gprof' should
-produce.
-
- Many of these options take an optional "symspec" to specify
-functions to be included or excluded. These options can be specified
-multiple times, with different symspecs, to include or exclude sets of
-symbols. *Note Symspecs: Symspecs.
-
- Specifying any of these options overrides the default (`-p -q'),
-which prints a flat profile and call graph analysis for all functions.
-
-`-A[SYMSPEC]'
-`--annotated-source[=SYMSPEC]'
- The `-A' option causes `gprof' to print annotated source code. If
- SYMSPEC is specified, print output only for matching symbols.
- *Note The Annotated Source Listing: Annotated Source.
-
-`-b'
-`--brief'
- If the `-b' option is given, `gprof' doesn't print the verbose
- blurbs that try to explain the meaning of all of the fields in the
- tables. This is useful if you intend to print out the output, or
- are tired of seeing the blurbs.
-
-`-C[SYMSPEC]'
-`--exec-counts[=SYMSPEC]'
- The `-C' option causes `gprof' to print a tally of functions and
- the number of times each was called. If SYMSPEC is specified,
- print tally only for matching symbols.
-
- If the profile data file contains basic-block count records,
- specifying the `-l' option, along with `-C', will cause basic-block
- execution counts to be tallied and displayed.
-
-`-i'
-`--file-info'
- The `-i' option causes `gprof' to display summary information
- about the profile data file(s) and then exit. The number of
- histogram, call graph, and basic-block count records is displayed.
-
-`-I DIRS'
-`--directory-path=DIRS'
- The `-I' option specifies a list of search directories in which to
- find source files. Environment variable GPROF_PATH can also be
- used to convey this information. Used mostly for annotated source
- output.
-
-`-J[SYMSPEC]'
-`--no-annotated-source[=SYMSPEC]'
- The `-J' option causes `gprof' not to print annotated source code.
- If SYMSPEC is specified, `gprof' prints annotated source, but
- excludes matching symbols.
-
-`-L'
-`--print-path'
- Normally, source filenames are printed with the path component
- suppressed. The `-L' option causes `gprof' to print the full
- pathname of source filenames, which is determined from symbolic
- debugging information in the image file and is relative to the
- directory in which the compiler was invoked.
-
-`-p[SYMSPEC]'
-`--flat-profile[=SYMSPEC]'
- The `-p' option causes `gprof' to print a flat profile. If
- SYMSPEC is specified, print flat profile only for matching symbols.
- *Note The Flat Profile: Flat Profile.
-
-`-P[SYMSPEC]'
-`--no-flat-profile[=SYMSPEC]'
- The `-P' option causes `gprof' to suppress printing a flat profile.
- If SYMSPEC is specified, `gprof' prints a flat profile, but
- excludes matching symbols.
-
-`-q[SYMSPEC]'
-`--graph[=SYMSPEC]'
- The `-q' option causes `gprof' to print the call graph analysis.
- If SYMSPEC is specified, print call graph only for matching symbols
- and their children. *Note The Call Graph: Call Graph.
-
-`-Q[SYMSPEC]'
-`--no-graph[=SYMSPEC]'
- The `-Q' option causes `gprof' to suppress printing the call graph.
- If SYMSPEC is specified, `gprof' prints a call graph, but excludes
- matching symbols.
-
-`-t'
-`--table-length=NUM'
- The `-t' option causes the NUM most active source lines in each
- source file to be listed when source annotation is enabled. The
- default is 10.
-
-`-y'
-`--separate-files'
- This option affects annotated source output only. Normally,
- `gprof' prints annotated source files to standard-output. If this
- option is specified, annotated source for a file named
- `path/FILENAME' is generated in the file `FILENAME-ann'. If the
- underlying file system would truncate `FILENAME-ann' so that it
- overwrites the original `FILENAME', `gprof' generates annotated
- source in the file `FILENAME.ann' instead (if the original file
- name has an extension, that extension is _replaced_ with `.ann').
-
-`-Z[SYMSPEC]'
-`--no-exec-counts[=SYMSPEC]'
- The `-Z' option causes `gprof' not to print a tally of functions
- and the number of times each was called. If SYMSPEC is specified,
- print tally, but exclude matching symbols.
-
-`-r'
-`--function-ordering'
- The `--function-ordering' option causes `gprof' to print a
- suggested function ordering for the program based on profiling
- data. This option suggests an ordering which may improve paging,
- tlb and cache behavior for the program on systems which support
- arbitrary ordering of functions in an executable.
-
- The exact details of how to force the linker to place functions in
- a particular order is system dependent and out of the scope of this
- manual.
-
-`-R MAP_FILE'
-`--file-ordering MAP_FILE'
- The `--file-ordering' option causes `gprof' to print a suggested
- .o link line ordering for the program based on profiling data.
- This option suggests an ordering which may improve paging, tlb and
- cache behavior for the program on systems which do not support
- arbitrary ordering of functions in an executable.
-
- Use of the `-a' argument is highly recommended with this option.
-
- The MAP_FILE argument is a pathname to a file which provides
- function name to object file mappings. The format of the file is
- similar to the output of the program `nm'.
-
- c-parse.o:00000000 T yyparse
- c-parse.o:00000004 C yyerrflag
- c-lang.o:00000000 T maybe_objc_method_name
- c-lang.o:00000000 T print_lang_statistics
- c-lang.o:00000000 T recognize_objc_keyword
- c-decl.o:00000000 T print_lang_identifier
- c-decl.o:00000000 T print_lang_type
- ...
-
- To create a MAP_FILE with GNU `nm', type a command like `nm
- --extern-only --defined-only -v --print-file-name program-name'.
-
-`-T'
-`--traditional'
- The `-T' option causes `gprof' to print its output in
- "traditional" BSD style.
-
-`-w WIDTH'
-`--width=WIDTH'
- Sets width of output lines to WIDTH. Currently only used when
- printing the function index at the bottom of the call graph.
-
-`-x'
-`--all-lines'
- This option affects annotated source output only. By default,
- only the lines at the beginning of a basic-block are annotated.
- If this option is specified, every line in a basic-block is
- annotated by repeating the annotation for the first line. This
- behavior is similar to `tcov''s `-a'.
-
-`--demangle[=STYLE]'
-`--no-demangle'
- These options control whether C++ symbol names should be demangled
- when printing output. The default is to demangle symbols. The
- `--no-demangle' option may be used to turn off demangling.
- Different compilers have different mangling styles. The optional
- demangling style argument can be used to choose an appropriate
- demangling style for your compiler.
-
-\1f
-File: gprof.info, Node: Analysis Options, Next: Miscellaneous Options, Prev: Output Options, Up: Invoking
-
-4.2 Analysis Options
-====================
-
-`-a'
-`--no-static'
- The `-a' option causes `gprof' to suppress the printing of
- statically declared (private) functions. (These are functions
- whose names are not listed as global, and which are not visible
- outside the file/function/block where they were defined.) Time
- spent in these functions, calls to/from them, etc., will all be
- attributed to the function that was loaded directly before it in
- the executable file. This option affects both the flat profile
- and the call graph.
-
-`-c'
-`--static-call-graph'
- The `-c' option causes the call graph of the program to be
- augmented by a heuristic which examines the text space of the
- object file and identifies function calls in the binary machine
- code. Since normal call graph records are only generated when
- functions are entered, this option identifies children that could
- have been called, but never were. Calls to functions that were
- not compiled with profiling enabled are also identified, but only
- if symbol table entries are present for them. Calls to dynamic
- library routines are typically _not_ found by this option.
- Parents or children identified via this heuristic are indicated in
- the call graph with call counts of `0'.
-
-`-D'
-`--ignore-non-functions'
- The `-D' option causes `gprof' to ignore symbols which are not
- known to be functions. This option will give more accurate
- profile data on systems where it is supported (Solaris and HPUX for
- example).
-
-`-k FROM/TO'
- The `-k' option allows you to delete from the call graph any arcs
- from symbols matching symspec FROM to those matching symspec TO.
-
-`-l'
-`--line'
- The `-l' option enables line-by-line profiling, which causes
- histogram hits to be charged to individual source code lines,
- instead of functions. This feature only works with programs
- compiled by older versions of the `gcc' compiler. Newer versions
- of `gcc' are designed to work with the `gcov' tool instead.
-
- If the program was compiled with basic-block counting enabled,
- this option will also identify how many times each line of code
- was executed. While line-by-line profiling can help isolate where
- in a large function a program is spending its time, it also
- significantly increases the running time of `gprof', and magnifies
- statistical inaccuracies. *Note Statistical Sampling Error:
- Sampling Error.
-
-`-m NUM'
-`--min-count=NUM'
- This option affects execution count output only. Symbols that are
- executed less than NUM times are suppressed.
-
-`-nSYMSPEC'
-`--time=SYMSPEC'
- The `-n' option causes `gprof', in its call graph analysis, to
- only propagate times for symbols matching SYMSPEC.
-
-`-NSYMSPEC'
-`--no-time=SYMSPEC'
- The `-n' option causes `gprof', in its call graph analysis, not to
- propagate times for symbols matching SYMSPEC.
-
-`-z'
-`--display-unused-functions'
- If you give the `-z' option, `gprof' will mention all functions in
- the flat profile, even those that were never called, and that had
- no time spent in them. This is useful in conjunction with the
- `-c' option for discovering which routines were never called.
-
-
-\1f
-File: gprof.info, Node: Miscellaneous Options, Next: Deprecated Options, Prev: Analysis Options, Up: Invoking
-
-4.3 Miscellaneous Options
-=========================
-
-`-d[NUM]'
-`--debug[=NUM]'
- The `-d NUM' option specifies debugging options. If NUM is not
- specified, enable all debugging. *Note Debugging `gprof':
- Debugging.
-
-`-h'
-`--help'
- The `-h' option prints command line usage.
-
-`-ONAME'
-`--file-format=NAME'
- Selects the format of the profile data files. Recognized formats
- are `auto' (the default), `bsd', `4.4bsd', `magic', and `prof'
- (not yet supported).
-
-`-s'
-`--sum'
- The `-s' option causes `gprof' to summarize the information in the
- profile data files it read in, and write out a profile data file
- called `gmon.sum', which contains all the information from the
- profile data files that `gprof' read in. The file `gmon.sum' may
- be one of the specified input files; the effect of this is to
- merge the data in the other input files into `gmon.sum'.
-
- Eventually you can run `gprof' again without `-s' to analyze the
- cumulative data in the file `gmon.sum'.
-
-`-v'
-`--version'
- The `-v' flag causes `gprof' to print the current version number,
- and then exit.
-
-
-\1f
-File: gprof.info, Node: Deprecated Options, Next: Symspecs, Prev: Miscellaneous Options, Up: Invoking
-
-4.4 Deprecated Options
-======================
-
- These options have been replaced with newer versions that use
- symspecs.
-
-`-e FUNCTION_NAME'
- The `-e FUNCTION' option tells `gprof' to not print information
- about the function FUNCTION_NAME (and its children...) in the call
- graph. The function will still be listed as a child of any
- functions that call it, but its index number will be shown as
- `[not printed]'. More than one `-e' option may be given; only one
- FUNCTION_NAME may be indicated with each `-e' option.
-
-`-E FUNCTION_NAME'
- The `-E FUNCTION' option works like the `-e' option, but time
- spent in the function (and children who were not called from
- anywhere else), will not be used to compute the
- percentages-of-time for the call graph. More than one `-E' option
- may be given; only one FUNCTION_NAME may be indicated with each
- `-E' option.
-
-`-f FUNCTION_NAME'
- The `-f FUNCTION' option causes `gprof' to limit the call graph to
- the function FUNCTION_NAME and its children (and their
- children...). More than one `-f' option may be given; only one
- FUNCTION_NAME may be indicated with each `-f' option.
-
-`-F FUNCTION_NAME'
- The `-F FUNCTION' option works like the `-f' option, but only time
- spent in the function and its children (and their children...)
- will be used to determine total-time and percentages-of-time for
- the call graph. More than one `-F' option may be given; only one
- FUNCTION_NAME may be indicated with each `-F' option. The `-F'
- option overrides the `-E' option.
-
-
- Note that only one function can be specified with each `-e', `-E',
-`-f' or `-F' option. To specify more than one function, use multiple
-options. For example, this command:
-
- gprof -e boring -f foo -f bar myprogram > gprof.output
-
-lists in the call graph all functions that were reached from either
-`foo' or `bar' and were not reachable from `boring'.
-
-\1f
-File: gprof.info, Node: Symspecs, Prev: Deprecated Options, Up: Invoking
-
-4.5 Symspecs
-============
-
-Many of the output options allow functions to be included or excluded
-using "symspecs" (symbol specifications), which observe the following
-syntax:
-
- filename_containing_a_dot
- | funcname_not_containing_a_dot
- | linenumber
- | ( [ any_filename ] `:' ( any_funcname | linenumber ) )
-
- Here are some sample symspecs:
-
-`main.c'
- Selects everything in file `main.c'--the dot in the string tells
- `gprof' to interpret the string as a filename, rather than as a
- function name. To select a file whose name does not contain a
- dot, a trailing colon should be specified. For example, `odd:' is
- interpreted as the file named `odd'.
-
-`main'
- Selects all functions named `main'.
-
- Note that there may be multiple instances of the same function name
- because some of the definitions may be local (i.e., static).
- Unless a function name is unique in a program, you must use the
- colon notation explained below to specify a function from a
- specific source file.
-
- Sometimes, function names contain dots. In such cases, it is
- necessary to add a leading colon to the name. For example,
- `:.mul' selects function `.mul'.
-
- In some object file formats, symbols have a leading underscore.
- `gprof' will normally not print these underscores. When you name a
- symbol in a symspec, you should type it exactly as `gprof' prints
- it in its output. For example, if the compiler produces a symbol
- `_main' from your `main' function, `gprof' still prints it as
- `main' in its output, so you should use `main' in symspecs.
-
-`main.c:main'
- Selects function `main' in file `main.c'.
-
-`main.c:134'
- Selects line 134 in file `main.c'.
-
-\1f
-File: gprof.info, Node: Output, Next: Inaccuracy, Prev: Invoking, Up: Top
-
-5 Interpreting `gprof''s Output
-*******************************
-
-`gprof' can produce several different output styles, the most important
-of which are described below. The simplest output styles (file
-information, execution count, and function and file ordering) are not
-described here, but are documented with the respective options that
-trigger them. *Note Output Options: Output Options.
-
-* Menu:
-
-* Flat Profile:: The flat profile shows how much time was spent
- executing directly in each function.
-* Call Graph:: The call graph shows which functions called which
- others, and how much time each function used
- when its subroutine calls are included.
-* Line-by-line:: `gprof' can analyze individual source code lines
-* Annotated Source:: The annotated source listing displays source code
- labeled with execution counts
-
-\1f
-File: gprof.info, Node: Flat Profile, Next: Call Graph, Up: Output
-
-5.1 The Flat Profile
-====================
-
-The "flat profile" shows the total amount of time your program spent
-executing each function. Unless the `-z' option is given, functions
-with no apparent time spent in them, and no apparent calls to them, are
-not mentioned. Note that if a function was not compiled for profiling,
-and didn't run long enough to show up on the program counter histogram,
-it will be indistinguishable from a function that was never called.
-
- This is part of a flat profile for a small program:
-
- Flat profile:
-
- Each sample counts as 0.01 seconds.
- % cumulative self self total
- time seconds seconds calls ms/call ms/call name
- 33.34 0.02 0.02 7208 0.00 0.00 open
- 16.67 0.03 0.01 244 0.04 0.12 offtime
- 16.67 0.04 0.01 8 1.25 1.25 memccpy
- 16.67 0.05 0.01 7 1.43 1.43 write
- 16.67 0.06 0.01 mcount
- 0.00 0.06 0.00 236 0.00 0.00 tzset
- 0.00 0.06 0.00 192 0.00 0.00 tolower
- 0.00 0.06 0.00 47 0.00 0.00 strlen
- 0.00 0.06 0.00 45 0.00 0.00 strchr
- 0.00 0.06 0.00 1 0.00 50.00 main
- 0.00 0.06 0.00 1 0.00 0.00 memcpy
- 0.00 0.06 0.00 1 0.00 10.11 print
- 0.00 0.06 0.00 1 0.00 0.00 profil
- 0.00 0.06 0.00 1 0.00 50.00 report
- ...
-
-The functions are sorted first by decreasing run-time spent in them,
-then by decreasing number of calls, then alphabetically by name. The
-functions `mcount' and `profil' are part of the profiling apparatus and
-appear in every flat profile; their time gives a measure of the amount
-of overhead due to profiling.
-
- Just before the column headers, a statement appears indicating how
-much time each sample counted as. This "sampling period" estimates the
-margin of error in each of the time figures. A time figure that is not
-much larger than this is not reliable. In this example, each sample
-counted as 0.01 seconds, suggesting a 100 Hz sampling rate. The
-program's total execution time was 0.06 seconds, as indicated by the
-`cumulative seconds' field. Since each sample counted for 0.01
-seconds, this means only six samples were taken during the run. Two of
-the samples occurred while the program was in the `open' function, as
-indicated by the `self seconds' field. Each of the other four samples
-occurred one each in `offtime', `memccpy', `write', and `mcount'.
-Since only six samples were taken, none of these values can be regarded
-as particularly reliable. In another run, the `self seconds' field for
-`mcount' might well be `0.00' or `0.02'. *Note Statistical Sampling
-Error: Sampling Error, for a complete discussion.
-
- The remaining functions in the listing (those whose `self seconds'
-field is `0.00') didn't appear in the histogram samples at all.
-However, the call graph indicated that they were called, so therefore
-they are listed, sorted in decreasing order by the `calls' field.
-Clearly some time was spent executing these functions, but the paucity
-of histogram samples prevents any determination of how much time each
-took.
-
- Here is what the fields in each line mean:
-
-`% time'
- This is the percentage of the total execution time your program
- spent in this function. These should all add up to 100%.
-
-`cumulative seconds'
- This is the cumulative total number of seconds the computer spent
- executing this functions, plus the time spent in all the functions
- above this one in this table.
-
-`self seconds'
- This is the number of seconds accounted for by this function alone.
- The flat profile listing is sorted first by this number.
-
-`calls'
- This is the total number of times the function was called. If the
- function was never called, or the number of times it was called
- cannot be determined (probably because the function was not
- compiled with profiling enabled), the "calls" field is blank.
-
-`self ms/call'
- This represents the average number of milliseconds spent in this
- function per call, if this function is profiled. Otherwise, this
- field is blank for this function.
-
-`total ms/call'
- This represents the average number of milliseconds spent in this
- function and its descendants per call, if this function is
- profiled. Otherwise, this field is blank for this function. This
- is the only field in the flat profile that uses call graph
- analysis.
-
-`name'
- This is the name of the function. The flat profile is sorted by
- this field alphabetically after the "self seconds" and "calls"
- fields are sorted.
-
-\1f
-File: gprof.info, Node: Call Graph, Next: Line-by-line, Prev: Flat Profile, Up: Output
-
-5.2 The Call Graph
-==================
-
-The "call graph" shows how much time was spent in each function and its
-children. From this information, you can find functions that, while
-they themselves may not have used much time, called other functions
-that did use unusual amounts of time.
-
- Here is a sample call from a small program. This call came from the
-same `gprof' run as the flat profile example in the previous section.
-
- granularity: each sample hit covers 2 byte(s) for 20.00% of 0.05 seconds
-
- index % time self children called name
- <spontaneous>
- [1] 100.0 0.00 0.05 start [1]
- 0.00 0.05 1/1 main [2]
- 0.00 0.00 1/2 on_exit [28]
- 0.00 0.00 1/1 exit [59]
- -----------------------------------------------
- 0.00 0.05 1/1 start [1]
- [2] 100.0 0.00 0.05 1 main [2]
- 0.00 0.05 1/1 report [3]
- -----------------------------------------------
- 0.00 0.05 1/1 main [2]
- [3] 100.0 0.00 0.05 1 report [3]
- 0.00 0.03 8/8 timelocal [6]
- 0.00 0.01 1/1 print [9]
- 0.00 0.01 9/9 fgets [12]
- 0.00 0.00 12/34 strncmp <cycle 1> [40]
- 0.00 0.00 8/8 lookup [20]
- 0.00 0.00 1/1 fopen [21]
- 0.00 0.00 8/8 chewtime [24]
- 0.00 0.00 8/16 skipspace [44]
- -----------------------------------------------
- [4] 59.8 0.01 0.02 8+472 <cycle 2 as a whole> [4]
- 0.01 0.02 244+260 offtime <cycle 2> [7]
- 0.00 0.00 236+1 tzset <cycle 2> [26]
- -----------------------------------------------
-
- The lines full of dashes divide this table into "entries", one for
-each function. Each entry has one or more lines.
-
- In each entry, the primary line is the one that starts with an index
-number in square brackets. The end of this line says which function
-the entry is for. The preceding lines in the entry describe the
-callers of this function and the following lines describe its
-subroutines (also called "children" when we speak of the call graph).
-
- The entries are sorted by time spent in the function and its
-subroutines.
-
- The internal profiling function `mcount' (*note The Flat Profile:
-Flat Profile.) is never mentioned in the call graph.
-
-* Menu:
-
-* Primary:: Details of the primary line's contents.
-* Callers:: Details of caller-lines' contents.
-* Subroutines:: Details of subroutine-lines' contents.
-* Cycles:: When there are cycles of recursion,
- such as `a' calls `b' calls `a'...
-
-\1f
-File: gprof.info, Node: Primary, Next: Callers, Up: Call Graph
-
-5.2.1 The Primary Line
-----------------------
-
-The "primary line" in a call graph entry is the line that describes the
-function which the entry is about and gives the overall statistics for
-this function.
-
- For reference, we repeat the primary line from the entry for function
-`report' in our main example, together with the heading line that shows
-the names of the fields:
-
- index % time self children called name
- ...
- [3] 100.0 0.00 0.05 1 report [3]
-
- Here is what the fields in the primary line mean:
-
-`index'
- Entries are numbered with consecutive integers. Each function
- therefore has an index number, which appears at the beginning of
- its primary line.
-
- Each cross-reference to a function, as a caller or subroutine of
- another, gives its index number as well as its name. The index
- number guides you if you wish to look for the entry for that
- function.
-
-`% time'
- This is the percentage of the total time that was spent in this
- function, including time spent in subroutines called from this
- function.
-
- The time spent in this function is counted again for the callers of
- this function. Therefore, adding up these percentages is
- meaningless.
-
-`self'
- This is the total amount of time spent in this function. This
- should be identical to the number printed in the `seconds' field
- for this function in the flat profile.
-
-`children'
- This is the total amount of time spent in the subroutine calls
- made by this function. This should be equal to the sum of all the
- `self' and `children' entries of the children listed directly
- below this function.
-
-`called'
- This is the number of times the function was called.
-
- If the function called itself recursively, there are two numbers,
- separated by a `+'. The first number counts non-recursive calls,
- and the second counts recursive calls.
-
- In the example above, the function `report' was called once from
- `main'.
-
-`name'
- This is the name of the current function. The index number is
- repeated after it.
-
- If the function is part of a cycle of recursion, the cycle number
- is printed between the function's name and the index number (*note
- How Mutually Recursive Functions Are Described: Cycles.). For
- example, if function `gnurr' is part of cycle number one, and has
- index number twelve, its primary line would be end like this:
-
- gnurr <cycle 1> [12]
-
-\1f
-File: gprof.info, Node: Callers, Next: Subroutines, Prev: Primary, Up: Call Graph
-
-5.2.2 Lines for a Function's Callers
-------------------------------------
-
-A function's entry has a line for each function it was called by.
-These lines' fields correspond to the fields of the primary line, but
-their meanings are different because of the difference in context.
-
- For reference, we repeat two lines from the entry for the function
-`report', the primary line and one caller-line preceding it, together
-with the heading line that shows the names of the fields:
-
- index % time self children called name
- ...
- 0.00 0.05 1/1 main [2]
- [3] 100.0 0.00 0.05 1 report [3]
-
- Here are the meanings of the fields in the caller-line for `report'
-called from `main':
-
-`self'
- An estimate of the amount of time spent in `report' itself when it
- was called from `main'.
-
-`children'
- An estimate of the amount of time spent in subroutines of `report'
- when `report' was called from `main'.
-
- The sum of the `self' and `children' fields is an estimate of the
- amount of time spent within calls to `report' from `main'.
-
-`called'
- Two numbers: the number of times `report' was called from `main',
- followed by the total number of non-recursive calls to `report'
- from all its callers.
-
-`name and index number'
- The name of the caller of `report' to which this line applies,
- followed by the caller's index number.
-
- Not all functions have entries in the call graph; some options to
- `gprof' request the omission of certain functions. When a caller
- has no entry of its own, it still has caller-lines in the entries
- of the functions it calls.
-
- If the caller is part of a recursion cycle, the cycle number is
- printed between the name and the index number.
-
- If the identity of the callers of a function cannot be determined, a
-dummy caller-line is printed which has `<spontaneous>' as the "caller's
-name" and all other fields blank. This can happen for signal handlers.
-
-\1f
-File: gprof.info, Node: Subroutines, Next: Cycles, Prev: Callers, Up: Call Graph
-
-5.2.3 Lines for a Function's Subroutines
-----------------------------------------
-
-A function's entry has a line for each of its subroutines--in other
-words, a line for each other function that it called. These lines'
-fields correspond to the fields of the primary line, but their meanings
-are different because of the difference in context.
-
- For reference, we repeat two lines from the entry for the function
-`main', the primary line and a line for a subroutine, together with the
-heading line that shows the names of the fields:
-
- index % time self children called name
- ...
- [2] 100.0 0.00 0.05 1 main [2]
- 0.00 0.05 1/1 report [3]
-
- Here are the meanings of the fields in the subroutine-line for `main'
-calling `report':
-
-`self'
- An estimate of the amount of time spent directly within `report'
- when `report' was called from `main'.
-
-`children'
- An estimate of the amount of time spent in subroutines of `report'
- when `report' was called from `main'.
-
- The sum of the `self' and `children' fields is an estimate of the
- total time spent in calls to `report' from `main'.
-
-`called'
- Two numbers, the number of calls to `report' from `main' followed
- by the total number of non-recursive calls to `report'. This
- ratio is used to determine how much of `report''s `self' and
- `children' time gets credited to `main'. *Note Estimating
- `children' Times: Assumptions.
-
-`name'
- The name of the subroutine of `main' to which this line applies,
- followed by the subroutine's index number.
-
- If the caller is part of a recursion cycle, the cycle number is
- printed between the name and the index number.
-
-\1f
-File: gprof.info, Node: Cycles, Prev: Subroutines, Up: Call Graph
-
-5.2.4 How Mutually Recursive Functions Are Described
-----------------------------------------------------
-
-The graph may be complicated by the presence of "cycles of recursion"
-in the call graph. A cycle exists if a function calls another function
-that (directly or indirectly) calls (or appears to call) the original
-function. For example: if `a' calls `b', and `b' calls `a', then `a'
-and `b' form a cycle.
-
- Whenever there are call paths both ways between a pair of functions,
-they belong to the same cycle. If `a' and `b' call each other and `b'
-and `c' call each other, all three make one cycle. Note that even if
-`b' only calls `a' if it was not called from `a', `gprof' cannot
-determine this, so `a' and `b' are still considered a cycle.
-
- The cycles are numbered with consecutive integers. When a function
-belongs to a cycle, each time the function name appears in the call
-graph it is followed by `<cycle NUMBER>'.
-
- The reason cycles matter is that they make the time values in the
-call graph paradoxical. The "time spent in children" of `a' should
-include the time spent in its subroutine `b' and in `b''s
-subroutines--but one of `b''s subroutines is `a'! How much of `a''s
-time should be included in the children of `a', when `a' is indirectly
-recursive?
-
- The way `gprof' resolves this paradox is by creating a single entry
-for the cycle as a whole. The primary line of this entry describes the
-total time spent directly in the functions of the cycle. The
-"subroutines" of the cycle are the individual functions of the cycle,
-and all other functions that were called directly by them. The
-"callers" of the cycle are the functions, outside the cycle, that
-called functions in the cycle.
-
- Here is an example portion of a call graph which shows a cycle
-containing functions `a' and `b'. The cycle was entered by a call to
-`a' from `main'; both `a' and `b' called `c'.
-
- index % time self children called name
- ----------------------------------------
- 1.77 0 1/1 main [2]
- [3] 91.71 1.77 0 1+5 <cycle 1 as a whole> [3]
- 1.02 0 3 b <cycle 1> [4]
- 0.75 0 2 a <cycle 1> [5]
- ----------------------------------------
- 3 a <cycle 1> [5]
- [4] 52.85 1.02 0 0 b <cycle 1> [4]
- 2 a <cycle 1> [5]
- 0 0 3/6 c [6]
- ----------------------------------------
- 1.77 0 1/1 main [2]
- 2 b <cycle 1> [4]
- [5] 38.86 0.75 0 1 a <cycle 1> [5]
- 3 b <cycle 1> [4]
- 0 0 3/6 c [6]
- ----------------------------------------
-
-(The entire call graph for this program contains in addition an entry
-for `main', which calls `a', and an entry for `c', with callers `a' and
-`b'.)
-
- index % time self children called name
- <spontaneous>
- [1] 100.00 0 1.93 0 start [1]
- 0.16 1.77 1/1 main [2]
- ----------------------------------------
- 0.16 1.77 1/1 start [1]
- [2] 100.00 0.16 1.77 1 main [2]
- 1.77 0 1/1 a <cycle 1> [5]
- ----------------------------------------
- 1.77 0 1/1 main [2]
- [3] 91.71 1.77 0 1+5 <cycle 1 as a whole> [3]
- 1.02 0 3 b <cycle 1> [4]
- 0.75 0 2 a <cycle 1> [5]
- 0 0 6/6 c [6]
- ----------------------------------------
- 3 a <cycle 1> [5]
- [4] 52.85 1.02 0 0 b <cycle 1> [4]
- 2 a <cycle 1> [5]
- 0 0 3/6 c [6]
- ----------------------------------------
- 1.77 0 1/1 main [2]
- 2 b <cycle 1> [4]
- [5] 38.86 0.75 0 1 a <cycle 1> [5]
- 3 b <cycle 1> [4]
- 0 0 3/6 c [6]
- ----------------------------------------
- 0 0 3/6 b <cycle 1> [4]
- 0 0 3/6 a <cycle 1> [5]
- [6] 0.00 0 0 6 c [6]
- ----------------------------------------
-
- The `self' field of the cycle's primary line is the total time spent
-in all the functions of the cycle. It equals the sum of the `self'
-fields for the individual functions in the cycle, found in the entry in
-the subroutine lines for these functions.
-
- The `children' fields of the cycle's primary line and subroutine
-lines count only subroutines outside the cycle. Even though `a' calls
-`b', the time spent in those calls to `b' is not counted in `a''s
-`children' time. Thus, we do not encounter the problem of what to do
-when the time in those calls to `b' includes indirect recursive calls
-back to `a'.
-
- The `children' field of a caller-line in the cycle's entry estimates
-the amount of time spent _in the whole cycle_, and its other
-subroutines, on the times when that caller called a function in the
-cycle.
-
- The `called' field in the primary line for the cycle has two numbers:
-first, the number of times functions in the cycle were called by
-functions outside the cycle; second, the number of times they were
-called by functions in the cycle (including times when a function in
-the cycle calls itself). This is a generalization of the usual split
-into non-recursive and recursive calls.
-
- The `called' field of a subroutine-line for a cycle member in the
-cycle's entry says how many time that function was called from
-functions in the cycle. The total of all these is the second number in
-the primary line's `called' field.
-
- In the individual entry for a function in a cycle, the other
-functions in the same cycle can appear as subroutines and as callers.
-These lines show how many times each function in the cycle called or
-was called from each other function in the cycle. The `self' and
-`children' fields in these lines are blank because of the difficulty of
-defining meanings for them when recursion is going on.
-
-\1f
-File: gprof.info, Node: Line-by-line, Next: Annotated Source, Prev: Call Graph, Up: Output
-
-5.3 Line-by-line Profiling
-==========================
-
-`gprof''s `-l' option causes the program to perform "line-by-line"
-profiling. In this mode, histogram samples are assigned not to
-functions, but to individual lines of source code. This only works
-with programs compiled with older versions of the `gcc' compiler.
-Newer versions of `gcc' use a different program - `gcov' - to display
-line-by-line profiling information.
-
- With the older versions of `gcc' the program usually has to be
-compiled with a `-g' option, in addition to `-pg', in order to generate
-debugging symbols for tracking source code lines. Note, in much older
-versions of `gcc' the program had to be compiled with the `-a' command
-line option as well.
-
- The flat profile is the most useful output table in line-by-line
-mode. The call graph isn't as useful as normal, since the current
-version of `gprof' does not propagate call graph arcs from source code
-lines to the enclosing function. The call graph does, however, show
-each line of code that called each function, along with a count.
-
- Here is a section of `gprof''s output, without line-by-line
-profiling. Note that `ct_init' accounted for four histogram hits, and
-13327 calls to `init_block'.
-
- Flat profile:
-
- Each sample counts as 0.01 seconds.
- % cumulative self self total
- time seconds seconds calls us/call us/call name
- 30.77 0.13 0.04 6335 6.31 6.31 ct_init
-
-
- Call graph (explanation follows)
-
-
- granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
-
- index % time self children called name
-
- 0.00 0.00 1/13496 name_too_long
- 0.00 0.00 40/13496 deflate
- 0.00 0.00 128/13496 deflate_fast
- 0.00 0.00 13327/13496 ct_init
- [7] 0.0 0.00 0.00 13496 init_block
-
- Now let's look at some of `gprof''s output from the same program run,
-this time with line-by-line profiling enabled. Note that `ct_init''s
-four histogram hits are broken down into four lines of source code--one
-hit occurred on each of lines 349, 351, 382 and 385. In the call graph,
-note how `ct_init''s 13327 calls to `init_block' are broken down into
-one call from line 396, 3071 calls from line 384, 3730 calls from line
-385, and 6525 calls from 387.
-
- Flat profile:
-
- Each sample counts as 0.01 seconds.
- % cumulative self
- time seconds seconds calls name
- 7.69 0.10 0.01 ct_init (trees.c:349)
- 7.69 0.11 0.01 ct_init (trees.c:351)
- 7.69 0.12 0.01 ct_init (trees.c:382)
- 7.69 0.13 0.01 ct_init (trees.c:385)
-
-
- Call graph (explanation follows)
-
-
- granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
-
- % time self children called name
-
- 0.00 0.00 1/13496 name_too_long (gzip.c:1440)
- 0.00 0.00 1/13496 deflate (deflate.c:763)
- 0.00 0.00 1/13496 ct_init (trees.c:396)
- 0.00 0.00 2/13496 deflate (deflate.c:727)
- 0.00 0.00 4/13496 deflate (deflate.c:686)
- 0.00 0.00 5/13496 deflate (deflate.c:675)
- 0.00 0.00 12/13496 deflate (deflate.c:679)
- 0.00 0.00 16/13496 deflate (deflate.c:730)
- 0.00 0.00 128/13496 deflate_fast (deflate.c:654)
- 0.00 0.00 3071/13496 ct_init (trees.c:384)
- 0.00 0.00 3730/13496 ct_init (trees.c:385)
- 0.00 0.00 6525/13496 ct_init (trees.c:387)
- [6] 0.0 0.00 0.00 13496 init_block (trees.c:408)
-
-\1f
-File: gprof.info, Node: Annotated Source, Prev: Line-by-line, Up: Output
-
-5.4 The Annotated Source Listing
-================================
-
-`gprof''s `-A' option triggers an annotated source listing, which lists
-the program's source code, each function labeled with the number of
-times it was called. You may also need to specify the `-I' option, if
-`gprof' can't find the source code files.
-
- With older versions of `gcc' compiling with `gcc ... -g -pg -a'
-augments your program with basic-block counting code, in addition to
-function counting code. This enables `gprof' to determine how many
-times each line of code was executed. With newer versions of `gcc'
-support for displaying basic-block counts is provided by the `gcov'
-program.
-
- For example, consider the following function, taken from gzip, with
-line numbers added:
-
- 1 ulg updcrc(s, n)
- 2 uch *s;
- 3 unsigned n;
- 4 {
- 5 register ulg c;
- 6
- 7 static ulg crc = (ulg)0xffffffffL;
- 8
- 9 if (s == NULL) {
- 10 c = 0xffffffffL;
- 11 } else {
- 12 c = crc;
- 13 if (n) do {
- 14 c = crc_32_tab[...];
- 15 } while (--n);
- 16 }
- 17 crc = c;
- 18 return c ^ 0xffffffffL;
- 19 }
-
- `updcrc' has at least five basic-blocks. One is the function
-itself. The `if' statement on line 9 generates two more basic-blocks,
-one for each branch of the `if'. A fourth basic-block results from the
-`if' on line 13, and the contents of the `do' loop form the fifth
-basic-block. The compiler may also generate additional basic-blocks to
-handle various special cases.
-
- A program augmented for basic-block counting can be analyzed with
-`gprof -l -A'. The `-x' option is also helpful, to ensure that each
-line of code is labeled at least once. Here is `updcrc''s annotated
-source listing for a sample `gzip' run:
-
- ulg updcrc(s, n)
- uch *s;
- unsigned n;
- 2 ->{
- register ulg c;
-
- static ulg crc = (ulg)0xffffffffL;
-
- 2 -> if (s == NULL) {
- 1 -> c = 0xffffffffL;
- 1 -> } else {
- 1 -> c = crc;
- 1 -> if (n) do {
- 26312 -> c = crc_32_tab[...];
- 26312,1,26311 -> } while (--n);
- }
- 2 -> crc = c;
- 2 -> return c ^ 0xffffffffL;
- 2 ->}
-
- In this example, the function was called twice, passing once through
-each branch of the `if' statement. The body of the `do' loop was
-executed a total of 26312 times. Note how the `while' statement is
-annotated. It began execution 26312 times, once for each iteration
-through the loop. One of those times (the last time) it exited, while
-it branched back to the beginning of the loop 26311 times.
-
-\1f
-File: gprof.info, Node: Inaccuracy, Next: How do I?, Prev: Output, Up: Top
-
-6 Inaccuracy of `gprof' Output
-******************************
-
-* Menu:
-
-* Sampling Error:: Statistical margins of error
-* Assumptions:: Estimating children times
-
-\1f
-File: gprof.info, Node: Sampling Error, Next: Assumptions, Up: Inaccuracy
-
-6.1 Statistical Sampling Error
-==============================
-
-The run-time figures that `gprof' gives you are based on a sampling
-process, so they are subject to statistical inaccuracy. If a function
-runs only a small amount of time, so that on the average the sampling
-process ought to catch that function in the act only once, there is a
-pretty good chance it will actually find that function zero times, or
-twice.
-
- By contrast, the number-of-calls and basic-block figures are derived
-by counting, not sampling. They are completely accurate and will not
-vary from run to run if your program is deterministic.
-
- The "sampling period" that is printed at the beginning of the flat
-profile says how often samples are taken. The rule of thumb is that a
-run-time figure is accurate if it is considerably bigger than the
-sampling period.
-
- The actual amount of error can be predicted. For N samples, the
-_expected_ error is the square-root of N. For example, if the sampling
-period is 0.01 seconds and `foo''s run-time is 1 second, N is 100
-samples (1 second/0.01 seconds), sqrt(N) is 10 samples, so the expected
-error in `foo''s run-time is 0.1 seconds (10*0.01 seconds), or ten
-percent of the observed value. Again, if the sampling period is 0.01
-seconds and `bar''s run-time is 100 seconds, N is 10000 samples,
-sqrt(N) is 100 samples, so the expected error in `bar''s run-time is 1
-second, or one percent of the observed value. It is likely to vary
-this much _on the average_ from one profiling run to the next.
-(_Sometimes_ it will vary more.)
-
- This does not mean that a small run-time figure is devoid of
-information. If the program's _total_ run-time is large, a small
-run-time for one function does tell you that that function used an
-insignificant fraction of the whole program's time. Usually this means
-it is not worth optimizing.
-
- One way to get more accuracy is to give your program more (but
-similar) input data so it will take longer. Another way is to combine
-the data from several runs, using the `-s' option of `gprof'. Here is
-how:
-
- 1. Run your program once.
-
- 2. Issue the command `mv gmon.out gmon.sum'.
-
- 3. Run your program again, the same as before.
-
- 4. Merge the new data in `gmon.out' into `gmon.sum' with this command:
-
- gprof -s EXECUTABLE-FILE gmon.out gmon.sum
-
- 5. Repeat the last two steps as often as you wish.
-
- 6. Analyze the cumulative data using this command:
-
- gprof EXECUTABLE-FILE gmon.sum > OUTPUT-FILE
-
-\1f
-File: gprof.info, Node: Assumptions, Prev: Sampling Error, Up: Inaccuracy
-
-6.2 Estimating `children' Times
-===============================
-
-Some of the figures in the call graph are estimates--for example, the
-`children' time values and all the time figures in caller and
-subroutine lines.
-
- There is no direct information about these measurements in the
-profile data itself. Instead, `gprof' estimates them by making an
-assumption about your program that might or might not be true.
-
- The assumption made is that the average time spent in each call to
-any function `foo' is not correlated with who called `foo'. If `foo'
-used 5 seconds in all, and 2/5 of the calls to `foo' came from `a',
-then `foo' contributes 2 seconds to `a''s `children' time, by
-assumption.
-
- This assumption is usually true enough, but for some programs it is
-far from true. Suppose that `foo' returns very quickly when its
-argument is zero; suppose that `a' always passes zero as an argument,
-while other callers of `foo' pass other arguments. In this program,
-all the time spent in `foo' is in the calls from callers other than `a'.
-But `gprof' has no way of knowing this; it will blindly and incorrectly
-charge 2 seconds of time in `foo' to the children of `a'.
-
- We hope some day to put more complete data into `gmon.out', so that
-this assumption is no longer needed, if we can figure out how. For the
-novice, the estimated figures are usually more useful than misleading.
-
-\1f
-File: gprof.info, Node: How do I?, Next: Incompatibilities, Prev: Inaccuracy, Up: Top
-
-7 Answers to Common Questions
-*****************************
-
-How can I get more exact information about hot spots in my program?
- Looking at the per-line call counts only tells part of the story.
- Because `gprof' can only report call times and counts by function,
- the best way to get finer-grained information on where the program
- is spending its time is to re-factor large functions into sequences
- of calls to smaller ones. Beware however that this can introduce
- artificial hot spots since compiling with `-pg' adds a significant
- overhead to function calls. An alternative solution is to use a
- non-intrusive profiler, e.g. oprofile.
-
-How do I find which lines in my program were executed the most times?
- Use the `gcov' program.
-
-How do I find which lines in my program called a particular function?
- Use `gprof -l' and lookup the function in the call graph. The
- callers will be broken down by function and line number.
-
-How do I analyze a program that runs for less than a second?
- Try using a shell script like this one:
-
- for i in `seq 1 100`; do
- fastprog
- mv gmon.out gmon.out.$i
- done
-
- gprof -s fastprog gmon.out.*
-
- gprof fastprog gmon.sum
-
- If your program is completely deterministic, all the call counts
- will be simple multiples of 100 (i.e., a function called once in
- each run will appear with a call count of 100).
-
-
-\1f
-File: gprof.info, Node: Incompatibilities, Next: Details, Prev: How do I?, Up: Top
-
-8 Incompatibilities with Unix `gprof'
-*************************************
-
-GNU `gprof' and Berkeley Unix `gprof' use the same data file
-`gmon.out', and provide essentially the same information. But there
-are a few differences.
-
- * GNU `gprof' uses a new, generalized file format with support for
- basic-block execution counts and non-realtime histograms. A magic
- cookie and version number allows `gprof' to easily identify new
- style files. Old BSD-style files can still be read. *Note
- Profiling Data File Format: File Format.
-
- * For a recursive function, Unix `gprof' lists the function as a
- parent and as a child, with a `calls' field that lists the number
- of recursive calls. GNU `gprof' omits these lines and puts the
- number of recursive calls in the primary line.
-
- * When a function is suppressed from the call graph with `-e', GNU
- `gprof' still lists it as a subroutine of functions that call it.
-
- * GNU `gprof' accepts the `-k' with its argument in the form
- `from/to', instead of `from to'.
-
- * In the annotated source listing, if there are multiple basic
- blocks on the same line, GNU `gprof' prints all of their counts,
- separated by commas.
-
- * The blurbs, field widths, and output formats are different. GNU
- `gprof' prints blurbs after the tables, so that you can see the
- tables without skipping the blurbs.
-
-\1f
-File: gprof.info, Node: Details, Next: GNU Free Documentation License, Prev: Incompatibilities, Up: Top
-
-9 Details of Profiling
-**********************
-
-* Menu:
-
-* Implementation:: How a program collects profiling information
-* File Format:: Format of `gmon.out' files
-* Internals:: `gprof''s internal operation
-* Debugging:: Using `gprof''s `-d' option
-
-\1f
-File: gprof.info, Node: Implementation, Next: File Format, Up: Details
-
-9.1 Implementation of Profiling
-===============================
-
-Profiling works by changing how every function in your program is
-compiled so that when it is called, it will stash away some information
-about where it was called from. From this, the profiler can figure out
-what function called it, and can count how many times it was called.
-This change is made by the compiler when your program is compiled with
-the `-pg' option, which causes every function to call `mcount' (or
-`_mcount', or `__mcount', depending on the OS and compiler) as one of
-its first operations.
-
- The `mcount' routine, included in the profiling library, is
-responsible for recording in an in-memory call graph table both its
-parent routine (the child) and its parent's parent. This is typically
-done by examining the stack frame to find both the address of the
-child, and the return address in the original parent. Since this is a
-very machine-dependent operation, `mcount' itself is typically a short
-assembly-language stub routine that extracts the required information,
-and then calls `__mcount_internal' (a normal C function) with two
-arguments--`frompc' and `selfpc'. `__mcount_internal' is responsible
-for maintaining the in-memory call graph, which records `frompc',
-`selfpc', and the number of times each of these call arcs was traversed.
-
- GCC Version 2 provides a magical function
-(`__builtin_return_address'), which allows a generic `mcount' function
-to extract the required information from the stack frame. However, on
-some architectures, most notably the SPARC, using this builtin can be
-very computationally expensive, and an assembly language version of
-`mcount' is used for performance reasons.
-
- Number-of-calls information for library routines is collected by
-using a special version of the C library. The programs in it are the
-same as in the usual C library, but they were compiled with `-pg'. If
-you link your program with `gcc ... -pg', it automatically uses the
-profiling version of the library.
-
- Profiling also involves watching your program as it runs, and
-keeping a histogram of where the program counter happens to be every
-now and then. Typically the program counter is looked at around 100
-times per second of run time, but the exact frequency may vary from
-system to system.
-
- This is done is one of two ways. Most UNIX-like operating systems
-provide a `profil()' system call, which registers a memory array with
-the kernel, along with a scale factor that determines how the program's
-address space maps into the array. Typical scaling values cause every
-2 to 8 bytes of address space to map into a single array slot. On
-every tick of the system clock (assuming the profiled program is
-running), the value of the program counter is examined and the
-corresponding slot in the memory array is incremented. Since this is
-done in the kernel, which had to interrupt the process anyway to handle
-the clock interrupt, very little additional system overhead is required.
-
- However, some operating systems, most notably Linux 2.0 (and
-earlier), do not provide a `profil()' system call. On such a system,
-arrangements are made for the kernel to periodically deliver a signal
-to the process (typically via `setitimer()'), which then performs the
-same operation of examining the program counter and incrementing a slot
-in the memory array. Since this method requires a signal to be
-delivered to user space every time a sample is taken, it uses
-considerably more overhead than kernel-based profiling. Also, due to
-the added delay required to deliver the signal, this method is less
-accurate as well.
-
- A special startup routine allocates memory for the histogram and
-either calls `profil()' or sets up a clock signal handler. This
-routine (`monstartup') can be invoked in several ways. On Linux
-systems, a special profiling startup file `gcrt0.o', which invokes
-`monstartup' before `main', is used instead of the default `crt0.o'.
-Use of this special startup file is one of the effects of using `gcc
-... -pg' to link. On SPARC systems, no special startup files are used.
-Rather, the `mcount' routine, when it is invoked for the first time
-(typically when `main' is called), calls `monstartup'.
-
- If the compiler's `-a' option was used, basic-block counting is also
-enabled. Each object file is then compiled with a static array of
-counts, initially zero. In the executable code, every time a new
-basic-block begins (i.e., when an `if' statement appears), an extra
-instruction is inserted to increment the corresponding count in the
-array. At compile time, a paired array was constructed that recorded
-the starting address of each basic-block. Taken together, the two
-arrays record the starting address of every basic-block, along with the
-number of times it was executed.
-
- The profiling library also includes a function (`mcleanup') which is
-typically registered using `atexit()' to be called as the program
-exits, and is responsible for writing the file `gmon.out'. Profiling
-is turned off, various headers are output, and the histogram is
-written, followed by the call-graph arcs and the basic-block counts.
-
- The output from `gprof' gives no indication of parts of your program
-that are limited by I/O or swapping bandwidth. This is because samples
-of the program counter are taken at fixed intervals of the program's
-run time. Therefore, the time measurements in `gprof' output say
-nothing about time that your program was not running. For example, a
-part of the program that creates so much data that it cannot all fit in
-physical memory at once may run very slowly due to thrashing, but
-`gprof' will say it uses little time. On the other hand, sampling by
-run time has the advantage that the amount of load due to other users
-won't directly affect the output you get.
-
-\1f
-File: gprof.info, Node: File Format, Next: Internals, Prev: Implementation, Up: Details
-
-9.2 Profiling Data File Format
-==============================
-
-The old BSD-derived file format used for profile data does not contain a
-magic cookie that allows to check whether a data file really is a
-`gprof' file. Furthermore, it does not provide a version number, thus
-rendering changes to the file format almost impossible. GNU `gprof'
-uses a new file format that provides these features. For backward
-compatibility, GNU `gprof' continues to support the old BSD-derived
-format, but not all features are supported with it. For example,
-basic-block execution counts cannot be accommodated by the old file
-format.
-
- The new file format is defined in header file `gmon_out.h'. It
-consists of a header containing the magic cookie and a version number,
-as well as some spare bytes available for future extensions. All data
-in a profile data file is in the native format of the target for which
-the profile was collected. GNU `gprof' adapts automatically to the
-byte-order in use.
-
- In the new file format, the header is followed by a sequence of
-records. Currently, there are three different record types: histogram
-records, call-graph arc records, and basic-block execution count
-records. Each file can contain any number of each record type. When
-reading a file, GNU `gprof' will ensure records of the same type are
-compatible with each other and compute the union of all records. For
-example, for basic-block execution counts, the union is simply the sum
-of all execution counts for each basic-block.
-
-9.2.1 Histogram Records
------------------------
-
-Histogram records consist of a header that is followed by an array of
-bins. The header contains the text-segment range that the histogram
-spans, the size of the histogram in bytes (unlike in the old BSD
-format, this does not include the size of the header), the rate of the
-profiling clock, and the physical dimension that the bin counts
-represent after being scaled by the profiling clock rate. The physical
-dimension is specified in two parts: a long name of up to 15 characters
-and a single character abbreviation. For example, a histogram
-representing real-time would specify the long name as "seconds" and the
-abbreviation as "s". This feature is useful for architectures that
-support performance monitor hardware (which, fortunately, is becoming
-increasingly common). For example, under DEC OSF/1, the "uprofile"
-command can be used to produce a histogram of, say, instruction cache
-misses. In this case, the dimension in the histogram header could be
-set to "i-cache misses" and the abbreviation could be set to "1"
-(because it is simply a count, not a physical dimension). Also, the
-profiling rate would have to be set to 1 in this case.
-
- Histogram bins are 16-bit numbers and each bin represent an equal
-amount of text-space. For example, if the text-segment is one thousand
-bytes long and if there are ten bins in the histogram, each bin
-represents one hundred bytes.
-
-9.2.2 Call-Graph Records
-------------------------
-
-Call-graph records have a format that is identical to the one used in
-the BSD-derived file format. It consists of an arc in the call graph
-and a count indicating the number of times the arc was traversed during
-program execution. Arcs are specified by a pair of addresses: the
-first must be within caller's function and the second must be within
-the callee's function. When performing profiling at the function
-level, these addresses can point anywhere within the respective
-function. However, when profiling at the line-level, it is better if
-the addresses are as close to the call-site/entry-point as possible.
-This will ensure that the line-level call-graph is able to identify
-exactly which line of source code performed calls to a function.
-
-9.2.3 Basic-Block Execution Count Records
------------------------------------------
-
-Basic-block execution count records consist of a header followed by a
-sequence of address/count pairs. The header simply specifies the
-length of the sequence. In an address/count pair, the address
-identifies a basic-block and the count specifies the number of times
-that basic-block was executed. Any address within the basic-address can
-be used.
-
-\1f
-File: gprof.info, Node: Internals, Next: Debugging, Prev: File Format, Up: Details
-
-9.3 `gprof''s Internal Operation
-================================
-
-Like most programs, `gprof' begins by processing its options. During
-this stage, it may building its symspec list (`sym_ids.c:sym_id_add'),
-if options are specified which use symspecs. `gprof' maintains a
-single linked list of symspecs, which will eventually get turned into
-12 symbol tables, organized into six include/exclude pairs--one pair
-each for the flat profile (INCL_FLAT/EXCL_FLAT), the call graph arcs
-(INCL_ARCS/EXCL_ARCS), printing in the call graph
-(INCL_GRAPH/EXCL_GRAPH), timing propagation in the call graph
-(INCL_TIME/EXCL_TIME), the annotated source listing
-(INCL_ANNO/EXCL_ANNO), and the execution count listing
-(INCL_EXEC/EXCL_EXEC).
-
- After option processing, `gprof' finishes building the symspec list
-by adding all the symspecs in `default_excluded_list' to the exclude
-lists EXCL_TIME and EXCL_GRAPH, and if line-by-line profiling is
-specified, EXCL_FLAT as well. These default excludes are not added to
-EXCL_ANNO, EXCL_ARCS, and EXCL_EXEC.
-
- Next, the BFD library is called to open the object file, verify that
-it is an object file, and read its symbol table (`core.c:core_init'),
-using `bfd_canonicalize_symtab' after mallocing an appropriately sized
-array of symbols. At this point, function mappings are read (if the
-`--file-ordering' option has been specified), and the core text space
-is read into memory (if the `-c' option was given).
-
- `gprof''s own symbol table, an array of Sym structures, is now built.
-This is done in one of two ways, by one of two routines, depending on
-whether line-by-line profiling (`-l' option) has been enabled. For
-normal profiling, the BFD canonical symbol table is scanned. For
-line-by-line profiling, every text space address is examined, and a new
-symbol table entry gets created every time the line number changes. In
-either case, two passes are made through the symbol table--one to count
-the size of the symbol table required, and the other to actually read
-the symbols. In between the two passes, a single array of type `Sym'
-is created of the appropriate length. Finally,
-`symtab.c:symtab_finalize' is called to sort the symbol table and
-remove duplicate entries (entries with the same memory address).
-
- The symbol table must be a contiguous array for two reasons. First,
-the `qsort' library function (which sorts an array) will be used to
-sort the symbol table. Also, the symbol lookup routine
-(`symtab.c:sym_lookup'), which finds symbols based on memory address,
-uses a binary search algorithm which requires the symbol table to be a
-sorted array. Function symbols are indicated with an `is_func' flag.
-Line number symbols have no special flags set. Additionally, a symbol
-can have an `is_static' flag to indicate that it is a local symbol.
-
- With the symbol table read, the symspecs can now be translated into
-Syms (`sym_ids.c:sym_id_parse'). Remember that a single symspec can
-match multiple symbols. An array of symbol tables (`syms') is created,
-each entry of which is a symbol table of Syms to be included or
-excluded from a particular listing. The master symbol table and the
-symspecs are examined by nested loops, and every symbol that matches a
-symspec is inserted into the appropriate syms table. This is done
-twice, once to count the size of each required symbol table, and again
-to build the tables, which have been malloced between passes. From now
-on, to determine whether a symbol is on an include or exclude symspec
-list, `gprof' simply uses its standard symbol lookup routine on the
-appropriate table in the `syms' array.
-
- Now the profile data file(s) themselves are read
-(`gmon_io.c:gmon_out_read'), first by checking for a new-style
-`gmon.out' header, then assuming this is an old-style BSD `gmon.out' if
-the magic number test failed.
-
- New-style histogram records are read by `hist.c:hist_read_rec'. For
-the first histogram record, allocate a memory array to hold all the
-bins, and read them in. When multiple profile data files (or files
-with multiple histogram records) are read, the memory ranges of each
-pair of histogram records must be either equal, or non-overlapping.
-For each pair of histogram records, the resolution (memory region size
-divided by the number of bins) must be the same. The time unit must be
-the same for all histogram records. If the above containts are met, all
-histograms for the same memory range are merged.
-
- As each call graph record is read (`call_graph.c:cg_read_rec'), the
-parent and child addresses are matched to symbol table entries, and a
-call graph arc is created by `cg_arcs.c:arc_add', unless the arc fails
-a symspec check against INCL_ARCS/EXCL_ARCS. As each arc is added, a
-linked list is maintained of the parent's child arcs, and of the child's
-parent arcs. Both the child's call count and the arc's call count are
-incremented by the record's call count.
-
- Basic-block records are read (`basic_blocks.c:bb_read_rec'), but
-only if line-by-line profiling has been selected. Each basic-block
-address is matched to a corresponding line symbol in the symbol table,
-and an entry made in the symbol's bb_addr and bb_calls arrays. Again,
-if multiple basic-block records are present for the same address, the
-call counts are cumulative.
-
- A gmon.sum file is dumped, if requested (`gmon_io.c:gmon_out_write').
-
- If histograms were present in the data files, assign them to symbols
-(`hist.c:hist_assign_samples') by iterating over all the sample bins
-and assigning them to symbols. Since the symbol table is sorted in
-order of ascending memory addresses, we can simple follow along in the
-symbol table as we make our pass over the sample bins. This step
-includes a symspec check against INCL_FLAT/EXCL_FLAT. Depending on the
-histogram scale factor, a sample bin may span multiple symbols, in
-which case a fraction of the sample count is allocated to each symbol,
-proportional to the degree of overlap. This effect is rare for normal
-profiling, but overlaps are more common during line-by-line profiling,
-and can cause each of two adjacent lines to be credited with half a
-hit, for example.
-
- If call graph data is present, `cg_arcs.c:cg_assemble' is called.
-First, if `-c' was specified, a machine-dependent routine (`find_call')
-scans through each symbol's machine code, looking for subroutine call
-instructions, and adding them to the call graph with a zero call count.
-A topological sort is performed by depth-first numbering all the
-symbols (`cg_dfn.c:cg_dfn'), so that children are always numbered less
-than their parents, then making a array of pointers into the symbol
-table and sorting it into numerical order, which is reverse topological
-order (children appear before parents). Cycles are also detected at
-this point, all members of which are assigned the same topological
-number. Two passes are now made through this sorted array of symbol
-pointers. The first pass, from end to beginning (parents to children),
-computes the fraction of child time to propagate to each parent and a
-print flag. The print flag reflects symspec handling of
-INCL_GRAPH/EXCL_GRAPH, with a parent's include or exclude (print or no
-print) property being propagated to its children, unless they
-themselves explicitly appear in INCL_GRAPH or EXCL_GRAPH. A second
-pass, from beginning to end (children to parents) actually propagates
-the timings along the call graph, subject to a check against
-INCL_TIME/EXCL_TIME. With the print flag, fractions, and timings now
-stored in the symbol structures, the topological sort array is now
-discarded, and a new array of pointers is assembled, this time sorted
-by propagated time.
-
- Finally, print the various outputs the user requested, which is now
-fairly straightforward. The call graph (`cg_print.c:cg_print') and
-flat profile (`hist.c:hist_print') are regurgitations of values already
-computed. The annotated source listing
-(`basic_blocks.c:print_annotated_source') uses basic-block information,
-if present, to label each line of code with call counts, otherwise only
-the function call counts are presented.
-
- The function ordering code is marginally well documented in the
-source code itself (`cg_print.c'). Basically, the functions with the
-most use and the most parents are placed first, followed by other
-functions with the most use, followed by lower use functions, followed
-by unused functions at the end.
-
-\1f
-File: gprof.info, Node: Debugging, Prev: Internals, Up: Details
-
-9.4 Debugging `gprof'
-=====================
-
-If `gprof' was compiled with debugging enabled, the `-d' option
-triggers debugging output (to stdout) which can be helpful in
-understanding its operation. The debugging number specified is
-interpreted as a sum of the following options:
-
-2 - Topological sort
- Monitor depth-first numbering of symbols during call graph analysis
-
-4 - Cycles
- Shows symbols as they are identified as cycle heads
-
-16 - Tallying
- As the call graph arcs are read, show each arc and how the total
- calls to each function are tallied
-
-32 - Call graph arc sorting
- Details sorting individual parents/children within each call graph
- entry
-
-64 - Reading histogram and call graph records
- Shows address ranges of histograms as they are read, and each call
- graph arc
-
-128 - Symbol table
- Reading, classifying, and sorting the symbol table from the object
- file. For line-by-line profiling (`-l' option), also shows line
- numbers being assigned to memory addresses.
-
-256 - Static call graph
- Trace operation of `-c' option
-
-512 - Symbol table and arc table lookups
- Detail operation of lookup routines
-
-1024 - Call graph propagation
- Shows how function times are propagated along the call graph
-
-2048 - Basic-blocks
- Shows basic-block records as they are read from profile data (only
- meaningful with `-l' option)
-
-4096 - Symspecs
- Shows symspec-to-symbol pattern matching operation
-
-8192 - Annotate source
- Tracks operation of `-A' option
-
-\1f
-File: gprof.info, Node: GNU Free Documentation License, Prev: Details, Up: Top
-
-Appendix A GNU Free Documentation License
-*****************************************
-
- Version 1.1, March 2000
-
- Copyright (C) 2000, 2003 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.
-
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone
- the effective freedom to copy and redistribute it, with or without
- modifying it, either commercially or noncommercially. Secondarily,
- this License preserves for the author and publisher a way to get
- credit for their work, while not being considered responsible for
- modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to
- software manuals; it can be used for any textual work, regardless
- of subject matter or whether it is published as a printed book.
- We recommend this License principally for works whose purpose is
- instruction or reference.
-
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be distributed
- under the terms of this License. The "Document", below, refers to
- any such manual or work. Any member of the public is a licensee,
- and is addressed as "you."
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter
- section of the Document that deals exclusively with the
- relationship of the publishers or authors of the Document to the
- Document's overall subject (or to related matters) and contains
- nothing that could fall directly within that overall subject.
- (For example, if the Document is in part a textbook of
- mathematics, a Secondary Section may not explain any mathematics.)
- The relationship could be a matter of historical connection with
- the subject or with related matters, or of legal, commercial,
- philosophical, ethical or political position regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, whose contents can be viewed and edited directly
- and straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup has been designed
- to thwart or discourage subsequent modification by readers is not
- Transparent. A copy that is not "Transparent" is called "Opaque."
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human modification.
- Opaque formats include PostScript, PDF, proprietary formats that
- can be read and edited only by proprietary word processors, SGML
- or XML for which the DTD and/or processing tools are not generally
- available, and the machine-generated HTML produced by some word
- processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, "Title
- Page" means the text near the most prominent appearance of the
- work's title, preceding the beginning of the body of the text.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow
- the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more than
- 100, and the Document's license notice requires Cover Texts, you
- must enclose the copies in covers that carry, clearly and legibly,
- all these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the
- title equally prominent and visible. You may add other material
- on the covers in addition. Copying with changes limited to the
- covers, as long as they preserve the title of the Document and
- satisfy these conditions, can be treated as verbatim copying in
- other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy, or
- state in or with each Opaque copy a publicly-accessible
- computer-network location containing a complete Transparent copy
- of the Document, free of added material, which the general
- network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with
- the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version to
- whoever possesses a copy of it. In addition, you must do these
- things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title
- as a previous version if the original publisher of that version
- gives permission.
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it
- has less than five).
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page.
- If there is no section entitled "History" in the Document,
- create one stating the title, year, authors, and publisher of
- the Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in the
- "History" section. You may omit a network location for a work
- that was published at least four years before the Document
- itself, or if the original publisher of the version it refers
- to gives permission.
- K. In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
- M. Delete any section entitled "Endorsements." Such a section
- may not be included in the Modified Version.
- N. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do this,
- add their titles to the list of Invariant Sections in the Modified
- Version's license notice. These titles must be distinct from any
- other section titles.
-
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties-for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition
- of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If the
- Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same entity
- you are acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section
- entitled "History"; likewise combine any sections entitled
- "Acknowledgements", and any sections entitled "Dedications." You
- must delete all sections entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow
- this License in all other respects regarding verbatim copying of
- that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of
- a storage or distribution medium, does not as a whole count as a
- Modified Version of the Document, provided no compilation
- copyright is claimed for the compilation. Such a compilation is
- called an "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document, on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may be
- placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License provided that you also include the
- original English version of this License. In case of a
- disagreement between the translation and the original English
- version of this License, the original English version will prevail.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-====================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.1
- or any later version published by the Free Software Foundation;
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License."
-
- If you have no Invariant Sections, write "with no Invariant Sections"
-instead of saying which ones are invariant. If you have no Front-Cover
-Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
-LIST"; likewise for Back-Cover Texts.
-
- If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License, to
-permit their use in free software.
-
-
-\1f
-Tag Table:
-Node: Top\7f719
-Node: Introduction\7f2033
-Node: Compiling\7f4525
-Node: Executing\7f7996
-Node: Invoking\7f10784
-Node: Output Options\7f12199
-Node: Analysis Options\7f19288
-Node: Miscellaneous Options\7f22689
-Node: Deprecated Options\7f23944
-Node: Symspecs\7f26023
-Node: Output\7f27849
-Node: Flat Profile\7f28889
-Node: Call Graph\7f33842
-Node: Primary\7f37074
-Node: Callers\7f39662
-Node: Subroutines\7f41779
-Node: Cycles\7f43620
-Node: Line-by-line\7f50397
-Node: Annotated Source\7f54470
-Node: Inaccuracy\7f57469
-Node: Sampling Error\7f57727
-Node: Assumptions\7f60297
-Node: How do I?\7f61767
-Node: Incompatibilities\7f63321
-Node: Details\7f64815
-Node: Implementation\7f65208
-Node: File Format\7f71105
-Node: Internals\7f75395
-Node: Debugging\7f83890
-Node: GNU Free Documentation License\7f85491
-\1f
-End Tag Table
+++ /dev/null
-This is ld.info, produced by makeinfo version 4.8 from ld.texinfo.
-
-START-INFO-DIR-ENTRY
-* Ld: (ld). The GNU linker.
-END-INFO-DIR-ENTRY
-
- This file documents the GNU linker LD (GNU Binutils) version 2.17.90.
-
- Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-\1f
-File: ld.info, Node: Top, Next: Overview, Up: (dir)
-
-LD
-**
-
-This file documents the GNU linker ld (GNU Binutils) version 2.17.90.
-
- 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".
-
-* Menu:
-
-* Overview:: Overview
-* Invocation:: Invocation
-* Scripts:: Linker Scripts
-
-* Machine Dependent:: Machine Dependent Features
-
-* BFD:: BFD
-
-* Reporting Bugs:: Reporting Bugs
-* MRI:: MRI Compatible Script Files
-* GNU Free Documentation License:: GNU Free Documentation License
-* LD Index:: LD Index
-
-\1f
-File: ld.info, Node: Overview, Next: Invocation, Prev: Top, Up: Top
-
-1 Overview
-**********
-
-`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 `ld'.
-
- `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.
-
- This version of `ld' uses the general purpose BFD libraries to
-operate on object files. This allows `ld' to read, combine, and write
-object files in many different formats--for example, COFF or `a.out'.
-Different formats may be linked together to produce any available kind
-of object file. *Note BFD::, for more information.
-
- 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,
-`ld' continues executing, allowing you to identify other errors (or, in
-some cases, to get an output file in spite of the error).
-
-\1f
-File: ld.info, Node: Invocation, Next: Scripts, Prev: Overview, Up: Top
-
-2 Invocation
-************
-
-The GNU linker `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.
-
-* Menu:
-
-* Options:: Command Line Options
-* Environment:: Environment Variables
-
-\1f
-File: ld.info, Node: Options, Next: Environment, Up: Invocation
-
-2.1 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 `ld' is to link standard Unix object files on a
-standard, supported Unix system. On such a system, to link a file
-`hello.o':
-
- ld -o OUTPUT /lib/crt0.o hello.o -lc
-
- This tells `ld' to produce a file called OUTPUT as the result of
-linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a',
-which will come from the standard search directories. (See the
-discussion of the `-l' option below.)
-
- Some of the command-line options to `ld' may be specified at any
-point in the command line. However, options which refer to files, such
-as `-l' or `-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.
-
- 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.
-
- Usually the linker is invoked with at least one object file, but you
-can specify other forms of binary input files using `-l', `-R', and the
-script command language. If _no_ binary input files at all are
-specified, the linker does not produce any output, and issues the
-message `No input files'.
-
- 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 `-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
-`INPUT' or `GROUP' to load other objects. Note that specifying a
-script in this way merely augments the main linker script; use the `-T'
-option to replace the default linker script entirely. *Note Scripts::.
-
- 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.
-
- For options whose names are multiple letters, either one dash or two
-can precede the option name; for example, `-trace-symbol' and
-`--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
-`-o' option. So for example `-omagic' sets the output file name to
-`magic' whereas `--omagic' sets the NMAGIC flag on the output.
-
- 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,
-`--trace-symbol foo' and `--trace-symbol=foo' are equivalent. Unique
-abbreviations of the names of multiple-letter options are accepted.
-
- Note--if the linker is being invoked indirectly, via a compiler
-driver (e.g. `gcc') then all the linker command line options should be
-prefixed by `-Wl,' (or whatever is appropriate for the particular
-compiler driver) like this:
-
- gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
-
- This is important, because otherwise the compiler driver program may
-silently drop the linker options, resulting in a bad link.
-
- Here is a table of the generic command line switches accepted by the
-GNU linker:
-
-`@FILE'
- Read command-line options from FILE. The options read are
- inserted in place of the original @FILE option. If FILE does not
- exist, or cannot be read, then the option will be treated
- literally, and not removed.
-
- Options in 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 FILE may itself contain
- additional @FILE options; any such options will be processed
- recursively.
-
-`-aKEYWORD'
- This option is supported for HP/UX compatibility. The KEYWORD
- argument must be one of the strings `archive', `shared', or
- `default'. `-aarchive' is functionally equivalent to `-Bstatic',
- and the other two keywords are functionally equivalent to
- `-Bdynamic'. This option may be used any number of times.
-
-`-AARCHITECTURE'
-`--architecture=ARCHITECTURE'
- In the current release of `ld', this option is useful only for the
- Intel 960 family of architectures. In that `ld' configuration, the
- ARCHITECTURE argument identifies the particular architecture in
- the 960 family, enabling some safeguards and modifying the
- archive-library search path. *Note `ld' and the Intel 960 family:
- i960, for details.
-
- Future releases of `ld' may support similar functionality for
- other architecture families.
-
-`-b INPUT-FORMAT'
-`--format=INPUT-FORMAT'
- `ld' may be configured to support more than one kind of object
- file. If your `ld' is configured this way, you can use the `-b'
- option to specify the binary format for input object files that
- follow this option on the command line. Even when `ld' is
- configured to support alternative object formats, you don't
- usually need to specify this, as `ld' should be configured to
- expect as a default input format the most usual format on each
- machine. 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 `objdump -i'.) *Note BFD::.
-
- You may want to use this option if you are linking files with an
- unusual binary format. You can also use `-b' to switch formats
- explicitly (when linking object files of different formats), by
- including `-b INPUT-FORMAT' before each group of object files in a
- particular format.
-
- The default format is taken from the environment variable
- `GNUTARGET'. *Note Environment::. You can also define the input
- format from a script, using the command `TARGET'; see *Note Format
- Commands::.
-
-`-c MRI-COMMANDFILE'
-`--mri-script=MRI-COMMANDFILE'
- For compatibility with linkers produced by MRI, `ld' accepts script
- files written in an alternate, restricted command language,
- described in *Note MRI Compatible Script Files: MRI. Introduce
- MRI script files with the option `-c'; use the `-T' option to run
- linker scripts written in the general-purpose `ld' scripting
- language. If MRI-CMDFILE does not exist, `ld' looks for it in the
- directories specified by any `-L' options.
-
-`-d'
-`-dc'
-`-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
- `-r'). The script command `FORCE_COMMON_ALLOCATION' has the same
- effect. *Note Miscellaneous Commands::.
-
-`-e ENTRY'
-`--entry=ENTRY'
- Use ENTRY as the explicit symbol for beginning execution of your
- program, rather than the default entry point. If there is no
- symbol named ENTRY, the linker will try to parse ENTRY as a number,
- and use that as the entry address (the number will be interpreted
- in base 10; you may use a leading `0x' for base 16, or a leading
- `0' for base 8). *Note Entry Point::, for a discussion of defaults
- and other ways of specifying the entry point.
-
-`--exclude-libs LIB,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 `--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.
-
-`-E'
-`--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.
-
- 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.
-
- If you use `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.
-
- 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 `--dynamic-list'.
-
-`-EB'
- Link big-endian objects. This affects the default output format.
-
-`-EL'
- Link little-endian objects. This affects the default output
- format.
-
-`-f'
-`--auxiliary 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 NAME.
-
- 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 NAME. If there is one, it will be used instead of
- the definition in the filter object. The shared object NAME need
- not exist. Thus the shared object NAME may be used to provide an
- alternative implementation of certain functions, perhaps for
- debugging or for machine specific performance.
-
- 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.
-
-`-F NAME'
-`--filter 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 NAME.
-
- 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 NAME. Thus the
- filter object can be used to select a subset of the symbols
- provided by the object NAME.
-
- Some older linkers used the `-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 `-b', `--format', `--oformat' options, the
- `TARGET' command in linker scripts, and the `GNUTARGET'
- environment variable. The GNU linker will ignore the `-F' option
- when not creating an ELF shared object.
-
-`-fini 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 `_fini'
- as the function to call.
-
-`-g'
- Ignored. Provided for compatibility with other tools.
-
-`-GVALUE'
-`--gpsize=VALUE'
- Set the maximum size of objects to be optimized using the GP
- register to 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.
-
-`-hNAME'
-`-soname=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.
-
-`-i'
- Perform an incremental link (same as option `-r').
-
-`-init 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 `_init'
- as the function to call.
-
-`-lNAMESPEC'
-`--library=NAMESPEC'
- Add the archive or object file specified by NAMESPEC to the list
- of files to link. This option may be used any number of times.
- If NAMESPEC is of the form `:FILENAME', `ld' will search the
- library path for a file called FILENAME, otherise it will search
- the library path for a file called `libNAMESPEC.a'.
-
- On systems which support shared libraries, `ld' may also search for
- files other than `libNAMESPEC.a'. Specifically, on ELF and SunOS
- systems, `ld' will search a directory for a library called
- `libNAMESPEC.so' before searching for one called `libNAMESPEC.a'.
- (By convention, a `.so' extension indicates a shared library.)
- Note that this behavior does not apply to `:FILENAME', which
- always specifies a file called FILENAME.
-
- 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.
-
- See the `-(' option for a way to force the linker to search
- archives multiple times.
-
- You may list the same archive multiple times on the command line.
-
- This type of archive searching is standard for Unix linkers.
- However, if you are using `ld' on AIX, note that it is different
- from the behaviour of the AIX linker.
-
-`-LSEARCHDIR'
-`--library-path=SEARCHDIR'
- Add path SEARCHDIR to the list of paths that `ld' will search for
- archive libraries and `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 `-L' options apply to all `-l' options,
- regardless of the order in which the options appear.
-
- If SEARCHDIR begins with `=', then the `=' will be replaced by the
- "sysroot prefix", a path specified when the linker is configured.
-
- The default set of paths searched (without being specified with
- `-L') depends on which emulation mode `ld' is using, and in some
- cases also on how it was configured. *Note Environment::.
-
- The paths can also be specified in a link script with the
- `SEARCH_DIR' command. Directories specified this way are searched
- at the point in which the linker script appears in the command
- line.
-
-`-mEMULATION'
- Emulate the EMULATION linker. You can list the available
- emulations with the `--verbose' or `-V' options.
-
- If the `-m' option is not used, the emulation is taken from the
- `LDEMULATION' environment variable, if that is defined.
-
- Otherwise, the default emulation depends upon how the linker was
- configured.
-
-`-M'
-`--print-map'
- Print a link map to the standard output. A link map provides
- information about the link, including the following:
-
- * Where object files are mapped into memory.
-
- * How common symbols are allocated.
-
- * All archive members included in the link, with a mention of
- the symbol which caused the archive member to be brought in.
-
- * The values assigned to symbols.
-
- 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:
-
- foo = 1
- foo = foo * 4
- foo = foo + 8
-
- will produce the following output in the link map if the `-M'
- option is used:
-
- 0x00000001 foo = 0x1
- [0x0000000c] foo = (foo * 0x4)
- [0x0000000c] foo = (foo + 0x8)
-
- See *Note Expressions:: for more information about
- expressions in linker scripts.
-
-`-n'
-`--nmagic'
- Turn off page alignment of sections, and mark the output as
- `NMAGIC' if possible.
-
-`-N'
-`--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 `OMAGIC'. Note: Although a writable
- text section is allowed for PE-COFF targets, it does not conform
- to the format specification published by Microsoft.
-
-`--no-omagic'
- This option negates most of the effects of the `-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 `-Bdynamic' for this.
-
-`-o OUTPUT'
-`--output=OUTPUT'
- Use OUTPUT as the name for the program produced by `ld'; if this
- option is not specified, the name `a.out' is used by default. The
- script command `OUTPUT' can also specify the output file name.
-
-`-O LEVEL'
- If LEVEL is a numeric values greater than zero `ld' optimizes the
- output. This might take significantly longer and therefore
- probably should only be enabled for the final binary. At the
- moment this option only affects ELF shared library generation.
- Future releases of the linker may make more use of this option.
- Also currently there is no difference in the linker's behaviour
- for different non-zero values of this option. Again this may
- change with future releases.
-
-`-q'
-`--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.
-
- This option is currently only supported on ELF platforms.
-
-`--force-dynamic'
- Force the output file to have dynamic sections. This option is
- specific to VxWorks targets.
-
-`-r'
-`--relocatable'
- Generate relocatable output--i.e., generate an output file that
- can in turn serve as input to `ld'. This is often called "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 `OMAGIC'. If this option is not specified, an absolute
- file is produced. When linking C++ programs, this option _will
- not_ resolve references to constructors; to do that, use `-Ur'.
-
- 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 `a.out'-based formats do
- not support partial linking with input files in other formats at
- all.
-
- This option does the same thing as `-i'.
-
-`-R FILENAME'
-`--just-symbols=FILENAME'
- Read symbol names and their addresses from 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.
-
- For compatibility with other ELF linkers, if the `-R' option is
- followed by a directory name, rather than a file name, it is
- treated as the `-rpath' option.
-
-`-s'
-`--strip-all'
- Omit all symbol information from the output file.
-
-`-S'
-`--strip-debug'
- Omit debugger symbol information (but not all symbols) from the
- output file.
-
-`-t'
-`--trace'
- Print the names of the input files as `ld' processes them.
-
-`-T SCRIPTFILE'
-`--script=SCRIPTFILE'
- Use SCRIPTFILE as the linker script. This script replaces `ld''s
- default linker script (rather than adding to it), so COMMANDFILE
- must specify everything necessary to describe the output file.
- *Note Scripts::. If SCRIPTFILE does not exist in the current
- directory, `ld' looks for it in the directories specified by any
- preceding `-L' options. Multiple `-T' options accumulate.
-
-`-dT SCRIPTFILE'
-`--default-script=SCRIPTFILE'
- Use SCRIPTFILE as the default linker script. *Note Scripts::.
-
- This option is similar to the `--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 `--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 `gcc').
-
-`-u SYMBOL'
-`--undefined=SYMBOL'
- Force 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. `-u' may be repeated with
- different option arguments to enter additional undefined symbols.
- This option is equivalent to the `EXTERN' linker script command.
-
-`-Ur'
- For anything other than C++ programs, this option is equivalent to
- `-r': it generates relocatable output--i.e., an output file that
- can in turn serve as input to `ld'. When linking C++ programs,
- `-Ur' _does_ resolve references to constructors, unlike `-r'. It
- does not work to use `-Ur' on files that were themselves linked
- with `-Ur'; once the constructor table has been built, it cannot
- be added to. Use `-Ur' only for the last partial link, and `-r'
- for the others.
-
-`--unique[=SECTION]'
- Creates a separate output section for every input section matching
- SECTION, or if the optional wildcard 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.
-
-`-v'
-`--version'
-`-V'
- Display the version number for `ld'. The `-V' option also lists
- the supported emulations.
-
-`-x'
-`--discard-all'
- Delete all local symbols.
-
-`-X'
-`--discard-locals'
- Delete all temporary local symbols. (These symbols start with
- system-specific local label prefixes, typically `.L' for ELF
- systems or `L' for traditional a.out systems.)
-
-`-y SYMBOL'
-`--trace-symbol=SYMBOL'
- Print the name of each linked file in which SYMBOL appears. This
- option may be given any number of times. On many systems it is
- necessary to prepend an underscore.
-
- This option is useful when you have an undefined symbol in your
- link but don't know where the reference is coming from.
-
-`-Y PATH'
- Add PATH to the default library search path. This option exists
- for Solaris compatibility.
-
-`-z KEYWORD'
- The recognized keywords are:
- `combreloc'
- Combines multiple reloc sections and sorts them to make
- dynamic symbol lookup caching possible.
-
- `defs'
- Disallows undefined symbols in object files. Undefined
- symbols in shared libraries are still allowed.
-
- `execstack'
- Marks the object as requiring executable stack.
-
- `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.
-
- `interpose'
- Marks the object that its symbol table interposes before all
- symbols but the primary executable.
-
- `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.
-
- `loadfltr'
- Marks the object that its filters be processed immediately at
- runtime.
-
- `muldefs'
- Allows multiple definitions.
-
- `nocombreloc'
- Disables multiple reloc sections combining.
-
- `nocopyreloc'
- Disables production of copy relocs.
-
- `nodefaultlib'
- Marks the object that the search for dependencies of this
- object will ignore any default library search paths.
-
- `nodelete'
- Marks the object shouldn't be unloaded at runtime.
-
- `nodlopen'
- Marks the object not available to `dlopen'.
-
- `nodump'
- Marks the object can not be dumped by `dldump'.
-
- `noexecstack'
- Marks the object as not requiring executable stack.
-
- `norelro'
- Don't create an ELF `PT_GNU_RELRO' segment header in the
- object.
-
- `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.
-
- `origin'
- Marks the object may contain $ORIGIN.
-
- `relro'
- Create an ELF `PT_GNU_RELRO' segment header in the object.
-
- `max-page-size=VALUE'
- Set the emulation maximum page size to VALUE.
-
- `common-page-size=VALUE'
- Set the emulation common page size to VALUE.
-
-
- Other keywords are ignored for Solaris compatibility.
-
-`-( ARCHIVES -)'
-`--start-group ARCHIVES --end-group'
- The ARCHIVES should be a list of archive files. They may be
- either explicit file names, or `-l' options.
-
- 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.
-
- 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.
-
-`--accept-unknown-input-arch'
-`--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 `--accept-unknown-input-arch'
- option has been added to restore the old behaviour.
-
-`--as-needed'
-`--no-as-needed'
- This option affects ELF DT_NEEDED tags for dynamic libraries
- mentioned on the command line after the `--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. `--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. `--no-as-needed' restores the
- default behaviour.
-
-`--add-needed'
-`--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 `--no-add-needed' option. Normally, the linker will add
- a DT_NEEDED tag for each dynamic library from DT_NEEDED tags.
- `--no-add-needed' causes DT_NEEDED tags will never be emitted for
- those libraries from DT_NEEDED tags. `--add-needed' restores the
- default behaviour.
-
-`-assert KEYWORD'
- This option is ignored for SunOS compatibility.
-
-`-Bdynamic'
-`-dy'
-`-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 `-l' options which follow it.
-
-`-Bgroup'
- Set the `DF_1_GROUP' flag in the `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.
- `--unresolved-symbols=report-all' is implied. This option is only
- meaningful on ELF platforms which support shared libraries.
-
-`-Bstatic'
-`-dn'
-`-non_shared'
-`-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 `-l' options which follow
- it. This option also implies `--unresolved-symbols=report-all'.
- This option can be used with `-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.
-
-`-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.
-
-`-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.
-
-`--dynamic-list=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.
-
- The format of the dynamic list is the same as the version node
- without scope and node name. See *Note VERSION:: for more
- information.
-
-`--dynamic-list-data'
- Include all global data symbols to the dynamic list.
-
-`--dynamic-list-cpp-new'
- Provide the builtin dynamic list for C++ operator new and delete.
- It is mainly useful for building shared libstdc++.
-
-`--dynamic-list-cpp-typeinfo'
- Provide the builtin dynamic list for C++ runtime type
- identification.
-
-`--check-sections'
-`--no-check-sections'
- Asks the linker _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
- `--check-sections'.
-
-`--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.
-
- 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.
-
-`--no-define-common'
- This option inhibits the assignment of addresses to common symbols.
- The script command `INHIBIT_COMMON_ALLOCATION' has the same effect.
- *Note Miscellaneous Commands::.
-
- The `--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 `--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.
-
-`--defsym SYMBOL=EXPRESSION'
- Create a global symbol in the output file, containing the absolute
- address given by 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 EXPRESSION in
- this context: you may give a hexadecimal constant or the name of
- an existing symbol, or use `+' and `-' to add or subtract
- hexadecimal constants or symbols. If you need more elaborate
- expressions, consider using the linker command language from a
- script (*note Assignment: Symbol Definitions: Assignments.).
- _Note:_ there should be no white space between SYMBOL, the equals
- sign ("<=>"), and EXPRESSION.
-
-`--demangle[=STYLE]'
-`--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 `COLLECT_NO_DEMANGLE' is
- set. These options may be used to override the default.
-
-`--dynamic-linker 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.
-
-`--fatal-warnings'
- Treat all warnings as errors.
-
-`--force-exe-suffix'
- Make sure that an output file has a .exe suffix.
-
- If a successfully built fully linked output file does not have a
- `.exe' or `.dll' suffix, this option forces the linker to copy the
- output file to one of the same name with a `.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 `.exe' suffix.
-
-`--gc-sections'
-`--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 `-r' or `--emit-relocs'. The default behaviour (of
- not performing this garbage collection) can be restored by
- specifying `--no-gc-sections' on the command line.
-
-`--print-gc-sections'
-`--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 `--gc-sections') option. The
- default behaviour (of not listing the sections that are removed)
- can be restored by specifying `--no-print-gc-sections' on the
- command line.
-
-`--help'
- Print a summary of the command-line options on the standard output
- and exit.
-
-`--target-help'
- Print a summary of all target specific options on the standard
- output and exit.
-
-`-Map MAPFILE'
- Print a link map to the file MAPFILE. See the description of the
- `-M' option, above.
-
-`--no-keep-memory'
- `ld' normally optimizes for speed over memory usage by caching the
- symbol tables of input files in memory. This option tells `ld' to
- instead optimize for memory usage, by rereading the symbol tables
- as necessary. This may be required if `ld' runs out of memory
- space while linking a large executable.
-
-`--no-undefined'
-`-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 `--[no-]allow-shlib-undefined' controls the
- behaviour for reporting unresolved references found in shared
- libraries being linked in.
-
-`--allow-multiple-definition'
-`-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.
-
-`--allow-shlib-undefined'
-`--no-allow-shlib-undefined'
- Allows (the default) or disallows undefined symbols in shared
- libraries. This switch is similar to `--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.
-
- The reason that `--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.
-
-`--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.
-
-`--default-symver'
- Create and use a default symbol version (the soname) for
- unversioned exported symbols.
-
-`--default-imported-symver'
- Create and use a default symbol version (the soname) for
- unversioned imported symbols.
-
-`--no-warn-mismatch'
- Normally `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 `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.
-
-`--no-warn-search-mismatch'
- Normally `ld' will give a warning if it finds an incompatible
- library during a library search. This option silences the warning.
-
-`--no-whole-archive'
- Turn off the effect of the `--whole-archive' option for subsequent
- archive files.
-
-`--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.
-
-`-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.
-
-`--oformat OUTPUT-FORMAT'
- `ld' may be configured to support more than one kind of object
- file. If your `ld' is configured this way, you can use the
- `--oformat' option to specify the binary format for the output
- object file. Even when `ld' is configured to support alternative
- object formats, you don't usually need to specify this, as `ld'
- should be configured to produce as a default output format the most
- usual format on each machine. 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 `objdump -i'.) The
- script command `OUTPUT_FORMAT' can also specify the output format,
- but this option overrides it. *Note BFD::.
-
-`-pie'
-`--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.
-
-`-qmagic'
- This option is ignored for Linux compatibility.
-
-`-Qy'
- This option is ignored for SVR4 compatibility.
-
-`--relax'
- An option with machine dependent effects. This option is only
- supported on a few targets. *Note `ld' and the H8/300: H8/300.
- *Note `ld' and the Intel 960 family: i960. *Note `ld' and Xtensa
- Processors: Xtensa. *Note `ld' and the 68HC11 and 68HC12:
- M68HC11/68HC12. *Note `ld' and PowerPC 32-bit ELF Support:
- PowerPC ELF32.
-
- On some platforms, the `--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.
-
- 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.
-
- On platforms where this is not supported, `--relax' is accepted,
- but ignored.
-
-`--retain-symbols-file FILENAME'
- Retain _only_ the symbols listed in the file FILENAME, discarding
- all others. 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.
-
- `--retain-symbols-file' does _not_ discard undefined symbols, or
- symbols needed for relocations.
-
- You may only specify `--retain-symbols-file' once in the command
- line. It overrides `-s' and `-S'.
-
-`-rpath DIR'
- Add a directory to the runtime library search path. This is used
- when linking an ELF executable with shared objects. All `-rpath'
- arguments are concatenated and passed to the runtime linker, which
- uses them to locate shared objects at runtime. The `-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 `-rpath-link' option. If `-rpath' is not used
- when linking an ELF executable, the contents of the environment
- variable `LD_RUN_PATH' will be used if it is defined.
-
- The `-rpath' option may also be used on SunOS. By default, on
- SunOS, the linker will form a runtime search patch out of all the
- `-L' options it is given. If a `-rpath' option is used, the
- runtime search path will be formed exclusively using the `-rpath'
- options, ignoring the `-L' options. This can be useful when using
- gcc, which adds many `-L' options which may be on NFS mounted file
- systems.
-
- For compatibility with other ELF linkers, if the `-R' option is
- followed by a directory name, rather than a file name, it is
- treated as the `-rpath' option.
-
-`-rpath-link DIR'
- When using ELF or SunOS, one shared library may require another.
- This happens when an `ld -shared' link includes a shared library
- as one of the input files.
-
- 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 `-rpath-link'
- option specifies the first set of directories to search. The
- `-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.
-
- 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.
-
- The linker uses the following search paths to locate required
- shared libraries:
- 1. Any directories specified by `-rpath-link' options.
-
- 2. Any directories specified by `-rpath' options. The difference
- between `-rpath' and `-rpath-link' is that directories
- specified by `-rpath' options are included in the executable
- and used at runtime, whereas the `-rpath-link' option is only
- effective at link time. Searching `-rpath' in this way is
- only supported by native linkers and cross linkers which have
- been configured with the `--with-sysroot' option.
-
- 3. On an ELF system, if the `-rpath' and `rpath-link' options
- were not used, search the contents of the environment variable
- `LD_RUN_PATH'. It is for the native linker only.
-
- 4. On SunOS, if the `-rpath' option was not used, search any
- directories specified using `-L' options.
-
- 5. For a native linker, the contents of the environment variable
- `LD_LIBRARY_PATH'.
-
- 6. For a native ELF linker, the directories in `DT_RUNPATH' or
- `DT_RPATH' of a shared library are searched for shared
- libraries needed by it. The `DT_RPATH' entries are ignored if
- `DT_RUNPATH' entries exist.
-
- 7. The default directories, normally `/lib' and `/usr/lib'.
-
- 8. For a native linker on an ELF system, if the file
- `/etc/ld.so.conf' exists, the list of directories found in
- that file.
-
- If the required shared library is not found, the linker will issue
- a warning and continue with the link.
-
-`-shared'
-`-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 `-e' option is not
- used and there are undefined symbols in the link.
-
-`--sort-common'
- This option tells `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.
-
-`--sort-section name'
- This option will apply `SORT_BY_NAME' to all wildcard section
- patterns in the linker script.
-
-`--sort-section alignment'
- This option will apply `SORT_BY_ALIGNMENT' to all wildcard section
- patterns in the linker script.
-
-`--split-by-file [SIZE]'
- Similar to `--split-by-reloc' but creates a new output section for
- each input file when SIZE is reached. SIZE defaults to a size of
- 1 if not given.
-
-`--split-by-reloc [COUNT]'
- Tries to creates extra sections in the output file so that no
- single output section in the file contains more than 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
- COUNT relocations one output section will contain that many
- relocations. COUNT defaults to a value of 32768.
-
-`--stats'
- Compute and display statistics about the operation of the linker,
- such as execution time and memory usage.
-
-`--sysroot=DIRECTORY'
- Use DIRECTORY as the location of the sysroot, overriding the
- configure-time default. This option is only supported by linkers
- that were configured using `--with-sysroot'.
-
-`--traditional-format'
- For some targets, the output of `ld' is different in some ways from
- the output of some existing linker. This switch requests `ld' to
- use the traditional format instead.
-
- For example, on SunOS, `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 `dbx' program can not read the resulting
- program (`gdb' has no trouble). The `--traditional-format' switch
- tells `ld' to not combine duplicate entries.
-
-`--section-start SECTIONNAME=ORG'
- Locate a section in the output file at the absolute address given
- by ORG. You may use this option as many times as necessary to
- locate multiple sections in the command line. ORG must be a
- single hexadecimal integer; for compatibility with other linkers,
- you may omit the leading `0x' usually associated with hexadecimal
- values. _Note:_ there should be no white space between
- SECTIONNAME, the equals sign ("<=>"), and ORG.
-
-`-Tbss ORG'
-`-Tdata ORG'
-`-Ttext ORG'
- Same as -section-start, with `.bss', `.data' or `.text' as the
- SECTIONNAME.
-
-`--unresolved-symbols=METHOD'
- Determine how to handle unresolved symbols. There are four
- possible values for `method':
-
- `ignore-all'
- Do not report any unresolved symbols.
-
- `report-all'
- Report all unresolved symbols. This is the default.
-
- `ignore-in-object-files'
- Report unresolved symbols that are contained in shared
- libraries, but ignore them if they come from regular object
- files.
-
- `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.
-
- The behaviour for shared libraries on their own can also be
- controlled by the `--[no-]allow-shlib-undefined' option.
-
- Normally the linker will generate an error message for each
- reported unresolved symbol but the option
- `--warn-unresolved-symbols' can change this to a warning.
-
-`--dll-verbose'
-`--verbose'
- Display the version number for `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.
-
-`--version-script=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. *Note VERSION::.
-
-`--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.
-
- There are three kinds of global symbols, illustrated here by C
- examples:
-
- `int i = 1;'
- A definition, which goes in the initialized data section of
- the output file.
-
- `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.
-
- `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.
-
- The `--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.
-
- 1. Turning a common symbol into a reference, because there is
- already a definition for the symbol.
- FILE(SECTION): warning: common of `SYMBOL'
- overridden by definition
- FILE(SECTION): warning: defined here
-
- 2. 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.
- FILE(SECTION): warning: definition of `SYMBOL'
- overriding common
- FILE(SECTION): warning: common is here
-
- 3. Merging a common symbol with a previous same-sized common
- symbol.
- FILE(SECTION): warning: multiple common
- of `SYMBOL'
- FILE(SECTION): warning: previous common is here
-
- 4. Merging a common symbol with a previous larger common symbol.
- FILE(SECTION): warning: common of `SYMBOL'
- overridden by larger common
- FILE(SECTION): warning: larger common is here
-
- 5. 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.
- FILE(SECTION): warning: common of `SYMBOL'
- overriding smaller common
- FILE(SECTION): warning: smaller common is here
-
-`--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.
-
-`--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.
-
-`--warn-once'
- Only warn once for each undefined symbol, rather than once per
- module which refers to 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 `SECTIONS' command does not specify a
- start address for the section (*note SECTIONS::).
-
-`--warn-shared-textrel'
- Warn if the linker adds a DT_TEXTREL to a shared object.
-
-`--warn-unresolved-symbols'
- If the linker is going to report an unresolved symbol (see the
- option `--unresolved-symbols') it will normally generate an error.
- This option makes it generate a warning instead.
-
-`--error-unresolved-symbols'
- This restores the linker's default behaviour of generating errors
- when it is reporting unresolved symbols.
-
-`--whole-archive'
- For each archive mentioned on the command line after the
- `--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.
-
- Two notes when using this option from gcc: First, gcc doesn't know
- about this option, so you have to use `-Wl,-whole-archive'.
- Second, don't forget to use `-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.
-
-`--wrap SYMBOL'
- Use a wrapper function for SYMBOL. Any undefined reference to
- SYMBOL will be resolved to `__wrap_SYMBOL'. Any undefined
- reference to `__real_SYMBOL' will be resolved to SYMBOL.
-
- This can be used to provide a wrapper for a system function. The
- wrapper function should be called `__wrap_SYMBOL'. If it wishes
- to call the system function, it should call `__real_SYMBOL'.
-
- Here is a trivial example:
-
- void *
- __wrap_malloc (size_t c)
- {
- printf ("malloc called with %zu\n", c);
- return __real_malloc (c);
- }
-
- If you link other code with this file using `--wrap malloc', then
- all calls to `malloc' will call the function `__wrap_malloc'
- instead. The call to `__real_malloc' in `__wrap_malloc' will call
- the real `malloc' function.
-
- You may wish to provide a `__real_malloc' function as well, so that
- links without the `--wrap' option will succeed. If you do this,
- you should not put the definition of `__real_malloc' in the same
- file as `__wrap_malloc'; if you do, the assembler may resolve the
- call before the linker has a chance to wrap it to `malloc'.
-
-`--eh-frame-hdr'
- Request creation of `.eh_frame_hdr' section and ELF
- `PT_GNU_EH_FRAME' segment header.
-
-`--enable-new-dtags'
-`--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
- `--enable-new-dtags', the dynamic tags will be created as needed.
- If you specify `--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.
-
-`--hash-size=NUMBER'
- Set the default size of the linker's hash tables to a prime number
- close to 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.
-
-`--hash-style=STYLE'
- Set the type of linker's hash table(s). STYLE can be either
- `sysv' for classic ELF `.hash' section, `gnu' for new style GNU
- `.gnu.hash' section or `both' for both the classic ELF `.hash' and
- new style GNU `.gnu.hash' hash tables. The default is `sysv'.
-
-`--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.
-
- 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 `--hash-size'
- switch has been used.
-
- The `--reduce-memory-overheads' switch may be also be used to
- enable other tradeoffs in future versions of the linker.
-
-`--build-id'
-`--build-id=STYLE'
- Request creation of `.note.gnu.build-id' ELF note section. The
- contents of the note are unique bits identifying this linked file.
- STYLE can be `uuid' to use 128 random bits, `sha1' to use a
- 160-bit SHA1 hash on the normative parts of the output contents,
- `md5' to use a 128-bit MD5 hash on the normative parts of the
- output contents, or `0xHEXSTRING' to use a chosen bit string
- specified as an even number of hexadecimal digits (`-' and `:'
- characters between digit pairs are ignored). If STYLE is omitted,
- `sha1' is used.
-
- The `md5' and `sha1' styles produces an identifier that is always
- the same in an identical output file, but will be unique among all
- nonidentical output files. It is not intended to be compared as a
- checksum for the file's contents. A linked file may be changed
- later by other tools, but the build ID bit string identifying the
- original linked file does not change.
-
- Passing `none' for STYLE disables the setting from any
- `--build-id' options earlier on the command line.
-
-2.1.1 Options Specific to i386 PE Targets
------------------------------------------
-
-The i386 PE linker supports the `-shared' option, which causes the
-output to be a dynamically linked library (DLL) instead of a normal
-executable. You should name the output `*.dll' when you use this
-option. In addition, the linker fully supports the standard `*.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).
-
- 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.
-
-`--add-stdcall-alias'
- If given, symbols with a stdcall suffix (@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]
-
-`--base-file FILE'
- Use FILE as the name of a file in which to save the base addresses
- of all the relocations needed for generating DLLs with `dlltool'.
- [This is an i386 PE specific option]
-
-`--dll'
- Create a DLL instead of a regular executable. You may also use
- `-shared' or specify a `LIBRARY' in a given `.def' file. [This
- option is specific to the i386 PE targeted port of the linker]
-
-`--enable-stdcall-fixup'
-`--disable-stdcall-fixup'
- If the link finds a symbol that it cannot resolve, it will attempt
- to do "fuzzy linking" 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 `_foo' might be linked to the
- function `_foo@12', or the undefined symbol `_bar@16' might be
- linked to the function `_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
- `--enable-stdcall-fixup', this feature is fully enabled and
- warnings are not printed. If you specify
- `--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]
-
-`--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 `DllMain@12',
- `DllEntryPoint@0', `DllMainCRTStartup@12', and `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 `_head_' or
- ending with `_iname'. In addition, no symbols from `libgcc',
- `libstd++', `libmingw32', or `crtX.o' will be exported. Symbols
- whose names begin with `__rtti_' or `__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: `_cygwin_dll_entry@12',
- `_cygwin_crt0_common@8', `_cygwin_noncygwin_dll_entry@12',
- `_fmode', `_impure_ptr', `cygwin_attach_dll', `cygwin_premain0',
- `cygwin_premain1', `cygwin_premain2', `cygwin_premain3', and
- `environ'. [This option is specific to the i386 PE targeted port
- of the linker]
-
-`--exclude-symbols SYMBOL,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]
-
-`--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]
-
-`--heap RESERVE'
-`--heap RESERVE,COMMIT'
- Specify the number of bytes 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]
-
-`--image-base VALUE'
- Use 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]
-
-`--kill-at'
- If given, the stdcall suffixes (@NN) will be stripped from symbols
- before they are exported. [This option is specific to the i386 PE
- targeted port of the linker]
-
-`--large-address-aware'
- If given, the appropriate bit in the "Characteristics" 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=VALUE megabytes switch in
- the "[operating systems]" section of the BOOT.INI. Otherwise,
- this bit has no effect. [This option is specific to PE targeted
- ports of the linker]
-
-`--major-image-version VALUE'
- Sets the major number of the "image version". Defaults to 1.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--major-os-version VALUE'
- Sets the major number of the "os version". Defaults to 4. [This
- option is specific to the i386 PE targeted port of the linker]
-
-`--major-subsystem-version VALUE'
- Sets the major number of the "subsystem version". Defaults to 4.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--minor-image-version VALUE'
- Sets the minor number of the "image version". Defaults to 0.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--minor-os-version VALUE'
- Sets the minor number of the "os version". Defaults to 0. [This
- option is specific to the i386 PE targeted port of the linker]
-
-`--minor-subsystem-version VALUE'
- Sets the minor number of the "subsystem version". Defaults to 0.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--output-def FILE'
- The linker will create the file FILE which will contain a DEF file
- corresponding to the DLL the linker is generating. This DEF file
- (which should be called `*.def') may be used to create an import
- library with `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]
-
-`--out-implib FILE'
- The linker will create the file FILE which will contain an import
- lib corresponding to the DLL the linker is generating. This import
- lib (which should be called `*.dll.a' or `*.a' may be used to link
- clients against the generated DLL; this behaviour makes it
- possible to skip a separate `dlltool' import library creation step.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--enable-auto-image-base'
- Automatically choose the image base for DLLs, unless one is
- specified using the `--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]
-
-`--disable-auto-image-base'
- Do not automatically generate a unique image base. If there is no
- user-specified image base (`--image-base') then use the platform
- default. [This option is specific to the i386 PE targeted port of
- the linker]
-
-`--dll-search-prefix STRING'
- When linking dynamically to a dll without an import library,
- search for `<string><basename>.dll' in preference to
- `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
- `--dll-search-prefix=cyg'. [This option is specific to the i386
- PE targeted port of the linker]
-
-`--enable-auto-import'
- Do sophisticated linking of `_symbol' to `__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.
-
- Using 'auto-import' generally will 'just work' - but sometimes you
- may see this message:
-
- "variable '<var>' can't be auto-imported. Please read the
- documentation for ld's `--enable-auto-import' for details."
-
- 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.
-
- There are several ways to address this difficulty, regardless of
- the data type of the exported variable:
-
- 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.
-
- 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:
-
- extern type extern_array[];
- extern_array[1] -->
- { volatile type *t=extern_array; t[1] }
-
- or
-
- extern type extern_array[];
- extern_array[1] -->
- { volatile int t=1; extern_array[t] }
-
- For structs (and most other multiword data types) the only option
- is to make the struct itself (or the long long, or the ...)
- variable:
-
- extern struct s extern_struct;
- extern_struct.field -->
- { volatile struct s *t=&extern_struct; t->field }
-
- or
-
- extern long long extern_ll;
- extern_ll -->
- { volatile long long * local_ll=&extern_ll; *local_ll }
-
- A third method of dealing with this difficulty is to abandon
- 'auto-import' for the offending symbol and mark it with
- `__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:
-
- Original:
- --foo.h
- extern int arr[];
- --foo.c
- #include "foo.h"
- void main(int argc, char **argv){
- printf("%d\n",arr[1]);
- }
-
- Solution 1:
- --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\n",parr[1]);
- }
-
- Solution 2:
- --foo.h
- /* Note: auto-export is assumed (no __declspec(dllexport)) */
- #if (defined(_WIN32) || defined(__CYGWIN__)) && \
- !(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\n",arr[1]);
- }
-
- 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]
-
-`--disable-auto-import'
- Do not attempt to do sophisticated linking of `_symbol' to
- `__imp__symbol' for DATA imports from DLLs. [This option is
- specific to the i386 PE targeted port of the linker]
-
-`--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]
-
-`--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]
-
-`--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]
-
-`--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]
-
-`--stack RESERVE'
-`--stack RESERVE,COMMIT'
- Specify the number of bytes 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]
-
-`--subsystem WHICH'
-`--subsystem WHICH:MAJOR'
-`--subsystem WHICH:MAJOR.MINOR'
- Specifies the subsystem under which your program will execute. The
- legal values for WHICH are `native', `windows', `console',
- `posix', and `xbox'. You may optionally set the subsystem version
- also. Numeric values are also accepted for WHICH. [This option
- is specific to the i386 PE targeted port of the linker]
-
-
-2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets
-------------------------------------------------------------
-
-The 68HC11 and 68HC12 linkers support specific options to control the
-memory bank switching mapping and trampoline code generation.
-
-`--no-trampoline'
- This option disables the generation of trampoline. By default a
- trampoline is generated for each far function which is called
- using a `jsr' instruction (this happens when a pointer to a far
- function is taken).
-
-`--bank-window NAME'
- This option indicates to the linker the name of the memory region
- in the `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.
-
-
-\1f
-File: ld.info, Node: Environment, Prev: Options, Up: Invocation
-
-2.2 Environment Variables
-=========================
-
-You can change the behaviour of `ld' with the environment variables
-`GNUTARGET', `LDEMULATION' and `COLLECT_NO_DEMANGLE'.
-
- `GNUTARGET' determines the input-file object format if you don't use
-`-b' (or its synonym `--format'). Its value should be one of the BFD
-names for an input format (*note BFD::). If there is no `GNUTARGET' in
-the environment, `ld' uses the natural format of the target. If
-`GNUTARGET' is set to `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.
-
- `LDEMULATION' determines the default emulation if you don't use the
-`-m' option. The emulation can affect various aspects of linker
-behaviour, particularly the default linker script. You can list the
-available emulations with the `--verbose' or `-V' options. If the `-m'
-option is not used, and the `LDEMULATION' environment variable is not
-defined, the default emulation depends upon how the linker was
-configured.
-
- Normally, the linker will default to demangling symbols. However, if
-`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 `gcc' linker wrapper program. The default may
-be overridden by the `--demangle' and `--no-demangle' options.
-
-\1f
-File: ld.info, Node: Scripts, Next: Machine Dependent, Prev: Invocation, Up: Top
-
-3 Linker Scripts
-****************
-
-Every link is controlled by a "linker script". This script is written
-in the linker command language.
-
- 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.
-
- 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 `--verbose' command line option to
-display the default linker script. Certain command line options, such
-as `-r' or `-N', will affect the default linker script.
-
- You may supply your own linker script by using the `-T' command line
-option. When you do this, your linker script will replace the default
-linker script.
-
- You may also use linker scripts implicitly by naming them as input
-files to the linker, as though they were files to be linked. *Note
-Implicit Linker Scripts::.
-
-* Menu:
-
-* Basic Script Concepts:: Basic Linker Script Concepts
-* Script Format:: Linker Script Format
-* Simple Example:: Simple Linker Script Example
-* Simple Commands:: Simple Linker Script Commands
-* Assignments:: Assigning Values to Symbols
-* SECTIONS:: SECTIONS Command
-* MEMORY:: MEMORY Command
-* PHDRS:: PHDRS Command
-* VERSION:: VERSION Command
-* Expressions:: Expressions in Linker Scripts
-* Implicit Linker Scripts:: Implicit Linker Scripts
-
-\1f
-File: ld.info, Node: Basic Script Concepts, Next: Script Format, Up: Scripts
-
-3.1 Basic Linker Script Concepts
-================================
-
-We need to define some basic concepts and vocabulary in order to
-describe the linker script language.
-
- 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
-"object file format". Each file is called an "object file". The
-output file is often called an "executable", but for our purposes we
-will also call it an object file. Each object file has, among other
-things, a list of "sections". We sometimes refer to a section in an
-input file as an "input section"; similarly, a section in the output
-file is an "output section".
-
- Each section in an object file has a name and a size. Most sections
-also have an associated block of data, known as the "section contents".
-A section may be marked as "loadable", which mean that the contents
-should be loaded into memory when the output file is run. A section
-with no contents may be "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.
-
- Every loadable or allocatable output section has two addresses. The
-first is the "VMA", or virtual memory address. This is the address the
-section will have when the output file is run. The second is the
-"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.
-
- You can see the sections in an object file by using the `objdump'
-program with the `-h' option.
-
- Every object file also has a list of "symbols", known as the "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.
-
- You can see the symbols in an object file by using the `nm' program,
-or by using the `objdump' program with the `-t' option.
-
-\1f
-File: ld.info, Node: Script Format, Next: Simple Example, Prev: Basic Script Concepts, Up: Scripts
-
-3.2 Linker Script Format
-========================
-
-Linker scripts are text files.
-
- 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.
-
- 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.
-
- You may include comments in linker scripts just as in C, delimited by
-`/*' and `*/'. As in C, comments are syntactically equivalent to
-whitespace.
-
-\1f
-File: ld.info, Node: Simple Example, Next: Simple Commands, Prev: Script Format, Up: Scripts
-
-3.3 Simple Linker Script Example
-================================
-
-Many linker scripts are fairly simple.
-
- The simplest possible linker script has just one command:
-`SECTIONS'. You use the `SECTIONS' command to describe the memory
-layout of the output file.
-
- The `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
-`.text', `.data', and `.bss' sections, respectively. Let's assume
-further that these are the only sections which appear in your input
-files.
-
- 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:
- SECTIONS
- {
- . = 0x10000;
- .text : { *(.text) }
- . = 0x8000000;
- .data : { *(.data) }
- .bss : { *(.bss) }
- }
-
- You write the `SECTIONS' command as the keyword `SECTIONS', followed
-by a series of symbol assignments and output section descriptions
-enclosed in curly braces.
-
- The first line inside the `SECTIONS' command of the above example
-sets the value of the special symbol `.', 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
-`SECTIONS' command, the location counter has the value `0'.
-
- The second line defines an output section, `.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 `*' is a wildcard
-which matches any file name. The expression `*(.text)' means all
-`.text' input sections in all input files.
-
- Since the location counter is `0x10000' when the output section
-`.text' is defined, the linker will set the address of the `.text'
-section in the output file to be `0x10000'.
-
- The remaining lines define the `.data' and `.bss' sections in the
-output file. The linker will place the `.data' output section at
-address `0x8000000'. After the linker places the `.data' output
-section, the value of the location counter will be `0x8000000' plus the
-size of the `.data' output section. The effect is that the linker will
-place the `.bss' output section immediately after the `.data' output
-section in memory.
-
- 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 `.text' and `.data' sections
-will probably satisfy any alignment constraints, but the linker may
-have to create a small gap between the `.data' and `.bss' sections.
-
- That's it! That's a simple and complete linker script.
-
-\1f
-File: ld.info, Node: Simple Commands, Next: Assignments, Prev: Simple Example, Up: Scripts
-
-3.4 Simple Linker Script Commands
-=================================
-
-In this section we describe the simple linker script commands.
-
-* Menu:
-
-* Entry Point:: Setting the entry point
-* File Commands:: Commands dealing with files
-
-* Format Commands:: Commands dealing with object file formats
-
-* Miscellaneous Commands:: Other linker script commands
-
-\1f
-File: ld.info, Node: Entry Point, Next: File Commands, Up: Simple Commands
-
-3.4.1 Setting the Entry Point
------------------------------
-
-The first instruction to execute in a program is called the "entry
-point". You can use the `ENTRY' linker script command to set the entry
-point. The argument is a symbol name:
- ENTRY(SYMBOL)
-
- 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:
- * the `-e' ENTRY command-line option;
-
- * the `ENTRY(SYMBOL)' command in a linker script;
-
- * the value of the symbol `start', if defined;
-
- * the address of the first byte of the `.text' section, if present;
-
- * The address `0'.
-
-\1f
-File: ld.info, Node: File Commands, Next: Format Commands, Prev: Entry Point, Up: Simple Commands
-
-3.4.2 Commands Dealing with Files
----------------------------------
-
-Several linker script commands deal with files.
-
-`INCLUDE FILENAME'
- Include the linker script FILENAME at this point. The file will
- be searched for in the current directory, and in any directory
- specified with the `-L' option. You can nest calls to `INCLUDE'
- up to 10 levels deep.
-
-`INPUT(FILE, FILE, ...)'
-`INPUT(FILE FILE ...)'
- The `INPUT' command directs the linker to include the named files
- in the link, as though they were named on the command line.
-
- For example, if you always want to include `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 `INPUT (subr.o)' in your linker script.
-
- 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 `-T'
- option.
-
- In case a "sysroot prefix" is configured, and the filename starts
- with the `/' character, and the script being processed was located
- inside the "sysroot prefix", the filename will be looked for in
- the "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 `-L' in *Note Command Line Options: Options.
-
- If you use `INPUT (-lFILE)', `ld' will transform the name to
- `libFILE.a', as with the command line argument `-l'.
-
- When you use the `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.
-
-`GROUP(FILE, FILE, ...)'
-`GROUP(FILE FILE ...)'
- The `GROUP' command is like `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 `-('
- in *Note Command Line Options: Options.
-
-`AS_NEEDED(FILE, FILE, ...)'
-`AS_NEEDED(FILE FILE ...)'
- This construct can appear only inside of the `INPUT' or `GROUP'
- commands, among other filenames. The files listed will be handled
- as if they appear directly in the `INPUT' or `GROUP' commands,
- with the exception of ELF shared libraries, that will be added only
- when they are actually needed. This construct essentially enables
- `--as-needed' option for all the files listed inside of it and
- restores previous `--as-needed' resp. `--no-as-needed' setting
- afterwards.
-
-`OUTPUT(FILENAME)'
- The `OUTPUT' command names the output file. Using
- `OUTPUT(FILENAME)' in the linker script is exactly like using `-o
- FILENAME' on the command line (*note Command Line Options:
- Options.). If both are used, the command line option takes
- precedence.
-
- You can use the `OUTPUT' command to define a default name for the
- output file other than the usual default of `a.out'.
-
-`SEARCH_DIR(PATH)'
- The `SEARCH_DIR' command adds PATH to the list of paths where `ld'
- looks for archive libraries. Using `SEARCH_DIR(PATH)' is exactly
- like using `-L PATH' on the command line (*note Command Line
- Options: Options.). If both are used, then the linker will search
- both paths. Paths specified using the command line option are
- searched first.
-
-`STARTUP(FILENAME)'
- The `STARTUP' command is just like the `INPUT' command, except
- that 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.
-
-\1f
-File: ld.info, Node: Format Commands, Next: Miscellaneous Commands, Prev: File Commands, Up: Simple Commands
-
-3.4.3 Commands Dealing with Object File Formats
------------------------------------------------
-
-A couple of linker script commands deal with object file formats.
-
-`OUTPUT_FORMAT(BFDNAME)'
-`OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)'
- The `OUTPUT_FORMAT' command names the BFD format to use for the
- output file (*note BFD::). Using `OUTPUT_FORMAT(BFDNAME)' is
- exactly like using `--oformat BFDNAME' on the command line (*note
- Command Line Options: Options.). If both are used, the command
- line option takes precedence.
-
- You can use `OUTPUT_FORMAT' with three arguments to use different
- formats based on the `-EB' and `-EL' command line options. This
- permits the linker script to set the output format based on the
- desired endianness.
-
- If neither `-EB' nor `-EL' are used, then the output format will
- be the first argument, DEFAULT. If `-EB' is used, the output
- format will be the second argument, BIG. If `-EL' is used, the
- output format will be the third argument, LITTLE.
-
- For example, the default linker script for the MIPS ELF target
- uses this command:
- OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
- This says that the default format for the output file is
- `elf32-bigmips', but if the user uses the `-EL' command line
- option, the output file will be created in the `elf32-littlemips'
- format.
-
-`TARGET(BFDNAME)'
- The `TARGET' command names the BFD format to use when reading input
- files. It affects subsequent `INPUT' and `GROUP' commands. This
- command is like using `-b BFDNAME' on the command line (*note
- Command Line Options: Options.). If the `TARGET' command is used
- but `OUTPUT_FORMAT' is not, then the last `TARGET' command is also
- used to set the format for the output file. *Note BFD::.
-
-\1f
-File: ld.info, Node: Miscellaneous Commands, Prev: Format Commands, Up: Simple Commands
-
-3.4.4 Other Linker Script Commands
-----------------------------------
-
-There are a few other linker scripts commands.
-
-`ASSERT(EXP, MESSAGE)'
- Ensure that EXP is non-zero. If it is zero, then exit the linker
- with an error code, and print MESSAGE.
-
-`EXTERN(SYMBOL SYMBOL ...)'
- Force 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 SYMBOLs for
- each `EXTERN', and you may use `EXTERN' multiple times. This
- command has the same effect as the `-u' command-line option.
-
-`FORCE_COMMON_ALLOCATION'
- This command has the same effect as the `-d' command-line option:
- to make `ld' assign space to common symbols even if a relocatable
- output file is specified (`-r').
-
-`INHIBIT_COMMON_ALLOCATION'
- This command has the same effect as the `--no-define-common'
- command-line option: to make `ld' omit the assignment of addresses
- to common symbols even for a non-relocatable output file.
-
-`NOCROSSREFS(SECTION SECTION ...)'
- This command may be used to tell `ld' to issue an error about any
- references among certain output sections.
-
- 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.
-
- The `NOCROSSREFS' command takes a list of output section names. If
- `ld' detects any cross references between the sections, it reports
- an error and returns a non-zero exit status. Note that the
- `NOCROSSREFS' command uses output section names, not input section
- names.
-
-`OUTPUT_ARCH(BFDARCH)'
- Specify a particular output machine architecture. The argument is
- one of the names used by the BFD library (*note BFD::). You can
- see the architecture of an object file by using the `objdump'
- program with the `-f' option.
-
-\1f
-File: ld.info, Node: Assignments, Next: SECTIONS, Prev: Simple Commands, Up: Scripts
-
-3.5 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.
-
-* Menu:
-
-* Simple Assignments:: Simple Assignments
-* PROVIDE:: PROVIDE
-* PROVIDE_HIDDEN:: PROVIDE_HIDDEN
-* Source Code Reference:: How to use a linker script defined symbol in source code
-
-\1f
-File: ld.info, Node: Simple Assignments, Next: PROVIDE, Up: Assignments
-
-3.5.1 Simple Assignments
-------------------------
-
-You may assign to a symbol using any of the C assignment operators:
-
-`SYMBOL = EXPRESSION ;'
-`SYMBOL += EXPRESSION ;'
-`SYMBOL -= EXPRESSION ;'
-`SYMBOL *= EXPRESSION ;'
-`SYMBOL /= EXPRESSION ;'
-`SYMBOL <<= EXPRESSION ;'
-`SYMBOL >>= EXPRESSION ;'
-`SYMBOL &= EXPRESSION ;'
-`SYMBOL |= EXPRESSION ;'
-
- The first case will define SYMBOL to the value of EXPRESSION. In
-the other cases, SYMBOL must already be defined, and the value will be
-adjusted accordingly.
-
- The special symbol name `.' indicates the location counter. You may
-only use this within a `SECTIONS' command. *Note Location Counter::.
-
- The semicolon after EXPRESSION is required.
-
- Expressions are defined below; see *Note Expressions::.
-
- You may write symbol assignments as commands in their own right, or
-as statements within a `SECTIONS' command, or as part of an output
-section description in a `SECTIONS' command.
-
- The section of the symbol will be set from the section of the
-expression; for more information, see *Note Expression Section::.
-
- Here is an example showing the three different places that symbol
-assignments may be used:
-
- floating_point = 0;
- SECTIONS
- {
- .text :
- {
- *(.text)
- _etext = .;
- }
- _bdata = (. + 3) & ~ 3;
- .data : { *(.data) }
- }
- In this example, the symbol `floating_point' will be defined as
-zero. The symbol `_etext' will be defined as the address following the
-last `.text' input section. The symbol `_bdata' will be defined as the
-address following the `.text' output section aligned upward to a 4 byte
-boundary.
-
-\1f
-File: ld.info, Node: PROVIDE, Next: PROVIDE_HIDDEN, Prev: Simple Assignments, Up: Assignments
-
-3.5.2 PROVIDE
--------------
-
-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 `etext'.
-However, ANSI C requires that the user be able to use `etext' as a
-function name without encountering an error. The `PROVIDE' keyword may
-be used to define a symbol, such as `etext', only if it is referenced
-but not defined. The syntax is `PROVIDE(SYMBOL = EXPRESSION)'.
-
- Here is an example of using `PROVIDE' to define `etext':
- SECTIONS
- {
- .text :
- {
- *(.text)
- _etext = .;
- PROVIDE(etext = .);
- }
- }
-
- In this example, if the program defines `_etext' (with a leading
-underscore), the linker will give a multiple definition error. If, on
-the other hand, the program defines `etext' (with no leading
-underscore), the linker will silently use the definition in the program.
-If the program references `etext' but does not define it, the linker
-will use the definition in the linker script.
-
-\1f
-File: ld.info, Node: PROVIDE_HIDDEN, Next: Source Code Reference, Prev: PROVIDE, Up: Assignments
-
-3.5.3 PROVIDE_HIDDEN
---------------------
-
-Similar to `PROVIDE'. For ELF targeted ports, the symbol will be
-hidden and won't be exported.
-
-\1f
-File: ld.info, Node: Source Code Reference, Prev: PROVIDE_HIDDEN, Up: Assignments
-
-3.5.4 Source Code Reference
----------------------------
-
-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.
-
- 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 `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:
-
- extern int foo;
-
- But in the linker script it might be defined as:
-
- _foo = 1000;
-
- In the remaining examples however it is assumed that no name
-transformation has taken place.
-
- 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 _value_ of the symbol. The second is
-that the compiler creates an entry in the program's symbol table which
-holds the symbol's _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:
-
- int foo = 1000;
-
- creates a entry called `foo' in the symbol table. This entry holds
-the address of an `int' sized block of memory where the number 1000 is
-initially stored.
-
- 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:
-
- foo = 1;
-
- looks up the symbol `foo' in the symbol table, gets the address
-associated with this symbol and then writes the value 1 into that
-address. Whereas:
-
- int * a = & foo;
-
- looks up the symbol `foo' in the symbol table, gets it address and
-then copies this address into the block of memory associated with the
-variable `a'.
-
- 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:
-
- foo = 1000;
-
- creates an entry in the symbol table called `foo' which holds the
-address of memory location 1000, but nothing special is stored at
-address 1000. This means that you cannot access the _value_ of a
-linker script defined symbol - it has no value - all you can do is
-access the _address_ of a linker script defined symbol.
-
- 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:
-
- start_of_ROM = .ROM;
- end_of_ROM = .ROM + sizeof (.ROM) - 1;
- start_of_FLASH = .FLASH;
-
- Then the C source code to perform the copy would be:
-
- extern char start_of_ROM, end_of_ROM, start_of_FLASH;
-
- memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
-
- Note the use of the `&' operators. These are correct.
-
-\1f
-File: ld.info, Node: SECTIONS, Next: MEMORY, Prev: Assignments, Up: Scripts
-
-3.6 SECTIONS Command
-====================
-
-The `SECTIONS' command tells the linker how to map input sections into
-output sections, and how to place the output sections in memory.
-
- The format of the `SECTIONS' command is:
- SECTIONS
- {
- SECTIONS-COMMAND
- SECTIONS-COMMAND
- ...
- }
-
- Each SECTIONS-COMMAND may of be one of the following:
-
- * an `ENTRY' command (*note Entry command: Entry Point.)
-
- * a symbol assignment (*note Assignments::)
-
- * an output section description
-
- * an overlay description
-
- The `ENTRY' command and symbol assignments are permitted inside the
-`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.
-
- Output section descriptions and overlay descriptions are described
-below.
-
- If you do not use a `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.
-
-* Menu:
-
-* Output Section Description:: Output section description
-* Output Section Name:: Output section name
-* Output Section Address:: Output section address
-* Input Section:: Input section description
-* Output Section Data:: Output section data
-* Output Section Keywords:: Output section keywords
-* Output Section Discarding:: Output section discarding
-* Output Section Attributes:: Output section attributes
-* Overlay Description:: Overlay description
-
-\1f
-File: ld.info, Node: Output Section Description, Next: Output Section Name, Up: SECTIONS
-
-3.6.1 Output Section Description
---------------------------------
-
-The full description of an output section looks like this:
- SECTION [ADDRESS] [(TYPE)] :
- [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)]
- {
- OUTPUT-SECTION-COMMAND
- OUTPUT-SECTION-COMMAND
- ...
- } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
-
- Most output sections do not use most of the optional section
-attributes.
-
- The whitespace around 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.
-
- Each OUTPUT-SECTION-COMMAND may be one of the following:
-
- * a symbol assignment (*note Assignments::)
-
- * an input section description (*note Input Section::)
-
- * data values to include directly (*note Output Section Data::)
-
- * a special output section keyword (*note Output Section Keywords::)
-
-\1f
-File: ld.info, Node: Output Section Name, Next: Output Section Address, Prev: Output Section Description, Up: SECTIONS
-
-3.6.2 Output Section Name
--------------------------
-
-The name of the output section is SECTION. SECTION must meet the
-constraints of your output format. In formats which only support a
-limited number of sections, such as `a.out', the name must be one of
-the names supported by the format (`a.out', for example, allows only
-`.text', `.data' or `.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.
-
- The output section name `/DISCARD/' is special; *Note Output Section
-Discarding::.
-
-\1f
-File: ld.info, Node: Output Section Address, Next: Input Section, Prev: Output Section Name, Up: SECTIONS
-
-3.6.3 Output Section Address
-----------------------------
-
-The ADDRESS is an expression for the VMA (the virtual memory address)
-of the output section. If you do not provide ADDRESS, the linker will
-set it based on REGION if present, or otherwise based on the current
-value of the location counter.
-
- If you provide ADDRESS, the address of the output section will be
-set to precisely that. If you provide neither ADDRESS nor 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.
-
- For example,
- .text . : { *(.text) }
- and
- .text : { *(.text) }
- are subtly different. The first will set the address of the `.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 `.text' input section.
-
- The ADDRESS may be an arbitrary expression; *Note 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:
- .text ALIGN(0x10) : { *(.text) }
- This works because `ALIGN' returns the current location counter
-aligned upward to the specified value.
-
- Specifying ADDRESS for a section will change the value of the
-location counter.
-
-\1f
-File: ld.info, Node: Input Section, Next: Output Section Data, Prev: Output Section Address, Up: SECTIONS
-
-3.6.4 Input Section Description
--------------------------------
-
-The most common output section command is an input section description.
-
- 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.
-
-* Menu:
-
-* Input Section Basics:: Input section basics
-* Input Section Wildcards:: Input section wildcard patterns
-* Input Section Common:: Input section for common symbols
-* Input Section Keep:: Input section and garbage collection
-* Input Section Example:: Input section example
-
-\1f
-File: ld.info, Node: Input Section Basics, Next: Input Section Wildcards, Up: Input Section
-
-3.6.4.1 Input Section Basics
-............................
-
-An input section description consists of a file name optionally followed
-by a list of section names in parentheses.
-
- The file name and the section name may be wildcard patterns, which we
-describe further below (*note Input Section Wildcards::).
-
- 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 `.text' sections, you would write:
- *(.text)
- Here the `*' 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:
- *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
- will cause all .ctors sections from all files except `crtend.o' and
-`otherfile.o' to be included.
-
- There are two ways to include more than one section:
- *(.text .rdata)
- *(.text) *(.rdata)
- The difference between these is the order in which the `.text' and
-`.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 `.text'
-input sections will appear first, followed by all `.rdata' input
-sections.
-
- 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:
- data.o(.data)
-
- 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:
- data.o
-
- 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 `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
-`INPUT' command, because the linker will not search for the file in the
-archive search path.
-
-\1f
-File: ld.info, Node: Input Section Wildcards, Next: Input Section Common, Prev: Input Section Basics, Up: Input Section
-
-3.6.4.2 Input Section Wildcard Patterns
-.......................................
-
-In an input section description, either the file name or the section
-name or both may be wildcard patterns.
-
- The file name of `*' seen in many examples is a simple wildcard
-pattern for the file name.
-
- The wildcard patterns are like those used by the Unix shell.
-
-`*'
- matches any number of characters
-
-`?'
- matches any single character
-
-`[CHARS]'
- matches a single instance of any of the CHARS; the `-' character
- may be used to specify a range of characters, as in `[a-z]' to
- match any lower case letter
-
-`\'
- quotes the following character
-
- When a file name is matched with a wildcard, the wildcard characters
-will not match a `/' character (used to separate directory names on
-Unix). A pattern consisting of a single `*' character is an exception;
-it will always match any file name, whether it contains a `/' or not.
-In a section name, the wildcard characters will match a `/' character.
-
- File name wildcard patterns only match files which are explicitly
-specified on the command line or in an `INPUT' command. The linker
-does not search directories to expand wildcards.
-
- 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
-`data.o' rule will not be used:
- .data : { *(.data) }
- .data1 : { data.o(.data) }
-
- 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 `SORT_BY_NAME' keyword, which appears before a
-wildcard pattern in parentheses (e.g., `SORT_BY_NAME(.text*)'). When
-the `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.
-
- `SORT_BY_ALIGNMENT' is very similar to `SORT_BY_NAME'. The
-difference is `SORT_BY_ALIGNMENT' will sort sections into ascending
-order by alignment before placing them in the output file.
-
- `SORT' is an alias for `SORT_BY_NAME'.
-
- When there are nested section sorting commands in linker script,
-there can be at most 1 level of nesting for section sorting commands.
-
- 1. `SORT_BY_NAME' (`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.
-
- 2. `SORT_BY_ALIGNMENT' (`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.
-
- 3. `SORT_BY_NAME' (`SORT_BY_NAME' (wildcard section pattern)) is
- treated the same as `SORT_BY_NAME' (wildcard section pattern).
-
- 4. `SORT_BY_ALIGNMENT' (`SORT_BY_ALIGNMENT' (wildcard section
- pattern)) is treated the same as `SORT_BY_ALIGNMENT' (wildcard
- section pattern).
-
- 5. All other nested section sorting commands are invalid.
-
- 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.
-
- 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.
-
- 1. `SORT_BY_NAME' (wildcard section pattern ) with `--sort-sections
- alignment' is equivalent to `SORT_BY_NAME' (`SORT_BY_ALIGNMENT'
- (wildcard section pattern)).
-
- 2. `SORT_BY_ALIGNMENT' (wildcard section pattern) with
- `--sort-section name' is equivalent to `SORT_BY_ALIGNMENT'
- (`SORT_BY_NAME' (wildcard section pattern)).
-
- If the section sorting command in linker script is nested, the
-command line option will be ignored.
-
- If you ever get confused about where input sections are going, use
-the `-M' linker option to generate a map file. The map file shows
-precisely how input sections are mapped to output sections.
-
- This example shows how wildcard patterns might be used to partition
-files. This linker script directs the linker to place all `.text'
-sections in `.text' and all `.bss' sections in `.bss'. The linker will
-place the `.data' section from all files beginning with an upper case
-character in `.DATA'; for all other files, the linker will place the
-`.data' section in `.data'.
- SECTIONS {
- .text : { *(.text) }
- .DATA : { [A-Z]*(.data) }
- .data : { *(.data) }
- .bss : { *(.bss) }
- }
-
-\1f
-File: ld.info, Node: Input Section Common, Next: Input Section Keep, Prev: Input Section Wildcards, Up: Input Section
-
-3.6.4.3 Input Section for Common Symbols
-........................................
-
-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 `COMMON'.
-
- You may use file names with the `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.
-
- In most cases, common symbols in input files will be placed in the
-`.bss' section in the output file. For example:
- .bss { *(.bss) *(COMMON) }
-
- 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 `COMMON' for standard common
-symbols and `.scommon' for small common symbols. This permits you to
-map the different types of common symbols into memory at different
-locations.
-
- You will sometimes see `[COMMON]' in old linker scripts. This
-notation is now considered obsolete. It is equivalent to `*(COMMON)'.
-
-\1f
-File: ld.info, Node: Input Section Keep, Next: Input Section Example, Prev: Input Section Common, Up: Input Section
-
-3.6.4.4 Input Section and Garbage Collection
-............................................
-
-When link-time garbage collection is in use (`--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
-`KEEP()', as in `KEEP(*(.init))' or `KEEP(SORT_BY_NAME(*)(.ctors))'.
-
-\1f
-File: ld.info, Node: Input Section Example, Prev: Input Section Keep, Up: Input Section
-
-3.6.4.5 Input Section Example
-.............................
-
-The following example is a complete linker script. It tells the linker
-to read all of the sections from file `all.o' and place them at the
-start of output section `outputa' which starts at location `0x10000'.
-All of section `.input1' from file `foo.o' follows immediately, in the
-same output section. All of section `.input2' from `foo.o' goes into
-output section `outputb', followed by section `.input1' from `foo1.o'.
-All of the remaining `.input1' and `.input2' sections from any files
-are written to output section `outputc'.
-
- SECTIONS {
- outputa 0x10000 :
- {
- all.o
- foo.o (.input1)
- }
- outputb :
- {
- foo.o (.input2)
- foo1.o (.input1)
- }
- outputc :
- {
- *(.input1)
- *(.input2)
- }
- }
-
-\1f
-File: ld.info, Node: Output Section Data, Next: Output Section Keywords, Prev: Input Section, Up: SECTIONS
-
-3.6.5 Output Section Data
--------------------------
-
-You can include explicit bytes of data in an output section by using
-`BYTE', `SHORT', `LONG', `QUAD', or `SQUAD' as an output section
-command. Each keyword is followed by an expression in parentheses
-providing the value to store (*note Expressions::). The value of the
-expression is stored at the current value of the location counter.
-
- The `BYTE', `SHORT', `LONG', and `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.
-
- For example, this will store the byte 1 followed by the four byte
-value of the symbol `addr':
- BYTE(1)
- LONG(addr)
-
- When using a 64 bit host or target, `QUAD' and `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 `QUAD'
-stores a 32 bit value zero extended to 64 bits, and `SQUAD' stores a 32
-bit value sign extended to 64 bits.
-
- 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.
-
- Note--these commands only work inside a section description and not
-between them, so the following will produce an error from the linker:
- SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } }
- whereas this will work:
- SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } }
-
- You may use the `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 `FILL'
-statement covers memory locations after the point at which it occurs in
-the section definition; by including more than one `FILL' statement,
-you can have different fill patterns in different parts of an output
-section.
-
- This example shows how to fill unspecified regions of memory with the
-value `0x90':
- FILL(0x90909090)
-
- The `FILL' command is similar to the `=FILLEXP' output section
-attribute, but it only affects the part of the section following the
-`FILL' command, rather than the entire section. If both are used, the
-`FILL' command takes precedence. *Note Output Section Fill::, for
-details on the fill expression.
-
-\1f
-File: ld.info, Node: Output Section Keywords, Next: Output Section Discarding, Prev: Output Section Data, Up: SECTIONS
-
-3.6.6 Output Section Keywords
------------------------------
-
-There are a couple of keywords which can appear as output section
-commands.
-
-`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 `CREATE_OBJECT_SYMBOLS' command
- appears.
-
- This is conventional for the a.out object file format. It is not
- normally used for any other object file format.
-
-`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 `CONSTRUCTORS' command
- tells the linker to place constructor information in the output
- section where the `CONSTRUCTORS' command appears. The
- `CONSTRUCTORS' command is ignored for other object file formats.
-
- The symbol `__CTOR_LIST__' marks the start of the global
- constructors, and the symbol `__CTOR_END__' marks the end.
- Similarly, `__DTOR_LIST__' and `__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 `__main'; a call to
- `__main' is automatically inserted into the startup code for
- `main'. GNU C++ normally runs destructors either by using
- `atexit', or directly from the function `exit'.
-
- For object file formats such as `COFF' or `ELF' which support
- arbitrary section names, GNU C++ will normally arrange to put the
- addresses of global constructors and destructors into the `.ctors'
- and `.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.
-
- __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__ = .;
-
- 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 `CONSTRUCTORS' command, use `SORT_BY_NAME(CONSTRUCTORS)'
- instead. When using the `.ctors' and `.dtors' sections, use
- `*(SORT_BY_NAME(.ctors))' and `*(SORT_BY_NAME(.dtors))' instead of
- just `*(.ctors)' and `*(.dtors)'.
-
- 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.
-
-
-\1f
-File: ld.info, Node: Output Section Discarding, Next: Output Section Attributes, Prev: Output Section Keywords, Up: SECTIONS
-
-3.6.7 Output Section Discarding
--------------------------------
-
-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:
- .foo : { *(.foo) }
- will only create a `.foo' section in the output file if there is a
-`.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.
-
- The linker will ignore address assignments (*note 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.
-
- The special output section name `/DISCARD/' may be used to discard
-input sections. Any input sections which are assigned to an output
-section named `/DISCARD/' are not included in the output file.
-
-\1f
-File: ld.info, Node: Output Section Attributes, Next: Overlay Description, Prev: Output Section Discarding, Up: SECTIONS
-
-3.6.8 Output Section Attributes
--------------------------------
-
-We showed above that the full description of an output section looked
-like this:
- SECTION [ADDRESS] [(TYPE)] :
- [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)]
- {
- OUTPUT-SECTION-COMMAND
- OUTPUT-SECTION-COMMAND
- ...
- } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
-We've already described SECTION, ADDRESS, and
-OUTPUT-SECTION-COMMAND. In this section we will describe the remaining
-section attributes.
-
-* Menu:
-
-* Output Section Type:: Output section type
-* Output Section LMA:: Output section LMA
-* Forced Output Alignment:: Forced Output Alignment
-* Forced Input Alignment:: Forced Input Alignment
-* Output Section Region:: Output section region
-* Output Section Phdr:: Output section phdr
-* Output Section Fill:: Output section fill
-
-\1f
-File: ld.info, Node: Output Section Type, Next: Output Section LMA, Up: Output Section Attributes
-
-3.6.8.1 Output Section Type
-...........................
-
-Each output section may have a type. The type is a keyword in
-parentheses. The following types are defined:
-
-`NOLOAD'
- The section should be marked as not loadable, so that it will not
- be loaded into memory when the program is run.
-
-`DSECT'
-`COPY'
-`INFO'
-`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.
-
- 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 `ROM'
-section is addressed at memory location `0' and does not need to be
-loaded when the program is run. The contents of the `ROM' section will
-appear in the linker output file as usual.
- SECTIONS {
- ROM 0 (NOLOAD) : { ... }
- ...
- }
-
-\1f
-File: ld.info, Node: Output Section LMA, Next: Forced Output Alignment, Prev: Output Section Type, Up: Output Section Attributes
-
-3.6.8.2 Output Section LMA
-..........................
-
-Every section has a virtual address (VMA) and a load address (LMA); see
-*Note Basic Script Concepts::. The address expression which may appear
-in an output section description sets the VMA (*note Output Section
-Address::).
-
- The expression LMA that follows the `AT' keyword specifies the load
-address of the section.
-
- Alternatively, with `AT>LMA_REGION' expression, you may specify a
-memory region for the section's load address. *Note MEMORY::. Note
-that if the section has not had a VMA assigned to it then the linker
-will use the LMA_REGION as the VMA region as well.
-
- If neither `AT' nor `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. *Note
-Output Section Region::.
-
- 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 `.text', which starts at `0x1000', one called `.mdata', which is
-loaded at the end of the `.text' section even though its VMA is
-`0x2000', and one called `.bss' to hold uninitialized data at address
-`0x3000'. The symbol `_data' is defined with the value `0x2000', which
-shows that the location counter holds the VMA value, not the LMA value.
-
- SECTIONS
- {
- .text 0x1000 : { *(.text) _etext = . ; }
- .mdata 0x2000 :
- AT ( ADDR (.text) + SIZEOF (.text) )
- { _data = . ; *(.data); _edata = . ; }
- .bss 0x3000 :
- { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;}
- }
-
- 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.
-
- 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;
-
-\1f
-File: ld.info, Node: Forced Output Alignment, Next: Forced Input Alignment, Prev: Output Section LMA, Up: Output Section Attributes
-
-3.6.8.3 Forced Output Alignment
-...............................
-
-You can increase an output section's alignment by using ALIGN.
-
-\1f
-File: ld.info, Node: Forced Input Alignment, Next: Output Section Region, Prev: Forced Output Alignment, Up: Output Section Attributes
-
-3.6.8.4 Forced Input Alignment
-..............................
-
-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.
-
-\1f
-File: ld.info, Node: Output Section Region, Next: Output Section Phdr, Prev: Forced Input Alignment, Up: Output Section Attributes
-
-3.6.8.5 Output Section Region
-.............................
-
-You can assign a section to a previously defined region of memory by
-using `>REGION'. *Note MEMORY::.
-
- Here is a simple example:
- MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
- SECTIONS { ROM : { *(.text) } >rom }
-
-\1f
-File: ld.info, Node: Output Section Phdr, Next: Output Section Fill, Prev: Output Section Region, Up: Output Section Attributes
-
-3.6.8.6 Output Section Phdr
-...........................
-
-You can assign a section to a previously defined program segment by
-using `:PHDR'. *Note 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 `:PHDR' modifier.
-You can use `:NONE' to tell the linker to not put the section in any
-segment at all.
-
- Here is a simple example:
- PHDRS { text PT_LOAD ; }
- SECTIONS { .text : { *(.text) } :text }
-
-\1f
-File: ld.info, Node: Output Section Fill, Prev: Output Section Phdr, Up: Output Section Attributes
-
-3.6.8.7 Output Section Fill
-...........................
-
-You can set the fill pattern for an entire section by using `=FILLEXP'.
-FILLEXP is an expression (*note 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 `0x'
-and without a trailing `k' or `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 `+', the fill pattern is the four least
-significant bytes of the value of the expression. In all cases, the
-number is big-endian.
-
- You can also change the fill value with a `FILL' command in the
-output section commands; (*note Output Section Data::).
-
- Here is a simple example:
- SECTIONS { .text : { *(.text) } =0x90909090 }
-
-\1f
-File: ld.info, Node: Overlay Description, Prev: Output Section Attributes, Up: SECTIONS
-
-3.6.9 Overlay Description
--------------------------
-
-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.
-
- Overlays are described using the `OVERLAY' command. The `OVERLAY'
-command is used within a `SECTIONS' command, like an output section
-description. The full syntax of the `OVERLAY' command is as follows:
- 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]
-
- Everything is optional except `OVERLAY' (a keyword), and each
-section must have a name (SECNAME1 and SECNAME2 above). The section
-definitions within the `OVERLAY' construct are identical to those
-within the general `SECTIONS' contruct (*note SECTIONS::), except that
-no addresses and no memory regions may be defined for sections within
-an `OVERLAY'.
-
- 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
-`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).
-
- If the `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. *Note NOCROSSREFS: Miscellaneous
-Commands.
-
- For each section within the `OVERLAY', the linker automatically
-provides two symbols. The symbol `__load_start_SECNAME' is defined as
-the starting load address of the section. The symbol
-`__load_stop_SECNAME' is defined as the final load address of the
-section. Any characters within 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.
-
- 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.
-
- Here is an example. Remember that this would appear inside a
-`SECTIONS' construct.
- OVERLAY 0x1000 : AT (0x4000)
- {
- .text0 { o1/*.o(.text) }
- .text1 { o2/*.o(.text) }
- }
-This will define both `.text0' and `.text1' to start at address
-0x1000. `.text0' will be loaded at address 0x4000, and `.text1' will
-be loaded immediately after `.text0'. The following symbols will be
-defined if referenced: `__load_start_text0', `__load_stop_text0',
-`__load_start_text1', `__load_stop_text1'.
-
- C code to copy overlay `.text1' into the overlay area might look
-like the following.
-
- extern char __load_start_text1, __load_stop_text1;
- memcpy ((char *) 0x1000, &__load_start_text1,
- &__load_stop_text1 - &__load_start_text1);
-
- Note that the `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.
-
- .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));
-
-\1f
-File: ld.info, Node: MEMORY, Next: PHDRS, Prev: SECTIONS, Up: Scripts
-
-3.7 MEMORY Command
-==================
-
-The linker's default configuration permits allocation of all available
-memory. You can override this by using the `MEMORY' command.
-
- The `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.
-
- A linker script may contain at most one use of the `MEMORY' command.
-However, you can define as many blocks of memory within it as you
-wish. The syntax is:
- MEMORY
- {
- NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
- ...
- }
-
- The 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.
-
- The 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 *Note
-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.
-
- The ATTR string must consist only of the following characters:
-`R'
- Read-only section
-
-`W'
- Read/write section
-
-`X'
- Executable section
-
-`A'
- Allocatable section
-
-`I'
- Initialized section
-
-`L'
- Same as `I'
-
-`!'
- Invert the sense of any of the preceding attributes
-
- If a unmapped section matches any of the listed attributes other than
-`!', it will be placed in the memory region. The `!' 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.
-
- The 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 `ORIGIN' may be abbreviated to
-`org' or `o' (but not, for example, `ORG').
-
- The LEN is an expression for the size in bytes of the memory region.
-As with the ORIGIN expression, the expression must be numerical only
-and must evaluate to a constant. The keyword `LENGTH' may be
-abbreviated to `len' or `l'.
-
- In the following example, we specify that there are two memory
-regions available for allocation: one starting at `0' for 256 kilobytes,
-and the other starting at `0x40000000' for four megabytes. The linker
-will place into the `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 `ram' memory region.
-
- MEMORY
- {
- rom (rx) : ORIGIN = 0, LENGTH = 256K
- ram (!rx) : org = 0x40000000, l = 4M
- }
-
- Once you define a memory region, you can direct the linker to place
-specific output sections into that memory region by using the `>REGION'
-output section attribute. For example, if you have a memory region
-named `mem', you would use `>mem' in the output section definition.
-*Note 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.
-
- It is possible to access the origin and length of a memory in an
-expression via the `ORIGIN(MEMORY)' and `LENGTH(MEMORY)' functions:
-
- _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
-
-\1f
-File: ld.info, Node: PHDRS, Next: VERSION, Prev: MEMORY, Up: Scripts
-
-3.8 PHDRS Command
-=================
-
-The ELF object file format uses "program headers", also knows as
-"segments". The program headers describe how the program should be
-loaded into memory. You can print them out by using the `objdump'
-program with the `-p' option.
-
- 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.
-
- 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 `PHDRS' command for this purpose. When the
-linker sees the `PHDRS' command in the linker script, it will not
-create any program headers other than the ones specified.
-
- The linker only pays attention to the `PHDRS' command when
-generating an ELF output file. In other cases, the linker will simply
-ignore `PHDRS'.
-
- This is the syntax of the `PHDRS' command. The words `PHDRS',
-`FILEHDR', `AT', and `FLAGS' are keywords.
-
- PHDRS
- {
- NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ]
- [ FLAGS ( FLAGS ) ] ;
- }
-
- The NAME is used only for reference in the `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.
-
- 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 `:PHDR' output section attribute
-to place a section in a particular segment. *Note Output Section
-Phdr::.
-
- 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 `:PHDR', using it once for each segment which should contain the
-section.
-
- If you place a section in one or more segments using `:PHDR', then
-the linker will place all subsequent allocatable sections which do not
-specify `: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 `:NONE' to override the default segment and tell
-the linker to not put the section in any segment at all.
-
- You may use the `FILEHDR' and `PHDRS' keywords appear after the
-program header type to further describe the contents of the segment.
-The `FILEHDR' keyword means that the segment should include the ELF
-file header. The `PHDRS' keyword means that the segment should include
-the ELF program headers themselves.
-
- The TYPE may be one of the following. The numbers indicate the
-value of the keyword.
-
-`PT_NULL' (0)
- Indicates an unused program header.
-
-`PT_LOAD' (1)
- Indicates that this program header describes a segment to be
- loaded from the file.
-
-`PT_DYNAMIC' (2)
- Indicates a segment where dynamic linking information can be found.
-
-`PT_INTERP' (3)
- Indicates a segment where the name of the program interpreter may
- be found.
-
-`PT_NOTE' (4)
- Indicates a segment holding note information.
-
-`PT_SHLIB' (5)
- A reserved program header type, defined but not specified by the
- ELF ABI.
-
-`PT_PHDR' (6)
- Indicates a segment where the program headers may be found.
-
-EXPRESSION
- An expression giving the numeric type of the program header. This
- may be used for types not defined above.
-
- You can specify that a segment should be loaded at a particular
-address in memory by using an `AT' expression. This is identical to the
-`AT' command used as an output section attribute (*note Output Section
-LMA::). The `AT' command for a program header overrides the output
-section attribute.
-
- The linker will normally set the segment flags based on the sections
-which comprise the segment. You may use the `FLAGS' keyword to
-explicitly specify the segment flags. The value of FLAGS must be an
-integer. It is used to set the `p_flags' field of the program header.
-
- Here is an example of `PHDRS'. This shows a typical set of program
-headers used on a native ELF system.
-
- 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
- ...
- }
-
-\1f
-File: ld.info, Node: VERSION, Next: Expressions, Prev: PHDRS, Up: Scripts
-
-3.9 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.
-
- 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 `--version-script' linker option.
-
- The syntax of the `VERSION' command is simply
- VERSION { version-script-commands }
-
- 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.
-
- The easiest way to demonstrate the version script language is with a
-few examples.
-
- 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;
-
- This example version script defines three version nodes. The first
-version node defined is `VERS_1.1'; it has no other dependencies. The
-script binds the symbol `foo1' to `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 `old', `original', or `new' is matched.
-The wildcard patterns available are the same as those used in the shell
-when matching filenames (also known as "globbing"). However, if you
-specify the symbol name inside double quotes, then the name is treated
-as literal, rather than as a glob pattern.
-
- Next, the version script defines node `VERS_1.2'. This node depends
-upon `VERS_1.1'. The script binds the symbol `foo2' to the version
-node `VERS_1.2'.
-
- Finally, the version script defines node `VERS_2.0'. This node
-depends upon `VERS_1.2'. The scripts binds the symbols `bar1' and
-`bar2' are bound to the version node `VERS_2.0'.
-
- 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 `global: *;'
-somewhere in the version script.
-
- The names of the version nodes have no specific meaning other than
-what they might suggest to the person reading them. The `2.0' version
-could just as well have appeared in between `1.1' and `1.2'. However,
-this would be a confusing way to write a version script.
-
- 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.
-
- { global: foo; bar; local: *; };
-
- 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.
-
- 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.
-
- 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:
- __asm__(".symver original_foo,foo@VERS_1.1");
- in the C source file. This renames the function `original_foo' to
-be an alias for `foo' bound to the version node `VERS_1.1'. The
-`local:' directive can be used to prevent the symbol `original_foo'
-from being exported. A `.symver' directive takes precedence over a
-version script.
-
- 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.
-
- To do this, you must use multiple `.symver' directives in the source
-file. Here is an example:
-
- __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");
-
- In this example, `foo@' represents the symbol `foo' bound to the
-unspecified base version of the symbol. The source file that contains
-this example would define 4 C functions: `original_foo', `old_foo',
-`old_foo1', and `new_foo'.
-
- 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 `foo@@VERS_2.0'
-type of `.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.
-
- 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., `old_foo'), or you can use the `.symver' directive to
-specifically bind to an external version of the function in question.
-
- You can also specify the language in the version script:
-
- VERSION extern "lang" { version-script-commands }
-
- The supported `lang's are `C', `C++', and `Java'. The linker will
-iterate over the list of symbols at the link time and demangle them
-according to `lang' before matching them to the patterns specified in
-`version-script-commands'.
-
- 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.
-
-\1f
-File: ld.info, Node: Expressions, Next: Implicit Linker Scripts, Prev: VERSION, Up: Scripts
-
-3.10 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.
-
- You can use and set symbol values in expressions.
-
- The linker defines several special purpose builtin functions for use
-in expressions.
-
-* Menu:
-
-* Constants:: Constants
-* Symbols:: Symbol Names
-* Orphan Sections:: Orphan Sections
-* Location Counter:: The Location Counter
-* Operators:: Operators
-* Evaluation:: Evaluation
-* Expression Section:: The Section of an Expression
-* Builtin Functions:: Builtin Functions
-
-\1f
-File: ld.info, Node: Constants, Next: Symbols, Up: Expressions
-
-3.10.1 Constants
-----------------
-
-All constants are integers.
-
- As in C, the linker considers an integer beginning with `0' to be
-octal, and an integer beginning with `0x' or `0X' to be hexadecimal.
-The linker considers other integers to be decimal.
-
- In addition, you can use the suffixes `K' and `M' to scale a
-constant by `1024' or `1024*1024' respectively. For example, the
-following all refer to the same quantity:
- _fourk_1 = 4K;
- _fourk_2 = 4096;
- _fourk_3 = 0x1000;
-
-\1f
-File: ld.info, Node: Symbols, Next: Orphan Sections, Prev: Constants, Up: Expressions
-
-3.10.2 Symbol Names
--------------------
-
-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:
- "SECTION" = 9;
- "with a space" = "also with a space" + 10;
-
- Since symbols can contain many non-alphabetic characters, it is
-safest to delimit symbols with spaces. For example, `A-B' is one
-symbol, whereas `A - B' is an expression involving subtraction.
-
-\1f
-File: ld.info, Node: Orphan Sections, Next: Location Counter, Prev: Symbols, Up: Expressions
-
-3.10.3 Orphan Sections
-----------------------
-
-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.
-
- For ELF targets, the attribute of the section includes section type
-as well as section flag.
-
-\1f
-File: ld.info, Node: Location Counter, Next: Operators, Prev: Orphan Sections, Up: Expressions
-
-3.10.4 The Location Counter
----------------------------
-
-The special linker variable "dot" `.' always contains the current
-output location counter. Since the `.' always refers to a location in
-an output section, it may only appear in an expression within a
-`SECTIONS' command. The `.' symbol may appear anywhere that an
-ordinary symbol is allowed in an expression.
-
- Assigning a value to `.' 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.
-
- SECTIONS
- {
- output :
- {
- file1(.text)
- . = . + 1000;
- file2(.text)
- . += 1000;
- file3(.text)
- } = 0x12345678;
- }
- In the previous example, the `.text' section from `file1' is located
-at the beginning of the output section `output'. It is followed by a
-1000 byte gap. Then the `.text' section from `file2' appears, also
-with a 1000 byte gap following before the `.text' section from `file3'.
-The notation `= 0x12345678' specifies what data to write in the gaps
-(*note Output Section Fill::).
-
- Note: `.' actually refers to the byte offset from the start of the
-current containing object. Normally this is the `SECTIONS' statement,
-whose start address is 0, hence `.' can be used as an absolute address.
-If `.' 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:
-
- SECTIONS
- {
- . = 0x100
- .text: {
- *(.text)
- . = 0x200
- }
- . = 0x500
- .data: {
- *(.data)
- . += 0x600
- }
- }
-
- The `.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
-`.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 `.'
-backwards). The `.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 `.data' input sections and before the end of the `.data' output
-section itself.
-
- 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:
-
- SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
-
- start_of_data = . ;
- .data: { *(.data) }
- end_of_data = . ;
- }
-
- If the linker needs to place some input section, e.g. `.rodata', not
-mentioned in the script, it might choose to place that section between
-`.text' and `.data'. You might think the linker should place `.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 `.'.
-I.e., the linker will place the orphan `.rodata' section as if the
-script was written as follows:
-
- SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
-
- start_of_data = . ;
- .rodata: { *(.rodata) }
- .data: { *(.data) }
- end_of_data = . ;
- }
-
- This may or may not be the script author's intention for the value of
-`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 `.' is setting the start address of a following output
-section and thus should be grouped with that section. So you could
-write:
-
- SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
-
- . = . ;
- start_of_data = . ;
- .data: { *(.data) }
- end_of_data = . ;
- }
-
- Now, the orphan `.rodata' section will be placed between
-`end_of_text' and `start_of_data'.
-
-\1f
-File: ld.info, Node: Operators, Next: Evaluation, Prev: Location Counter, Up: Expressions
-
-3.10.5 Operators
-----------------
-
-The linker recognizes the standard C set of arithmetic operators, with
-the standard bindings and precedence levels:
- 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)
- Notes: (1) Prefix operators (2) *Note Assignments::.
-
-\1f
-File: ld.info, Node: Evaluation, Next: Expression Section, Prev: Operators, Up: Expressions
-
-3.10.6 Evaluation
------------------
-
-The linker evaluates expressions lazily. It only computes the value of
-an expression when absolutely necessary.
-
- 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.
-
- 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.
-
- The sizes of sections cannot be known until after allocation, so
-assignments dependent upon these are not performed until after
-allocation.
-
- Some expressions, such as those depending upon the location counter
-`.', must be evaluated during section allocation.
-
- 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
- SECTIONS
- {
- .text 9+this_isnt_constant :
- { *(.text) }
- }
-will cause the error message `non constant expression for initial
-address'.
-
-\1f
-File: ld.info, Node: Expression Section, Next: Builtin Functions, Prev: Evaluation, Up: Expressions
-
-3.10.7 The Section of an Expression
------------------------------------
-
-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.
-
- 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.
-
- A symbol set to a relative expression will be relocatable if you
-request relocatable output using the `-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.
-
- 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.
-
- You can use the builtin function `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 `.data':
- SECTIONS
- {
- .data : { *(.data) _edata = ABSOLUTE(.); }
- }
- If `ABSOLUTE' were not used, `_edata' would be relative to the
-`.data' section.
-
-\1f
-File: ld.info, Node: Builtin Functions, Prev: Expression Section, Up: Expressions
-
-3.10.8 Builtin Functions
-------------------------
-
-The linker script language includes a number of builtin functions for
-use in linker script expressions.
-
-`ABSOLUTE(EXP)'
- Return the absolute (non-relocatable, as opposed to non-negative)
- value of the expression EXP. Primarily useful to assign an
- absolute value to a symbol within a section definition, where
- symbol values are normally section relative. *Note Expression
- Section::.
-
-`ADDR(SECTION)'
- Return the absolute address (the VMA) of the named SECTION. Your
- script must previously have defined the location of that section.
- In the following example, `symbol_1' and `symbol_2' are assigned
- identical values:
- SECTIONS { ...
- .output1 :
- {
- start_of_output_1 = ABSOLUTE(.);
- ...
- }
- .output :
- {
- symbol_1 = ADDR(.output1);
- symbol_2 = start_of_output_1;
- }
- ... }
-
-`ALIGN(ALIGN)'
-`ALIGN(EXP,ALIGN)'
- Return the location counter (`.') or arbitrary expression aligned
- to the next ALIGN boundary. The single operand `ALIGN' doesn't
- change the value of the location counter--it just does arithmetic
- on it. The two operand `ALIGN' allows an arbitrary expression to
- be aligned upwards (`ALIGN(ALIGN)' is equivalent to `ALIGN(.,
- ALIGN)').
-
- Here is an example which aligns the output `.data' section to the
- next `0x2000' byte boundary after the preceding section and sets a
- variable within the section to the next `0x8000' boundary after the
- input sections:
- SECTIONS { ...
- .data ALIGN(0x2000): {
- *(.data)
- variable = ALIGN(0x8000);
- }
- ... }
- The first use of `ALIGN' in this example specifies the
- location of a section because it is used as the optional ADDRESS
- attribute of a section definition (*note Output Section
- Address::). The second use of `ALIGN' is used to defines the
- value of a symbol.
-
- The builtin function `NEXT' is closely related to `ALIGN'.
-
-`ALIGNOF(SECTION)'
- Return the alignment in bytes of the named 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 `.output' section is
- stored as the first value in that section.
- SECTIONS{ ...
- .output {
- LONG (ALIGNOF (.output))
- ...
- }
- ... }
-
-`BLOCK(EXP)'
- This is a synonym for `ALIGN', for compatibility with older linker
- scripts. It is most often seen when setting the address of an
- output section.
-
-`DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)'
- This is equivalent to either
- (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1)))
- or
- (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - COMMONPAGESIZE)))
- depending on whether the latter uses fewer COMMONPAGESIZE sized
- pages for the data segment (area between the result of this
- expression and `DATA_SEGMENT_END') than the former or not. If the
- latter form is used, it means COMMONPAGESIZE bytes of runtime
- memory will be saved at the expense of up to COMMONPAGESIZE wasted
- bytes in the on-disk file.
-
- This expression can only be used directly in `SECTIONS' commands,
- not in any output section descriptions and only once in the linker
- script. COMMONPAGESIZE should be less or equal to MAXPAGESIZE and
- should be the system page size the object wants to be optimized
- for (while still working on system page sizes up to MAXPAGESIZE).
-
- Example:
- . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
-
-`DATA_SEGMENT_END(EXP)'
- This defines the end of data segment for `DATA_SEGMENT_ALIGN'
- evaluation purposes.
-
- . = DATA_SEGMENT_END(.);
-
-`DATA_SEGMENT_RELRO_END(OFFSET, EXP)'
- This defines the end of the `PT_GNU_RELRO' segment when `-z relro'
- option is used. Second argument is returned. When `-z relro'
- option is not present, `DATA_SEGMENT_RELRO_END' does nothing,
- otherwise `DATA_SEGMENT_ALIGN' is padded so that EXP + 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 `DATA_SEGMENT_ALIGN' and `DATA_SEGMENT_END'.
-
- . = DATA_SEGMENT_RELRO_END(24, .);
-
-`DEFINED(SYMBOL)'
- Return 1 if 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 `begin' to the first location in the `.text'
- section--but if a symbol called `begin' already existed, its value
- is preserved:
-
- SECTIONS { ...
- .text : {
- begin = DEFINED(begin) ? begin : . ;
- ...
- }
- ...
- }
-
-`LENGTH(MEMORY)'
- Return the length of the memory region named MEMORY.
-
-`LOADADDR(SECTION)'
- Return the absolute LMA of the named SECTION. This is normally
- the same as `ADDR', but it may be different if the `AT' attribute
- is used in the output section definition (*note Output Section
- LMA::).
-
-`MAX(EXP1, EXP2)'
- Returns the maximum of EXP1 and EXP2.
-
-`MIN(EXP1, EXP2)'
- Returns the minimum of EXP1 and EXP2.
-
-`NEXT(EXP)'
- Return the next unallocated address that is a multiple of EXP.
- This function is closely related to `ALIGN(EXP)'; unless you use
- the `MEMORY' command to define discontinuous memory for the output
- file, the two functions are equivalent.
-
-`ORIGIN(MEMORY)'
- Return the origin of the memory region named MEMORY.
-
-`SEGMENT_START(SEGMENT, DEFAULT)'
- Return the base address of the named SEGMENT. If an explicit
- value has been given for this segment (with a command-line `-T'
- option) that value will be returned; otherwise the value will be
- DEFAULT. At present, the `-T' command-line option can only be
- used to set the base address for the "text", "data", and "bss"
- sections, but you use `SEGMENT_START' with any segment name.
-
-`SIZEOF(SECTION)'
- Return the size in bytes of the named 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, `symbol_1' and `symbol_2' are assigned identical values:
- SECTIONS{ ...
- .output {
- .start = . ;
- ...
- .end = . ;
- }
- symbol_1 = .end - .start ;
- symbol_2 = SIZEOF(.output);
- ... }
-
-`SIZEOF_HEADERS'
-`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.
-
- When producing an ELF output file, if the linker script uses the
- `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 `not enough
- room for program headers'. To avoid this error, you must avoid
- using the `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
- `PHDRS' command (*note PHDRS::).
-
-\1f
-File: ld.info, Node: Implicit Linker Scripts, Prev: Expressions, Up: Scripts
-
-3.11 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.
-
- An implicit linker script will not replace the default linker script.
-
- Typically an implicit linker script would contain only symbol
-assignments, or the `INPUT', `GROUP', or `VERSION' commands.
-
- 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.
-
-\1f
-File: ld.info, Node: Machine Dependent, Next: BFD, Prev: Scripts, Up: Top
-
-4 Machine Dependent Features
-****************************
-
-`ld' has additional features on some platforms; the following sections
-describe them. Machines where `ld' has no additional functionality are
-not listed.
-
-* Menu:
-
-
-* H8/300:: `ld' and the H8/300
-
-* i960:: `ld' and the Intel 960 family
-
-* ARM:: `ld' and the ARM family
-
-* HPPA ELF32:: `ld' and HPPA 32-bit ELF
-
-* MMIX:: `ld' and MMIX
-
-* MSP430:: `ld' and MSP430
-
-* M68HC11/68HC12:: `ld' and the Motorola 68HC11 and 68HC12 families
-
-* PowerPC ELF32:: `ld' and PowerPC 32-bit ELF Support
-
-* PowerPC64 ELF64:: `ld' and PowerPC64 64-bit ELF Support
-
-* SPU ELF:: `ld' and SPU ELF Support
-
-* TI COFF:: `ld' and TI COFF
-
-* WIN32:: `ld' and WIN32 (cygwin/mingw)
-
-* Xtensa:: `ld' and Xtensa Processors
-
-\1f
-File: ld.info, Node: H8/300, Next: i960, Up: Machine Dependent
-
-4.1 `ld' and the H8/300
-=======================
-
-For the H8/300, `ld' can perform these global optimizations when you
-specify the `--relax' command-line option.
-
-_relaxing address modes_
- `ld' finds all `jsr' and `jmp' instructions whose targets are
- within eight bits, and turns them into eight-bit program-counter
- relative `bsr' and `bra' instructions, respectively.
-
-_synthesizing instructions_
- `ld' finds all `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 `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the
- address AA is in the top page of memory).
-
-_bit manipulation instructions_
- `ld' finds all bit manipulation instructions like `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 `bset #xx:3,`@'AA:32'
- into `bset #xx:3,`@'AA:8' whenever the address AA is in the top
- page of memory).
-
-_system control instructions_
- `ld' finds all `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 `ldc.w `@'AA:32,ccr' into `ldc.w `@'AA:16,ccr' whenever the
- address AA is in the top page of memory).
-
-\1f
-File: ld.info, Node: i960, Next: ARM, Prev: H8/300, Up: Machine Dependent
-
-4.2 `ld' and the Intel 960 Family
-=================================
-
-You can use the `-AARCHITECTURE' 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.
-
- For example, if your `ld' command line included `-ACA' as well as
-`-ltry', the linker would look (in its built-in search paths, and in
-any paths you specify with `-L') for a library with the names
-
- try
- libtry.a
- tryca
- libtryca.a
-
-The first two possibilities would be considered in any event; the last
-two are due to the use of `-ACA'.
-
- You can meaningfully use `-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 `-l'
-specifies a library.
-
- `ld' supports the `--relax' option for the i960 family. If you
-specify `--relax', `ld' finds all `balx' and `calx' instructions whose
-targets are within 24 bits, and turns them into 24-bit program-counter
-relative `bal' and `cal' instructions, respectively. `ld' also turns
-`cal' instructions into `bal' instructions when it determines that the
-target subroutine is a leaf routine (that is, the target subroutine does
-not itself call any subroutines).
-
-\1f
-File: ld.info, Node: M68HC11/68HC12, Next: PowerPC ELF32, Prev: MSP430, Up: Machine Dependent
-
-4.3 `ld' and the Motorola 68HC11 and 68HC12 families
-====================================================
-
-4.3.1 Linker Relaxation
------------------------
-
-For the Motorola 68HC11, `ld' can perform these global optimizations
-when you specify the `--relax' command-line option.
-
-_relaxing address modes_
- `ld' finds all `jsr' and `jmp' instructions whose targets are
- within eight bits, and turns them into eight-bit program-counter
- relative `bsr' and `bra' instructions, respectively.
-
- `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).
-
-_relaxing gcc instruction group_
- When `gcc' is called with `-mrelax', it can emit group of
- instructions that the linker can optimize to use a 68HC11 direct
- addressing mode. These instructions consists of `bclr' or `bset'
- instructions.
-
-
-4.3.2 Trampoline Generation
----------------------------
-
-For 68HC11 and 68HC12, `ld' can generate trampoline code to call a far
-function using a normal `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.
-
- The `--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 `--emit-relocs' is
-used to generate relocatable binaries.
-
-\1f
-File: ld.info, Node: ARM, Next: HPPA ELF32, Prev: i960, Up: Machine Dependent
-
-4.4 `ld' and the ARM family
-===========================
-
-For the ARM, `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 `-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 `--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.
-
- The `--thumb-entry' switch is a duplicate of the generic `--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.
-
- The `--be8' switch instructs `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.
-
- The `R_ARM_TARGET1' relocation is typically used for entries in the
-`.init_array' section. It is interpreted as either `R_ARM_REL32' or
-`R_ARM_ABS32', depending on the target. The `--target1-rel' and
-`--target1-abs' switches override the default.
-
- The `--target2=type' switch overrides the default definition of the
-`R_ARM_TARGET2' relocation. Valid values for `type', their meanings,
-and target defaults are as follows:
-`rel'
- `R_ARM_REL32' (arm*-*-elf, arm*-*-eabi)
-
-`abs'
- `R_ARM_ABS32' (arm*-*-symbianelf)
-
-`got-rel'
- `R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd)
-
- The `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.
-
- In the latter case, the switch `--fix-v4bx' must be passed to the
-linker, which causes v4t `BX rM' instructions to be rewritten as `MOV
-PC,rM', since v4 processors do not have a `BX' instruction.
-
- In the former case, the switch should not be used, and `R_ARM_V4BX'
-relocations are ignored.
-
- The `--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.
-
- This option is enabled implicitly for SymbianOS, so there is no need
-to specify it if you are using that target.
-
- The `--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.
-
- 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.
-
- If you know you are using buggy VFP11 hardware, you can enable this
-workaround by specifying the linker option `--vfp-denorm-fix=scalar' if
-you are using the VFP11 scalar mode only, or `--vfp-denorm-fix=vector'
-if you are using vector mode (the latter also works for scalar code).
-The default is `--vfp-denorm-fix=none'.
-
- 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.
-
- The `--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.
-
-\1f
-File: ld.info, Node: HPPA ELF32, Next: MMIX, Prev: ARM, Up: Machine Dependent
-
-4.5 `ld' and HPPA 32-bit ELF Support
-====================================
-
-When generating a shared library, `ld' will by default generate import
-stubs suitable for use with a single sub-space application. The
-`--multi-subspace' switch causes `ld' to generate export stubs, and
-different (larger) import stubs suitable for use with multiple
-sub-spaces.
-
- Long branch stubs and import/export stubs are placed by `ld' in stub
-sections located between groups of input sections. `--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
-`N' chooses this scheme, ensuring that branches to stubs always use a
-negative offset. Two special values of `N' are recognized, `1' and
-`-1'. These both instruct `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 `N' respectively.
-
- Note that `--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.
-
-\1f
-File: ld.info, Node: MMIX, Next: MSP430, Prev: HPPA ELF32, Up: Machine Dependent
-
-4.6 `ld' and MMIX
-=================
-
-For MMIX, there is a choice of generating `ELF' object files or `mmo'
-object files when linking. The simulator `mmix' understands the `mmo'
-format. The binutils `objcopy' utility can translate between the two
-formats.
-
- There is one special section, the `.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
-`.MMIX.reg_contents' section corresponds to the first allocated global
-register multiplied by 8. Register `$255' is not included in this
-section; it is always set to the program entry, which is at the symbol
-`Main' for `mmo' files.
-
- Symbols with the prefix `__.MMIX.start.', for example
-`__.MMIX.start..text' and `__.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.
-
- Initial and trailing multiples of zero-valued 32-bit words in a
-section, are left out from an mmo file.
-
-\1f
-File: ld.info, Node: MSP430, Next: M68HC11/68HC12, Prev: MMIX, Up: Machine Dependent
-
-4.7 `ld' and MSP430
-===================
-
-For the MSP430 it is possible to select the MPU architecture. The flag
-`-m [mpu type]' will select an appropriate linker script for selected
-MPU type. (To get a list of known MPUs just pass `-m help' option to
-the linker).
-
- The linker will recognize some extra sections which are MSP430
-specific:
-
-``.vectors''
- Defines a portion of ROM where interrupt vectors located.
-
-``.bootloader''
- Defines the bootloader portion of the ROM (if applicable). Any
- code in this section will be uploaded to the MPU.
-
-``.infomem''
- Defines an information memory section (if applicable). Any code in
- this section will be uploaded to the MPU.
-
-``.infomemnobits''
- This is the same as the `.infomem' section except that any code in
- this section will not be uploaded to the MPU.
-
-``.noinit''
- Denotes a portion of RAM located above `.bss' section.
-
- The last two sections are used by gcc.
-
-\1f
-File: ld.info, Node: PowerPC ELF32, Next: PowerPC64 ELF64, Prev: M68HC11/68HC12, Up: Machine Dependent
-
-4.8 `ld' and PowerPC 32-bit ELF Support
-=======================================
-
-Branches on PowerPC processors are limited to a signed 26-bit
-displacement, which may result in `ld' giving `relocation truncated to
-fit' errors with very large programs. `--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.
-
-`--bss-plt'
- Current PowerPC GCC accepts a `-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
- `ld' will generate this layout, including stubs to access the PLT,
- if all input files (including startup and static libraries) were
- compiled with `-msecure-plt'. `--bss-plt' forces the old BSS PLT
- (and GOT layout) which can give slightly better performance.
-
-`--secure-plt'
- `ld' will use the new PLT and GOT layout if it is linking new
- `-fpic' or `-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.
-
-`--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 `.plt' must change because the new secure PLT is an
- initialized section while the old PLT is uninitialized. The
- reason for the `.got' change is more subtle: The new placement
- allows `.got' to be read-only in applications linked with `-z
- relro -z now'. However, this placement means that `.sdata' cannot
- always be used in shared libraries, because the PowerPC ABI
- accesses `.sdata' in shared libraries from the GOT pointer.
- `--sdata-got' forces the old GOT placement. PowerPC GCC doesn't
- use `.sdata' in shared libraries, so this option is really only
- useful for other compilers that may do so.
-
-`--emit-stub-syms'
- This option causes `ld' to label linker stubs with a local symbol
- that encodes the stub type and destination.
-
-`--no-tls-optimize'
- PowerPC `ld' normally performs some optimization of code sequences
- used to access Thread-Local Storage. Use this option to disable
- the optimization.
-
-\1f
-File: ld.info, Node: PowerPC64 ELF64, Next: SPU ELF, Prev: PowerPC ELF32, Up: Machine Dependent
-
-4.9 `ld' and PowerPC64 64-bit ELF Support
-=========================================
-
-`--stub-group-size'
- Long branch stubs, PLT call stubs and TOC adjusting stubs are
- placed by `ld' in stub sections located between groups of input
- sections. `--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 `N'
- chooses this scheme, ensuring that branches to stubs always use a
- negative offset. Two special values of `N' are recognized, `1'
- and `-1'. These both instruct `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 `N' respectively.
-
- Note that `--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.
-
-`--emit-stub-syms'
- This option causes `ld' to label linker stubs with a local symbol
- that encodes the stub type and destination.
-
-`--dotsyms, --no-dotsyms'
- These two options control how `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 (`.'). To
- properly version a function `foo', the version script thus needs
- to control both `foo' and `.foo'. The option `--dotsyms', on by
- default, automatically adds the required dot-prefixed patterns.
- Use `--no-dotsyms' to disable this feature.
-
-`--no-tls-optimize'
- PowerPC64 `ld' normally performs some optimization of code
- sequences used to access Thread-Local Storage. Use this option to
- disable the optimization.
-
-`--no-opd-optimize'
- PowerPC64 `ld' normally removes `.opd' section entries
- corresponding to deleted link-once functions, or functions removed
- by the action of `--gc-sections' or linker scrip `/DISCARD/'. Use
- this option to disable `.opd' optimization.
-
-`--non-overlapping-opd'
- Some PowerPC64 compilers have an option to generate compressed
- `.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.
-
-`--no-toc-optimize'
- PowerPC64 `ld' normally removes unused `.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.
-
-`--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 `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. `ld' does not split apart input sections, so
- cannot help if a single input file has a `.toc' section that
- exceeds 64K, most likely from linking multiple files with `ld -r'.
- Use this option to turn off this feature.
-
-\1f
-File: ld.info, Node: SPU ELF, Next: TI COFF, Prev: PowerPC64 ELF64, Up: Machine Dependent
-
-4.10 `ld' and SPU ELF Support
-=============================
-
-`--plugin'
- This option marks an executable as a PIC plugin module.
-
-`--no-overlays'
- Normally, `ld' recognizes calls to functions within overlay
- regions, and redirects such calls to an overlay manager via a stub.
- `ld' also provides a built-in overlay manager. This option turns
- off all this special overlay handling.
-
-`--emit-stub-syms'
- This option causes `ld' to label overlay stubs with a local symbol
- that encodes the stub type and destination.
-
-`--extra-overlay-stubs'
- This option causes `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.
-
-`--local-store=lo:hi'
- `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 `--local-store=0:0'.
-
-`--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, `ld' will provide an estimate of maximum stack usage.
- `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.
-
-`--emit-stack-syms'
- This option, if given along with `--stack-analysis' will result in
- `ld' emitting stack sizing symbols for each function. These take
- the form `__stack_<function_name>' for global functions, and
- `__stack_<number>_<function_name>' for static functions.
- `<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 `STT_NOTYPE', binding `STB_LOCAL', and
- section `SHN_ABS'.
-
-\1f
-File: ld.info, Node: TI COFF, Next: WIN32, Prev: SPU ELF, Up: Machine Dependent
-
-4.11 `ld''s Support for Various TI COFF Versions
-================================================
-
-The `--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;
-`ld' will read any version or byte order, but the output header format
-depends on the default specified by the specific target.
-
-\1f
-File: ld.info, Node: WIN32, Next: Xtensa, Prev: TI COFF, Up: Machine Dependent
-
-4.12 `ld' and WIN32 (cygwin/mingw)
-==================================
-
-This section describes some of the win32 specific `ld' issues. See
-*Note Command Line Options: Options. for detailed description of the
-command line options mentioned here.
-
-_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 `ld' have specific support
- for creating such libraries provided with the `--out-implib'
- command line option.
-
-_exporting DLL symbols_
- The cygwin/mingw `ld' has several ways to export symbols for dll's.
-
- _using auto-export functionality_
- By default `ld' exports symbols with the auto-export
- functionality, which is controlled by the following command
- line options:
-
- * -export-all-symbols [This is the default]
-
- * -exclude-symbols
-
- * -exclude-libs
-
- If, however, `--export-all-symbols' is not given explicitly
- on the command line, then the default auto-export behavior
- will be _disabled_ if either of the following are true:
-
- * A DEF file is used.
-
- * Any symbol in any object file was marked with the
- __declspec(dllexport) attribute.
-
- _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 `<dll name>.def' and is added as any other object file
- to the linker's command line. The file's name must end in
- `.def' or `.DEF'.
-
- gcc -o <output> <objectfiles> <dll name>.def
-
- Using a DEF file turns off the normal auto-export behavior,
- unless the `--export-all-symbols' option is also used.
-
- Here is an example of a DEF file for a shared library called
- `xyz.dll':
-
- LIBRARY "xyz.dll" BASE=0x20000000
-
- EXPORTS
- foo
- bar
- _bar = bar
- another_foo = abc.dll.afoo
- var1 DATA
-
- This example defines a DLL with a non-default base address
- and five symbols in the export table. The third exported
- symbol `_bar' is an alias for the second. The fourth symbol,
- `another_foo' is resolved by "forwarding" to another module
- and treating it as an alias for `afoo' exported from the DLL
- `abc.dll'. The final symbol `var1' is declared to be a data
- object.
-
- The optional `LIBRARY <name>' command indicates the _internal_
- name of the output DLL. If `<name>' does not include a suffix,
- the default library suffix, `.DLL' is appended.
-
- When the .DEF file is used to build an application, rather
- than a library, the `NAME <name>' command should be used
- instead of `LIBRARY'. If `<name>' does not include a suffix,
- the default executable suffix, `.EXE' is appended.
-
- With either `LIBRARY <name>' or `NAME <name>' the optional
- specification `BASE = <number>' may be used to specify a
- non-default base address for the image.
-
- If neither `LIBRARY <name>' nor `NAME <name>' is specified,
- or they specify an empty string, the internal name is the
- same as the filename specified on the command line.
-
- The complete specification of an export symbol is:
-
- EXPORTS
- ( ( ( <name1> [ = <name2> ] )
- | ( <name1> = <module-name> . <external-name>))
- [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
-
- Declares `<name1>' as an exported symbol from the DLL, or
- declares `<name1>' as an exported alias for `<name2>'; or
- declares `<name1>' as a "forward" alias for the symbol
- `<external-name>' in the DLL `<module-name>'. Optionally,
- the symbol may be exported by the specified ordinal
- `<integer>' alias.
-
- The optional keywords that follow the declaration indicate:
-
- `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 `PRIVATE' is also specified.
-
- `DATA': The symbol is a variable or object, rather than a
- function. The import lib will export only an indirect
- reference to `foo' as the symbol `_imp__foo' (ie, `foo' must
- be resolved as `*_imp__foo').
-
- `CONSTANT': Like `DATA', but put the undecorated `foo' as
- well as `_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 `dllimport' attribute and also fails to
- explicitly add the extra indirection that the use of the
- attribute enforces, the application will behave unexpectedly.
-
- `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 `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
-
- While linking a shared dll, `ld' is able to create a DEF file
- with the `--output-def <file>' command line option.
-
- _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:
-
- __declspec(dllexport) int a_variable
- __declspec(dllexport) void a_function(int with_args)
-
- 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 `--export-all-symbols' option is also
- used.
-
- Note that object files that wish to access these symbols must
- _not_ decorate them with dllexport. Instead, they should use
- dllimport, instead:
-
- __declspec(dllimport) int a_variable
- __declspec(dllimport) void a_function(int with_args)
-
- 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 `--enable-auto-import' and
- `automatic data imports' for more information.
-
-_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
- `--enable-auto-import' command-line option, although it is enabled
- by default on cygwin/mingw. The `--enable-auto-import' option
- itself now serves mainly to suppress any warnings that are
- ordinarily emitted when linked objects trigger the feature's use.
-
- auto-import of variables does not always work flawlessly without
- additional assistance. Sometimes, you will see this message
-
- "variable '<var>' can't be auto-imported. Please read the
- documentation for ld's `--enable-auto-import' for details."
-
- The `--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 _runtime pseudo-relocs_
- feature, described below.
-
- For complex variables imported from DLLs (such as structs or
- classes), object files typically contain a base address for the
- variable and an offset (_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.
-
- The `--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.
-
- `--enable-runtime-pseudo-relocs' is not the default; it must be
- explicitly enabled as needed.
-
-_direct linking to a dll_
- The cygwin/mingw ports of `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 `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.
-
- Linking directly to a dll uses no extra command-line switches
- other than `-L' and `-l', because `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.
-
- For instance, when ld is called with the argument `-lxxx' it will
- attempt to find, in the first directory of its search path,
-
- libxxx.dll.a
- xxx.dll.a
- libxxx.a
- xxx.lib
- cygxxx.dll (*)
- libxxx.dll
- xxx.dll
-
- before moving on to the next directory in the search path.
-
- (*) Actually, this is not `cygxxx.dll' but in fact is
- `<prefix>xxx.dll', where `<prefix>' is set by the `ld' option
- `--dll-search-prefix=<prefix>'. In the case of cygwin, the
- standard gcc spec file includes `--dll-search-prefix=cyg', so in
- effect we actually search for `cygxxx.dll'.
-
- Other win32-based unix environments, such as mingw or pw32, may
- use other `<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.
-
- The generic cygwin/mingw path layout uses a `bin' directory for
- applications and dll's and a `lib' directory for the import
- libraries (using cygwin nomenclature):
-
- bin/
- cygxxx.dll
- lib/
- libxxx.dll.a (in case of dll's)
- libxxx.a (in case of static archive)
-
- Linking directly to a dll without using the import library can be
- done two ways:
-
- 1. Use the dll directly by adding the `bin' path to the link line
- gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
-
- However, as the dll's often have version numbers appended to their
- names (`cygncurses-5.dll') this will often fail, unless one
- specifies `-L../bin -lncurses-5' to include the version. Import
- libs are generally not versioned, and do not have this difficulty.
-
- 2. Create a symbolic link from the dll to a file in the `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.
-
- ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
-
- Then you can link without any make environment changes.
-
- gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
-
- This technique also avoids the version number problems, because
- the following is perfectly legal
-
- bin/
- cygxxx-5.dll
- lib/
- libxxx.dll.a -> ../bin/cygxxx-5.dll
-
- Linking directly to a dll without using an import lib will work
- even when auto-import features are exercised, and even when
- `--enable-runtime-pseudo-relocs' is used.
-
- Given the improvements in speed and memory usage, one might
- justifiably wonder why import libraries are used at all. There
- are three reasons:
-
- 1. Until recently, the link-directly-to-dll functionality did _not_
- work with auto-imported data.
-
- 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.
-
- 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.
-
- 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.
-
-_symbol aliasing_
-
- _adding additional names_
- Sometimes, it is useful to export symbols with additional
- names. A symbol `foo' will be exported as `foo', but it can
- also be exported as `_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:
-
- LIBRARY "xyz.dll" BASE=0x61000000
-
- EXPORTS
- foo
- _foo = foo
-
- The line `_foo = foo' maps the symbol `foo' to `_foo'.
-
- Another method for creating a symbol alias is to create it in
- the source code using the "weak" attribute:
-
- void foo () { /* Do something. */; }
- void _foo () __attribute__ ((weak, alias ("foo")));
-
- See the gcc manual for more information about attributes and
- weak symbols.
-
- _renaming symbols_
- Sometimes it is useful to rename exports. For instance, the
- cygwin kernel does this regularly. A symbol `_foo' can be
- exported as `foo' but not as `_foo' by using special
- directives in the DEF file. (This will also affect the import
- library, if it is created). In the following example:
-
- LIBRARY "xyz.dll" BASE=0x61000000
-
- EXPORTS
- _foo = foo
-
- The line `_foo = foo' maps the exported symbol `foo' to
- `_foo'.
-
- Note: using a DEF file disables the default auto-export behavior,
- unless the `--export-all-symbols' command line option is used.
- If, however, you are trying to rename symbols, then you should list
- _all_ desired exports in the DEF file, including the symbols that
- are not being renamed, and do _not_ use the `--export-all-symbols'
- option. If you list only the renamed symbols in the DEF file, and
- use `--export-all-symbols' to handle the other symbols, then the
- both the new names _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.
-
-_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:
- * Definition is searched for in objects and libraries,
- historically called lazy externals.
-
- * Definition is searched for only in other objects, not in
- libraries. This form is not presently implemented.
-
- * No search; the symbol is an alias. This form is not presently
- implemented.
- 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.
-
-\1f
-File: ld.info, Node: Xtensa, Prev: WIN32, Up: Machine Dependent
-
-4.13 `ld' and Xtensa Processors
-===============================
-
-The default `ld' behavior for Xtensa processors is to interpret
-`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:
-
- SECTIONS
- {
- .text : {
- *(.literal .text)
- }
- }
-
-`ld' may interleave some of the `.literal' and `.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 `.literal' sections from an initial group of files followed by the
-`.text' sections of that group of files. Then, the `.literal' sections
-from the rest of the files and the `.text' sections from the rest of
-the files would follow.
-
- Relaxation is enabled by default for the Xtensa version of `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 `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 `L32R' instructions. The second optimization is to remove
-unnecessary overhead from assembler-generated "longcall" sequences of
-`L32R'/`CALLXN' when the target functions are within range of direct
-`CALLN' instructions.
-
- For each of these cases where an indirect call sequence can be
-optimized to a direct call, the linker will change the `CALLXN'
-instruction to a `CALLN' instruction, remove the `L32R' instruction,
-and remove the literal referenced by the `L32R' instruction if it is
-not used for anything else. Removing the `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 `L32R' instruction that was removed.
-If code size is more important than performance, the `--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.
-
- The following Xtensa-specific command-line options can be used to
-control the linker:
-
-`--no-relax'
- Since the Xtensa version of `ld' enables the `--relax' option by
- default, the `--no-relax' option is provided to disable relaxation.
-
-`--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.
-
-\1f
-File: ld.info, Node: BFD, Next: Reporting Bugs, Prev: Machine Dependent, Up: Top
-
-5 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 `objdump -i' (*note
-objdump: (binutils.info)objdump.) to list all the formats available for
-your configuration.
-
- 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.
-
- 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. *Note BFD information loss::.
-
-* Menu:
-
-* BFD outline:: How it works: an outline of BFD
-
-\1f
-File: ld.info, Node: BFD outline, Up: BFD
-
-5.1 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.
-
- 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.
-
-* Menu:
-
-* BFD information loss:: Information Loss
-* Canonical format:: The BFD canonical object-file format
-
-\1f
-File: ld.info, Node: BFD information loss, Next: Canonical format, Up: BFD outline
-
-5.1.1 Information Loss
-----------------------
-
-_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 `b.out'. There is nowhere
-in an `a.out' format file to store alignment information on the
-contained data, so when a file is linked from `b.out' and an `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).
-
- 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., `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.
-
- _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.
-
- 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 `a.out' to
-`b.out'. When a mixture of formats is linked, the information is only
-lost from the files whose format differs from the destination.
-
-\1f
-File: ld.info, Node: Canonical format, Prev: BFD information loss, Up: BFD outline
-
-5.1.2 The BFD canonical object-file format
-------------------------------------------
-
-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.
-
-_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 `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.
-
-_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.
-
-_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. `ld' can operate on a collection
- of symbols of wildly different formats without problems.
-
- 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 `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.
-
- 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.
-
-_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.
-
-_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).
-
-\1f
-File: ld.info, Node: Reporting Bugs, Next: MRI, Prev: BFD, Up: Top
-
-6 Reporting Bugs
-****************
-
-Your bug reports play an essential role in making `ld' reliable.
-
- 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 `ld' work
-better. Bug reports are your contribution to the maintenance of `ld'.
-
- In order for a bug report to serve its purpose, you must include the
-information that enables us to fix the bug.
-
-* Menu:
-
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-
-\1f
-File: ld.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs
-
-6.1 Have You Found a Bug?
-=========================
-
-If you are not sure whether you have found a bug, here are some
-guidelines:
-
- * If the linker gets a fatal signal, for any input whatever, that is
- a `ld' bug. Reliable linkers never crash.
-
- * If `ld' produces an error message for valid input, that is a bug.
-
- * If `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.
-
- * If you are an experienced user of linkers, your suggestions for
- improvement of `ld' are welcome in any case.
-
-\1f
-File: ld.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
-
-6.2 How to Report Bugs
-======================
-
-A number of companies and individuals offer support for GNU products.
-If you obtained `ld' from a support organization, we recommend you
-contact that organization first.
-
- You can find contact information for many support companies and
-individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
-
- Otherwise, send bug reports for `ld' to
-`http://www.sourceware.org/bugzilla/'.
-
- The fundamental principle of reporting bugs usefully is this:
-*report all the facts*. If you are not sure whether to state a fact or
-leave it out, state it!
-
- 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.
-
- 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.
-
- Sometimes people give a few sketchy facts and ask, "Does this ring a
-bell?" 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.
-
- To enable us to fix the bug, you should include all these things:
-
- * The version of `ld'. `ld' announces it if you start it with the
- `--version' argument.
-
- Without this, we will not know whether there is any point in
- looking for the bug in the current version of `ld'.
-
- * Any patches you may have applied to the `ld' source, including any
- patches made to the `BFD' library.
-
- * The type of machine you are using, and the operating system name
- and version number.
-
- * What compiler (and its version) was used to compile `ld'--e.g.
- "`gcc-2.7'".
-
- * 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.
-
- If we were to try to guess the arguments, we would probably guess
- wrong and then we might not encounter the bug.
-
- * 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.
-
- If the source files were assembled using `gas' or compiled using
- `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
- `gas' or `gcc' was used to produce the object files. Also say how
- `gas' or `gcc' were configured.
-
- * A description of what behavior you observe that you believe is
- incorrect. For example, "It gets a fatal signal."
-
- Of course, if the bug is that `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.
-
- 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 `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.
-
- * If you wish to suggest changes to the `ld' source, send us context
- diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
- Always send diffs from the old file to the new file. If you even
- discuss something in the `ld' source, refer to it by context, not
- by line number.
-
- The line numbers in our development sources will not match those
- in your sources. Your line numbers would convey no useful
- information to us.
-
- Here are some things that are not necessary:
-
- * A description of the envelope of the bug.
-
- 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.
-
- 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.
-
- Of course, if you can find a simpler example to report _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.
-
- 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.
-
- * A patch for the bug.
-
- 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.
-
- Sometimes with a program as complicated as `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.
-
- 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.
-
- * A guess about what the bug is or what it depends on.
-
- Such guesses are usually wrong. Even we cannot guess right about
- such things without first using the debugger to find the facts.
-
-\1f
-File: ld.info, Node: MRI, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top
-
-Appendix A MRI Compatible Script Files
-**************************************
-
-To aid users making the transition to GNU `ld' from the MRI linker,
-`ld' can use MRI compatible linker scripts as an alternative to the
-more general-purpose linker scripting language described in *Note
-Scripts::. MRI compatible linker scripts have a much simpler command
-set than the scripting language otherwise used with `ld'. GNU `ld'
-supports the most commonly used MRI linker commands; these commands are
-described here.
-
- In general, MRI scripts aren't of much use with the `a.out' object
-file format, since it only has three sections and MRI scripts lack some
-features to make use of them.
-
- You can specify a file containing an MRI-compatible script using the
-`-c' command-line option.
-
- 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, `ld' issues
-a warning message, but continues processing the script.
-
- Lines beginning with `*' are comments.
-
- You can write these commands using all upper-case letters, or all
-lower case; for example, `chip' is the same as `CHIP'. The following
-list shows only the upper-case form of each command.
-
-`ABSOLUTE SECNAME'
-`ABSOLUTE SECNAME, SECNAME, ... SECNAME'
- Normally, `ld' includes in the output file all sections from all
- the input files. However, in an MRI-compatible script, you can
- use the `ABSOLUTE' command to restrict the sections that will be
- present in your output program. If the `ABSOLUTE' command is used
- at all in a script, then only the sections named explicitly in
- `ABSOLUTE' commands will appear in the linker output. You can
- still use other input sections (whatever you select on the command
- line, or using `LOAD') to resolve addresses in the output file.
-
-`ALIAS OUT-SECNAME, IN-SECNAME'
- Use this command to place the data from input section IN-SECNAME
- in a section called OUT-SECNAME in the linker output file.
-
- IN-SECNAME may be an integer.
-
-`ALIGN SECNAME = EXPRESSION'
- Align the section called SECNAME to EXPRESSION. The EXPRESSION
- should be a power of two.
-
-`BASE EXPRESSION'
- Use the value of EXPRESSION as the lowest address (other than
- absolute addresses) in the output file.
-
-`CHIP EXPRESSION'
-`CHIP EXPRESSION, EXPRESSION'
- This command does nothing; it is accepted only for compatibility.
-
-`END'
- This command does nothing whatever; it's only accepted for
- compatibility.
-
-`FORMAT OUTPUT-FORMAT'
- Similar to the `OUTPUT_FORMAT' command in the more general linker
- language, but restricted to one of these output formats:
-
- 1. S-records, if OUTPUT-FORMAT is `S'
-
- 2. IEEE, if OUTPUT-FORMAT is `IEEE'
-
- 3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is
- `COFF'
-
-`LIST ANYTHING...'
- Print (to the standard output file) a link map, as produced by the
- `ld' command-line option `-M'.
-
- The keyword `LIST' may be followed by anything on the same line,
- with no change in its effect.
-
-`LOAD FILENAME'
-`LOAD FILENAME, FILENAME, ... FILENAME'
- Include one or more object file FILENAME in the link; this has the
- same effect as specifying FILENAME directly on the `ld' command
- line.
-
-`NAME OUTPUT-NAME'
- OUTPUT-NAME is the name for the program produced by `ld'; the
- MRI-compatible command `NAME' is equivalent to the command-line
- option `-o' or the general script language command `OUTPUT'.
-
-`ORDER SECNAME, SECNAME, ... SECNAME'
-`ORDER SECNAME SECNAME SECNAME'
- Normally, `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
- `ORDER' command. The sections you list with `ORDER' will appear
- first in your output file, in the order specified.
-
-`PUBLIC NAME=EXPRESSION'
-`PUBLIC NAME,EXPRESSION'
-`PUBLIC NAME EXPRESSION'
- Supply a value (EXPRESSION) for external symbol NAME used in the
- linker input files.
-
-`SECT SECNAME, EXPRESSION'
-`SECT SECNAME=EXPRESSION'
-`SECT SECNAME EXPRESSION'
- You can use any of these three forms of the `SECT' command to
- specify the start address (EXPRESSION) for section SECNAME. If
- you have more than one `SECT' statement for the same SECNAME, only
- the _first_ sets the start address.
-
-\1f
-File: ld.info, Node: GNU Free Documentation License, Next: LD Index, Prev: MRI, Up: Top
-
-Appendix B GNU Free Documentation License
-*****************************************
-
- Version 1.1, March 2000
-
- Copyright (C) 2000, 2003 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.
-
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone
- the effective freedom to copy and redistribute it, with or without
- modifying it, either commercially or noncommercially. Secondarily,
- this License preserves for the author and publisher a way to get
- credit for their work, while not being considered responsible for
- modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to
- software manuals; it can be used for any textual work, regardless
- of subject matter or whether it is published as a printed book.
- We recommend this License principally for works whose purpose is
- instruction or reference.
-
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be distributed
- under the terms of this License. The "Document", below, refers to
- any such manual or work. Any member of the public is a licensee,
- and is addressed as "you."
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter
- section of the Document that deals exclusively with the
- relationship of the publishers or authors of the Document to the
- Document's overall subject (or to related matters) and contains
- nothing that could fall directly within that overall subject.
- (For example, if the Document is in part a textbook of
- mathematics, a Secondary Section may not explain any mathematics.)
- The relationship could be a matter of historical connection with
- the subject or with related matters, or of legal, commercial,
- philosophical, ethical or political position regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, whose contents can be viewed and edited directly
- and straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup has been designed
- to thwart or discourage subsequent modification by readers is not
- Transparent. A copy that is not "Transparent" is called "Opaque."
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human modification.
- Opaque formats include PostScript, PDF, proprietary formats that
- can be read and edited only by proprietary word processors, SGML
- or XML for which the DTD and/or processing tools are not generally
- available, and the machine-generated HTML produced by some word
- processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, "Title
- Page" means the text near the most prominent appearance of the
- work's title, preceding the beginning of the body of the text.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow
- the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more than
- 100, and the Document's license notice requires Cover Texts, you
- must enclose the copies in covers that carry, clearly and legibly,
- all these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the
- title equally prominent and visible. You may add other material
- on the covers in addition. Copying with changes limited to the
- covers, as long as they preserve the title of the Document and
- satisfy these conditions, can be treated as verbatim copying in
- other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy, or
- state in or with each Opaque copy a publicly-accessible
- computer-network location containing a complete Transparent copy
- of the Document, free of added material, which the general
- network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with
- the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version to
- whoever possesses a copy of it. In addition, you must do these
- things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title
- as a previous version if the original publisher of that version
- gives permission.
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it
- has less than five).
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page.
- If there is no section entitled "History" in the Document,
- create one stating the title, year, authors, and publisher of
- the Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in the
- "History" section. You may omit a network location for a work
- that was published at least four years before the Document
- itself, or if the original publisher of the version it refers
- to gives permission.
- K. In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
- M. Delete any section entitled "Endorsements." Such a section
- may not be included in the Modified Version.
- N. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do this,
- add their titles to the list of Invariant Sections in the Modified
- Version's license notice. These titles must be distinct from any
- other section titles.
-
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties-for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition
- of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If the
- Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same entity
- you are acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section
- entitled "History"; likewise combine any sections entitled
- "Acknowledgements", and any sections entitled "Dedications." You
- must delete all sections entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow
- this License in all other respects regarding verbatim copying of
- that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of
- a storage or distribution medium, does not as a whole count as a
- Modified Version of the Document, provided no compilation
- copyright is claimed for the compilation. Such a compilation is
- called an "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document, on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may be
- placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License provided that you also include the
- original English version of this License. In case of a
- disagreement between the translation and the original English
- version of this License, the original English version will prevail.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-====================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.1
- or any later version published by the Free Software Foundation;
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License."
-
- If you have no Invariant Sections, write "with no Invariant Sections"
-instead of saying which ones are invariant. If you have no Front-Cover
-Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
-LIST"; likewise for Back-Cover Texts.
-
- If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License, to
-permit their use in free software.
-
-\1f
-File: ld.info, Node: LD Index, Prev: GNU Free Documentation License, Up: Top
-
-LD Index
-********
-
-\0\b[index\0\b]
-* Menu:
-
-* ": Symbols. (line 6)
-* -(: Options. (line 643)
-* --accept-unknown-input-arch: Options. (line 661)
-* --add-needed: Options. (line 683)
-* --add-stdcall-alias: Options. (line 1450)
-* --allow-multiple-definition: Options. (line 892)
-* --allow-shlib-undefined: Options. (line 898)
-* --architecture=ARCH: Options. (line 104)
-* --as-needed: Options. (line 671)
-* --auxiliary: Options. (line 205)
-* --bank-window: Options. (line 1789)
-* --base-file: Options. (line 1455)
-* --be8: ARM. (line 23)
-* --bss-plt: PowerPC ELF32. (line 13)
-* --build-id: Options. (line 1412)
-* --build-id=STYLE: Options. (line 1412)
-* --check-sections: Options. (line 765)
-* --cref: Options. (line 775)
-* --default-imported-symver: Options. (line 926)
-* --default-script=SCRIPT: Options. (line 488)
-* --default-symver: Options. (line 922)
-* --defsym SYMBOL=EXP: Options. (line 803)
-* --demangle[=STYLE]: Options. (line 816)
-* --disable-auto-image-base: Options. (line 1602)
-* --disable-auto-import: Options. (line 1731)
-* --disable-new-dtags: Options. (line 1375)
-* --disable-runtime-pseudo-reloc: Options. (line 1744)
-* --disable-stdcall-fixup: Options. (line 1465)
-* --discard-all: Options. (line 534)
-* --discard-locals: Options. (line 538)
-* --dll: Options. (line 1460)
-* --dll-search-prefix: Options. (line 1608)
-* --dotsyms: PowerPC64 ELF64. (line 33)
-* --dynamic-linker FILE: Options. (line 829)
-* --dynamic-list-cpp-new: Options. (line 757)
-* --dynamic-list-cpp-typeinfo: Options. (line 761)
-* --dynamic-list-data: Options. (line 754)
-* --dynamic-list=DYNAMIC-LIST-FILE: Options. (line 741)
-* --eh-frame-hdr: Options. (line 1371)
-* --emit-relocs: Options. (line 423)
-* --emit-stack-syms: SPU ELF. (line 46)
-* --emit-stub-syms <1>: SPU ELF. (line 15)
-* --emit-stub-syms <2>: PowerPC64 ELF64. (line 29)
-* --emit-stub-syms: PowerPC ELF32. (line 44)
-* --enable-auto-image-base: Options. (line 1594)
-* --enable-auto-import: Options. (line 1617)
-* --enable-extra-pe-debug: Options. (line 1749)
-* --enable-new-dtags: Options. (line 1375)
-* --enable-runtime-pseudo-reloc: Options. (line 1736)
-* --enable-stdcall-fixup: Options. (line 1465)
-* --entry=ENTRY: Options. (line 158)
-* --error-unresolved-symbols: Options. (line 1324)
-* --exclude-libs: Options. (line 168)
-* --exclude-symbols: Options. (line 1507)
-* --export-all-symbols: Options. (line 1483)
-* --export-dynamic: Options. (line 179)
-* --extra-overlay-stubs: SPU ELF. (line 19)
-* --fatal-warnings: Options. (line 835)
-* --file-alignment: Options. (line 1513)
-* --filter: Options. (line 226)
-* --fix-v4bx: ARM. (line 44)
-* --force-dynamic: Options. (line 432)
-* --force-exe-suffix: Options. (line 838)
-* --format=FORMAT: Options. (line 115)
-* --format=VERSION: TI COFF. (line 6)
-* --gc-sections: Options. (line 848)
-* --gpsize: Options. (line 259)
-* --hash-size=NUMBER: Options. (line 1384)
-* --hash-style=STYLE: Options. (line 1392)
-* --heap: Options. (line 1519)
-* --help: Options. (line 865)
-* --image-base: Options. (line 1526)
-* --just-symbols=FILE: Options. (line 455)
-* --kill-at: Options. (line 1535)
-* --large-address-aware: Options. (line 1540)
-* --library-path=DIR: Options. (line 318)
-* --library=NAMESPEC: Options. (line 285)
-* --local-store=lo:hi: SPU ELF. (line 24)
-* --major-image-version: Options. (line 1549)
-* --major-os-version: Options. (line 1554)
-* --major-subsystem-version: Options. (line 1558)
-* --minor-image-version: Options. (line 1563)
-* --minor-os-version: Options. (line 1568)
-* --minor-subsystem-version: Options. (line 1572)
-* --mri-script=MRI-CMDFILE: Options. (line 139)
-* --multi-subspace: HPPA ELF32. (line 6)
-* --nmagic: Options. (line 387)
-* --no-accept-unknown-input-arch: Options. (line 661)
-* --no-add-needed: Options. (line 683)
-* --no-allow-shlib-undefined: Options. (line 898)
-* --no-as-needed: Options. (line 671)
-* --no-check-sections: Options. (line 765)
-* --no-define-common: Options. (line 787)
-* --no-demangle: Options. (line 816)
-* --no-dotsyms: PowerPC64 ELF64. (line 33)
-* --no-enum-size-warning: ARM. (line 94)
-* --no-gc-sections: Options. (line 848)
-* --no-keep-memory: Options. (line 877)
-* --no-multi-toc: PowerPC64 ELF64. (line 74)
-* --no-omagic: Options. (line 401)
-* --no-opd-optimize: PowerPC64 ELF64. (line 48)
-* --no-overlays: SPU ELF. (line 9)
-* --no-print-gc-sections: Options. (line 856)
-* --no-relax: Xtensa. (line 56)
-* --no-tls-optimize <1>: PowerPC64 ELF64. (line 43)
-* --no-tls-optimize: PowerPC ELF32. (line 48)
-* --no-toc-optimize: PowerPC64 ELF64. (line 60)
-* --no-trampoline: Options. (line 1783)
-* --no-undefined: Options. (line 884)
-* --no-undefined-version: Options. (line 917)
-* --no-warn-mismatch: Options. (line 930)
-* --no-warn-search-mismatch: Options. (line 939)
-* --no-whole-archive: Options. (line 943)
-* --noinhibit-exec: Options. (line 947)
-* --non-overlapping-opd: PowerPC64 ELF64. (line 54)
-* --oformat: Options. (line 959)
-* --omagic: Options. (line 392)
-* --out-implib: Options. (line 1585)
-* --output-def: Options. (line 1577)
-* --output=OUTPUT: Options. (line 407)
-* --pic-executable: Options. (line 972)
-* --pic-veneer: M68HC11/68HC12. (line 38)
-* --plugin: SPU ELF. (line 6)
-* --print-gc-sections: Options. (line 856)
-* --print-map: Options. (line 350)
-* --reduce-memory-overheads: Options. (line 1398)
-* --relax: Options. (line 988)
-* --relax on i960: i960. (line 31)
-* --relax on PowerPC: PowerPC ELF32. (line 6)
-* --relax on Xtensa: Xtensa. (line 27)
-* --relocatable: Options. (line 436)
-* --script=SCRIPT: Options. (line 479)
-* --sdata-got: PowerPC ELF32. (line 30)
-* --section-alignment: Options. (line 1754)
-* --section-start SECTIONNAME=ORG: Options. (line 1161)
-* --secure-plt: PowerPC ELF32. (line 23)
-* --sort-common: Options. (line 1108)
-* --sort-section alignment: Options. (line 1118)
-* --sort-section name: Options. (line 1114)
-* --split-by-file: Options. (line 1122)
-* --split-by-reloc: Options. (line 1127)
-* --stack: Options. (line 1760)
-* --stack-analysis: SPU ELF. (line 29)
-* --stats: Options. (line 1140)
-* --strip-all: Options. (line 466)
-* --strip-debug: Options. (line 470)
-* --stub-group-size: PowerPC64 ELF64. (line 6)
-* --stub-group-size=N: HPPA ELF32. (line 12)
-* --subsystem: Options. (line 1767)
-* --support-old-code: ARM. (line 6)
-* --sysroot: Options. (line 1144)
-* --target-help: Options. (line 869)
-* --target1-abs: ARM. (line 27)
-* --target1-rel: ARM. (line 27)
-* --target2=TYPE: ARM. (line 32)
-* --thumb-entry=ENTRY: ARM. (line 17)
-* --trace: Options. (line 475)
-* --trace-symbol=SYMBOL: Options. (line 544)
-* --traditional-format: Options. (line 1149)
-* --undefined=SYMBOL: Options. (line 501)
-* --unique[=SECTION]: Options. (line 519)
-* --unresolved-symbols: Options. (line 1176)
-* --use-blx: ARM. (line 57)
-* --verbose: Options. (line 1205)
-* --version: Options. (line 528)
-* --version-script=VERSION-SCRIPTFILE: Options. (line 1211)
-* --vfp11-denorm-fix: ARM. (line 66)
-* --warn-common: Options. (line 1218)
-* --warn-constructors: Options. (line 1286)
-* --warn-multiple-gp: Options. (line 1291)
-* --warn-once: Options. (line 1305)
-* --warn-section-align: Options. (line 1309)
-* --warn-shared-textrel: Options. (line 1316)
-* --warn-unresolved-symbols: Options. (line 1319)
-* --whole-archive: Options. (line 1328)
-* --wrap: Options. (line 1342)
-* -AARCH: Options. (line 103)
-* -aKEYWORD: Options. (line 96)
-* -assert KEYWORD: Options. (line 693)
-* -b FORMAT: Options. (line 115)
-* -Bdynamic: Options. (line 696)
-* -Bgroup: Options. (line 706)
-* -Bshareable: Options. (line 1100)
-* -Bstatic: Options. (line 713)
-* -Bsymbolic: Options. (line 728)
-* -Bsymbolic-functions: Options. (line 735)
-* -c MRI-CMDFILE: Options. (line 139)
-* -call_shared: Options. (line 696)
-* -d: Options. (line 149)
-* -dc: Options. (line 149)
-* -dn: Options. (line 713)
-* -dp: Options. (line 149)
-* -dT SCRIPT: Options. (line 488)
-* -dy: Options. (line 696)
-* -E: Options. (line 179)
-* -e ENTRY: Options. (line 158)
-* -EB: Options. (line 198)
-* -EL: Options. (line 201)
-* -F: Options. (line 226)
-* -f: Options. (line 205)
-* -fini: Options. (line 250)
-* -G: Options. (line 259)
-* -g: Options. (line 256)
-* -hNAME: Options. (line 267)
-* -i: Options. (line 276)
-* -IFILE: Options. (line 829)
-* -init: Options. (line 279)
-* -LDIR: Options. (line 318)
-* -lNAMESPEC: Options. (line 285)
-* -M: Options. (line 350)
-* -m EMULATION: Options. (line 340)
-* -Map: Options. (line 873)
-* -N: Options. (line 392)
-* -n: Options. (line 387)
-* -non_shared: Options. (line 713)
-* -nostdlib: Options. (line 953)
-* -O LEVEL: Options. (line 413)
-* -o OUTPUT: Options. (line 407)
-* -pie: Options. (line 972)
-* -q: Options. (line 423)
-* -qmagic: Options. (line 982)
-* -Qy: Options. (line 985)
-* -r: Options. (line 436)
-* -R FILE: Options. (line 455)
-* -rpath: Options. (line 1023)
-* -rpath-link: Options. (line 1045)
-* -S: Options. (line 470)
-* -s: Options. (line 466)
-* -shared: Options. (line 1100)
-* -soname=NAME: Options. (line 267)
-* -static: Options. (line 713)
-* -t: Options. (line 475)
-* -T SCRIPT: Options. (line 479)
-* -Tbss ORG: Options. (line 1170)
-* -Tdata ORG: Options. (line 1170)
-* -Ttext ORG: Options. (line 1170)
-* -u SYMBOL: Options. (line 501)
-* -Ur: Options. (line 509)
-* -V: Options. (line 528)
-* -v: Options. (line 528)
-* -X: Options. (line 538)
-* -x: Options. (line 534)
-* -Y PATH: Options. (line 553)
-* -y SYMBOL: Options. (line 544)
-* -z defs: Options. (line 884)
-* -z KEYWORD: Options. (line 557)
-* -z muldefs: Options. (line 892)
-* .: Location Counter. (line 6)
-* /DISCARD/: Output Section Discarding.
- (line 21)
-* :PHDR: Output Section Phdr.
- (line 6)
-* =FILLEXP: Output Section Fill.
- (line 6)
-* >REGION: Output Section Region.
- (line 6)
-* [COMMON]: Input Section Common.
- (line 29)
-* ABSOLUTE (MRI): MRI. (line 33)
-* absolute and relocatable symbols: Expression Section. (line 6)
-* absolute expressions: Expression Section. (line 6)
-* ABSOLUTE(EXP): Builtin Functions. (line 10)
-* ADDR(SECTION): Builtin Functions. (line 17)
-* address, section: Output Section Address.
- (line 6)
-* ALIAS (MRI): MRI. (line 44)
-* ALIGN (MRI): MRI. (line 50)
-* align expression: Builtin Functions. (line 36)
-* align location counter: Builtin Functions. (line 36)
-* ALIGN(ALIGN): Builtin Functions. (line 36)
-* ALIGN(EXP,ALIGN): Builtin Functions. (line 36)
-* ALIGN(SECTION_ALIGN): Forced Output Alignment.
- (line 6)
-* ALIGNOF(SECTION): Builtin Functions. (line 62)
-* allocating memory: MEMORY. (line 6)
-* architecture: Miscellaneous Commands.
- (line 46)
-* architectures: Options. (line 103)
-* archive files, from cmd line: Options. (line 285)
-* archive search path in linker script: File Commands. (line 71)
-* arithmetic: Expressions. (line 6)
-* arithmetic operators: Operators. (line 6)
-* ARM interworking support: ARM. (line 6)
-* AS_NEEDED(FILES): File Commands. (line 51)
-* ASSERT: Miscellaneous Commands.
- (line 9)
-* assertion in linker script: Miscellaneous Commands.
- (line 9)
-* assignment in scripts: Assignments. (line 6)
-* AT(LMA): Output Section LMA. (line 6)
-* AT>LMA_REGION: Output Section LMA. (line 6)
-* automatic data imports: WIN32. (line 170)
-* back end: BFD. (line 6)
-* BASE (MRI): MRI. (line 54)
-* BE8: ARM. (line 23)
-* BFD canonical format: Canonical format. (line 11)
-* BFD requirements: BFD. (line 16)
-* big-endian objects: Options. (line 198)
-* binary input format: Options. (line 115)
-* BLOCK(EXP): Builtin Functions. (line 75)
-* bug criteria: Bug Criteria. (line 6)
-* bug reports: Bug Reporting. (line 6)
-* bugs in ld: Reporting Bugs. (line 6)
-* BYTE(EXPRESSION): Output Section Data.
- (line 6)
-* C++ constructors, arranging in link: Output Section Keywords.
- (line 19)
-* CHIP (MRI): MRI. (line 58)
-* COLLECT_NO_DEMANGLE: Environment. (line 29)
-* combining symbols, warnings on: Options. (line 1218)
-* command files: Scripts. (line 6)
-* command line: Options. (line 6)
-* common allocation: Options. (line 149)
-* common allocation in linker script: Miscellaneous Commands.
- (line 20)
-* common symbol placement: Input Section Common.
- (line 6)
-* compatibility, MRI: Options. (line 139)
-* constants in linker scripts: Constants. (line 6)
-* CONSTRUCTORS: Output Section Keywords.
- (line 19)
-* constructors: Options. (line 509)
-* constructors, arranging in link: Output Section Keywords.
- (line 19)
-* crash of linker: Bug Criteria. (line 9)
-* CREATE_OBJECT_SYMBOLS: Output Section Keywords.
- (line 9)
-* creating a DEF file: WIN32. (line 137)
-* cross reference table: Options. (line 775)
-* cross references: Miscellaneous Commands.
- (line 30)
-* current output location: Location Counter. (line 6)
-* data: Output Section Data.
- (line 6)
-* DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE): Builtin Functions.
- (line 80)
-* DATA_SEGMENT_END(EXP): Builtin Functions. (line 101)
-* DATA_SEGMENT_RELRO_END(OFFSET, EXP): Builtin Functions. (line 107)
-* dbx: Options. (line 1154)
-* DEF files, creating: Options. (line 1577)
-* default emulation: Environment. (line 21)
-* default input format: Environment. (line 9)
-* DEFINED(SYMBOL): Builtin Functions. (line 118)
-* deleting local symbols: Options. (line 534)
-* demangling, default: Environment. (line 29)
-* demangling, from command line: Options. (line 816)
-* direct linking to a dll: WIN32. (line 218)
-* discarding sections: Output Section Discarding.
- (line 6)
-* discontinuous memory: MEMORY. (line 6)
-* DLLs, creating: Options. (line 1483)
-* DLLs, linking to: Options. (line 1608)
-* dot: Location Counter. (line 6)
-* dot inside sections: Location Counter. (line 36)
-* dot outside sections: Location Counter. (line 66)
-* dynamic linker, from command line: Options. (line 829)
-* dynamic symbol table: Options. (line 179)
-* ELF program headers: PHDRS. (line 6)
-* emulation: Options. (line 340)
-* emulation, default: Environment. (line 21)
-* END (MRI): MRI. (line 62)
-* endianness: Options. (line 198)
-* entry point: Entry Point. (line 6)
-* entry point, from command line: Options. (line 158)
-* entry point, thumb: ARM. (line 17)
-* ENTRY(SYMBOL): Entry Point. (line 6)
-* error on valid input: Bug Criteria. (line 12)
-* example of linker script: Simple Example. (line 6)
-* exporting DLL symbols: WIN32. (line 19)
-* expression evaluation order: Evaluation. (line 6)
-* expression sections: Expression Section. (line 6)
-* expression, absolute: Builtin Functions. (line 10)
-* expressions: Expressions. (line 6)
-* EXTERN: Miscellaneous Commands.
- (line 13)
-* fatal signal: Bug Criteria. (line 9)
-* file name wildcard patterns: Input Section Wildcards.
- (line 6)
-* FILEHDR: PHDRS. (line 61)
-* filename symbols: Output Section Keywords.
- (line 9)
-* fill pattern, entire section: Output Section Fill.
- (line 6)
-* FILL(EXPRESSION): Output Section Data.
- (line 39)
-* finalization function: Options. (line 250)
-* first input file: File Commands. (line 79)
-* first instruction: Entry Point. (line 6)
-* FIX_V4BX: ARM. (line 44)
-* FORCE_COMMON_ALLOCATION: Miscellaneous Commands.
- (line 20)
-* forcing input section alignment: Forced Input Alignment.
- (line 6)
-* forcing output section alignment: Forced Output Alignment.
- (line 6)
-* forcing the creation of dynamic sections: Options. (line 432)
-* FORMAT (MRI): MRI. (line 66)
-* functions in expressions: Builtin Functions. (line 6)
-* garbage collection <1>: Input Section Keep. (line 6)
-* garbage collection: Options. (line 848)
-* generating optimized output: Options. (line 413)
-* GNU linker: Overview. (line 6)
-* GNUTARGET: Environment. (line 9)
-* GROUP(FILES): File Commands. (line 44)
-* grouping input files: File Commands. (line 44)
-* groups of archives: Options. (line 643)
-* H8/300 support: H8/300. (line 6)
-* header size: Builtin Functions. (line 183)
-* heap size: Options. (line 1519)
-* help: Options. (line 865)
-* holes: Location Counter. (line 12)
-* holes, filling: Output Section Data.
- (line 39)
-* HPPA multiple sub-space stubs: HPPA ELF32. (line 6)
-* HPPA stub grouping: HPPA ELF32. (line 12)
-* i960 support: i960. (line 6)
-* image base: Options. (line 1526)
-* implicit linker scripts: Implicit Linker Scripts.
- (line 6)
-* import libraries: WIN32. (line 10)
-* INCLUDE FILENAME: File Commands. (line 9)
-* including a linker script: File Commands. (line 9)
-* including an entire archive: Options. (line 1328)
-* incremental link: Options. (line 276)
-* INHIBIT_COMMON_ALLOCATION: Miscellaneous Commands.
- (line 25)
-* initialization function: Options. (line 279)
-* initialized data in ROM: Output Section LMA. (line 26)
-* input file format in linker script: Format Commands. (line 35)
-* input filename symbols: Output Section Keywords.
- (line 9)
-* input files in linker scripts: File Commands. (line 16)
-* input files, displaying: Options. (line 475)
-* input format: Options. (line 115)
-* input object files in linker scripts: File Commands. (line 16)
-* input section alignment: Forced Input Alignment.
- (line 6)
-* input section basics: Input Section Basics.
- (line 6)
-* input section wildcards: Input Section Wildcards.
- (line 6)
-* input sections: Input Section. (line 6)
-* INPUT(FILES): File Commands. (line 16)
-* integer notation: Constants. (line 6)
-* integer suffixes: Constants. (line 12)
-* internal object-file format: Canonical format. (line 11)
-* invalid input: Bug Criteria. (line 14)
-* K and M integer suffixes: Constants. (line 12)
-* KEEP: Input Section Keep. (line 6)
-* l =: MEMORY. (line 72)
-* lazy evaluation: Evaluation. (line 6)
-* ld bugs, reporting: Bug Reporting. (line 6)
-* LDEMULATION: Environment. (line 21)
-* len =: MEMORY. (line 72)
-* LENGTH =: MEMORY. (line 72)
-* LENGTH(MEMORY): Builtin Functions. (line 135)
-* library search path in linker script: File Commands. (line 71)
-* link map: Options. (line 350)
-* link-time runtime library search path: Options. (line 1045)
-* linker crash: Bug Criteria. (line 9)
-* linker script concepts: Basic Script Concepts.
- (line 6)
-* linker script example: Simple Example. (line 6)
-* linker script file commands: File Commands. (line 6)
-* linker script format: Script Format. (line 6)
-* linker script input object files: File Commands. (line 16)
-* linker script simple commands: Simple Commands. (line 6)
-* linker scripts: Scripts. (line 6)
-* LIST (MRI): MRI. (line 77)
-* little-endian objects: Options. (line 201)
-* LOAD (MRI): MRI. (line 84)
-* load address: Output Section LMA. (line 6)
-* LOADADDR(SECTION): Builtin Functions. (line 138)
-* loading, preventing: Output Section Type.
- (line 22)
-* local symbols, deleting: Options. (line 538)
-* location counter: Location Counter. (line 6)
-* LONG(EXPRESSION): Output Section Data.
- (line 6)
-* M and K integer suffixes: Constants. (line 12)
-* M68HC11 and 68HC12 support: M68HC11/68HC12. (line 6)
-* machine architecture: Miscellaneous Commands.
- (line 46)
-* machine dependencies: Machine Dependent. (line 6)
-* mapping input sections to output sections: Input Section. (line 6)
-* MAX: Builtin Functions. (line 143)
-* MEMORY: MEMORY. (line 6)
-* memory region attributes: MEMORY. (line 32)
-* memory regions: MEMORY. (line 6)
-* memory regions and sections: Output Section Region.
- (line 6)
-* memory usage: Options. (line 877)
-* MIN: Builtin Functions. (line 146)
-* MRI compatibility: MRI. (line 6)
-* MSP430 extra sections: MSP430. (line 11)
-* NAME (MRI): MRI. (line 90)
-* name, section: Output Section Name.
- (line 6)
-* names: Symbols. (line 6)
-* naming the output file: Options. (line 407)
-* NEXT(EXP): Builtin Functions. (line 150)
-* NMAGIC: Options. (line 387)
-* NO_ENUM_SIZE_WARNING: ARM. (line 94)
-* NOCROSSREFS(SECTIONS): Miscellaneous Commands.
- (line 30)
-* NOLOAD: Output Section Type.
- (line 22)
-* not enough room for program headers: Builtin Functions. (line 188)
-* o =: MEMORY. (line 67)
-* objdump -i: BFD. (line 6)
-* object file management: BFD. (line 6)
-* object files: Options. (line 29)
-* object formats available: BFD. (line 6)
-* object size: Options. (line 259)
-* OMAGIC: Options. (line 392)
-* opening object files: BFD outline. (line 6)
-* operators for arithmetic: Operators. (line 6)
-* options: Options. (line 6)
-* ORDER (MRI): MRI. (line 95)
-* org =: MEMORY. (line 67)
-* ORIGIN =: MEMORY. (line 67)
-* ORIGIN(MEMORY): Builtin Functions. (line 156)
-* orphan: Orphan Sections. (line 6)
-* output file after errors: Options. (line 947)
-* output file format in linker script: Format Commands. (line 10)
-* output file name in linker script: File Commands. (line 61)
-* output section alignment: Forced Output Alignment.
- (line 6)
-* output section attributes: Output Section Attributes.
- (line 6)
-* output section data: Output Section Data.
- (line 6)
-* OUTPUT(FILENAME): File Commands. (line 61)
-* OUTPUT_ARCH(BFDARCH): Miscellaneous Commands.
- (line 46)
-* OUTPUT_FORMAT(BFDNAME): Format Commands. (line 10)
-* OVERLAY: Overlay Description.
- (line 6)
-* overlays: Overlay Description.
- (line 6)
-* partial link: Options. (line 436)
-* PHDRS: PHDRS. (line 6)
-* PIC_VENEER: M68HC11/68HC12. (line 38)
-* position independent executables: Options. (line 974)
-* PowerPC ELF32 options: PowerPC ELF32. (line 13)
-* PowerPC GOT: PowerPC ELF32. (line 30)
-* PowerPC long branches: PowerPC ELF32. (line 6)
-* PowerPC PLT: PowerPC ELF32. (line 13)
-* PowerPC stub symbols: PowerPC ELF32. (line 44)
-* PowerPC TLS optimization: PowerPC ELF32. (line 48)
-* PowerPC64 dot symbols: PowerPC64 ELF64. (line 33)
-* PowerPC64 ELF64 options: PowerPC64 ELF64. (line 6)
-* PowerPC64 multi-TOC: PowerPC64 ELF64. (line 74)
-* PowerPC64 OPD optimization: PowerPC64 ELF64. (line 48)
-* PowerPC64 OPD spacing: PowerPC64 ELF64. (line 54)
-* PowerPC64 stub grouping: PowerPC64 ELF64. (line 6)
-* PowerPC64 stub symbols: PowerPC64 ELF64. (line 29)
-* PowerPC64 TLS optimization: PowerPC64 ELF64. (line 43)
-* PowerPC64 TOC optimization: PowerPC64 ELF64. (line 60)
-* precedence in expressions: Operators. (line 6)
-* prevent unnecessary loading: Output Section Type.
- (line 22)
-* program headers: PHDRS. (line 6)
-* program headers and sections: Output Section Phdr.
- (line 6)
-* program headers, not enough room: Builtin Functions. (line 188)
-* program segments: PHDRS. (line 6)
-* PROVIDE: PROVIDE. (line 6)
-* PROVIDE_HIDDEN: PROVIDE_HIDDEN. (line 6)
-* PUBLIC (MRI): MRI. (line 103)
-* QUAD(EXPRESSION): Output Section Data.
- (line 6)
-* quoted symbol names: Symbols. (line 6)
-* read-only text: Options. (line 387)
-* read/write from cmd line: Options. (line 392)
-* regions of memory: MEMORY. (line 6)
-* relative expressions: Expression Section. (line 6)
-* relaxing addressing modes: Options. (line 988)
-* relaxing on H8/300: H8/300. (line 9)
-* relaxing on i960: i960. (line 31)
-* relaxing on M68HC11: M68HC11/68HC12. (line 12)
-* relaxing on Xtensa: Xtensa. (line 27)
-* relocatable and absolute symbols: Expression Section. (line 6)
-* relocatable output: Options. (line 436)
-* removing sections: Output Section Discarding.
- (line 6)
-* reporting bugs in ld: Reporting Bugs. (line 6)
-* requirements for BFD: BFD. (line 16)
-* retain relocations in final executable: Options. (line 423)
-* retaining specified symbols: Options. (line 1009)
-* ROM initialized data: Output Section LMA. (line 26)
-* round up expression: Builtin Functions. (line 36)
-* round up location counter: Builtin Functions. (line 36)
-* runtime library name: Options. (line 267)
-* runtime library search path: Options. (line 1023)
-* runtime pseudo-relocation: WIN32. (line 196)
-* scaled integers: Constants. (line 12)
-* scommon section: Input Section Common.
- (line 20)
-* script files: Options. (line 479)
-* scripts: Scripts. (line 6)
-* search directory, from cmd line: Options. (line 318)
-* search path in linker script: File Commands. (line 71)
-* SEARCH_DIR(PATH): File Commands. (line 71)
-* SECT (MRI): MRI. (line 109)
-* section address: Output Section Address.
- (line 6)
-* section address in expression: Builtin Functions. (line 17)
-* section alignment: Builtin Functions. (line 62)
-* section alignment, warnings on: Options. (line 1309)
-* section data: Output Section Data.
- (line 6)
-* section fill pattern: Output Section Fill.
- (line 6)
-* section load address: Output Section LMA. (line 6)
-* section load address in expression: Builtin Functions. (line 138)
-* section name: Output Section Name.
- (line 6)
-* section name wildcard patterns: Input Section Wildcards.
- (line 6)
-* section size: Builtin Functions. (line 167)
-* section, assigning to memory region: Output Section Region.
- (line 6)
-* section, assigning to program header: Output Section Phdr.
- (line 6)
-* SECTIONS: SECTIONS. (line 6)
-* sections, discarding: Output Section Discarding.
- (line 6)
-* segment origins, cmd line: Options. (line 1170)
-* SEGMENT_START(SEGMENT, DEFAULT): Builtin Functions. (line 159)
-* segments, ELF: PHDRS. (line 6)
-* shared libraries: Options. (line 1102)
-* SHORT(EXPRESSION): Output Section Data.
- (line 6)
-* SIZEOF(SECTION): Builtin Functions. (line 167)
-* SIZEOF_HEADERS: Builtin Functions. (line 183)
-* small common symbols: Input Section Common.
- (line 20)
-* SORT: Input Section Wildcards.
- (line 58)
-* SORT_BY_ALIGNMENT: Input Section Wildcards.
- (line 54)
-* SORT_BY_NAME: Input Section Wildcards.
- (line 46)
-* SPU: SPU ELF. (line 29)
-* SPU ELF options: SPU ELF. (line 6)
-* SPU extra overlay stubs: SPU ELF. (line 19)
-* SPU local store size: SPU ELF. (line 24)
-* SPU overlay stub symbols: SPU ELF. (line 15)
-* SPU overlays: SPU ELF. (line 9)
-* SPU plugins: SPU ELF. (line 6)
-* SQUAD(EXPRESSION): Output Section Data.
- (line 6)
-* stack size: Options. (line 1760)
-* standard Unix system: Options. (line 7)
-* start of execution: Entry Point. (line 6)
-* STARTUP(FILENAME): File Commands. (line 79)
-* strip all symbols: Options. (line 466)
-* strip debugger symbols: Options. (line 470)
-* stripping all but some symbols: Options. (line 1009)
-* SUBALIGN(SUBSECTION_ALIGN): Forced Input Alignment.
- (line 6)
-* suffixes for integers: Constants. (line 12)
-* symbol defaults: Builtin Functions. (line 118)
-* symbol definition, scripts: Assignments. (line 6)
-* symbol names: Symbols. (line 6)
-* symbol tracing: Options. (line 544)
-* symbol versions: VERSION. (line 6)
-* symbol-only input: Options. (line 455)
-* symbols, from command line: Options. (line 803)
-* symbols, relocatable and absolute: Expression Section. (line 6)
-* symbols, retaining selectively: Options. (line 1009)
-* synthesizing linker: Options. (line 988)
-* synthesizing on H8/300: H8/300. (line 14)
-* TARGET(BFDNAME): Format Commands. (line 35)
-* TARGET1: ARM. (line 27)
-* TARGET2: ARM. (line 32)
-* thumb entry point: ARM. (line 17)
-* TI COFF versions: TI COFF. (line 6)
-* traditional format: Options. (line 1149)
-* trampoline generation on M68HC11: M68HC11/68HC12. (line 31)
-* trampoline generation on M68HC12: M68HC11/68HC12. (line 31)
-* unallocated address, next: Builtin Functions. (line 150)
-* undefined symbol: Options. (line 501)
-* undefined symbol in linker script: Miscellaneous Commands.
- (line 13)
-* undefined symbols, warnings on: Options. (line 1305)
-* uninitialized data placement: Input Section Common.
- (line 6)
-* unspecified memory: Output Section Data.
- (line 39)
-* usage: Options. (line 865)
-* USE_BLX: ARM. (line 57)
-* using a DEF file: WIN32. (line 42)
-* using auto-export functionality: WIN32. (line 22)
-* Using decorations: WIN32. (line 141)
-* variables, defining: Assignments. (line 6)
-* verbose: Options. (line 1205)
-* version: Options. (line 528)
-* version script: VERSION. (line 6)
-* version script, symbol versions: Options. (line 1211)
-* VERSION {script text}: VERSION. (line 6)
-* versions of symbols: VERSION. (line 6)
-* VFP11_DENORM_FIX: ARM. (line 66)
-* warnings, on combining symbols: Options. (line 1218)
-* warnings, on section alignment: Options. (line 1309)
-* warnings, on undefined symbols: Options. (line 1305)
-* weak externals: WIN32. (line 386)
-* what is this?: Overview. (line 6)
-* wildcard file name patterns: Input Section Wildcards.
- (line 6)
-* Xtensa options: Xtensa. (line 56)
-* Xtensa processors: Xtensa. (line 6)
-
-
-\1f
-Tag Table:
-Node: Top\7f750
-Node: Overview\7f1524
-Node: Invocation\7f2638
-Node: Options\7f3046
-Node: Environment\7f83631
-Node: Scripts\7f85391
-Node: Basic Script Concepts\7f87125
-Node: Script Format\7f89832
-Node: Simple Example\7f90695
-Node: Simple Commands\7f93791
-Node: Entry Point\7f94242
-Node: File Commands\7f95001
-Node: Format Commands\7f98867
-Node: Miscellaneous Commands\7f100833
-Node: Assignments\7f103063
-Node: Simple Assignments\7f103554
-Node: PROVIDE\7f105290
-Node: PROVIDE_HIDDEN\7f106495
-Node: Source Code Reference\7f106739
-Node: SECTIONS\7f110319
-Node: Output Section Description\7f112210
-Node: Output Section Name\7f113263
-Node: Output Section Address\7f114139
-Node: Input Section\7f115788
-Node: Input Section Basics\7f116589
-Node: Input Section Wildcards\7f118939
-Node: Input Section Common\7f123672
-Node: Input Section Keep\7f125154
-Node: Input Section Example\7f125644
-Node: Output Section Data\7f126612
-Node: Output Section Keywords\7f129389
-Node: Output Section Discarding\7f132958
-Node: Output Section Attributes\7f134139
-Node: Output Section Type\7f135143
-Node: Output Section LMA\7f136297
-Node: Forced Output Alignment\7f138810
-Node: Forced Input Alignment\7f139078
-Node: Output Section Region\7f139463
-Node: Output Section Phdr\7f139893
-Node: Output Section Fill\7f140557
-Node: Overlay Description\7f141699
-Node: MEMORY\7f146002
-Node: PHDRS\7f150202
-Node: VERSION\7f155241
-Node: Expressions\7f163033
-Node: Constants\7f163911
-Node: Symbols\7f164472
-Node: Orphan Sections\7f165210
-Node: Location Counter\7f165973
-Node: Operators\7f170409
-Node: Evaluation\7f171331
-Node: Expression Section\7f172695
-Node: Builtin Functions\7f174184
-Node: Implicit Linker Scripts\7f182151
-Node: Machine Dependent\7f182926
-Node: H8/300\7f183897
-Node: i960\7f185522
-Node: M68HC11/68HC12\7f187207
-Node: ARM\7f188910
-Node: HPPA ELF32\7f193760
-Node: MMIX\7f195383
-Node: MSP430\7f196600
-Node: PowerPC ELF32\7f197649
-Node: PowerPC64 ELF64\7f200263
-Node: SPU ELF\7f204677
-Node: TI COFF\7f207309
-Node: WIN32\7f207835
-Node: Xtensa\7f226192
-Node: BFD\7f229314
-Node: BFD outline\7f230769
-Node: BFD information loss\7f232055
-Node: Canonical format\7f234572
-Node: Reporting Bugs\7f238929
-Node: Bug Criteria\7f239623
-Node: Bug Reporting\7f240322
-Node: MRI\7f247361
-Node: GNU Free Documentation License\7f252004
-Node: LD Index\7f271721
-\1f
-End Tag Table
projects / msp430-binutils.git / commitdiff