| <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: <a rel="next" accesskey="n" href="Comm.html#Comm">Comm</a>, |
| Previous: <a rel="previous" accesskey="p" href="Byte.html#Byte">Byte</a>, |
| Up: <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> |
| |
