as: CFI directives
1
1 7.11 CFI directives
1 ===================
1
1 7.11.1 '.cfi_sections SECTION_LIST'
1 -----------------------------------
1
1 '.cfi_sections' may be used to specify whether CFI directives should
1 emit '.eh_frame' section and/or '.debug_frame' section. If SECTION_LIST
1 is '.eh_frame', '.eh_frame' is emitted, if SECTION_LIST is
1 '.debug_frame', '.debug_frame' is emitted. To emit both use '.eh_frame,
1 .debug_frame'. The default if this directive is not used is
1 '.cfi_sections .eh_frame'.
1
1 On targets that support compact unwinding tables these can be
1 generated by specifying '.eh_frame_entry' instead of '.eh_frame'.
1
1 Some targets may support an additional name, such as '.c6xabi.exidx'
1 which is used by the target.
1
1 The '.cfi_sections' directive can be repeated, with the same or
1 different arguments, provided that CFI generation has not yet started.
1 Once CFI generation has started however the section list is fixed and
1 any attempts to redefine it will result in an error.
1
1 7.11.2 '.cfi_startproc [simple]'
1 --------------------------------
1
1 '.cfi_startproc' is used at the beginning of each function that should
1 have an entry in '.eh_frame'. It initializes some internal data
1 structures. Don't forget to close the function by '.cfi_endproc'.
1
1 Unless '.cfi_startproc' is used along with parameter 'simple' it also
1 emits some architecture dependent initial CFI instructions.
1
1 7.11.3 '.cfi_endproc'
1 ---------------------
1
1 '.cfi_endproc' is used at the end of a function where it closes its
1 unwind entry previously opened by '.cfi_startproc', and emits it to
1 '.eh_frame'.
1
1 7.11.4 '.cfi_personality ENCODING [, EXP]'
1 ------------------------------------------
1
1 '.cfi_personality' defines personality routine and its encoding.
1 ENCODING must be a constant determining how the personality should be
1 encoded. If it is 255 ('DW_EH_PE_omit'), second argument is not
1 present, otherwise second argument should be a constant or a symbol
1 name. When using indirect encodings, the symbol provided should be the
1 location where personality can be loaded from, not the personality
1 routine itself. The default after '.cfi_startproc' is '.cfi_personality
1 0xff', no personality routine.
1
1 7.11.5 '.cfi_personality_id ID'
1 -------------------------------
1
1 'cfi_personality_id' defines a personality routine by its index as
1 defined in a compact unwinding format. Only valid when generating
1 compact EH frames (i.e. with '.cfi_sections eh_frame_entry'.
1
1 7.11.6 '.cfi_fde_data [OPCODE1 [, ...]]'
1 ----------------------------------------
1
1 'cfi_fde_data' is used to describe the compact unwind opcodes to be used
1 for the current function. These are emitted inline in the
1 '.eh_frame_entry' section if small enough and there is no LSDA, or in
1 the '.gnu.extab' section otherwise. Only valid when generating compact
1 EH frames (i.e. with '.cfi_sections eh_frame_entry'.
1
1 7.11.7 '.cfi_lsda ENCODING [, EXP]'
1 -----------------------------------
1
1 '.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant
1 determining how the LSDA should be encoded. If it is 255
1 ('DW_EH_PE_omit'), the second argument is not present, otherwise the
1 second argument should be a constant or a symbol name. The default
1 after '.cfi_startproc' is '.cfi_lsda 0xff', meaning that no LSDA is
1 present.
1
1 7.11.8 '.cfi_inline_lsda' [ALIGN]
1 ---------------------------------
1
1 '.cfi_inline_lsda' marks the start of a LSDA data section and switches
1 to the corresponding '.gnu.extab' section. Must be preceded by a CFI
1 block containing a '.cfi_lsda' directive. Only valid when generating
1 compact EH frames (i.e. with '.cfi_sections eh_frame_entry'.
1
1 The table header and unwinding opcodes will be generated at this
1 point, so that they are immediately followed by the LSDA data. The
1 symbol referenced by the '.cfi_lsda' directive should still be defined
1 in case a fallback FDE based encoding is used. The LSDA data is
1 terminated by a section directive.
1
1 The optional ALIGN argument specifies the alignment required. The
1 alignment is specified as a power of two, as with the '.p2align'
1 directive.
1
1 7.11.9 '.cfi_def_cfa REGISTER, OFFSET'
1 --------------------------------------
1
1 '.cfi_def_cfa' defines a rule for computing CFA as: take address from
1 REGISTER and add OFFSET to it.
1
1 7.11.10 '.cfi_def_cfa_register REGISTER'
1 ----------------------------------------
1
1 '.cfi_def_cfa_register' modifies a rule for computing CFA. From now on
1 REGISTER will be used instead of the old one. Offset remains the same.
1
1 7.11.11 '.cfi_def_cfa_offset OFFSET'
1 ------------------------------------
1
1 '.cfi_def_cfa_offset' modifies a rule for computing CFA. Register
1 remains the same, but OFFSET is new. Note that it is the absolute
1 offset that will be added to a defined register to compute CFA address.
1
1 7.11.12 '.cfi_adjust_cfa_offset OFFSET'
1 ---------------------------------------
1
1 Same as '.cfi_def_cfa_offset' but OFFSET is a relative value that is
1 added/subtracted from the previous offset.
1
1 7.11.13 '.cfi_offset REGISTER, OFFSET'
1 --------------------------------------
1
1 Previous value of REGISTER is saved at offset OFFSET from CFA.
1
1 7.11.14 '.cfi_val_offset REGISTER, OFFSET'
1 ------------------------------------------
1
1 Previous value of REGISTER is CFA + OFFSET.
1
1 7.11.15 '.cfi_rel_offset REGISTER, OFFSET'
1 ------------------------------------------
1
1 Previous value of REGISTER is saved at offset OFFSET from the current
1 CFA register. This is transformed to '.cfi_offset' using the known
1 displacement of the CFA register from the CFA. This is often easier to
1 use, because the number will match the code it's annotating.
1
1 7.11.16 '.cfi_register REGISTER1, REGISTER2'
1 --------------------------------------------
1
1 Previous value of REGISTER1 is saved in register REGISTER2.
1
1 7.11.17 '.cfi_restore REGISTER'
1 -------------------------------
1
1 '.cfi_restore' says that the rule for REGISTER is now the same as it was
1 at the beginning of the function, after all initial instruction added by
1 '.cfi_startproc' were executed.
1
1 7.11.18 '.cfi_undefined REGISTER'
1 ---------------------------------
1
1 From now on the previous value of REGISTER can't be restored anymore.
1
1 7.11.19 '.cfi_same_value REGISTER'
1 ----------------------------------
1
1 Current value of REGISTER is the same like in the previous frame, i.e.
1 no restoration needed.
1
1 7.11.20 '.cfi_remember_state' and '.cfi_restore_state'
1 ------------------------------------------------------
1
1 '.cfi_remember_state' pushes the set of rules for every register onto an
1 implicit stack, while '.cfi_restore_state' pops them off the stack and
1 places them in the current row. This is useful for situations where you
1 have multiple '.cfi_*' directives that need to be undone due to the
1 control flow of the program. For example, we could have something like
1 this (assuming the CFA is the value of 'rbp'):
1
1 je label
1 popq %rbx
1 .cfi_restore %rbx
1 popq %r12
1 .cfi_restore %r12
1 popq %rbp
1 .cfi_restore %rbp
1 .cfi_def_cfa %rsp, 8
1 ret
1 label:
1 /* Do something else */
1
1 Here, we want the '.cfi' directives to affect only the rows
1 corresponding to the instructions before 'label'. This means we'd have
1 to add multiple '.cfi' directives after 'label' to recreate the original
1 save locations of the registers, as well as setting the CFA back to the
1 value of 'rbp'. This would be clumsy, and result in a larger binary
1 size. Instead, we can write:
1
1 je label
1 popq %rbx
1 .cfi_remember_state
1 .cfi_restore %rbx
1 popq %r12
1 .cfi_restore %r12
1 popq %rbp
1 .cfi_restore %rbp
1 .cfi_def_cfa %rsp, 8
1 ret
1 label:
1 .cfi_restore_state
1 /* Do something else */
1
1 That way, the rules for the instructions after 'label' will be the
1 same as before the first '.cfi_restore' without having to use multiple
1 '.cfi' directives.
1
1 7.11.21 '.cfi_return_column REGISTER'
1 -------------------------------------
1
1 Change return column REGISTER, i.e. the return address is either
1 directly in REGISTER or can be accessed by rules for REGISTER.
1
1 7.11.22 '.cfi_signal_frame'
1 ---------------------------
1
1 Mark current function as signal trampoline.
1
1 7.11.23 '.cfi_window_save'
1 --------------------------
1
1 SPARC register window has been saved.
1
1 7.11.24 '.cfi_escape' EXPRESSION[, ...]
1 ---------------------------------------
1
1 Allows the user to add arbitrary bytes to the unwind info. One might
1 use this to add OS-specific CFI opcodes, or generic CFI opcodes that GAS
1 does not yet support.
1
1 7.11.25 '.cfi_val_encoded_addr REGISTER, ENCODING, LABEL'
1 ---------------------------------------------------------
1
1 The current value of REGISTER is LABEL. The value of LABEL will be
1 encoded in the output file according to ENCODING; see the description of
1 '.cfi_personality' for details on this encoding.
1
1 The usefulness of equating a register to a fixed label is probably
1 limited to the return address register. Here, it can be useful to mark
1 a code segment that has only one return address which is reached by a
1 direct branch and no copy of the return address exists in memory or
1 another register.
1