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 | 2 | Supporting PMUs on RISC-V platforms |
| 2 | −========================================== | |
| 3 | +=================================== | |
| 4 | + | |
| 3 | 5 | Alan Kao <alankao@andestech.com>, Mar 2018 |
| 4 | 6 | |
| 5 | 7 | Introduction |
| @@ -77,13 +79,13 @@ Note that some features can be done in this stage as well: · 71 unmodified lines | ||
| 77 | 79 | (2) privilege level setting (user space only, kernel space only, both); |
| 78 | 80 | (3) destructor setting. Normally it is sufficient to apply *riscv_destroy_event*; |
| 79 | 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)) { | |
| 83 | − hwc->sample_period = x86_pmu.max_period; | |
| 84 | − hwc->last_period = hwc->sample_period; | |
| 85 | − local64_set(&hwc->period_left, hwc->sample_period); | |
| 86 | −} | |
| 84 | + if (!is_sampling_event(event)) { | |
| 85 | + hwc->sample_period = x86_pmu.max_period; | |
| 86 | + hwc->last_period = hwc->sample_period; | |
| 87 | + local64_set(&hwc->period_left, hwc->sample_period); | |
| 88 | + } | |
| 87 | 89 | |
| 88 | 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 | 96 | 3.1. Interrupt Initialization |
| 95 | 97 | |
| 96 | 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) | |
| 100 | −{ | |
| 101 | + int x86_reserve_hardware(void) | |
| 102 | + { | |
| 101 | 103 | int err = 0; |
| 102 | 104 | |
| 103 | 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 | 118 | return err; |
| 117 | −} | |
| 119 | + } | |
| 118 | 120 | |
| 119 | 121 | And the magic is in *reserve_pmc_hardware*, which usually does atomic |
| 120 | 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 | 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()*, | |
| 138 | − // check the section Reading/Writing Counters for details. | |
| 139 | − count the delta value since previous interrupt | |
| 140 | − update the event->count (# event occurs) by adding delta, and | |
| 141 | − event->hw.period_left by subtracting delta | |
| 139 | + // following two steps are defined as *read()*, | |
| 140 | + // check the section Reading/Writing Counters for details. | |
| 141 | + count the delta value since previous interrupt | |
| 142 | + update the event->count (# event occurs) by adding delta, and | |
| 143 | + event->hw.period_left by subtracting delta | |
| 142 | 144 | |
| 143 | − if the event overflows | |
| 144 | − sample data | |
| 145 | − set the counter appropriately for the next overflow | |
| 145 | + if the event overflows | |
| 146 | + sample data | |
| 147 | + set the counter appropriately for the next overflow | |
| 146 | 148 | |
| 147 | − if the event overflows again | |
| 148 | − too frequently, throttle this event | |
| 149 | − fi | |
| 150 | − fi | |
| 149 | + if the event overflows again | |
| 150 | + too frequently, throttle this event | |
| 151 | + fi | |
| 152 | + fi | |
| 151 | 153 | |
| 152 | −end for | |
| 154 | + end for | |
| 153 | 155 | |
| 154 | 156 | However as of this writing, none of the RISC-V implementations have designed an |
| 155 | 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 | 197 | At this stage, a general event is bound to a physical counter, if any. |
| 196 | 198 | The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now |
| 197 | 199 | stopped, and the (software) event count does not need updating. |
| 198 | −** *start* is then called, and the counter is enabled. | |
| 199 | − With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check | |
| 200 | − previous section for detail). | |
| 201 | − Nothing is written if the flag does not contain PERF_EF_RELOAD. | |
| 202 | − The state now is reset to none, because it is neither stopped nor updated | |
| 203 | − (the counting already started) | |
| 200 | + | |
| 201 | + - *start* is then called, and the counter is enabled. | |
| 202 | + With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check | |
| 203 | + previous section for detail). | |
| 204 | + Nothing is written if the flag does not contain PERF_EF_RELOAD. | |
| 205 | + The state now is reset to none, because it is neither stopped nor updated | |
| 206 | + (the counting already started) | |
| 207 | + | |
| 204 | 208 | * When being context-switched out, *del* is called. It then checks out all the |
| 205 | 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 | |
| 212 | − tasks switch in-and-out; *start* and *stop* is also called when the perf core | |
| 213 | − needs a quick stop-and-start, for instance, when the interrupt period is being | |
| 214 | − adjusted. | |
| 211 | + - *stop* is called by *del* | |
| 212 | + and the perf core with flag PERF_EF_UPDATE, and it often shares the same | |
| 213 | + subroutine as *read* with the same logic. | |
| 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 | 221 | Current implementation is sufficient for now and can be easily extended to |
| 217 | 222 | features in the future. |
| @@ -225,25 +230,26 @@ A. Related Structures · 7 unmodified lines | ||
| 225 | 230 | Both structures are designed to be read-only. |
| 226 | 231 | |
| 227 | 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 | |
| 229 | −perf's internal state machine (check kernel/events/core.c for details). | |
| 233 | + *struct perf_event* as a main argument, dealing with perf events according to | |
| 234 | + perf's internal state machine (check kernel/events/core.c for details). | |
| 230 | 235 | |
| 231 | 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 | 239 | * struct perf_event: include/linux/perf_event.h |
| 235 | 240 | * struct hw_perf_event |
| 236 | 241 | |
| 237 | 242 | The generic structure that represents perf events, and the hardware-related |
| 238 | −details. | |
| 243 | + details. | |
| 239 | 244 | |
| 240 | 245 | * struct riscv_hw_events: arch/riscv/include/asm/perf_event.h |
| 241 | 246 | |
| 242 | 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 | 250 | References |
| 246 | 251 | ---------- |
| 247 | 252 | |
| 248 | 253 | [1] https://github.com/riscv/riscv-linux/pull/124 |
| 254 | + | |
| 249 | 255 | [2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA |