diff options
Diffstat (limited to 'doc/zjit.md')
| -rw-r--r-- | doc/zjit.md | 133 |
1 files changed, 0 insertions, 133 deletions
diff --git a/doc/zjit.md b/doc/zjit.md deleted file mode 100644 index 90f890bfa0..0000000000 --- a/doc/zjit.md +++ /dev/null @@ -1,133 +0,0 @@ -# ZJIT: ADVANCED RUBY JIT PROTOTYPE - -## Build Instructions - -To build ZJIT on macOS: -``` -./autogen.sh -./configure --enable-zjit=dev --prefix=$HOME/.rubies/ruby-zjit --disable-install-doc --with-opt-dir="$(brew --prefix openssl):$(brew --prefix readline):$(brew --prefix libyaml)" -make -j miniruby -``` - -## Useful dev commands - -To view YARV output for code snippets: -``` -./miniruby --dump=insns -e0 -``` - -To run code snippets with ZJIT: -``` -./miniruby --zjit -e0 -``` - -You can also try https://www.rubyexplorer.xyz/ to view Ruby YARV disasm output with syntax highlighting -in a way that can be easily shared with other team members. - -## Testing - -Make sure you have a `--enable-zjit=dev` build, and run `brew install cargo-nextest` first. - -### make zjit-check - -This command runs all ZJIT tests: `make zjit-test` and `test/ruby/test_zjit.rb`. - -``` -make zjit-check -``` - -### make zjit-test - -This command runs Rust unit tests. - -``` -make zjit-test -``` - -You can also run a single test case by specifying the function name: - -``` -make zjit-test ZJIT_TESTS=test_putobject -``` - -If you expect that your changes cause tests to fail and they do, you can have -`expect-test` fix the expected value for you by putting `UPDATE_EXPECT=1` -before your test command, like so: - -``` -UPDATE_EXPECT=1 make zjit-test ZJIT_TESTS=test_putobject -``` - -Test changes will be reviewed alongside code changes. - -<details> - -<summary>Setting up zjit-test</summary> - -ZJIT uses `cargo-nextest` for Rust unit tests instead of `cargo test`. -`cargo-nextest` runs each test in its own process, which is valuable since -CRuby only supports booting once per process, and most APIs are not thread -safe. Use `brew install cargo-nextest` to install it on macOS, otherwise, refer -to <https://nexte.st/docs/installation/pre-built-binaries/> for installation -instructions. - -Since it uses Cargo, you'll also need a `configure --enable-zjit=dev ...` build -for `make zjit-test`. Since the tests need to link against CRuby, directly -calling `cargo test`, or `cargo nextest` likely won't build. Make sure to -use `make`. - -</details> - -### make zjit-test-all - -``` -make zjit-test-all -``` - -This command runs all Ruby tests under `/test/ruby/` with ZJIT enabled. - -Certain tests are excluded under `/test/.excludes-zjit`. - -### test/ruby/test\_zjit.rb - -This command runs Ruby execution tests. - -``` -make test-all TESTS="test/ruby/test_zjit.rb" -``` - -You can also run a single test case by matching the method name: - -``` -make test-all TESTS="test/ruby/test_zjit.rb -n TestZJIT#test_putobject" -``` - -## ZJIT Glossary - -This glossary contains terms that are helpful for understanding ZJIT. - -Please note that some terms may appear in CRuby internals too but with different meanings. - -| Term | Definition | -| --- | -----------| -| HIR | High-level Intermediate Representation. High-level (Ruby semantics) graph representation in static single-assignment (SSA) form | -| LIR | Low-level Intermediate Representation. Low-level IR used in the backend for assembly generation | -| SSA | Static Single Assignment. A form where each variable is assigned exactly once | -| `opnd` | Operand. An operand to an IR instruction (can be register, memory, immediate, etc.) | -| `dst` | Destination. The output operand of an instruction where the result is stored | -| VReg | Virtual Register. A virtual register that gets lowered to physical register or memory | -| `insn_id` | Instruction ID. An index of an instruction in a function | -| `block_id` | The index of a basic block, which effectively acts like a pointer | -| `branch` | Control flow edge between basic blocks in the compiled code | -| `cb` | Code Block. Memory region for generated machine code | -| `entry` | The starting address of compiled code for an ISEQ | -| Patch Point | Location in generated code that can be modified later in case assumptions get invalidated | -| Frame State | Captured state of the Ruby stack frame at a specific point for deoptimization | -| Guard | A run-time check that ensures assumptions are still valid | -| `invariant` | An assumption that JIT code relies on, requiring invalidation if broken | -| Deopt | Deoptimization. Process of falling back from JIT code to interpreter | -| Side Exit | Exit from JIT code back to interpreter | -| Type Lattice | Hierarchy of types used for type inference and optimization | -| Constant Folding | Optimization that evaluates constant expressions at compile time | -| RSP | x86-64 stack pointer register used for native stack operations | -| Register Spilling | Process of moving register values to memory when running out of physical registers | |