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 341593858C83 for ; Sat, 22 Apr 2023 09:21:38 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 341593858C83 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 1pq9R3-0007Lm-2m; Sat, 22 Apr 2023 05:21:37 -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=mepn4HJ0PkIMATXadSRdHjq99ycIpKZCjxvRU+ybYFg=; b=YWWvbmoRhdyw LYGd4x47GEJQdrR8ZO3zfoJL4G8QH7ufbvoSNFSQ7al5TD0q6GnMRIGYw7WQfi0uWtLXooXR3YoX2 0rBkFXeHpOobQICyPZWuOjKltY2p2VBQEYerbx/5O/mUxaY3NMIQlGyPWLl78WRVs+ID/H+seGsjr 6v/Fop246mqEZeakY6ghn1cltDlpmOlh/2xe767reDNI83BbBMeO9resMjLJsja3bsT+1T/0lOilH WPrqInEyZJVqJwt5USQz62Mx2Slpjq8LObW20pPAXtBnoo2foEZkee3fq1Jfx0t/kZ0USCUgq8+9c ZB2HuRAb8K1LkB+Z6jWJnw==; 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 1pq9R2-0005NM-CK; Sat, 22 Apr 2023 05:21:36 -0400 Date: Sat, 22 Apr 2023 12:21:55 +0300 Message-Id: <83ttx81dcc.fsf@gnu.org> From: Eli Zaretskii To: Luis Machado Cc: gdb-patches@sourceware.org In-Reply-To: <20230417171945.328823-1-luis.machado@arm.com> (message from Luis Machado on Mon, 17 Apr 2023 18:19:45 +0100) Subject: Re: [PATCH,v3 17/17] [gdb/docs] sme: Document SME registers and features References: <20230411042658.1852730-18-luis.machado@arm.com> <20230417171945.328823-1-luis.machado@arm.com> X-Spam-Status: No, score=-7.1 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,T_SCC_BODY_TEXT_LINE 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: > From: Luis Machado > Date: Mon, 17 Apr 2023 18:19:45 +0100 > > 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(+) Thanks. > 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. This part is OK. > +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. I thought we agreed to use @var{vl}, @var{vq}, etc., instead of @code{VL} etc.? These are meta-syntactic parameters, they stand for something else, not literally for themselves, so @var is more appropriate. Also, you place @cindex between @item and the text of the @item -- did you verify that typing "i VQ" in an Info reader goes to the beginning of the item's line? I think @cindex should be before @item. > +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 Elsewhere you use @code{za}, lower-case, for the register. Please be consistent in the capitalization of the register names. > +(@code{SVL} for short). @xref{VL} @xref{SVL} ^^ Two spaces there. > +@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. Likewise here: I thought we agreed on using @var{svl} etc., not @code{SVL}. > +The @code{za} register is a 2-dimensional square @code{@var{SVL}x@var{SVL}} And here you actually use @var (which is correct), but with an upper-case argument, which is sub-optimal. The argument of @var should be in lower-case. > +@item > +@samp{za} is a register represented by a vector of @code{SVL} x @code{SVL} ^^^^^^^^^^^^^^^^^^^^^^^ This should use @var, not @code. Also, I'd remove the whitespace around "x". Reviewed-By: Eli Zaretskii