Math and Logic Instructions

Data movement

MOV copies the Source value into Destination.

If the WC or WCZ effect is specified, the C flag is updated to be Source[31].

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero.

MOVBYTS shuffles the bytes of Destination based on bottom 8 bits in Source. Each bit pair in Source[7:0] corrosponds to one byte slot of the result and selects which of the input bytes will appear there. It is useful to use base-4 literals (%%0123) with MOVBYTS, since each digit corrosponds to one bit pair.

• MOVBYTS D,#%%3210 leaves D as-is.
• MOVBYTS D,#%%0123 reverses the bytes of D ("endian swap").
• MOVBYTS D,#%%0000 will copy the lowest byte into all four slots

LOC moves a 20-bit address into either PA, PB, PTRA or PTRB. This address can be encoded as either absolute or relative.

GETNIB reads the Nth nibble (4 bits) from Source and moves it into Destination. The upper 28 bits of Destination are cleared.

N can be any constant between 0 and 7. N = 0 gets the least significant nibble (S[3:0]), N = 7 gets the most significant nibble (S[31:28])

GETNIB can have its Source and N omitted, in which case they default to 0 and #0. This is intended for use with ALTGN.

GETBYTE reads the Nth byte (8 bits) from Source and moves it into Destination. The upper 24 bits of Destination are cleared.

N can be any constant between 0 and 3. N = 0 gets the least significant byte (S[7:0]), N = 3 gets the most significant byte (S[31:24])

GETBYTE can have its Source and N omitted, in which case they default to 0 and #0. This is intended for use with ALTGB.

GETWORD reads the Nth word (16 bits) from Source and moves it into Destination. The upper 16 bits of Destination are cleared.

N can be the constants 0 and 1. N = 0 gets the least significant word (S[15:0]), N = 1 gets the most significant word (S[31:16])

GETWORD can have its Source and N omitted, in which case they default to 0 and #0. This is intended for use with ALTGW.

SETNIB stores the least significant nibble (4 bits) of Source into the Nth nibble of Destination. All other bits are unaffected.

N can be any constant between 0 and 7. N = 0 sets the least significant nibble (D[3:0]), N = 7 sets the most significant nibble (D[31:28])

SETNIB can have its Destination and N omitted, in which case they default to 0 and #0. This is intended for use with ALTSN.

SETBYTE stores the least significant byte (8 bits) of Source into the Nth byte of Destination. All other bits are unaffected.

N can be any constant between 0 and 3. N = 0 sets the least significant byte (D[7:0]), N = 3 sets the most significant byte (D[31:24])

SETBYTE can have its Destination and N omitted, in which case they default to 0 and #0. This is intended for use with ALTSB.

SETWORD stores the least significant byte (16 bits) of Source into the Nth word of Destination. All other bits are unaffected.

N can be the constants 0 and 1. N = 0 sets the least significant word (D[15:0]), N = 1 sets the most significant word (D[31:16])

SETWORD can have its Destination and N omitted, in which case they default to 0 and #0. This is intended for use with ALTSW.

ROLNIB reads the Nth nibble (4 bits) from Source and shifts it into Destination. The lower 28 bits of Destination are shifted up by 4 and the top 4 bits are discarded.

N can be any constant between 0 and 7. N = 0 gets the least significant nibble (S[3:0]), N = 7 gets the most significant nibble (S[31:28])

ROLNIB can have its Source and N omitted, in which case they default to 0 and #0. This is intended for use with ALTGN.

ROLBYTE reads the Nth byte (8 bits) from Source and shifts it into Destination. The lower 24 bits of Destination are shifted up by 8 and the top 8 bits are discarded.

N can be any constant between 0 and 3. N = 0 gets the least significant byte (S[7:0]), N = 3 gets the most significant byte (S[31:24])

ROLBYTE can have its Source and N omitted, in which case they default to 0 and #0. This is intended for use with ALTGB.

ROLWORD reads the Nth word (16 bits) from Source and shifts it into Destination. The lower 16 bits of Destination are shifted up by 16 and the top 16 bits are discarded.

N can be the constants 0 and 1. N = 0 gets the least significant word (S[15:0]), N = 1 gets the most significant word (S[31:16])

ROLWORD can have its Source and N omitted, in which case they default to 0 and #0. This is intended for use with ALTGW.

