1===================
2RISC-V CPU Bindings
3===================
4
5The device tree allows to describe the layout of CPUs in a system through
6the "cpus" node, which in turn contains a number of subnodes (ie "cpu")
7defining properties for every cpu.
8
9Bindings for CPU nodes follow the Devicetree Specification, available from:
10
11https://www.devicetree.org/specifications/
12
13with updates for 32-bit and 64-bit RISC-V systems provided in this document.
14
15===========
16Terminology
17===========
18
19This document uses some terminology common to the RISC-V community that is not
20widely used, the definitions of which are listed here:
21
22* hart: A hardware execution context, which contains all the state mandated by
23  the RISC-V ISA: a PC and some registers.  This terminology is designed to
24  disambiguate software's view of execution contexts from any particular
25  microarchitectural implementation strategy.  For example, my Intel laptop is
26  described as having one socket with two cores, each of which has two hyper
27  threads.  Therefore this system has four harts.
28
29=====================================
30cpus and cpu node bindings definition
31=====================================
32
33The RISC-V architecture, in accordance with the Devicetree Specification,
34requires the cpus and cpu nodes to be present and contain the properties
35described below.
36
37- cpus node
38
39        Description: Container of cpu nodes
40
41        The node name must be "cpus".
42
43        A cpus node must define the following properties:
44
45        - #address-cells
46                Usage: required
47                Value type: <u32>
48                Definition: must be set to 1
49        - #size-cells
50                Usage: required
51                Value type: <u32>
52                Definition: must be set to 0
53
54- cpu node
55
56        Description: Describes a hart context
57
58        PROPERTIES
59
60        - device_type
61                Usage: required
62                Value type: <string>
63                Definition: must be "cpu"
64        - reg
65                Usage: required
66                Value type: <u32>
67                Definition: The hart ID of this CPU node
68        - compatible:
69                Usage: required
70                Value type: <stringlist>
71                Definition: must contain "riscv", may contain one of
72                            "sifive,rocket0"
73        - mmu-type:
74                Usage: optional
75                Value type: <string>
76                Definition: Specifies the CPU's MMU type.  Possible values are
77                            "riscv,sv32"
78                            "riscv,sv39"
79                            "riscv,sv48"
80        - riscv,isa:
81                Usage: required
82                Value type: <string>
83                Definition: Contains the RISC-V ISA string of this hart.  These
84                            ISA strings are defined by the RISC-V ISA manual.
85
86Example: SiFive Freedom U540G Development Kit
87---------------------------------------------
88
89This system contains two harts: a hart marked as disabled that's used for
90low-level system tasks and should be ignored by Linux, and a second hart that
91Linux is allowed to run on.
92
93        cpus {
94                #address-cells = <1>;
95                #size-cells = <0>;
96                timebase-frequency = <1000000>;
97                cpu@0 {
98                        clock-frequency = <1600000000>;
99                        compatible = "sifive,rocket0", "riscv";
100                        device_type = "cpu";
101                        i-cache-block-size = <64>;
102                        i-cache-sets = <128>;
103                        i-cache-size = <16384>;
104                        next-level-cache = <&L15 &L0>;
105                        reg = <0>;
106                        riscv,isa = "rv64imac";
107                        status = "disabled";
108                        L10: interrupt-controller {
109                                #interrupt-cells = <1>;
110                                compatible = "riscv,cpu-intc";
111                                interrupt-controller;
112                        };
113                };
114                cpu@1 {
115                        clock-frequency = <1600000000>;
116                        compatible = "sifive,rocket0", "riscv";
117                        d-cache-block-size = <64>;
118                        d-cache-sets = <64>;
119                        d-cache-size = <32768>;
120                        d-tlb-sets = <1>;
121                        d-tlb-size = <32>;
122                        device_type = "cpu";
123                        i-cache-block-size = <64>;
124                        i-cache-sets = <64>;
125                        i-cache-size = <32768>;
126                        i-tlb-sets = <1>;
127                        i-tlb-size = <32>;
128                        mmu-type = "riscv,sv39";
129                        next-level-cache = <&L15 &L0>;
130                        reg = <1>;
131                        riscv,isa = "rv64imafdc";
132                        status = "okay";
133                        tlb-split;
134                        L13: interrupt-controller {
135                                #interrupt-cells = <1>;
136                                compatible = "riscv,cpu-intc";
137                                interrupt-controller;
138                        };
139                };
140        };
141
142Example: Spike ISA Simulator with 1 Hart
143----------------------------------------
144
145This device tree matches the Spike ISA golden model as run with `spike -p1`.
146
147        cpus {
148                cpu@0 {
149                        device_type = "cpu";
150                        reg = <0x00000000>;
151                        status = "okay";
152                        compatible = "riscv";
153                        riscv,isa = "rv64imafdc";
154                        mmu-type = "riscv,sv48";
155                        clock-frequency = <0x3b9aca00>;
156                        interrupt-controller {
157                                #interrupt-cells = <0x00000001>;
158                                interrupt-controller;
159                                compatible = "riscv,cpu-intc";
160                        }
161                }
162        }
163