### Install Executable

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Headers/tools/buildHeaders/CMakeLists.txt

Installs the 'buildSpvHeaders' target to the 'bin' directory at runtime.

```cmake
install(TARGETS buildSpvHeaders RUNTIME DESTINATION bin)
```

--------------------------------

### Start SVA Webserver

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/tools/sva/README.md

Starts a local webserver on localhost:5000. Load tests/index.html in a browser to use the SVA files.

```shell
yarn serve
```

--------------------------------

### SwiftShader Configuration File Example

Source: https://github.com/google/swiftshader/blob/master/docs/RuntimeConfiguration.md

Example of a SwiftShader.ini file demonstrating sections, key-value pairs, and comments for runtime configuration.

```ini
[Processor]
ThreadCount=4
AffinityMask=0xf

# Comment
[Profiler]
EnableSpirvProfiling=true

```

--------------------------------

### Run Marl Emscripten Webserver

Source: https://github.com/google/swiftshader/blob/master/third_party/marl/README.md

Python script command to start a local web server for testing Emscripten-built Marl examples. Navigate to http://127.0.0.1:8080/ in your browser.

```bash
../run_webserver
```

--------------------------------

### Install pkg-config files

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/CMakeLists.txt

Installs the generated SPIRV-Tools.pc and SPIRV-Tools-shared.pc files to the pkgconfig directory if the ENABLE_SPIRV_TOOLS_INSTALL option is enabled.

```cmake
if (ENABLE_SPIRV_TOOLS_INSTALL)
  install(
    FILES
      ${CMAKE_CURRENT_BINARY_DIR}/SPIRV-Tools.pc
      ${CMAKE_CURRENT_BINARY_DIR}/SPIRV-Tools-shared.pc
    DESTINATION
      ${CMAKE_INSTALL_LIBDIR}/pkgconfig)
endif()
```

--------------------------------

### Install and Test SVA

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/tools/sva/README.md

Installs the SVA package and runs the test suite using Yarn. Use 'yarn watch' to automatically re-run tests when files change.

```shell
yarn install
yarn test
```

--------------------------------

### Initialize PowerVR Examples Submodule

Source: https://github.com/google/swiftshader/blob/master/CMakeLists.txt

Initializes the `PVRCore` submodule if `SWIFTSHADER_BUILD_PVR` is enabled.

```cmake
if(SWIFTSHADER_BUILD_PVR)
    InitSubmodule(PVRCore ${THIRD_PARTY_DIR}/PowerVR_Examples)
endif()
```

--------------------------------

### Pre-/Post-Indexed Load/Store Optimization Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/ARM/README.txt

Contrasts a pre-indexed load with a sequence of load and add operations. The example highlights a scenario where a pre-indexed load might be a 'wasted optimization' if the base pointer is live beyond the load, suggesting a split into add/sub and load/store.

```assembly
mov r1, r2
ldr r3, [r1], #4
...
```

```assembly
ldr r3, [r2]
add r1, r2, #4
...
```

--------------------------------

### Build Marl Example with Emscripten

Source: https://github.com/google/swiftshader/blob/master/third_party/marl/README.md

Commands to build a Marl example (e.g., hello_task) using Emscripten's CMake wrapper. Ensure the emscripten SDK is activated and the sPTHREAD_POOL_SIZE linker flag is appropriately set.

```bash
cd <path-to-marl>
mkdir build
cd build
emcmake cmake .. -DMARL_BUILD_EXAMPLES=1
make hello_task -j 8
```

--------------------------------

### Running pnacl-sz with a pexe file

Source: https://github.com/google/swiftshader/blob/master/third_party/subzero/README.rst

Example of how to run the pnacl-sz tool to parse and translate a pexe file.

```bash
../pnacl-sz ./path/to/<file>.pexe
```

--------------------------------

### Configure SPIRV-Headers Installation

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Headers/CMakeLists.txt

Sets up installation rules for SPIRV-Headers, including header files, CMake configuration files, and pkgconfig files. This block is executed only if SPIRV_HEADERS_ENABLE_INSTALL is true.

```cmake
if(SPIRV_HEADERS_ENABLE_INSTALL)
    include(GNUInstallDirs)
    include(CMakePackageConfigHelpers)

    install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/spirv DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

    set(cmake_install_dir "${CMAKE_INSTALL_DATADIR}/cmake/SPIRV-Headers")
    set(version_config "${CMAKE_CURRENT_BINARY_DIR}/generated/SPIRV-HeadersConfigVersion.cmake")

    write_basic_package_version_file("${version_config}" COMPATIBILITY SameMajorVersion ARCH_INDEPENDENT)
    install(FILES "${version_config}" DESTINATION "${cmake_install_dir}")

    install(TARGETS SPIRV-Headers EXPORT "SPIRV-HeadersConfig" INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
    install(EXPORT "SPIRV-HeadersConfig" NAMESPACE "SPIRV-Headers::" DESTINATION "${cmake_install_dir}")

    if (IS_ABSOLUTE ${CMAKE_INSTALL_INCLUDEDIR})
        set(SPIRV_HEADERS_PKGCONFIG_INCLUDE_DIR ${CMAKE_INSTALL_INCLUDEDIR})
    else()
        set(SPIRV_HEADERS_PKGCONFIG_INCLUDE_DIR ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR})
    endif()
    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/SPIRV-Headers.pc.in ${CMAKE_CURRENT_BINARY_DIR}/SPIRV-Headers.pc @ONLY)
    install(FILES "${CMAKE_CURRENT_BINARY_DIR}/SPIRV-Headers.pc" DESTINATION ${CMAKE_INSTALL_DATADIR}/pkgconfig)
endif()
```

