as: CFI directives
7.10 CFI directives
===================
7.10.1 '.cfi_sections SECTION_LIST'
-----------------------------------
'.cfi_sections' may be used to specify whether CFI directives should
emit '.eh_frame' section and/or '.debug_frame' section. If SECTION_LIST
is '.eh_frame', '.eh_frame' is emitted, if SECTION_LIST is
'.debug_frame', '.debug_frame' is emitted. To emit both use '.eh_frame,
.debug_frame'. The default if this directive is not used is
'.cfi_sections .eh_frame'.
On targets that support compact unwinding tables these can be
generated by specifying '.eh_frame_entry' instead of '.eh_frame'.
Some targets may support an additional name, such as '.c6xabi.exidx'
which is used by the target.
The '.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.
7.10.2 '.cfi_startproc [simple]'
--------------------------------
'.cfi_startproc' is used at the beginning of each function that should
have an entry in '.eh_frame'. It initializes some internal data
structures. Don't forget to close the function by '.cfi_endproc'.
Unless '.cfi_startproc' is used along with parameter 'simple' it also
emits some architecture dependent initial CFI instructions.
7.10.3 '.cfi_endproc'
---------------------
'.cfi_endproc' is used at the end of a function where it closes its
unwind entry previously opened by '.cfi_startproc', and emits it to
'.eh_frame'.
7.10.4 '.cfi_personality ENCODING [, EXP]'
------------------------------------------
'.cfi_personality' defines personality routine and its encoding.
ENCODING must be a constant determining how the personality should be
encoded. If it is 255 ('DW_EH_PE_omit'), second argument is not
present, otherwise second argument should be a constant or a symbol
name. When using indirect encodings, the symbol provided should be the
location where personality can be loaded from, not the personality
routine itself. The default after '.cfi_startproc' is '.cfi_personality
0xff', no personality routine.
7.10.5 '.cfi_personality_id ID'
-------------------------------
'cfi_personality_id' defines a personality routine by its index as
defined in a compact unwinding format. Only valid when generating
compact EH frames (i.e. with '.cfi_sections eh_frame_entry'.
7.10.6 '.cfi_fde_data [OPCODE1 [, ...]]'
----------------------------------------
'cfi_fde_data' is used to describe the compact unwind opcodes to be used
for the current function. These are emitted inline in the
'.eh_frame_entry' section if small enough and there is no LSDA, or in
the '.gnu.extab' section otherwise. Only valid when generating compact
EH frames (i.e. with '.cfi_sections eh_frame_entry'.
7.10.7 '.cfi_lsda ENCODING [, EXP]'
-----------------------------------
'.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant
determining how the LSDA should be encoded. If it is 255
('DW_EH_PE_omit'), the second argument is not present, otherwise the
second argument should be a constant or a symbol name. The default
after '.cfi_startproc' is '.cfi_lsda 0xff', meaning that no LSDA is
present.
7.10.8 '.cfi_inline_lsda' [ALIGN]
---------------------------------
'.cfi_inline_lsda' marks the start of a LSDA data section and switches
to the corresponding '.gnu.extab' section. Must be preceded by a CFI
block containing a '.cfi_lsda' directive. Only valid when generating
compact EH frames (i.e. with '.cfi_sections eh_frame_entry'.
The table header and unwinding opcodes will be generated at this
point, so that they are immediately followed by the LSDA data. The
symbol referenced by the '.cfi_lsda' directive should still be defined
in case a fallback FDE based encoding is used. The LSDA data is
terminated by a section directive.
The optional ALIGN argument specifies the alignment required. The
alignment is specified as a power of two, as with the '.p2align'
directive.
7.10.9 '.cfi_def_cfa REGISTER, OFFSET'
--------------------------------------
'.cfi_def_cfa' defines a rule for computing CFA as: take address from
REGISTER and add OFFSET to it.
7.10.10 '.cfi_def_cfa_register REGISTER'
----------------------------------------
'.cfi_def_cfa_register' modifies a rule for computing CFA. From now on
REGISTER will be used instead of the old one. Offset remains the same.
7.10.11 '.cfi_def_cfa_offset OFFSET'
------------------------------------
'.cfi_def_cfa_offset' modifies a rule for computing CFA. Register
remains the same, but OFFSET is new. Note that it is the absolute
offset that will be added to a defined register to compute CFA address.
7.10.12 '.cfi_adjust_cfa_offset OFFSET'
---------------------------------------
Same as '.cfi_def_cfa_offset' but OFFSET is a relative value that is
added/subtracted from the previous offset.
7.10.13 '.cfi_offset REGISTER, OFFSET'
--------------------------------------
Previous value of REGISTER is saved at offset OFFSET from CFA.
7.10.14 '.cfi_val_offset REGISTER, OFFSET'
------------------------------------------
Previous value of REGISTER is CFA + OFFSET.
7.10.15 '.cfi_rel_offset REGISTER, OFFSET'
------------------------------------------
Previous value of REGISTER is saved at offset OFFSET from the current
CFA register. This is transformed to '.cfi_offset' using the known
displacement of the CFA register from the CFA. This is often easier to
use, because the number will match the code it's annotating.
7.10.16 '.cfi_register REGISTER1, REGISTER2'
--------------------------------------------
Previous value of REGISTER1 is saved in register REGISTER2.
7.10.17 '.cfi_restore REGISTER'
-------------------------------
'.cfi_restore' says that the rule for REGISTER is now the same as it was
at the beginning of the function, after all initial instruction added by
'.cfi_startproc' were executed.
7.10.18 '.cfi_undefined REGISTER'
---------------------------------
From now on the previous value of REGISTER can't be restored anymore.
7.10.19 '.cfi_same_value REGISTER'
----------------------------------
Current value of REGISTER is the same like in the previous frame, i.e.
no restoration needed.
7.10.20 '.cfi_remember_state' and '.cfi_restore_state'
------------------------------------------------------
'.cfi_remember_state' pushes the set of rules for every register onto an
implicit stack, while '.cfi_restore_state' pops them off the stack and
places them in the current row. This is useful for situations where you
have multiple '.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 'rbp'):
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 */
Here, we want the '.cfi' directives to affect only the rows
corresponding to the instructions before 'label'. This means we'd have
to add multiple '.cfi' directives after 'label' to recreate the original
save locations of the registers, as well as setting the CFA back to the
value of 'rbp'. This would be clumsy, and result in a larger binary
size. Instead, we can write:
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 */
That way, the rules for the instructions after 'label' will be the
same as before the first '.cfi_restore' without having to use multiple
'.cfi' directives.
7.10.21 '.cfi_return_column REGISTER'
-------------------------------------
Change return column REGISTER, i.e. the return address is either
directly in REGISTER or can be accessed by rules for REGISTER.
7.10.22 '.cfi_signal_frame'
---------------------------
Mark current function as signal trampoline.
7.10.23 '.cfi_window_save'
--------------------------
SPARC register window has been saved.
7.10.24 '.cfi_escape' EXPRESSION[, ...]
---------------------------------------
Allows the user to add arbitrary bytes to the unwind info. One might
use this to add OS-specific CFI opcodes, or generic CFI opcodes that GAS
does not yet support.
7.10.25 '.cfi_val_encoded_addr REGISTER, ENCODING, LABEL'
---------------------------------------------------------
The current value of REGISTER is LABEL. The value of LABEL will be
encoded in the output file according to ENCODING; see the description of
'.cfi_personality' for details on this encoding.
The usefulness of equating a register to a fixed label is probably
limited to the return address register. Here, it can be useful to mark
a code segment that has only one return address which is reached by a
direct branch and no copy of the return address exists in memory or
another register.
Info Catalog
as: Byte
as: Pseudo Ops
as: Comm