[wperf] Update usage docs for wperf CLI (#69)

* wperf: update usage and comments for --pe_file, --image_name and --annotate

Added small clarification in the code for image name, PE and PDB file
name deduction.

* wperf: udpate usage in README

Author: PrzemekWirkus

wperf/README.md

@@ -112,16 +112,17 @@ OPTIONS:
         Number of consecutive counts in timeline mode (disabled by default).
 
     --annotate
-        Enable translating addresses taken from samples in sample/record mode into source code line numbers.
+        Enable translating addresses taken from samples in sample/record mode
+        into source code line numbers.
 
     --disassemble
         Enable disassemble output on sampling mode. Implies 'annotate'.
 
     --image_name
-        Specify the image name you want to sample.
+        Specify the image (base) name of a module to sample.
 
     --pe_file
-        Specify the PE filename (and path).
+        Specify the PE filename (and path) to sample.
 
     --pdb_file
         Specify the PDB filename (and path), PDB file should directly
@@ -133,7 +134,7 @@ OPTIONS:
     --sample-display-row
         Set how many samples you want to see in the summary (50 by default).
 
-    -s, --symbol
+    --symbol
         Filter results for specific symbols (for use with 'record' and 'sample' commands).
 
     --record_spawn_delay
@@ -183,6 +184,8 @@ OPTIONS aliases:
 
     sleep
         Alias of `--timeout`.
+    -s
+        Alias of `--symbol`.
 
 EXAMPLES:
 
@@ -212,6 +215,11 @@ EXAMPLES:
     with frequency `100000` on core #1 for 30 seconds.
     Hint: add `--annotate` or `--disassemble` to `wperf record` command line
     parameters to increase sampling "resolution".
+
+    > wperf record -e arm_spe_0/ld=1/ -c 8 --cpython\PCbuild\arm64\python_d.exe -c 10**10**100
+    Launch `python_d.exe -c 10**10**100` process on core no. 8 and start SPE sampling, enable
+    collection of load sampled operations, including atomic operations that return a value to a register.
+    Hint: add `--annotate` or `--disassemble` to `wperf record` command.
 ```
 
 ## Important Note: Use of curly braces in command line

wperf/user_request.cpp

@@ -138,16 +138,17 @@ void user_request::print_help_usage()
         Number of consecutive counts in timeline mode (disabled by default).
 
     --annotate
-        Enable translating addresses taken from samples in sample/record mode into source code line numbers.
+        Enable translating addresses taken from samples in sample/record mode
+        into source code line numbers.
 
     --disassemble
         Enable disassemble output on sampling mode. Implies 'annotate'.
 
     --image_name
-        Specify the image name you want to sample.
+        Specify the image (base) name of a module to sample.
 
     --pe_file
-        Specify the PE filename (and path).
+        Specify the PE filename (and path) to sample.
 
     --pdb_file
         Specify the PDB filename (and path), PDB file should directly
@@ -336,13 +337,26 @@ void user_request::init(wstr_vec& raw_args, const struct pmu_device_cfg& pmu_cfg
     // Deduce image name and PDB file name from PE file name
     if (sample_pe_file.size())
     {
+        /*
+        * if `image_name` is not provided by user with `--image_name` we can
+        * deduce image / base module name based on PE file name provided with
+        * `--pe_file`. In most cases these are the same. In case image name is
+        * different than PE name users should provide `image_name` to remove
+        * ambiguity.
+        */
         if (sample_image_name.empty())
         {
             sample_image_name = sample_pe_file;
             if (do_verbose)
                 m_out.GetOutputStream() << L"deduced image name '" << sample_image_name << L"'" << std::endl;
         }
 
+        /*
+        * We can also deduce PE file's corresponding PDB file (with debug information)
+        * based on PE file name (and path). Assumptions is that PDB files and PE files
+        * are located in the same directory and have the same name (excluding extension).
+        * E.g. `c:\path\to\image.exe` ->`c:\path\to\image.pdb`.
+        */
         if (sample_pdb_file.empty())
         {
             sample_pdb_file = ReplaceFileExtension(sample_pe_file, L"pdb");