This is the mail archive of the
binutils@sourceware.org
mailing list for the binutils project.
[PATCH] gas: Improve documentation for cfi_remember/restore_state
- From: Martin Galvan <martin dot galvan at tallertechnologies dot com>
- To: binutils at sourceware dot org, nickc at redhat dot com
- Date: Wed, 13 Apr 2016 18:49:20 -0300
- Subject: [PATCH] gas: Improve documentation for cfi_remember/restore_state
- Authentication-results: sourceware.org; auth=none
The previous documentation for these CFI directives wasn't very helpful, so I
reworded it and added an example. Any feedback is welcome.
I have a company-wide copyright assignment for binutils, but I don't have write
access so someone else should commit this for me. Thanks!
gas/ChangeLog:
2016-04-13 Martin Galvan <martin.galvan@tallertechnologies.com>
* doc/as.texinfo (.cfi_remember_state, .cfi_restore_state): Improve
documentation.
---
gas/doc/as.texinfo | 38 +++++++++++++++++++++++++++++++++-----
1 file changed, 33 insertions(+), 5 deletions(-)
diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 7b36931..01fc17d 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -4816,11 +4816,39 @@ From now on the previous value of @var{register} can't be restored anymore.
Current value of @var{register} is the same like in the previous frame,
i.e. no restoration needed.
-@subsection @code{.cfi_remember_state},
-First save all current rules for all registers by @code{.cfi_remember_state},
-then totally screw them up by subsequent @code{.cfi_*} directives and when
-everything is hopelessly bad, use @code{.cfi_restore_state} to restore
-the previous saved state.
+@subsection @code{.cfi_remember_state} and @code{.cfi_restore_state}
+@code{.cfi_remember_state} pushes the set of rules for every register onto an
+implicit stack, while @code{.cfi_restore_state} pops them off the stack and
+places them in the current row. This is useful for situations where you have
+@code{.cfi_*} directives that alter the following rows only under certain
+conditions. For example, we could have something like this:
+
+@smallexample
+ jne label
+ addq $42, %rsp
+ .cfi_adjust_cfa_offset -42
+ ret
+label:
+ /* Do something else */
+@end smallexample
+
+Here, we want the @code{.cfi} directive to affect only the row corresponding to
+the @code{ret} instruction, but not the code after @code{label}. To do this we
+can write:
+
+@smallexample
+ .cfi_remember_state
+ jne label
+ addq $42, %rsp
+ .cfi_adjust_cfa_offset -42
+ ret
+label:
+ .cfi_restore_state
+ /* Do something else */
+@end smallexample
+
+That way, the rules for the instructions after @code{label} will be the same
+as before the @{.cfi_adjust_cfa_offset}.
@subsection @code{.cfi_return_column @var{register}}
Change return column @var{register}, i.e. the return address is either
--
2.8.1