X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=gas%2Fdoc%2Finternals.texi;h=59b2d3acee59fe31eab6cf8e61a11cbca937c3b0;hb=408520bcaa874edb0e37506e8559b2e4194dca05;hp=b2c8586be8c6f929898fe48e81be4b2c016097a4;hpb=885afe7b6fda4324ac445cfdd9e37630f5061dc0;p=binutils-gdb.git diff --git a/gas/doc/internals.texi b/gas/doc/internals.texi index b2c8586be8c..59b2d3acee5 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-2022 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 @@ -1038,6 +1034,12 @@ Predefined symbols with fixed values, such as register names or condition codes, are typically entered directly into the symbol table when @code{md_begin} is called. One argument is passed, a @code{char *} for the symbol. +@item md_resolve_symbol +@cindex md_resolve_symbol +If this macro is defined, GAS will call it upon resolving machine-dependent +symbols (that is, for any symbol with operation O_md1..O_md32 inclusively). +If this functions returns zero, then the symbol could not be resolved. + @item md_operand @cindex md_operand GAS will call this function with one argument, an @code{expressionS} @@ -1045,6 +1047,16 @@ pointer, for any expression that can not be recognized. When the function is called, @code{input_line_pointer} will point to the start of the expression. +@item md_register_arithmetic +@cindex md_register_arithmetic +If this macro is defined and evaluates to zero then GAS will not fold +expressions that add or subtract a constant to/from a register to give +another register. For example GAS's default behaviour is to fold the +expression "r8 + 1" into "r9", which is probably not the result +intended by the programmer. The default is to allow such folding, +since this maintains backwards compatibility with earlier releases of +GAS. + @item tc_unrecognized_line @cindex tc_unrecognized_line If you define this macro, GAS will call it when it finds a line that it can not @@ -1083,11 +1095,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 @@ -1105,7 +1112,8 @@ You may define this macro to generate a fixup for a data allocation pseudo-op. @item TC_ADDRESS_BYTES @cindex TC_ADDRESS_BYTES Define this macro to specify the number of bytes used to store an address. -Used to implement @code{dc.a}. The target must have a reloc for this size. +Used to implement @code{dc.a}. If not defined by the target, a default will +be supplied. Targets are assumed to have a reloc for this size. @item TC_INIT_FIX_DATA (@var{fixp}) @cindex TC_INIT_FIX_DATA @@ -1117,10 +1125,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 @@ -1134,17 +1143,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}) @@ -1200,6 +1217,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 @@ -1208,7 +1230,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. @@ -1232,7 +1254,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 @@ -1279,7 +1301,7 @@ absolute symbol. If undefined, @code{TC_FORCE_RELOCATION} will be used. @cindex TC_FORCE_RELOCATION_LOCAL Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against a symbol in the current section. If undefined, fixups that are not -@code{fx_pcrel} or @code{fx_plt} or for which @code{TC_FORCE_RELOCATION} +@code{fx_pcrel} or for which @code{TC_FORCE_RELOCATION} returns non-zero, will emit relocs. @item TC_FORCE_RELOCATION_SUB_SAME (@var{fix}, @var{seg}) @@ -1288,25 +1310,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 @@ -1372,6 +1398,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 @@ -1439,6 +1470,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. @@ -1476,7 +1513,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 @@ -1493,7 +1530,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. @@ -1517,6 +1554,33 @@ 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_emit_single_noop_insn +@itemx md_single_noop_insn +These macro facilitate the @var{.nop} directive. If defined the +@var{md_emit_single_noop_insn) macro provides code to insert a single no-op +instruction into the output stream. If this involves calling @var{md_assemble} +with a fixed string then the alternative macro @var{md_single_noop_insn} can be +defined, specifying the string to pass. If neither of these macros are defined +then the @var{.nop} directive will call @var{md_assemble} with the string +@option{nop}. + +@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 @@ -1540,7 +1604,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 @@ -1700,12 +1764,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. @@ -1867,43 +1925,6 @@ after all input has been read, but messages about fixups should refer to the original filename and line number that they are applicable to. @end deftypefun -@deftypefun @{@} void sprint_value (char *@var{buf}, valueT @var{val}) -This function is helpful for converting a @code{valueT} value into printable -format, in case it's wider than modes that @code{*printf} can handle. If the -type is narrow enough, a decimal number will be produced; otherwise, it will be -in hexadecimal. The value itself is not examined to make this determination. -@end deftypefun - -@node Hash tables -@subsection Hash tables -@cindex hash tables - -@deftypefun @{@} @{struct hash_control *@} hash_new (void) -Creates the hash table control structure. -@end deftypefun - -@deftypefun @{@} void hash_die (struct hash_control *) -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. -@end deftypefun - -@deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR) -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) -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) -Inserts if the value isn't already present, updates it if it is. -@end deftypefun - @node Test suite @section Test suite @cindex test suite