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 37F9C3858D38 for ; Fri, 19 May 2023 11:20:21 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 37F9C3858D38 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 1pzy9k-0004Fx-Dh; Fri, 19 May 2023 07:20:20 -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=8wqbLOPLR3Isw/YJxQaQBEzBJ9ENMFY71jjSOv686+g=; b=HE6KCFheym7E 6I9Jxec3PLbgz4DmNmaF2SKDEigZ/1mSFnpda7/d/CPDp/8ARpgkML6Yw/1mAAxoLG18+z3+TfjDR J/a/WXF8s6rBlHEms55Doaya8M2tfGBdEx20AKtNJTfPJpoTSbbMYyayBjLtKB1Irx4VsxcxhMRPX fKayuZB4MaWraZLxsbd46hB7gS9ygEs/Cv9TtV3mR1o2iNUDXdTaoJE3maAuqHmfEekYBhexQDVCT Sybmi+TPVUnwpYZiz5t6FsFMbtf5ydaXSSsKDnAt13n3OQx++8G3+0M3fFtO0EO0l9QeNU5CJwsRN sVXn3kLXAh9TySULUqvwaQ==; 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 1pzy9h-0007s5-OP; Fri, 19 May 2023 07:20:19 -0400 Date: Fri, 19 May 2023 14:20:32 +0300 Message-Id: <83lehktvnj.fsf@gnu.org> From: Eli Zaretskii To: Luis Machado Cc: gdb-patches@sourceware.org In-Reply-To: <20230519102508.14020-18-luis.machado@arm.com> (message from Luis Machado via Gdb-patches on Fri, 19 May 2023 11:25:08 +0100) Subject: Re: [PATCH v3 17/17] [gdb/docs] sme: Document SME registers and features References: <20230519102508.14020-1-luis.machado@arm.com> <20230519102508.14020-18-luis.machado@arm.com> X-Spam-Status: No, score=1.7 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_BARRACUDACENTRAL,SPF_HELO_PASS,SPF_PASS,TXREP,T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.6 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: > Date: Fri, 19 May 2023 11:25:08 +0100 > From: Luis Machado via 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. Thanks. This part of the patch has numerous inconsistencies in letter-case and markup of register names, see below. > +The @code{za} register state can be either active or inactive, if it is not in > +use. "@code{ZA}", upper-case. > +@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}. Same here. > +The @code{za} register is a 2-dimensional square @var{svl} by @var{svl} And here. > +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. And here. > +The @var{svg} register always contains the streaming vector granule ^^^^^^^^^ "@code{SVG}" > +(@var{svg}) for the current thread. From @var{svg} we can easily derive Same here. > +The @code{svcr} pseudo-register (streaming vector control register) is a status Same here: "@code{SVCR}" > +If the @sc{za} bit is 1, it means the @code{za} register is being used and ^^^^^^^^^ "@code{ZA}", upper-case. > +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. Same here. > +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. And here. > +It is possible for users to change @var{svl} during the execution of a > +program by modifying the @var{svg} register value. ^^^^^^^^^ "@code{SVG}" > +Whenever the @var{svg} register is modified with a new value, the Same here. > +@item The @code{za} register will have a new size and its state will be "@code{ZA}" > +@sc{sm} bit was 0 prior to modifying the @var{svg} register, there will be no ^^^^^^^^^ "@code{SVG}" > +The possible values for the @var{svg} register are 2, 4, 8, 16, 32. These Same here. > +The minimum size of the @code{za} register is 16 x 16 (256) bytes, and the "@code{ZA}" > +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} Same here, and also "@code{Z}", upper-case. > +The @code{za} register can also be accessed using tiles and tile slices. "@code{ZA}" > +Tile pseudo-registers are square, 2-dimensional sub-arrays of elements within > +the @code{za} register. Same here. > +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}. Same here: all the register names should be in upper-case. > +Tile slice pseudo-registers are vectors of horizontally or vertically > +contiguous elements within the @code{za} register. "@code{ZA}" > +The tile slice pseudo-registers have the following naming pattern: > +@code{za<@var{tile number}><@var{direction}><@var{qualifier}> > +<@var{slice number}>}. Same here. > +When listing all the available registers, users will see the > +currently-available @code{za} pseudo-registers. Pseudo-registers that don't And here. > +account the @code{svcr} pseudo-register bits nor the @code{za} register And here. > +contents. @xref{Calling} ^^ Two spaces there. > +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}. Please up-case the names of the registers here. > +@value{GDBN} showing incorrect values for the @code{za} register and "@code{ZA}" > +The @samp{org.gnu.gdb.aarch64.sme} feature is optional. If present, > +it should contain registers @samp{za}, @samp{svg} and @samp{svcr}. Since you use @code, not @samp, for register markup elsewhere, please use @code here as well. Also, please up-case the names of the registers. > +@samp{za} is a register represented by a vector of @var{svl}x@var{svl} ^^^^^^^^^ "@code{ZA}" > +@samp{svg} is a 64-bit register containing the value of @var{svg}. @xref{svg}. ^^^^^^^^^^ "@code{SVG}" > +@samp{svcr} is a 64-bit status pseudo-register with two valid bits. Bit 0 ^^^^^^^^^^^ "@code{SVCR}" > +Bit 1 (@sc{za}) shows whether the @code{za} register state is active (in use) or ^^^^^^^^^ "@code{ZA}" > +The rest of the unused bits of the @samp{svcr} pseudo-register is undefined ^^^^^^^^^^^ "@code{SVCR}" Reviewed-By: Eli Zaretskii