SETS copies Source[8:0] into Destination[8:0]. Other bits remain unaffected. This is useful to set up the S-field for ALTI or to set the S-field of an instruction in memory (See: Self-Modifying Code TODO Link).

SETD copies Source[8:0] into Destination[17:9]. Other bits remain unaffected. This is useful to set up the D field for ALTI or to set the D field of an instruction in memory (See: Self-Modifying Code TODO Link).

SETR copies Source[8:0] into Destination[27:19]. Other bits remain unaffected. This is useful to set up the R field for ALTI or to modify the opcode and flag effects of an instruction in memory (See: Self-Modifying Code TODO Link).

Arithmetic

ADD sums the two unsigned values of Destination and Source together and stores the result into the Destination register.

If the WC or WCZ effect is specified, the C flag is set (1) if the summation resulted in an unsigned carry (= 32-bit overflow), or is cleared (0) if no carry.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result stored into Destination is zero, or is cleared (0) if it is non-zero.

To add unsigned, multi-long values, use ADD followed by ADDX as described in Adding Two Multi-Long Values(TODO LINK). ADD and ADDX are also used in adding signed, multi-long values with ADDSX ending the sequence.

ADDS sums the two signed values of Destination and Source together and stores the result into the Destination register. If Source is a 9-bit literal, its value is interpreted as positive (0-511; it is not sign-extended) — use ##Value (or insert a prior AUGS instruction) for a 32-bit signed value; negative or positive.

If the WC or WCZ effect is specified, the C flag is set (1) if the summation, signed overflow nonwithstanding, produced a negative result. Overflow occured if C is not equal to the result's MSB (see TJV).

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result stored into Destination is zero, or is cleared (0) if it is non-zero.

To add signed, multi-long values, use ADD (not ADDS) followed possibly by ADDX, and finally ADDSX as described in Adding Two Multi-Long Values(TODO LINK).

ADDX sums the unsigned values of Destination and Source plus C together and stores the result into the Destination register. The ADDX instruction is used to perform unsigned multi-long (extended) addition, such as 64-bit addition.

If the WC or WCZ effect is specified, the C flag is set (1) if the summation resulted in an unsigned carry, or is cleared (0) if no carry.

If the WZ or WCZ effect is specified, the Z flag is set (1) if Z was previously set and the result stored into Destination is zero, or it is cleared (0) if non-zero or if Z was not previously set. Use WCZ on preceding ADD and ADDX instructions for proper final Z flag.

To add unsigned multi-long values, use ADD followed by one or more ADDX instructions as described in Adding Two Multi-Long Values(TODO LINK).

ADDSX sums the signed values of Destination and Source plus C together and stores the result into the Destination register. The ADDSX instruction is used to perform signed multi-long (extended) addition, such as 64-bit addition.

If the WC or WCZ effect is specified, the C flag is set (1) if the summation, signed overflow nonwithstanding, produced a negative result. Overflow occured if C is not equal to the result's MSB (see TJV).

If the WZ or WCZ effect is specified, the Z flag is set (1) if Z was previously set and the result stored into Destination is zero, or it is cleared (0) if non-zero or if Z was not previously set. Use WCZ on preceding ADD and ADDX instructions for proper final Z flag.

To add signed multi-long values, use ADD (not ADDS) followed possibly by ADDX, and finally ADDSX as described in Adding Two Multi-Long Values(TODO LINK).

SUB subtracts the unsigned Source from the unsigned Destination and stores the result into the Destination register.

If the WC or WCZ effect is specified, the C flag is set (1) if the subtraction results in an unsigned borrow (= 32-bit underflow), or is cleared (0) if no borrow.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result stored into Destination is zero, or is cleared (0) if it is non-zero.

To subtract unsigned, multi-long values, use SUB followed by SUBX as described in Subtracting Two Multi-Long Values(TODO LINK). SUB and SUBX are also used in subtracting signed, multi-long values with SUBSX ending the sequence.

SUBR subtracts the unsigned Destination from the unsigned Source and stores the result into the Destination register. This is the reverse of the subtraction order of SUB.

If the WC or WCZ effect is specified, the C flag is set (1) if the subtraction results in an unsigned borrow (= 32-bit underflow), or is cleared (0) if no borrow.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result stored into Destination is zero, or is cleared (0) if it is non-zero.

SUBS subtracts the signed Source from the signed Destination and stores the result into the Destination register. If Source is a 9-bit literal, its value is interpreted as positive (0-511; it is not sign-extended) — use ##Value (or insert a prior AUGS instruction) for a 32-bit signed value; negative or positive.

If the WC or WCZ effect is specified, the C flag is set (1) if the subtraction, signed overflow nonwithstanding, produced a negative result. Overflow occured if C is not equal to the result's MSB (see TJV).

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result stored into Destination is zero, or is cleared (0) if it is non-zero.

To subtract signed, multi-long values, use SUB (not SUBS) followed possibly by SUBX, and finally SUBSX as described in Subtracting Two Multi-Long Values(TODO LINK).

SUBX subtracts the unsigned value of Source plus C from the unsigned Destination and stores the result into the Destination register. The SUBX instruction is used to perform unsigned multi-long (extended) subtraction, such as 64-bit subtraction.

If the WC or WCZ effect is specified, the C flag is set (1) if the subtraction resulted in an unsigned borrow, or is cleared (0) if no carry.

If the WZ or WCZ effect is specified, the Z flag is set (1) if Z was previously set and the result stored into Destination is zero, or it is cleared (0) if non-zero or if Z was not previously set. Use WCZ on preceding SUB and SUBX instructions for proper final Z flag.

SUBSX subtracts the signed value of Source plus C from the signed Destination and stores the result into the Destination register. The SUBSX instruction is used to perform signed multi-long (extended) subtraction, such as 64-bit subtraction.

If the WC or WCZ effect is specified, the C flag is set (1) if the subtraction, signed overflow nonwithstanding, produced a negative result. Overflow occured if C is not equal to the result's MSB (see TJV).

If the WZ or WCZ effect is specified, the Z flag is set (1) if Z was previously set and the result stored into Destination is zero, or it is cleared (0) if non-zero or if Z was not previously set. Use WCZ on preceding SUB and SUBX instructions for proper final Z flag.

To subtract signed multi-long values, use SUB (not SUBS) followed possibly by SUBX, and finally SUBSX as described in Subtracting Two Multi-Long Values(TODO LINK).

CMP compares the unsigned values of Destination and Source (by subtracting Source from Destination) and optionally setting the C and Z flags accordingly.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination is less than Source.

If the WZ or WCZ effect is specified, the Z flag is set (1) if Destination equals Source.

Note that it is possible to encode CMP without any effects, which is entirely pointless.

CMPR compares the unsigned values of Destination and Source (by subtracting Destination from Source) and optionally setting the C and Z flags accordingly.

If the WC or WCZ effect is specified, the C flag is set (1) if Source is less than Destination.

If the WZ or WCZ effect is specified, the Z flag is set (1) if Destination equals Source.

Note that it is possible to encode CMP without any effects, which is entirely pointless.

CMPS compares the signed values of Destination and Source (by subtracting Source from Destination) and optionally setting the C and Z flags accordingly.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination is less than Source.

If the WZ or WCZ effect is specified, the Z flag is set (1) if Destination equals Source.

Note that it is possible to encode CMPS without any effects, which is entirely pointless.

CMPM compares the values of Destination and Source (by subtracting Source from Destination) and optionally setting the C and Z flags accordingly.

If the WC or WCZ effect is specified, the C flag is updated to the MSB (bit 31) of (Destination - Source)

If the WZ or WCZ effect is specified, the Z flag is set (1) if Destination equals Source.

Note that it is possible to encode CMPM without any effects, which is entirely pointless.

CMPSUB compares the unsigned values of Destination and Source, and, if Source is less than or equal to Destination, it is subtracted from Destination. Optionally, the C and Z flags are set to indicate the comparison and operation results.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination was greater than or equal to Source.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result equals 0 (including if Destination was 0 to begin with).

ABS determines the absolute value of Source and writes the result into Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the original Source value was negative, or is cleared (0) if it was positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

Literal Source values are zero-extended, so ABS is really best used with register Source (or augmented Source) values.

ABS's Source can be omitted, in which case it defaults to being the same as its Destination.

NEG negates Source and stores the result in the Destination register. The negation flips the value's sign; ex: 78 becomes -78, or -306 becomes 306.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

NEG's Source can be omitted, in which case it defaults to being the same as its Destination.

NEGC negates Source if the C flag is set and stores the result in the Destination register. If the C flag is clear, the Source value is left as-is (not negated) and is stored into Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

NEGNC negates Source if the C flag is not set and stores the result in the Destination register. If the C flag is set, the Source value is left as-is (not negated) and is stored into Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

