From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 7850) id BB6543858023; Thu, 2 Feb 2023 08:56:03 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org BB6543858023 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1675328163; bh=9My2kd17zlfoRuULDStlIBwr/Ckx4PjupKhTs0OqxFo=; h=From:To:Subject:Date:From; b=EEFARF/dTUnqBA35blwgJQPUuW9WpajEdoR4VJyWVT0HG37FxGpWwX7tZnyw5p6JS 8X84+jy2BARRwBM86Pu8Zrq5q3TQRyzpAUGkJT2TogGIo/Wpfar44HSVwTsdCKWOIG YAVtSHTrVveh4awlIa2qEsZ+neo9MVJ5MS920eFM= Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable From: Indu Bhagat To: bfd-cvs@sourceware.org, gdb-cvs@sourceware.org Subject: [binutils-gdb] libsframe/doc: use "stack trace" instead of "unwind" for SFrame X-Act-Checkin: binutils-gdb X-Git-Author: Indu Bhagat X-Git-Refname: refs/heads/master X-Git-Oldrev: 0709900ede7dcb0c77d40a0c2403d2921afa18c3 X-Git-Newrev: 469b6d54d3a739df64e48ce69f9c6eb37bec0c57 Message-Id: <20230202085603.BB6543858023@sourceware.org> Date: Thu, 2 Feb 2023 08:56:03 +0000 (GMT) List-Id: https://sourceware.org/git/gitweb.cgi?p=3Dbinutils-gdb.git;h=3D469b6d54d3a7= 39df64e48ce69f9c6eb37bec0c57 commit 469b6d54d3a739df64e48ce69f9c6eb37bec0c57 Author: Indu Bhagat Date: Thu Feb 2 00:47:22 2023 -0800 libsframe/doc: use "stack trace" instead of "unwind" for SFrame =20 SFrame format is meant for generating stack traces only. =20 libsframe/ * doc/sframe-spec.texi: Use "stack trace" instead of "unwind". Diff: --- 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''. =20 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: =20 @itemize @minus @item @@ -47,7 +47,7 @@ Return Address (RA). @end itemize =20 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. =20 @menu * Overview:: @@ -62,7 +62,7 @@ backtracing using a simple unwinder. @cindex Overview @tindex PT_GNU_SFRAME =20 -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 appear= s in a new segment of its own, PT_GNU_SFRAME. =20 @@ -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 SF= rame -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}. =20 @end multitable @@ -303,8 +303,9 @@ elements. @xref{SFrame Frame Row Entries}. @cindex SFrame ABI/arch identifier =20 SFrame header identifies the ABI/arch of the target system for which the -executable and it's unwind information is intended. There are currently t= hree -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 val= ues +in the format. =20 @multitable {SFRAME_ABI_AARCH64_ENDIAN_LITTLE} {Value} {@code{AARCH64 litt= le-endian}} @headitem ABI/arch Identifier @tab Value @tab Description @@ -324,7 +325,7 @@ identifiable ABI/arch values in the format. @end multitable =20 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. =20 @node SFrame Function Descriptor Entries @section SFrame FDE @@ -332,8 +333,8 @@ unwinders to make certain ABI-specific decisions. =20 The SFrame Function Descriptor Entry sub-section is a sorted array of fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFram= e 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. =20 @example typedef struct sframe_func_desc_entry @@ -459,7 +460,7 @@ to look up a matching FRE. @subsection The SFrame FRE types =20 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 tr= ace information for such a variety of function sizes. These representations v= ary in the number of bits needed to encode the start address offset in the SFr= ame FRE. @@ -488,21 +489,21 @@ The following constants are defined and used to ident= ify the SFrame FRE types: 32-bit value. @end multitable =20 -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}. =20 @node SFrame Frame Row Entries @section SFrame FRE @cindex SFrame FRE =20 -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. =20 -An SFrame Frame Row Entry is a self-sufficient record containing SFrame un= wind -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 st= ack +trace information for a range of contiguous addresses, starting at the +specified offset from the start of the function. Each SFrame Frame Row En= try +is followed by S*N bytes, where: =20 @itemize @minus @item