--------------------------------

### Set Installation Prefix

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Headers/tools/buildHeaders/CMakeLists.txt

Configures the installation directory for the built targets. The FORCE option ensures this setting overrides any previous cache value.

```cmake
set(CMAKE_INSTALL_PREFIX "install" CACHE STRING "prefix" FORCE)
```

--------------------------------

### LLVM IR for Store Sinking Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/README.txt

This LLVM IR snippet corresponds to the C code example for store sinking, illustrating the current state before the desired optimization is applied.

```llvm
bb:	; preds = %bb2, %entry
	%.rle = phi i32 [ 0, %entry ], [ %.rle6, %bb2 ]	
	%i.05 = phi i32 [ 0, %entry ], [ %indvar.next, %bb2 ]
	%1 = load i32* %cond, align 4
	%2 = icmp eq i32 %1, 0
	br i1 %2, label %bb2, label %bb1

bb1:	; preds = %bb
	%3 = xor i32 %.rle, 234	
	store i32 %3, i32* %res, align 4
	br label %bb2

bb2:	; preds = %bb, %bb1
	%.rle6 = phi i32 [ %3, %bb1 ], [ %.rle, %bb ]	
	%indvar.next = add i32 %i.05, 1	
	%exitcond = icmp eq i32 %indvar.next, %n
```

--------------------------------

### FP Stack Permutation Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/X86/README-FPStack.txt

Illustrates how simple permutations on the FP stack can be optimized to reduce the number of shuffle instructions. This example shows reordering of `fld` operations.

```Assembly
fld P	fld Q	fxch
```

--------------------------------

### FP Stack Permutation Example 2

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/X86/README-FPStack.txt

Shows another example of optimizing FP stack operations by reordering `fxch` and `fucomi` instructions to potentially reduce instruction count or improve performance.

```Assembly
fxch
fucomi
jg X
```

--------------------------------

### C++ to X86 Assembly: Tail Call Optimization Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/X86/README.txt

Illustrates a C++ example demonstrating the need for tail call optimization to prevent overwriting caller arguments. Shows the potential stack layout changes.

```cpp
int callee(int32, int64); 
int caller(int32 arg1, int32 arg2) { 
  int64 local = arg2 * 2; 
  return callee(arg2, (int64)local); 
}
```

--------------------------------

### Build Marl Unit Tests and Examples on Linux/macOS

Source: https://github.com/google/swiftshader/blob/master/third_party/marl/README.md

CMake commands to configure and build Marl's unit tests and examples on Linux and macOS. Assumes googletest submodule is initialized.

```bash
cd <path-to-marl>
mkdir build
cd build
cmake .. -DMARL_BUILD_EXAMPLES=1 -DMARL_BUILD_TESTS=1
make
```

--------------------------------

### PowerPC Assembly Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/PowerPC/README_ALTIVEC.txt

A snippet of PowerPC assembly code demonstrating control flow and register manipulation.

```assembly
vcmpeqfp. v2, v3, v2
        mfcr r3, 2
        rlwinm r3, r3, 25, 31, 31
        cmpwi cr0, r3, 0
        bne cr0, LBB1_2 ; entry
LBB1_1: ; entry
        mr r6, r5
LBB1_2: ; entry
        mr r3, r6
        mtspr 256, r2
        blr
```

--------------------------------

### ARM Predication Optimization Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/ARM/README.txt

Compares two code generation strategies for a C function involving conditional logic. The second example demonstrates an optimization to fold a shift into a conditional move, saving an instruction and a register.

```c
extern unsigned array[ 128 ];
int     foo( int x ) {
  int     y;
  y = array[ x & 127 ];
  if ( x & 128 )
     y = 123456789 & ( y >> 2 );
  else
     y = 123456789 & y;
  return y;
}
```

```assembly
_foo:
	and r1, r0, #127
	ldr r2, LCPI1_0
	ldr r2, [r2]
	ldr r1, [r2, +r1, lsl #2]
	mov r2, r1, lsr #2
	tst r0, #128
	moveq r2, r1
	ldr r0, LCPI1_1
	and r0, r2, r0
	bx lr
```

```assembly
	and r1, r0, #127
	ldr r2, LCPI1_0
	ldr r2, [r2]
	ldr r1, [r2, +r1, lsl #2]
	tst r0, #128
	movne r1, r1, lsr #2
	ldr r0, LCPI1_1
	and r0, r1, r0
	bx lr
```

--------------------------------

### LLVM Component Library Setup

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/ToolDrivers/llvm-dlltool/CMakeLists.txt

Defines the LLVMDlltoolDriver component library and adds dependencies.

```cmake
add_llvm_component_library(LLVMDlltoolDriver
  DlltoolDriver.cpp
  )

add_dependencies(LLVMDlltoolDriver DllOptionsTableGen)
```

--------------------------------

### Dereference a Pointer to an Integer

Source: https://github.com/google/swiftshader/blob/master/docs/Reactor.md

Example of declaring a function that takes a Pointer<Int> and dereferencing it to get an Int value.

```C++
Function<Int(Pointer<Int>)> function;
{
    Pointer<Int> x = function.Arg<0>();

    Int dereference = *x;

    Return(dereference);
}
```

--------------------------------

### Include SPIR-V Headers in C/C++ Source (CMake)

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Headers/README.md

Example include directives for using SPIR-V headers in C or C++ source code after installation or when using CMake's add_subdirectory.

```c++
#include "spirv/unified1/GLSL.std.450.h"
#include "spirv/unified1/OpenCL.std.h"
#include "spirv/unified1/spirv.hpp"
```

