From: Indu Bhagat <indu.bhagat@oracle.com>
To: binutils@sourceware.org
Cc: Indu Bhagat <indu.bhagat@oracle.com>
Subject: [PATCH 1/5] libsframe/doc: use "stack trace" instead of "unwind" for SFrame
Date: Tue, 31 Jan 2023 15:34:25 -0800 [thread overview]
Message-ID: <20230131233429.3708328-2-indu.bhagat@oracle.com> (raw)
In-Reply-To: <20230131233429.3708328-1-indu.bhagat@oracle.com>
SFrame format is meant for generating stack traces only.
libsframe/
* doc/sframe-spec.texi: Use "stack trace" instead of "unwind".
---
libsframe/doc/sframe-spec.texi | 37 +++++++++++++++++-----------------
1 file changed, 19 insertions(+), 18 deletions(-)
diff --git a/libsframe/doc/sframe-spec.texi b/libsframe/doc/sframe-spec.texi
index 175c622f85d..6987b6fee13 100644
--- a/libsframe/doc/sframe-spec.texi
+++ b/libsframe/doc/sframe-spec.texi
@@ -35,7 +35,7 @@ License''.
This manual describes version 1 of the SFrame file format. SFrame stands for
Simple Frame format. SFrame format keeps track of the minimal necessary
-information needed for stack unwinding:
+information needed for generating stack traces:
@itemize @minus
@item
@@ -47,7 +47,7 @@ Return Address (RA).
@end itemize
The reason for existence of the SFrame format is to support fast, online
-backtracing using a simple unwinder.
+generation of stack traces using simple means.
@menu
* Overview::
@@ -62,7 +62,7 @@ backtracing using a simple unwinder.
@cindex Overview
@tindex PT_GNU_SFRAME
-The SFrame unwind information is provided in a loaded section, known as the
+The SFrame stack trace information is provided in a loaded section, known as the
@code{.sframe} section. When available, the @code{.sframe} section appears in
a new segment of its own, PT_GNU_SFRAME.
@@ -289,7 +289,7 @@ high-level function description for backtracing.
@item 0x18
@tab @code{uint32_t sfh_freoff}
@tab The offset in bytes of the SFrame FRE sub-section, the core of the SFrame
-section, which describes the unwind information using variable-length array
+section, which describes the stack trace information using variable-length array
elements. @xref{SFrame Frame Row Entries}.
@end multitable
@@ -303,8 +303,9 @@ elements. @xref{SFrame Frame Row Entries}.
@cindex SFrame ABI/arch identifier
SFrame header identifies the ABI/arch of the target system for which the
-executable and it's unwind information is intended. There are currently three
-identifiable ABI/arch values in the format.
+executable and hence, the stack trace information contained in the SFrame
+section, is intended. There are currently three identifiable ABI/arch values
+in the format.
@multitable {SFRAME_ABI_AARCH64_ENDIAN_LITTLE} {Value} {@code{AARCH64 little-endian}}
@headitem ABI/arch Identifier @tab Value @tab Description
@@ -324,7 +325,7 @@ identifiable ABI/arch values in the format.
@end multitable
The presence of an explicit identification of ABI/arch in SFrame may allow
-unwinders to make certain ABI-specific decisions.
+stack trace generators to make certain ABI-specific decisions.
@node SFrame Function Descriptor Entries
@section SFrame FDE
@@ -332,8 +333,8 @@ unwinders to make certain ABI-specific decisions.
The SFrame Function Descriptor Entry sub-section is a sorted array of
fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFrame FDE
-is a packed structure which contains information to describe a function's unwind
-information at a high-level.
+is a packed structure which contains information to describe a function's stack
+trace information at a high-level.
@example
typedef struct sframe_func_desc_entry
@@ -459,7 +460,7 @@ to look up a matching FRE.
@subsection The SFrame FRE types
A real world application can have functions of size big and small. SFrame
-format defines three types of SFrame FRE entries to represent the unwind
+format defines three types of SFrame FRE entries to represent the stack trace
information for such a variety of function sizes. These representations vary
in the number of bits needed to encode the start address offset in the SFrame
FRE.
@@ -488,21 +489,21 @@ The following constants are defined and used to identify the SFrame FRE types:
32-bit value.
@end multitable
-A single function must use the same type of FRE throughout. The choice of
-which SFrame FRE is used to encode the unwind information of a function, is
-stored in the @xref{The SFrame FDE info word}.
+A single function must use the same type of SFrame FRE throughout. An
+identifier to reflect the chosen SFrame FRE type is stored in the
+@xref{The SFrame FDE info word}.
@node SFrame Frame Row Entries
@section SFrame FRE
@cindex SFrame FRE
-The SFrame Frame Row Entry sub-section contains the core of the unwind
+The SFrame Frame Row Entry sub-section contains the core of the stack trace
information.
-An SFrame Frame Row Entry is a self-sufficient record containing SFrame unwind
-info for a range of contiguous addresses, starting at the specified offset from
-the start of the function. Each SFrame Frame Row Entry is followed by S*N
-bytes, where:
+An SFrame Frame Row Entry is a self-sufficient record containing SFrame stack
+trace information for a range of contiguous addresses, starting at the
+specified offset from the start of the function. Each SFrame Frame Row Entry
+is followed by S*N bytes, where:
@itemize @minus
@item
--
2.39.0
next prev parent reply other threads:[~2023-01-31 23:34 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-01-31 23:34 [PATCH 0/5] Reword to reflect SFrame is a stack trace format Indu Bhagat
2023-01-31 23:34 ` Indu Bhagat [this message]
2023-01-31 23:34 ` [PATCH 2/5] sframe: use "stack trace" instead of "unwind" for SFrame Indu Bhagat
2023-01-31 23:34 ` [PATCH 3/5] gas: " Indu Bhagat
2023-01-31 23:34 ` [PATCH 4/5] bfd: " Indu Bhagat
2023-01-31 23:34 ` [PATCH 5/5] ld/doc: " Indu Bhagat
2023-02-01 9:42 ` [PATCH 0/5] Reword to reflect SFrame is a stack trace format Nick Clifton
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230131233429.3708328-2-indu.bhagat@oracle.com \
--to=indu.bhagat@oracle.com \
--cc=binutils@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).