beam_spy

#
# %CopyrightBegin%
#
# SPDX-License-Identifier: Apache-2.0
#
# Copyright Ericsson AB 1998-2025. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# %CopyrightEnd%
#
BEAM_FORMAT_NUMBER=0

#
# Generic instructions, generated by the compiler.  If any of them change number,
# arity or semantics, the format number above must be bumped.
#

## @spec label Lbl
## @doc Specify a module local label.
##      Label gives this code address a name (Lbl) and marks the start of
##      a basic block.
1: label/1

## @spec func_info M F A
## @doc Define a function M:F/A
2: func_info/3

3: int_code_end/0

#
# Function and BIF calls.
#

## @spec call Arity Label
## @doc Call the function at Label.
##      Save the next instruction as the return address in the CP register.
4: call/2

## @spec call_last Arity Label Deallocate
## @doc Deallocate and do a tail recursive call to the function at Label.
##      Do not update the CP register.
##      Before the call deallocate Deallocate words of stack.
5: call_last/3

## @spec call_only Arity Label
## @doc Do a tail recursive call to the function at Label.
##      Do not update the CP register.
6: call_only/2

## @spec call_ext Arity Destination
## @doc Call the function of arity Arity pointed to by Destination.
##      Save the next instruction as the return address in the CP register.
7: call_ext/2

## @spec call_ext_last Arity Destination Deallocate
## @doc Deallocate and do a tail call to function of arity Arity
##      pointed to by Destination.
##      Do not update the CP register.
##      Deallocate Deallocate words from the stack before the call.
8: call_ext_last/3

## @spec bif0 Bif Reg
## @doc Call the bif Bif and store the result in Reg.
9: bif0/2

## @spec bif1 Lbl Bif Arg Reg
## @doc Call the bif Bif with the argument Arg, and store the result in Reg.
##      On failure jump to Lbl.
10: bif1/4

## @spec bif2 Lbl Bif Arg1 Arg2 Reg
## @doc Call the bif Bif with the arguments Arg1 and Arg2,
##      and store the result in Reg.
##      On failure jump to Lbl.
11: bif2/5

#
# Allocating, deallocating and returning.
#

## @spec allocate StackNeed Live
## @doc Allocate space for StackNeed words on the stack. If a GC is needed
##      during allocation there are Live number of live X registers.
##      Also save the continuation pointer (CP) on the stack.
12: allocate/2

## @spec allocate_heap StackNeed HeapNeed Live
## @doc Allocate space for StackNeed words on the stack and ensure there is
##      space for HeapNeed words on the heap. If a GC is needed
##      save Live number of X registers.
##      Also save the continuation pointer (CP) on the stack.
13: allocate_heap/3

## @spec allocate_zero StackNeed Live
## @doc Allocate space for StackNeed words on the stack. If a GC is needed
##      during allocation there are Live number of live X registers.
##      Clear the new stack words. (By writing NIL.)
##      Also save the continuation pointer (CP) on the stack.
##
##      OTP 24: This instruction has been superseded by allocate/2 followed
##      by init_yregs/1.
14: -allocate_zero/2

## @spec allocate_heap_zero StackNeed HeapNeed Live
## @doc Allocate space for StackNeed words on the stack and HeapNeed words
##      on the heap. If a GC is needed
##      during allocation there are Live number of live X registers.
##      Clear the new stack words. (By writing NIL.)
##      Also save the continuation pointer (CP) on the stack.
##
##      OTP 24: This instruction has been superseded by allocate_heap/2
##      followed by init_yregs/1.
15: -allocate_heap_zero/3

## @spec test_heap HeapNeed Live
## @doc Ensure there is space for HeapNeed words on the heap. If a GC is needed
##      save Live number of X registers.
16: test_heap/2

## @spec init N
## @doc  Clear the Nth stack word. (By writing NIL.)
##
##       OTP 24: This instruction has been superseded by init_yregs/1.
17: -init/1

