From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR05-VI1-obe.outbound.protection.outlook.com (mail-vi1eur05on2048.outbound.protection.outlook.com [40.107.21.48]) by sourceware.org (Postfix) with ESMTPS id 4BDC7387605D for ; Fri, 30 Jun 2023 13:46:50 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 4BDC7387605D 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=qUGaNizvg4xDgAP7LuCF/3KdyoBREsqW/+pm465a0Ig=; b=VAzfnQfv2ijAFoZWOLmBNRuDycct0GVVZArFPy3TfMp3FxQbv2p72S+075bLJgdDSg/en7fC4ogyoLXPPJwfO4hVOhrIgyZdOVq+VFHH/YgfIjpuMRioQBBl5FmtKVHp6fLuWTBxcKXFxlfOKrrv/ub3B20X28MF2wUqBeFbJr0= Received: from DUZPR01CA0218.eurprd01.prod.exchangelabs.com (2603:10a6:10:4b4::21) by DB5PR08MB10022.eurprd08.prod.outlook.com (2603:10a6:10:4a7::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6544.19; Fri, 30 Jun 2023 13:46:47 +0000 Received: from DBAEUR03FT033.eop-EUR03.prod.protection.outlook.com (2603:10a6:10:4b4:cafe::b5) by DUZPR01CA0218.outlook.office365.com (2603:10a6:10:4b4::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6544.22 via Frontend Transport; Fri, 30 Jun 2023 13:46:47 +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 DBAEUR03FT033.mail.protection.outlook.com (100.127.142.251) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6544.22 via Frontend Transport; Fri, 30 Jun 2023 13:46:47 +0000 Received: ("Tessian outbound c63645f235c1:v142"); Fri, 30 Jun 2023 13:46:47 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: c717aa76e3abfd87 X-CR-MTA-TID: 64aa7808 Received: from c1822afd910d.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id 8A481A32-D6A3-4AAB-AE98-695690AA0172.1; Fri, 30 Jun 2023 13:46:40 +0000 Received: from EUR04-HE1-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id c1822afd910d.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Fri, 30 Jun 2023 13:46:40 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=fWODMUDtnuhIJH81Xcv7YUjWo/wYw8qsnUjp8sQf8vWfFzV9NI0EvSmEcV2qIZdWnzDnG+Svcu5qpQLUTUhbS0mNNaxfajZyC69gfh6FcpAAXDbBSZ0NXAg/BN+RiyvXdFy7Y0osZlYP/hu3nMZtLLQs3KqvBSEBCG0TPaFyHazuXS7Y17GryDdYEH4Sry7uRRpRQSL/dm1odP9H6kIX1FFnY7wYhZDOhYSeoma1D1tEUwvG3DGYnwJZUrBTOfG7Mt42cXgFih+eZsCwldsiawyziy8cU0yzAUA/vw9L7kAgUV/9cetnOoMUtbRRhcGc7zk1QhsOilyjKglyIdihsQ== 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=qUGaNizvg4xDgAP7LuCF/3KdyoBREsqW/+pm465a0Ig=; b=gJsOSMvMq0+FYd90j4y6V3OeQb+dQbMIlWuMEo2gKo7w9nk8ZrSOr0A7ZtoburtQ+H97Bwz2teVnVqNxqu1HbtdPcfcd9vSY/oKScoGvn9N74v8AkdfHso6LiuW9I4CFvSFQd+7B5rjn2fpc1a1d9mWQfw+RahwWmYO82O6pvvZhZGf3A5U8mpUdilkDvYXwOkK8SsTD4SNqfu1qqRu1/dvhsgYjMJRt8uX2xiyyejl2E6eYmC84W5GayL9qMRyfzRummQkIMI3dyAkxC0XEvqhvUBBsNMcaSdiPueNERkUzPc9SG9U3wj+DMHfoOILYX+ERWbWMwSXhH/FHf7fuOg== 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=qUGaNizvg4xDgAP7LuCF/3KdyoBREsqW/+pm465a0Ig=; b=VAzfnQfv2ijAFoZWOLmBNRuDycct0GVVZArFPy3TfMp3FxQbv2p72S+075bLJgdDSg/en7fC4ogyoLXPPJwfO4hVOhrIgyZdOVq+VFHH/YgfIjpuMRioQBBl5FmtKVHp6fLuWTBxcKXFxlfOKrrv/ub3B20X28MF2wUqBeFbJr0= Received: from AS9PR04CA0119.eurprd04.prod.outlook.com (2603:10a6:20b:531::15) by AM0PR08MB5492.eurprd08.prod.outlook.com (2603:10a6:208:185::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6521.26; Fri, 30 Jun 2023 13:46:38 +0000 Received: from AM7EUR03FT014.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:531:cafe::2e) by AS9PR04CA0119.outlook.office365.com (2603:10a6:20b:531::15) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6544.22 via Frontend Transport; Fri, 30 Jun 2023 13:46:38 +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 AM7EUR03FT014.mail.protection.outlook.com (100.127.140.163) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.6544.22 via Frontend Transport; Fri, 30 Jun 2023 13:46:38 +0000 Received: from AZ-NEU-EX03.Arm.com (10.251.24.31) 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; Fri, 30 Jun 2023 13:46:35 +0000 Received: from e129171.arm.com (10.57.27.17) by mail.arm.com (10.251.24.31) with Microsoft SMTP Server id 15.1.2507.27 via Frontend Transport; Fri, 30 Jun 2023 13:46:35 +0000 From: Luis Machado To: Subject: [PATCH v3 16/16] [gdb/docs] sme: Document SME registers and features Date: Fri, 30 Jun 2023 14:46:16 +0100 Message-ID: <20230630134616.1238105-17-luis.machado@arm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20230630134616.1238105-1-luis.machado@arm.com> References: <20230630134616.1238105-1-luis.machado@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain X-EOPAttributedMessage: 1 X-MS-TrafficTypeDiagnostic: AM7EUR03FT014:EE_|AM0PR08MB5492:EE_|DBAEUR03FT033:EE_|DB5PR08MB10022:EE_ X-MS-Office365-Filtering-Correlation-Id: f980fdce-3521-4de4-862d-08db797072e2 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: nwIMr8iXgn93GlU12tHwgaZslZwdvSSdvRORwJKMuxEZHF3P+7Za1a04rpJkL5dythkEFX/Lz5mzhGtSbxB82Wx+jMSwzK1fKklys7Jse7sIdRk9ZHAMImTbIUaKQtSDF7POdE8lU7LCwOle9VQG0KNi3Z5XhUl/fhzXNKibU1Uc1/rKzqQlQrbD1xfAhCjfP8DxtKhAwGSARNyLRIjDzV4Kia//rN6RaK6+oKAgdjxvp9REkrGsHp7Z6w9N7SS9SxpgEWLP2L7167iky2w6pcipfZjXI8IkALuk1uvry86s+MStQrsAnBEajyaon/be7wgM61MuNINTZo3qfYVryV2Q4AxhUpj9GGnxz+g86H/r+GWdvj7CR6cx6N0kvhGbj3gXe7YIUI1nHFradjpvYNaqDo3XbS8MYrGmZrTM9nhyYxYzrgdJOBcs6M/RaHjukM5SOtk5K4UFrShSvpclQ8vwMOF4oZDUIwgLl5zQJQ4ne98AbVH81tF+Kd0WKJDa8FciVtw6aZph9B0WpmuCEMvvMYUCKbp5EsuxSHTB1w5dQ7Q8Ki4GlYNz2M8kGIa2jyJ2MxhDOY6gPBmS0sqy/oxctwtDoZ+DE7Je/xSD+x+NnQnCtoeYpYFbreU3vmuk2bgIuO3PqXgw5Z4VAHczQuTCV9brLddHl+0K93s7/1bEw216rjHUNyCPZQvDmKmhMrxeXDpJUvh7+Meg+SSjuNVh4H8nTRG0RbHC2rgLJcNIzFuFIliY7YzRgD7OVXJlZH+0kUaWRF4RGmTGpJCV2sdIItA+Gr2K3B/zdV7US1Q= 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:(13230028)(4636009)(39860400002)(396003)(346002)(136003)(376002)(451199021)(46966006)(40470700004)(36840700001)(36756003)(82310400005)(36860700001)(70206006)(40480700001)(82740400003)(40460700003)(81166007)(356005)(86362001)(44832011)(30864003)(5660300002)(316002)(41300700001)(6916009)(8936002)(8676002)(70586007)(47076005)(7696005)(1076003)(186003)(2906002)(478600001)(26005)(336012)(83380400001)(426003)(6666004)(2616005)(36900700001);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM0PR08MB5492 X-MS-Exchange-Transport-CrossTenantHeadersStripped: DBAEUR03FT033.eop-EUR03.prod.protection.outlook.com X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id-Prvs: 9741b470-99eb-4ebe-6f4d-08db79706d79 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 8WDYD6wYHb07S9PmkbGPynwrS1rwqlddC20fzHF1plRrldG/Z89R6KNs5Xcd+Jv1SizZ3EKrFIyW3OVrC2ZmCu/9q/26WkJ8NHG6tAEfYaLr4n2tF6MOajfBXjGKEBN7ZZCdeW/iJ9FXN7MRJR7L6TK8SqQOZia1U2aZrZgmm7sZH4MqLqdkbiyhMYS4AmpsJhFOdnC5vAHbAbO4oDtOx1RolRxkAOpqtorgvNDYAduwp/tIrulr16Jcklq3Q++0Cgsduy2T+a4kNidyGyx/zmfWinnxU83IfxATyAZfNPJ+yF/5/v90m/WpvFJQLP/hPng/en6rKrigu+GSKlAr7tvNZ6sOzrY30gYD4zu2eyMHErrfq40ad6F+pGadO/EPkBiO/muvsocrsvwSLCv2j8MEFVf6/0bN0e1PggPNLejj8V5CFPI0/z81SNTsLtIfUSkoMJar6glqU6AGPJBZxa5rGxt6nHXiLYreyF61zW1aKO75QFOBhIQ78/kavBMdqdVdCqg+zCdTkyknZupqqHI5flIU6F4kq+Q/tELER8wXnm3P5hAFaMO5YNEY6d/1yhmQTfWHbg69EIHvtXPeelA5C0uXQDyXenYz9Q6o9aoknjRs9u35MwBLo2LTh1ktdb8KhTe3AUxDpj43ancJ0iJqtlTP+sIJLycHkcJOYlzfEX9wT6OYUCjSQevRXy/AhWsU3O8f1sdovjYnHI3K7NQE4h1wVst+Ktl5svBLp7S01UhHRMxvK18wYhz3rca6L8QPcsmDmaGUv3VVb/DryQ== 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:(13230028)(4636009)(376002)(396003)(136003)(39860400002)(346002)(451199021)(46966006)(36840700001)(40470700004)(86362001)(8936002)(8676002)(5660300002)(82310400005)(26005)(1076003)(44832011)(7696005)(478600001)(6916009)(70206006)(70586007)(41300700001)(316002)(6666004)(186003)(2616005)(2906002)(47076005)(40460700003)(83380400001)(336012)(426003)(30864003)(36860700001)(40480700001)(36756003)(82740400003)(81166007);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 30 Jun 2023 13:46:47.3647 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: f980fdce-3521-4de4-862d-08db797072e2 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: DBAEUR03FT033.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB5PR08MB10022 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,T_SCC_BODY_TEXT_LINE,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. --- gdb/NEWS | 11 ++ gdb/doc/gdb.texinfo | 249 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 260 insertions(+) diff --git a/gdb/NEWS b/gdb/NEWS index fd42864c692..720008a5d97 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 b10c06ae91f..758c9632217 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -26073,6 +26073,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} @@ -48196,6 +48414,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