From 1ceb414c9705bbe17ddd8b425085ecdc5de1a08a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20M=C3=BCller?= Date: Wed, 5 Feb 2025 12:00:15 -0800 Subject: [PATCH] describe stack effects in descriptions of instructions --- bbq/opcode/instructions.go | 70 +++++++++---------- bbq/opcode/instructions.yml | 133 +++++++++++++++++++++++++----------- 2 files changed, 130 insertions(+), 73 deletions(-) diff --git a/bbq/opcode/instructions.go b/bbq/opcode/instructions.go index d849d31b6..b9789001d 100644 --- a/bbq/opcode/instructions.go +++ b/bbq/opcode/instructions.go @@ -61,7 +61,7 @@ func DecodeGetLocal(ip *uint16, code []byte) (i InstructionGetLocal) { // InstructionSetLocal // -// Sets the value of the local at the given index to the top value on the stack. +// Pops a value off the stack and then sets the local at the given index to that value. type InstructionSetLocal struct { LocalIndex uint16 } @@ -121,7 +121,7 @@ func DecodeGetGlobal(ip *uint16, code []byte) (i InstructionGetGlobal) { // InstructionSetGlobal // -// Sets the value of the global at the given index to the top value on the stack. +// Pops a value off the stack and then sets the global at the given index to that value. type InstructionSetGlobal struct { GlobalIndex uint16 } @@ -151,7 +151,7 @@ func DecodeSetGlobal(ip *uint16, code []byte) (i InstructionSetGlobal) { // InstructionGetField // -// Pushes the value of the field at the given index onto the stack. +// Pops a value off the stack, the target, and then pushes the value of the field at the given index onto the stack. type InstructionGetField struct { FieldNameIndex uint16 } @@ -181,7 +181,7 @@ func DecodeGetField(ip *uint16, code []byte) (i InstructionGetField) { // InstructionSetField // -// Sets the value of the field at the given index to the top value on the stack. +// Pops two values off the stack, the target and the value, and then sets the field at the given index of the target to the value. type InstructionSetField struct { FieldNameIndex uint16 } @@ -211,7 +211,7 @@ func DecodeSetField(ip *uint16, code []byte) (i InstructionSetField) { // InstructionGetIndex // -// Pushes the value at the given index onto the stack. +// Pops two values off the stack, the array and the index, and then pushes the value at the given index of the array onto the stack. type InstructionGetIndex struct { } @@ -231,7 +231,7 @@ func (i InstructionGetIndex) Encode(code *[]byte) { // InstructionSetIndex // -// Sets the value at the given index to the top value on the stack. +// Pops three values off the stack, the array, the index, and the value, and then sets the value at the given index of the array to the value. type InstructionSetIndex struct { } @@ -311,7 +311,7 @@ func (i InstructionNil) Encode(code *[]byte) { // InstructionPath // -// Pushes the path with the given domain and identifier onto the stack. +// Creates a new path with the given domain and identifier and then pushes it onto the stack. type InstructionPath struct { Domain common.PathDomain IdentifierIndex uint16 @@ -345,7 +345,7 @@ func DecodePath(ip *uint16, code []byte) (i InstructionPath) { // InstructionNew // -// Creates a new instance of the given type. +// Creates a new instance of the given kind and type and then pushes it onto the stack. type InstructionNew struct { Kind common.CompositeKind TypeIndex uint16 @@ -379,7 +379,7 @@ func DecodeNew(ip *uint16, code []byte) (i InstructionNew) { // InstructionNewArray // -// Creates a new array with the given type and size. +// Pops the given number of elements off the stack, creates a new array with the given type, size, and elements, and then pushes it onto the stack. type InstructionNewArray struct { TypeIndex uint16 Size uint16 @@ -417,7 +417,7 @@ func DecodeNewArray(ip *uint16, code []byte) (i InstructionNewArray) { // InstructionNewDictionary // -// Creates a new dictionary with the given type and size. +// Pops the given number of entries off the stack (twice the number of the given size), creates a new dictionary with the given type, size, and entries, and then pushes it onto the stack. type InstructionNewDictionary struct { TypeIndex uint16 Size uint16 @@ -455,7 +455,7 @@ func DecodeNewDictionary(ip *uint16, code []byte) (i InstructionNewDictionary) { // InstructionNewRef // -// Creates a new reference with the given type. +// Pops a value off the stack, creates a new reference with the given type, and then pushes it onto the stack. type InstructionNewRef struct { TypeIndex uint16 } @@ -515,7 +515,7 @@ func DecodeGetConstant(ip *uint16, code []byte) (i InstructionGetConstant) { // InstructionInvoke // -// Invokes the function with the given type arguments. +// Pops the function and arguments off the stack, invokes the function with the arguments, and then pushes the result back on to the stack. type InstructionInvoke struct { TypeArgs []uint16 } @@ -545,7 +545,7 @@ func DecodeInvoke(ip *uint16, code []byte) (i InstructionInvoke) { // InstructionInvokeDynamic // -// Invokes the dynamic function with the given name, type arguments, and argument count. +// Pops the arguments off the stack, invokes the function with the given name and argument count, and then pushes the result back on to the stack. type InstructionInvokeDynamic struct { NameIndex uint16 TypeArgs []uint16 @@ -583,7 +583,7 @@ func DecodeInvokeDynamic(ip *uint16, code []byte) (i InstructionInvokeDynamic) { // InstructionDup // -// Duplicates the top value on the stack. +// Pops a value off the stack, duplicates it, and then pushes the original and the copy back on to the stack. type InstructionDup struct { } @@ -603,7 +603,7 @@ func (i InstructionDup) Encode(code *[]byte) { // InstructionDrop // -// Removes the top value from the stack. +// Pops a value off the stack and discards it. type InstructionDrop struct { } @@ -623,7 +623,7 @@ func (i InstructionDrop) Encode(code *[]byte) { // InstructionDestroy // -// Destroys the top value on the stack. +// Pops a resource off the stack and then destroys it. type InstructionDestroy struct { } @@ -643,7 +643,7 @@ func (i InstructionDestroy) Encode(code *[]byte) { // InstructionUnwrap // -// Unwraps the top value on the stack. +// Pops an optional value off the stack, unwraps it, and then pushes the value back on to the stack. type InstructionUnwrap struct { } @@ -663,7 +663,7 @@ func (i InstructionUnwrap) Encode(code *[]byte) { // InstructionTransfer // -// Transfers the top value on the stack. +// Pops a value off the stack, transfers it to the given type, and then pushes it back on to the stack. type InstructionTransfer struct { TypeIndex uint16 } @@ -693,7 +693,7 @@ func DecodeTransfer(ip *uint16, code []byte) (i InstructionTransfer) { // InstructionCast // -// Casts the top value on the stack to the given type. +// Pops a value off the stack, casts it to the given type, and then pushes it back on to the stack. type InstructionCast struct { TypeIndex uint16 Kind CastKind @@ -727,7 +727,7 @@ func DecodeCast(ip *uint16, code []byte) (i InstructionCast) { // InstructionJump // -// Jumps to the given instruction. +// Unconditionally jumps to the given instruction. type InstructionJump struct { Target uint16 } @@ -757,7 +757,7 @@ func DecodeJump(ip *uint16, code []byte) (i InstructionJump) { // InstructionJumpIfFalse // -// Jumps to the given instruction, if the top value on the stack is `false`. +// Pops a value off the stack. If it is `false`, jumps to the target instruction. type InstructionJumpIfFalse struct { Target uint16 } @@ -787,7 +787,7 @@ func DecodeJumpIfFalse(ip *uint16, code []byte) (i InstructionJumpIfFalse) { // InstructionJumpIfNil // -// Jumps to the given instruction, if the top value on the stack is `nil`. +// Pops a value off the stack. If it is `nil`, jumps to the target instruction. type InstructionJumpIfNil struct { Target uint16 } @@ -837,7 +837,7 @@ func (i InstructionReturn) Encode(code *[]byte) { // InstructionReturnValue // -// Returns from the current function, with the top value on the stack. +// Pops a value off the stack and then returns from the current function with that value. type InstructionReturnValue struct { } @@ -857,7 +857,7 @@ func (i InstructionReturnValue) Encode(code *[]byte) { // InstructionEqual // -// Compares the top two values on the stack for equality. +// Pops two values off the stack, checks if the first value is equal to the second, and then pushes the result back on to the stack. type InstructionEqual struct { } @@ -877,7 +877,7 @@ func (i InstructionEqual) Encode(code *[]byte) { // InstructionNotEqual // -// Compares the top two values on the stack for inequality. +// Pops two values off the stack, checks if the first value is not equal to the second, and then pushes the result back on to the stack. type InstructionNotEqual struct { } @@ -897,7 +897,7 @@ func (i InstructionNotEqual) Encode(code *[]byte) { // InstructionNot // -// Negates the boolean value at the top of the stack. +// Pops a boolean value off the stack, negates it, and then pushes the result back on to the stack. type InstructionNot struct { } @@ -917,7 +917,7 @@ func (i InstructionNot) Encode(code *[]byte) { // InstructionIntAdd // -// Adds the top two values on the stack. +// Pops two integer values off the stack, adds them together, and then pushes the result back on to the stack. type InstructionIntAdd struct { } @@ -937,7 +937,7 @@ func (i InstructionIntAdd) Encode(code *[]byte) { // InstructionIntSubtract // -// Subtracts the top two values on the stack. +// Pops two integer values off the stack, subtracts the second from the first, and then pushes the result back on to the stack. type InstructionIntSubtract struct { } @@ -957,7 +957,7 @@ func (i InstructionIntSubtract) Encode(code *[]byte) { // InstructionIntMultiply // -// Multiplies the top two values on the stack. +// Pops two integer values off the stack, multiplies them together, and then pushes the result back on to the stack. type InstructionIntMultiply struct { } @@ -977,7 +977,7 @@ func (i InstructionIntMultiply) Encode(code *[]byte) { // InstructionIntDivide // -// Divides the top two values on the stack. +// Pops two integer values off the stack, divides the first by the second, and then pushes the result back on to the stack. type InstructionIntDivide struct { } @@ -997,7 +997,7 @@ func (i InstructionIntDivide) Encode(code *[]byte) { // InstructionIntMod // -// Calculates the modulo of the top two values on the stack. +// Pops two integer values off the stack, calculates the modulus of the first by the second, and then pushes the result back on to the stack. type InstructionIntMod struct { } @@ -1017,7 +1017,7 @@ func (i InstructionIntMod) Encode(code *[]byte) { // InstructionIntLess // -// Compares the top two values on the stack for less than. +// Pops two values off the stack, checks if the first value is less than the second, and then pushes the result back on to the stack. type InstructionIntLess struct { } @@ -1037,7 +1037,7 @@ func (i InstructionIntLess) Encode(code *[]byte) { // InstructionIntLessOrEqual // -// Compares the top two values on the stack for less than or equal. +// Pops two values off the stack, checks if the first value is less than or equal to the second, and then pushes the result back on to the stack. type InstructionIntLessOrEqual struct { } @@ -1057,7 +1057,7 @@ func (i InstructionIntLessOrEqual) Encode(code *[]byte) { // InstructionIntGreater // -// Compares the top two values on the stack for greater than. +// Pops two values off the stack, checks if the first value is greater than the second, and then pushes the result back on to the stack. type InstructionIntGreater struct { } @@ -1077,7 +1077,7 @@ func (i InstructionIntGreater) Encode(code *[]byte) { // InstructionIntGreaterOrEqual // -// Compares the top two values on the stack for greater than or equal. +// Pops two values off the stack, checks if the first value is greater than or equal to the second, and then pushes the result back on to the stack. type InstructionIntGreaterOrEqual struct { } diff --git a/bbq/opcode/instructions.yml b/bbq/opcode/instructions.yml index 57924d2a6..5900f36ee 100644 --- a/bbq/opcode/instructions.yml +++ b/bbq/opcode/instructions.yml @@ -5,7 +5,8 @@ # Local instructions - name: "getLocal" - description: Pushes the value of the local at the given index onto the stack. + description: + Pushes the value of the local at the given index onto the stack. operands: - name: "localIndex" type: "index" @@ -15,7 +16,8 @@ type: "value" - name: "setLocal" - description: Sets the value of the local at the given index to the top value on the stack. + description: + Pops a value off the stack and then sets the local at the given index to that value. operands: - name: "localIndex" type: "index" @@ -27,7 +29,8 @@ # Global instructions - name: "getGlobal" - description: Pushes the value of the global at the given index onto the stack. + description: + Pushes the value of the global at the given index onto the stack. operands: - name: "globalIndex" type: "index" @@ -37,7 +40,8 @@ type: "value" - name: "setGlobal" - description: Sets the value of the global at the given index to the top value on the stack. + description: + Pops a value off the stack and then sets the global at the given index to that value. operands: - name: "globalIndex" type: "index" @@ -49,20 +53,24 @@ # Field instructions - name: "getField" - description: Pushes the value of the field at the given index onto the stack. + description: + Pops a value off the stack, the target, + and then pushes the value of the field at the given index onto the stack. operands: - name: "fieldNameIndex" type: "index" valueEffects: pop: - - name: "container" + - name: "target" type: "value" push: - name: "value" type: "value" - name: "setField" - description: Sets the value of the field at the given index to the top value on the stack. + description: + Pops two values off the stack, the target and the value, + and then sets the field at the given index of the target to the value. operands: - name: "fieldNameIndex" type: "index" @@ -76,7 +84,9 @@ # Index instructions - name: "getIndex" - description: Pushes the value at the given index onto the stack. + description: + Pops two values off the stack, the array and the index, + and then pushes the value at the given index of the array onto the stack. valueEffects: pop: - name: "array" @@ -88,7 +98,9 @@ type: "value" - name: "setIndex" - description: Sets the value at the given index to the top value on the stack. + description: + Pops three values off the stack, the array, the index, and the value, + and then sets the value at the given index of the array to the value. valueEffects: pop: - name: "array" @@ -122,7 +134,7 @@ type: "value" - name: "path" - description: Pushes the path with the given domain and identifier onto the stack. + description: Creates a new path with the given domain and identifier and then pushes it onto the stack. operands: - name: "domain" type: "pathDomain" @@ -134,7 +146,7 @@ type: "path" - name: "new" - description: Creates a new instance of the given type. + description: Creates a new instance of the given kind and type and then pushes it onto the stack. operands: - name: "kind" type: "compositeKind" @@ -146,7 +158,9 @@ type: "value" - name: "newArray" - description: Creates a new array with the given type and size. + description: + Pops the given number of elements off the stack, creates a new array with the given type, size, and elements, + and then pushes it onto the stack. operands: - name: "typeIndex" type: "index" @@ -165,7 +179,10 @@ type: "array" - name: "newDictionary" - description: Creates a new dictionary with the given type and size. + description: + Pops the given number of entries off the stack (twice the number of the given size), + creates a new dictionary with the given type, size, and entries, + and then pushes it onto the stack. operands: - name: "typeIndex" type: "index" @@ -185,7 +202,9 @@ - name: "newRef" - description: Creates a new reference with the given type. + description: + Pops a value off the stack, creates a new reference with the given type, + and then pushes it onto the stack. operands: - name: "typeIndex" type: "index" @@ -210,7 +229,9 @@ # Invocation instructions - name: "invoke" - description: Invokes the function with the given type arguments. + description: + Pops the function and arguments off the stack, invokes the function with the arguments, + and then pushes the result back on to the stack. operands: - name: "typeArgs" type: "indices" @@ -227,7 +248,9 @@ - call: - name: "invokeDynamic" - description: Invokes the dynamic function with the given name, type arguments, and argument count. + description: + Pops the arguments off the stack, invokes the function with the given name and argument count, + and then pushes the result back on to the stack. operands: - name: "nameIndex" type: "index" @@ -248,7 +271,8 @@ # Value stack instructions - name: "dup" - description: Duplicates the top value on the stack. + description: + Pops a value off the stack, duplicates it, and then pushes the original and the copy back on to the stack. valueEffects: pop: - name: "value" @@ -260,7 +284,8 @@ type: "value" - name: "drop" - description: Removes the top value from the stack. + description: + Pops a value off the stack and discards it. valueEffects: pop: - name: "value" @@ -269,7 +294,8 @@ # Resource stack instructions - name: "destroy" - description: Destroys the top value on the stack. + description: + Pops a resource off the stack and then destroys it. valueEffects: pop: - name: "resource" @@ -278,7 +304,8 @@ # Optional instructions - name: "unwrap" - description: Unwraps the top value on the stack. + description: + Pops an optional value off the stack, unwraps it, and then pushes the value back on to the stack. valueEffects: pop: - name: "optional" @@ -290,7 +317,8 @@ # Conversion instructions - name: "transfer" - description: Transfers the top value on the stack. + description: + Pops a value off the stack, transfers it to the given type, and then pushes it back on to the stack. operands: - name: "typeIndex" type: "index" @@ -303,7 +331,8 @@ type: "value" - name: "cast" - description: Casts the top value on the stack to the given type. + description: + Pops a value off the stack, casts it to the given type, and then pushes it back on to the stack. operands: - name: "typeIndex" type: "index" @@ -320,7 +349,8 @@ # Control flow instructions - name: "jump" - description: Jumps to the given instruction. + description: + Unconditionally jumps to the given instruction. operands: - name: "target" type: "index" @@ -328,7 +358,8 @@ - jump: "target" - name: "jumpIfFalse" - description: Jumps to the given instruction, if the top value on the stack is `false`. + description: + Pops a value off the stack. If it is `false`, jumps to the target instruction. operands: - name: "target" type: "index" @@ -340,7 +371,8 @@ type: "value" - name: "jumpIfNil" - description: Jumps to the given instruction, if the top value on the stack is `nil`. + description: + Pops a value off the stack. If it is `nil`, jumps to the target instruction. operands: - name: "target" type: "index" @@ -357,7 +389,8 @@ - return: - name: "returnValue" - description: Returns from the current function, with the top value on the stack. + description: + Pops a value off the stack and then returns from the current function with that value. valueEffects: pop: - name: "value" @@ -368,7 +401,9 @@ # Comparison instructions - name: "equal" - description: Compares the top two values on the stack for equality. + description: + Pops two values off the stack, checks if the first value is equal to the second, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -380,7 +415,9 @@ type: "bool" - name: "notEqual" - description: Compares the top two values on the stack for inequality. + description: + Pops two values off the stack, checks if the first value is not equal to the second, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -394,7 +431,9 @@ # Logical instructions - name: "not" - description: Negates the boolean value at the top of the stack. + description: + Pops a boolean value off the stack, negates it, + and then pushes the result back on to the stack. valueEffects: pop: - name: "value" @@ -406,7 +445,9 @@ # Integer arithmetic instructions - name: "intAdd" - description: Adds the top two values on the stack. + description: + Pops two integer values off the stack, adds them together, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -418,7 +459,9 @@ type: "int" - name: "intSubtract" - description: Subtracts the top two values on the stack. + description: + Pops two integer values off the stack, subtracts the second from the first, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -430,7 +473,9 @@ type: "int" - name: "intMultiply" - description: Multiplies the top two values on the stack. + description: + Pops two integer values off the stack, multiplies them together, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -442,7 +487,9 @@ type: "int" - name: "intDivide" - description: Divides the top two values on the stack. + description: + Pops two integer values off the stack, divides the first by the second, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -454,7 +501,9 @@ type: "int" - name: "intMod" - description: Calculates the modulo of the top two values on the stack. + description: + Pops two integer values off the stack, calculates the modulus of the first by the second, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -468,7 +517,9 @@ # Integer comparison instructions - name: "intLess" - description: Compares the top two values on the stack for less than. + description: + Pops two values off the stack, checks if the first value is less than the second, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -480,7 +531,9 @@ type: "bool" - name: "intLessOrEqual" - description: Compares the top two values on the stack for less than or equal. + description: + Pops two values off the stack, checks if the first value is less than or equal to the second, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -492,7 +545,9 @@ type: "bool" - name: "intGreater" - description: Compares the top two values on the stack for greater than. + description: + Pops two values off the stack, checks if the first value is greater than the second, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left" @@ -504,7 +559,9 @@ type: "bool" - name: "intGreaterOrEqual" - description: Compares the top two values on the stack for greater than or equal. + description: + Pops two values off the stack, checks if the first value is greater than or equal to the second, + and then pushes the result back on to the stack. valueEffects: pop: - name: "left"