Documentation/devicetree/bindings/riscv/cpus.txt

   1 ===================
   2 RISC-V CPU Bindings
   3 ===================
   4
   5 The device tree allows to describe the layout of CPUs in a system through
   6 the "cpus" node, which in turn contains a number of subnodes (ie "cpu")
   7 defining properties for every cpu.
   8
   9 Bindings for CPU nodes follow the Devicetree Specification, available from:
  10
  11 https://www.devicetree.org/specifications/
  12
  13 with updates for 32-bit and 64-bit RISC-V systems provided in this document.
  14
  15 ===========
  16 Terminology
  17 ===========
  18
  19 This document uses some terminology common to the RISC-V community that is not
  20 widely 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 =====================================
  30 cpus and cpu node bindings definition
  31 =====================================
  32
  33 The RISC-V architecture, in accordance with the Devicetree Specification,
  34 requires the cpus and cpu nodes to be present and contain the properties
  35 described 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
  86 Example: SiFive Freedom U540G Development Kit
  87 ---------------------------------------------
  88
  89 This system contains two harts: a hart marked as disabled that's used for
  90 low-level system tasks and should be ignored by Linux, and a second hart that
  91 Linux 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
 142 Example: Spike ISA Simulator with 1 Hart
 143 ----------------------------------------
 144
 145 This 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         }