[dev.power64] 5g,6g,8g: synchronize documentation for regopt structures

I added several comments to the regopt-related structures when
porting it to 9g.  Synchronize those comments back in to the
other compilers.

LGTM=rsc
R=rsc
CC=golang-codereviews
https://codereview.appspot.com/175720043

3 files changed, 68 insertions, 20 deletions

diff --git a/src/cmd/5g/opt.h b/src/cmd/5g/opt.h
index 5016d1cc8..01edeb84d 100644
--- a/src/cmd/5g/opt.h
+++ b/src/cmd/5g/opt.h
@@ -75,12 +75,18 @@ struct	Reg
 {
 	Flow	f;
 
-	Bits	set;  		// variables written by this instruction.
-	Bits	use1; 		// variables read by prog->from.
-	Bits	use2; 		// variables read by prog->to.
+	Bits	set;  		// regopt variables written by this instruction.
+	Bits	use1; 		// regopt variables read by prog->from.
+	Bits	use2; 		// regopt variables read by prog->to.
 
+	// refahead/refbehind are the regopt variables whose current
+	// value may be used in the following/preceding instructions
+	// up to a CALL (or the value is clobbered).
 	Bits	refbehind;
 	Bits	refahead;
+	// calahead/calbehind are similar, but for variables in
+	// instructions that are reachable after hitting at least one
+	// CALL.
 	Bits	calbehind;
 	Bits	calahead;
 	Bits	regdiff;
@@ -93,6 +99,16 @@ struct	Reg
 
 #define	NRGN	600
 /*c2go enum { NRGN = 600 }; */
+
+// A Rgn represents a single regopt variable over a region of code
+// where a register could potentially be dedicated to that variable.
+// The code encompassed by a Rgn is defined by the flow graph,
+// starting at enter, flood-filling forward while varno is refahead
+// and backward while varno is refbehind, and following branches.  A
+// single variable may be represented by multiple disjoint Rgns and
+// each Rgn may choose a different register for that variable.
+// Registers are allocated to regions greedily in order of descending
+// cost.
 struct	Rgn
 {
 	Reg*	enter;
@@ -187,16 +203,16 @@ enum
 	SizeF = 1<<7, // float aka float32
 	SizeD = 1<<8, // double aka float64
 
-	// Left side: address taken, read, write.
+	// Left side (Prog.from): address taken, read, write.
 	LeftAddr = 1<<9,
 	LeftRead = 1<<10,
 	LeftWrite = 1<<11,
 	
-	// Register in middle; never written.
+	// Register in middle (Prog.reg); only ever read.
 	RegRead = 1<<12,
 	CanRegRead = 1<<13,
 	
-	// Right side: address taken, read, write.
+	// Right side (Prog.to): address taken, read, write.
 	RightAddr = 1<<14,
 	RightRead = 1<<15,
 	RightWrite = 1<<16,
diff --git a/src/cmd/6g/opt.h b/src/cmd/6g/opt.h
index 4c9bb89fc..08486a04a 100644
--- a/src/cmd/6g/opt.h
+++ b/src/cmd/6g/opt.h
@@ -75,12 +75,18 @@ struct	Reg
 {
 	Flow	f;
 
-	Bits	set;  		// variables written by this instruction.
-	Bits	use1; 		// variables read by prog->from.
-	Bits	use2; 		// variables read by prog->to.
+	Bits	set;  		// regopt variables written by this instruction.
+	Bits	use1; 		// regopt variables read by prog->from.
+	Bits	use2; 		// regopt variables read by prog->to.
 
+	// refahead/refbehind are the regopt variables whose current
+	// value may be used in the following/preceding instructions
+	// up to a CALL (or the value is clobbered).
 	Bits	refbehind;
 	Bits	refahead;
+	// calahead/calbehind are similar, but for variables in
+	// instructions that are reachable after hitting at least one
+	// CALL.
 	Bits	calbehind;
 	Bits	calahead;
 	Bits	regdiff;
@@ -93,6 +99,16 @@ struct	Reg
 
 #define	NRGN	600
 /*c2go enum { NRGN = 600 }; */
+
+// A Rgn represents a single regopt variable over a region of code
+// where a register could potentially be dedicated to that variable.
+// The code encompassed by a Rgn is defined by the flow graph,
+// starting at enter, flood-filling forward while varno is refahead
+// and backward while varno is refbehind, and following branches.  A
+// single variable may be represented by multiple disjoint Rgns and
+// each Rgn may choose a different register for that variable.
+// Registers are allocated to regions greedily in order of descending
+// cost.
 struct	Rgn
 {
 	Reg*	enter;
@@ -165,8 +181,8 @@ typedef struct ProgInfo ProgInfo;
 struct ProgInfo
 {
 	uint32 flags; // the bits below
-	uint32 reguse; // required registers used by this instruction
-	uint32 regset; // required registers set by this instruction
+	uint32 reguse; // registers implicitly used by this instruction
+	uint32 regset; // registers implicitly set by this instruction
 	uint32 regindex; // registers used by addressing mode
 };
 
@@ -187,12 +203,12 @@ enum
 	SizeF = 1<<7, // float aka float32
 	SizeD = 1<<8, // double aka float64
 
-	// Left side: address taken, read, write.
+	// Left side (Prog.from): address taken, read, write.
 	LeftAddr = 1<<9,
 	LeftRead = 1<<10,
 	LeftWrite = 1<<11,
 	
-	// Right side: address taken, read, write.
+	// Right side (Prog.to): address taken, read, write.
 	RightAddr = 1<<12,
 	RightRead = 1<<13,
 	RightWrite = 1<<14,
diff --git a/src/cmd/8g/opt.h b/src/cmd/8g/opt.h
index 0e2d165b1..11ee66e08 100644
--- a/src/cmd/8g/opt.h
+++ b/src/cmd/8g/opt.h
@@ -75,12 +75,18 @@ struct	Reg
 {
 	Flow	f;
 
-	Bits	set;  		// variables written by this instruction.
-	Bits	use1; 		// variables read by prog->from.
-	Bits	use2; 		// variables read by prog->to.
+	Bits	set;  		// regopt variables written by this instruction.
+	Bits	use1; 		// regopt variables read by prog->from.
+	Bits	use2; 		// regopt variables read by prog->to.
 
+	// refahead/refbehind are the regopt variables whose current
+	// value may be used in the following/preceding instructions
+	// up to a CALL (or the value is clobbered).
 	Bits	refbehind;
 	Bits	refahead;
+	// calahead/calbehind are similar, but for variables in
+	// instructions that are reachable after hitting at least one
+	// CALL.
 	Bits	calbehind;
 	Bits	calahead;
 	Bits	regdiff;
@@ -106,6 +112,16 @@ struct	Reg
 
 #define	NRGN	600
 /*c2go enum { NRGN = 600 }; */
+
+// A Rgn represents a single regopt variable over a region of code
+// where a register could potentially be dedicated to that variable.
+// The code encompassed by a Rgn is defined by the flow graph,
+// starting at enter, flood-filling forward while varno is refahead
+// and backward while varno is refbehind, and following branches.  A
+// single variable may be represented by multiple disjoint Rgns and
+// each Rgn may choose a different register for that variable.
+// Registers are allocated to regions greedily in order of descending
+// cost.
 struct	Rgn
 {
 	Reg*	enter;
@@ -183,8 +199,8 @@ typedef struct ProgInfo ProgInfo;
 struct ProgInfo
 {
 	uint32 flags; // the bits below
-	uint32 reguse; // required registers used by this instruction
-	uint32 regset; // required registers set by this instruction
+	uint32 reguse; // registers implicitly used by this instruction
+	uint32 regset; // registers implicitly set by this instruction
 	uint32 regindex; // registers used by addressing mode
 };
 
@@ -205,12 +221,12 @@ enum
 	SizeF = 1<<7, // float aka float32
 	SizeD = 1<<8, // double aka float64
 
-	// Left side: address taken, read, write.
+	// Left side (Prog.from): address taken, read, write.
 	LeftAddr = 1<<9,
 	LeftRead = 1<<10,
 	LeftWrite = 1<<11,
 	
-	// Right side: address taken, read, write.
+	// Right side (Prog.to): address taken, read, write.
 	RightAddr = 1<<12,
 	RightRead = 1<<13,
 	RightWrite = 1<<14,