From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 99199C636D3 for ; Tue, 7 Feb 2023 20:20:42 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230231AbjBGUUl (ORCPT ); Tue, 7 Feb 2023 15:20:41 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58966 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229952AbjBGUUk (ORCPT ); Tue, 7 Feb 2023 15:20:40 -0500 Received: from mx0b-00069f02.pphosted.com (mx0b-00069f02.pphosted.com [205.220.177.32]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2ED1E3B0CD for ; Tue, 7 Feb 2023 12:20:30 -0800 (PST) Received: from pps.filterd (m0246632.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 317K5i8Z023789; Tue, 7 Feb 2023 20:20:27 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : content-type : mime-version; s=corp-2022-7-12; bh=mw/H8XkeTP5H+T+M8tDeyWzLWVYFky2SylX+qrzZdS4=; b=PBAYm9IxTH/+TmRj8Jf6rdUpdmTR86oIrfHKU2XCUAznlOx90fJUmtCRe8kdXG0Macde X1b+bQdErMy/kA0IyQBpYO1LaEZ8R1w9Xa9qgU28/R7SE3NTQrwv6OWZgJ4AwlyW6xYV HZar3LmG2Rc484q2RvzRyhTSXOL9dwZiAyRTm3MccW7iWPuiNQkTpzRcoMpb8CkgtM3F b58CpLqUZndfwNHYXHxw7zrRliK+iPiIzBSivTVlJV8KzOiwUH3dIJycSeucbsK9rh+D 5Lnp9SdjNOYlBYu3gFh3FKzsmPhta6Zl9xtbsgb0fPEeNsQZI477HbC1xi1+bTKyNjvY Rg== Received: from iadpaimrmta02.imrmtpd1.prodappiadaev1.oraclevcn.com (iadpaimrmta02.appoci.oracle.com [147.154.18.20]) by mx0b-00069f02.pphosted.com (PPS) with ESMTPS id 3nheytxmtt-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 07 Feb 2023 20:20:26 +0000 Received: from pps.filterd (iadpaimrmta02.imrmtpd1.prodappiadaev1.oraclevcn.com [127.0.0.1]) by iadpaimrmta02.imrmtpd1.prodappiadaev1.oraclevcn.com (8.17.1.5/8.17.1.5) with ESMTP id 317JZaIe028679; Tue, 7 Feb 2023 20:20:26 GMT Received: from nam11-bn8-obe.outbound.protection.outlook.com (mail-bn8nam11lp2168.outbound.protection.outlook.com [104.47.58.168]) by iadpaimrmta02.imrmtpd1.prodappiadaev1.oraclevcn.com (PPS) with ESMTPS id 3nhdtd7q4k-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 07 Feb 2023 20:20:23 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=PCKPr5mYyzabKa4voVkA/XH05b7Pt+CyqkCqhNjJ5x0ZjbvYJdA/qRibLT+/pkUldl6AEkIwH60LWZoJXyF3v3zG/bx8q8A4Obk9jtJ03Ww5UTvE+sjd58eEI9PRPp9/xY9VmklDJsIr/T9u+7zgx9rXDqTXn0sXn9uvHFRziFDiaypYjT6pnFhp/lklZo0MV5ajEclLq1JcEJdoqvicA/53lAYTYmJQBlFWERpj9KokY+HHkFFD/KlnCNN2ZeBaYdXo3Od1/8ChDoPgI5kW5GE6kGxWTNEoMpIEA9aFLjJRjyIhVe4vzVH0O6Qp1kAvgsZGbPs//NzPPZdCJxZGvw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=mw/H8XkeTP5H+T+M8tDeyWzLWVYFky2SylX+qrzZdS4=; b=c5Vz5M1HYoADDuT2MDkVPXQDMz0Gw/mze8k9Vhl4/gKn4HQkrJPCaxJZXWQ7R+6JMdCEgU4MqjSkdd2dq/RJt9uWobzs+LVcRrkTzqRqQ6VLtSlGHXl1CxQDbuRMwo0NxJFleGQ+ErwukVVj+oj/iJpVHaOjwb6wxo3Eo58GZBKXHu1OAk45A4zj5fDZ1UT3qryANeoLauLOWfeS3D9QI4Nd2rdTdZ83MgI7PgN3Ofco6eqpKB8lR/Q+8UggEqULBltwmYM18F6js1GeV39PfKuqVMs+jpWWRKm3FuvoetCGZow+YbXa5507foAFLkSjEDIySaQRIbogoTT7apImRw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=mw/H8XkeTP5H+T+M8tDeyWzLWVYFky2SylX+qrzZdS4=; b=TIgqa5N5sk5IZcAa4/4VN2PEjmtAcb5aQE4rS+MP68/O+Uuf59nLGH+sByqq6EcIzOJ2PJ5BAKO9dV7VHlRwFf7YEqgGn9h36xym5EpZ6No7ZA9fL/ZJhR/ZtVbUFiR8c34iU2lqPBWOwSqVLwNn4poMPyw0peuRmbmrB1x71Rw= Received: from BYAPR10MB2888.namprd10.prod.outlook.com (2603:10b6:a03:88::32) by IA1PR10MB5947.namprd10.prod.outlook.com (2603:10b6:208:3d5::13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6086.11; Tue, 7 Feb 2023 20:19:39 +0000 Received: from BYAPR10MB2888.namprd10.prod.outlook.com ([fe80::3cd3:9bef:83f:5a85]) by BYAPR10MB2888.namprd10.prod.outlook.com ([fe80::3cd3:9bef:83f:5a85%7]) with mapi id 15.20.6086.011; Tue, 7 Feb 2023 20:19:39 +0000 From: "Jose E. Marchesi" To: Steven Rostedt Cc: linux-toolchains@vger.kernel.org, Ross Zwisler Subject: SFrame spec Date: Tue, 07 Feb 2023 21:19:33 +0100 Message-ID: <87cz6lkz3e.fsf@oracle.com> User-Agent: Gnus/5.13 (Gnus v5.13) Content-Type: text/plain X-ClientProxiedBy: AM0PR01CA0151.eurprd01.prod.exchangelabs.com (2603:10a6:208:aa::20) To BYAPR10MB2888.namprd10.prod.outlook.com (2603:10b6:a03:88::32) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: BYAPR10MB2888:EE_|IA1PR10MB5947:EE_ X-MS-Office365-Filtering-Correlation-Id: 7b5ab7c8-54ba-47be-951e-08db0948a3c2 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: UV0upwv7G3Stk4lJX/q9Q6HOpMPn6DgJ2+60JGWatvWLCvcF5nWI2096UEljDbg/aKkRUf++QfdhaRa/dXKYOiQ7OQPUihUfzHL3fpS9eEWglP910GhFsgBEjoG5JvvJNT5GnsehFW7p8ofRIM37Jj0MGsBVHgENRLeRSeqa9KCO3pvWsUkzrEpkTwGe9Wk/r6DzmRVWlUj1Cqf4jH9DN56092H7rR/ofOmfS170OVhwaSgDewF9WpfTB9QbTfqLqIS5ZauLmwwwGQYJ51hbNYuDDgQ2rqS6zOrWKg+5f/elwjW4+J0bIqYqYiY5xCiLMJKwQzUi70OHMNZQHI5r1JNM0rQmjdb5HblWAh2Z1lSUsJxo/u+WGhRekrIUvdS/eAY9zSSqIlGiiqlWqE8IcL25lGnqJ8zOzZPgfijTgsujyJvxY4o7u02Bg05FCbzLYCKBBusy3jjpJu8tiEbe9lQDLuoByeJkhxzLKIIf9PVSCRxCkRBMpTjzp1A4bdq6yGtox8o0O0Im9mK4DBOnSZFkcBd+5VF6hYyIGVz02ZIUVnMx/RT+Vhi/fMGTmf3msQycxw1tv0dgtgNLdHmIQTmHWcw8gTZ+bsVUPgZCD4MRinVVbyRG89WYG8RYbQps87eO8fCiXt5OL8T2QEU7y+td1MVjOr3emxBJhXIYW6g= X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:BYAPR10MB2888.namprd10.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230025)(376002)(396003)(366004)(346002)(39860400002)(136003)(451199018)(86362001)(26005)(2616005)(6512007)(186003)(83380400001)(6666004)(3480700007)(6506007)(36756003)(38100700002)(66946007)(316002)(8676002)(6486002)(6916009)(66556008)(966005)(478600001)(4326008)(8936002)(5660300002)(41300700001)(66476007)(7116003)(30864003)(2906002);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?R0vC8YqAjsFsZOgl1ZwUQMoQPuJM5vw1ADAHpbh52sM4HO10RVw2W4gNOwwz?= =?us-ascii?Q?0E5ZnkbywVaYaWmU53vgjPMJn0S3+nTlyC/DLcxhaf9G/EsGifReLbPXeSFE?= =?us-ascii?Q?eb+tO4IoN0i5tWioX5TkBxDvEisnH7CB9wf3Wtn62cPpfpXTg/p8mogMUkHx?= =?us-ascii?Q?Awr4j+BhL98Fk46wk/o/y+BuWeknPh2jagiCZekVEmle2FqyovWbNW0HUZAo?= =?us-ascii?Q?LOBNbtir1i//LWIFJAg+F8bp3RXaN9pXmPnyk36G71MoA8X3KcpjvwgpGjZo?= =?us-ascii?Q?DHSq73U8Ol2kggnk64UzQ0vYe2t5BB/LtF7Sti+3PDl4gVveIuLWDiuq8zht?= =?us-ascii?Q?Kt9fAYpnGaX6cvH7dCFpJ1ERguvoN78172UGMAl8I7TpDASnQFJp+dD4gm2o?= =?us-ascii?Q?aZQDYo2r5BA/0VASgHLEvCm+TvP3PRveaaoNMTSVJkxVR7H4kx4AnPIqJd0c?= =?us-ascii?Q?ri38u20gUptJUwwLJaVzjOpcpWXKTPsJsVrFS7wHeavtbrNqUc0g7E7X5oCF?= =?us-ascii?Q?IzkmfeBOIBekODE8GwHukHlinB/q3LNZqfvcdsqlEzZltnRDB/6NWwnI9Vii?= =?us-ascii?Q?i7XHPx7R3WbP+5s+PcaiSHLyElYEjOxa72H6Qn11K4cjifl/azA0XpR1NybF?= =?us-ascii?Q?Rox6ECiYnyVqUPdQwKcDvmhvA72VX//5B4dz7rf7+ZCOzo0F50vsAHY5LN+i?= =?us-ascii?Q?f5HgX6ZA4YteQwLgesBCm8rjjEnbxks1KFEretcfPBSZEDfxVaL7N0+sREkD?= =?us-ascii?Q?Hv+7dl23n2IsQi3vwHur/wok6kFNTKIv24MPWhBkPzvm02l2iRE+QE6gJsY7?= =?us-ascii?Q?dJXDjIDQNNA7DHhh9lgqRSB02GIT7Rfi+L+BL8WrMiDJ5R7+YN4wzqAd93U2?= =?us-ascii?Q?aQ0gfZeyAd1iOv3OD7E7Z95KUVsMmCcuUxBZxYtkoifP/UE3q/IBtyUiOW+x?= =?us-ascii?Q?p5y/Ng7RJdB8t/fGlsq1qfNGY+HELRH8KNPflslf+oKBHCeGbE17oF874TUE?= =?us-ascii?Q?mS2FOGG0VaSxiM7NmfIFFWGrKfpfNvsF0Nsy0aF/LmG6E0Ejb33mHasO014w?= =?us-ascii?Q?Hvixj2bz/eNNfXRqQqO8sw3CoY16JkhZf+8nM+u7dnBczPrJWV6gIw8w5bmv?= =?us-ascii?Q?zGjstt5PUhxAEEDdxsjx7XhbLXAQl3uHRKmemaH5Xgcr08boDhXB5gAi6lfE?= =?us-ascii?Q?OjcJNd28kwoCy+Qn2ODvLYQYDZXFUnYuXCm9GHSJbMT58kprJdUf6hUW+xII?= =?us-ascii?Q?0xOKSDmxorNZDZKeiJLBzoZH7o9GKatVOF3g+f/RTSOxv7Q40ZEpXDeWbe2i?= =?us-ascii?Q?roU4bZ00JaqYwXV3shVLirDk1FRxHm0izFWQGcx5RPSWCEtkGEV3KjF4OTLm?= =?us-ascii?Q?y3qlokWB8ZxAwieFo5DGsZQJX+zbjdq6AbqLYTBg9fJjsfVDOzJ4fnex8hSH?= =?us-ascii?Q?OuxkpWTf4qSpt1xnX2wMuWSyjL0JhjLWU+EGlBpq/WFmCeP1LHuB/B3Kzu8w?= =?us-ascii?Q?9iiHVLDx3Cr94GUsBofyDaXwZq2g+VuoZKH0OyZjuPNYlbZC1mEYFXCgXCcA?= =?us-ascii?Q?ymmRPZvAOEWRFJjEpm9JKiniNSA4k1/U23+ml26bPy4PJUpR0bwYccnJEKVQ?= =?us-ascii?Q?CA=3D=3D?= X-MS-Exchange-AntiSpam-ExternalHop-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-ExternalHop-MessageData-0: 8YgrdKhWXyGBE/w2DvsJ8TOHgdhFWXc+WEFfLp9sP9n1JAFPtIaB8G98RJLzzCo90ujIVV83pm+x7MILV0WMtEbgTJvQaWYvPInzpsQ/C3HO2KX4Mz03zWieXU7OFsuADTMteAoXcy7KS8WLK7c/rfeB9HM7AyVtvFacHmkEgCDBzI4+etxktgf0fyDWlyRp0AZ7UVOK+HY8H2N2UCl69ZgzX2gEYKsGxuj/LQyIbKt4BNQvFz+DOGX7jXA3QNZf+zbShTMFx8atQqIvYgWNwlrIIcypK/KT/B2okZuaFoyB6oJ35qFnM2bYhQYGq+KsghcfadUcqfcy9/iwZM1g84rJ57gacNW97oXEDFT9zr7ng+jB2P9kp9FIHyj16S7YArYoriK49Odb2PfrCGnabOqkJqQzf2gmmc6b6ig5fe8xQB5mUTgCkgg0whuxqNnkXA8OPkcQ9mMrTOqHQPKG/YUbMRIKIzjoDHlgz4KAi0AI+O1iTRAnKJvRE9M6x3Ee8m8PXuKDIaQ1UzUO4Ora/Khmf6SKP8HPUxiCK8wRCx7KEZnP/PMz5fVvdSfIVHTSTe6+rHy+iWER1aQN1YatuidJMvfNLpGbCpHES1OKGi9JkLNQZ6DE3Sab9UOVggxFDtoLX76i5OG+dM2ixfaC/31QhAqQmVhwWZNb8gI5041fwF9Td/w4IIXb/w0CDTcSOQt5XcVQ+J63ZTn14+OTGXcmJ+ov4FsVv0Oz0IJXVMdRozrQwf3Ao6Vk1OUDf5cAmso4xHZqqXI0vzRn/jAHqmxsSReaHU0RnQZQMBuDGe9SpUzfX16XYqlPRvLVr6/c X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-Network-Message-Id: 7b5ab7c8-54ba-47be-951e-08db0948a3c2 X-MS-Exchange-CrossTenant-AuthSource: BYAPR10MB2888.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 07 Feb 2023 20:19:39.6384 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: JREGoZBnhPlJNgRBzelzR8skAm2Bs5foQ6U964kSKXJXesd5DpdvY2oKrBD6RkA8pKeDGx56rRWz+91SW+E4G26KBtLiF/okDLvxVZclf7k= X-MS-Exchange-Transport-CrossTenantHeadersStamped: IA1PR10MB5947 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.219,Aquarius:18.0.930,Hydra:6.0.562,FMLib:17.11.122.1 definitions=2023-02-07_12,2023-02-06_03,2022-06-22_01 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 bulkscore=0 mlxlogscore=999 malwarescore=0 adultscore=0 phishscore=0 suspectscore=0 mlxscore=0 spamscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2212070000 definitions=main-2302070176 X-Proofpoint-GUID: oe5Vs8goXkpEPu50AovVS8KqgwQuwGBp X-Proofpoint-ORIG-GUID: oe5Vs8goXkpEPu50AovVS8KqgwQuwGBp Precedence: bulk List-ID: X-Mailing-List: linux-toolchains@vger.kernel.org Hi Steven, Ross, all. Find below a plain text rendering of the SFrame format specification. It documents the current version of the format (version 1). The source of the spec lives in the upstream binutils repo: https://sourceware.org/git?p=binutils-gdb.git;a=blob;f=libsframe/doc/sframe-spec.texi As we discussed during FOSDEM, it is very likely the format will need adjustments and improvements due to practical reasons not foreseen during the development of the format. The SFrame format Overview 1 SFrame section 1.1 SFrame Preamble 1.1.1 SFrame endianness 1.1.2 SFrame version 1.1.3 SFrame flags 1.2 SFrame Header 1.2.1 SFrame ABI/arch identifier 1.3 SFrame FDE 1.3.1 The SFrame FDE info word 1.3.2 The SFrame FDE types 1.3.3 The SFrame FRE types 1.4 SFrame FRE 1.4.1 The SFrame FRE info word Index The SFrame format ***************** 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 generating stack traces: - Canonical Frame Address (CFA). - Frame Pointer (FP). - Return Address (RA). The reason for existence of the SFrame format is to support fast, online generation of stack traces using simple means. Overview ******** The SFrame stack trace information is provided in a loaded section, known as the '.sframe' section. When available, the '.sframe' section appears in a new segment of its own, PT_GNU_SFRAME. The SFrame format is currently supported only for select ABIs, namely, AMD64 and AAPCS64. The contents of the SFrame section are stored in the target endianness, i.e., in the endianness of the system on which the section is targetted to be used. An SFrame section reader may use the magic number in the SFrame header to identify the endianness of the SFrame section. Addresses in this specification are expressed in bytes. The associated API to decode, probe and encode the SFrame section, provided via 'libsframe', is not accompanied here at this time. This will be added later. This document is intended to be in sync with the C code in 'sframe.h'. Please report descrepancies between the two, if any. 1 SFrame section **************** The SFrame section consists of an SFrame header, starting with a preamble, and two other sub-sections, namely the SFrame Function Descriptor Entry (SFrame FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section. 1.1 SFrame Preamble =================== The preamble is a 32-bit packed structure; the only part of the SFrame whose format cannot vary between versions. typedef struct sframe_preamble { uint16_t sfp_magic; uint8_t sfp_version; uint8_t sfp_flags; } ATTRIBUTE_PACKED sframe_preamble; All values are stored in the endianness of the target system for which the SFrame section is intended. Further details: Offset Name Description ----------------------------------------------------------------------------------------- 0x00 'uint16_t sfp_magic' The magic number for SFrame section: 0xdee2. Defined as a macro 'SFRAME_MAGIC'. 0x02 'uint8_t sfp_version' The version number of this SFrame section. *Note SFrame version::, for the set of valid values. Current version is 'SFRAME_VERSION_1'. 0x03 'uint8_t sfp_flags' Flags (section-wide) for this SFrame section. *Note SFrame flags::, for the set of valid values. 1.1.1 SFrame endianness ----------------------- SFrame sections are stored in the target endianness of the system that consumes them. The SFrame library ('libsframe') can, however, detect whether to endian-flip an SFrame section at decode time, by inspecting the 'sfp_magic' field in the SFrame header (If it appears as 0xe2de, endian-flipping is needed). 1.1.2 SFrame version -------------------- The version of the SFrame format can be determined by inspecting 'sfp_version'. The following versions are currently valid: Version Number Description ---------------------------------------------------------------- 'SFRAME_VERSION_1' 1 First version, under development. This section documents 'SFRAME_VERSION_1'. 1.1.3 SFrame flags ------------------ The preamble contains bitflags in its 'sfp_flags' field that describe various section-wide properties. The following flags are currently defined. Flag Versions Value Meaning ---------------------------------------------------------------------------- 'SFRAME_F_FDE_SORTED' All 0x1 Function Descriptor Entries are sorted on PC. 'SFRAME_F_FRAME_POINTER' All 0x2 Functions preserve frame-pointer. Further flags may be added in future. 1.2 SFrame Header ================= The SFrame header is the first part of an SFrame section. It begins with the SFrame preamble. All parts of it other than the preamble (*note SFrame Preamble::) can vary between SFrame file versions. It contains things that apply to the section as a whole, and offsets to the various other sub-sections defined in the format. As with the rest of the SFrame section, all values are stored in the endianness of the target system. The two sub-sections tile the SFrame section: each section runs from the offset given until the start of the next section. An explicit length is given for the last sub-section, the SFrame Frame Row Entry (SFrame FRE) sub-section. typedef struct sframe_header { sframe_preamble sfh_preamble; uint8_t sfh_abi_arch; int8_t sfh_cfa_fixed_fp_offset; int8_t sfh_cfa_fixed_ra_offset; uint8_t sfh_auxhdr_len; uint32_t sfh_num_fdes; uint32_t sfh_num_fres; uint32_t sfh_fre_len; uint32_t sfh_fdeoff; uint32_t sfh_freoff; } ATTRIBUTE_PACKED sframe_header; The sub-section offsets, namely 'sfh_fdeoff' and 'sfh_freoff', in the SFrame header are relative to the _end_ of the SFrame header; they are each an offset in bytes into the SFrame section where the SFrame FDE sub-section and the SFrame FRE sub-section respectively start. SFrame header allows specifying explicitly the fixed offsets from CFA, if any, from which FP or RA may be recovered. For example, in AMD64, the stack offset of the return address is 'CFA - 8'. Since this offset is in close vicinity with the CFA in most ABIs, 'sfh_cfa_fixed_fp_offset' and 'sfh_cfa_fixed_ra_offset' are limited to signed 8-bit integers. SFrame format has provisioned for future ABIs/architectures that it may support. The 'sframe_header' structure provides an unsigned 8-bit integral field to denote the size of an auxilliary SFrame header. The auxilliary SFrame header follows right after the 'sframe_header' structure. As for the offset calculations, the _end_ of SFrame header must be the end of the auxilliary SFrame header, if the latter is present. Tieing it all together: Offset Name Description ---------------------------------------------------------------------------------------- 0x00 'sframe_preamble sfh_preamble' The SFrame preamble. *Note SFrame Preamble::. 0x04 'uint8_t sfh_abi_arch' The ABI/arch identifier. *Note SFrame ABI/arch identifier::. 0x05 'int8_t sfh_cfa_fixed_fp_offset' The CFA fixed FP offset, if any. 0x06 'int8_t sfh_cfa_fixed_ra_offset' The CFA fixed RA offset, if any. 0x07 'uint8_t sfh_auxhdr_len' Size in bytes of the auxilliary header that follows the 'sframe_header' structure. 0x08 'uint32_t sfh_num_fdes' The number of SFrame FDEs in the section. 0xc 'uint32_t sfh_num_fres' The number of SFrame FREs in the section. 0x10 'uint32_t sfh_fre_len' The length in bytes of the SFrame FRE sub-section. 0x14 'uint32_t sfh_fdeoff' The offset in bytes of the SFrame FDE sub-section. This sub-section contains 'sfh_num_fdes' number of fixed-length array elements. The array element is of type SFrame function desciptor entry, each providing a high-level function description for backtracing. *Note SFrame Function Descriptor Entries::. 0x18 'uint32_t sfh_freoff' The offset in bytes of the SFrame FRE sub-section, the core of the SFrame section, which describes the stack trace information using variable-length array elements. *Note SFrame Frame Row Entries::. 1.2.1 SFrame ABI/arch identifier -------------------------------- SFrame header identifies the ABI/arch of the target system for which the 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. ABI/arch Identifier Value Description --------------------------------------------------------------------- 'SFRAME_ABI_AARCH64_ENDIAN_BIG' 1 AARCH64 big-endian 'SFRAME_ABI_AARCH64_ENDIAN_LITTLE' 2 AARCH64 little-endian 'SFRAME_ABI_AMD64_ENDIAN_LITTLE' 3 AMD64 little-endian The presence of an explicit identification of ABI/arch in SFrame may allow stack trace generators to make certain ABI-specific decisions. 1.3 SFrame FDE ============== 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 stack trace information at a high-level. typedef struct sframe_func_desc_entry { int32_t sfde_func_start_address; uint32_t sfde_func_size; uint32_t sfde_func_start_fre_off; uint32_t sfde_func_num_fres; uint8_t sfde_func_info; } ATTRIBUTE_PACKED sframe_func_desc_entry; 'sfde_func_start_fre_off' is the offset to the first SFrame FRE for the function. This offset is relative to the _end of the SFrame FDE_ sub-section (unlike the offsets in the SFrame header, which are relative to the _end_ of the SFrame header). 'sfde_func_info' is the "info word", containing information on the FRE type and the FDE type for the function *Note The SFrame FDE info word::. Following table describes each component of the SFrame FDE structure: Offset Name Description ------------------------------------------------------------------------------------ 0x00 'int32_t sfde_func_start_address' Signed 32-bit integral field denoting the virtual memory address of the described function. 0x04 'uint32_t sfde_func_size' Unsigned 32-bit integral field specifying the size of the function in bytes. 0x08 'uint32_t sfde_func_start_fre_off' Unsigned 32-bit integral field specifying the offset in bytes of the function's first SFrame FRE in the SFrame section. 0x0c 'uint32_t sfde_func_num_fres' Unsigned 32-bit integral field specifying the total number of SFrame FREs used for the function. 0x10 'uint8_t sfde_func_info' The SFrame FDE info word. *Note The SFrame FDE info word::. 1.3.1 The SFrame FDE info word ------------------------------ The info word is a bitfield split into three parts. From MSB to LSB: Bit offset Name Description ---------------------------------------------------------------------------------------- 7-6 'unused' Unused bits. 5 'pauth_key' Specify which key is used for signing the return addresses in the SFrame FDE. Two possible values: SFRAME_AARCH64_PAUTH_KEY_A (0), or SFRAME_AARCH64_PAUTH_KEY_B (1). 4 'fdetype' Specify the SFrame FDE type. Two possible values: SFRAME_FDE_TYPE_PCMASK (1), or SFRAME_FDE_TYPE_PCINC (0). *Note The SFrame FDE types::. 0-3 'fretype' Choice of three SFrame FRE types. *Note The SFrame FRE types::. 1.3.2 The SFrame FDE types -------------------------- SFrame format defines two types of FDE entries. The choice of which SFrame FDE type to use is made based on the instruction patterns in the relevant program stub. An SFrame FDE of type 'SFRAME_FDE_TYPE_PCINC' is an indication that the PCs in the FREs should be treated as increments in bytes. This is used fo the the bulk of the executable code of a program, which contains instructions with no specific pattern. In contrast, an SFrame FDE of type 'SFRAME_FDE_TYPE_PCMASK' is an indication that the PCs in the FREs should be treated as masks. This type is useful for the cases where a small pattern of instructions in a program stub is used repeatedly for a specific functionality. Typical usecases are pltN entries and trampolines. Name of SFrame FDE Value Description type --------------------------------------------------------------------------- SFRAME_FDE_TYPE_PCINC 0 Unwinders perform a (PC >= FRE_START_ADDR) to look up a matching FRE. SFRAME_FDE_TYPE_PCMASK 1 Unwinders perform a (PC & FRE_START_ADDR_AS_MASK >= FRE_START_ADDR_AS_MASK) to look up a matching FRE. 1.3.3 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 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. The following constants are defined and used to identify the SFrame FRE types: Name Value Description -------------------------------------------------------------------------- 'SFRAME_FRE_TYPE_ADDR1' 0 The start address offset (in bytes) of the SFrame FRE is an unsigned 8-bit value. 'SFRAME_FRE_TYPE_ADDR2' 1 The start address offset (in bytes) of the SFrame FRE is an unsigned 16-bit value. 'SFRAME_FRE_TYPE_ADDR4' 2 The start address offset (in bytes) of the SFrame FRE is an unsigned 32-bit value. 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 *Note The SFrame FDE info word::. 1.4 SFrame FRE ============== 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 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: - 'S' is the size of the stack frame offset for the FRE, and - 'N' is the number of stack frame offsets in the FRE The stack offsets, following the FRE, are interpreted in order as follows: - The first offset is always used to locate the CFA, by interpreting it as: CFA = 'BASE_REG' + offset1. - If RA is being tracked, the second offset is always used to locate the RA, by interpreting it as: RA = CFA + offset2. If RA is _not_ being tracked _and_ FP is being tracked, the second offset will be used to locate the FP, by interpreting it as: FP = CFA + offset2. - If both RA and FP are being tracked, the third offset will be used to locate the FP, by interpreting it as FP = CFA + offset3. The entities 'S', 'N' and 'BASE_REG' are identified using the SFrame FRE info word, a.k.a. the 'sframe_fre_info' *Note The SFrame FRE info word::. Following are the definitions of the allowed SFrame FRE: typedef struct sframe_frame_row_entry_addr1 { uint8_t sfre_start_address; sframe_fre_info sfre_info; } ATTRIBUTE_PACKED sframe_frame_row_entry_addr1; typedef struct sframe_frame_row_entry_addr2 { uint16_t sfre_start_address; sframe_fre_info sfre_info; } ATTRIBUTE_PACKED sframe_frame_row_entry_addr2; typedef struct sframe_frame_row_entry_addr4 { uint32_t sfre_start_address; sframe_fre_info sfre_info; } ATTRIBUTE_PACKED sframe_frame_row_entry_addr4; 'sfre_start_address' is an unsigned 8-bit/16-bit/32-bit integral field identifies the start address of the range of program counters, for which the SFrame FRE applies. The value encoded in the 'sfre_start_address' field is the offset in bytes of the start address of the SFrame FRE, from the start address of the function. Further FRE types may be added in future. 1.4.1 The SFrame FRE info word ------------------------------ The SFrame FRE info word is a bitfield split into four parts. From MSB to LSB: Bit offset Name Description ------------------------------------------------------------------------------------- 7 'fre_mangled_ra_p' Indicate whether the return address is mangled with any authorization bits (signed RA). 5-6 'fre_offset_size' Size of stack offsets in bytes. Valid values are: SFRAME_FRE_OFFSET_1B, SFRAME_FRE_OFFSET_2B, and SFRAME_FRE_OFFSET_4B. 1-4 'fre_offset_count' A value of upto 3 is allowed to track all three of CFA, FP and RA. 0 'fre_cfa_base_reg_id' Distinguish between SP or FP based CFA recovery. Name Value Description -------------------------------------------------------------------------------- 'SFRAME_FRE_OFFSET_1B' 0 All stack offsets following the fixed-length FRE structure are 1 byte long. 'SFRAME_FRE_OFFSET_2B' 1 All stack offsets following the fixed-length FRE structure are 2 bytes long. 'SFRAME_FRE_OFFSET_4B' 2 All stack offsets following the fixed-length FRE structure are 4 bytes long. Index ***** * Menu: * endianness: SFrame endianness. (line 94) * Overview: Overview. (line 33) * PT_GNU_SFRAME: Overview. (line 33) * SFrame ABI/arch identifier: SFrame ABI/arch identifier. (line 224) * SFrame FDE: SFrame Function Descriptor Entries. (line 245) * SFrame flags: SFrame flags. (line 115) * SFrame FRE: SFrame Frame Row Entries. (line 380) * SFrame header: SFrame Header. (line 132) * SFrame preamble: SFrame Preamble. (line 66) * SFrame section: SFrame section. (line 58) * SFrame versions: SFrame version. (line 106) * SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch identifier. (line 231) * SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch identifier. (line 234) * SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch identifier. (line 236) * SFRAME_FDE_TYPE_PCINC: The SFrame FDE types. (line 318) * SFRAME_FDE_TYPE_PCMASK: The SFrame FDE types. (line 318) * SFRAME_FRE_OFFSET_1B: The SFrame FRE info word. (line 462) * SFRAME_FRE_OFFSET_2B: The SFrame FRE info word. (line 466) * SFRAME_FRE_OFFSET_4B: The SFrame FRE info word. (line 469) * SFRAME_FRE_TYPE_ADDR1: The SFrame FRE types. (line 360) * SFRAME_FRE_TYPE_ADDR2: The SFrame FRE types. (line 365) * SFRAME_FRE_TYPE_ADDR4: The SFrame FRE types. (line 369) * SFRAME_F_FDE_SORTED: SFrame flags. (line 120) * SFRAME_F_FRAME_POINTER: SFrame flags. (line 123) * SFRAME_MAGIC: SFrame Preamble. (line 82) * SFRAME_VERSION_1: SFrame version. (line 106) * The SFrame FDE info word: SFrame Function Descriptor Entries. (line 292) * The SFrame FRE info word: SFrame Frame Row Entries. (line 434)