NEGZ negates Source if the C flag is set and stores the result in the Destination register. If the Z flag is clear, the Source value is left as-is (not negated) and is stored into Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

NEGNZ negates Source if the Z flag is not set and stores the result in the Destination register. If the Z flag is set, the Source value is left as-is (not negated) and is stored into Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

SUMC subtracts Source from Destination if the C flag is set and stores the result in the Destination register. If the C flag is clear, Source is instead added to Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

SUMNC subtracts Source from Destination if the C flag is not set and stores the result in the Destination register. If the C flag is set, Source is instead added to Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

SUMZ subtracts Source from Destination if the Z flag is set and stores the result in the Destination register. If the Z flag is clear, Source is instead added to Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

SUMNZ subtracts Source from Destination if the Z flag is not set and stores the result in the Destination register. If the Z flag is set, Source is instead added to Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result is negative, or is cleared (0) if positive.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

MUL performs an unsigned multiplication of the lower 16-bits of Destination and Source and stores the 32-bit product result into the Destination register. This is a fast (2-clock) 16 x 16 bit multiplication operation - to multiply larger factors, use the CORDIC Solver QMUL instruction.

If the WZ effect is specified, the Z flag is set (1) if either the Destination or Source values are zero, or is cleared (0) if both are non-zero. TODO: is the entire register checked or just the bottom 16 bits?

MULS performs a signed multiplication of the lower 16-bits of Destination and Source and stores the 32-bit signed product result into the Destination register. This is a fast (2-clock) signed 16 x 16 bit multiplication operation - to multiply larger factors, use the CORDIC Solver QMUL instruction.

If the WZ effect is specified, the Z flag is set (1) if either the Destination or Source values are zero, or is cleared (0) if both are non-zero. TODO: same question as MUL

SCA performs an unsigned multiplication of the lower 16-bits of Destination and Source, shifts the 32-bit product right by 16 (to scale down the result), and substitutes this value as the next instruction's Source value.

If the WZ effect is specified, the Z flag is set (1) if the product (before scaling down) is zero, or is cleared (0) if non-zero.

SCAS performs a signed multiplication of the lower 16-bits of Destination and Source, right shifts the 32-bit product by 14 (to scale down the result), and substitutes this value as the next instruction's Source value.

In this 2.14 fixed point scheme, a factor of $4000 will pass the the other factor through unchanged and a factor of $C000 will negate it.

If the WZ effect is specified, the Z flag is set (1) if the product (before scaling down) is zero, or is cleared (0) if non-zero.

INCMOD compares Destination with Source - if not equal, it increments Destination; otherwise it sets Destination to 0. If Destination begins in the range 0 to Source, iterations of INCMOD will increment Destination repetitively from 0 to Source.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination was equal to Source and subsequently reset to 0; or is cleared (0) if not reset.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

INCMOD does not limit Destination within the specified range - if Destination begins as greater than Source, iterations of INCMOD will continue to increment it through the 32-bit rollover point (back to 0) before it will effectively cycle from 0 to Source.

DECMOD compares Destination with 0 - if not equal, it decrements Destination; otherwise it sets Destination to Source. If Destination begins in the range 0 to Source, iterations of DECMOD will decrement Destination repetitively from Source to 0.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination was equal to 0 and subsequently reset to Source; or is cleared (0) if not reset.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

DECMOD does not limit Destination within the specified range - if Destination begins as greater than Source, iterations of DECMOD will continue to decrement it down through Source before it will effectively cycle from Source to 0.

FGE sets Destination to Source if Destination is less than Source by unsigned comparsion. This is also known as a limit minimum function; preventing Destination from sinking below Source.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination was limited (Destination was less than Source and now Destination is equal to Source), or is cleared (0) if not limited.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

FGES sets Destination to Source if Destination is less than Source by signed comparsion. This is also known as a limit minimum function; preventing Destination from sinking below Source.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination was limited (Destination was less than Source and now Destination is equal to Source), or is cleared (0) if not limited.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

FLE sets Destination to Source if Destination is greater than Source by unsigned comparsion. This is also known as a limit maximum function; preventing Destination from rising above Source.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination was limited (Destination was greater than Source and now Destination is equal to Source), or is cleared (0) if not limited.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

FLES sets Destination to Source if Destination is greater than Source by signed comparsion. This is also known as a limit maximum function; preventing Destination from rising above Source.

If the WC or WCZ effect is specified, the C flag is set (1) if Destination was limited (Destination was greater than Source and now Destination is equal to Source), or is cleared (0) if not limited.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

Bit operations

SHL shifts Destination's binary value left by Source places (0–31 bits) and sets the new LSBs to 0. This is useful for bit-stream manipulation as well as for swift multiplication; signed or unsigned 32-bit integer multiplication by a power-of-two. Care must be taken for power-of-two multiplications since upper bits will shift through the MSB (sign bit); mangling large signed values.

If the WC or WCZ effect is specified, the C flag is updated to the value of the last bit shifted out (effectively C = result bit "32") if Source is 1–31, or to Destination[31] if Source is 0.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero.

SHR shifts Destination's binary value right by Source places (0–31 bits) and sets the new MSBs to 0. This is useful for bit-stream manipulation as well as for swift division; unsigned 32-bit integer division by a power-of-two. For similar division of a signed value, use SAR instead.

If the WC or WCZ effect is specified, the C flag is updated to the value of the last bit shifted out (effectively C = result bit "-1") if Source is 1–31, or to Destination[0] if Source is 0.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero.

SAL shifts Destination's binary value left by Source places (0–31 bits) and sets the new LSBs to that of the original Destination[0]. SAL is the complement of SAR for bit streams but not for math operations - use SHL instead for swift 32-bit integer multiplication by a power-of-two.

If the WC or WCZ effect is specified, the C flag is updated to the value of the last bit shifted out (effectively C = result bit "32") if Source is 1–31, or to Destination[31] if Source is 0.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero.

SAR shifts Destination's binary value right by Source places (0–31 bits) and sets the new MSBs to that of the original Destination[31]; preserving the sign of a signed integer. This is useful for bit stream manipulation and for swift division - it is similar to SHR for swift division by a power-of-two, but is safe for both signed and unsigned integers. (Note that the rounding behaviour for negative numbers is different to a real division - TODO: Describe this better)

If the WC or WCZ effect is specified, the C flag is updated to the value of the last bit shifted out (effectively C = result bit "-1") if Source is 1–31, or to Destination[0] if Source is 0.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero.

ROL rotates Destination's binary value left by Source places (0–31 bits). All MSBs rotated out are moved into the new LSBs.

If the WC or WCZ effect is specified, the C flag is updated to the value of the last bit rotated out (effectively C = result bit "0") if Source is 1–31, or to Destination[31] if Source is 0.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero. Since no bits are lost by this operation, the result will only be zero if Destination started at zero.

ROR rotates Destination's binary value right by Source places (0–31 bits). All LSBs rotated out are moved into the new MSBs.

If the WC or WCZ effect is specified, the C flag is updated to the value of the last bit rotated out (effectively C = result bit "31") if Source is 1–31, or to Destination[0] if Source is 0.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero. Since no bits are lost by this operation, the result will only be zero if Destination started at zero.

RCL shifts Destination's binary value left by Source places (0–31 bits) and sets the new LSBs to C.

If the WC or WCZ effect is specified, the C flag is updated to the value of the last bit shifted out if Source is 1–31, or to Destination[31] if Source is 0.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero.

RCR shifts Destination's binary value right by Source places (0–31 bits) and sets the new MSBs to C.

If the WC or WCZ effect is specified, the C flag is updated to the value of the last bit shifted out if Source is 1–31, or to Destination[0] if Source is 0.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination result equals zero, or is cleared (0) if it is non-zero.

RCZL shifts Destination's binary value left by two places and sets Destination[1] to C and Destination[0] to Z.

If the WC or WCZ effect is specified, the C flag is updated to the original Destination[31] state.

If the WZ or WCZ effect is specified, the Z is flag is updated to the original Destination[30] state.

RCZR shifts Destination's binary value right by two places and sets Destination[31] to C and Destination[30] to Z.

If the WC or WCZ effect is specified, the C flag is updated to the original Destination[1] state.

If the WZ or WCZ effect is specified, the Z is flag is updated to the original Destination[0] state.

SIGNX fills the bits of Destination, above the bit indicated by Source[4:0], with the value of that identified bit; i.e. sign-extending the value. This is handy when converting encoded or received signed values from a small bit width to a large bit with; i.e. 32 bits.

Note: To extend an N-bit value, Source[4:0] has to be N-1. (TODO: Clarify this in a less confusing way)

