From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR03-AM7-obe.outbound.protection.outlook.com (mail-am7eur03on2065.outbound.protection.outlook.com [40.107.105.65]) by sourceware.org (Postfix) with ESMTPS id 2E1773858D28 for ; Tue, 11 Apr 2023 07:23:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 2E1773858D28 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=wWivGczcXl/RpFAPXa9I84IpvrkdmKT4SLnmzmWo9+A=; b=ndShrQAuvHC2D4A2zkH12iLKVdiNvMVuf2Lh7QS9onNbyo1AKJ9YWgyJUidnRqvqjeZkfJRgxrdlZLcI2VnuCNARFylXC2ECm5PgsNk5v0doEWTA+Wpx3NtSbKlG6MATmtAhYirwg/03wAgPsDD1iaSOtiCyPrp86dd+AGJHchE= Received: from AS9PR05CA0205.eurprd05.prod.outlook.com (2603:10a6:20b:495::12) by PAWPR08MB8957.eurprd08.prod.outlook.com (2603:10a6:102:33d::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6254.35; Tue, 11 Apr 2023 07:22:52 +0000 Received: from AM7EUR03FT011.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:495:cafe::ce) by AS9PR05CA0205.outlook.office365.com (2603:10a6:20b:495::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6277.38 via Frontend Transport; Tue, 11 Apr 2023 07:22:51 +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 AM7EUR03FT011.mail.protection.outlook.com (100.127.140.81) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6298.28 via Frontend Transport; Tue, 11 Apr 2023 07:22:51 +0000 Received: ("Tessian outbound 8b05220b4215:v136"); Tue, 11 Apr 2023 07:22:51 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: a13db0ee406f37a1 X-CR-MTA-TID: 64aa7808 Received: from e9b0e10a5ea1.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id D7DD63B5-E9C6-4542-94C7-18E33E549BE6.1; Tue, 11 Apr 2023 07:22:45 +0000 Received: from EUR04-DB3-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id e9b0e10a5ea1.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Tue, 11 Apr 2023 07:22:45 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=MAlHJqgjN5gFhqAS0B1UfyL9/ptmdN80QW5oSVo0Vr8Equm7zDuS+miidK6V5RU9tfHSVg64ZJil+K/lRnzGCFGVNKFZdA3cd7phl6okfzaEqbkDbQtT6CjenerBlZDbTNfxPXjhvIloMywMicnyJclyGsqi6nMxQpwKmiA5S8yl46k7/+hTIjXJJUw2ODNlwwe05QcqDYQt3Q1ASfIvxZnljeBXQ1ZVdHiAvWD3xI2+e2MU/j6NDtLcsPTGxg5a6mRMSLVcVtOsEMRBQFql6YjuUKue7fRfb7c/4PLzVgB2Ls7rj606nwoqpGPMb9ov0Pc9xOr972gWbC6UgIK1pQ== 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=wWivGczcXl/RpFAPXa9I84IpvrkdmKT4SLnmzmWo9+A=; b=aqZ2E3P3bNFozInPkYFB4LygrSng7VpqGtAiruonoE3ljVRK1MMxGVY1I093oDx3GviKpLP3NPP0Qrt6FAYirnep0Tq20yS/v9NqnqP4ZX37odlb5JwoktCgAait547Hsvweyw3R3ktSvqx7/MTYSjWwX5NAY3Uep9rYp1bkIxFjr4U7VtZS8Bp2apO4Mb76GHwIbgz8txvUr2GgNIFsQqQVmEV6u4/ibqQMGIrEH0eYV4i+bxUnE71qsUSfjIhAVRQDK6ABZM3YlPB12KGtRIG1qkwiB5ATv2b+UDuy/NHtQCQbWp33KAvP28+5l45iajL+7LrjA5dexwTRcEKv/A== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass header.d=arm.com; 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=wWivGczcXl/RpFAPXa9I84IpvrkdmKT4SLnmzmWo9+A=; b=ndShrQAuvHC2D4A2zkH12iLKVdiNvMVuf2Lh7QS9onNbyo1AKJ9YWgyJUidnRqvqjeZkfJRgxrdlZLcI2VnuCNARFylXC2ECm5PgsNk5v0doEWTA+Wpx3NtSbKlG6MATmtAhYirwg/03wAgPsDD1iaSOtiCyPrp86dd+AGJHchE= Authentication-Results-Original: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=arm.com; Received: from VI1PR08MB3919.eurprd08.prod.outlook.com (2603:10a6:803:c4::31) by GV1PR08MB8692.eurprd08.prod.outlook.com (2603:10a6:150:86::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6277.38; Tue, 11 Apr 2023 07:22:37 +0000 Received: from VI1PR08MB3919.eurprd08.prod.outlook.com ([fe80::ff70:5431:70fa:34bf]) by VI1PR08MB3919.eurprd08.prod.outlook.com ([fe80::ff70:5431:70fa:34bf%4]) with mapi id 15.20.6277.038; Tue, 11 Apr 2023 07:22:36 +0000 Message-ID: <6e8f7223-5019-c6f4-1e89-e778726790ea@arm.com> Date: Tue, 11 Apr 2023 08:22:28 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.9.0 Subject: Re: [PATCH 17/17] [gdb/docs] sme: Document SME registers and features Content-Language: en-US To: Eli Zaretskii Cc: gdb-patches@sourceware.org References: <20230411042658.1852730-1-luis.machado@arm.com> <20230411042658.1852730-18-luis.machado@arm.com> <833556c2ue.fsf@gnu.org> From: Luis Machado In-Reply-To: <833556c2ue.fsf@gnu.org> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-ClientProxiedBy: SA1P222CA0119.NAMP222.PROD.OUTLOOK.COM (2603:10b6:806:3c5::18) To VI1PR08MB3919.eurprd08.prod.outlook.com (2603:10a6:803:c4::31) MIME-Version: 1.0 X-MS-TrafficTypeDiagnostic: VI1PR08MB3919:EE_|GV1PR08MB8692:EE_|AM7EUR03FT011:EE_|PAWPR08MB8957:EE_ X-MS-Office365-Filtering-Correlation-Id: 6b45f6db-9bea-4f06-d8ae-08db3a5d8f65 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: xjN/4BaCAUvehmF6FW2FdijgxJAznaLzRCPJkcro20K+Hf6T5egTpftcW1r7GujOfNbmSCZrqa8s3Ol+hdaiyPnwmeyJE6QbpaTofC3ICYP4kECYBYMQYJR2ms2d43qIMHMNtSToB0LDfSd3Q9bIH67j60oF19IqISnaf7dIEsHMu0+PVNgOHN2gUYnQbEhJkS+aLe8uE10mEFrSYT4Y5h4wX0itrKzVw8fGJqdAY2W+RUi29VyZH4TPQghV8cgFiL8b+QVfVzD/CzV+g5Shw431iiYWdy7rMtbzcgsijHZ+wW7ryWOy2+6bGwz6ipw2gSAspAURAdCV0r0qCYbFYMO4glPD1UTuZoHkFBhR4fOnE59gOODOP8+FZL1UpkzYSyopE2LyieSKveenltZE5339sZm1o3iC4051prKrRC9mrFRa70H4K5nKzRrN6LtSUoez8PwkvJymWP1Ua4WvdTHp9yH1WDRws8JVaTHBvAfGUtWdd/X3kwqIDnnHJeHv/154trw0zMTPOX5X38ruoBRUXtzu2yZenNel9b+nh4bNC7MuZh1UtpS/Dr03uk0iMe3f6Yy7zAHbXIVFoCHjYm27BILbubWzCYhuAj1s3VYu2ywPzIbcyhbHQdWXAlsQrK1pxvkWfskzozpStt2RHh0/PiAnLJB4uUswUhTWpyJsYHH153YBQ1w0WDKnyITr X-Forefront-Antispam-Report-Untrusted: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:VI1PR08MB3919.eurprd08.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230028)(4636009)(39860400002)(136003)(376002)(396003)(366004)(346002)(451199021)(31696002)(6486002)(86362001)(53546011)(6512007)(6506007)(478600001)(26005)(36756003)(5660300002)(186003)(316002)(38100700002)(66476007)(66946007)(66556008)(31686004)(4326008)(6916009)(6666004)(41300700001)(2616005)(2906002)(83380400001)(8936002)(8676002)(44832011)(43740500002)(45980500001)(357404004);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV1PR08MB8692 Original-Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=arm.com; X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM7EUR03FT011.eop-EUR03.prod.protection.outlook.com X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id-Prvs: 20bcada1-7f41-4d3f-5427-08db3a5d8522 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: XmMd9KGCZbf6ag2AW+Wpp76NrGRTX/VUv/8vFBPgYGDhMMwKLqv3dQLbzL36B+dQpMsYDk2QmyHPmGCAE2t3apzmmZtU9bHTy+ZreUyTrQ1MexskQ6N+dFOEk7j+Ig/lIuDm6CPdCgEDiClKEVnEU4Bmv0BGb+onDfUxuqxmo0gK/dE1znZoWGalYFjpDNT0P2wvnYv4BjGLwfylFhFUB1B/uazUZGkMXDKyEW0g3NjJcqDZNDdTfcCGYbjuzlo0wO+OJkN9e6byo10maNbgh4hqJS5W8egueyalvuFz0dKwpKfbgnEOOCHGwxGOruLqolkcxhDnLXkGN3UxIdnBaCFMgL4BVatoThhop6NR4SvRFz+VeaGMayXwyHQsNyJAVgElQMwohPWnk8a6IhTkNLbf9+D63dTFJgMDyTfHg+dWMJR6TYz0yDDvWwdYWyhZE7eOU5SCpkeb/PJQJ2Lo9c0RbsTF5OkbyWyksvZ/uc+eQReM2L7SpMQMPMsO4/Up4G+AytzSr5jAbcZS50SC8tIMQi6zYAH8E9NmdVomveGDpDWj0851m3q1e5Kcb9alX1H7w7KrG+TNveS/+7RP+iuuJefuZgXSVObI47/XbOqAaPgxcKr38rFoU/Hn2xcBdGs/5W7NRTWgYU7C4UfA19IXrNAw4ar450ymBxk5g2tI1jRtrgw5VMBGpNjV14TdAAIOjJchWQRavz7DXgN85skANNPYLVM2b2/SQ21VP7bh/D9mQ8dqPJhJVyffJIIhXApTxYqoii4OERdgamnEGA== 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)(346002)(396003)(136003)(39860400002)(451199021)(36840700001)(40470700004)(46966006)(47076005)(356005)(6486002)(6666004)(186003)(41300700001)(81166007)(31686004)(2616005)(26005)(53546011)(6512007)(336012)(83380400001)(6506007)(36860700001)(478600001)(40460700003)(316002)(2906002)(40480700001)(31696002)(86362001)(82310400005)(70586007)(70206006)(4326008)(8676002)(82740400003)(5660300002)(44832011)(36756003)(8936002)(6862004)(43740500002)(357404004);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 11 Apr 2023 07:22:51.4461 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 6b45f6db-9bea-4f06-d8ae-08db3a5d8f65 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: AM7EUR03FT011.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: PAWPR08MB8957 X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,FORGED_SPF_HELO,GIT_PATCH_0,KAM_DMARC_NONE,NICE_REPLY_A,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: Hi Eli, Thanks for the quick feedback. On 4/11/23 08:08, Eli Zaretskii wrote: >> Date: Tue, 11 Apr 2023 05:26:58 +0100 >> From: Luis Machado via Gdb-patches >> >> 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 | 68 +++++++++++++++++++++++++++++++++++++++++++++ >> 2 files changed, 79 insertions(+) > > Thanks. > >> diff --git a/gdb/NEWS b/gdb/NEWS >> index 10a1a70fa52..48a82172f0e 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. >> + >> * GDB now has some support for integer types larger than 64 bits. > > This part is OK. > >> +@subsubsection AArch64 SME. >> +@cindex AArch64 SME. > > Please also add a @cindex entry with the full name: scalable matrix > extension. > >> +The @code{za} register is a 2-dimensional vector of bytes with a size of svl >> +x svl, where svl is the streaming vector length. > > I suggest to rephrase: > > The @code{za} register is a 2-dimensional rectangular > @code{@var{n}x@var{n}} matrix of bytes, where @var{n} is the > streaming vector length. > > Should the text also explain what is this "streaming vector", its > length and "granule"? The text seems to use these terms all over > assuming the reader knows what they mean. > >> +The @code{svg} vector is the streaming vector granule for the current thread > ^^^^^^ > "register", not "vector", right? > >> +and represents the number of 64-bit chunks in one dimension of the @code{za} >> +register. > > What do you mean by "represents the number"? how can one "represent" a > number? > > Also, it sounds like the @var{n} I suggested to use above is related > to this register, in which case the description of ZA should make that > relation explicit. (I can suggest how once I understand the subject > well enough, see the questions above.) > >> +The @code{svcr} register (streaming vector control register) is a status >> +register that holds two state bits: @code{SM} in bit 0 and @code{ZA} in bit 1. > > I suggest to use @sc{sm} and @sc{za} here, instead of @code{SM} and > @code{ZA}. Try that in PDF and see which you like better. (Note that > @sc has its effect only on lower-case characters of its argument.) > >> +If the @code{SM} bit is 1, it means the current thread is in streaming >> +mode, and the SVE registers will have their sizes based on the @code{svg} >> +register. > > What does it mean for "the SVE registers will have their sizes based > on the @code{svg} register"? The text should explain this more > explicitly, IMO. > >> If the @code{SM} bit is 0, the current thread is not in streaming >> +mode, and the SVE registers have sizes based on the @code{vg} register. > > This refers to stuff explained elsewhere (the 'vg' register), so a > cross-reference is in order. > >> +If the @code{ZA} state is 0, the @code{za} register and its pseudo registers >> +will read as . > > What are the pseudo registers of the ZA register? I don't think they > were described earlier in the text. > >> +The minimum size of the @code{za} register is there 16 x 16 bytes, and the >> +maximum size is 256 x 256 bytes. The size of the @code{za} register is the >> +size of all the SVE @code{z} registers combined. > > By "The size of the @code{za} register" do you mean the number of > bytes in the matrix? That is, if ZA is 16 x 16, then its size is > 16*16=256 bytes, or is it 16 bytes? > >> +The @code{za} register can also be referenced using tiles and tile slices. > > Referenced how? Should the text say anything specific about this > slice referencing, before talking (below) about the number of slices? > >> +There is a fixed number of @code{za} tile pseudo registers (32). They are: >> +za0b, za0h, za1h, zas0, zas1, zas2, zas3, zad0, zad1, zad2, zad3, zad4, zad5. > > This should probably preceded by something like > > A @dfn{tile} of the @code{za} register is a pseudo-register which > can be used to... ". > >> +The tile slice pseudo registers are numerous. For a minimum streaming vector >> +length of 16 bytes, there are 5 x 32 pseudo registers. For the maximum >> +streaming vector length of 256 bytes, there are 5 x 512 pseudo registers. >> + >> +The tile slice pseudo registers have the following naming pattern: >> + >> +za. > > Likewise here: there should be a short explanation of what are tile > slices and how to use them. > > All in all, I find this description rather terse and almost > impenetrable. I guess only those who are already familiar with this > architecture will fully understand it. Maybe this is the assumption > for the readers of this stuff, but then perhaps include a reference to > some external description of the architecture, and just say that GDB > supports this and that registers and pseudo-registers, without going > into any details regarding the meaning and purpose of each one of > them. As is usually the case, developers tend to assume some of the subject matter is already understood by whoever is developing software using a particular architectural feature. :-) I agree the current documentation is a bit on the light side. Let me try to fill the gaps in v2. Hopefully that will make the description of how SME is being used in gdb a bit more clear. > >> +@samp{za} is a vector of bytes of size svl x svl. @samp{svg} is a 64-bit >> +pseudo register containing the number of 64-bit chunks in svl. @samp{svcr} >> +is a 64-bit state register containing bits 0 (SM) and 1 (ZA). > > This again mentions "svl" without saying anything about it. > > Reviewed-By: Eli Zaretskii