X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gas%2Fdoc%2Finternals.texi;h=cb86b5b3629ec64a48b3b2d21bd464e49b73fa4f;hb=b65d68b8d60338a860e169aac3bac54e6bac60db;hp=ff1df989e5367b8691b2d98e525e9b75e623c3a5;hpb=499ac353610f24006acf82c32503d8d15d0f278c;p=deliverable%2Fbinutils-gdb.git diff --git a/gas/doc/internals.texi b/gas/doc/internals.texi index ff1df989e5..cb86b5b362 100644 --- a/gas/doc/internals.texi +++ b/gas/doc/internals.texi @@ -1,7 +1,5 @@ \input texinfo -@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006 -@c Free Software Foundation, Inc. +@c Copyright (C) 1991-2019 Free Software Foundation, Inc. @setfilename internals.info @node Top @top Assembler Internals @@ -43,11 +41,10 @@ This section describes some fundamental GAS data types. @cindex symbolS structure The definition for the symbol structure, @code{symbolS}, is located in -@file{struc-symbol.h}. +@file{symbols.c}. -In general, the fields of this structure may not be referred to directly. +The fields of this structure may not be referred to directly. Instead, you must use one of the accessor functions defined in @file{symbol.h}. -These accessor functions should work for any GAS version. Symbol structures contain the following fields: @@ -153,10 +150,6 @@ Set the name of the symbol. @cindex S_IS_EXTERNAL Return non-zero if the symbol is externally visible. -@item S_IS_EXTERN -@cindex S_IS_EXTERN -A synonym for @code{S_IS_EXTERNAL}. Don't use it. - @item S_IS_WEAK @cindex S_IS_WEAK Return non-zero if the symbol is weak, or if it is a @code{weakref} alias or @@ -252,8 +245,8 @@ Indicate that the symbol is a forward reference, that is its value must only be determined upon use. @item S_GET_TYPE -@item S_GET_DESC -@item S_GET_OTHER +@itemx S_GET_DESC +@itemx S_GET_OTHER @cindex S_GET_TYPE @cindex S_GET_DESC @cindex S_GET_OTHER @@ -262,8 +255,8 @@ are only defined for object file formats for which they make sense (primarily a.out). @item S_SET_TYPE -@item S_SET_DESC -@item S_SET_OTHER +@itemx S_SET_DESC +@itemx S_SET_OTHER @cindex S_SET_TYPE @cindex S_SET_DESC @cindex S_SET_OTHER @@ -404,12 +397,6 @@ deal with local symbols. @code{struct local_symbol} is much smaller than @code{symbolS} (which also automatically creates a bfd @code{asymbol} structure), so this saves space when assembling large files. -The first field of @code{symbolS} is @code{bsym}, the pointer to the BFD -symbol. The first field of @code{struct local_symbol} is a pointer which is -always set to NULL. This is how the symbol accessor functions can distinguish -local symbols from ordinary symbols. The symbol accessor functions -automatically convert a local symbol into an ordinary symbol when necessary. - @node Expressions @subsection Expressions @cindex internals, expressions @@ -732,7 +719,7 @@ all the fixups (@code{fixup_segment}), resolves all the symbol values (using @cindex porting Each GAS target specifies two main things: the CPU file and the object format -file. Two main switches in the @file{configure.in} file handle this. The +file. Two main switches in the @file{configure.ac} file handle this. The first switches on CPU type to set the shell variable @code{cpu_type}. The second switches on the entire target to set the shell variable @code{fmt}. @@ -886,6 +873,8 @@ comment. @item tc_comment_chars @cindex tc_comment_chars If this macro is defined, GAS will use it instead of @code{comment_chars}. +This has the advantage that this macro does not have to refer to a constant +array. @item tc_symbol_chars @cindex tc_symbol_chars @@ -910,6 +899,13 @@ listed in this array). Note that line_separator_chars do not separate lines if found in a comment, such as after a character in line_comment_chars or comment_chars. +@item tc_line_separator_chars +@cindex tc_line_separator_chars +If this macro is defined, GAS will use it instead of +@code{line_separator_chars}. This has the advantage that this macro does not +have to refer to a constant array. + + @item EXP_CHARS @cindex EXP_CHARS This is a null terminated @code{const char} array of characters which may be @@ -1093,11 +1089,6 @@ You may define this macro to parse an expression used in a data allocation pseudo-op such as @code{.word}. You can use this to recognize relocation directives that may appear in such directives. -@item BITFIELD_CONS_EXPRESSION -@cindex BITFIELD_CONS_EXPRESSION -If you define this macro, GAS will recognize bitfield instructions in data -allocation pseudo-ops, as used on the i960. - @item REPEAT_CONS_EXPRESSION @cindex REPEAT_CONS_EXPRESSION If you define this macro, GAS will recognize repeat counts in data allocation @@ -1127,10 +1118,11 @@ These fields are defined with the @code{TC_FIX_TYPE} macro. A C statement to output target specific debugging information for fixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}. -@item TC_FRAG_INIT (@var{fragp}) +@item TC_FRAG_INIT (@var{fragp}, @var{max_bytes}) @cindex TC_FRAG_INIT -A C statement to initialize the target specific fields of frag @var{fragp}. -These fields are defined with the @code{TC_FRAG_TYPE} macro. +A C statement to initialize the target specific fields of frag @var{fragp} +with maximum number of bytes @var{max_bytes}. These fields are defined +with the @code{TC_FRAG_TYPE} macro. @item md_number_to_chars @cindex md_number_to_chars @@ -1145,7 +1137,7 @@ simple macro. This function is called to convert an ASCII string into a floating point value in format used by the CPU. It takes three arguments. The first is @var{type} which is a byte describing the type of floating point number to be created. It -is one of the characters defined in the @xref{FLT_CHARS} macro. Possible +is one of the characters defined in the @code{FLT_CHARS} macro. Possible values are @var{'f'} or @var{'s'} for single precision, @var{'d'} or @var{'r'} for double precision and @var{'x'} or @var{'p'} for extended precision. Either lower or upper case versions of these letters can be used. Note: some targets @@ -1218,6 +1210,11 @@ If you do not define @code{md_relax_frag}, you may define machine independent code knows how to use such a table to relax PC relative references. See @file{tc-m68k.c} for an example. @xref{Relaxation}. +@item md_generic_table_relax_frag +@cindex md_generic_table_relax_frag +If defined, it is a C statement that is invoked, instead of +the default implementation, to scan @code{TC_GENERIC_RELAX_TABLE}. + @item md_prepare_relax_scan @cindex md_prepare_relax_scan If defined, it is a C statement that is invoked prior to scanning @@ -1226,7 +1223,7 @@ the relax table. @item LINKER_RELAXING_SHRINKS_ONLY @cindex LINKER_RELAXING_SHRINKS_ONLY If you define this macro, and the global variable @samp{linkrelax} is set -(because of a command line option, or unconditionally in @code{md_begin}), a +(because of a command-line option, or unconditionally in @code{md_begin}), a @samp{.align} directive will cause extra space to be allocated. The linker can then discard this space when relaxing the section. @@ -1250,7 +1247,7 @@ It may also create any necessary relocations. @cindex TC_FINALIZE_SYMS_BEFORE_SIZE_SEG Specifies the value to be assigned to @code{finalize_syms} before the function @code{size_segs} is called. Since @code{size_segs} calls @code{cvt_frag_to_fill} -which can call @code{md_convert_frag}, this constant governs whether the symbols +which can call @code{md_convert_frag}, this constant governs whether the symbols accessed in @code{md_convert_frag} will be fully resolved. In particular it governs whether local symbols will have been resolved, and had their frag information removed. Depending upon the processing performed by @@ -1306,25 +1303,29 @@ This macro controls resolution of fixup expressions involving the difference of two symbols in the same section. If this macro returns zero, the subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for @code{md_apply_fix}. If undefined, the default of -@w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will -be used. +@w{@code{! SEG_NORMAL (@var{seg})}} will be used. -@item TC_FORCE_RELOCATION_SUB_ABS (@var{fix}) +@item TC_FORCE_RELOCATION_SUB_ABS (@var{fix}, @var{seg}) @cindex TC_FORCE_RELOCATION_SUB_ABS Like @code{TC_FORCE_RELOCATION_SUB_SAME}, but used when the subtrahend is an absolute symbol. If the macro is undefined a default of @code{0} is used. -@item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix}) +@item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix}, @var{seg}) @cindex TC_FORCE_RELOCATION_SUB_LOCAL Like @code{TC_FORCE_RELOCATION_SUB_ABS}, but the subtrahend is a symbol in the same section as the fixup. -@item TC_VALIDATE_FIX_SUB (@var{fix}) +@item TC_VALIDATE_FIX_SUB (@var{fix}, @var{seg}) @cindex TC_VALIDATE_FIX_SUB This macro is evaluated for any fixup with a @code{fx_subsy} that @code{fixup_segment} cannot reduce to a number. If the macro returns @code{false} an error will be reported. +@item TC_GLOBAL_REGISTER_SYMBOL_OK +@cindex TC_GLOBAL_REGISTER_SYMBOL_OK +Define this macro if global register symbols are supported. The default +is to disallow global register symbols. + @item MD_APPLY_SYM_VALUE (@var{fix}) @cindex MD_APPLY_SYM_VALUE This macro controls whether the symbol value becomes part of the value passed @@ -1390,6 +1391,11 @@ that @code{md_pcrel_from} does not take a section argument. @cindex tc_frob_label If you define this macro, GAS will call it each time a label is defined. +@item tc_new_dot_label +@cindex tc_new_dot_label +If you define this macro, GAS will call it each time a fake label is created +off the special dot symbol. + @item md_section_align @cindex md_section_align GAS will call this function for each section at the end of the assembly, to @@ -1457,6 +1463,12 @@ completed, but before the relocations have been generated. If you define this macro, GAS will call it after the relocs have been generated. +@item tc_cfi_reloc_for_encoding +@cindex tc_cfi_reloc_for_encoding +This macro is used to indicate whether a cfi encoding requires a relocation. +It should return the required relocation type. Defining this macro implies +that Compact EH is supported. + @item md_post_relax_hook If you define this macro, GAS will call it after relaxing and sizing the segments. @@ -1494,7 +1506,7 @@ The COFF @code{.section} directive will use the value of this macro to set a new section's attributes when a directive has no valid flags or when the flag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}. -@item DWARF2_FORMAT () +@item DWARF2_FORMAT (@var{sec}) @cindex DWARF2_FORMAT If you define this, it should return one of @code{dwarf2_format_32bit}, @code{dwarf2_format_64bit}, or @code{dwarf2_format_64bit_irix} to indicate @@ -1511,7 +1523,7 @@ the section's length. If you don't define this, @code{dwarf2_format_32bit} will be used as the default. -This define only affects @code{.debug_info} and @code{.debug_line} +This define only affects debug sections generated by the assembler. DWARF 2 sections generated by other tools will be unaffected by this setting. @@ -1535,6 +1547,23 @@ The function should return the debug format that is preferred by the CPU backend. This format will be used when generating assembler specific debug information. +@item md_allow_local_subtract (@var{left}, @var{right}, @var{section}) +If defined, GAS will call this macro when evaluating an expression which is the +difference of two symbols defined in the same section. It takes three +arguments: @code{expressioS * @var{left}} which is the symbolic expression on +the left hand side of the subtraction operation, @code{expressionS * +@var{right}} which is the symbolic expression on the right hand side of the +subtraction, and @code{segT @var{section}} which is the section containing the two +symbols. The macro should return a non-zero value if the expression should be +evaluated. Targets which implement link time relaxation which may change the +position of the two symbols relative to each other should ensure that this +macro returns zero in situations where this can occur. + +@item md_allow_eh_opt +If defined, GAS will check this macro before performing any optimizations on +the DWARF call frame debug information that is emitted. Targets which +implement link time relaxation may need to define this macro and set it to zero +if it is possible to change the size of a function's prologue. @end table @node Object format backend @@ -1558,7 +1587,7 @@ if it is necessary to add object file format specific code to the CPU file. @item obj_begin If you define this macro, GAS will call it at the start of the assembly, after -the command line arguments have been parsed and all the machine independent +the command-line arguments have been parsed and all the machine independent initializations have been completed. @item obj_app_file @@ -1718,12 +1747,6 @@ no-op instructions, it must be able to expand or shrink the section contents while still preserving intra-section references and meeting alignment requirements. -For the i960 using b.out format, no expansion is done; instead, each -@samp{.align} directive causes extra space to be allocated, enough that when -the linker is relaxing a section and removing unneeded space, it can discard -some or all of this extra padding and cause the following data to be correctly -aligned. - For the H8/300, I think the linker expands calls that can't reach, and doesn't worry about alignment issues; the cpu probably never needs any significant alignment beyond the instruction size. @@ -1904,21 +1927,23 @@ Creates the hash table control structure. Destroy a hash table. @end deftypefun -@deftypefun @{@} PTR hash_delete (struct hash_control *, const char *) -Deletes entry from the hash table, returns the value it had. +@deftypefun @{@} void *hash_delete (struct hash_control *, const char *, int) +Deletes entry from the hash table, returns the value it had. If the last +arg is non-zero, free memory allocated for this entry and all entries +allocated more recently than this entry. @end deftypefun -@deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR) +@deftypefun @{@} void *hash_replace (struct hash_control *, const char *, void *) Updates the value for an entry already in the table, returning the old value. If no entry was found, just returns NULL. @end deftypefun -@deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR) +@deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, void *) Inserting a value already in the table is an error. Returns an error message or NULL. @end deftypefun -@deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR) +@deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, void *) Inserts if the value isn't already present, updates it if it is. @end deftypefun