runtime: document pointer write atomicity for memclrNoHeapPointers

memclrNoHeapPointers is the underlying implementation of
typedmemclr and memclrHasPointers, so it still needs to write
pointer-aligned words atomically. Document this requirement.

Updates #41428.

Change-Id: Ice00dee5de7a96a50e51ff019fcef069e8a8406a
Reviewed-on: https://go-review.googlesource.com/c/go/+/287692
Trust: Cherry Zhang <cherryyz@google.com>
Reviewed-by: Keith Randall <khr@golang.org>

diff --git a/src/runtime/memclr_386.s b/src/runtime/memclr_386.s
index 65f7196312cec0fa6d3aa758f2b61b573013b2a0..5e090ef09ebf2b8f6a6fba8efe1045943e96bb49 100644 (file)
--- a/src/runtime/memclr_386.s
+++ b/src/runtime/memclr_386.s
@@ -9,6 +9,8 @@
 
 // NOTE: Windows externalthreadhandler expects memclr to preserve DX.
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB), NOSPLIT, $0-8
        MOVL    ptr+0(FP), DI

diff --git a/src/runtime/memclr_amd64.s b/src/runtime/memclr_amd64.s
index d79078fd00bf5f389837603ad1c40fda72b20c18..37fe9745b1be082d4c0380899ed2bc1cc0009cb9 100644 (file)
--- a/src/runtime/memclr_amd64.s
+++ b/src/runtime/memclr_amd64.s
@@ -9,6 +9,8 @@
 
 // NOTE: Windows externalthreadhandler expects memclr to preserve DX.
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB), NOSPLIT, $0-16
        MOVQ    ptr+0(FP), DI

diff --git a/src/runtime/memclr_arm.s b/src/runtime/memclr_arm.s
index 7326b8be34066ad7bce04d8973e724c366b909a0..f113a1aa2dd9ffd559dcfde1185e6e645e8e13e7 100644 (file)
--- a/src/runtime/memclr_arm.s
+++ b/src/runtime/memclr_arm.s
@@ -30,6 +30,8 @@
 #define N      R12
 #define TMP    R12                             /* N and TMP don't overlap */
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB),NOSPLIT,$0-8
        MOVW    ptr+0(FP), TO

diff --git a/src/runtime/memclr_arm64.s b/src/runtime/memclr_arm64.s
index a56a6dfb85df8099e3c80bbb457cfce239f330a6..bef77651e48c445b4d88ab7eb31c330b872e54fd 100644 (file)
--- a/src/runtime/memclr_arm64.s
+++ b/src/runtime/memclr_arm64.s
@@ -4,6 +4,8 @@
 
 #include "textflag.h"
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB),NOSPLIT,$0-16
        MOVD    ptr+0(FP), R0

diff --git a/src/runtime/memclr_mips64x.s b/src/runtime/memclr_mips64x.s
index 4c2292eae8520e4ae782121a586f488f1e92b93d..d7a3251e2046abf15ac9e487dfa6884ef4e714ac 100644 (file)
--- a/src/runtime/memclr_mips64x.s
+++ b/src/runtime/memclr_mips64x.s
@@ -7,6 +7,8 @@
 #include "go_asm.h"
 #include "textflag.h"
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB),NOSPLIT,$0-16
        MOVV    ptr+0(FP), R1

diff --git a/src/runtime/memclr_mipsx.s b/src/runtime/memclr_mipsx.s
index 1561a23dbe297171a8c4aded6eceb71e4e5636e9..eb2a8a7219c6bbf0bc39064e5beef20cc0306573 100644 (file)
--- a/src/runtime/memclr_mipsx.s
+++ b/src/runtime/memclr_mipsx.s
@@ -14,6 +14,8 @@
 #define MOVWLO  MOVWL
 #endif
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB),NOSPLIT,$0-8
        MOVW    n+4(FP), R2

diff --git a/src/runtime/memclr_plan9_386.s b/src/runtime/memclr_plan9_386.s
index 5b880ae86f81b43206c55c51ed06a7399be316ae..54701a94536e5493cb9005dcfb82a2823a627b95 100644 (file)
--- a/src/runtime/memclr_plan9_386.s
+++ b/src/runtime/memclr_plan9_386.s
@@ -4,6 +4,8 @@
 
 #include "textflag.h"
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB), NOSPLIT, $0-8
        MOVL    ptr+0(FP), DI

