[Docs][llvm-exegesis] Add documentation for memory

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

Rebase

[aidengrossman]

@courbet Now that (most of) the memory annotation patch stack has landed, do you mind taking a look at this patch when you have time?

[ondrasej]

llvm/docs/CommandGuide/llvm-exegesis.rst

72

Typo: ...in bytes, the value is

79

Would it be possible to parse both decimal and hex? E.g. parse "123" as decimal, and "0x123" as hex.

Similar for the size of the memory (on the other side, the value stored in the memory might be easiest when kept only in hex).

[aidengrossman]

Address reviewer feedback.

llvm/docs/CommandGuide/llvm-exegesis.rst

79

Yes, this is possible, just not something I currently have implemented (but probably something I should write up a patch for at some point). Since this isn't supported currently, I'm thinking we leave the documentation as is, documenting the functionality currently, and then add in enhanced parsing along with documentation changes in a future patch. Thoughts?

llvm/docs/CommandGuide/llvm-exegesis.rst

* `LLVM-EXEGESIS-LIVEIN <register name>` - This annotation allows specifying
   can be passed through registers from the benchmarking setup in some cases.
   The registers and the values assigned to them that can be utilized in the
   benchmarking script with a `LLVM-EXEGESIS-LIVEIN` are as follows:
 
   * Scratch memory register - The specific register that this value is put in
     is platform dependent (e.g., it is the RDI register on X86 Linux). Setting
     this register as a live in ensures that a pointer to a block of memory (1MB)
     is placed within this register that can be used by the snippet.
+* `LLVM-EXEGESIS-MEM-DEF <value name> <size> <value>` - This annotation allows
+  specifying memory definitions that can later be mapped into the execution
+  process of a snippet with the `LLVM-EXEGESIS-MEM-MAP` annotation. Each
+  value is named using the `<value name>` argument so that it can be referenced
+  later within a map annotation. The size is specified in bytes the the value
+  is taken in hexadecimal. If the size of the value is less than the specified
+  size, the value will be repeated until it fills the entire section of memory.
+  Using this annotation requires using the subprocess execution mode.
+* `LLVM-EXEGESIS-MEM-MAP <value name> <address>` - This annotation allows for
+  mapping previously defined memory definitions into the execution context of a
+  process. The value name refers to a previously defined memory definition and
+  the address is a decimal number that specifies the address the memory
+  definition should start at. Note that a single memory definition can be
+  mapped multiple times. Using this annotation requires the subprocess
+  execution mode.
 
 EXAMPLE 1: benchmarking instructions
 ------------------------------------
 
 Assume you have an X86-64 machine. To measure the latency of a single
 instruction, run:
 
 .. code-block:: bash
.. code-block:: none
 
   # LLVM-EXEGESIS-LIVEIN RDI
   # LLVM-EXEGESIS-DEFREG XMM1 42
   vmulps  (%rdi), %xmm1, %xmm2
   vhaddps %xmm2, %xmm2, %xmm3
   addq $0x10, %rdi
 
 
-EXAMPLE 3: analysis
+Example 3: benchmarking with memory annotations
+-----------------------------------------------
+
+Some snippets require memory setup in specific places to execute without
+crashing. Setting up memory can be accomplished with the `LLVM-EXEGESIS-MEM-DEF`
+and `LLVM-EXEGESIS-MEM-MAP` annotations. To execute the following snippet:
+
+.. code-block:: none
+
+    movq $8192, %rax
+    movq (%rax), %rdi
+
+We need to have at least eight bytes of memory allocated starting `0x2000`.
+We can create the necessary execution environment with the following
+annotations added to the snippet:
+
+.. code-block:: none
+
+  # LLVM-EXEGESIS-MEM-DEF test1 4096 2147483647
+  # LLVM-EXEGESIS-MEM-MAP test1 8192
+
+  movq $8192, %rax
+  movq (%rax), %rdi
+
+EXAMPLE 4: analysis
 -------------------
 
 Assuming you have a set of benchmarked instructions (either latency or uops) as
 YAML in file `/tmp/benchmarks.yaml`, you can analyze the results using the
 following command:
 
 .. code-block:: bash
 

 
 .. option:: --use-dummy-perf-counters
 
  If set, llvm-exegesis will not read any real performance counters and
  return a dummy value instead. This can be used to ensure a snippet doesn't
  crash when hardware performance counters are unavailable and for
  debugging :program:`llvm-exegesis` itself.
 
+.. option:: --execution-mode=[inprocess,subprocess]
+
+  This option specifies what execution mode to use. The `inprocess` execution
+  mode is the default. The `subprocess` execution mode allows for additional
+  features such as memory annotations but is currently restricted to X86-64
+  on Linux.
+
 EXIT STATUS
 -----------
 
 :program:`llvm-exegesis` returns 0 on success. Otherwise, an error message is
 printed to standard error, and the tool returns a non 0 value.

llvm/tools/llvm-exegesis/README.md

 Analysis mode in `llvm-exegesis` is supported on all platforms on which LLVM is.
 
 #### Currently Supported Operating Systems for Benchmarking
 
 Currently, `llvm-exegesis`  only supports benchmarking on Linux. This is mainly
 due to a dependency on the Linux perf subsystem for reading performance
 counters.
 
+The subprocess execution mode and memory annotations currently only supports
+Linux due to a heavy reliance on many Linux specific syscalls/syscall
+implementations.
+
 #### Currently Supported Architectures for Benchmarking
 
 Currently, using `llvm-exegesis` for benchmarking is supported on the following
 architectures:
 * x86
   * 64-bit only due to this being the only implemented calling convention
     in `llvm-exegesis` currently.
 * ARM
   * AArch64 only
 * MIPS
 * PowerPC (PowerPC64LE only)
 
 Note that not benchmarking functionality is guaranteed to work on all platforms.
+
+Memory annotations are currently only supported on 64-bit X86. There is no
+inherent limitations for porting memory annotations to other architectures, but
+parts of the test harness are implemented as MCJITed assembly that is generated
+in `./lib/X86/Target.cpp` that would need to be implemented on other architectures
+to bring up support.