From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10]) by sourceware.org (Postfix) with ESMTPS id A9E543858D28 for ; Tue, 11 Apr 2023 07:08:47 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org A9E543858D28 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gnu.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gnu.org Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pm87S-0000Fy-HY; Tue, 11 Apr 2023 03:08:46 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=NeeGt6q6YscEipPrypSm/e/7HiMeUHsNfJFGrVIvvbE=; b=BxPrMLYGlEXh eYnrSbHI0GoABHpIiYQT5rMkSttQ55cdMsj36avPlJiwoZgs4QxojPQJNt7PijTOgHq4FlJEBtlFi /8yEBZsY400dng10yulCQCYeMcyTvOWd9JSnyt+SaX9EYqANkdfjF1yfk/GEO+kOJ7wWj1af+1L5s i3SfNpVlZaQlYbY1zYf5pwIEskPnbliqiK3kKA6SURuL/bo6jVvncuVTzm+DxepxowOIcvJEqCRt7 ppoBi0p/CgW3NRMMMLVOAbjdlL4lb9CaO/BcJ727rIcBlKrjVuwvraPViMXBjhBgKqvGMzkOpEfWG s+6TiDr46Ksc192Phentgg==; Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pm87K-00021D-L0; Tue, 11 Apr 2023 03:08:43 -0400 Date: Tue, 11 Apr 2023 10:09:13 +0300 Message-Id: <833556c2ue.fsf@gnu.org> From: Eli Zaretskii To: Luis Machado Cc: gdb-patches@sourceware.org In-Reply-To: <20230411042658.1852730-18-luis.machado@arm.com> (message from Luis Machado via Gdb-patches on Tue, 11 Apr 2023 05:26:58 +0100) Subject: Re: [PATCH 17/17] [gdb/docs] sme: Document SME registers and features References: <20230411042658.1852730-1-luis.machado@arm.com> <20230411042658.1852730-18-luis.machado@arm.com> X-Spam-Status: No, score=-7.0 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_BARRACUDACENTRAL,SPF_HELO_PASS,SPF_PASS,TXREP 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: > 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. > +@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