<html lang="en">
<head>
<title>CFI directives - Using as</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using as">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Pseudo-Ops.html#Pseudo-Ops" title="Pseudo Ops">
<link rel="prev" href="Byte.html#Byte" title="Byte">
<link rel="next" href="Comm.html#Comm" title="Comm">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU Assembler "as".

Copyright (C) 1991-2019 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the
section entitled ``GNU Free Documentation License''.

-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="CFI-directives"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Comm.html#Comm">Comm</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Byte.html#Byte">Byte</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Pseudo-Ops.html#Pseudo-Ops">Pseudo Ops</a>
<hr>
</div>

<h3 class="section">7.10 CFI directives</h3>

<h4 class="subsection">7.10.1 <code>.cfi_sections </code><var>section_list</var></h4>

<p><a name="index-g_t_0040code_007bcfi_005fsections_007d-directive-301"></a><code>.cfi_sections</code> may be used to specify whether CFI directives
should emit <code>.eh_frame</code> section and/or <code>.debug_frame</code> section. 
If <var>section_list</var> is <code>.eh_frame</code>, <code>.eh_frame</code> is emitted,
if <var>section_list</var> is <code>.debug_frame</code>, <code>.debug_frame</code> is emitted. 
To emit both use <code>.eh_frame, .debug_frame</code>.  The default if this
directive is not used is <code>.cfi_sections .eh_frame</code>.

   <p>On targets that support compact unwinding tables these can be generated
by specifying <code>.eh_frame_entry</code> instead of <code>.eh_frame</code>.

   <p>Some targets may support an additional name, such as <code>.c6xabi.exidx</code>
which is used by the  target.

   <p>The <code>.cfi_sections</code> 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.

<h4 class="subsection">7.10.2 <code>.cfi_startproc [simple]</code></h4>

<p><a name="index-g_t_0040code_007bcfi_005fstartproc_007d-directive-302"></a><code>.cfi_startproc</code> is used at the beginning of each function that
should have an entry in <code>.eh_frame</code>. It initializes some internal
data structures. Don't forget to close the function by
<code>.cfi_endproc</code>.

   <p>Unless <code>.cfi_startproc</code> is used along with parameter <code>simple</code>
it also emits some architecture dependent initial CFI instructions.

<h4 class="subsection">7.10.3 <code>.cfi_endproc</code></h4>

<p><a name="index-g_t_0040code_007bcfi_005fendproc_007d-directive-303"></a><code>.cfi_endproc</code> is used at the end of a function where it closes its
unwind entry previously opened by
<code>.cfi_startproc</code>, and emits it to <code>.eh_frame</code>.

<h4 class="subsection">7.10.4 <code>.cfi_personality </code><var>encoding</var><code> [, </code><var>exp</var><code>]</code></h4>

<p><a name="index-g_t_0040code_007bcfi_005fpersonality_007d-directive-304"></a><code>.cfi_personality</code> defines personality routine and its encoding. 
<var>encoding</var> must be a constant determining how the personality
should be encoded.  If it is 255 (<code>DW_EH_PE_omit</code>), 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 <code>.cfi_startproc</code> is <code>.cfi_personality 0xff</code>,
no personality routine.

<h4 class="subsection">7.10.5 <code>.cfi_personality_id </code><var>id</var></h4>

<p><a name="index-g_t_0040code_007bcfi_005fpersonality_005fid_007d-directive-305"></a><code>cfi_personality_id</code> defines a personality routine by its index as
defined in a compact unwinding format. 
Only valid when generating compact EH frames (i.e. 
with <code>.cfi_sections eh_frame_entry</code>.

<h4 class="subsection">7.10.6 <code>.cfi_fde_data [</code><var>opcode1</var><code> [, ...]]</code></h4>

<p><a name="index-g_t_0040code_007bcfi_005ffde_005fdata_007d-directive-306"></a><code>cfi_fde_data</code> is used to describe the compact unwind opcodes to be
used for the current function.  These are emitted inline in the
<code>.eh_frame_entry</code> section if small enough and there is no LSDA, or
in the <code>.gnu.extab</code> section otherwise. 
Only valid when generating compact EH frames (i.e. 
with <code>.cfi_sections eh_frame_entry</code>.

<h4 class="subsection">7.10.7 <code>.cfi_lsda </code><var>encoding</var><code> [, </code><var>exp</var><code>]</code></h4>

<p><code>.cfi_lsda</code> defines LSDA and its encoding. 
<var>encoding</var> must be a constant determining how the LSDA
should be encoded.  If it is 255 (<code>DW_EH_PE_omit</code>), the second
argument is not present, otherwise the second argument should be a constant
or a symbol name.  The default after <code>.cfi_startproc</code> is <code>.cfi_lsda 0xff</code>,
meaning that no LSDA is present.

<h4 class="subsection">7.10.8 <code>.cfi_inline_lsda</code> [<var>align</var>]</h4>

<p><code>.cfi_inline_lsda</code> marks the start of a LSDA data section and
switches to the corresponding <code>.gnu.extab</code> section. 
Must be preceded by a CFI block containing a <code>.cfi_lsda</code> directive. 
Only valid when generating compact EH frames (i.e. 
with <code>.cfi_sections eh_frame_entry</code>.

   <p>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 <code>.cfi_lsda</code> directive should still be defined
in case a fallback FDE based encoding is used.  The LSDA data is terminated
by a section directive.

   <p>The optional <var>align</var> argument specifies the alignment required. 
The alignment is specified as a power of two, as with the
<code>.p2align</code> directive.

<h4 class="subsection">7.10.9 <code>.cfi_def_cfa </code><var>register</var><code>, </code><var>offset</var></h4>

<p><code>.cfi_def_cfa</code> defines a rule for computing CFA as: <i>take
address from </i><var>register</var><i> and add </i><var>offset</var><i> to it</i>.

<h4 class="subsection">7.10.10 <code>.cfi_def_cfa_register </code><var>register</var></h4>

<p><code>.cfi_def_cfa_register</code> modifies a rule for computing CFA. From
now on <var>register</var> will be used instead of the old one. Offset
remains the same.

<h4 class="subsection">7.10.11 <code>.cfi_def_cfa_offset </code><var>offset</var></h4>

<p><code>.cfi_def_cfa_offset</code> modifies a rule for computing CFA. Register
remains the same, but <var>offset</var> is new. Note that it is the
absolute offset that will be added to a defined register to compute
CFA address.

<h4 class="subsection">7.10.12 <code>.cfi_adjust_cfa_offset </code><var>offset</var></h4>

<p>Same as <code>.cfi_def_cfa_offset</code> but <var>offset</var> is a relative
value that is added/subtracted from the previous offset.

<h4 class="subsection">7.10.13 <code>.cfi_offset </code><var>register</var><code>, </code><var>offset</var></h4>

<p>Previous value of <var>register</var> is saved at offset <var>offset</var> from
CFA.

<h4 class="subsection">7.10.14 <code>.cfi_val_offset </code><var>register</var><code>, </code><var>offset</var></h4>

<p>Previous value of <var>register</var> is CFA + <var>offset</var>.

<h4 class="subsection">7.10.15 <code>.cfi_rel_offset </code><var>register</var><code>, </code><var>offset</var></h4>

<p>Previous value of <var>register</var> is saved at offset <var>offset</var> from
the current CFA register.  This is transformed to <code>.cfi_offset</code>
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.

<h4 class="subsection">7.10.16 <code>.cfi_register </code><var>register1</var><code>, </code><var>register2</var></h4>

<p>Previous value of <var>register1</var> is saved in register <var>register2</var>.

<h4 class="subsection">7.10.17 <code>.cfi_restore </code><var>register</var></h4>

<p><code>.cfi_restore</code> says that the rule for <var>register</var> is now the
same as it was at the beginning of the function, after all initial
instruction added by <code>.cfi_startproc</code> were executed.

<h4 class="subsection">7.10.18 <code>.cfi_undefined </code><var>register</var></h4>

<p>From now on the previous value of <var>register</var> can't be restored anymore.

<h4 class="subsection">7.10.19 <code>.cfi_same_value </code><var>register</var></h4>

<p>Current value of <var>register</var> is the same like in the previous frame,
i.e. no restoration needed.

<h4 class="subsection">7.10.20 <code>.cfi_remember_state</code> and <code>.cfi_restore_state</code></h4>

<p><code>.cfi_remember_state</code> pushes the set of rules for every register onto an
implicit stack, while <code>.cfi_restore_state</code> pops them off the stack and
places them in the current row.  This is useful for situations where you have
multiple <code>.cfi_*</code> 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</code>):

<pre class="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 */
</pre>
   <p>Here, we want the <code>.cfi</code> directives to affect only the rows corresponding
to the instructions before <code>label</code>.  This means we'd have to add multiple
<code>.cfi</code> directives after <code>label</code> to recreate the original save
locations of the registers, as well as setting the CFA back to the value of
<code>rbp</code>.  This would be clumsy, and result in a larger binary size. Instead,
we can write:

<pre class="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 */
</pre>
   <p>That way, the rules for the instructions after <code>label</code> will be the same
as before the first <code>.cfi_restore</code> without having to use multiple
<code>.cfi</code> directives.

<h4 class="subsection">7.10.21 <code>.cfi_return_column </code><var>register</var></h4>

<p>Change return column <var>register</var>, i.e. the return address is either
directly in <var>register</var> or can be accessed by rules for <var>register</var>.

<h4 class="subsection">7.10.22 <code>.cfi_signal_frame</code></h4>

<p>Mark current function as signal trampoline.

<h4 class="subsection">7.10.23 <code>.cfi_window_save</code></h4>

<p>SPARC register window has been saved.

<h4 class="subsection">7.10.24 <code>.cfi_escape</code> <var>expression</var>[, <small class="dots">...</small>]</h4>

<p>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.

<h4 class="subsection">7.10.25 <code>.cfi_val_encoded_addr </code><var>register</var><code>, </code><var>encoding</var><code>, </code><var>label</var></h4>

<p>The current value of <var>register</var> is <var>label</var>.  The value of <var>label</var>
will be encoded in the output file according to <var>encoding</var>; see the
description of <code>.cfi_personality</code> for details on this encoding.

   <p>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.

   </body></html>