[@b{-W}] [@b{--warn}] [@b{--fatal-warnings}] [@b{-w}] [@b{-x}]
[@b{-Z}] [@b{@@@var{FILE}}]
[@b{--sectname-subst}] [@b{--size-check=[error|warning]}]
+ [@b{--elf-stt-common=[no|yes]}]
[@b{--target-help}] [@var{target-options}]
[@b{--}|@var{files} @dots{}]
@c
+@c man end
@c Target dependent options are listed below. Keep the list sorted.
@c Add an empty line for separation.
+@c man begin TARGET
@ifset AARCH64
@emph{Target AArch64 options:}
then debug line section will still be called just @var{.debug_line} without any
suffix.
+@ifset ELF
@item --size-check=error
@itemx --size-check=warning
Issue an error or warning for invalid ELF .size directive.
+@item --elf-stt-common=no
+@itemx --elf-stt-common=yes
+These options control whether the ELF assembler should generate common
+symbols with the @code{STT_COMMON} type. The default can be controlled
+by a configure option @option{--enable-elf-stt-common}.
+@end ifset
+
@item --help
Print a summary of the command line options and exit.
On targets that support compact unwinding tables these can be generated
by specifying @code{.eh_frame_entry} instead of @code{.eh_frame}.
+Some targets may support an additional name, such as @code{.c6xabi.exidx}
+which is used by the @value{TIC6X} target.
+
+The @code{.cfi_sections} directive can be repeated, with the same or different
+arguments, provided that CFI generation has not yet started. Once CFI
+generation has started however the section list is fixed and any attempts to
+redefine it will result in an error.
+
@subsection @code{.cfi_startproc [simple]}
@cindex @code{cfi_startproc} directive
@code{.cfi_startproc} is used at the beginning of each function that
Current value of @var{register} is the same like in the previous frame,
i.e. no restoration needed.
-@subsection @code{.cfi_remember_state},
-First save all current rules for all registers by @code{.cfi_remember_state},
-then totally screw them up by subsequent @code{.cfi_*} directives and when
-everything is hopelessly bad, use @code{.cfi_restore_state} to restore
-the previous saved state.
+@subsection @code{.cfi_remember_state} and @code{.cfi_restore_state}
+@code{.cfi_remember_state} pushes the set of rules for every register onto an
+implicit stack, while @code{.cfi_restore_state} pops them off the stack and
+places them in the current row. This is useful for situations where you have
+multiple @code{.cfi_*} directives that need to be undone due to the control
+flow of the program. For example, we could have something like this (assuming
+the CFA is the value of @code{rbp}):
+
+@smallexample
+ je label
+ popq %rbx
+ .cfi_restore %rbx
+ popq %r12
+ .cfi_restore %r12
+ popq %rbp
+ .cfi_restore %rbp
+ .cfi_def_cfa %rsp, 8
+ ret
+label:
+ /* Do something else */
+@end smallexample
+
+Here, we want the @code{.cfi} directives to affect only the rows corresponding
+to the instructions before @code{label}. This means we'd have to add multiple
+@code{.cfi} directives after @code{label} to recreate the original save
+locations of the registers, as well as setting the CFA back to the value of
+@code{rbp}. This would be clumsy, and result in a larger binary size. Instead,
+we can write:
+
+@smallexample
+ je label
+ popq %rbx
+ .cfi_remember_state
+ .cfi_restore %rbx
+ popq %r12
+ .cfi_restore %r12
+ popq %rbp
+ .cfi_restore %rbp
+ .cfi_def_cfa %rsp, 8
+ ret
+label:
+ .cfi_restore_state
+ /* Do something else */
+@end smallexample
+
+That way, the rules for the instructions after @code{label} will be the same
+as before the first @code{.cfi_restore} without having to use multiple
+@code{.cfi} directives.
@subsection @code{.cfi_return_column @var{register}}
Change return column @var{register}, i.e. the return address is either
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:
+
@table @code
@item b
bss section (uninitialized data)
The optional @var{flags} argument is a quoted string which may contain any
combination of the following characters:
+
@table @code
@item a
section is allocatable
section is used for thread-local-storage
@item ?
section is a member of the previously-current section's group, if any
+@item @code{<number>}
+a numeric value indicating the bits to be set in the ELF section header's flags
+field. Note - if one or more of the alphabetic characters described above is
+also included in the flags field, their bit values will be ORed into the
+resulting value.
+@item @code{<target specific>}
+some targets extend this list with their own flag characters
@end table
+Note - once a section's flags have been set they cannot be changed. There are
+a few exceptions to this rule however. Processor and application specific
+flags can be added to an already defined section. The @code{.interp},
+@code{.strtab} and @code{.symtab} sections can have the allocate flag
+(@code{a}) set after they are initially defined, and the @code{.note-GNU-stack}
+section may have the executable (@code{x}) flag added.
+
The optional @var{type} argument may contain one of the following constants:
+
@table @code
@item @@progbits
section contains data
section contains an array of pointers to finish functions
@item @@preinit_array
section contains an array of pointers to pre-init functions
+@item @@@code{<number>}
+a numeric value to be set as the ELF section header's type field.
+@item @@@code{<target specific>}
+some targets extend this list with their own types
@end table
-Many targets only support the first three section types.
+Many targets only support the first three section types. The type may be
+enclosed in double quotes if necessary.
Note on targets where the @code{@@} character is the start of a comment (eg
ARM) then another character is used instead. For example the ARM port uses the
@code{%} character.
+Note - some sections, eg @code{.text} and @code{.data} are considered to be
+special and have fixed types. Any attempt to declare them with a different
+type will generate an error from the assembler.
+
If @var{flags} contains the @code{M} symbol then the @var{type} argument must
be specified as well as an extra argument---@var{entsize}---like this:
The @var{GroupName} field specifies the name of the section group to which this
particular section belongs. The optional linkage field can contain:
+
@table @code
@item comdat
indicates that only one copy of this section should be retained
Note that the section name is quoted. There may be a sequence of comma
separated flags:
+
@table @code
@item #alloc
section is allocatable
projects / deliverable / binutils-gdb.git / blobdiff