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+===================
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`
Documentation/riscv/pmu.rstrenamed from Documentation/riscv/pmu.txt+52−46
@@ -1,5 +1,7 @@
1+===================================
12 Supporting PMUs on RISC-V platforms
2−==========================================
3+===================================
4+
35 Alan Kao <alankao@andestech.com>, Mar 2018
46
57 Introduction
@@ -77,13 +79,13 @@ Note that some features can be done in this stage as well: · 71 unmodified lines
7779 (2) privilege level setting (user space only, kernel space only, both);
7880 (3) destructor setting. Normally it is sufficient to apply *riscv_destroy_event*;
7981 (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::
8183
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+ }
8789
8890 In the case of *riscv_base_pmu*, only (3) is provided for now.
8991
@@ -94,10 +96,10 @@ In the case of *riscv_base_pmu*, only (3) is provided for now. · 4 unmodified lines
9496 3.1. Interrupt Initialization
9597
9698 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::
98100
99−int x86_reserve_hardware(void)
100−{
101+ int x86_reserve_hardware(void)
102+ {
101103 int err = 0;
102104
103105 if (!atomic_inc_not_zero(&pmc_refcount)) {
@@ -114,7 +116,7 @@ int x86_reserve_hardware(void) · 10 unmodified lines
114116 }
115117
116118 return err;
117−}
119+ }
118120
119121 And the magic is in *reserve_pmc_hardware*, which usually does atomic
120122 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
128130
129131 3.2. IRQ Structure
130132
131−Basically, a IRQ runs the following pseudo code:
133+Basically, a IRQ runs the following pseudo code::
132134
133−for each hardware counter that triggered this overflow
135+ for each hardware counter that triggered this overflow
134136
135− get the event of this counter
137+ get the event of this counter
136138
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
142144
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
146148
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
151153
152−end for
154+ end for
153155
154156 However as of this writing, none of the RISC-V implementations have designed an
155157 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
195197 At this stage, a general event is bound to a physical counter, if any.
196198 The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now
197199 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+
204208 * When being context-switched out, *del* is called. It then checks out all the
205209 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.
210210
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.
215220
216221 Current implementation is sufficient for now and can be easily extended to
217222 features in the future.
@@ -225,25 +230,26 @@ A. Related Structures · 7 unmodified lines
225230 Both structures are designed to be read-only.
226231
227232 *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).
230235
231236 *struct riscv_pmu* defines PMU-specific parameters. The naming follows the
232−convention of all other architectures.
237+ convention of all other architectures.
233238
234239 * struct perf_event: include/linux/perf_event.h
235240 * struct hw_perf_event
236241
237242 The generic structure that represents perf events, and the hardware-related
238−details.
243+ details.
239244
240245 * struct riscv_hw_events: arch/riscv/include/asm/perf_event.h
241246
242247 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.
244249
245250 References
246251 ----------
247252
248253 [1] https://github.com/riscv/riscv-linux/pull/124
254+
249255 [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