aboutsummaryrefslogtreecommitdiffstats
path: root/lib/compiler
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2013-09-04 12:28:55 +0200
committerBjörn Gustavsson <[email protected]>2013-09-04 12:43:44 +0200
commit053b721841efb06d3339c0376783a6dd09e625b5 (patch)
tree75e5adc139e6e1767c924f13bf27dba30150921b /lib/compiler
parent9c5426cbb9e46b1edd239c849af676699f539a3d (diff)
downloadotp-053b721841efb06d3339c0376783a6dd09e625b5.tar.gz
otp-053b721841efb06d3339c0376783a6dd09e625b5.tar.bz2
otp-053b721841efb06d3339c0376783a6dd09e625b5.zip
genop.tab: Add documentation for many BEAM instructions
By Erik Stenman (happi) with corrections by me.
Diffstat (limited to 'lib/compiler')
-rwxr-xr-x[-rw-r--r--]lib/compiler/src/genop.tab244
1 files changed, 244 insertions, 0 deletions
diff --git a/lib/compiler/src/genop.tab b/lib/compiler/src/genop.tab
index 75ac91907a..ebc9b1c85b 100644..100755
--- a/lib/compiler/src/genop.tab
+++ b/lib/compiler/src/genop.tab
@@ -23,45 +23,148 @@ BEAM_FORMAT_NUMBER=0
# 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 Dellocate
+## @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.
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.
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.)
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(0) 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 and store a
+## pointer to the message in x(0). 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 Lable Time
+## @doc Sets up a timeout of Time milllisecons and saves the address of the
+## following instruction as the entry point if the timeout triggers.
26: wait_timeout/2
#
@@ -83,36 +186,106 @@ BEAM_FORMAT_NUMBER=0
#
# Comparision 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
#
@@ -124,9 +297,26 @@ BEAM_FORMAT_NUMBER=0
#
# 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 postition Position of the tuple Tuple
+## with the new element NewElement.
67: set_tuple_element/3
#
@@ -147,13 +337,26 @@ BEAM_FORMAT_NUMBER=0
#
# '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
#
@@ -212,9 +415,14 @@ BEAM_FORMAT_NUMBER=0
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.
@@ -229,7 +437,20 @@ BEAM_FORMAT_NUMBER=0
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.
@@ -241,6 +462,8 @@ BEAM_FORMAT_NUMBER=0
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
@@ -250,7 +473,12 @@ BEAM_FORMAT_NUMBER=0
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
@@ -277,8 +505,24 @@ BEAM_FORMAT_NUMBER=0
# R14A
+## @spec recv_mark Label
+## @doc Save the end of the message queue and the address of
+## the label Label so that a recv_set instruction can start
+## scanning the inbox from this position.
150: recv_mark/1
+
+## @spec recv_set Label
+## @doc Check that the saved mark points to Label and set the
+## save pointer in the message queue to the last position
+## of the message queue saved by the recv_mark instruction.
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