Difference between revisions of "SCI/Specifications/SCI virtual machine/The Sierra PMachine"

Certain instructions (in particular, branching ones) take relative addresses as a parameter. The actual address is calculated based on the instruction after the branching instruction itself. In this example, the <tt>bnt</tt> instruction, if the branch is made, jumps over the <tt>ldi</tt> instruction.

Certain instructions (in particular, branching ones) take relative addresses as a parameter. The actual address is calculated based on the instruction after the branching instruction itself. In this example, the <tt>bnt</tt> instruction, if the branch is made, jumps over the <tt>ldi</tt> instruction.

     eq?

     eq?

     bnt +2

     bnt +2

     ldi byte 2

     ldi byte 2

     push

     push

Relative addresses are signed values.

Relative addresses are signed values.

In every call instruction, a value is included which determines the size of the parameter list, as an offset into the stack. This value discounts the list size pushed by the SCI code. For instance, consider this example from real SCI code:

In every call instruction, a value is included which determines the size of the parameter list, as an offset into the stack. This value discounts the list size pushed by the SCI code. For instance, consider this example from real SCI code:

     pushi 3 ; three parameters passed

     pushi 3 ; three parameters passed

     pushi 4 ; the screen flag

     pushi 4 ; the screen flag

     pTos y ; push the y property

     pTos y ; push the y property

     callk OnControl, 6

     callk OnControl, 6

Notice that, although the <tt>callk</tt> line specifies 6 bytes of parameters, the kernel routine has access to the list size (which is at offset 8)!

Notice that, although the <tt>callk</tt> line specifies 6 bytes of parameters, the kernel routine has access to the list size (which is at offset 8)!

pop(): sp -= 2; return *sp;

pop(): sp -= 2; return *sp;

push(x): *sp = x; sp += 2; return x;

push(x): *sp = x; sp += 2; return x;

The following rules apply to opcodes:

The following rules apply to opcodes:

;<nowiki>op 0x01: bnot (1 byte)</nowiki>

;<nowiki>op 0x01: bnot (1 byte)</nowiki>

:Binary not

:Binary not

acc ^= 0xffff;

acc ^= 0xffff;

;<nowiki>op 0x03: add (1 byte)</nowiki>

;<nowiki>op 0x03: add (1 byte)</nowiki>

:Addition:

:Addition:

acc += pop();

acc += pop();

;<nowiki>op 0x05: sub (1 byte)</nowiki>

;<nowiki>op 0x05: sub (1 byte)</nowiki>

:Subtraction:

:Subtraction:

acc = pop() - acc;

acc = pop() - acc;

;<nowiki>op 0x07: mul (1 byte)</nowiki>

;<nowiki>op 0x07: mul (1 byte)</nowiki>

:Multiplication:

:Multiplication:

acc *= pop();

acc *= pop();

;<nowiki>op 0x09: div (1 byte)</nowiki>

;<nowiki>op 0x09: div (1 byte)</nowiki>

:Division:

:Division:

acc = pop() / acc;

acc = pop() / acc;

Division by zero is caught => acc = 0.

Division by zero is caught => acc = 0.

;<nowiki>op 0x0b: mod (1 byte)</nowiki>

;<nowiki>op 0x0b: mod (1 byte)</nowiki>

:Modulo:

:Modulo:

acc = pop() % acc;

acc = pop() % acc;

Modulo by zero is caught => acc = 0.

Modulo by zero is caught => acc = 0.

;<nowiki>op 0x0d: shr (1 byte)</nowiki>

;<nowiki>op 0x0d: shr (1 byte)</nowiki>

:Shift Right logical:

:Shift Right logical:

acc = pop() >> acc;

acc = pop() >> acc;

;<nowiki>op 0x0f: shl (1 byte)</nowiki>

;<nowiki>op 0x0f: shl (1 byte)</nowiki>

:Shift Left logical:

:Shift Left logical:

acc = pop() << acc;

acc = pop() << acc;

;<nowiki>op 0x11: xor (1 byte)</nowiki>

;<nowiki>op 0x11: xor (1 byte)</nowiki>

:Exclusive or:

:Exclusive or:

acc ^= pop();

acc ^= pop();

;<nowiki>op 0x13: and (1 byte)</nowiki>

;<nowiki>op 0x13: and (1 byte)</nowiki>

:Logical and:

:Logical and:

acc &= pop();

acc &= pop();

;<nowiki>op 0x15: or (1 byte)</nowiki>

;<nowiki>op 0x15: or (1 byte)</nowiki>

:Logical or:

:Logical or:

acc |= pop();

acc |= pop();

