X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gas%2Fdoc%2Finternals.texi;h=f7ae8a407c0cdf44f902c40fa7dd2d2b741bf465;hb=fe779266b39080e49b04e61160e6af8be439c182;hp=a97ead386c58cc01a9a6e47f34d0425df341171e;hpb=5a918ce730bca784591cef4b3696269510c5f814;p=deliverable%2Fbinutils-gdb.git diff --git a/gas/doc/internals.texi b/gas/doc/internals.texi index a97ead386c..f7ae8a407c 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-2016 Free Software Foundation, Inc. @setfilename internals.info @node Top @top Assembler Internals @@ -153,10 +151,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 +246,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 +256,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 @@ -732,7 +726,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 +880,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 +906,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 @@ -1144,17 +1147,25 @@ simple macro. @cindex md_atof 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. -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. +which is a byte describing the type of floating point number to be created. It +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 +do not support all of these types, and some targets may also support other +types not mentioned here. The second parameter is @var{litP} which is a pointer to a byte array where the -converted value should be stored. The third argument is @var{sizeP}, which is -a pointer to a integer that should be filled in with the number of -@var{LITTLENUM}s emitted into the byte array. (@var{LITTLENUM} is defined in -gas/bignum.h). The function should return NULL upon success or an error string -upon failure. +converted value should be stored. The value is converted into LITTLENUMs and +is stored in the target's endian-ness order. (@var{LITTLENUM} is defined in +gas/bignum.h). Single precision values occupy 2 littlenums. Double precision +values occupy 4 littlenums and extended precision values occupy either 5 or 6 +littlenums, depending upon the target. + +The third argument is @var{sizeP}, which is a pointer to a integer that should +be filled in with the number of chars emitted into the byte array. + +The function should return NULL upon success or an error string upon failure. @item TC_LARGEST_EXPONENT_IS_NORMAL @cindex TC_LARGEST_EXPONENT_IS_NORMAL (@var{precision}) @@ -1242,7 +1253,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 @@ -1298,25 +1309,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 @@ -1382,6 +1397,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 @@ -1449,6 +1469,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. @@ -1486,7 +1512,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 @@ -1503,7 +1529,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. @@ -1527,6 +1553,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 @@ -1896,21 +1939,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