doc: Update documentation on MODE_PARTIAL_INT subregs

Message ID 20200831165915.jzly4pgtadxcvpxp@jozef-acer-manjaro
State New
Headers show
Series
  • doc: Update documentation on MODE_PARTIAL_INT subregs
Related show

Commit Message

Jozef Lawrynowicz Aug. 31, 2020, 4:59 p.m.
In d8487c949ad5 (~GCC 4.9.0), MODE_PARTIAL_INT modes were changed from
having an unknown number of undefined bits, to having a known number of
undefined bits, however the documentation on using SUBREG expressions
with MODE_PARTIAL_INT modes was not updated to reflect this.

The attached patch updates that portion of the GCC internals
documentation.

Ok for trunk?
From e195dce328b272cd413ca7c659b800170eb60f2c Mon Sep 17 00:00:00 2001
From: Jozef Lawrynowicz <jozef.l@mittosystems.com>

Date: Mon, 31 Aug 2020 17:26:31 +0100
Subject: [PATCH] doc: Update documentation on MODE_PARTIAL_INT subregs

In d8487c949ad5, MODE_PARTIAL_INT modes were changed from having an
unknown number of undefined bits, to having a known number of undefined
bits, however the documentation on using SUBREG expressions with
MODE_PARTIAL_INT modes was not updated to reflect this.

gcc/ChangeLog:

	* doc/rtl.texi (subreg): Fix documentation to state there is a known
	number of undefined bits in regs and subregs of MODE_PARTIAL_INT modes.

---
 gcc/doc/rtl.texi | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

-- 
2.28.0

Comments

Richard Sandiford Sept. 7, 2020, 12:55 p.m. | #1
Jozef Lawrynowicz <jozef.l@mittosystems.com> writes:
> In d8487c949ad5 (~GCC 4.9.0), MODE_PARTIAL_INT modes were changed from

> having an unknown number of undefined bits, to having a known number of

> undefined bits, however the documentation on using SUBREG expressions

> with MODE_PARTIAL_INT modes was not updated to reflect this.

>

> The attached patch updates that portion of the GCC internals

> documentation.

>

> Ok for trunk?


Thanks for doing this.  OK for trunk with one very minor nit:

> -does not guarantee that @samp{(subreg:HI (reg:PSI 0) 0)} has the

> -value @samp{(reg:HI 4)}.

> +sets the low 16 bits of @samp{(reg:PSI 0)} to @samp{(reg:HI 4)}, and

> +the high 4 defined bits of @samp{(reg:PSI 0)} retain their

> +original value.  The behavior here is therefore the same as


IMO reads more naturally as “the same as for”.

Richard

> +normal @code{subreg}s, when there are no

> +@code{MODE_PARTIAL_INT} modes involved.

>  

>  @cindex @code{TARGET_CAN_CHANGE_MODE_CLASS} and subreg semantics

>  The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.
Jozef Lawrynowicz Sept. 7, 2020, 4:56 p.m. | #2
On Mon, Sep 07, 2020 at 01:55:59PM +0100, Richard Sandiford wrote:
> Jozef Lawrynowicz <jozef.l@mittosystems.com> writes:

> > In d8487c949ad5 (~GCC 4.9.0), MODE_PARTIAL_INT modes were changed from

> > having an unknown number of undefined bits, to having a known number of

> > undefined bits, however the documentation on using SUBREG expressions

> > with MODE_PARTIAL_INT modes was not updated to reflect this.

> >

> > The attached patch updates that portion of the GCC internals

> > documentation.

> >

> > Ok for trunk?

> 

> Thanks for doing this.  OK for trunk with one very minor nit:

> 

> > -does not guarantee that @samp{(subreg:HI (reg:PSI 0) 0)} has the

> > -value @samp{(reg:HI 4)}.

> > +sets the low 16 bits of @samp{(reg:PSI 0)} to @samp{(reg:HI 4)}, and

> > +the high 4 defined bits of @samp{(reg:PSI 0)} retain their

> > +original value.  The behavior here is therefore the same as

> 

> IMO reads more naturally as “the same as for”.

> 

> Richard

> 

> > +normal @code{subreg}s, when there are no

> > +@code{MODE_PARTIAL_INT} modes involved.

> >  


Thanks, fixed and applied.

Jozef

Patch

diff --git a/gcc/doc/rtl.texi b/gcc/doc/rtl.texi
index f8e1f950823..4760bb97d52 100644
--- a/gcc/doc/rtl.texi
+++ b/gcc/doc/rtl.texi
@@ -2209,17 +2209,22 @@  whether the subreg is a lowpart of a block.
 @end table
 
 A @code{MODE_PARTIAL_INT} mode behaves as if it were as wide as the
-corresponding @code{MODE_INT} mode, except that it has an unknown
-number of undefined bits.  For example:
+corresponding @code{MODE_INT} mode, except that it has a number of
+undefined bits, which are determined by the precision of the
+mode.
+
+For example, on a little-endian target which defines @code{PSImode}
+to have a precision of 20 bits:
 
 @smallexample
 (subreg:PSI (reg:SI 0) 0)
 @end smallexample
 
+accesses the low 20 bits of @samp{(reg:SI 0)}.
+
 @findex REGMODE_NATURAL_SIZE
-accesses the whole of @samp{(reg:SI 0)}, but the exact relationship
-between the @code{PSImode} value and the @code{SImode} value is not
-defined.  If we assume @samp{REGMODE_NATURAL_SIZE (DImode) <= 4},
+Continuing with a @code{PSImode} precision of 20 bits, if we assume
+@samp{REGMODE_NATURAL_SIZE (DImode) <= 4},
 then the following two @code{subreg}s:
 
 @smallexample
@@ -2227,9 +2232,8 @@  then the following two @code{subreg}s:
 (subreg:PSI (reg:DI 0) 4)
 @end smallexample
 
-represent independent 4-byte accesses to the two halves of
-@samp{(reg:DI 0)}.  Both @code{subreg}s have an unknown number
-of undefined bits.
+represent accesses to the low 20 bits of the two halves of
+@samp{(reg:DI 0)}.
 
 If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:
 
@@ -2240,15 +2244,17 @@  If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:
 
 represent independent 2-byte accesses that together span the whole
 of @samp{(reg:PSI 0)}.  Storing to the first @code{subreg} does not
-affect the value of the second, and vice versa.  @samp{(reg:PSI 0)}
-has an unknown number of undefined bits, so the assignment:
+affect the value of the second, and vice versa, so the assignment:
 
 @smallexample
 (set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
 @end smallexample
 
-does not guarantee that @samp{(subreg:HI (reg:PSI 0) 0)} has the
-value @samp{(reg:HI 4)}.
+sets the low 16 bits of @samp{(reg:PSI 0)} to @samp{(reg:HI 4)}, and
+the high 4 defined bits of @samp{(reg:PSI 0)} retain their
+original value.  The behavior here is therefore the same as
+normal @code{subreg}s, when there are no
+@code{MODE_PARTIAL_INT} modes involved.
 
 @cindex @code{TARGET_CAN_CHANGE_MODE_CLASS} and subreg semantics
 The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.