X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=gas%2Fdoc%2Finternals.texi;h=59b2d3acee59fe31eab6cf8e61a11cbca937c3b0;hb=408520bcaa874edb0e37506e8559b2e4194dca05;hp=1da6b1f05e6d220be148afa9b3760dfb4298dee3;hpb=adfd7328359958d6ad31521278cc5f44b96ae30c;p=binutils-gdb.git diff --git a/gas/doc/internals.texi b/gas/doc/internals.texi index 1da6b1f05e6..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} @@ -1093,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 @@ -1115,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 @@ -1127,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 @@ -1218,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 @@ -1226,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. @@ -1250,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 @@ -1306,8 +1310,7 @@ 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}, @var{seg}) @cindex TC_FORCE_RELOCATION_SUB_ABS @@ -1395,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 @@ -1462,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. @@ -1540,6 +1554,16 @@ 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 @@ -1580,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 @@ -1740,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. @@ -1907,45 +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 @{@} 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 @{@} 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 *, 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 *, void *) -Inserts if the value isn't already present, updates it if it is. -@end deftypefun - @node Test suite @section Test suite @cindex test suite