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

[Jessica Clarke]

On 10 Aug 2023, at 17:33, Jisheng Zhang <jszhang at kernel.org> wrote:
> 
> On Tue, Aug 08, 2023 at 09:29:58AM -0400, guoren at kernel.org wrote:
>> 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:
> 
> +DT maintainers and DT list.
> 
> I can submit a dt-binding for this if DT maintainers agree with below
> properties. Could you please help review?

I thought this was already discussed on the OpenSBI list 2 months ago,
and received pretty negative feedback.

Jess

>> +
>> + - 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