From 2754118731b81baf0c812116a9b72b6153abf79d Mon Sep 17 00:00:00 2001
From: Pure White <wu.purewhite@gmail.com>
Date: Sun, 11 Aug 2019 05:37:29 +0000
Subject: [PATCH] doc/asm: document go_asm.h only works in the runtime package

Fixes #33054

Change-Id: I687d45e092d721a6c22888cc7ddbe420c16a5af9
GitHub-Last-Rev: a7208c89a0d613a53ab057e0b4418ae4719cfcbd
GitHub-Pull-Request: golang/go#33069
Reviewed-on: https://go-review.googlesource.com/c/go/+/185917
Reviewed-by: Rob Pike <r@golang.org>
---
 doc/asm.html | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/doc/asm.html b/doc/asm.html
index 77defdbd28f..11033fe3c5f 100644
--- a/doc/asm.html
+++ b/doc/asm.html
@@ -590,27 +590,37 @@ Here follow some descriptions of key Go-specific details for the supported archi
 <p>
 The runtime pointer to the <code>g</code> structure is maintained
 through the value of an otherwise unused (as far as Go is concerned) register in the MMU.
-A OS-dependent macro <code>get_tls</code> is defined for the assembler if the source includes
-a special header, <code>go_asm.h</code>:
+An OS-dependent macro <code>get_tls</code> is defined for the assembler if the source is
+in the <code>runtime</code> package and includes a special header, <code>go_tls.h</code>:
 </p>
 
 <pre>
-#include "go_asm.h"
+#include "go_tls.h"
 </pre>
 
 <p>
 Within the runtime, the <code>get_tls</code> macro loads its argument register
 with a pointer to the <code>g</code> pointer, and the <code>g</code> struct
 contains the <code>m</code> pointer.
+There's another special header containing the offsets for each
+element of <code>g</code>, called <code>go_asm.h</code>.
 The sequence to load <code>g</code> and <code>m</code> using <code>CX</code> looks like this:
 </p>
 
 <pre>
+#include "go_tls.h"
+#include "go_asm.h"
+...
 get_tls(CX)
 MOVL	g(CX), AX     // Move g into AX.
 MOVL	g_m(AX), BX   // Move g.m into BX.
 </pre>
 
+<p>
+Note: The code above works only in the <code>runtime</code> package, while <code>go_tls.h</code> also
+applies to <a href="#arm">arm</a>, <a href="#amd64">amd64</a> and amd64p32, and <code>go_asm.h</code> applies to all architectures.
+</p>
+
 <p>
 Addressing modes:
 </p>