diff --git a/llvm/docs/CommandGuide/llvm-exegesis.rst b/llvm/docs/CommandGuide/llvm-exegesis.rst --- a/llvm/docs/CommandGuide/llvm-exegesis.rst +++ b/llvm/docs/CommandGuide/llvm-exegesis.rst @@ -65,6 +65,21 @@ 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 ` - 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 `` 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
` - 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 ------------------------------------ @@ -141,7 +156,31 @@ 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 @@ -378,6 +417,13 @@ 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 ----------- diff --git a/llvm/tools/llvm-exegesis/README.md b/llvm/tools/llvm-exegesis/README.md --- a/llvm/tools/llvm-exegesis/README.md +++ b/llvm/tools/llvm-exegesis/README.md @@ -16,6 +16,10 @@ 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 @@ -29,3 +33,9 @@ * 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.