From patchwork Fri May 19 10:25:08 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luis Machado X-Patchwork-Id: 69676 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 AF60A3836E9F for ; Fri, 19 May 2023 10:28:33 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org AF60A3836E9F DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1684492113; bh=VIBUNMwddr564ZBDY4z5u75eS6IbkTze4ZkIsJxm0Vw=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=atMy49qxT8EGorjebkr+DBDFtUfWwoSaDF18COJQ2BL5P9V3fv+piQoG1dK/2Qweu wSOtsDm29lK13jS13KkCrETvqah4S7FiSZ9yzG5gp8SqD+qRD5XaLjowJ8hrISGvEW vmzWtTR0uyAcRqqDiB6pMnffEjdV8YC1NPW6foy4= X-Original-To: gdb-patches@sourceware.org Delivered-To: gdb-patches@sourceware.org Received: from EUR02-AM0-obe.outbound.protection.outlook.com (mail-am0eur02on2042.outbound.protection.outlook.com [40.107.247.42]) by sourceware.org (Postfix) with ESMTPS id 674A03858412 for ; Fri, 19 May 2023 10:25:30 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 674A03858412 Received: from AM7PR03CA0011.eurprd03.prod.outlook.com (2603:10a6:20b:130::21) by GV1PR08MB7985.eurprd08.prod.outlook.com (2603:10a6:150:9f::20) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6411.19; Fri, 19 May 2023 10:25:26 +0000 Received: from AM7EUR03FT058.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:130:cafe::81) by AM7PR03CA0011.outlook.office365.com (2603:10a6:20b:130::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6411.21 via Frontend Transport; Fri, 19 May 2023 10:25:26 +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 AM7EUR03FT058.mail.protection.outlook.com (100.127.140.247) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6411.19 via Frontend Transport; Fri, 19 May 2023 10:25:26 +0000 Received: ("Tessian outbound 945aec65ec65:v136"); Fri, 19 May 2023 10:25:26 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: bba31486d77bf037 X-CR-MTA-TID: 64aa7808 Received: from f441d7add428.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id F778EB68-75AD-4150-B7D3-793FD410CE19.1; Fri, 19 May 2023 10:25:19 +0000 Received: from EUR01-VE1-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id f441d7add428.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Fri, 19 May 2023 10:25:19 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=eIukRAFXHwTTHWJaZSj7RItphXlkoTItbL3vwPhI8FVJI/NqHI383xh9sOsk6BYAKOHNAgjiueZq7/72bWvJZrHWFWC2rwSHv74mQbS/ywhepOUpqRtWji5GKxuyx4F982f0x90PDHf4HRgqTHqe/Idb7BSXRydR/6HLhsg+7j6Cdf4Ymem3Ag+eIYXM73/vdajy6aQM4bzbxGnsOvLeE6jMRDDzB7F5QenkTnPjHc3mu44eKh4rB4zZb8lYeNynAyTftnRiUjLc9ULAvqwasMznlxj2LRmYZdOnPGX85SEEdSthhEc6SieLkf/ioC8N8VYoB26Ib69E+jrM3tGVwg== 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=VIBUNMwddr564ZBDY4z5u75eS6IbkTze4ZkIsJxm0Vw=; b=Hg7faRw9kHB4x6fV9dzJAUKbtGFe2AJURIY2kVp/HdSdHbz8Fh3VYrSlwyaIaMO/Pw/tAxJrK62PTw+Q0McLunZk37Q/IGvvUo1fkX6NsPiOlntS9ksAhCX01W7o3CP9uG/qLVCp3zZCzLVvJ/9yE5MKgA6lnS35vEcs3fkLEJlEOl+9iBviMJxx/b8+L0SxHRIKjrsluBAdgYdhDYXHvvOJ03PD2GdsFV1GQDP2IAQ3lXK3xsmJX2vr4pWRnREEDrna3h7MvuBz038RE+P0pGS204llImWUtu9V+s0fAFae8oNGiNL9wchTtzFeR7hXWBGCvOsvUcRZxn7cGHF6GQ== 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 AM6PR10CA0104.EURPRD10.PROD.OUTLOOK.COM (2603:10a6:209:8c::45) by AS8PR08MB5974.eurprd08.prod.outlook.com (2603:10a6:20b:298::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6411.19; Fri, 19 May 2023 10:25:17 +0000 Received: from AM7EUR03FT027.eop-EUR03.prod.protection.outlook.com (2603:10a6:209:8c:cafe::b0) by AM6PR10CA0104.outlook.office365.com (2603:10a6:209:8c::45) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6411.21 via Frontend Transport; Fri, 19 May 2023 10:25:17 +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.6433.7 via Frontend Transport; Fri, 19 May 2023 10:25:17 +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.23; Fri, 19 May 2023 10:25:14 +0000 Received: from e129171.cambridge.arm.com (10.1.37.65) by mail.arm.com (10.251.24.31) with Microsoft SMTP Server id 15.1.2507.23 via Frontend Transport; Fri, 19 May 2023 10:25:13 +0000 To: Subject: [PATCH v3 17/17] [gdb/docs] sme: Document SME registers and features Date: Fri, 19 May 2023 11:25:08 +0100 Message-ID: <20230519102508.14020-18-luis.machado@arm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20230519102508.14020-1-luis.machado@arm.com> References: <20230519102508.14020-1-luis.machado@arm.com> MIME-Version: 1.0 X-EOPAttributedMessage: 1 X-MS-TrafficTypeDiagnostic: AM7EUR03FT027:EE_|AS8PR08MB5974:EE_|AM7EUR03FT058:EE_|GV1PR08MB7985:EE_ X-MS-Office365-Filtering-Correlation-Id: 41d768e9-e284-4a91-0bdf-08db58535c8c 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: ctRm4nfcgs1M4Oh0+N9+bK84/1QBnUKFTOlaA0/J/TTKOQEpuhVdnCMOOm/8HC65/4hZP+ZcWmzD85DV3kcXgzyJgQL9IJKgc3VzOMgoFsRsBga9ifmV8OVQWBNFmXTWUSeAKPHwkg6XEHQdIepjX1VKPpfcKB1yVh3LrfzXqWwu7m78mwsrLWLRj33LoWbO2UOxpgrI2hDpKz9dpaaZx/kUT6yVvuUSLFBvMVLYoHKYEq2nZY8B0XZlcddT9Nf+VH3BPf4WjJTW5VGIdzzDw/ujpkRkIPcKz6JHGQzcwcdTa7jis/BXlRKmRxVd8bDSLQqw5JkhPCIYSGpqeDk+EU1JwqwRSQHddO6vIEUJgRt8iBmXvoMb1UyjXnkem4gleerlq0SE54JmMraNHKAVUMp13RdMOOUOOI9GgPq+xsupMX+Tan2TBJa/RZ3WhQGOieTwjHMi63+eKMZg9oqwD8IpGeQqzGwxUJZ0jtkO1TkWetTY9AUYrlq/spGKhdsolfIlo6J+UXXEp6dZHEkVEKoGwogP1lv3MZ1v/87EuRJnlzgqp+NZ2z5bFOWHWKLLM2QeYxyQe8humpg5gCHfPDMQmWtIp9cBD2KjYbOlbsBJXrDmxtmZvZgPQeLomdCg9OJsb1JfZLRTtPnRVSfrd+vBLhi8rK5KYDJweMB8ByiluCWBlPjUpkRiklxbUGYloLzdQb6NXbbCdLs/CQetwAGRb3WtGcm+v3Tfx1dRf6ngEDXlRegumHHfKNVkaljn6W45ByogxVY8E3ICCurHqq7Ie3QX/BM31VLHD+88xHg= 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)(396003)(346002)(39860400002)(376002)(136003)(451199021)(36840700001)(46966006)(40470700004)(5660300002)(40460700003)(41300700001)(2906002)(36756003)(47076005)(426003)(36860700001)(83380400001)(2616005)(336012)(356005)(81166007)(1076003)(82310400005)(86362001)(82740400003)(30864003)(8936002)(26005)(44832011)(8676002)(40480700001)(186003)(7696005)(6666004)(70206006)(70586007)(478600001)(6916009)(316002)(36900700001); DIR:OUT; SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS8PR08MB5974 X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM7EUR03FT058.eop-EUR03.prod.protection.outlook.com X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id-Prvs: 75902b66-e90a-4eb0-3bcc-08db58535728 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: uGeMk2nkHA3uS2FF5gg4WrjpxOVzvuv3+TDUIbRZlm9m7AYgk6WiR6jZkCWvI20mOU1AOOz7v8CPvftKvkdYb2ZU+xALZwLy3FeaI6YNV7PNBgSdPqJfNvmwV3ABrze1Kvr6+yLYeH8C7RIW7oswy1l2fhk/9SUxfX8cOBSEPS0frUJoFbREAM3szxtTxjSOBYNDsIyno884v/8uJRLdKewGcWTqIgC1dfNy2UYGP5S+M8xf3D/mvxT2AXSX/GFku/mS5xsrvuNUB38/X+a0LLoIWYJtaZC6OyfW/Xr8a1/S7v31VOYOS3AjcmpLqNHfqCBUrdxULB+4znmxXCcu3lvlTdXrUB+tA4MgNU1INnqTrjwIZLKUOBsWniBtvJ7OdCc4gZceD+opXws3JXSzsDcU2uiPLdOX2r79rJ3azEvr+MAxsYxCLfrVO//QF464GIO5guk/fab8mmDW4Euey6wOMX8Rp1CLr4Fy36RS68p/AEFnc3Bi8q4Ki/cQV+OWwfB/aXqCAZKjEDF0ClhNbeTkX+bINLomq+vAEbwrd7xxEIZHjEqDxF9P3fuV93aQlUJ1KShJ+vQ/J99GxKRJc7gDYQtVzIEr/o2o6VYv17lhFPs+A8FhU4ydSl2JU0rTv4J7rN/2qI7xHnEobioxM24f2W85yGhNtEItQzBoC+DFktWEMDZvoXCKMRJemhj3q9YkpsxEXVlP7p9Q26bQ6emQ8GCsWXg17xAKBAA+J+rbTvmS9CLwB1QQOAnRl10oJy/7EqSpnK1x4wIUA97ksQ== 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)(39860400002)(376002)(346002)(396003)(136003)(451199021)(40470700004)(46966006)(36840700001)(86362001)(36756003)(6916009)(70586007)(316002)(478600001)(70206006)(44832011)(82310400005)(8676002)(7696005)(40480700001)(5660300002)(30864003)(8936002)(6666004)(2906002)(81166007)(41300700001)(82740400003)(2616005)(426003)(1076003)(36860700001)(336012)(26005)(83380400001)(47076005)(186003)(40460700003); DIR:OUT; SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 19 May 2023 10:25:26.0487 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 41d768e9-e284-4a91-0bdf-08db58535c8c 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: AM7EUR03FT058.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV1PR08MB7985 X-Spam-Status: No, score=-11.9 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 X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 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 Errors-To: gdb-patches-bounces+patchwork=sourceware.org@sourceware.org Sender: "Gdb-patches" 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 Reviewed-By: Eli Zaretskii --- gdb/NEWS | 11 ++ gdb/doc/gdb.texinfo | 249 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 260 insertions(+) diff --git a/gdb/NEWS b/gdb/NEWS index b82114d80b0..579afde159c 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 f23bcc5f3f8..5da93b870d9 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -26056,6 +26056,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 @var{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 @var{svg} register always contains the streaming vector granule +(@var{svg}) for the current thread. From @var{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 @var{svg} register value. + +Whenever the @var{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 @var{svg} register, there will be no +observable effect on the @acronym{SVE} registers. + +@end itemize + +The possible values for the @var{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} @@ -48116,6 +48334,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 @samp{za}, @samp{svg} and @samp{svcr}. +@xref{AArch64 SME} + +@itemize @minus + +@item +@samp{za} is a register represented by a vector of @var{svl}x@var{svl} +bytes. @xref{svl} + +@item +@samp{svg} is a 64-bit register containing the value of @var{svg}. @xref{svg}. + +@item +@samp{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 @samp{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