From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR05-AM6-obe.outbound.protection.outlook.com (mail-am6eur05on2052.outbound.protection.outlook.com [40.107.22.52]) by sourceware.org (Postfix) with ESMTPS id 0F01438768BB for ; Tue, 22 Aug 2023 11:21:56 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 0F01438768BB Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=arm.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=arm.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=gOfvS1n1ip3VtqMrE5NooJImQT6N+PPYyZFh7g2xMPA=; b=KibXPpXNFu84zLNUdpLQdp6e7kWJ3nZew7CvpIPJZ1s4Ae74BsZosNafTQunY6Sl5uGDyeAf4Sb6Om3O6G5MOEsQr1l0pNhnArinRKri7Evxf6MZRKy3pK4+gzpTriuxMYA6dHh+nfG8F8qky5kVnJgb41cjeNAVabuNoz5/gHg= Received: from AS9PR05CA0246.eurprd05.prod.outlook.com (2603:10a6:20b:493::21) by GV1PR08MB7684.eurprd08.prod.outlook.com (2603:10a6:150:63::11) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6699.20; Tue, 22 Aug 2023 11:21:53 +0000 Received: from AM7EUR03FT038.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:493:cafe::97) by AS9PR05CA0246.outlook.office365.com (2603:10a6:20b:493::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6699.20 via Frontend Transport; Tue, 22 Aug 2023 11:21:53 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 63.35.35.123) smtp.mailfrom=arm.com; dkim=pass (signature was verified) header.d=armh.onmicrosoft.com;dmarc=pass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 63.35.35.123 as permitted sender) receiver=protection.outlook.com; client-ip=63.35.35.123; helo=64aa7808-outbound-1.mta.getcheckrecipient.com; pr=C Received: from 64aa7808-outbound-1.mta.getcheckrecipient.com (63.35.35.123) by AM7EUR03FT038.mail.protection.outlook.com (100.127.140.120) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6723.15 via Frontend Transport; Tue, 22 Aug 2023 11:21:52 +0000 Received: ("Tessian outbound 30c9f5e988c5:v175"); Tue, 22 Aug 2023 11:21:52 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: c269b286872c92b6 X-CR-MTA-TID: 64aa7808 Received: from 35244d613464.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id 3F603843-132C-4581-83CD-9B47C84DAF48.1; Tue, 22 Aug 2023 11:21:45 +0000 Received: from EUR01-HE1-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id 35244d613464.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Tue, 22 Aug 2023 11:21:45 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=WgquNeCwNBHEO3dcGUjEqVmPgejFgXS0jYxDmDIkZ5hFkvbMSKF3BNwuE7P1FxyoHr99wVDARZ3uOhrztvMwQbjaAkbJHLR8/QUE7VpJvcIxdUrOB17Hcl/t9fJ/yFBGdH4aW4KFD7IcXv8J2HSKEzVrj35IcSVxmUrZqVHoHbyhgGhqMvujPOpKmrjS6mHGCmqz6Bah2KOHaMHp6uIIQ8iIIMLqz1emnG94lhK2e42TleV3kKt7UBd4kquS8sFauvsIXmY3wo3ZwYvJTG2gmkpO3OagjrQOa80Y3gDLHGBSLS30qoGskk2EG3P1s4Bt25SSz0sGRQhxvU6cRQluwg== 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=gOfvS1n1ip3VtqMrE5NooJImQT6N+PPYyZFh7g2xMPA=; b=hXbzIjaySzL66UQ4sDCqwymzqtUcf3M4ZZfcrhgOFklbRT8Byj0ByA0DBYj2UKHoRBUzQFBOntQWX37nCQkRqNvDN89Dqn7ILoes3j5EqCr3w9xSj5Rl7nuGvtg4i1ZvPKtXThGI+rYjeojYllZ88CxJvjTI92cXmTDUKDJ84T5cIm3vNAFkh4+xFi5vWVIYcBGp9SwVkX84DOv3o0XDCcJJzJ06LynMlYif2Jh1wL5S9AxqQuix8N7WsudcXDx3248EpCEzbXGZahZRqiXLtGzBsppfC+6ZDUIpoow2VLbOlhN7nrA3h1j9Uay8HkPRSUD2qe2HCZofmqjdpp6s/w== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 40.67.248.234) smtp.rcpttodomain=sourceware.org smtp.mailfrom=arm.com; dmarc=pass (p=none sp=none pct=100) action=none header.from=arm.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=gOfvS1n1ip3VtqMrE5NooJImQT6N+PPYyZFh7g2xMPA=; b=KibXPpXNFu84zLNUdpLQdp6e7kWJ3nZew7CvpIPJZ1s4Ae74BsZosNafTQunY6Sl5uGDyeAf4Sb6Om3O6G5MOEsQr1l0pNhnArinRKri7Evxf6MZRKy3pK4+gzpTriuxMYA6dHh+nfG8F8qky5kVnJgb41cjeNAVabuNoz5/gHg= Received: from AS9PR07CA0011.eurprd07.prod.outlook.com (2603:10a6:20b:46c::18) by AS8PR08MB6248.eurprd08.prod.outlook.com (2603:10a6:20b:298::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6699.24; Tue, 22 Aug 2023 11:21:41 +0000 Received: from AM7EUR03FT027.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:46c:cafe::17) by AS9PR07CA0011.outlook.office365.com (2603:10a6:20b:46c::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6699.15 via Frontend Transport; Tue, 22 Aug 2023 11:21:41 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 40.67.248.234) smtp.mailfrom=arm.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 40.67.248.234 as permitted sender) receiver=protection.outlook.com; client-ip=40.67.248.234; helo=nebula.arm.com; pr=C Received: from nebula.arm.com (40.67.248.234) by AM7EUR03FT027.mail.protection.outlook.com (100.127.140.124) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.6723.15 via Frontend Transport; Tue, 22 Aug 2023 11:21:41 +0000 Received: from AZ-NEU-EX04.Arm.com (10.251.24.32) by AZ-NEU-EX03.Arm.com (10.251.24.31) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.27; Tue, 22 Aug 2023 11:21:38 +0000 Received: from e129171.cambridge.arm.com (10.1.34.58) by mail.arm.com (10.251.24.32) with Microsoft SMTP Server id 15.1.2507.27 via Frontend Transport; Tue, 22 Aug 2023 11:21:38 +0000 From: Luis Machado To: CC: Subject: [PATCH v4 16/16] [gdb/docs] sme: Document SME registers and features Date: Tue, 22 Aug 2023 12:21:30 +0100 Message-ID: <20230822112130.1513216-17-luis.machado@arm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20230822112130.1513216-1-luis.machado@arm.com> References: <20230822112130.1513216-1-luis.machado@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain X-EOPAttributedMessage: 1 X-MS-TrafficTypeDiagnostic: AM7EUR03FT027:EE_|AS8PR08MB6248:EE_|AM7EUR03FT038:EE_|GV1PR08MB7684:EE_ X-MS-Office365-Filtering-Correlation-Id: ffaac668-5747-44c2-5fa8-08dba301fc89 x-checkrecipientrouted: true NoDisclaimer: true X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam-Untrusted: BCL:0; X-Microsoft-Antispam-Message-Info-Original: YSQcSf7ONX9S+3yHTS9Pzls6bxdSCUo6w31Xb3qJYcwNETze07J1yquGuWkGFlJK8o2N3Y9FOXBKQK3BphbU4uG/D9dyXsV/UWLcZstTHHbxWqvSuxRDU7DnKxa8BuCQ62V8+HDDthKtGAXI5p4MD7olIzhuK1aiV9q1LDufj8LBK3J894wVPqmOVXkGlBL0mfhocBQOSGDBC2Sop/CHoeQvYn0x13d7yjxGKg48K9QEdN2Ozcjh4lv/Ivk0rWWl7j09gzt8vqWzMSLiAiXAswf8jBLIbv2Bp+1eWqfLzTOLZxrxdqi9sppF1/5UH7Q6XkoLUPybAJtqd4xaZiQJ60XkyCMLW4v8f4LLw8pLUKi9qskeY0wyK2U4YB1IuJ9BVyvFYKDFR6ujUzFN/PyjNEvWtLvWC6vmNxq3jhU5ObWTCwyRMLUd0YLuCYzRr8YZIRIS1A0K2KJ7VODZvSda3f1K3de7J6rs+9KqgAvOA3S2gDykKFgIDhDxyhc1i8R3+02N/oXuWF1c/NW3gEPjt+4CDCYsUih6h8dew13qUT1OlFPlhQc6sqvd1kVPvEdjuepI2q/UTsT8uSGe9nuVilDojqzLcYv7wvcNmqF5YYJHIItkyHMj9Zon70jJek3MXC5VwoMJKw/aSz63L+10CJ7bxxOL9SNK7vHL5x7EinDB+yaLg66SRtmOudQz1AEI4i9X6bYcwxbsSj5B5CCFHupXwdKUevqgtSaAxfdhDxWf2u2W7vEeaa23uAfZl5jppRoWgAxEU8SBb2oEwRohNyXrR3cm6Vxs/SON9YJ+PnI= X-Forefront-Antispam-Report-Untrusted: CIP:40.67.248.234;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:nebula.arm.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(13230031)(4636009)(136003)(376002)(396003)(39860400002)(346002)(1800799009)(186009)(451199024)(82310400011)(36840700001)(40470700004)(46966006)(6916009)(316002)(70586007)(70206006)(8676002)(8936002)(2616005)(4326008)(36756003)(40460700003)(41300700001)(1076003)(82740400003)(356005)(81166007)(478600001)(6666004)(40480700001)(83380400001)(30864003)(2906002)(86362001)(47076005)(7696005)(36860700001)(336012)(44832011)(426003)(5660300002)(26005)(36900700001);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS8PR08MB6248 X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM7EUR03FT038.eop-EUR03.prod.protection.outlook.com X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id-Prvs: 0cfabc5a-c606-4e30-f5dc-08dba301f584 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: JQ+VvES7E61eXsdP+TLWKmVUKUD0TYH2z7RAWsb2HA9Xa46XEwp1J3kvF08llED+Nf7mzb84qscE3zB01ph9t1b6YZVRnDf+BTY3F5JrtQ8YTvlpGNp0Y5vb2ZcoQINz/DTAkKdFKM3YqCWOa69C+WbabIUQiJ21zMlQWSW5DY+0pKb9zUapmUH2VCF4Rx5N4iyOmHwCcOq9p66ZXLQv4CHjzYgGVKitFUhACLcaMXpBuIAiP9m/6x7YvfNmUQappRa5LM1LuYMsT5Djka/dmCYRZgYH7WhuTysCG1kOlxg1WCrJNsgit/OTjqqrJXYXS23HZREotVGNxwoNcWpZuAXVzX+qbMVg7A6WxGUk9FdvDvJKmcivV6LubWYKyx1Zh7BgkEPQiqU2kUam5+anRzDTPosR1qWhxVZnq5oWwfYmMPf8pf0JxKww4xQDdrSaJPd6/I1TwbGtssWPP0nNdwoUjJnE83eVqDNVc69yni5d69UBE9y7PMSyMtASFLfRgo0j/1qCqwo4rerSYNhoPQJqaqwWUXKW7v9Nn6lKy4DA8Br8FWKdXvltkbtPcQHK4Dj9Us3KTvDTNTdheyJi8Di6xGs4flVquizHFKOyX/QWHdTLQK6k9T8Dw8P317FNZOReoH4z/aoBMO9wK6c5ITfy2Fwu3DhpBUfz2lsfUK6JPZWOgUOEerhGCSmdDWjVl7K9lSKT6tsjEGPYzsmTtFiY61yneWGKdrqSRrHiXthFE4sjlzOaPYhp3htYzsII6LL0tzMUAW7s1PjEEEC1dg== X-Forefront-Antispam-Report: CIP:63.35.35.123;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:64aa7808-outbound-1.mta.getcheckrecipient.com;PTR:ec2-63-35-35-123.eu-west-1.compute.amazonaws.com;CAT:NONE;SFS:(13230031)(4636009)(136003)(39860400002)(376002)(346002)(396003)(186009)(82310400011)(1800799009)(451199024)(36840700001)(40470700004)(46966006)(86362001)(40480700001)(36756003)(81166007)(478600001)(40460700003)(6916009)(41300700001)(70206006)(316002)(70586007)(82740400003)(26005)(6666004)(7696005)(47076005)(1076003)(336012)(426003)(107886003)(5660300002)(8676002)(2906002)(4326008)(2616005)(36860700001)(44832011)(30864003)(8936002)(83380400001);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 22 Aug 2023 11:21:52.9432 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: ffaac668-5747-44c2-5fa8-08dba301fc89 X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d;Ip=[63.35.35.123];Helo=[64aa7808-outbound-1.mta.getcheckrecipient.com] X-MS-Exchange-CrossTenant-AuthSource: AM7EUR03FT038.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV1PR08MB7684 X-Spam-Status: No, score=-11.8 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,FORGED_SPF_HELO,GIT_PATCH_0,KAM_DMARC_NONE,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_NONE,TXREP,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Updates since v2: - More adjustments based on reviews. - Fixed incorrect number of tile pseudo-registers. - Fixed naming of tile slice pseudo-registers. - More detail about SME and how gdb implements it. - Attempted to clarify the text a bit more. Updates since v1: - Made SME text more thorough. - Adjusted text based on upstream reviews. - Fixed documentation errors (missing itemization for SME registers). Provide documentation for the SME feature and other information that should be useful for users that need to debug a SME-capable target. Reviewed-By: Eli Zaretskii Signed-off-by: Luis Machado --- gdb/NEWS | 11 ++ gdb/doc/gdb.texinfo | 249 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 260 insertions(+) diff --git a/gdb/NEWS b/gdb/NEWS index c4b1f7a7e3b..49acc765ea7 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -3,6 +3,17 @@ *** Changes since GDB 13 +* GDB now supports the AArch64 Scalable Matrix Extension (SME), which includes + a new matrix register named ZA, a new thread register TPIDR2 and a new vector + length register SVG (streaming vector granule). GDB also supports tracking + ZA state across signal frames. + + Some features are still under development or are dependent on ABI specs that + are still in alpha stage. For example, manual function calls with ZA state + don't have any special handling, and tracking of SVG changes based on + DWARF information is still not implemented, but there are plans to do so in + the future. + * The AArch64 'org.gnu.gdb.aarch64.pauth' Pointer Authentication feature string has been deprecated in favor of the 'org.gnu.gdb.aarch64.pauth_v2' feature string. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 8be9725d1a2..23a40f0e8de 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -26140,6 +26140,224 @@ but the lengths of the @code{z} and @code{p} registers will not change. This is a known limitation of @value{GDBN} and does not affect the execution of the target process. +For SVE, the following definitions are used throughout @value{GDBN}'s source +code and in this document: + +@itemize + +@item +@var{vl}: The vector length, in bytes. It defines the size of each @code{z} +register. +@anchor{vl} +@cindex vl + +@item +@var{vq}: The number of 128 bit units in @var{vl}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. +@anchor{vq} +@cindex vq + +@item +@var{vg}: The number of 64 bit units in @var{vl}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. +@anchor{vg} +@cindex vg + +@end itemize + +@subsubsection AArch64 SME. +@anchor{AArch64 SME} +@cindex SME +@cindex AArch64 SME +@cindex Scalable Matrix Extension + +The Scalable Matrix Extension (@url{https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/scalable-matrix-extension-armv9-a-architecture, @acronym{SME}}) +is an AArch64 architecture extension that expands on the concept of the +Scalable Vector Extension (@url{https://developer.arm.com/documentation/101726/4-0/Learn-about-the-Scalable-Vector-Extension--SVE-/What-is-the-Scalable-Vector-Extension-, @acronym{SVE}}) +by providing a 2-dimensional register @code{ZA}, which is a square +matrix of variable size, just like SVE provides a group of vector registers of +variable size. + +Similarly to SVE, where the size of each @code{Z} register is directly related +to the vector length (@var{vl} for short), the @acronym{SME} @code{ZA} matrix +register's size is directly related to the streaming vector length +(@var{svl} for short). @xref{vl} @xref{svl} + +The @code{ZA} register state can be either active or inactive, if it is not in +use. + +@acronym{SME} also introduces a new execution mode called streaming +@acronym{SVE} mode (streaming mode for short). When streaming mode is +enabled, the program supports execution of @acronym{SVE2} instructions and the +@acronym{SVE} registers will have vector length @var{svl}. When streaming +mode is disabled, the SVE registers have vector length @var{vl}. + +For more information about @acronym{SME} and @acronym{SVE}, please refer to +official @url{https://developer.arm.com/documentation/ddi0487/latest, +architecture documentation}. + +The following definitions are used throughout @value{GDBN}'s source code and +in this document: + +@itemize + +@item +@var{svl}: The streaming vector length, in bytes. It defines the size of each +dimension of the 2-dimensional square @code{ZA} matrix. The total size of +@code{ZA} is therefore @var{svl} by @var{svl}. + +When streaming mode is enabled, it defines the size of the @acronym{SVE} +registers as well. +@anchor{svl} +@cindex svl + +@item +@var{svq}: The number of 128 bit units in @var{svl}, also known as streaming +vector granule. This is mostly used internally by @value{GDBN} and the Linux +Kernel. +@anchor{svq} +@cindex svq + +@item +@var{svg}: The number of 64 bit units in @var{svl}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. +@anchor{svg} +@cindex svg + +@end itemize + +When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Matrix +Extension (@acronym{SME}) is present, then @value{GDBN} will make the @code{ZA} +register available. @value{GDBN} will also make the @code{SVG} register and +@code{SVCR} pseudo-register available. + +The @code{ZA} register is a 2-dimensional square @var{svl} by @var{svl} +matrix of bytes. To simplify the representation and access to the @code{ZA} +register in @value{GDBN}, it is defined as a vector of +@var{svl}x@var{svl} bytes. + +If the user wants to index the @code{ZA} register as a matrix, it is possible +to reference @code{ZA} as @code{ZA[@var{i}][@var{j}]}, where @var{i} is the +row number and @var{j} is the column number. + +The @code{SVG} register always contains the streaming vector granule +(@var{svg}) for the current thread. From the value of register @code{SVG} we +can easily derive the @var{svl} value. + +@anchor{aarch64 sme svcr} +The @code{SVCR} pseudo-register (streaming vector control register) is a status +register that holds two state bits: @sc{sm} in bit 0 and @sc{za} in bit 1. + +If the @sc{sm} bit is 1, it means the current thread is in streaming +mode, and the @acronym{SVE} registers will use @var{svl} for their sizes. If +the @sc{sm} bit is 0, the current thread is not in streaming mode, and the +@acronym{SVE} registers will use @var{vl} for their sizes. @xref{vl}. + +If the @sc{za} bit is 1, it means the @code{ZA} register is being used and +has meaningful contents. If the @sc{za} bit is 0, the @code{ZA} register is +unavailable and its contents are undefined. + +For convenience and simplicity, if the @sc{za} bit is 0, the @code{ZA} +register and all of its pseudo-registers will read as zero. + +If @var{svl} changes during the execution of a program, then the @code{ZA} +register size and the bits in the @code{SVCR} pseudo-register will be updated +to reflect it. + +It is possible for users to change @var{svl} during the execution of a +program by modifying the @code{SVG} register value. + +Whenever the @code{SVG} register is modified with a new value, the +following will be observed: + +@itemize + +@item The @sc{za} and @sc{sm} bits will be cleared in the @code{SVCR} +pseudo-register. + +@item The @code{ZA} register will have a new size and its state will be +cleared, forcing its contents and the contents of all of its pseudo-registers +back to zero. + +@item If the @sc{sm} bit was 1, the @acronym{SVE} registers will be reset to +having their sizes based on @var{vl} as opposed to @var{svl}. If the +@sc{sm} bit was 0 prior to modifying the @code{SVG} register, there will be no +observable effect on the @acronym{SVE} registers. + +@end itemize + +The possible values for the @code{SVG} register are 2, 4, 8, 16, 32. These +numbers correspond to streaming vector length (@var{svl}) values of 16 +bytes, 32 bytes, 64 bytes, 128 bytes and 256 bytes respectively. + +The minimum size of the @code{ZA} register is 16 x 16 (256) bytes, and the +maximum size is 256 x 256 (65536) bytes. In streaming mode, with bit @sc{sm} +set, the size of the @code{ZA} register is the size of all the SVE @code{z} +registers combined. + +The @code{ZA} register can also be accessed using tiles and tile slices. + +Tile pseudo-registers are square, 2-dimensional sub-arrays of elements within +the @code{ZA} register. + +There is a total of 31 @code{ZA} tile pseudo-registers. They are +@code{za0b}, @code{za0h} through @code{za1h}, @code{zas0} through @code{zas3}, +@code{zad0} through @code{zad7} and @code{zaq0} through @code{zaq15}. + +Tile slice pseudo-registers are vectors of horizontally or vertically +contiguous elements within the @code{ZA} register. + +The tile slice pseudo-registers have the following naming pattern: +@code{za<@var{tile number}><@var{direction}><@var{qualifier}> +<@var{slice number}>}. + +There are up to 16 tiles (0 ~ 15), the direction can be either @code{v} +(vertical) or @code{h} (horizontal), the qualifiers can be @code{b} (byte), +@code{h} (halfword), @code{s} (word), @code{d} (doubleword) and @code{q} +(quadword) and there are up to 256 slices (0 ~ 255) depending on the value +of @var{svl}. The number of slices is the same as the value of @var{svl}. + +The number of available tile slice pseudo-registers can be large. For a +minimum @var{svl} of 16 bytes, there are 5 (number of qualifiers) x +2 (number of directions) x 16 (@var{svl}) pseudo-registers. For the +maximum @var{svl} of 256 bytes, there are 5 x 2 x 256 pseudo-registers. + +When listing all the available registers, users will see the +currently-available @code{ZA} pseudo-registers. Pseudo-registers that don't +exist for a given @var{svl} value will not be displayed. + +For more information on @acronym{SME} and its terminology, please refer to the +@url{https://developer.arm.com/documentation/ddi0616/aa/, +Arm Architecture Reference Manual Supplement}, The Scalable Matrix Extension +(@acronym{SME}), for Armv9-A. + +Some features are still under development and rely on +@url{https://github.com/ARM-software/acle/releases/latest, ACLE} and +@url{https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst, ABI} +definitions, so there are known limitations to the current @acronym{SME} +support in @value{GDBN}. + +One such example is calling functions in the program being debugged by +@value{GDBN}. Such calls are not @acronym{SME}-aware and thus don't take into +account the @code{SVCR} pseudo-register bits nor the @code{ZA} register +contents. @xref{Calling} + +The @url{https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst#the-za-lazy-saving-scheme, +lazy saving scheme} involving the @code{tpidr2} register is not yet supported +by @value{GDBN}, though the @code{tpidr2} register is known and supported +by @value{GDBN}. + +Lastly, an important limitation for @code{gdbserver} is its inability to +communicate @var{svl} changes to @value{GDBN}. This means @code{gdbserver}, +even though it is capable of adjusting its internal caches to reflect a change +in the value of @var{svl} mid-execution, will operate with a potentially +different @var{svl} value compared to @value{GDBN}. This can lead to +@value{GDBN} showing incorrect values for the @code{ZA} register and +incorrect values for SVE registers (when in streaming mode). + +This is the same limitation we have for the @acronym{SVE} registers, and there +are plans to address this limitation going forward. + @subsubsection AArch64 Pointer Authentication. @cindex AArch64 Pointer Authentication. @anchor{AArch64 PAC} @@ -48291,6 +48509,37 @@ This restriction may be lifted in the future. Extra registers are allowed in this feature, but they will not affect @value{GDBN}. +@subsubsection AArch64 SME registers feature + +The @samp{org.gnu.gdb.aarch64.sme} feature is optional. If present, +it should contain registers @code{ZA}, @code{SVG} and @code{SVCR}. +@xref{AArch64 SME} + +@itemize @minus + +@item +@code{ZA} is a register represented by a vector of @var{svl}x@var{svl} +bytes. @xref{svl} + +@item +@code{SVG} is a 64-bit register containing the value of @var{svg}. @xref{svg}. + +@item +@code{SVCR} is a 64-bit status pseudo-register with two valid bits. Bit 0 +(@sc{sm}) shows whether the streaming @acronym{SVE} mode is enabled or disabled. +Bit 1 (@sc{ZA}) shows whether the @code{ZA} register state is active (in use) or +not. +@xref{aarch64 sme svcr} + +The rest of the unused bits of the @code{SVCR} pseudo-register is undefined +and reserved. Such bits should not be used and may be defined by future +extensions of the architecture. + +@end itemize + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + @node ARC Features @subsection ARC Features @cindex target descriptions, ARC Features -- 2.25.1