diff --git a/src/runtime/memclr_plan9_amd64.s b/src/runtime/memclr_plan9_amd64.s
index ad383cd6b3d69c230362b9881eaf4d1cfacbf9de..8c6a1cc7809ac6a94a81c753009382e53d8842e6 100644 (file)
--- a/src/runtime/memclr_plan9_amd64.s
+++ b/src/runtime/memclr_plan9_amd64.s
@@ -4,6 +4,8 @@
 
 #include "textflag.h"
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB),NOSPLIT,$0-16
        MOVQ    ptr+0(FP), DI

diff --git a/src/runtime/memclr_ppc64x.s b/src/runtime/memclr_ppc64x.s
index 072963f75687dcdae62c7dd88ec8c24a966d0094..751262089425430eeec3a7208972d4c01507236f 100644 (file)
--- a/src/runtime/memclr_ppc64x.s
+++ b/src/runtime/memclr_ppc64x.s
@@ -6,6 +6,8 @@
 
 #include "textflag.h"
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB), NOSPLIT|NOFRAME, $0-16
        MOVD ptr+0(FP), R3

diff --git a/src/runtime/memclr_riscv64.s b/src/runtime/memclr_riscv64.s
index ba7704e805d2b536823f9a03b7c6018a6b0136a3..54ddaa4560c77635e357b9b0a14b8f7da5c211dd 100644 (file)
--- a/src/runtime/memclr_riscv64.s
+++ b/src/runtime/memclr_riscv64.s
@@ -4,6 +4,8 @@
 
 #include "textflag.h"
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // void runtime·memclrNoHeapPointers(void*, uintptr)
 TEXT runtime·memclrNoHeapPointers(SB),NOSPLIT,$0-16
        MOV     ptr+0(FP), T1

diff --git a/src/runtime/memclr_s390x.s b/src/runtime/memclr_s390x.s
index dd14a441cc2bb77bba15bb4227d7b431ecc7ee99..fa657ef66e6b9545417223164a4d163329fc6e1a 100644 (file)
--- a/src/runtime/memclr_s390x.s
+++ b/src/runtime/memclr_s390x.s
@@ -4,6 +4,8 @@
 
 #include "textflag.h"
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB),NOSPLIT|NOFRAME,$0-16
        MOVD    ptr+0(FP), R4

diff --git a/src/runtime/memclr_wasm.s b/src/runtime/memclr_wasm.s
index 68ffe2f67b513079ad66c6ecf21dc70fd058e224..5a053049f8154eaabe70d92280e7ec6c1edf48d1 100644 (file)
--- a/src/runtime/memclr_wasm.s
+++ b/src/runtime/memclr_wasm.s
@@ -4,6 +4,8 @@
 
 #include "textflag.h"
 
+// See memclrNoHeapPointers Go doc for important implementation constraints.
+
 // func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 TEXT runtime·memclrNoHeapPointers(SB), NOSPLIT, $0-16
        MOVD ptr+0(FP), R0

diff --git a/src/runtime/stubs.go b/src/runtime/stubs.go
index b55c3c0590072ed67f7ee64ce2a6af302969d5f9..2ee2c74dfe07e5f1ef4e881352f296697644aab4 100644 (file)
--- a/src/runtime/stubs.go
+++ b/src/runtime/stubs.go
@@ -73,7 +73,15 @@ func badsystemstack() {
 // *ptr is uninitialized memory (e.g., memory that's being reused
 // for a new allocation) and hence contains only "junk".
 //
+// memclrNoHeapPointers ensures that if ptr is pointer-aligned, and n
+// is a multiple of the pointer size, then any pointer-aligned,
+// pointer-sized portion is cleared atomically. Despite the function
+// name, this is necessary because this function is the underlying
+// implementation of typedmemclr and memclrHasPointers. See the doc of
+// memmove for more details.
+//
 // The (CPU-specific) implementations of this function are in memclr_*.s.
+//
 //go:noescape
 func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)