--------------------------------

### C Variadic Function and x86-64 Assembly

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/X86/README.txt

Shows the compilation of a C function using variadic arguments (__builtin_va_list) into x86-64 assembly. This example illustrates the stack setup and argument handling for variadic functions.

```C
int foo(const char *str,...)
{
 __builtin_va_list a; int x;
 __builtin_va_start(a,str); x = __builtin_va_arg(a,int); __builtin_va_end(a);
 return x;
}
```

```Assembly
	subq	$200, %rsp
        movaps	%xmm7, 160(%rsp)
        movaps	%xmm6, 144(%rsp)
        movaps	%xmm5, 128(%rsp)
        movaps	%xmm4, 112(%rsp)
        movaps	%xmm3, 96(%rsp)
        movaps	%xmm2, 80(%rsp)
        movaps	%xmm1, 64(%rsp)
        movaps	%xmm0, 48(%rsp)
        movq	%r9, 40(%rsp)
        movq	%r8, 32(%rsp)
        movq	%rcx, 24(%rsp)
        movq	%rdx, 16(%rsp)
        movq	%rsi, 8(%rsp)
        leaq	(%rsp), %rax
        movq	%rax, 192(%rsp)
        leaq	208(%rsp), %rax
        movq	%rax, 184(%rsp)
        movl	$48, 180(%rsp)
        movl	$8, 176(%rsp)
        movl	176(%rsp), %eax
        cmpl	$47, %eax
        jbe	.LBB1_3 # bb
.LBB1_1:	# bb3
        movq	184(%rsp), %rcx
        leaq	8(%rcx), %rax
        movq	%rax, 184(%rsp)
.LBB1_2:	# bb4
        movl	(%rcx), %eax
        addq	$200, %rsp
        ret
.LBB1_3:	# bb
        movl	%eax, %ecx
        addl	$8, %eax
        addq	192(%rsp), %rcx
        movl	%eax, 176(%rsp)
        jmp	.LBB1_2 # bb4
```

--------------------------------

### Start dEQP Test Server

Source: https://github.com/google/swiftshader/blob/master/docs/dEQP.md

Run the Cherry test server from its root directory. This server is used to manage and execute dEQP tests.

```bash
go run server.go
```

--------------------------------

### Install SPIRV-Tools-reduce Target

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/source/reduce/CMakeLists.txt

Configures the installation of the SPIRV-Tools-reduce target and its associated export file when installation is enabled.

```cmake
if(ENABLE_SPIRV_TOOLS_INSTALL)
  install(TARGETS SPIRV-Tools-reduce EXPORT SPIRV-Tools-reduceTargets)
  export(EXPORT SPIRV-Tools-reduceTargets FILE SPIRV-Tools-reduceTarget.cmake)

  spvtools_config_package_dir(SPIRV-Tools-reduce PACKAGE_DIR)
  install(EXPORT SPIRV-Tools-reduceTargets FILE SPIRV-Tools-reduceTarget.cmake
  	DESTINATION ${PACKAGE_DIR})

  spvtools_generate_config_file(SPIRV-Tools-reduce)
  install(FILES ${CMAKE_BINARY_DIR}/SPIRV-Tools-reduceConfig.cmake DESTINATION ${PACKAGE_DIR})
endif(ENABLE_SPIRV_TOOLS_INSTALL)
```

--------------------------------

### Install SPIR-V Headers using CMake

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Headers/README.md

Steps to build and install the SPIR-V headers using CMake. The headers will be installed to `/usr/local/include/spirv/unified1/` by default.

```bash
mkdir build
cd build
cmake ..
cmake --build . --target install
```

--------------------------------

### Define SPIRV-Tools Example Function

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/examples/CMakeLists.txt

Defines a CMake function to add SPIR-V Tools examples. It takes a target name, source files, and libraries as input, creating an executable with default compile options and linking specified libraries. The example is then placed in a 'SPIRV-Tools examples' folder.

```cmake
function(add_spvtools_example)
  if (NOT ${SPIRV_SKIP_EXECUTABLES})
    set(one_value_args TARGET)
    set(multi_value_args SRCS LIBS)
    cmake_parse_arguments(
        ARG "" ${one_value_args} ${multi_value_args} ${ARGN})

    add_executable(${ARG_TARGET} ${ARG_SRCS})
    spvtools_default_compile_options(${ARG_TARGET})
    target_link_libraries(${ARG_TARGET} PRIVATE ${ARG_LIBS})
    set_property(TARGET ${ARG_TARGET} PROPERTY FOLDER "SPIRV-Tools examples")
  endif()
endfunction()
```

--------------------------------

### Getting Help for run_testlist.sh

Source: https://github.com/google/swiftshader/blob/master/docs/Regres.md

View all available flags and options for the run_testlist.sh script by running it with the --help flag.

```bash
run_testlist.sh --help
```

--------------------------------

### Initialize BLAKE3 Hasher for Key Derivation (C String Context)

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Support/BLAKE3/README.md

Initializes a BLAKE3 hasher for key derivation using a null-terminated C string as context. The context should be hardcoded, globally unique, and application-specific.

```c
void llvm_blake3_hasher_init_derive_key(
  llvm_blake3_hasher *self,
  const char *context);
```

--------------------------------

### Install Marl using vcpkg

Source: https://github.com/google/swiftshader/blob/master/third_party/marl/README.md

Commands to install Marl using the vcpkg dependency manager. This involves cloning vcpkg, bootstrapping, integrating it with your system, and then installing the marl package.

```bash
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install marl
```

