From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR05-DB8-obe.outbound.protection.outlook.com (mail-db8eur05on2072.outbound.protection.outlook.com [40.107.20.72]) by sourceware.org (Postfix) with ESMTPS id 46BA63858C53 for ; Mon, 17 Apr 2023 17:20:05 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 46BA63858C53 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=rvB0fOABE6lE6awUP0noGUAhBltU8FDvaacxtm/hOBc=; b=e+MGl3z5L5FqpDAQlq/gE5w3Bi51Iw/MPVIRMKOLQV6aSAIyMOpkz3GCFkO6DX0aMCQGbXYtQHL3VFwc0ujVFsWPq/NbNQseM/2eS7ISOuNzEpjpy/plNuGG4gRGpUbUlg0hW5GKEbm1km7wGPnNBtkR/v8kO2IaYfLWHvzNpP4= Received: from AS9P250CA0012.EURP250.PROD.OUTLOOK.COM (2603:10a6:20b:532::25) by PR3PR08MB5676.eurprd08.prod.outlook.com (2603:10a6:102:82::5) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6298.45; Mon, 17 Apr 2023 17:20:00 +0000 Received: from AM7EUR03FT035.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:532:cafe::38) by AS9P250CA0012.outlook.office365.com (2603:10a6:20b:532::25) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6298.46 via Frontend Transport; Mon, 17 Apr 2023 17:20:00 +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 AM7EUR03FT035.mail.protection.outlook.com (100.127.141.24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6319.17 via Frontend Transport; Mon, 17 Apr 2023 17:20:00 +0000 Received: ("Tessian outbound 3a01b65b5aad:v136"); Mon, 17 Apr 2023 17:20:00 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: 653ee3c5bbc47f3e X-CR-MTA-TID: 64aa7808 Received: from a8f2011a2aed.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id B98E660F-45A9-4CFC-91EF-9AA6B1C72BDB.1; Mon, 17 Apr 2023 17:19:53 +0000 Received: from EUR04-VI1-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id a8f2011a2aed.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Mon, 17 Apr 2023 17:19:53 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=llMeHSicSS2A6fG4yyD4ezJjiaK8tX8N9aWzuGGArA1ZjG498oKs5YxQQ/6JF+WXkV33aeJ54RXSiMd2yuIGcatmojDWC41KfnpmTMWnW+OOSZPt7CBaHy6rDRJz3cf8e9Rk+rLvplVNWXRVweM5lhEUZraPhsBojlE9zwGKjUlTkXdn3ZPo20yG59wxM2drSHgmHQSlQMkm3xvhkfHMzZoMl9GjtyZq3rHdilsXMs9wCxtxJFi23Hxlc546drNtLyyjA2XzY8ixkcusKSdTMVkZ+YvNU67zSvqigO5ENOBmVbgQ1YEndzMT5gHb4/TNAV2k3zb/PTkJfLddXxTVtw== 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=rvB0fOABE6lE6awUP0noGUAhBltU8FDvaacxtm/hOBc=; b=WPjJkaL3Pfhss9Cf3o3Hm+RTeFfOnx2Qu++RpqlklVbELFBF18zBkGp+/lpDZvmDiT5nnaG4LhZxaCOPI9iPDqcBdxPFF3kUafqCYTDzq37u7Ab+NikgIQDlVVaek+bYBmxPmsid74opWFJvIEQl3stUEcNaLH9E1HYxJm9lZC858wjl9tfPiOKpF6yXAgsGed5upoJbgwjLdYBxmGKKqLovlgMLKxTUm1GZ/r4lOAf8ljNECtrpSThoByHLy40adKNCsAo9MrHvPJpfukaWLDqNOPefrSWJCE8AwgDUAXSspLJbQ+vxqxrHccC7kICEHSQysSBAzOeAnnDhTCq83A== 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=rvB0fOABE6lE6awUP0noGUAhBltU8FDvaacxtm/hOBc=; b=e+MGl3z5L5FqpDAQlq/gE5w3Bi51Iw/MPVIRMKOLQV6aSAIyMOpkz3GCFkO6DX0aMCQGbXYtQHL3VFwc0ujVFsWPq/NbNQseM/2eS7ISOuNzEpjpy/plNuGG4gRGpUbUlg0hW5GKEbm1km7wGPnNBtkR/v8kO2IaYfLWHvzNpP4= Received: from AM3PR04CA0139.eurprd04.prod.outlook.com (2603:10a6:207::23) by AS8PR08MB9241.eurprd08.prod.outlook.com (2603:10a6:20b:5a0::17) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6298.30; Mon, 17 Apr 2023 17:19:51 +0000 Received: from AM7EUR03FT013.eop-EUR03.prod.protection.outlook.com (2603:10a6:207:0:cafe::4d) by AM3PR04CA0139.outlook.office365.com (2603:10a6:207::23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6298.45 via Frontend Transport; Mon, 17 Apr 2023 17:19:51 +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 AM7EUR03FT013.mail.protection.outlook.com (100.127.140.191) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.6319.20 via Frontend Transport; Mon, 17 Apr 2023 17:19:51 +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; Mon, 17 Apr 2023 17:19:51 +0000 Received: from e129171.arm.com (10.57.82.91) by mail.arm.com (10.251.24.31) with Microsoft SMTP Server id 15.1.2507.23 via Frontend Transport; Mon, 17 Apr 2023 17:19:50 +0000 From: Luis Machado To: , Subject: [PATCH,v3 17/17] [gdb/docs] sme: Document SME registers and features Date: Mon, 17 Apr 2023 18:19:45 +0100 Message-ID: <20230417171945.328823-1-luis.machado@arm.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20230411042658.1852730-18-luis.machado@arm.com> References: <20230411042658.1852730-18-luis.machado@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain X-EOPAttributedMessage: 1 X-MS-TrafficTypeDiagnostic: AM7EUR03FT013:EE_|AS8PR08MB9241:EE_|AM7EUR03FT035:EE_|PR3PR08MB5676:EE_ X-MS-Office365-Filtering-Correlation-Id: 957bb4b6-585c-455e-e6e0-08db3f67f9a6 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: DL8I4JzgMkM9ypseY6bY3K80OtgQvVZ2yf99bcuj2fTcGl/VFB2LSaWzlxDeTV7ko5K7XPb+98MjSy0dNqDmAhqCr5XZEUZBmHnylJcEhDbGPv76vO4Ccyb7pZE/NCaeXFaz5QgfPw6v3N3pkDLUopq5bUIAPuwNpUO3FMXN91qlE3vPDEfDhY7k4e8JXf1vnBSYSAD2AruA4ZBrSjkDEVOsPFqBAIPQUHt9JJ9qzWPOUTfKi25cmp45uAS20X4FKnfY2feOa5y6QygrbeSXBo2xjgW2i2/qaGzJWpd2i4ibkcOODLrrNCG/LeDI8KntvjFPAeyey5wjC5/XXYsBB5V9ImRoXnKTv3cBtUtCMBvHmwlqz9VT8YpspiAA3IuYT4vVSAVYbIk9PkvUVyhtGVi+rIQrb6kA7i0/LaUuK5BBvbiMJYZ2+9MR/PaxRQmaijg/Cm/divdYsHQgRPnAkYFuFGms31SWWR1tXrD8QSCdLlC4i6Gmfw2Kk7xIY1dGO7EYS88U5GPD+s3ncEtoQZlFGZ1eRlMYRuQL7mlpb7nsETNsZBKl2hzY0a51tBI7BEJLVeNcjB7yutVRpmypTlsF1zDrNLmk0Mhi1+Xa9VZssMuoMGFta6F34NaYNvwpShcawdp6Q9dW/NjddwZQ/Ml3GenYGVT7J9sNrNyJBU0GkHQfz3x4lBOC4qKC8f0qc2ZB5/2wuog1hYBmq2+cEKpwQqvoyjVChyW67UNfqzz11sRbbqXx3XWdh17y2XrKe4o3uehyydXyRH5eveTqKw== 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)(346002)(376002)(39860400002)(136003)(396003)(451199021)(36840700001)(40470700004)(46966006)(40460700003)(426003)(336012)(2616005)(186003)(82310400005)(40480700001)(26005)(1076003)(47076005)(70586007)(81166007)(70206006)(2906002)(356005)(110136005)(6666004)(7696005)(8936002)(41300700001)(8676002)(44832011)(5660300002)(478600001)(30864003)(36860700001)(36756003)(82740400003)(83380400001)(316002)(86362001)(36900700001);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS8PR08MB9241 X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM7EUR03FT035.eop-EUR03.prod.protection.outlook.com X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id-Prvs: 24b08dea-322a-4917-489d-08db3f67f452 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: DXI0g0XrFkJzoH8WFwCOoZOMrDlNMXLaMh+6vWLQ9HVcY5TMU+YCrOtYuarSbtNatqQrORK9z375ZZyxshfoMa69wsW+6DOIJRGhc8nxi6VtBCKlp/kUzi6tx811SPgY+k0fXnCtv+BpCZXndcjprs+pVZr/BuvqdaFvwSeF6vfIQ8gMJNwT02RlRq8/hbUKy/sWNJiTrOXjSFR1XoO+zpAHaIuz+lE3mIu5dUb0CqSM966EciIAMllMQbzhlpTSDvEDg1LKbZ8a5uA28JTV6jwSJk/GwE0ebPIDWnVP/bMSHVauZkSVpH/oqsJYm3KjLegfuM3lsYoDQgnFhlsqHN3+Qi2xpqS82oPRdKA1FWHCcG5nDdzRhogLb2LgZSJRo2Z2dsga/LTEIRO/e9LLl2Mf4UtXhhCKySgUHEgwE6PZVR1O+req73v/cIsyxPXKLZCfdp7BFwe5U6k/I7dxQ3/HwKsjvXfjo058kNIrSlOlgTq6SHEU6+dfRnszvSzG83g9hh8ewCN8FsS62LFEZQyV9nP6i4umZWD3CbUTXRM6T5uexGWGMtcfhSKv7tpGLiwtRKc8BgV5RodY/vuCZCSOIuzS5wUc3OU+7/+X2qOOM311r2DNbljxL9q+u8/z68jwvz9qaSLSb7qP54GZQuNEqiiUXwqT6/MA3V3ThvIOI3u4L5oWbnOaU00dByr1WLaOxqjrsQudz7PdiHgUxzNZtEhBfcrkJ2w88RybHJ0= 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)(396003)(39860400002)(136003)(376002)(346002)(451199021)(36840700001)(46966006)(40470700004)(36756003)(44832011)(40460700003)(82310400005)(2906002)(30864003)(5660300002)(8936002)(8676002)(41300700001)(81166007)(40480700001)(86362001)(478600001)(110136005)(2616005)(36860700001)(26005)(1076003)(186003)(6666004)(7696005)(336012)(426003)(70206006)(70586007)(82740400003)(83380400001)(47076005)(316002);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 17 Apr 2023 17:20:00.4922 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 957bb4b6-585c-455e-e6e0-08db3f67f9a6 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: AM7EUR03FT035.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: PR3PR08MB5676 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 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 54b5da21245..e3ce7d7e881 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 940315b2713..3149e5a6765 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -26045,6 +26045,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 +@anchor{VL} +@cindex VL +@code{VL}: The vector length, in bytes. It defines the size of each @code{Z} +register. + +@item +@anchor{VQ} +@cindex VQ +@code{VQ}: The number of 128 bit units in @code{VL}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. + +@item +@anchor{VG} +@cindex VG +@code{VG}: The number of 64 bit units in @code{VL}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. + +@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 (@code{VL} for short), the @acronym{SME} @code{ZA} matrix +register's size is directly related to the streaming vector length +(@code{SVL} for short). @xref{VL} @xref{SVL} + +The @code{ZA} matrix 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 @code{SVL}. When streaming +mode is disabled, the SVE registers have vector length @code{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 +@anchor{SVL} +@cindex SVL +@code{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 @code{@var{SVL}x@var{SVL}}. + +When streaming mode is enabled, it defines the size of the @acronym{SVE} +registers as well. + +@item +@anchor{SVQ} +@cindex SVQ +@code{SVQ}: The number of 128 bit units in @code{SVL}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. + +@item +@anchor{SVG} +@cindex SVG +@code{SVG}: The number of 64 bit units in @code{SVL}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. + +@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 @code{@var{SVL}x@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 +@code{@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 +(@code{SVG}) for the current thread. From @code{SVG} we can easily derive +the @code{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 @code{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 @code{VG} for their sizes. @xref{VG}. + +If the @sc{za} bit is 1, it means the @code{ZA} state, and therefore the +@code{za} register, is being used and has meaningful contents. If the +@sc{za} bit is 0, the @code{ZA} state is unavailable and the contents of the +@code{za} register 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 @code{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 @code{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 @code{VL} as opposed to @code{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 (@code{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 @code{SVL}. The number of slices is the same as the value of @code{SVL}. + +The number of available tile slice pseudo-registers can be large. For a +minimum @code{SVL} of 16 bytes, there are 5 (number of qualifiers) x +2 (number of directions) x 16 (@code{SVL}) pseudo-registers. For the +maximum @code{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 @code{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 @code{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 @code{SVL} mid-execution, will operate with a potentially +different @code{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} @@ -48071,6 +48289,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 @code{SVL} x @code{SVL} +bytes. @xref{SVL} + +@item +@samp{svg} is a 64-bit register containing the value of @code{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 -- 2.25.1