If the WC or WCZ effect is specified, the C flag is set to the result's MSB value.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

ZEROX fills the bits of Destination, above the bit indicated by Source[4:0], with zeroes; i.e. zero-extending the value. This is handy when converting encoded or received unsigned values from a small bit width to a large bit with; i.e. 32 bits.

Note: To extend an N-bit value, Source[4:0] has to be N-1. (TODO: Clarify this in a less confusing way)

If the WC or WCZ effect is specified, the C flag is set to the result's MSB value. This is always zero unless Source[4:0] == 31.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result is zero, or is cleared (0) if it is non-zero.

NOT performs a bitwise NOT (inverting all bits) of the value in Source and stores the result into Destination.

If the WC or WCZ effect is specified, the C flag value is replaced by the inverse of either S[31].

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result (of !Source) equals zero, or is cleared (0) if it is non-zero.

ONES tallies the number of high bits of Source, or Destination, and stores the count into Destination. This is also known as a "Population Count" ("popcount") function.

If the WC or WCZ effect is specified, the C flag is set (1) if the count is odd, or is cleared (0) if it is even.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result equals zero, or is cleared (0) if not zero.

ONES' Source can be omitted, in which case it defaults to being the same as its Destination.

ENCOD stores the bit position value (0—31) of the top-most high bit (1) of Source into Destination. If the value to encode is all zeroes, the resulting Destination will be 0 - use the WC or WCZ effect and check the resulting C flag to distinguish between the cases of Source == 1 vs. Source == 0.

If the WC or WCZ effect is specified, the C flag is set (1) if Source was not zero, or is cleared (0) if it was zero.

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result equals zero, or is cleared (0) if not zero.

• A long of %00000000_00000000_00000000_00000001 encodes to 0.
• A long of %00000000_00000000_00000000_00100000 encodes to 5.
• A long of %00000000_00000000_10000001_01000000 encodes to 15.
• A long of %00000000_00000000_00000000_00000000 encodes to 0 with optional C cleared to 0.

ENCOD is the complement of DECOD.

ENCOD's Source can be omitted, in which case it defaults to being the same as its Destination.

DECOD generates a 32-bit value with just one bit high, corresponding to Source[4:0] (0—31) and stores that result in Destination.

In effect, Destination becomes 1 << value via the DECOD instruction; where value is Source[4:0].

• A value of 0 generates %00000000_00000000_00000000_00000001.
• A value of 5 generates %00000000_00000000_00000000_00100000.
• A value of 15 generates %00000000_00000000_10000000_00000000.

DECOD is the complement of ENCOD

DECOD's Source can be omitted, in which case it defaults to being the same as its Destination.

BMASK generates an LSB-justified bit mask (all ones) of Source[4:0]+1 bits and stores it in Destination. The size value, specified by Source[4:0], is in the range 0—31 to generate 1 to 32 bits of bit mask.

In effect, Destination becomes (%10 << size) - 1 via the BMASK instruction.

• A size value of 0 generates a bit mask of %00000000_00000000_00000000_00000001.
• A size value of 5 generates a bit mask of %00000000_00000000_00000000_00111111.
• A size value of 15 generates a bit mask of %00000000_00000000_11111111_11111111.

A bit mask is often useful in bitwise operations (AND, OR, XOR) to filter out or affect special groups of bits.

BMASK's Source can be omitted, in which case it defaults to being the same as its Destination.

REV performs a bitwise reverse (bits 31:0 -> bits 0:31) of the value in Destination and stores the result back into Destination. This is useful for processing binary data in a different MSB/LSB order than it is transmitted with.

SPLITB and MERGEB reorder the bits within Destination in a complementary pattern. TODO more text

SPLITW and MERGEW reorder the bits within Destination in a complementary pattern. TODO more text

RGBEXP and RGBSQZ convert between RGBx8888 and RGB565 color values.

TODO RGBEXP text

RGBSQZ converts a 32-bit color in Destination into a 16-bit color. This can be described as moving Destination[15:11] to Destination[4:0], Destination[23:18] into Destination[10:5], Destination[31:27] into Destination[15:11] and clearing the remaining 16 bits.

SEUSSF and SEUSSR are TODO weird. What are these actually good for?

SEUSSF bit permutation in text form:

• bit 0 -> bit 11, inverted

• bit 1 -> bit 5, non-inverted

• bit 2 -> bit 18, inverted

• bit 3 -> bit 24, inverted

• bit 4 -> bit 27, non-inverted

• bit 5 -> bit 19, inverted

• bit 6 -> bit 20, non-inverted

• bit 7 -> bit 30, non-inverted

• bit 8 -> bit 28, inverted

• bit 9 -> bit 26, inverted

• bit 10 -> bit 21, non-inverted

• bit 11 -> bit 25, non-inverted

• bit 12 -> bit 3, non-inverted

• bit 13 -> bit 8, non-inverted

• bit 14 -> bit 7, non-inverted

• bit 15 -> bit 23, non-inverted

• bit 16 -> bit 13, inverted

• bit 17 -> bit 12, non-inverted

• bit 18 -> bit 16, inverted

• bit 19 -> bit 2, non-inverted

• bit 20 -> bit 15, inverted

• bit 21 -> bit 1, non-inverted

• bit 22 -> bit 9, inverted

• bit 23 -> bit 31, non-inverted

• bit 24 -> bit 0, inverted

• bit 25 -> bit 29, inverted

• bit 26 -> bit 17, non-inverted

• bit 27 -> bit 10, inverted

• bit 28 -> bit 14, non-inverted

• bit 29 -> bit 4, inverted

• bit 30 -> bit 6, inverted

• bit 31 -> bit 22, inverted

TEST performs a bitwise AND of the value in Source into that of Destination, but discards the result (Destination remains unchanged). Note that it is possible to encode TEST without any effects, which is entirely pointless.

If the WC or WCZ effect is specified, the C flag is set (1) if the result has odd parity (contains an odd number of high (1) bits), or is cleared (0) if it has even parity (contains an even number of high bits).

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination OR Source result equals zero, or is cleared (0) if it is non-zero.

Warning: Easy to confuse with TESTB

TESTN performs a bitwise AND of the inverse of the value in Source into that of Destination, but discards the result (Destination remains unchanged). Note that it is possible to encode TESTN without any effects, which is entirely pointless.

If the WC or WCZ effect is specified, the C flag is set (1) if the result has odd parity (contains an odd number of high (1) bits), or is cleared (0) if it has even parity (contains an even number of high bits).

If the WZ or WCZ effect is specified, the Z flag is set (1) if the Destination OR Source result equals zero, or is cleared (0) if it is non-zero.

Warning: Easy to confuse with TESTBN

AND performs a bitwise AND of the value in Source into that of Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result has odd parity (contains an odd number of high (1) bits), or is cleared (0) if it has even parity (contains an even number of high bits).

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result equals zero, or is cleared (0) if it is non-zero.

ANDN performs a bitwise AND of the inverse of the value in Source into that of Destination. That is, each high bit in Source will become low in Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result has odd parity (contains an odd number of high (1) bits), or is cleared (0) if it has even parity (contains an even number of high bits).

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result equals zero, or is cleared (0) if it is non-zero.

OR performs a bitwise OR of the value in Source into that of Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result has odd parity (contains an odd number of high (1) bits), or is cleared (0) if it has even parity (contains an even number of high bits).

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result equals zero, or is cleared (0) if it is non-zero.

XOR performs a bitwise XOR of the value in Source into that of Destination.

If the WC or WCZ effect is specified, the C flag is set (1) if the result has odd parity (contains an odd number of high (1) bits), or is cleared (0) if it has even parity (contains an even number of high bits).

If the WZ or WCZ effect is specified, the Z flag is set (1) if the result equals zero, or is cleared (0) if it is non-zero.

TESTB reads the state (0/1) of a bit in Destination designated by Source and either stores it as-is, or bitwise ANDs, ORs, or XORs it into the C or Z flag.

Source[4:0] indicates the bit number (0–31) to test.

If the WC or WZ effect is specified, the C or Z flag is overwritten with the state of the bit.

If the ANDC or ANDZ effect is specified, the C or Z flag is bitwise ANDed with the state of the bit.

If the ORC or ORZ effect is specified, the C or Z flag is bitwise ORed with the state of the bit.

If the XORC or XORZ effect is specified, the C or Z flag is bitwise XORed with the state of the bit.

See also TESTBN.

Warning: Easy to confuse with TEST.

TESTBN reads the state (0/1) of a bit in Destination designated by Source, inverts the result, and either stores it (the inverse value) as-is, or bitwise ANDs, ORs, or XORs it into the C or Z flag.

Source[4:0] indicates the bit number (0–31) to test and invert.

If the WC or WZ effect is specified, the C or Z flag is overwritten with the inverse state of the bit.

If the ANDC or ANDZ effect is specified, the C or Z flag is bitwise ANDed with the inverse state of the bit.

If the ORC or ORZ effect is specified, the C or Z flag is bitwise ORed with the inverse state of the bit.

If the XORC or XORZ effect is specified, the C or Z flag is bitwise XORed with the inverse state of the bit.

See also TESTB.

Warning: Easy to confuse with TESTN.

MUXQ copies all bits from Source corresponding to high (1) bits of the Q Register into the corresponding bits of Destination. All other Destination bits are left as-is.

The current Q value is always used, regardless of whether MUXQ is directly preceded by SETQ (i.e. whether the "SETQ Flag" is set) or not.

MUXNIBS copies any non-zero nibbles from Source into the corresponding nibbles of Destination and leaves the rest of Destination's nibbles as-is.

TODO more detail

MUXNITS copies any non-zero bit pairs from Source into the corresponding bit pairs of Destination and leaves the rest of Destination's bit pairs as-is.

TODO more detail

Flag manipulation

MODC, MODZ, or MODCZ sets or clears the C and/or Z flag based on the mode described by the given modifier symbols and the current state of the C and Z flags. The WC, WZ, and WCZ effects are required to affect the designated flag. Note that it is possible to encode MODCZ without any effects, which is entirely pointless.

These flag modifier instructions allow code to preset flags to a desired state which may be required for entry into certain code routines, or to set a special state based on multiple events that are otherwise not possible to realize with a single instruction.

The possible modifiers are:

Note the logical nature of the encoding: Each bit in the modifier corrosponds to one possible state of [C,Z].

Thus, every modifier with one bit set is an "x AND y" type (only one of four possible states sets the flag), every modifier with 3 bits set is an "x OR y" type (all but one state sets the flag).

MODC is an alias for MODCZ without the Z parameter.

MODZ is an alias for MODCZ without the C parameter.

WRC writes the state of C (0 or 1) to Destination. The entire register is overwritten.

WRNC writes the inverse state of C (0 or 1) to Destination. The entire register is overwritten.

WRZ writes the state of Z (0 or 1) to Destination. The entire register is overwritten.

WRNZ writes the inverse state of Z (0 or 1) to Destination. The entire register is overwritten.

Other

CRCBIT feeds one bit, taken from the C flag, into the CRC checksum in Destination, using the polynomial given in Source.

CRCBIT D,S is equivalent to the following sequence (except that CRCBIT does not change the C flag):

        TESTB  D,#0 xorc
        SHR    D,#1
   if_c XOR    D,S

CRCNIB feeds one nibble, taken from the top 4 bits of the Q Register, into the CRC checksum in Destination, using the polynomial given in Source. The top bit of Q is processed first. Afterwards, Q is shifted left by 4 bits.

To process an entire long, the following sequence can be used:

        SETQ  value
        REP   #1,#8
        CRCNIB checksum,polynomial

XORO32 generates a pseudo-random number based on the seed value in Destination. The next seed value is written back into Destination and the generated pseudo-random number is substituted as the next instruction's Source value (and as a side effect, also written to the Q Register).

Destination's value should never be zero, since that causes the seed to stay zero.

The algorithm used is xoroshiro32++, stepped twice to generate 2x16 bits of data. Due to this, some 32-bit numbers are never generated. Ideal properties are only guaranteed if only the top or bottom 16 bits of the generated number are used. Any subset of bits from either the upper or lower half are also equidistributed.

A software implementation of the algorithm in Spin2:

CON
    A = 13, B = 5, C = 10, D = 9
PUB xoro32_soft(seed) : state,val
  state, val.word[0] := xoro32_half(seed)
  state, val.word[1] := xoro32_half(state)

PRI xoro32_half(seed) : state,val
  val.word[0] := rol16(seed.word[0]+seed.word[1],D)+seed.word[0]
  state := seed
  state.word[1] ^= state.word[0]
  state.word[0] := rol16(state.word[0],A) ^ (state.word[1]<<B) ^ state.word[1]
  state.word[1] := rol16(state.word[1],C)

PRI rol16(val,amount) :r
  val.word[1] := val.word[0]
  return (val rol amount) zerox 15