--------------------------------

### C llvm_blake3_hasher_init Function

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Support/BLAKE3/README.md

Initializes the C BLAKE3 hasher state.

```c
void llvm_blake3_hasher_init(
  llvm_blake3_hasher *self);

```

--------------------------------

### Emacs Lisp Helper Installation Logic

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/tools/emacs/CMakeLists.txt

This CMake code block conditionally installs an Emacs helper script (`50spirv-tools.el`) to `/etc/emacs/site-start.d/`. Installation requires `SPIRV_TOOLS_INSTALL_EMACS_HELPERS` to be defined and the target directory to exist.

```cmake
option(SPIRV_TOOLS_INSTALL_EMACS_HELPERS
  "Install Emacs helper to disassemble/assemble SPIR-V binaries on file load/save."
  ${SPIRV_TOOLS_INSTALL_EMACS_HELPERS})
if (${SPIRV_TOOLS_INSTALL_EMACS_HELPERS})
  if(EXISTS /etc/emacs/site-start.d)
    if(ENABLE_SPIRV_TOOLS_INSTALL)
      install(FILES 50spirv-tools.el DESTINATION /etc/emacs/site-start.d)
    endif(ENABLE_SPIRV_TOOLS_INSTALL)
  endif()
endif()
```

--------------------------------

### Loop Optimization Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/README.txt

Illustrates loop optimization for finding the maximum element, showing generated assembly and areas for improvement.

```C
int winner, numf2s;
struct { double y; int   reset; } *Y;

void find_match() {
   int i;
   winner = 0;
   for (i=0;i<numf2s;i++)
       if (Y[i].y > Y[winner].y)
              winner =i;
}
```

```Assembly
for.body:                                         ; preds = %for.inc, %bb.nph
  %indvar = phi i64 [ 0, %bb.nph ], [ %indvar.next, %for.inc ]
  %i.01718 = phi i32 [ 0, %bb.nph ], [ %i.01719, %for.inc ]
  %tmp4 = getelementptr inbounds %struct.anon* %tmp3, i64 %indvar, i32 0
  %tmp5 = load double* %tmp4, align 8, !tbaa !4
  %idxprom7 = sext i32 %i.01718 to i64
  %tmp10 = getelementptr inbounds %struct.anon* %tmp3, i64 %idxprom7, i32 0
  %tmp11 = load double* %tmp10, align 8, !tbaa !4
  %cmp12 = fcmp ogt double %tmp5, %tmp11
  br i1 %cmp12, label %if.then, label %for.inc

if.then:                                          ; preds = %for.body
  %i.017 = trunc i64 %indvar to i32
  br label %for.inc

for.inc:                                          ; preds = %for.body, %if.then
  %i.01719 = phi i32 [ %i.01718, %for.body ], [ %i.017, %if.then ]
  %indvar.next = add i64 %indvar, 1
  %exitcond = icmp eq i64 %indvar.next, %tmp22
  br i1 %exitcond, label %for.cond.for.end_crit_edge, label %for.body
```

```Assembly
LBB0_2:                                 ## %for.body
                                        ## =>This Inner Loop Header: Depth=1
	movsd	(%rdi), %xmm0
	movslq	%edx, %r8
	shlq	$4, %r8
	ucomisd	(%rcx,%r8), %xmm0
	jbe	LBB0_4
	movl	%esi, %edx
LBB0_4:                                 ## %for.inc
	addq	$16, %rdi
	incq	%rsi
	cmpq	%rsi, %rax
	jne	LBB0_2
```

--------------------------------

### Install SPIRV-Tools Targets and Configuration

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/source/CMakeLists.txt

Configures the installation of SPIRV-Tools targets, including shared and static libraries, and generates CMake configuration files for package management. It handles mimalloc linking for installation.

```cmake
if(ENABLE_SPIRV_TOOLS_INSTALL)
  if (SPIRV_TOOLS_USE_MIMALLOC AND NOT SPIRV_TOOLS_BUILD_STATIC)
    list(APPEND SPIRV_TOOLS_TARGETS mimalloc-static)
  endif()
  install(TARGETS ${SPIRV_TOOLS_TARGETS} EXPORT ${SPIRV_TOOLS}Targets)
  export(EXPORT ${SPIRV_TOOLS}Targets FILE ${SPIRV_TOOLS}Target.cmake)

  spvtools_config_package_dir(${SPIRV_TOOLS} PACKAGE_DIR)
  install(EXPORT ${SPIRV_TOOLS}Targets FILE ${SPIRV_TOOLS}Target.cmake DESTINATION ${PACKAGE_DIR})

  # Special config file for root library compared to other libs.
  file(WRITE ${CMAKE_BINARY_DIR}/${SPIRV_TOOLS}Config.cmake
    "include(\\\${CMAKE_CURRENT_LIST_DIR}/${SPIRV_TOOLS}Target.cmake)\\n"
    "if(TARGET ${SPIRV_TOOLS})\\n"
    "    set(${SPIRV_TOOLS}_LIBRARIES ${SPIRV_TOOLS})\\n"
    "    get_target_property(${SPIRV_TOOLS}_INCLUDE_DIRS ${SPIRV_TOOLS} INTERFACE_INCLUDE_DIRECTORIES)\\n"
    "endif()\\n")
  install(FILES ${CMAKE_BINARY_DIR}/${SPIRV_TOOLS}Config.cmake DESTINATION ${PACKAGE_DIR})
endif(ENABLE_SPIRV_TOOLS_INSTALL)
```

--------------------------------

### Assembly Code Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/X86/README-SSE.txt

