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.
Unified · Split
| @@ -0,0 +1,17 @@ | |||
| 1 | :orphan: | ||
| 2 | |||
| 3 | =================== | ||
| 4 | RISC-V architecture | ||
| 5 | =================== | ||
| 6 | |||
| 7 | .. toctree:: | ||
| 8 | :maxdepth: 1 | ||
| 9 | |||
| 10 | pmu | ||
| 11 | |||
| 12 | .. only:: subproject and html | ||
| 13 | |||
| 14 | Indices | ||
| 15 | ======= | ||
| 16 | |||
| 17 | * :ref:`genindex` | ||
| @@ -1,5 +1,7 @@ | |||
| 1 | =================================== | ||
| 1 | Supporting PMUs on RISC-V platforms | 2 | Supporting PMUs on RISC-V platforms |
| 2 | ========================================== | 3 | =================================== |
| 4 | |||
| 3 | Alan Kao <alankao@andestech.com>, Mar 2018 | 5 | Alan Kao <alankao@andestech.com>, Mar 2018 |
| 4 | 6 | ||
| 5 | Introduction | 7 | Introduction |
| @@ -77,13 +79,13 @@ Note that some features can be done in this stage as well: · 71 unmodified lines | |||
| 77 | (2) privilege level setting (user space only, kernel space only, both); | 79 | (2) privilege level setting (user space only, kernel space only, both); |
| 78 | (3) destructor setting. Normally it is sufficient to apply *riscv_destroy_event*; | 80 | (3) destructor setting. Normally it is sufficient to apply *riscv_destroy_event*; |
| 79 | (4) tweaks for non-sampling events, which will be utilized by functions such as | 81 | (4) tweaks for non-sampling events, which will be utilized by functions such as |
| 80 | *perf_adjust_period*, usually something like the follows: | 82 | *perf_adjust_period*, usually something like the follows:: |
| 81 | 83 | ||
| 82 | if (!is_sampling_event(event)) { | 84 | if (!is_sampling_event(event)) { |
| 83 | hwc->sample_period = x86_pmu.max_period; | 85 | hwc->sample_period = x86_pmu.max_period; |
| 84 | hwc->last_period = hwc->sample_period; | 86 | hwc->last_period = hwc->sample_period; |
| 85 | local64_set(&hwc->period_left, hwc->sample_period); | 87 | local64_set(&hwc->period_left, hwc->sample_period); |
| 86 | } | 88 | } |
| 87 | 89 | ||
| 88 | In the case of *riscv_base_pmu*, only (3) is provided for now. | 90 | In the case of *riscv_base_pmu*, only (3) is provided for now. |
| 89 | 91 | ||
| @@ -94,10 +96,10 @@ In the case of *riscv_base_pmu*, only (3) is provided for now. · 4 unmodified lines | |||
| 94 | 3.1. Interrupt Initialization | 96 | 3.1. Interrupt Initialization |
| 95 | 97 | ||
| 96 | This often occurs at the beginning of the *event_init* method. In common | 98 | This often occurs at the beginning of the *event_init* method. In common |
| 97 | practice, this should be a code segment like | 99 | practice, this should be a code segment like:: |
| 98 | 100 | ||
| 99 | int x86_reserve_hardware(void) | 101 | int x86_reserve_hardware(void) |
| 100 | { | 102 | { |
| 101 | int err = 0; | 103 | int err = 0; |
| 102 | 104 | ||
| 103 | if (!atomic_inc_not_zero(&pmc_refcount)) { | 105 | if (!atomic_inc_not_zero(&pmc_refcount)) { |
| @@ -114,7 +116,7 @@ int x86_reserve_hardware(void) · 10 unmodified lines | |||
| 114 | } | 116 | } |
| 115 | 117 | ||
| 116 | return err; | 118 | return err; |
| 117 | } | 119 | } |
| 118 | 120 | ||
| 119 | And the magic is in *reserve_pmc_hardware*, which usually does atomic | 121 | And the magic is in *reserve_pmc_hardware*, which usually does atomic |
| 120 | operations to make implemented IRQ accessible from some global function pointer. | 122 | operations to make implemented IRQ accessible from some global function pointer. |
| @@ -128,28 +130,28 @@ which will be introduced in the next section.) · 7 unmodified lines | |||
| 128 | 130 | ||
| 129 | 3.2. IRQ Structure | 131 | 3.2. IRQ Structure |
| 130 | 132 | ||
| 131 | Basically, a IRQ runs the following pseudo code: | 133 | Basically, a IRQ runs the following pseudo code:: |
| 132 | 134 | ||
| 133 | for each hardware counter that triggered this overflow | 135 | for each hardware counter that triggered this overflow |
| 134 | 136 | ||
| 135 | get the event of this counter | 137 | get the event of this counter |
| 136 | 138 | ||
| 137 | // following two steps are defined as *read()*, | 139 | // following two steps are defined as *read()*, |
| 138 | // check the section Reading/Writing Counters for details. | 140 | // check the section Reading/Writing Counters for details. |
| 139 | count the delta value since previous interrupt | 141 | count the delta value since previous interrupt |
| 140 | update the event->count (# event occurs) by adding delta, and | 142 | update the event->count (# event occurs) by adding delta, and |
| 141 | event->hw.period_left by subtracting delta | 143 | event->hw.period_left by subtracting delta |
| 142 | 144 | ||
| 143 | if the event overflows | 145 | if the event overflows |
| 144 | sample data | 146 | sample data |
| 145 | set the counter appropriately for the next overflow | 147 | set the counter appropriately for the next overflow |
| 146 | 148 | ||
| 147 | if the event overflows again | 149 | if the event overflows again |
| 148 | too frequently, throttle this event | 150 | too frequently, throttle this event |
| 149 | fi | 151 | fi |
| 150 | fi | 152 | fi |
| 151 | 153 | ||
| 152 | end for | 154 | end for |
| 153 | 155 | ||
| 154 | However as of this writing, none of the RISC-V implementations have designed an | 156 | However as of this writing, none of the RISC-V implementations have designed an |
| 155 | interrupt for perf, so the details are to be completed in the future. | 157 | interrupt for perf, so the details are to be completed in the future. |
| @@ -195,23 +197,26 @@ A normal flow of these state transitions are as follows: · 39 unmodified lines | |||
| 195 | At this stage, a general event is bound to a physical counter, if any. | 197 | At this stage, a general event is bound to a physical counter, if any. |
| 196 | The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now | 198 | The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now |
| 197 | stopped, and the (software) event count does not need updating. | 199 | stopped, and the (software) event count does not need updating. |
| 198 | ** *start* is then called, and the counter is enabled. | 200 | |
| 199 | With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check | 201 | - *start* is then called, and the counter is enabled. |
| 200 | previous section for detail). | 202 | With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check |
| 201 | Nothing is written if the flag does not contain PERF_EF_RELOAD. | 203 | previous section for detail). |
| 202 | The state now is reset to none, because it is neither stopped nor updated | 204 | Nothing is written if the flag does not contain PERF_EF_RELOAD. |
| 203 | (the counting already started) | 205 | The state now is reset to none, because it is neither stopped nor updated |
| 206 | (the counting already started) | ||
| 207 | |||
| 204 | * When being context-switched out, *del* is called. It then checks out all the | 208 | * When being context-switched out, *del* is called. It then checks out all the |
| 205 | events in the PMU and calls *stop* to update their counts. | 209 | events in the PMU and calls *stop* to update their counts. |
| 206 | ** *stop* is called by *del* | ||
| 207 | and the perf core with flag PERF_EF_UPDATE, and it often shares the same | ||
| 208 | subroutine as *read* with the same logic. | ||
| 209 | The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again. | ||
| 210 | 210 | ||
| 211 | ** Life cycle of these two pairs: *add* and *del* are called repeatedly as | 211 | - *stop* is called by *del* |
| 212 | tasks switch in-and-out; *start* and *stop* is also called when the perf core | 212 | and the perf core with flag PERF_EF_UPDATE, and it often shares the same |
| 213 | needs a quick stop-and-start, for instance, when the interrupt period is being | 213 | subroutine as *read* with the same logic. |
| 214 | adjusted. | 214 | The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again. |
| 215 | |||
| 216 | - Life cycle of these two pairs: *add* and *del* are called repeatedly as | ||
| 217 | tasks switch in-and-out; *start* and *stop* is also called when the perf core | ||
| 218 | needs a quick stop-and-start, for instance, when the interrupt period is being | ||
| 219 | adjusted. | ||
| 215 | 220 | ||
| 216 | Current implementation is sufficient for now and can be easily extended to | 221 | Current implementation is sufficient for now and can be easily extended to |
| 217 | features in the future. | 222 | features in the future. |
| @@ -225,25 +230,26 @@ A. Related Structures · 7 unmodified lines | |||
| 225 | Both structures are designed to be read-only. | 230 | Both structures are designed to be read-only. |
| 226 | 231 | ||
| 227 | *struct pmu* defines some function pointer interfaces, and most of them take | 232 | *struct pmu* defines some function pointer interfaces, and most of them take |
| 228 | *struct perf_event* as a main argument, dealing with perf events according to | 233 | *struct perf_event* as a main argument, dealing with perf events according to |
| 229 | perf's internal state machine (check kernel/events/core.c for details). | 234 | perf's internal state machine (check kernel/events/core.c for details). |
| 230 | 235 | ||
| 231 | *struct riscv_pmu* defines PMU-specific parameters. The naming follows the | 236 | *struct riscv_pmu* defines PMU-specific parameters. The naming follows the |
| 232 | convention of all other architectures. | 237 | convention of all other architectures. |
| 233 | 238 | ||
| 234 | * struct perf_event: include/linux/perf_event.h | 239 | * struct perf_event: include/linux/perf_event.h |
| 235 | * struct hw_perf_event | 240 | * struct hw_perf_event |
| 236 | 241 | ||
| 237 | The generic structure that represents perf events, and the hardware-related | 242 | The generic structure that represents perf events, and the hardware-related |
| 238 | details. | 243 | details. |
| 239 | 244 | ||
| 240 | * struct riscv_hw_events: arch/riscv/include/asm/perf_event.h | 245 | * struct riscv_hw_events: arch/riscv/include/asm/perf_event.h |
| 241 | 246 | ||
| 242 | The structure that holds the status of events, has two fixed members: | 247 | The structure that holds the status of events, has two fixed members: |
| 243 | the number of events and the array of the events. | 248 | the number of events and the array of the events. |
| 244 | 249 | ||
| 245 | References | 250 | References |
| 246 | ---------- | 251 | ---------- |
| 247 | 252 | ||
| 248 | [1] https://github.com/riscv/riscv-linux/pull/124 | 253 | [1] https://github.com/riscv/riscv-linux/pull/124 |
| 254 | |||
| 249 | [2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA | 255 | [2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA |