Skip to content

Commit 750c750

Browse files
authored
[DOC] ZJIT: Add documentation about native stack and Ruby's VM stack (#14993)
ZJIT: Add documentation about native stack and Ruby's VM stack
1 parent b8c82a9 commit 750c750

File tree

1 file changed

+27
-0
lines changed

1 file changed

+27
-0
lines changed

doc/zjit.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,33 @@ To run code snippets with ZJIT:
189189
You can also try https://www.rubyexplorer.xyz/ to view Ruby YARV disasm output with syntax highlighting
190190
in a way that can be easily shared with other team members.
191191

192+
## Understanding Ruby Stacks
193+
194+
Ruby execution involves three distinct stacks and understanding them will help you understand ZJIT's implementation:
195+
196+
### 1. Native Stack
197+
198+
- **Purpose**: Return addresses and saved registers. ZJIT also uses it for some C functions' argument arrays
199+
- **Management**: OS-managed, one per native thread
200+
- **Growth**: Downward from high addresses
201+
- **Constants**: `NATIVE_STACK_PTR`, `NATIVE_BASE_PTR`
202+
203+
### 2. Ruby VM Stack
204+
205+
The Ruby VM uses a single contiguous memory region (`ec->vm_stack`) containing two sub-stacks that grow toward each other. When they meet, stack overflow occurs.
206+
207+
**Control Frame Stack:**
208+
209+
- **Stores**: Frame metadata (`rb_control_frame_t` structures)
210+
- **Growth**: Downward from `vm_stack + size` (high addresses)
211+
- **Constants**: `CFP`
212+
213+
**Value Stack:**
214+
215+
- **Stores**: YARV bytecode operands (self, arguments, locals, temporaries)
216+
- **Growth**: Upward from `vm_stack` (low addresses)
217+
- **Constants**: `SP`
218+
192219
## ZJIT Glossary
193220

194221
This glossary contains terms that are helpful for understanding ZJIT.

0 commit comments

Comments
 (0)