An example of assembly code with comments indicating line numbers and probabilities.

```assembly
negl	%ebx					#69.49
lea	-3(%edi,%ebx), %ebx			#70.33
shll	$4, %ebx					#68.37
addl	32(%ecx), %ebx				#68.37
testb	$15, %bl					#91.13
jne	L_B1.24 	# Prob 5%				#91.13
```

--------------------------------

### Install MARL Package

Source: https://github.com/google/swiftshader/blob/master/third_party/marl/CMakeLists.txt

Configures and installs the MARL library, headers, and CMake package configuration files.

```cmake
# install
if(MARL_INSTALL)
    include(CMakePackageConfigHelpers)
    include(GNUInstallDirs)

    configure_package_config_file(
        ${CMAKE_CURRENT_SOURCE_DIR}/cmake/marl-config.cmake.in
        ${CMAKE_CURRENT_BINARY_DIR}/marl-config.cmake
        INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/marl
    )

    install(DIRECTORY ${MARL_INCLUDE_DIR}/marl
        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
        USE_SOURCE_PERMISSIONS
    )

    install(TARGETS marl
        EXPORT marl-targets
        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
        INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
    )

    install(EXPORT marl-targets
        FILE marl-targets.cmake
        NAMESPACE marl::
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/marl
    )

    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/marl-config.cmake
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/marl
    )
endif(MARL_INSTALL)
```

--------------------------------

### Simplifying ICMP with Bitwise AND

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/README.txt

Demonstrates how certain bitwise AND and ICMP operations can be simplified. The first example can be folded to (x & 2) == 0, and the second to (x & 2) != 0.

```LLVM IR
define i1 @test1(i32 %x) nounwind {
  %and = and i32 %x, 3
  %cmp = icmp ult i32 %and, 2
  ret i1 %cmp
}

Can be folded to (x & 2) == 0.

define i1 @test2(i32 %x) nounwind {
  %and = and i32 %x, 3
  %cmp = icmp ugt i32 %and, 1
  ret i1 %cmp
}

Can be folded to (x & 2) != 0.
```

--------------------------------

### Build and Run SPEC2000 Benchmarks with AddressSanitizer

Source: https://github.com/google/swiftshader/blob/master/third_party/subzero/docs/ASAN.rst

Commands to build and run SPEC2000 benchmarks with Subzero and AddressSanitizer, including setup and execution steps.

```bash
cd native_client/tests/spec2k

```

```bash
./run_all.sh BuildBenchmarks 0 SetupPnaclX8632Opt <benchmarks>

```

```bash
../../toolchain_build/src/subzero/pydir/szbuild_spec2k.py -v -O2 \
    --fsanitize-address <benchmarks>

```

```bash
./run_all.sh RunTimedBenchmarks SetupGccX8632Opt train <benchmarks>

```

--------------------------------

### ARM Thumb Assembly Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/ARM/README-Thumb.txt

An example of Thumb assembly code, likely for testing or demonstration purposes.

```assembly
ldr r5, LCPI1_0
LPC0:
	add r5, pc
	ldr r6, LCPI1_1
	ldr r2, LCPI1_2
	mov r3, r6
	mov lr, pc
	bx r5
```

--------------------------------

### Immediate Materialization Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/ARM/README.txt

Demonstrates a technique for materializing a specific immediate value (0xffff8000) using a combination of 'mov' and 'sub' instructions.

```assembly
mov r9, #&3f8000
sub r9, r9, #&400000
```

--------------------------------

### Build and Install SPIR-V Language Server (Linux/macOS)

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/utils/vim/README.md

This script builds the SPIR-V Language Server and copies the necessary binaries and configuration files to /usr/local/bin. Ensure you are in the correct directory before running.

```bash
cd <spirv-tools dir>/utils/vscode
./build_lsp.sh
sudo cp spirvls/* /usr/local/bin/
```

--------------------------------

### Clone SwiftShader and Install Commit Hooks

Source: https://github.com/google/swiftshader/blob/master/docs/dEQP.md

Clones the SwiftShader repository and installs commit hooks for contributing to the project.

```bash
git clone https://swiftshader.googlesource.com/SwiftShader && (cd SwiftShader && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x `git rev-parse --git-dir`/hooks/commit-msg)
```

--------------------------------

### ARM Thumb Select Instruction Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/ARM/README-Thumb.txt

An example of Thumb select instructions used in code generation tests.

```assembly
	ldr r5, LCPI1_0
LPC0:
	add r5, pc
	ldr r6, LCPI1_1
	ldr r2, LCPI1_2
	mov r3, r6
	mov lr, pc
	bx r5
```

--------------------------------

### Example Bazel cc_library Target with SPIRV-Headers

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Headers/README.md

A sample Bazel cc_library definition demonstrating how to include SPIRV-Headers dependencies.

```bazel
cc_library(
  name = "project",
  srcs = [
    # Path to project sources
  ],
  hdrs = [
    # Path to project headers
  ],
  deps = [
    "@spirv_tools//:spirv_c_headers",
    # Other dependencies,
  ],
)
```

--------------------------------

### Equivalent Naive C++ Implementation

Source: https://github.com/google/swiftshader/blob/master/docs/Reactor.md

Illustrates a naive C++ implementation for comparison, highlighting potential code duplication and larger binary sizes when specializing for multiple state conditions.

```C++
int function(int *p, int n)
{
    int total = 0;

    if(state.operation == ADD)
    {
        for(int i = 0; i < n; i++)
        {
            total += p[i];
        }
    }
    else if(state.operation == SUBTRACT)
    {
        for(int i = 0; i < n; i++)
        {
            total -= p[i];
        }
    }
    else if(state.operation == AND)
    {
        for(int i = 0; i < n; i++)
        {
            total &= p[i];
        }
    }
    else if(...)
    {
        ...
    }

    return total;
}
```

