_content/doc: update huge page details with max_ptes_none workarounds

Go 1.21.1 and Go 1.22 have ceased working around an issue with Linux
kernel defaults for transparent huge pages that can result in excessive
memory overheads. (https://bugzilla.kernel.org/show_bug.cgi?id=93111)

Many Linux distributions disable huge pages altogether these days, so
this problem isn't quite as far-reaching as it used to be. Also, the
problem only affects Go programs with very particular memory usage
patterns.

That being said, because the runtime used to actively deal with this
problem (but with some unpredictable behavior), it's preventing users
that don't have a lot of control over their execution environment from
upgrading to Go beyond Go 1.20.

This adds documentation about this change in behavior in both the GC
guide and the Go 1.21 release notes.

For golang/go#64332.

Change-Id: I29baaffcc678d08255364a3cd6f11211ce4164ba
Reviewed-on: https://go-review.googlesource.com/c/website/+/547675
Auto-Submit: Michael Knyszek <[email protected]>
Reviewed-by: Mauri de Souza Meneguzzo <[email protected]>
Reviewed-by: Michael Pratt <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: mknyszek

_content/doc/gc-guide.html

@@ -1539,7 +1539,7 @@ <h3 id="Linux_transparent_huge_pages">Linux transparent huge pages (THP)</h3>
 		</p>
 	</li>
 	<li>
-		<p>
+		<p id="Linux_THP_max_ptes_none_workaround">
 		Set <code>/sys/kernel/mm/transparent_hugepage/khugepaged/max_ptes_none</code>
 		to <code>0</code>.
 		<br />
@@ -1551,8 +1551,18 @@ <h3 id="Linux_transparent_huge_pages">Linux transparent huge pages (THP)</h3>
 		runtime does to return memory to the OS</a>.
 		Before Go 1.21, the Go runtime tried to mitigate the negative effects of the
 		default setting, but it came with a CPU cost.
-		With Go 1.21+ and Linux 6.2+, the Go runtime will coalesce regular pages
-		into huge pages itself with its own more accurate heuristics.
+		With Go 1.21+ and Linux 6.2+, the Go runtime no longer mutates huge page
+		state.
+		<br />
+		<br />
+		If you experience an increase in memory usage when upgrading to Go 1.21.1 or
+		later, try applying this setting; it will likely resolve your issue.
+		As an additional workaround, you can call
+		<a href="/pkg/golang.org/x/sys/unix#Prctl">the <code>Prctl</code>
+		function</a> with <code>PR_SET_THP_DISABLE</code> to disable huge pages at
+		the process level, or you can set <code>GODEBUG=disablethp=1</code> (to be
+		added in Go 1.21.6 and Go 1.22) to disable huge pages for heap memory.
+		Note that the <code>GODEBUG</code> setting may be removed in a future release.
 		</p>
 	</li>
 </ul>

_content/doc/go1.21.md

@@ -231,7 +231,13 @@ now manages which parts of the heap may be backed by huge pages more
 explicitly. This leads to better utilization of memory: small heaps
 should see less memory used (up to 50% in pathological cases) while
 large heaps should see fewer broken huge pages for dense parts of the
-heap, improving CPU usage and latency by up to 1%.
+heap, improving CPU usage and latency by up to 1%. A consequence of this
+change is that the runtime no longer tries to work around a particular
+problematic Linux configuration setting, which may result in higher
+memory overheads. The recommended fix is to adjust the OS's huge page
+settings according to the [GC guide](/doc/gc-guide#Linux_transparent_huge_pages).
+However, other workarounds are available as well. See the [section on
+`max_ptes_none`](/doc/gc-guide#Linux_THP_max_ptes_none_workaround).
 
 <!-- https://go.dev/issue/57069, https://go.dev/issue/56966 -->
 As a result of runtime-internal garbage collection tuning,