;<nowiki>op 0x17: neg (1 byte)</nowiki>

;<nowiki>op 0x17: neg (1 byte)</nowiki>

:Sign negation:

:Sign negation:

acc = -acc;

acc = -acc;

;<nowiki>op 0x19: not (1 byte)</nowiki>

;<nowiki>op 0x19: not (1 byte)</nowiki>

:Boolean not:

:Boolean not:

acc = !acc;

acc = !acc;

;<nowiki>op 0x1b: eq? (1 byte)</nowiki>

;<nowiki>op 0x1b: eq? (1 byte)</nowiki>

:Equals?:

:Equals?:

prev = acc;

prev = acc;

acc = (acc == pop());

acc = (acc == pop());

;<nowiki>op 0x1d: ne? (1 byte)</nowiki>

;<nowiki>op 0x1d: ne? (1 byte)</nowiki>

:Is not equal to?

:Is not equal to?

prev = acc;

prev = acc;

acc = !(acc == pop());

acc = !(acc == pop());

;<nowiki>op 0x1f: gt? (1 byte)</nowiki>

;<nowiki>op 0x1f: gt? (1 byte)</nowiki>

:Greater than?

:Greater than?

prev = acc;

prev = acc;

acc = (pop() > acc);

acc = (pop() > acc);

;<nowiki>op 0x21: ge? (1 byte)</nowiki>

;<nowiki>op 0x21: ge? (1 byte)</nowiki>

:Greater than or equal to?

:Greater than or equal to?

prev = acc;

prev = acc;

acc = (pop() >= acc);

acc = (pop() >= acc);

;<nowiki>op 0x23: lt? (1 byte)</nowiki>

;<nowiki>op 0x23: lt? (1 byte)</nowiki>

:Less than?

:Less than?

prev = acc;

prev = acc;

acc = (pop() < acc);

acc = (pop() < acc);

;<nowiki>op 0x25: le? (1 byte)</nowiki>

;<nowiki>op 0x25: le? (1 byte)</nowiki>

:Less than or equal to?

:Less than or equal to?

prev = acc;

prev = acc;

acc = (pop() <= acc);

acc = (pop() <= acc);

;<nowiki>op 0x27: ugt? (1 byte)</nowiki>

;<nowiki>op 0x27: ugt? (1 byte)</nowiki>

:Unsigned: Greater than?

:Unsigned: Greater than?

acc = (pop() > acc);

acc = (pop() > acc);

;<nowiki>op 0x29: uge? (1 byte)</nowiki>

;<nowiki>op 0x29: uge? (1 byte)</nowiki>

:Unsigned: Greather than or equal to?

:Unsigned: Greather than or equal to?

acc = (pop() >= acc);

acc = (pop() >= acc);

;<nowiki>op 0x2b: ult? (1 byte)</nowiki>

;<nowiki>op 0x2b: ult? (1 byte)</nowiki>

:Unsigned: Less than?

:Unsigned: Less than?

acc = (pop() < acc);

acc = (pop() < acc);

;<nowiki>op 0x2d: ule? (1 byte)</nowiki>

;<nowiki>op 0x2d: ule? (1 byte)</nowiki>

:Unsigned: Less than or equal to?

:Unsigned: Less than or equal to?

acc = (pop() >= acc);

acc = (pop() >= acc);

;<nowiki>op 0x2f: bt B relpos (2 bytes)</nowiki>

;<nowiki>op 0x2f: bt B relpos (2 bytes)</nowiki>

:Branch relative if true

:Branch relative if true

if (acc) pc += relpos;

if (acc) pc += relpos;

;<nowiki>op 0x31: bnt B relpos (2 bytes)</nowiki>

;<nowiki>op 0x31: bnt B relpos (2 bytes)</nowiki>

:Branch relative if not true

:Branch relative if not true

if (!acc) pc += relpos;

if (!acc) pc += relpos;

;<nowiki>op 0x33: jmp B relpos (2 bytes)</nowiki>

;<nowiki>op 0x33: jmp B relpos (2 bytes)</nowiki>

:Jump

:Jump

pc += relpos;

pc += relpos;

;<nowiki>op 0x35: ldi B data (2 bytes)</nowiki>

;<nowiki>op 0x35: ldi B data (2 bytes)</nowiki>

:Load data immediate

:Load data immediate

acc = data;

acc = data;

:Sign extension is done for 0x35 if required.

:Sign extension is done for 0x35 if required.

;<nowiki>op 0x37: push (1 byte)</nowiki>

;<nowiki>op 0x37: push (1 byte)</nowiki>

:Push to stack

:Push to stack