## @spec deallocate N
## @doc  Restore the continuation pointer (CP) from the stack and deallocate
##       N+1 words from the stack (the + 1 is for the CP).
18: deallocate/1

## @spec return
## @doc  Return to the address in the continuation pointer (CP).
19: return/0

#
# Sending & receiving.
#
## @spec send
## @doc  Send argument in x(1) as a message to the destination process in x(0).
##       The message in x(1) ends up as the result of the send in x(0).
20: send/0

## @spec remove_message
## @doc  Unlink the current message from the message queue. Remove any timeout.
21: remove_message/0

## @spec timeout
## @doc  Reset the save point of the mailbox and clear the timeout flag.
22: timeout/0

## @spec loop_rec Label Source
## @doc  Loop over the message queue, if it is empty jump to Label.
23: loop_rec/2

## @spec loop_rec_end Label
## @doc  Advance the save pointer to the next message and jump back to Label.
24: loop_rec_end/1

## @spec wait Label
## @doc  Suspend the processes and set the entry point to the beginning of the
##       receive loop at Label.
25: wait/1

## @spec wait_timeout Label Time
## @doc  Sets up a timeout of Time milliseconds and saves the address of the
##       following instruction as the entry point if the timeout triggers.
26: wait_timeout/2

#
# Arithmetic opcodes.
#
27: -m_plus/4
28: -m_minus/4
29: -m_times/4
30: -m_div/4
31: -int_div/4
32: -int_rem/4
33: -int_band/4
34: -int_bor/4
35: -int_bxor/4
36: -int_bsl/4
37: -int_bsr/4
38: -int_bnot/3

#
# Comparison operators.
#

## @spec is_lt Lbl Arg1 Arg2
## @doc Compare two terms and jump to Lbl if Arg1 is not less than Arg2.
39: is_lt/3

## @spec is_ge Lbl Arg1 Arg2
## @doc Compare two terms and jump to Lbl if Arg1 is less than Arg2.
40: is_ge/3

## @spec is_eq Lbl Arg1 Arg2
## @doc Compare two terms and jump to Lbl if Arg1 is not (numerically) equal to Arg2.
41: is_eq/3

## @spec is_ne Lbl Arg1 Arg2
## @doc Compare two terms and jump to Lbl if Arg1 is (numerically) equal to Arg2.
42: is_ne/3

## @spec is_eq_exact Lbl Arg1 Arg2
## @doc Compare two terms and jump to Lbl if Arg1 is not exactly equal to Arg2.
43: is_eq_exact/3

## @spec is_ne_exact Lbl Arg1 Arg2
## @doc Compare two terms and jump to Lbl if Arg1 is exactly equal to Arg2.
44: is_ne_exact/3

#
# Type tests.
#

## @spec is_integer Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not an integer.
45: is_integer/2

## @spec is_float Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a float.
46: is_float/2

## @spec is_number Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a number.
47: is_number/2

## @spec is_atom Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not an atom.
48: is_atom/2

## @spec is_pid Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a pid.
49: is_pid/2

## @spec is_reference Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a reference.
50: is_reference/2

## @spec is_port Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a port.
51: is_port/2

## @spec is_nil Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not nil.
52: is_nil/2

## @spec is_binary Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a binary.
53: is_binary/2

54: -is_constant/2

## @spec is_list Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a cons or nil.
55: is_list/2

## @spec is_nonempty_list Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a cons.
56: is_nonempty_list/2

## @spec is_tuple Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a tuple.
57: is_tuple/2

## @spec test_arity Lbl Arg1 Arity
## @doc Test the arity of (the tuple in) Arg1 and jump
## to Lbl if it is not equal to Arity.
58: test_arity/3

#
# Indexing & jumping.
#

## @spec select_val Arg FailLabel Destinations
## @doc Jump to the destination label corresponding to Arg
##      in the Destinations list, if no arity matches, jump to FailLabel.
59: select_val/3

## @spec select_tuple_arity Tuple FailLabel Destinations
## @doc Check the arity of the tuple Tuple and jump to the corresponding
##      destination label, if no arity matches, jump to FailLabel.
60: select_tuple_arity/3

## @spec jump Label
## @doc Jump to Label.
61: jump/1

#
# Catch.
#
62: catch/2
63: catch_end/1

#
# Moving, extracting, modifying.
#

## @spec move Source Destination
## @doc Move the source Source (a literal or a register) to
##      the destination register Destination.
64: move/2

## @spec get_list  Source Head Tail
## @doc  Get the head and tail (or car and cdr) parts of a list
##       (a cons cell) from Source and put them into the registers
##       Head and Tail.
65: get_list/3

## @spec get_tuple_element Source Element Destination
## @doc  Get element number Element from the tuple in Source and put
##       it in the destination register Destination.
66: get_tuple_element/3

## @spec set_tuple_element NewElement Tuple Position
## @doc  Update the element at position Position of the tuple Tuple
##       with the new element NewElement.
##
##       TODO: As of Erlang/OTP 29, this instruction is no longer emitted
##       by the compiler.
67: set_tuple_element/3

#
# Building terms.
#
68: -put_string/3
69: put_list/3
70: -put_tuple/2
71: -put/1

#
# Raising errors.
#
72: badmatch/1
73: if_end/0
74: case_end/1

#
# 'fun' support.
#
## @spec call_fun Arity
## @doc Call a fun of arity Arity. Assume arguments in
##      registers x(0) to x(Arity-1) and that the fun is in x(Arity).
##      Save the next instruction as the return address in the CP register.
75: call_fun/1

76: -make_fun/3

## @spec is_function Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a
##      function (i.e. fun or closure).
77: is_function/2

#
# Late additions to R5.
#

## @spec call_ext_only Arity Label
##      Do a tail recursive call to the function at Label.
##      Do not update the CP register.
78: call_ext_only/2

#
# Binary matching (R7).
#
79: -bs_start_match/2
80: -bs_get_integer/5
81: -bs_get_float/5
82: -bs_get_binary/5
83: -bs_skip_bits/4
84: -bs_test_tail/2
85: -bs_save/1
86: -bs_restore/1

#
# Binary construction (R7A).
#
87: -bs_init/2
88: -bs_final/2
89: -bs_put_integer/5
90: -bs_put_binary/5
91: -bs_put_float/5
92: -bs_put_string/2

#
# Binary construction (R7B).
#
93: -bs_need_buf/1

#
# Floating point arithmetic (R8).
#
# The fclearerror and fcheckerror instructions are not used in OTP 24
# and later.
#
94: -fclearerror/0
95: -fcheckerror/1
96: fmove/2
97: fconv/2
98: fadd/4
99: fsub/4
100: fmul/4
101: fdiv/4
102: fnegate/3

# New fun construction (R8).
103: -make_fun2/1

# Try/catch/raise (R10B).
104: try/2
105: try_end/1
106: try_case/1
107: try_case_end/1
108: raise/2

# New instructions in R10B.
109: -bs_init2/6
110: -bs_bits_to_bytes/3
111: -bs_add/5
112: apply/1
113: apply_last/2
## @spec is_boolean Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a Boolean.
114: is_boolean/2

# New instructions in R10B-6.
## @spec is_function2 Lbl Arg1 Arity
## @doc Test the type of Arg1 and jump to Lbl if it is not a
##      function of arity Arity.
115: is_function2/3

# New bit syntax matching in R11B.

116: -bs_start_match2/5
117: bs_get_integer2/7
118: bs_get_float2/7
119: bs_get_binary2/7
120: bs_skip_bits2/5
121: bs_test_tail2/3
122: -bs_save2/2
123: -bs_restore2/2

# New GC bifs introduced in R11B.

## @spec gc_bif1 Lbl Live Bif Arg Reg
## @doc Call the bif Bif with the argument Arg, and store the result in Reg.
##      On failure jump to Lbl.
##      Do a garbage collection if necessary to allocate space on the heap
##      for the result (saving Live number of X registers).
124: gc_bif1/5

## @spec gc_bif2 Lbl Live Bif Arg1 Arg2 Reg
## @doc Call the bif Bif with the arguments Arg1 and Arg2,
##      and store the result in Reg.
##      On failure jump to Lbl.
##      Do a garbage collection if necessary to allocate space on the heap
##      for the result (saving Live number of X registers).
125: gc_bif2/6

# Experimental new bit_level bifs introduced in R11B.
# NOT used in R12B.
126: -bs_final2/2
127: -bs_bits_to_bytes2/2

# R11B-4
128: -put_literal/2

# R11B-5
## @spec is_bitstr Lbl Arg1
## @doc Test the type of Arg1 and jump to Lbl if it is not a bit string.
129: is_bitstr/2

# R12B
130: -bs_context_to_binary/1
131: bs_test_unit/3
132: bs_match_string/4
133: bs_init_writable/0
134: -bs_append/8
135: -bs_private_append/6

## @spec trim N Remaining
## @doc Reduce the stack usage by N words,
##      keeping the CP on the top of the stack.
136: trim/2

137: -bs_init_bits/6

# R12B-5
138: bs_get_utf8/5
139: bs_skip_utf8/4

140: bs_get_utf16/5
141: bs_skip_utf16/4

142: bs_get_utf32/5
143: bs_skip_utf32/4

144: -bs_utf8_size/3
145: -bs_put_utf8/3

146: -bs_utf16_size/3
147: -bs_put_utf16/3

148: -bs_put_utf32/3

# R13B03

149: on_load/0

# R14A

150: -recv_mark/1
151: -recv_set/1

## @spec gc_bif3 Lbl Live Bif Arg1 Arg2 Arg3 Reg
## @doc Call the bif Bif with the arguments Arg1, Arg2 and Arg3,
##      and store the result in Reg.
##      On failure jump to Lbl.
##      Do a garbage collection if necessary to allocate space on the heap
##      for the result (saving Live number of X registers).
152: gc_bif3/7

# R15A

153: line/1

# R17

154: put_map_assoc/5
155: put_map_exact/5
156: is_map/2
157: has_map_fields/3
158: get_map_elements/3

# OTP 20

## @spec is_tagged_tuple Lbl Reg N Atom
## @doc Test the type of Reg and jumps to Lbl if it is not a tuple.
##      Test the arity of Reg and jumps to Lbl if it is not N.
##      Test the first element of the tuple and jumps to Lbl if it is not Atom.
159: is_tagged_tuple/4

# OTP 21

## @spec build_stacktrace
## @doc  Given the raw stacktrace in x(0), build a cooked stacktrace suitable
##       for human consumption. Store it in x(0). Destroys all other registers.
##       Do a garbage collection if necessary to allocate space on the heap
##       for the result.
160: build_stacktrace/0

## @spec raw_raise
## @doc  This instruction works like the erlang:raise/3 BIF, except that the
##       stacktrace in x(2) must be a raw stacktrace.
##       x(0) is the class of the exception (error, exit, or throw),
##       x(1) is the exception term, and x(2) is the raw stackframe.
##       If x(0) is not a valid class, the instruction will not throw an
##       exception, but store the atom 'badarg' in x(0) and execute the
##       next instruction.
161: raw_raise/0

## @spec get_hd  Source Head
## @doc  Get the head (or car) part of a list (a cons cell) from Source and
##       put it into the register Head.
162: get_hd/2

## @spec get_tl  Source Tail
## @doc  Get the tail (or cdr) part of a list (a cons cell) from Source and
##       put it into the register Tail.
163: get_tl/2

# OTP 22

## @spec put_tuple2  Destination Elements
## @doc  Build a tuple with the elements in the list Elements and put it
##       into register Destination.
164: put_tuple2/2

## @spec bs_get_tail Ctx Dst Live
## @doc  Sets Dst to the tail of Ctx at the current position
165: bs_get_tail/3

## @spec bs_start_match3 Fail Bin Live Dst
## @doc  Starts a binary match sequence
166: bs_start_match3/4

## @spec bs_get_position Ctx Dst Live
## @doc  Sets Dst to the current position of Ctx
167: bs_get_position/3

## @spec bs_set_positon Ctx Pos
## @doc  Sets the current position of Ctx to Pos
168: bs_set_position/2

# OTP 23

## @spec swap Register1 Register2
## @doc  Swaps the contents of two registers.
169: swap/2

## @spec bs_start_match4 Fail Bin Live Dst
## @doc  As bs_start_match3, but the fail label can be 'no_fail' when we know
##       it will never fail at runtime, or 'resume' when we know the input is
##       a match context.
170: bs_start_match4/4

# OTP 24

## @spec make_fun3 OldIndex Dst EnvTerms
## @doc  Build a fun with the environment in the list EnvTerms and put it
##       into register Dst.
171: make_fun3/3

## @spec init_yregs ListOfYRegs
## @doc  Initialize the Y registers in the list.
172: init_yregs/1

## @spec recv_marker_bind Marker Reference
## @doc  Associates Reference with a previously reserved marker.
173: recv_marker_bind/2

## @spec recv_marker_clear Reference
## @doc  Clears the receive marker associated with the given Reference.
174: recv_marker_clear/1

## @spec recv_marker_reserve Marker
## @doc  Creates a receive marker which can be later bound to a reference.
175: recv_marker_reserve/1

## @spec recv_marker_use Reference
## @doc  Sets the current receive cursor to the marker associated with
##       the given Reference.
176: recv_marker_use/1

# OTP 25

## @spec bs_create_bin Fail Alloc Live Unit Dst OpList
## @doc  Builda a new binary using the binary syntax.
177: bs_create_bin/6

## @spec call_fun2 Tag Arity Func
## @doc Calls the fun Func with arity Arity. Assume arguments in registers x(0)
##      to x(Arity-1). Tag can be one of:
##
##      * FunIndex      - `Func` is always a local fun identified by `FunIndex`
##      * {atom,safe}   - `Func` is known to be a fun of correct arity.
##      * {atom,unsafe} - Nothing is known about `Func`.
178: call_fun2/3

## @spec nif_start
## @doc  No-op at start of each function declared in -nifs().
179: nif_start/0

## @spec badrecord Value
## @doc Raises a {badrecord,Value} error exception.
180: badrecord/1

# OTP 26

## @spec update_record Hint Size Src Dst Updates=[Index, Value]
## @doc  Sets Dst to a copy of Src with the update list applied. Hint can be
##       one of:
##
##       * {atom,copy}        - The result will always differ from Src, so
##                              don't bother checking if it can be reused.
##       * {atom,reuse}       - Reuse Src if a runtime check deduces that it's
##                              equal to the result.
##
##       Note that these are just hints and the implementation is free to
##       ignore them. More hints may be added in the future.
181: update_record/5

## @spec bs_match Fail Ctx {commands,Commands}
## @doc  Match one or more binary segments of fixed size. Commands
##       can be one of the following:
##
##       * {ensure_at_least,Stride,Unit}
##       * {ensure_exactly,Stride}
##       * {binary,Live,Flags,Size,Unit,Dst}
##       * {integer,Live,Flags,Size,Unit,Dst}
##       * {skip,Stride}
##       * {get_tail,Live,Unit,Dst}
##       * {'=:=',Live,Size,Value}.
182: bs_match/3

# OTP 27

## @spec executable_line Location Index
## @doc  Provide location for an executable line.
183: executable_line/2

# OTP 28

## @spec debug_line Kind Location Index Live
## @doc  Provide location for a place where a break point can be placed.
##       Kind can be one of:
##
##       * {atom,entry}       - Function entry.
##       * {atom,line}        - Any other line in the function.
184: debug_line/4

# OTP 29

## @spec bif3 Lbl Bif Arg1 Arg2 Arg3 Reg
## @doc Call the bif Bif with the arguments Arg1, Arg2, and Arg3,
##      and store the result in Reg.
##      On failure jump to Lbl.
185: bif3/6