History

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.

Mauro Carvalho Chehab committed 7 years ago

Commit bdf3a951 parent 329f0042 files · +69 −46Browse files

Unified · Split

2 files
  1. Documentation/riscv/index.rst +17 −0
  2. Documentation/riscv/pmu.rst +52 −46
Documentation/riscv/index.rst+17−0
@@ -0,0 +1,17 @@
1:orphan:
2
3===================
4RISC-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`
Documentation/riscv/pmu.rstrenamed from Documentation/riscv/pmu.txt+52−46
@@ -1,5 +1,7 @@
1===================================
1Supporting PMUs on RISC-V platforms2Supporting PMUs on RISC-V platforms
2==========================================3===================================
4
3Alan Kao <alankao@andestech.com>, Mar 20185Alan Kao <alankao@andestech.com>, Mar 2018
4 6
5Introduction7Introduction
@@ -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 as81(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
82if (!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
88In the case of *riscv_base_pmu*, only (3) is provided for now.90In 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
943.1. Interrupt Initialization963.1. Interrupt Initialization
95 97
96This often occurs at the beginning of the *event_init* method. In common98This often occurs at the beginning of the *event_init* method. In common
97practice, this should be a code segment like99practice, this should be a code segment like::
98 100
99int 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
119And the magic is in *reserve_pmc_hardware*, which usually does atomic121And the magic is in *reserve_pmc_hardware*, which usually does atomic
120operations to make implemented IRQ accessible from some global function pointer.122operations 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
1293.2. IRQ Structure1313.2. IRQ Structure
130 132
131Basically, a IRQ runs the following pseudo code:133Basically, a IRQ runs the following pseudo code::
132 134
133for each hardware counter that triggered this overflow135 for each hardware counter that triggered this overflow
134 136
135 get the event of this counter137 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 interrupt141 count the delta value since previous interrupt
140 update the event->count (# event occurs) by adding delta, and142 update the event->count (# event occurs) by adding delta, and
141 event->hw.period_left by subtracting delta143 event->hw.period_left by subtracting delta
142 144
143 if the event overflows145 if the event overflows
144 sample data146 sample data
145 set the counter appropriately for the next overflow147 set the counter appropriately for the next overflow
146 148
147 if the event overflows again149 if the event overflows again
148 too frequently, throttle this event150 too frequently, throttle this event
149 fi151 fi
150 fi152 fi
151 153
152end for154 end for
153 155
154However as of this writing, none of the RISC-V implementations have designed an156However as of this writing, none of the RISC-V implementations have designed an
155interrupt for perf, so the details are to be completed in the future.157interrupt 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 now198 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 (check201 - *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 updated204 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 the208* 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 as211 - *stop* is called by *del*
212 tasks switch in-and-out; *start* and *stop* is also called when the perf core212 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 being213 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
216Current implementation is sufficient for now and can be easily extended to221Current implementation is sufficient for now and can be easily extended to
217features in the future.222features 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 take232 *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 to233 *struct perf_event* as a main argument, dealing with perf events according to
229perf'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 the236 *struct riscv_pmu* defines PMU-specific parameters. The naming follows the
232convention of all other architectures.237 convention of all other architectures.
233 238
234* struct perf_event: include/linux/perf_event.h239* struct perf_event: include/linux/perf_event.h
235* struct hw_perf_event240* struct hw_perf_event
236 241
237 The generic structure that represents perf events, and the hardware-related242 The generic structure that represents perf events, and the hardware-related
238details.243 details.
239 244
240* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h245* 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:
243the number of events and the array of the events.248 the number of events and the array of the events.
244 249
245References250References
246----------251----------
247 252
248[1] https://github.com/riscv/riscv-linux/pull/124253[1] https://github.com/riscv/riscv-linux/pull/124
254
249[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA255[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t