1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- This file documents the GNU Assembler "as". 4 5Copyright (C) 1991-2021 Free Software Foundation, Inc. 6 7Permission is granted to copy, distribute and/or modify this document 8under the terms of the GNU Free Documentation License, Version 1.3 9or any later version published by the Free Software Foundation; 10with no Invariant Sections, with no Front-Cover Texts, and with no 11Back-Cover Texts. A copy of the license is included in the 12section entitled "GNU Free Documentation License". 13 --> 14<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 15<head> 16<title>Using as: CFI directives</title> 17 18<meta name="description" content="Using as: CFI directives"> 19<meta name="keywords" content="Using as: CFI directives"> 20<meta name="resource-type" content="document"> 21<meta name="distribution" content="global"> 22<meta name="Generator" content="makeinfo"> 23<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 24<link href="index.html#Top" rel="start" title="Top"> 25<link href="AS-Index.html#AS-Index" rel="index" title="AS Index"> 26<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 27<link href="Pseudo-Ops.html#Pseudo-Ops" rel="up" title="Pseudo Ops"> 28<link href="Comm.html#Comm" rel="next" title="Comm"> 29<link href="Byte.html#Byte" rel="previous" title="Byte"> 30<style type="text/css"> 31<!-- 32a.summary-letter {text-decoration: none} 33blockquote.smallquotation {font-size: smaller} 34div.display {margin-left: 3.2em} 35div.example {margin-left: 3.2em} 36div.indentedblock {margin-left: 3.2em} 37div.lisp {margin-left: 3.2em} 38div.smalldisplay {margin-left: 3.2em} 39div.smallexample {margin-left: 3.2em} 40div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 41div.smalllisp {margin-left: 3.2em} 42kbd {font-style:oblique} 43pre.display {font-family: inherit} 44pre.format {font-family: inherit} 45pre.menu-comment {font-family: serif} 46pre.menu-preformatted {font-family: serif} 47pre.smalldisplay {font-family: inherit; font-size: smaller} 48pre.smallexample {font-size: smaller} 49pre.smallformat {font-family: inherit; font-size: smaller} 50pre.smalllisp {font-size: smaller} 51span.nocodebreak {white-space:nowrap} 52span.nolinebreak {white-space:nowrap} 53span.roman {font-family:serif; font-weight:normal} 54span.sansserif {font-family:sans-serif; font-weight:normal} 55ul.no-bullet {list-style: none} 56--> 57</style> 58 59 60</head> 61 62<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 63<a name="CFI-directives"></a> 64<div class="header"> 65<p> 66Next: <a href="Comm.html#Comm" accesskey="n" rel="next">Comm</a>, Previous: <a href="Byte.html#Byte" accesskey="p" rel="previous">Byte</a>, Up: <a href="Pseudo-Ops.html#Pseudo-Ops" accesskey="u" rel="up">Pseudo Ops</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AS-Index.html#AS-Index" title="Index" rel="index">Index</a>]</p> 67</div> 68<hr> 69<a name="CFI-directives-1"></a> 70<h3 class="section">7.11 CFI directives</h3> 71<a name="g_t_002ecfi_005fsections-section_005flist"></a> 72<h4 class="subsection">7.11.1 <code>.cfi_sections <var>section_list</var></code></h4> 73<a name="index-cfi_005fsections-directive"></a> 74<p><code>.cfi_sections</code> may be used to specify whether CFI directives 75should emit <code>.eh_frame</code> section and/or <code>.debug_frame</code> section. 76If <var>section_list</var> is <code>.eh_frame</code>, <code>.eh_frame</code> is emitted, 77if <var>section_list</var> is <code>.debug_frame</code>, <code>.debug_frame</code> is emitted. 78To emit both use <code>.eh_frame, .debug_frame</code>. The default if this 79directive is not used is <code>.cfi_sections .eh_frame</code>. 80</p> 81<p>On targets that support compact unwinding tables these can be generated 82by specifying <code>.eh_frame_entry</code> instead of <code>.eh_frame</code>. 83</p> 84<p>Some targets may support an additional name, such as <code>.c6xabi.exidx</code> 85which is used by the target. 86</p> 87<p>The <code>.cfi_sections</code> directive can be repeated, with the same or different 88arguments, provided that CFI generation has not yet started. Once CFI 89generation has started however the section list is fixed and any attempts to 90redefine it will result in an error. 91</p> 92<a name="g_t_002ecfi_005fstartproc-_005bsimple_005d"></a> 93<h4 class="subsection">7.11.2 <code>.cfi_startproc [simple]</code></h4> 94<a name="index-cfi_005fstartproc-directive"></a> 95<p><code>.cfi_startproc</code> is used at the beginning of each function that 96should have an entry in <code>.eh_frame</code>. It initializes some internal 97data structures. Don’t forget to close the function by 98<code>.cfi_endproc</code>. 99</p> 100<p>Unless <code>.cfi_startproc</code> is used along with parameter <code>simple</code> 101it also emits some architecture dependent initial CFI instructions. 102</p> 103<a name="g_t_002ecfi_005fendproc"></a> 104<h4 class="subsection">7.11.3 <code>.cfi_endproc</code></h4> 105<a name="index-cfi_005fendproc-directive"></a> 106<p><code>.cfi_endproc</code> is used at the end of a function where it closes its 107unwind entry previously opened by 108<code>.cfi_startproc</code>, and emits it to <code>.eh_frame</code>. 109</p> 110<a name="g_t_002ecfi_005fpersonality-encoding-_005b_002c-exp_005d"></a> 111<h4 class="subsection">7.11.4 <code>.cfi_personality <var>encoding</var> [, <var>exp</var>]</code></h4> 112<a name="index-cfi_005fpersonality-directive"></a> 113<p><code>.cfi_personality</code> defines personality routine and its encoding. 114<var>encoding</var> must be a constant determining how the personality 115should be encoded. If it is 255 (<code>DW_EH_PE_omit</code>), second 116argument is not present, otherwise second argument should be 117a constant or a symbol name. When using indirect encodings, 118the symbol provided should be the location where personality 119can be loaded from, not the personality routine itself. 120The default after <code>.cfi_startproc</code> is <code>.cfi_personality 0xff</code>, 121no personality routine. 122</p> 123<a name="g_t_002ecfi_005fpersonality_005fid-id"></a> 124<h4 class="subsection">7.11.5 <code>.cfi_personality_id <var>id</var></code></h4> 125<a name="index-cfi_005fpersonality_005fid-directive"></a> 126<p><code>cfi_personality_id</code> defines a personality routine by its index as 127defined in a compact unwinding format. 128Only valid when generating compact EH frames (i.e. 129with <code>.cfi_sections eh_frame_entry</code>. 130</p> 131<a name="g_t_002ecfi_005ffde_005fdata-_005bopcode1-_005b_002c-_2026_005d_005d"></a> 132<h4 class="subsection">7.11.6 <code>.cfi_fde_data [<var>opcode1</var> [, …]]</code></h4> 133<a name="index-cfi_005ffde_005fdata-directive"></a> 134<p><code>cfi_fde_data</code> is used to describe the compact unwind opcodes to be 135used for the current function. These are emitted inline in the 136<code>.eh_frame_entry</code> section if small enough and there is no LSDA, or 137in the <code>.gnu.extab</code> section otherwise. 138Only valid when generating compact EH frames (i.e. 139with <code>.cfi_sections eh_frame_entry</code>. 140</p> 141<a name="g_t_002ecfi_005flsda-encoding-_005b_002c-exp_005d"></a> 142<h4 class="subsection">7.11.7 <code>.cfi_lsda <var>encoding</var> [, <var>exp</var>]</code></h4> 143<p><code>.cfi_lsda</code> defines LSDA and its encoding. 144<var>encoding</var> must be a constant determining how the LSDA 145should be encoded. If it is 255 (<code>DW_EH_PE_omit</code>), the second 146argument is not present, otherwise the second argument should be a constant 147or a symbol name. The default after <code>.cfi_startproc</code> is <code>.cfi_lsda 0xff</code>, 148meaning that no LSDA is present. 149</p> 150<a name="g_t_002ecfi_005finline_005flsda-_005balign_005d"></a> 151<h4 class="subsection">7.11.8 <code>.cfi_inline_lsda</code> [<var>align</var>]</h4> 152<p><code>.cfi_inline_lsda</code> marks the start of a LSDA data section and 153switches to the corresponding <code>.gnu.extab</code> section. 154Must be preceded by a CFI block containing a <code>.cfi_lsda</code> directive. 155Only valid when generating compact EH frames (i.e. 156with <code>.cfi_sections eh_frame_entry</code>. 157</p> 158<p>The table header and unwinding opcodes will be generated at this point, 159so that they are immediately followed by the LSDA data. The symbol 160referenced by the <code>.cfi_lsda</code> directive should still be defined 161in case a fallback FDE based encoding is used. The LSDA data is terminated 162by a section directive. 163</p> 164<p>The optional <var>align</var> argument specifies the alignment required. 165The alignment is specified as a power of two, as with the 166<code>.p2align</code> directive. 167</p> 168<a name="g_t_002ecfi_005fdef_005fcfa-register_002c-offset"></a> 169<h4 class="subsection">7.11.9 <code>.cfi_def_cfa <var>register</var>, <var>offset</var></code></h4> 170<p><code>.cfi_def_cfa</code> defines a rule for computing CFA as: <i>take 171address from <var>register</var> and add <var>offset</var> to it</i>. 172</p> 173<a name="g_t_002ecfi_005fdef_005fcfa_005fregister-register"></a> 174<h4 class="subsection">7.11.10 <code>.cfi_def_cfa_register <var>register</var></code></h4> 175<p><code>.cfi_def_cfa_register</code> modifies a rule for computing CFA. From 176now on <var>register</var> will be used instead of the old one. Offset 177remains the same. 178</p> 179<a name="g_t_002ecfi_005fdef_005fcfa_005foffset-offset"></a> 180<h4 class="subsection">7.11.11 <code>.cfi_def_cfa_offset <var>offset</var></code></h4> 181<p><code>.cfi_def_cfa_offset</code> modifies a rule for computing CFA. Register 182remains the same, but <var>offset</var> is new. Note that it is the 183absolute offset that will be added to a defined register to compute 184CFA address. 185</p> 186<a name="g_t_002ecfi_005fadjust_005fcfa_005foffset-offset"></a> 187<h4 class="subsection">7.11.12 <code>.cfi_adjust_cfa_offset <var>offset</var></code></h4> 188<p>Same as <code>.cfi_def_cfa_offset</code> but <var>offset</var> is a relative 189value that is added/subtracted from the previous offset. 190</p> 191<a name="g_t_002ecfi_005foffset-register_002c-offset"></a> 192<h4 class="subsection">7.11.13 <code>.cfi_offset <var>register</var>, <var>offset</var></code></h4> 193<p>Previous value of <var>register</var> is saved at offset <var>offset</var> from 194CFA. 195</p> 196<a name="g_t_002ecfi_005fval_005foffset-register_002c-offset"></a> 197<h4 class="subsection">7.11.14 <code>.cfi_val_offset <var>register</var>, <var>offset</var></code></h4> 198<p>Previous value of <var>register</var> is CFA + <var>offset</var>. 199</p> 200<a name="g_t_002ecfi_005frel_005foffset-register_002c-offset"></a> 201<h4 class="subsection">7.11.15 <code>.cfi_rel_offset <var>register</var>, <var>offset</var></code></h4> 202<p>Previous value of <var>register</var> is saved at offset <var>offset</var> from 203the current CFA register. This is transformed to <code>.cfi_offset</code> 204using the known displacement of the CFA register from the CFA. 205This is often easier to use, because the number will match the 206code it’s annotating. 207</p> 208<a name="g_t_002ecfi_005fregister-register1_002c-register2"></a> 209<h4 class="subsection">7.11.16 <code>.cfi_register <var>register1</var>, <var>register2</var></code></h4> 210<p>Previous value of <var>register1</var> is saved in register <var>register2</var>. 211</p> 212<a name="g_t_002ecfi_005frestore-register"></a> 213<h4 class="subsection">7.11.17 <code>.cfi_restore <var>register</var></code></h4> 214<p><code>.cfi_restore</code> says that the rule for <var>register</var> is now the 215same as it was at the beginning of the function, after all initial 216instruction added by <code>.cfi_startproc</code> were executed. 217</p> 218<a name="g_t_002ecfi_005fundefined-register"></a> 219<h4 class="subsection">7.11.18 <code>.cfi_undefined <var>register</var></code></h4> 220<p>From now on the previous value of <var>register</var> can’t be restored anymore. 221</p> 222<a name="g_t_002ecfi_005fsame_005fvalue-register"></a> 223<h4 class="subsection">7.11.19 <code>.cfi_same_value <var>register</var></code></h4> 224<p>Current value of <var>register</var> is the same like in the previous frame, 225i.e. no restoration needed. 226</p> 227<a name="g_t_002ecfi_005fremember_005fstate-and-_002ecfi_005frestore_005fstate"></a> 228<h4 class="subsection">7.11.20 <code>.cfi_remember_state</code> and <code>.cfi_restore_state</code></h4> 229<p><code>.cfi_remember_state</code> pushes the set of rules for every register onto an 230implicit stack, while <code>.cfi_restore_state</code> pops them off the stack and 231places them in the current row. This is useful for situations where you have 232multiple <code>.cfi_*</code> directives that need to be undone due to the control 233flow of the program. For example, we could have something like this (assuming 234the CFA is the value of <code>rbp</code>): 235</p> 236<div class="smallexample"> 237<pre class="smallexample"> je label 238 popq %rbx 239 .cfi_restore %rbx 240 popq %r12 241 .cfi_restore %r12 242 popq %rbp 243 .cfi_restore %rbp 244 .cfi_def_cfa %rsp, 8 245 ret 246label: 247 /* Do something else */ 248</pre></div> 249 250<p>Here, we want the <code>.cfi</code> directives to affect only the rows corresponding 251to the instructions before <code>label</code>. This means we’d have to add multiple 252<code>.cfi</code> directives after <code>label</code> to recreate the original save 253locations of the registers, as well as setting the CFA back to the value of 254<code>rbp</code>. This would be clumsy, and result in a larger binary size. Instead, 255we can write: 256</p> 257<div class="smallexample"> 258<pre class="smallexample"> je label 259 popq %rbx 260 .cfi_remember_state 261 .cfi_restore %rbx 262 popq %r12 263 .cfi_restore %r12 264 popq %rbp 265 .cfi_restore %rbp 266 .cfi_def_cfa %rsp, 8 267 ret 268label: 269 .cfi_restore_state 270 /* Do something else */ 271</pre></div> 272 273<p>That way, the rules for the instructions after <code>label</code> will be the same 274as before the first <code>.cfi_restore</code> without having to use multiple 275<code>.cfi</code> directives. 276</p> 277<a name="g_t_002ecfi_005freturn_005fcolumn-register"></a> 278<h4 class="subsection">7.11.21 <code>.cfi_return_column <var>register</var></code></h4> 279<p>Change return column <var>register</var>, i.e. the return address is either 280directly in <var>register</var> or can be accessed by rules for <var>register</var>. 281</p> 282<a name="g_t_002ecfi_005fsignal_005fframe"></a> 283<h4 class="subsection">7.11.22 <code>.cfi_signal_frame</code></h4> 284<p>Mark current function as signal trampoline. 285</p> 286<a name="g_t_002ecfi_005fwindow_005fsave"></a> 287<h4 class="subsection">7.11.23 <code>.cfi_window_save</code></h4> 288<p>SPARC register window has been saved. 289</p> 290<a name="g_t_002ecfi_005fescape-expression_005b_002c-_2026_005d"></a> 291<h4 class="subsection">7.11.24 <code>.cfi_escape</code> <var>expression</var>[, …]</h4> 292<p>Allows the user to add arbitrary bytes to the unwind info. One 293might use this to add OS-specific CFI opcodes, or generic CFI 294opcodes that GAS does not yet support. 295</p> 296<a name="g_t_002ecfi_005fval_005fencoded_005faddr-register_002c-encoding_002c-label"></a> 297<h4 class="subsection">7.11.25 <code>.cfi_val_encoded_addr <var>register</var>, <var>encoding</var>, <var>label</var></code></h4> 298<p>The current value of <var>register</var> is <var>label</var>. The value of <var>label</var> 299will be encoded in the output file according to <var>encoding</var>; see the 300description of <code>.cfi_personality</code> for details on this encoding. 301</p> 302<p>The usefulness of equating a register to a fixed label is probably 303limited to the return address register. Here, it can be useful to 304mark a code segment that has only one return address which is reached 305by a direct branch and no copy of the return address exists in memory 306or another register. 307</p> 308<hr> 309<div class="header"> 310<p> 311Next: <a href="Comm.html#Comm" accesskey="n" rel="next">Comm</a>, Previous: <a href="Byte.html#Byte" accesskey="p" rel="previous">Byte</a>, Up: <a href="Pseudo-Ops.html#Pseudo-Ops" accesskey="u" rel="up">Pseudo Ops</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AS-Index.html#AS-Index" title="Index" rel="index">Index</a>]</p> 312</div> 313 314 315 316</body> 317</html> 318