--------------------------------

### Running the Subzero lit test suite

Source: https://github.com/google/swiftshader/blob/master/third_party/subzero/README.rst

Command to execute the Subzero test suite using the LLVM lit testing tool after building Subzero.

```bash
make -f Makefile.standalone check-lit
```

--------------------------------

### DILocation Hierarchy Example

Source: https://github.com/google/swiftshader/blob/master/docs/ReactorDebugInfo.md

Illustrates the hierarchical structure of DILocation objects, including inlined locations, for the first C++ example.

```C++
rr::DebugInfo::diRootLocation:      DILocation(DISubprogram: "ReactorFunction")
r::DebugInfo::diScope[0].location: ↳ DILocation(DISubprogram: "main")
r::DebugInfo::diScope[1].location:   ↳ DILocation(DISubprogram: "A")
r::DebugInfo::diScope[2].location:     ↳ DILocation(DISubprogram: "B")
```

--------------------------------

### DIScope Hierarchy Example

Source: https://github.com/google/swiftshader/blob/master/docs/ReactorDebugInfo.md

Shows the hierarchical structure of DIScope objects representing the call stack for the first C++ example.

```C++
                              DIFile: "foo.cpp"
r::DebugInfo::diScope[0].di: ↳ DISubprogram: "main"
r::DebugInfo::diScope[1].di: ↳ DISubprogram: "A"
r::DebugInfo::diScope[2].di: ↳ DISubprogram: "B"
```

--------------------------------

### Running pnacl-sz with an LLVM bitcode file

Source: https://github.com/google/swiftshader/blob/master/third_party/subzero/README.rst

Example of how to run the pnacl-sz tool to parse and translate an LLVM bitcode file.

```bash
../pnacl-sz ./tests_lit/pnacl-sz_tests/<file>.ll
```

--------------------------------

### Conditional Installation of SPIRV-Tools-opt

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/source/opt/CMakeLists.txt

Configures the installation of SPIRV-Tools-opt and related targets only if ENABLE_SPIRV_TOOLS_INSTALL is enabled. Includes mimalloc if specified and not building statically.

```cmake
if(ENABLE_SPIRV_TOOLS_INSTALL)
  set(SPIRV-Tools-opt-InstallTargets SPIRV-Tools-opt)

  if (SPIRV_TOOLS_USE_MIMALLOC AND NOT SPIRV_TOOLS_BUILD_STATIC)
    list(APPEND SPIRV-Tools-opt-InstallTargets mimalloc-static)
  endif()

  install(TARGETS ${SPIRV-Tools-opt-InstallTargets} EXPORT SPIRV-Tools-optTargets)
  export(EXPORT SPIRV-Tools-optTargets FILE SPIRV-Tools-optTargets.cmake)

  spvtools_config_package_dir(SPIRV-Tools-opt PACKAGE_DIR)
  install(EXPORT SPIRV-Tools-optTargets FILE SPIRV-Tools-optTargets.cmake
  	DESTINATION ${PACKAGE_DIR})

  spvtools_generate_config_file(SPIRV-Tools-opt)
  install(FILES ${CMAKE_BINARY_DIR}/SPIRV-Tools-optConfig.cmake DESTINATION ${PACKAGE_DIR})
endif(ENABLE_SPIRV_TOOLS_INSTALL)
```

--------------------------------

### llvm_blake3_hasher_init_derive_key

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Support/BLAKE3/README.md

Initializes a BLAKE3 hasher for key derivation using a provided context string. The context should be hardcoded, globally unique, and application-specific.

```APIDOC
## llvm_blake3_hasher_init_derive_key

### Description
Initializes a `llvm_blake3_hasher` in the key derivation mode. The context string is given as an initialization parameter, and afterwards input key material should be given with `llvm_blake3_hasher_update`. The context string is a null-terminated C string which should be **hardcoded, globally unique, and application-specific**.

### Function Signature
```c
void llvm_blake3_hasher_init_derive_key(
  llvm_blake3_hasher *self,
  const char *context);
```
```

--------------------------------

### Initialize BLAKE3 Hasher for Key Derivation (Raw Bytes Context)

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Support/BLAKE3/README.md

Initializes a BLAKE3 hasher for key derivation using a pointer to an array of arbitrary bytes and its length. This is intended for language bindings and Unicode strings should be UTF-8 encoded.

```c
void llvm_blake3_hasher_init_derive_key_raw(
  llvm_blake3_hasher *self,
  const void *context,
  size_t context_len);
```

--------------------------------

### Optimized C++ SSE Intrinsics Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/X86/README-SSE.txt

The optimized assembly output for the _mm_set_ps example, showing fewer instructions due to pre-zeroed operands.

```assembly
movss 4(%esp), %xmm1
mulss %xmm1, %xmm1
xorps %xmm0, %xmm0
movss %xmm1, %xmm0
ret
```

--------------------------------

### llvm_blake3_hasher_init_keyed

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Support/BLAKE3/README.md

Initializes a BLAKE3 hasher in keyed hashing mode. Requires a 32-byte key.

```APIDOC
## llvm_blake3_hasher_init_keyed

### Description
Initializes a `llvm_blake3_hasher` in the keyed hashing mode. The key must be exactly 32 bytes.

### Function Signature
```c
void llvm_blake3_hasher_init_keyed(
  llvm_blake3_hasher *self,
  const uint8_t key[LLVM_BLAKE3_KEY_LEN]);