push(acc)

push(acc)

;<nowiki>op 0x39: pushi B data (2 bytes)</nowiki>

;<nowiki>op 0x39: pushi B data (2 bytes)</nowiki>

:Push immediate

:Push immediate

push(data)

push(data)

:Sign extension for 0x39 is performed where required.

:Sign extension for 0x39 is performed where required.

;<nowiki>op 0x3b: toss (1 byte)</nowiki>

;<nowiki>op 0x3b: toss (1 byte)</nowiki>

:TOS subtract

:TOS subtract

pop();

pop();

:For confirmation: Yes, this simply tosses the TOS value away.

:For confirmation: Yes, this simply tosses the TOS value away.

;<nowiki>op 0x3d: dup (1 byte)</nowiki>

;<nowiki>op 0x3d: dup (1 byte)</nowiki>

:Duplicate TOS element

:Duplicate TOS element

push(*TOS);

push(*TOS);

;<nowiki>op 0x3e: link W size (3 bytes)</nowiki>

;<nowiki>op 0x3e: link W size (3 bytes)</nowiki>

;<nowiki>op 0x3f: link B size (2 bytes)</nowiki>

;<nowiki>op 0x3f: link B size (2 bytes)</nowiki>

sp += (size * 2);

sp += (size * 2);

:Call inside script.

:Call inside script.

:(See description below)

:(See description below)

sp -= (framesize + 2 + &rest_modifier);

sp -= (framesize + 2 + &rest_modifier);

&rest_modifier = 0;

&rest_modifier = 0;

:This calls a script subroutine at the relative position relpos, setting up the <tt>ParmVar</tt> pointer first. <tt>ParmVar points</tt> to sp-<tt>''framesize''</tt> (but see also the <tt>&rest</tt> operation). The number of parameters is stored at word offset <tt>-1</tt> relative to <tt>ParmVar</tt>.

:This calls a script subroutine at the relative position relpos, setting up the <tt>ParmVar</tt> pointer first. <tt>ParmVar points</tt> to sp-<tt>''framesize''</tt> (but see also the <tt>&rest</tt> operation). The number of parameters is stored at word offset <tt>-1</tt> relative to <tt>ParmVar</tt>.

;<nowiki>op 0x43: callk B kfunct, B kparams (3 bytes)</nowiki>

;<nowiki>op 0x43: callk B kfunct, B kparams (3 bytes)</nowiki>

:Call kernel function (see the [[SCI/Specifications/SCI virtual machine/Kernel functions|Kernel functions]] section)

:Call kernel function (see the [[SCI/Specifications/SCI virtual machine/Kernel functions|Kernel functions]] section)

sp -= (kparams + 2 + &rest_modifier);

sp -= (kparams + 2 + &rest_modifier);

&rest_modifier = 0;

&rest_modifier = 0;

(call kernel function kfunct)

(call kernel function kfunct)

:Call base script

:Call base script

:(See description below)

:(See description below)

sp -= (framesize + 2 + &rest_modifier);

sp -= (framesize + 2 + &rest_modifier);

&rest_modifier = 0;

&rest_modifier = 0;

:This operation starts a new execution loop at the beginning of script 0, public method <tt>dispindex</tt> (Each script comes with a dispatcher list (type 7) that identifies public methods). Parameters are handled as in the call operation.

:This operation starts a new execution loop at the beginning of script 0, public method <tt>dispindex</tt> (Each script comes with a dispatcher list (type 7) that identifies public methods). Parameters are handled as in the call operation.

:Call external script

:Call external script

:(See description below)

:(See description below)

sp -= (framesize + 2 + &rest_modifier);

sp -= (framesize + 2 + &rest_modifier);

&rest_modifier = 0;

&rest_modifier = 0;

:This operation performs a function call (implicitly placing the current program counter on the execution stack) to an ``external'' procedure of a script. More precisely, exported procedure <tt>dispindex</tt> of script <tt>script</tt> is invoked, where <tt>dispindex</tt> is an offset into the script's Exports list (i.e., <tt>dispindex = ''n'' * 2</tt> references the ''n''th exported procedure).

:This operation performs a function call (implicitly placing the current program counter on the execution stack) to an ``external'' procedure of a script. More precisely, exported procedure <tt>dispindex</tt> of script <tt>script</tt> is invoked, where <tt>dispindex</tt> is an offset into the script's Exports list (i.e., <tt>dispindex = ''n'' * 2</tt> references the ''n''th exported procedure).

