cmd/link: give RelocVariant a type, document Reloc

Change-Id: Ib20263405a08674b5e160295fc965da4c8b54b34
Reviewed-on: https://go-review.googlesource.com/29248
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/cmd/link/internal/ld/link.go b/src/cmd/link/internal/ld/link.go
index 7fd436fd9772238ba2276535e92e59786a8a2864..77d3b38a677510b8856ecef6c8e742eb5c12eeda 100644 (file)
--- a/src/cmd/link/internal/ld/link.go
+++ b/src/cmd/link/internal/ld/link.go
@@ -132,16 +132,27 @@ func (a *Attribute) Set(flag Attribute, value bool) {
        }
 }
 
+// Reloc is a relocation.
+//
+// The typical Reloc rewrites part of a symbol at offset Off to address Sym.
+// A Reloc is stored in a slice on the Symbol it rewrites.
+//
+// Relocations are generated by the compiler as the type
+// cmd/internal/obj.Reloc, which is encoded into the object file wire
+// format and decoded by the linker into this type. A separate type is
+// used to hold linker-specific state about the relocation.
+//
+// Some relocations are created by cmd/link.
 type Reloc struct {
-       Off     int32
-       Siz     uint8
-       Done    uint8
-       Type    obj.RelocType
-       Variant int32
-       Add     int64
-       Xadd    int64
-       Sym     *Symbol
-       Xsym    *Symbol
+       Off     int32         // offset to rewrite
+       Siz     uint8         // number of bytes to rewrite, 1, 2, or 4
+       Done    uint8         // set to 1 when relocation is complete
+       Variant RelocVariant  // variation on Type
+       Type    obj.RelocType // the relocation type
+       Add     int64         // addend
+       Xadd    int64         // addend passed to external linker
+       Sym     *Symbol       // symbol the relocation addresses
+       Xsym    *Symbol       // symbol passed to external linker
 }
 
 type Auto struct {
@@ -251,9 +262,11 @@ type Pciter struct {
        done    int
 }
 
-// Reloc.variant
+// RelocVariant is a linker-internal variation on a relocation.
+type RelocVariant uint8
+
 const (
-       RV_NONE = iota
+       RV_NONE RelocVariant = iota
        RV_POWER_LO
        RV_POWER_HI
        RV_POWER_HA
@@ -264,6 +277,6 @@ const (
        // divided by 2.
        RV_390_DBL
 
-       RV_CHECK_OVERFLOW = 1 << 8
-       RV_TYPE_MASK      = RV_CHECK_OVERFLOW - 1
+       RV_CHECK_OVERFLOW RelocVariant = 1 << 7
+       RV_TYPE_MASK      RelocVariant = RV_CHECK_OVERFLOW - 1
 )