```
```

--------------------------------

### Instruction Scheduling Example: memset Sequence

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/CodeGen/README.txt

Illustrates a sequence of independent stores that the scheduler can reorder by address. This is an example of code that can be optimized by the instruction scheduler.

```Assembly
movl $0, 4(%rdi)
movl $0, 8(%rdi)
movl $0, 12(%rdi)
movl $0, 0(%rdi)
```

--------------------------------

### Run dEQP-VK Tests from Command Line

Source: https://github.com/google/swiftshader/blob/master/docs/dEQP.md

Executes Vulkan tests using the deqp-vk executable. This command will stop on the first failure.

```bash
external/vulkanacts/modules/vulkan/deqp-vk
```

--------------------------------

### Reassociate for GCC PR16157 Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/README.txt

Implement reassociation to handle patterns where expressions can be simplified by reordering operations. This example demonstrates a series of dependent additions that can be optimized.

```C++
extern int a0, a1, a2, a3, a4; extern int b0, b1, b2, b3, b4; 
void f () {  /* this can be optimized to four additions... */ 
        b4 = a4 + a3 + a2 + a1 + a0; 
        b3 = a3 + a2 + a1 + a0;
        b2 = a2 + a1 + a0;
        b1 = a1 + a0;
}
```

--------------------------------

### Initialize Benchmark Submodule

Source: https://github.com/google/swiftshader/blob/master/CMakeLists.txt

Initializes the `benchmark::benchmark` submodule if `SWIFTSHADER_BUILD_BENCHMARKS` is enabled.

```cmake
if(SWIFTSHADER_BUILD_BENCHMARKS)
    InitSubmodule(benchmark::benchmark ${THIRD_PARTY_DIR}/benchmark)
endif()
```

--------------------------------

### Install Gerrit Commit Hook

Source: https://github.com/google/swiftshader/blob/master/CMakeLists.txt

Installs the commit-msg hook for Gerrit if it's not already present. Downloads the hook from a specified URL and sets appropriate file permissions.

```cmake
if(IS_DIRECTORY ${CMAKE_SOURCE_DIR}/.git AND NOT EXISTS ${CMAKE_SOURCE_DIR}/.git/hooks/commit-msg)
    message(WARNING "
        .git/hooks/commit-msg was not found.
        Downloading from https://gerrit-review.googlesource.com/tools/hooks/commit-msg...
    ")

    file(DOWNLOAD https://gerrit-review.googlesource.com/tools/hooks/commit-msg ${CMAKE_SOURCE_DIR}/commit-msg)

    file(COPY ${CMAKE_SOURCE_DIR}/commit-msg
         DESTINATION ${CMAKE_SOURCE_DIR}/.git/hooks/
         FILE_PERMISSIONS
           OWNER_READ OWNER_WRITE OWNER_EXECUTE
           GROUP_READ GROUP_WRITE GROUP_EXECUTE
           WORLD_READ WORLD_EXECUTE)
    file(REMOVE ${CMAKE_SOURCE_DIR}/commit-msg)
endif()
```

--------------------------------

### Marl Scheduler Example

Source: https://github.com/google/swiftshader/blob/master/third_party/marl/README.md

Demonstrates creating a scheduler, binding it to the main thread, and using marl::schedule() to run asynchronous tasks. It utilizes marl::Event and marl::WaitGroup for task synchronization.

```cpp
#include "marl/defer.h"
#include "marl/event.h"
#include "marl/scheduler.h"
#include "marl/waitgroup.h"

#include <cstdio>

int main() {
  // Create a marl scheduler using all the logical processors available to the process.
  // Bind this scheduler to the main thread so we can call marl::schedule()
  marl::Scheduler scheduler(marl::Scheduler::Config::allCores());
  scheduler.bind();
  defer(scheduler.unbind());  // Automatically unbind before returning.

  constexpr int numTasks = 10;

  // Create an event that is manually reset.
  marl::Event sayHello(marl::Event::Mode::Manual);

  // Create a WaitGroup with an initial count of numTasks.
  marl::WaitGroup saidHello(numTasks);

  // Schedule some tasks to run asynchronously.
  for (int i = 0; i < numTasks; i++) {
    // Each task will run on one of the 4 worker threads.
    marl::schedule([=] {  // All marl primitives are capture-by-value.
      // Decrement the WaitGroup counter when the task has finished.
      defer(saidHello.done());

      printf("Task %d waiting to say hello...\n", i);

      // Blocking in a task?
      // The scheduler will find something else for this thread to do.
      sayHello.wait();

      printf("Hello from task %d!\n", i);
    });
  }

  sayHello.signal();  // Unblock all the tasks.

  saidHello.wait();  // Wait for all tasks to complete.

  printf("All tasks said hello.\n");

  // All tasks are guaranteed to complete before the scheduler is destructed.
}

```

--------------------------------

### Scanf Modulo/Ref Analysis Example (C++)

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/README.txt

An example illustrating potential optimizations for scanf with structures, highlighting the need for better mod/ref analysis to eliminate vtable overhead.

```c++
#include <cstdio>
struct test {
    int val;
    virtual ~test() {}
};

int main() {
    test t;
    std::scanf("%d", &t.val);
    std::printf("%d\n", t.val);
}
```

--------------------------------

### Basic Phi Lowering Example

Source: https://github.com/google/swiftshader/blob/master/third_party/subzero/DESIGN.rst

Demonstrates a simple strategy for lowering phi instructions, commonly used in LLVM's -O0 optimization level. It involves creating temporaries and assigning values in predecessor blocks.

