genop.tab: Add documentation for many BEAM instructions

By Erik Stenman (happi) with corrections by me.

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