Documentation/devicetree/bindings/perf/riscv,pmu.yaml

   1 # SPDX-License-Identifier: BSD-2-Clause
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/perf/riscv,pmu.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: RISC-V SBI PMU events
   8
   9 maintainers:
  10   - Atish Patra <atishp@rivosinc.com>
  11
  12 description: |
  13   The SBI PMU extension allows supervisor software to configure, start and
  14   stop any performance counter at anytime. Thus, a user can leverage all
  15   capabilities of performance analysis tools, such as perf, if the SBI PMU
  16   extension is enabled. The following constraints apply:
  17
  18     The platform must provide information about PMU event to counter mappings
  19     either via device tree or another way, specific to the platform.
  20     Without the event to counter mappings, the SBI PMU extension cannot be used.
  21
  22     Platforms should provide information about the PMU event selector values
  23     that should be encoded in the expected value of MHPMEVENTx while configuring
  24     MHPMCOUNTERx for that specific event. The can either be done via device tree
  25     or another way, specific to the platform.
  26     The exact value to be written to MHPMEVENTx is completely dependent on the
  27     platform.
  28
  29     For information on the SBI specification see the section "Performance
  30     Monitoring Unit Extension" of:
  31       https://github.com/riscv-non-isa/riscv-sbi-doc/blob/master/riscv-sbi.adoc
  32
  33 properties:
  34   compatible:
  35     const: riscv,pmu
  36
  37   riscv,event-to-mhpmevent:
  38     $ref: /schemas/types.yaml#/definitions/uint32-matrix
  39     description:
  40       Represents an ONE-to-ONE mapping between a PMU event and the event
  41       selector value that the platform expects to be written to the MHPMEVENTx
  42       CSR for that event.
  43       The mapping is encoded in an matrix format where each element represents
  44       an event.
  45       This property shouldn't encode any raw hardware event.
  46     items:
  47       items:
  48         - description: event_idx, a 20-bit wide encoding of the event type and
  49             code. Refer to the SBI specification for a complete description of
  50             the event types and codes.
  51         - description: upper 32 bits of the event selector value for MHPMEVENTx
  52         - description: lower 32 bits of the event selector value for MHPMEVENTx
  53
  54   riscv,event-to-mhpmcounters:
  55     $ref: /schemas/types.yaml#/definitions/uint32-matrix
  56     description:
  57       Represents a MANY-to-MANY mapping between a range of events and all the
  58       MHPMCOUNTERx in a bitmap format that can be used to monitor these range
  59       of events. The information is encoded in an matrix format where each
  60       element represents a certain range of events and corresponding counters.
  61       This property shouldn't encode any raw event.
  62     items:
  63       items:
  64         - description: first event_idx of the range of events
  65         - description: last event_idx of the range of events
  66         - description: bitmap of MHPMCOUNTERx for this event
  67
  68   riscv,raw-event-to-mhpmcounters:
  69     $ref: /schemas/types.yaml#/definitions/uint32-matrix
  70     description:
  71       Represents an ONE-to-MANY or MANY-to-MANY mapping between the rawevent(s)
  72       and all the MHPMCOUNTERx in a bitmap format that can be used to monitor
  73       that raw event.
  74       The encoding of the raw events are platform specific. The information is
  75       encoded in a matrix format where each element represents the specific raw
  76       event(s).
  77       If a platform directly encodes each raw PMU event as a unique ID, the
  78       value of variant must be 0xffffffff_ffffffff.
  79     items:
  80       items:
  81         - description:
  82             upper 32 invariant bits for the range of events
  83         - description:
  84             lower 32 invariant bits for the range of events
  85         - description:
  86             upper 32 bits of the variant bit mask for the range of events
  87         - description:
  88             lower 32 bits of the variant bit mask for the range of events
  89         - description:
  90             bitmap of all MHPMCOUNTERx that can monitor the range of events
  91
  92 dependencies:
  93   "riscv,event-to-mhpmevent": [ "riscv,event-to-mhpmcounters" ]
  94
  95 required:
  96   - compatible
  97
  98 additionalProperties: false
  99
 100 examples:
 101   - |
 102     pmu {
 103         compatible = "riscv,pmu";
 104         riscv,event-to-mhpmevent = <0x0000B 0x0000 0x0001>;
 105         riscv,event-to-mhpmcounters = <0x00001 0x00001 0x00000001>,
 106                                       <0x00002 0x00002 0x00000004>,
 107                                       <0x00003 0x0000A 0x00000ff8>,
 108                                       <0x10000 0x10033 0x000ff000>;
 109         riscv,raw-event-to-mhpmcounters =
 110             /* For event ID 0x0002 */
 111             <0x0000 0x0002 0xffffffff 0xffffffff 0x00000f8>,
 112             /* For event ID 0-4 */
 113             <0x0 0x0 0xffffffff 0xfffffff0 0x00000ff0>,
 114             /* For event ID 0xffffffff0000000f - 0xffffffff000000ff */
 115             <0xffffffff 0x0 0xffffffff 0xffffff0f 0x00000ff0>;
 116     };
 117
 118   - |
 119     /*
 120      * For HiFive Unmatched board the encodings can be found here
 121      * https://sifive.cdn.prismic.io/sifive/1a82e600-1f93-4f41-b2d8-86ed8b16acba_fu740-c000-manual-v1p6.pdf
 122      *
 123      * This example also binds standard SBI PMU hardware IDs to U74 PMU event
 124      * codes, U74 uses a bitfield for events encoding, so several U74 events
 125      * can be bound to a single perf ID.
 126      * See SBI PMU hardware IDs in arch/riscv/include/asm/sbi.h
 127      */
 128     pmu {
 129           compatible = "riscv,pmu";
 130           riscv,event-to-mhpmevent =
 131               /* SBI_PMU_HW_CACHE_REFERENCES -> Instruction or Data cache/ITIM busy */
 132               <0x00003 0x00000000 0x1801>,
 133               /* SBI_PMU_HW_CACHE_MISSES -> Instruction or Data cache miss or MMIO access */
 134               <0x00004 0x00000000 0x0302>,
 135               /* SBI_PMU_HW_BRANCH_INSTRUCTIONS -> Conditional branch retired */
 136               <0x00005 0x00000000 0x4000>,
 137               /* SBI_PMU_HW_BRANCH_MISSES -> Branch or jump misprediction */
 138               <0x00006 0x00000000 0x6001>,
 139               /* L1D_READ_MISS -> Data cache miss or MMIO access */
 140               <0x10001 0x00000000 0x0202>,
 141               /* L1D_WRITE_ACCESS -> Data cache write-back */
 142               <0x10002 0x00000000 0x0402>,
 143               /* L1I_READ_ACCESS -> Instruction cache miss */
 144               <0x10009 0x00000000 0x0102>,
 145               /* LL_READ_MISS -> UTLB miss */
 146               <0x10011 0x00000000 0x2002>,
 147               /* DTLB_READ_MISS -> Data TLB miss */
 148               <0x10019 0x00000000 0x1002>,
 149               /* ITLB_READ_MISS-> Instruction TLB miss */
 150               <0x10021 0x00000000 0x0802>;
 151           riscv,event-to-mhpmcounters = <0x00003 0x00006 0x18>,
 152                                         <0x10001 0x10002 0x18>,
 153                                         <0x10009 0x10009 0x18>,
 154                                         <0x10011 0x10011 0x18>,
 155                                         <0x10019 0x10019 0x18>,
 156                                         <0x10021 0x10021 0x18>;
 157           riscv,raw-event-to-mhpmcounters = <0x0 0x0 0xffffffff 0xfc0000ff 0x18>,
 158                                             <0x0 0x1 0xffffffff 0xfff800ff 0x18>,
 159                                             <0x0 0x2 0xffffffff 0xffffe0ff 0x18>;
 160     };