```pseudocode
L1:
  ...
  br L3
L2:
  ...
  br L3
L3:
  A = phi [B, L1], [C, L2]
  X = phi [Y, L1], [Z, L2]
```

```pseudocode
L1:
  ...
  A' = B
  X' = Y
  br L3
L2:
  ...
  A' = C
  X' = Z
  br L3
L2:
  A = A'
  X = X'
```

--------------------------------

### llvm_blake3_hasher_init_derive_key_raw

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Support/BLAKE3/README.md

Initializes a BLAKE3 hasher for key derivation using raw byte context. Suitable for language bindings where C string conversion is not desired.

```APIDOC
## llvm_blake3_hasher_init_derive_key_raw

### Description
As `llvm_blake3_hasher_init_derive_key` above, except that the context string is given as a pointer to an array of arbitrary bytes with a provided length. This is intended for writing language bindings, where C string conversion would add unnecessary overhead and new error cases. Unicode strings should be encoded as UTF-8.

### Function Signature
```c
void llvm_blake3_hasher_init_derive_key_raw(
  llvm_blake3_hasher *self,
  const void *context,
  size_t context_len);
```
```

--------------------------------

### Enable Emacs Helper Installation with CMake

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/README.md

Configure the build system to install the Emacs helper for automatic disassembly and reassembly of .spv files. This requires defining a CMake symbol.

```shell
cmake -DSPIRV_TOOLS_INSTALL_EMACS_HELPERS=true ...
```

--------------------------------

### WebAssembly Stackify Optimization Example

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-16.0/llvm/lib/Target/WebAssembly/README.txt

Illustrates a potential issue in WebAssembly register stackification where a binary operator might stackify with its user before its operands, leading to suboptimal register allocation. This highlights the need for more sophisticated scheduling.

```text
global.get  $push8=, 0
local.tee   $push9=, 1, $pop8
drop        $pop9
[...]
```

--------------------------------

### Range Comparison with Truncation on 64-bit (LLVM IR)

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/Target/README.txt

This LLVM IR example shows a range comparison involving division and truncation on a 64-bit target, highlighting a potential optimization.

```llvm
%361 = sdiv i64 %.046, 8                        ; [#uses=1]
%362 = trunc i64 %361 to i32                    ; [#uses=2]
...
%367 = icmp eq i32 %362, 0                      ; [#uses=1]
```

--------------------------------

### Install SPIRV-Tools Linker Library and Config Files

Source: https://github.com/google/swiftshader/blob/master/third_party/SPIRV-Tools/source/link/CMakeLists.txt

Conditionally installs the SPIRV-Tools-link library, export targets, and configuration files if ENABLE_SPIRV_TOOLS_INSTALL is set. This makes the library available for external projects.

```cmake
if(ENABLE_SPIRV_TOOLS_INSTALL)
  install(TARGETS SPIRV-Tools-link EXPORT SPIRV-Tools-linkTargets)
  export(EXPORT SPIRV-Tools-linkTargets FILE SPIRV-Tools-linkTargets.cmake)

  spvtools_config_package_dir(SPIRV-Tools-link PACKAGE_DIR)
  install(EXPORT SPIRV-Tools-linkTargets FILE SPIRV-Tools-linkTargets.cmake
  	DESTINATION ${PACKAGE_DIR})

  spvtools_generate_config_file(SPIRV-Tools-link)
  install(FILES ${CMAKE_BINARY_DIR}/SPIRV-Tools-linkConfig.cmake DESTINATION ${PACKAGE_DIR})
endif(ENABLE_SPIRV_TOOLS_INSTALL)
```

--------------------------------

### Install SwiftShader Git Hooks

Source: https://github.com/google/swiftshader/blob/master/README.md

Clone the SwiftShader repository and install Git commit hooks to automatically add the required Change-ID tag to commit messages. This is necessary for contributing changes.

```bash
git clone https://swiftshader.googlesource.com/SwiftShader && (cd SwiftShader && git submodule update --init --recursive third_party/git-hooks && ./third_party/git-hooks/install_hooks.sh)
```

--------------------------------

### Standalone Build Configurations

Source: https://github.com/google/swiftshader/blob/master/third_party/subzero/docs/README.rst

Build Subzero using the standalone Makefile with various configurations for debugging, performance, or size optimization. ASAN and TSAN enable sanitizers.

```makefile
make -f Makefile.standalone
make -f Makefile.standalone DEBUG=1
make -f Makefile.standalone NOASSERT=1
make -f Makefile.standalone DEBUG=1 NOASSERT=1
make -f Makefile.standalone MINIMAL=1
make -f Makefile.standalone ASAN=1
make -f Makefile.standalone TSAN=1
```

--------------------------------

### LLVM OProfileJIT CMakeLists.txt Configuration

Source: https://github.com/google/swiftshader/blob/master/third_party/llvm-10.0/llvm/lib/ExecutionEngine/OProfileJIT/CMakeLists.txt

Configures include directories and defines the LLVM OProfileJIT library using CMake.

```cmake
include_directories( ${LLVM_OPROFILE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/.. )

add_llvm_component_library(LLVMOProfileJIT
  OProfileJITEventListener.cpp
  OProfileWrapper.cpp
  )
```

--------------------------------

### Build Executable with szbuild_spec2k.py

Source: https://github.com/google/swiftshader/blob/master/third_party/subzero/README.rst

Use the szbuild_spec2k.py script to run szbuild.py on Spec2K components. Assumes Spec2K is set up and pexes are finalized.

```bash
pydir/szbuild_spec2k.py
```