From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR05-DB8-obe.outbound.protection.outlook.com (mail-db8eur05on2050.outbound.protection.outlook.com [40.107.20.50]) by sourceware.org (Postfix) with ESMTPS id AFD0C3882168 for ; Wed, 13 Sep 2023 10:22:12 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org AFD0C3882168 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=wC1jEtT+qNNPs/wT5CMnk4ppwxzDCugNkL7BgMxgECA=; b=IG2XbS0CVFhFE7NRFvdlzxTYP+v0CUJpzydUzRsetojeCKnriEA/VcO12VyaEd63k6J4damLyage+S5LGsa8N5kKQhOu3dEQi4kOPpbYzf4iTMlfCHTzejI1hZKVh5xKT2btrIzmP9ulxrn9xbNZb8TmtSHKQNiJwBdvx8DhfOE= Received: from DB9PR05CA0001.eurprd05.prod.outlook.com (2603:10a6:10:1da::6) by GV2PR08MB9877.eurprd08.prod.outlook.com (2603:10a6:150:dd::7) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6768.31; Wed, 13 Sep 2023 10:22:09 +0000 Received: from DBAEUR03FT065.eop-EUR03.prod.protection.outlook.com (2603:10a6:10:1da:cafe::ff) by DB9PR05CA0001.outlook.office365.com (2603:10a6:10:1da::6) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6792.19 via Frontend Transport; Wed, 13 Sep 2023 10:22:09 +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 DBAEUR03FT065.mail.protection.outlook.com (100.127.142.147) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6792.19 via Frontend Transport; Wed, 13 Sep 2023 10:22:09 +0000 Received: ("Tessian outbound c99fbc01d472:v175"); Wed, 13 Sep 2023 10:22:09 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: 38a6342cb1edc1f2 X-CR-MTA-TID: 64aa7808 Received: from 344a02ec0b13.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id D6204DD2-EA5B-454B-A3CE-C2072E78DCBC.1; Wed, 13 Sep 2023 10:18:39 +0000 Received: from EUR05-AM6-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id 344a02ec0b13.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Wed, 13 Sep 2023 10:18:39 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=ic7guoVpvirXk/zt0d3er1em8h1KVnPlYIfGmtcaITNdSdKKkjNxY/GCDN7fSkUSsmOSoaliY1sE2H9Ajbh4ZOIpy3sYOh/GfF2NOtZMh3UVI75iz2xJ9T6InjkQSa/9+e6o40+Eg7SG1Ezk2id7PCVg4RFoN5+EFSiCrYmRg67+qPnRsFhik08dXt7nuTQVwuPbEjlJoTzw7jWdUnTyZUcCVXYw60LvLONxNHtQiqUsMDeNg/bNENBVjJewOcqJwXQPKiZzKuy2VNKmWWuL3+zmDvEmddoA6I3tOHbe1sINwGGLSf5bH8G7AN9y44WdoV4NKaEHPlmBgOialU2wVg== 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=wC1jEtT+qNNPs/wT5CMnk4ppwxzDCugNkL7BgMxgECA=; b=I4JIscYDQEHDoDQJ18XDtOuaa6nH5jcYnkv2BJtM02L5qxhHf+oNF74t89U2K3AgMZikINSh8hxYGqMu1du2rkEZxVZ5xJWTyIkTAqQ4KDN2SsJWd2LvHy9ZmwinVLWVHZQa2nwquUNT4OoQGFZI5ElURuAYdH09qQrk8+T8aedkYGMxLD+IefbzGZoyROg1tc5LHNUWp1HA1S0LXUbVAC4O2e10pOMjSIqZQXvDinVeHVT86Ug+2EsG5o8l00029eXpVYoCWkDB19sJ7WsFNntH2sQ0FCRHDstTfDNOEmD5WiHnwtJVFQiiL/LXNy/DJ3ii2rUzcqf4wQGgoxPrfg== 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=wC1jEtT+qNNPs/wT5CMnk4ppwxzDCugNkL7BgMxgECA=; b=IG2XbS0CVFhFE7NRFvdlzxTYP+v0CUJpzydUzRsetojeCKnriEA/VcO12VyaEd63k6J4damLyage+S5LGsa8N5kKQhOu3dEQi4kOPpbYzf4iTMlfCHTzejI1hZKVh5xKT2btrIzmP9ulxrn9xbNZb8TmtSHKQNiJwBdvx8DhfOE= Received: from AS9PR06CA0710.eurprd06.prod.outlook.com (2603:10a6:20b:49f::26) by DU2PR08MB10201.eurprd08.prod.outlook.com (2603:10a6:10:496::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6768.30; Wed, 13 Sep 2023 10:18:33 +0000 Received: from AM7EUR03FT050.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:49f:cafe::2a) by AS9PR06CA0710.outlook.office365.com (2603:10a6:20b:49f::26) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6792.19 via Frontend Transport; Wed, 13 Sep 2023 10:18:33 +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 AM7EUR03FT050.mail.protection.outlook.com (100.127.141.27) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.6792.19 via Frontend Transport; Wed, 13 Sep 2023 10:18:33 +0000 Received: from AZ-NEU-EX04.Arm.com (10.251.24.32) by AZ-NEU-EX04.Arm.com (10.251.24.32) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.27; Wed, 13 Sep 2023 10:18:33 +0000 Received: from e129171.arm.com (10.57.66.200) by mail.arm.com (10.251.24.32) with Microsoft SMTP Server id 15.1.2507.27 via Frontend Transport; Wed, 13 Sep 2023 10:18:32 +0000 From: Luis Machado To: CC: , Subject: [PATCH v6 17/17] [gdb/docs] sme: Document SME registers and features Date: Wed, 13 Sep 2023 11:18:15 +0100 Message-ID: <20230913101815.178154-18-luis.machado@arm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20230913101815.178154-1-luis.machado@arm.com> References: <20230913101815.178154-1-luis.machado@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain X-EOPAttributedMessage: 1 X-MS-TrafficTypeDiagnostic: AM7EUR03FT050:EE_|DU2PR08MB10201:EE_|DBAEUR03FT065:EE_|GV2PR08MB9877:EE_ X-MS-Office365-Filtering-Correlation-Id: 8ea8645f-5181-471e-8f7d-08dbb44349b3 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: puyiDdnO672SxRAuT4gFxmO7UJ7EJyYJ96ffGjc5RIEw9PPImtpqbx55wa5fPKtJEnalPZab1Fc6ZzvtMxOojmJPG+lY68PaNdv9gm0dGKpidktcQCgZW1PEvAzx7M5CKt3Qh08c5qC2fvw8kBxUb8mbnqZWYMMPOecdi7j5/4f7zo0TS6D6G0uh+YS4hqIloOd/Ctp3Y4K0VCnvLnvMSNOhfgzBFQqxpP+eInYcaWKzstg1QVJ7FI95m9icz4wjwCZfF5B+163lSpGyj603OdzTpSh8XYu3YaqNIRUtmf1B9SEOz8wZgCS18YQgU5w5mFiJ7BHAgScq6z7Y9cgRIXB2DejdgpzFdCIcGQi9e9F/fwQeDbfFfN80rwIC/vvFD0V422FaBMnu38H8I8R+hekz5OA8hg34Uql+eIkBzLzKfsf3rzUlwgrVk4mhhgHKIn87qgcm4W00dhvSNr4pq0iYTnJESwpRtR6I8HdqJBXJIxVESr2JHIpshDdfVDLwzPirQSVDeCSdUPE4Dp9Z/ZpR88SBc6n9ilEhHBUo9Ic55E0bjEZ7+CpHYUKfRqqNVhDlN0HgUhjvIFa6PNpzxkjNV143JHH6phm8vl753vxb826VTLy4epWOKR19FvmdoufkBxI00FM45tcKVVM6gk7DUcVqzb0gxd8XMsMipfZB3PMfPU4b+JetZUt1FcN12DV7RfqK65pO3lLk8kbJrRmPEVms6Zn8t8c1Bc7k28G9etwaaX4JOp5JTWeiNVp97+UeL7cPVYwntJ05qm0Dhg== 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)(39860400002)(346002)(136003)(396003)(376002)(451199024)(82310400011)(1800799009)(186009)(36840700001)(46966006)(6916009)(70586007)(70206006)(5660300002)(356005)(41300700001)(54906003)(81166007)(316002)(4326008)(44832011)(36860700001)(8676002)(47076005)(2906002)(8936002)(83380400001)(82740400003)(30864003)(478600001)(40480700001)(336012)(426003)(6666004)(1076003)(26005)(86362001)(36756003)(7696005)(2616005)(36900700001);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: DU2PR08MB10201 X-MS-Exchange-Transport-CrossTenantHeadersStripped: DBAEUR03FT065.eop-EUR03.prod.protection.outlook.com X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id-Prvs: bf1ce8bc-ec59-41ad-0db1-08dbb442c90a X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: utc6zqpj+YM3pGPvgVzrb6JJw0G0dWlH9wq3PcX1ODO4kd8HQZtWlkAGeG/jgw1rvHe6En1Ec2tz9Xg8b5yDdISObyrk5uesYeKugTIC/xrehL270p/Ys0KiU9T2VlCPj37MPIdJXl3fQvSmnV6wSwogVkUm9+IvcWLPLkH0xvcXtLsw53xq5/zcv8XGcrCKqGC8TgymagtAt470p8Ckp4YOUEb8aRh425GQvPVJo5Ac2DWjLTXfjM3UQECIxo5CU9udi4pOsr5SuHWdSuygGsJyjqnP2XiArrypGus/k1rWaih7nxXfUwwuI/Xct9BM3hBAAz2sacDcxR1vygyEINK2YVJ8YuctveDKMi9Lh+BHpRr59mkARh4NgPmRN44sjB3fncuU1sw2wSXspOmQROhLAiEvE5MxROJ3PsinpwSAeTAI/VCMWrkQbPdw5Bw90n24cqm+lJktch2hN1zvf0RvlhlLoxA4xNbSFFlpWXum+UpqjRYHWExMj7OGft+cgZfZOOC/izo7MoouWboiIE2LhRpCRpDCQxCdKbrFrWKOcGNisKi0ZX8B18LIkIs2dGIfJ2SKKyTFkeh8W6rdDaOO4eRRJ5z1i0M0Ah5lg+g7UT6fWKo7tNC9RQxwJxjZifNMAnSbdbsNjyJ3PCBrw2rJDEaImj5/IaTLZs2XxM1KJvNTzWkqkdLhr3e0m8BJeKndOgnun0bXiSR07yLd9XXegO9oGaQF5Oddqll93MbVbgRa9VZDK7L6BnISnzLvXBFNnH5BT4kBVZPsgIcjZg== 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)(39860400002)(346002)(376002)(396003)(136003)(1800799009)(82310400011)(186009)(451199024)(40470700004)(36840700001)(46966006)(7696005)(426003)(6666004)(83380400001)(107886003)(36860700001)(478600001)(26005)(336012)(30864003)(2906002)(54906003)(70206006)(6916009)(316002)(44832011)(70586007)(41300700001)(8936002)(1076003)(2616005)(4326008)(8676002)(5660300002)(36756003)(47076005)(82740400003)(40480700001)(86362001)(40460700003)(81166007);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 Sep 2023 10:22:09.5213 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 8ea8645f-5181-471e-8f7d-08dbb44349b3 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: DBAEUR03FT065.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV2PR08MB9877 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 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 Signed-off-by: Luis Machado --- 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 9b7e06f3156..3c0419cf43c 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} @@ -48310,6 +48531,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