From patchwork Mon Sep 18 21:26:51 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luis Machado X-Patchwork-Id: 76320 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id BEA63385C6EF for ; Mon, 18 Sep 2023 21:29:18 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org BEA63385C6EF DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1695072558; bh=Ox2OJFnFMz0LGizRWoFN/3AffLxY8X/Cm8XRwTjU8mI=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=TgQCAYcf1qaWrNGC30LiWR3AE+luQaLoRSE16SYONrbFTVVBNJF0KWH2H/8ci8zVt RSDkd77qEb+ihSpgV6H5+hqrN7DqGfcZYmprfRl5fQNuoWmoBZdigbVUn7gZPupvr5 4cRGKomZgeMQbGoMDEKoMHEHOeKnH3j5oZIeJzfw= X-Original-To: gdb-patches@sourceware.org Delivered-To: gdb-patches@sourceware.org Received: from EUR05-AM6-obe.outbound.protection.outlook.com (mail-am6eur05on2061.outbound.protection.outlook.com [40.107.22.61]) by sourceware.org (Postfix) with ESMTPS id EC0F63857030 for ; Mon, 18 Sep 2023 21:27:21 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org EC0F63857030 Received: from AS9PR06CA0263.eurprd06.prod.outlook.com (2603:10a6:20b:45f::17) by AM8PR08MB6356.eurprd08.prod.outlook.com (2603:10a6:20b:36b::23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6792.27; Mon, 18 Sep 2023 21:27:19 +0000 Received: from AM7EUR03FT039.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:45f:cafe::a3) by AS9PR06CA0263.outlook.office365.com (2603:10a6:20b:45f::17) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6792.26 via Frontend Transport; Mon, 18 Sep 2023 21:27:19 +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 AM7EUR03FT039.mail.protection.outlook.com (100.127.140.224) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6813.16 via Frontend Transport; Mon, 18 Sep 2023 21:27:19 +0000 Received: ("Tessian outbound 5c548696a0e7:v175"); Mon, 18 Sep 2023 21:27:19 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: dd1cb71b0608c629 X-CR-MTA-TID: 64aa7808 Received: from b3ad7b057161.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id F033E5CF-95DA-40A6-AEE1-B7DF8F6387F5.1; Mon, 18 Sep 2023 21:27:12 +0000 Received: from EUR04-VI1-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id b3ad7b057161.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Mon, 18 Sep 2023 21:27:12 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Gtd6bsZMIDZRiYED0bP6Ucfaf8Lsv3C6advCaoohAGnlMuvy7z5UggWlL4xOSi3JDCbJh8JE3cW3c3npaXImNh1GlDC1IPdXo1qiXOu764LwmxYzKS7P0DL2zkfOs0frBD8HNk6r/xrTSTHKrGs1k11XqcbZWr7CogI8WRUdqnvduFAaTWXejmRizaHtMuF5y7WrJlvk4UWJy1sujnOeR9aSSIx9XN9kugApfOrF1AI4zZmSHT0gDP1u5rTP1tkzyA84DYOVHDzAtJ5LauHkHux4DUS/eSpxc/o2m8X8t/Dt9raFRVjgDbJZyYe4mMV384k3jRzg12aH6iAoBks0uw== 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=Ox2OJFnFMz0LGizRWoFN/3AffLxY8X/Cm8XRwTjU8mI=; b=fAD64/izncmxtS7hMsdF9xzkkfXnHhsk3qtniCq5inR6Y83NL64mHHnpnON1kLhWDAHq0dZGC8qfkSVIdsuJOzGMBMsSckg47DS4M4c9CCRvzUEtEDVHnN4gI+xVE0Twt8HKqKrthcTuksjM262m2RBX69oJOo+sKUJkw9gQKWTQoR8nMre4o6AIjXCJFtxtBeRrMMwvvT4f2LCHNzs9w4E1JcY0gw+bMwHo2kGw5sZs719LINXm4Hzk1yehZzWtUt+2n7Vsds93rELdn2KZgzwrcfksxc9uxPQjJYZDvD4LtJYr/x8zzZkHqje3SvNHTJVrXiLVpoLYERR8swrHPA== 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 Received: from AM6PR02CA0023.eurprd02.prod.outlook.com (2603:10a6:20b:6e::36) by AS8PR08MB6231.eurprd08.prod.outlook.com (2603:10a6:20b:298::13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6792.26; Mon, 18 Sep 2023 21:27:09 +0000 Received: from AM7EUR03FT007.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:6e:cafe::53) by AM6PR02CA0023.outlook.office365.com (2603:10a6:20b:6e::36) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6792.26 via Frontend Transport; Mon, 18 Sep 2023 21:27:09 +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 AM7EUR03FT007.mail.protection.outlook.com (100.127.140.242) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.6813.16 via Frontend Transport; Mon, 18 Sep 2023 21:27:09 +0000 Received: from AZ-NEU-EX02.Emea.Arm.com (10.251.26.5) 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; Mon, 18 Sep 2023 21:27:09 +0000 Received: from AZ-NEU-EX04.Arm.com (10.251.24.32) by AZ-NEU-EX02.Emea.Arm.com (10.251.26.5) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.27; Mon, 18 Sep 2023 21:27:09 +0000 Received: from e129171.arm.com (10.57.64.238) by mail.arm.com (10.251.24.32) with Microsoft SMTP Server id 15.1.2507.27 via Frontend Transport; Mon, 18 Sep 2023 21:27:08 +0000 To: Subject: [PATCH v7 18/18] [gdb/docs] sme: Document SME registers and features Date: Mon, 18 Sep 2023 22:26:51 +0100 Message-ID: <20230918212651.660141-19-luis.machado@arm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20230918212651.660141-1-luis.machado@arm.com> References: <20230918212651.660141-1-luis.machado@arm.com> MIME-Version: 1.0 X-EOPAttributedMessage: 1 X-MS-TrafficTypeDiagnostic: AM7EUR03FT007:EE_|AS8PR08MB6231:EE_|AM7EUR03FT039:EE_|AM8PR08MB6356:EE_ X-MS-Office365-Filtering-Correlation-Id: 1d18cb52-0b75-445c-997a-08dbb88e0a09 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: ZAZr12LramMhQcHnObz9B+apdYhiEIQ/l5q3BPXuleU87NL204a/5E+tS0Cv0KG1xeYD/vnSZ66uTXP6YbxYecOrOLZCh6/E+vKFSBs9WKDuUbOW4rjnpPk6ApwYNr8pD8QJMwOwJ9A7A6I1w3Ll7RmvFfYTB8TwKlOGCi5v2q/qRIzStRMQwwnV8BT5vyIiOiCg/y9bvGXyU/cs5wqWwCh7aMRUXDqPB5+XG9M6gUWRhygYebJqqX3tQtRuYbGvZ721C8btMHU6VGl5bA8Ht3iiK74RqYlw9NTRg0cnssDS98dWM9jw9+0Ljn+A/lDe4Jtu6O9lX5ExZxM63eeAszoj6gG9xAeOB+XzcZ+iG/AelHoNVbvwYG15dujH8/yvnbu+GbcuCgEuhP1I7ZGD9dXOOlMpSPiCxIfRI6z2/HaYtQs+g7uGgPDupxCmFddRO7PQe7DY4JZlBLkDO5I69n2rpFd51LmA07+FSfD5NO0Z94UHhzEeX3xDNwcEW9lgR7Rgl941eF8ILesYh0pcaCiQf23eg+Ji6fe5+ws+Udl/2w0V8wsk98KJVOYdGwEGcK/Gbw36KO8fF7WI51Jn7DDAFf1bdaG48Rt2O6eh9M0/+YGZCMOen+i8UKHwk9S+dL0WzGvFlhuD3x9o8aq1GEsPNqSDd7jAukRw36rifJ23Rx9npabLAaVIO3N2WBONwwQlCBg0XDZRZF2yE0GESaQ8G5OoIqjQN62RNesTRvWS1v8LudS1s7/9xTqKTLNPlaG5fPcsuddF5Y9KKjvUuuTCrrre7U1ziW/QxXHA6w0= 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)(39860400002)(396003)(376002)(346002)(1800799009)(451199024)(186009)(82310400011)(40470700004)(46966006)(36840700001)(54906003)(40460700003)(70206006)(70586007)(36860700001)(6916009)(81166007)(316002)(8936002)(8676002)(4326008)(47076005)(82740400003)(41300700001)(356005)(7696005)(6666004)(478600001)(83380400001)(336012)(1076003)(426003)(2616005)(26005)(86362001)(30864003)(2906002)(44832011)(5660300002)(40480700001)(36756003)(36900700001); DIR:OUT; SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS8PR08MB6231 X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM7EUR03FT039.eop-EUR03.prod.protection.outlook.com X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id-Prvs: 4463a673-b3f7-440b-630e-08dbb88e041a X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: zEG8mUQHuIzYHYC28TEEYFKuJcOU8Vt1/wwUyKGAQtKvrRbjld1+Sck6EMEJpf7+oDV1FDQ2WXloinW9vT4Z6M4hVBLu97s/scjEOSZtZVRQ7urV5+ZvPOD264CBmAhVGN2MIIWQODbgwSwP/xeQWA0Yft3qdBPpvYdLFEyVQKqtfQQqXYI4kYY3U+dDvAUDH2/fY9tWqPrH+wuahTWqMEXtqfBcxyWWpqMvSd6bWxbtGyg5wY27dikvUI3iuNkon1iu3yB+dSMGsNqXDmBo31GrlADiNiMSk85SaH5mKox6bsprO+LnOinLaOriDqsP8uoVxsWfXw1DGaIesbUzUh5A3rDnADcxIhDMm6Dln689HUiWWH+WG7qwukQ/WnpxGl3ap5u2HDSRCc9jAfl8WOhwSPNBdc9A/M34gNb9PM7R3E0fSQ08YUaenKhybYXPUWsbVlBO0FZrdscNCABAc4J6qRtB8zhWhkhRhu3gKPmGyaeLXk/JHeQC1z9Njh9Hx4Z7x6xdAGdGlYZsdD3BjU2dKvxs0My0Fc/U85eHeIPIto8rzb6R0Uk6PrHVkPMyUY3T5jDS7m8zBDRXYwhQ1BMdhExhOtybwidZD9ImjNIDAaTt3CMIrtJAwMpD+eK24lxxDArfQFsBsqdHsH2oamd3tfeGbu7jx91HNSwYdEMRdQHKZEl+DSLGJkmp0xe7rgadF6Ul/Vq/IR5WoCAWv7EUyz7W2Ytb63EnQG/kmpdXZlgN05pNicpFOEmErbynOazjukLAOrq98t97gn7vEg== 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)(346002)(396003)(376002)(136003)(39860400002)(451199024)(82310400011)(186009)(1800799009)(46966006)(40470700004)(36840700001)(6666004)(36756003)(478600001)(40460700003)(40480700001)(83380400001)(426003)(336012)(26005)(86362001)(30864003)(2906002)(5660300002)(47076005)(44832011)(36860700001)(7696005)(82740400003)(81166007)(2616005)(4326008)(54906003)(70586007)(70206006)(6916009)(316002)(41300700001)(8936002)(1076003)(8676002)(107886003); DIR:OUT; SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 18 Sep 2023 21:27:19.5544 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 1d18cb52-0b75-445c-997a-08dbb88e0a09 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: AM7EUR03FT039.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM8PR08MB6356 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 X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Luis Machado via Gdb-patches From: Luis Machado Reply-To: Luis Machado Cc: thiago.bauermann@linaro.org Errors-To: gdb-patches-bounces+patchwork=sourceware.org@sourceware.org Sender: "Gdb-patches" Updates since v3: - Fixed more lowercase/uppercase issues with @code{} and registers. - Added an explanation of the naming pattern for tile pseudo-registers. - Misc formatting issues. 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 Reviewed-by: Thiago Jung Bauermann --- gdb/NEWS | 11 ++ gdb/doc/gdb.texinfo | 252 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 263 insertions(+) diff --git a/gdb/NEWS b/gdb/NEWS index 98ff00d5efc..525ab15e7a6 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 aa3c6778887..b5a61aa8973 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -26140,6 +26140,227 @@ 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. + +The tile pseudo-registers have the following naming pattern: +@code{ZA<@var{tile number}><@var{qualifier}>}. + +There is a total of 31 @code{ZA} tile pseudo-registers. They are +@code{ZA0B}, @code{ZA0H} through @code{ZA1H}, @code{ZA0S} through @code{ZA3S}, +@code{ZA0D} through @code{ZA7D} and @code{ZA0Q} through @code{ZA15Q}. + +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 @command{gdbserver} is its inability to +communicate @var{svl} changes to @value{GDBN}. This means @command{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} @@ -48353,6 +48574,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