[PATCH] docs/platform: thead-c9xx: Improve the documentation

[guoren at kernel.org]

From: Guo Ren <guoren at linux.alibaba.com>

Add detailed information about thead,reset-sample driver, and improve
usage documentation.

Signed-off-by: Guo Ren <guoren at linux.alibaba.com>
Signed-off-by: Guo Ren <guoren at kernel.org>
---
 docs/platform/thead-c9xx.md | 87 ++++++++++++++++++++++++++++---------
 1 file changed, 67 insertions(+), 20 deletions(-)

diff --git a/docs/platform/thead-c9xx.md b/docs/platform/thead-c9xx.md
index 8bb9e91f1a9b..fe05fc5bb85a 100644
--- a/docs/platform/thead-c9xx.md
+++ b/docs/platform/thead-c9xx.md
@@ -1,8 +1,8 @@
-T-HEAD C9xx Series Processors
-=============================
+T-HEAD Processors
+=================
 
-The **C9xx** series processors are high-performance RISC-V architecture
-multi-core processors with AI vector acceleration engine.
+T-HEAD provides high-performance RISC-V architecture multi-core
+processors with AI vector acceleration engine.
 
 For more details, refer [T-HEAD.CN](https://www.t-head.cn/)
 
@@ -12,15 +12,75 @@ To build the platform-specific library and firmware images, provide the
 Platform Options
 ----------------
 
-The *T-HEAD C9xx* does not have any platform-specific compile options
+The *T-HEAD CPU* does not have any platform-specific compile options
 because it uses generic platform.
 
 ```
 CROSS_COMPILE=riscv64-linux-gnu- PLATFORM=generic /usr/bin/make
 ```
 
-The *T-HEAD C9xx* DTB provided to OpenSBI generic firmwares will usually have
-"riscv,clint0", "riscv,plic0", "thead,reset-sample" compatible strings.
+The *T-HEAD CPU* DTB provided to OpenSBI generic firmwares will usually have
+"thead,reset-sample" compatible strings. The "thead,reset-sample" is a T-HEAD
+custom driver for the SMP system bootup; the single-core system doesn't need
+it.
+
+T-HEAD Fdt Reset Driver Introduction
+------------------------------------
+
+Every T-HEAD CPU provides a reset control signal and reset address signals.
+ - Reset address signal determines CPU where to start up.
+ - Reset control signal releases CPU from reset state and begins to execute
+   at reset address.
+
+Many vendors would gather these signals into SoC control registers. These
+register designs are similar but with different base addresses and bits
+definitions. We only provide standard opensbi, Linux binaries, and jtag gdbinit
+script to simplify Linux booting at the FPGA stage. The fdt reset driver helps
+users bring up their SMP system quickly with the below settings:
+
+ - entry-reg:
+	The base address to store reset address value
+
+ - entry-cnt:
+	The numbers of entry-reg, all of them set the same reset address
+
+ - control-reg:
+	The base address to reset the controller
+
+ - control-val:
+	Write which bits of control-reg for booting
+
+ - csr-copy:
+	This array determines which csrs to copy from primary hart to the
+	secondary harts, which are set in sequence from left to right. The
+	secondary harts should keep the same setting as the primary hart.
+	These settings are also the first part of the bootup instructions
+	for secondary harts.
+
+ - using-csr-reset:
+	A legacy reset controller for the SMP system, but abandoned in the
+	latest T-HEAD processors.
+
+Here is the dts example:
+```
+	reset: reset-sample {
+		compatible = "thead,reset-sample";
+		entry-reg = <0xff 0xff019050>;
+		entry-cnt = <4>;
+		control-reg = <0xff 0xff015004>;
+		control-val = <0x1c>;
+		csr-copy = <0x7f3 0x7c0 0x7c1 0x7c2 0x7c3 0x7c5 0x7cc>;
+	};
+```
+
+Legacy dts example (Abandoned):
+```
+	reset: reset-sample {
+		compatible = "thead,reset-sample";
+		using-csr-reset;
+		csr-copy = <0x7f3 0x7c0 0x7c1 0x7c2 0x7c3 0x7c5 0x7cc>;
+	};
+```
 
 DTS Example1: (Single core, eg: Allwinner D1 - c906)
 ----------------------------------------------------
@@ -181,16 +241,3 @@ DTS Example2: (Multi cores with soc reset-regs)
 		};
 	}
 ```
-
-DTS Example2: (Multi cores with old reset csrs)
------------------------------------------------
-```
-	reset: reset-sample {
-		compatible = "thead,reset-sample";
-		using-csr-reset;
-		csr-copy = <0x7c0 0x7c1 0x7c2 0x7c3 0x7c5 0x7cc
-			    0x3b0 0x3b1 0x3b2 0x3b3
-			    0x3b4 0x3b5 0x3b6 0x3b7
-			    0x3a0>;
-	};
-```
-- 
2.36.1