:The ``Exports list'' is defined in the script's type 7 object (cf. section [[SCI/Specifications/SCI_virtual_machine/Introduction#Script_resources|Script resources]]). It is an error to invoke a script which does not exist or which does not provide an Exports list, or to use a dispatch index which does not point into an even address within the Exports list.

:The ``Exports list'' is defined in the script's type 7 object (cf. section [[SCI/Specifications/SCI_virtual_machine/Introduction#Script_resources|Script resources]]). It is an error to invoke a script which does not exist or which does not provide an Exports list, or to use a dispatch index which does not point into an even address within the Exports list.

:Send looks up the supplied selector(s) in the object pointed to by the accumulator. If the selector is a variable selector, it is read (to the accumulator) if it was sent for with zero parameters. If a parameter was supplied, this selector is set to that parameter. Method selectors are called with the specified parameters.

:Send looks up the supplied selector(s) in the object pointed to by the accumulator. If the selector is a variable selector, it is read (to the accumulator) if it was sent for with zero parameters. If a parameter was supplied, this selector is set to that parameter. Method selectors are called with the specified parameters.

:The selector(s) and parameters are retreived from the stack frame. Send first looks up the selector ID at the bottom of the frame, then retreives the number of parameters, and, eventually, the parameters themselves. This algorithm is iterated until all of the stack frame has been "used up". Example:

:The selector(s) and parameters are retreived from the stack frame. Send first looks up the selector ID at the bottom of the frame, then retreives the number of parameters, and, eventually, the parameters themselves. This algorithm is iterated until all of the stack frame has been "used up". Example:

; This is an example for usage of the SCI send operation

; This is an example for usage of the SCI send operation

   pushi x      ; push the selector ID of x

   pushi x      ; push the selector ID of x

   push0        ; This will read foo and return the value in acc.

   push0        ; This will read foo and return the value in acc.

   send 12      ; This operation does three quite different things.

   send 12      ; This operation does three quite different things.

::set if the accumulator is to be used as additional index  

::set if the accumulator is to be used as additional index  

:::Because it is so hard to explain, I have made a transcription of it here:

:::Because it is so hard to explain, I have made a transcription of it here:

short *vars[4];

short *vars[4];

   return &((vars[(vt >> 1) &amp; 3])[vt &amp; 0x10 ? vi+acc : vi]);

   return &((vars[(vt >> 1) &amp; 3])[vt &amp; 0x10 ? vi+acc : vi]);

}

}

;<nowiki>op 0x5d: selfID (1 bytes)</nowiki>

;<nowiki>op 0x5d: selfID (1 bytes)</nowiki>

:Get 'self' identity: SCI uses heap pointers to identify objects, so this operation sets the accumulator to the address of the current object.

:Get 'self' identity: SCI uses heap pointers to identify objects, so this operation sets the accumulator to the address of the current object.

;<nowiki>op 0x61: pprev (1 bytes)</nowiki>

;<nowiki>op 0x61: pprev (1 bytes)</nowiki>

:Push prev: Pushes the value of the prev register, set by the last comparison bytecode (eq?, lt?, etc.), on the stack.

:Push prev: Pushes the value of the prev register, set by the last comparison bytecode (eq?, lt?, etc.), on the stack.

;<nowiki>op 0x73: lofsa B offset (2 bytes)</nowiki>

;<nowiki>op 0x73: lofsa B offset (2 bytes)</nowiki>

:Load Offset to Accumulator:

:Load Offset to Accumulator:

:Adds a value to the post-operation pc and stores the result in the accumulator.

:Adds a value to the post-operation pc and stores the result in the accumulator.

;<nowiki>op 0x75: lofss B offset (2 bytes)</nowiki>

;<nowiki>op 0x75: lofss B offset (2 bytes)</nowiki>

:Load Offset to Stack:

:Load Offset to Stack:

:Adds a value to the post-operation pc and pushes the result on the stack.

:Adds a value to the post-operation pc and pushes the result on the stack.

;<nowiki>op 0x77: push0 (1 bytes)</nowiki>

;<nowiki>op 0x77: push0 (1 bytes)</nowiki>

:Push 0:

:Push 0:

;<nowiki>op 0x79: push1 (1 bytes)</nowiki>

;<nowiki>op 0x79: push1 (1 bytes)</nowiki>

:Push 1:

:Push 1:

;<nowiki>op 0x7b: push2 (1 bytes)</nowiki>

;<nowiki>op 0x7b: push2 (1 bytes)</nowiki>

:Push 2:

:Push 2:

;<nowiki>op 0x7d: pushSelf (1 bytes)</nowiki>

;<nowiki>op 0x7d: pushSelf (1 bytes)</nowiki>

:Push self:

:Push self: