| Message ID | 20210527003044.889681-2-atish.patra@wdc.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | SBI PMU extension support | expand |
> -----Original Message----- > From: Atish Patra <atish.patra@wdc.com> > Sent: 27 May 2021 06:01 > To: opensbi@lists.infradead.org > Cc: Atish Patra <Atish.Patra@wdc.com>; Anup Patel <Anup.Patel@wdc.com> > Subject: [PATCH v2 01/15] docs: Add device tree bindings for SBI PMU > extension > > SBI PMU extension requires a firmware to be aware of the event to > counter/mhpmevent mappings supported by the hardware. One approach is > to encode that information in the device tree. > > Define a device tree binding that allows a hardware to describe all the PMU > mappings required in concise format. > > Signed-off-by: Atish Patra <atish.patra@wdc.com> Looks good to me. Reviewed-by: Anup Patel <anup.patel@wdc.com> Regards, Anup > --- > docs/pmu_support.md | 83 > +++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 83 insertions(+) > create mode 100644 docs/pmu_support.md > > diff --git a/docs/pmu_support.md b/docs/pmu_support.md new file mode > 100644 index 000000000000..8535a1dccbeb > --- /dev/null > +++ b/docs/pmu_support.md > @@ -0,0 +1,83 @@ > +OpenSBI SBI PMU extension support > +================================== > +SBI PMU extension supports allow supervisor software to > +configure/start/stop any performance counter at anytime. Thus, an user > +can leverage full capability of performance analysis tools such as perf > +if SBI PMU extension is enabled. The OpenSBI implementation makes the > +following assumptions about the hardware platform. > + > + * MCOUNTINHIBIT CSR must be implemented in the hardware. Otherwise, > +SBI PMU extension will not be enabled. > + > + * The platform must provide information about PMU event to counter > +mapping via device tree or platform specific hooks. Otherwise, SBI PMU > +extension will not be enabled. > + > + * The platforms should provide information about the PMU event > +selector values that should be encoded in the expected value of > +MHPMEVENTx while configuring MHPMCOUNTERx for that specific event. > This > +can be done via a device tree or platform specific hooks. The exact > +value to be written to he MHPMEVENTx is completely platform specific. > +Generic platform writes a default value <xyz> to the MHPMEVENTx CSR > where <xyz> is formatted as described below. > +``` > + xyz[0:19] : event_idx > + xyz[20:XLEN] : event_data[0:(XLEN-20)] > + > +``` > + > +SBI PMU Device Tree Bindings > +---------------------------- > + > +Platforms may choose to describe PMU event selector and event to > +counter mapping values via device tree. The following sections > +describes the PMU DT node bindings in details. > + > +* **compatible** (Mandatory) - The compatible string of SBI PMU device > tree node. > +This DT property must have the value **riscv,pmu**. > + > +* **opensbi,event-to-mhpmevent**(Optional) - It represents an > +ONE-to-ONE mapping between a PMU event and the event selector value > +that platform expects to be written to the MHPMEVENTx CSR for that > +event. The mapping is encoded in a table format where each row > +represents an event. The first column represent the event idx where the > +2nd & 3rd column represent the event selector value that should be > encoded in the expected value to be written in MHPMEVENTx. > +This property shouldn't encode any raw hardware event. > + > +* **opensbi,event-to-counters**(Optional) - It represents a > +MANY-to-MANY mapping between a range of events and all the > MHPMCOUNTERx > +in a bitmap format that can be used to monitor these range of events. > +The information is encoded in a table format where each row represent a > +certain range of events and corresponding counters. The first column > +represents starting of the pmu event id and 2nd column represents the > +end of the pmu event id. The third column represent a bitmap of all the > +MHPMCOUNTERx. This property is mandatory if event-to-mhpmevent is > +present. Otherwise, it can be omitted. This property shouldn't encode any > raw event. > + > +* **opensbi,raw-event-to-counters**(Optional) - It represents an > +ONE-to-MANY mapping between a raw event and all the MHPMCOUNTERx in > a > +bitmap format that can be used to monitor that raw event. The > +information is encoded in a table format where each raw represent a > +specific raw event. The first column stores the expected event selector > +value that should be encoded in the expected value to be written in > +MHPMEVENTx. The second column stores a bitmap of all the > MHPMCOUNTERx that can be used for monitoring the specified event. > + > +*Note:* A platform may choose to provide the mapping between event & > +counters via platform hooks rather than the device tree. > + > +### Example > + > +``` > +pmu { > + compatible = "riscv,pmu"; > + interrupts = <0x100>; > + interrupt-parent = <&plic> > + opensbi,event-to-mhpmevent = <0x0000B 0x0000 0x0001>, > + opensbi,event-to-counters = <0x00001 0x00001 0x00000001>, > + <0x00002 0x00002 0x00000004>, > + <0x00003 0x0000A 0x00000ff8>, > + <0x10000 0x10033 0x000ff000>, > + opensbi,raw-event-to-counters = <0x0000 0x0002 0x00000f8>, > + <0x0000 0x0003 0x00000ff0>, > +}; > + > +``` > -- > 2.25.1
diff --git a/docs/pmu_support.md b/docs/pmu_support.md new file mode 100644 index 000000000000..8535a1dccbeb --- /dev/null +++ b/docs/pmu_support.md @@ -0,0 +1,83 @@ +OpenSBI SBI PMU extension support +================================== +SBI PMU extension supports allow supervisor software to configure/start/stop +any performance counter at anytime. Thus, an user can leverage full +capability of performance analysis tools such as perf if SBI PMU extension is +enabled. The OpenSBI implementation makes the following assumptions about the +hardware platform. + + * MCOUNTINHIBIT CSR must be implemented in the hardware. Otherwise, SBI PMU +extension will not be enabled. + + * The platform must provide information about PMU event to counter mapping +via device tree or platform specific hooks. Otherwise, SBI PMU extension will +not be enabled. + + * The platforms should provide information about the PMU event selector values +that should be encoded in the expected value of MHPMEVENTx while configuring +MHPMCOUNTERx for that specific event. This can be done via a device tree or +platform specific hooks. The exact value to be written to he MHPMEVENTx is +completely platform specific. Generic platform writes a default value <xyz> to +the MHPMEVENTx CSR where <xyz> is formatted as described below. +``` + xyz[0:19] : event_idx + xyz[20:XLEN] : event_data[0:(XLEN-20)] + +``` + +SBI PMU Device Tree Bindings +---------------------------- + +Platforms may choose to describe PMU event selector and event to counter mapping +values via device tree. The following sections describes the PMU DT node +bindings in details. + +* **compatible** (Mandatory) - The compatible string of SBI PMU device tree node. +This DT property must have the value **riscv,pmu**. + +* **opensbi,event-to-mhpmevent**(Optional) - It represents an ONE-to-ONE mapping +between a PMU event and the event selector value that platform expects to be +written to the MHPMEVENTx CSR for that event. The mapping is encoded in a +table format where each row represents an event. The first column represent the +event idx where the 2nd & 3rd column represent the event selector value that +should be encoded in the expected value to be written in MHPMEVENTx. +This property shouldn't encode any raw hardware event. + +* **opensbi,event-to-counters**(Optional) - It represents a MANY-to-MANY +mapping between a range of events and all the MHPMCOUNTERx in a bitmap format +that can be used to monitor these range of events. The information is encoded in +a table format where each row represent a certain range of events and +corresponding counters. The first column represents starting of the pmu event id +and 2nd column represents the end of the pmu event id. The third column +represent a bitmap of all the MHPMCOUNTERx. This property is mandatory if +event-to-mhpmevent is present. Otherwise, it can be omitted. This property +shouldn't encode any raw event. + +* **opensbi,raw-event-to-counters**(Optional) - It represents an ONE-to-MANY +mapping between a raw event and all the MHPMCOUNTERx in a bitmap format that can +be used to monitor that raw event. The information is encoded in a table format +where each raw represent a specific raw event. The first column stores the +expected event selector value that should be encoded in the expected value to be +written in MHPMEVENTx. The second column stores a bitmap of all the MHPMCOUNTERx +that can be used for monitoring the specified event. + +*Note:* A platform may choose to provide the mapping between event & counters +via platform hooks rather than the device tree. + +### Example + +``` +pmu { + compatible = "riscv,pmu"; + interrupts = <0x100>; + interrupt-parent = <&plic> + opensbi,event-to-mhpmevent = <0x0000B 0x0000 0x0001>, + opensbi,event-to-counters = <0x00001 0x00001 0x00000001>, + <0x00002 0x00002 0x00000004>, + <0x00003 0x0000A 0x00000ff8>, + <0x10000 0x10033 0x000ff000>, + opensbi,raw-event-to-counters = <0x0000 0x0002 0x00000f8>, + <0x0000 0x0003 0x00000ff0>, +}; + +```
SBI PMU extension requires a firmware to be aware of the event to counter/mhpmevent mappings supported by the hardware. One approach is to encode that information in the device tree. Define a device tree binding that allows a hardware to describe all the PMU mappings required in concise format. Signed-off-by: Atish Patra <atish.patra@wdc.com> --- docs/pmu_support.md | 83 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/pmu_support.md