Commit bdf3a950 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

docs: riscv: convert docs to ReST and rename to *.rst 



The conversion here is trivial:
 - Adjust the document title's markup
 - Do some whitespace alignment;
 - mark literal blocks;
 - Use ReST way to markup indented lists.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 329f0041

Documentation/riscv/index.rst

0 → 100644
+17 −0
Original line number Original line Diff line number Diff line 
:orphan:



===================

RISC-V architecture

===================



.. toctree::

    :maxdepth: 1



    pmu



.. only::  subproject and html



   Indices

   =======



   * :ref:`genindex`

Documentation/riscv/pmu.txt→Documentation/riscv/pmu.rst

+13 −7
Original line number Original line Diff line number Diff line 
===================================

Supporting PMUs on RISC-V platforms

Supporting PMUs on RISC-V platforms

==========================================

===================================



Alan Kao <alankao@andestech.com>, Mar 2018

Alan Kao <alankao@andestech.com>, Mar 2018





Introduction

Introduction
@@ -77,7 +79,7 @@ Note that some features can be done in this stage as well: 
(2) privilege level setting (user space only, kernel space only, both);

(2) privilege level setting (user space only, kernel space only, both);

(3) destructor setting.  Normally it is sufficient to apply *riscv_destroy_event*;

(3) destructor setting.  Normally it is sufficient to apply *riscv_destroy_event*;

(4) tweaks for non-sampling events, which will be utilized by functions such as

(4) tweaks for non-sampling events, which will be utilized by functions such as

*perf_adjust_period*, usually something like the follows:

    *perf_adjust_period*, usually something like the follows::





      if (!is_sampling_event(event)) {

      if (!is_sampling_event(event)) {

              hwc->sample_period = x86_pmu.max_period;

              hwc->sample_period = x86_pmu.max_period;
@@ -94,7 +96,7 @@ In the case of *riscv_base_pmu*, only (3) is provided for now. 
3.1. Interrupt Initialization

3.1. Interrupt Initialization





This often occurs at the beginning of the *event_init* method. In common

This often occurs at the beginning of the *event_init* method. In common

practice, this should be a code segment like

practice, this should be a code segment like::





  int x86_reserve_hardware(void)

  int x86_reserve_hardware(void)

  {

  {
@@ -128,7 +130,7 @@ which will be introduced in the next section.) 




3.2. IRQ Structure

3.2. IRQ Structure





Basically, a IRQ runs the following pseudo code:

Basically, a IRQ runs the following pseudo code::





  for each hardware counter that triggered this overflow

  for each hardware counter that triggered this overflow
@@ -195,20 +197,23 @@ A normal flow of these state transitions are as follows: 
  At this stage, a general event is bound to a physical counter, if any.

  At this stage, a general event is bound to a physical counter, if any.

  The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now

  The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now

  stopped, and the (software) event count does not need updating.

  stopped, and the (software) event count does not need updating.

** *start* is then called, and the counter is enabled.



  - *start* is then called, and the counter is enabled.

    With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check

    With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check

    previous section for detail).

    previous section for detail).

    Nothing is written if the flag does not contain PERF_EF_RELOAD.

    Nothing is written if the flag does not contain PERF_EF_RELOAD.

    The state now is reset to none, because it is neither stopped nor updated

    The state now is reset to none, because it is neither stopped nor updated

    (the counting already started)

    (the counting already started)



* When being context-switched out, *del* is called.  It then checks out all the

* When being context-switched out, *del* is called.  It then checks out all the

  events in the PMU and calls *stop* to update their counts.

  events in the PMU and calls *stop* to update their counts.

** *stop* is called by *del*



  - *stop* is called by *del*

    and the perf core with flag PERF_EF_UPDATE, and it often shares the same

    and the perf core with flag PERF_EF_UPDATE, and it often shares the same

    subroutine as *read* with the same logic.

    subroutine as *read* with the same logic.

    The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.

    The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.





** Life cycle of these two pairs: *add* and *del* are called repeatedly as

  - Life cycle of these two pairs: *add* and *del* are called repeatedly as

    tasks switch in-and-out; *start* and *stop* is also called when the perf core

    tasks switch in-and-out; *start* and *stop* is also called when the perf core

    needs a quick stop-and-start, for instance, when the interrupt period is being

    needs a quick stop-and-start, for instance, when the interrupt period is being

    adjusted.

    adjusted.
@@ -246,4 +251,5 @@ References 
----------

----------





[1] https://github.com/riscv/riscv-linux/pull/124

[1] https://github.com/riscv/riscv-linux/pull/124



[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA
 
[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA