USAGE: Document profile report type

Signed-off-by: SeongJae Park <sj38.park@gmail.com>

1 files changed, 31 insertions, 0 deletions

diff --git a/USAGE.md b/USAGE.md
index 1bd10b19..b70e67f9 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -578,6 +578,37 @@ duration spikes could be more easily found.
 Similar to that of ``heats --heatmap``, it also supports `gnuplot` based simple
 visualization of the distribution via ``--plot`` option.
 
+### profile
+
+Note: This feature is an experimental one.  Some changes could be made, or the
+support can be dropped in future.
+
+The `profile` type shows profiling report for specific access pattern.
+
+It requires two files, namely an access pattern record file and a profiling
+information record file that recorded together with the access pattern record
+file.  Those can be generated by `damo record` with `--profile` option (Refer
+to 'Recording Profile Information' [section](#recording-profile-information)
+for details).  Users can further describe access pattern of their interest that
+they want to know what happens when the access pattern occurs.  Then, `damo
+report profile` command read the access pattern, find times when the specific
+access pattern happened, collect profiling information for the time ranges, and
+generate the report with the filtered information.
+
+For example, below shows what was consuming CPU while 50% or more rate of
+access to 50 MiB size address range starting from `139,798,348,038,144`
+happened.
+
+    $ sudo ./damo report profile --access_rate 50% 100% \
+            --address 139798348038144 $((139798348038144 + 50 * 1024 * 1024))
+    Samples: 69K of event 'cpu-clock:pppH', Event count (approx.): 17449500000
+    Overhead  Command          Shared Object         Symbol
+      70.32%  swapper          [kernel.vmlinux]      [k] pv_native_safe_halt
+      28.83%  masim            masim                 [.] do_seq_wo
+       0.03%  masim            [kernel.vmlinux]      [k] _raw_spin_unlock_irqrestore
+       0.03%  ps               [kernel.vmlinux]      [k] do_syscall_64
+       0.03%  swapper          [kernel.vmlinux]      [k] __do_softirq
+
 `damo replay` (Replay Recorded Data Access Pattern)
 ---------------------------------------------------