Editing Spec.isa (section)

=== Addendum: Masking ===
On several occasions through this document, "mask it out" has been noted as a solution to various bit width problems.  While masking is a fairly common and well-known operation in computer programming, this section will describe it for the sake of completeness.

There are several kinds of masking you hear of on occasion, with the most prominent by far being the ability to extract one or more individual bits from a larger number.  This is performed by ANDing the value you want to extract the bits from with a ''mask'', which is a second number containing <code>1</code> in bit positions you wish to extract, and <code>0</code> elsewhere.  For example, if we have the number <code>90</code> and wish to extract the bottom four bits, we can use the following code (in [[#Virtual_operands|virtual operand]] syntax):
<pre>
%value = 90
%masked = %value & 0b1111
</pre>

This will return the value 10 (<code>1010</code>).

One thing to be careful of is that the bits you select with your mask will remain in the position they were originally.  If we instead want the top four bits and try to use the code:
<pre>
%value = 90
%masked = %value & 0b11110000
</pre>
we will end up with the value 80 (<code>01010000</code>).  We would need to perform an additional shift operation if we wanted to extract those four bits into an actual four-bit number:
<pre>
%value = 90
%masked = (%value & 0b11110000) >> 4
</pre>
will return the value 5 (<code>0101</code>) that we were looking for.

==== An alternative ====
The game's bit slicing syntax provides an alternative method for extracting higher bits:
<pre>
%value = 90
%masked = %value[7:4]
</pre>
will also return the value 5.  There is no need to shift in this case, as the bit slicing operator treats the lower bound as the LSB of the extracted value.

==== Constructing a mask ====
Using hexits or even bits to describe a mask is easy enough if you're working with fairly small constant values (a full 64-bit mask is 16 hexits!  That's a lot to write out already, never mind trying to write it in binary!)  If you're working with non-constant values however, or if you just don't want to manually work out such large numbers, you can create your own mask with shifts and ORs.  For example, if you want the 38th bit, you can simply use:
<pre>
%mask = 1 << 38
</pre>
{{note|type=info|This shift operation counts bits starting at 0, so your LSB will be <code>1&nbsp;&lt;&lt;&nbsp;0</code>, not <code>1&nbsp;&lt;&lt;&nbsp;1</code>, despite it often being referred to as the "first" bit.}}

If you want the three bits from the 36th through the 38, you can OR them together like so:
<pre>
%bit36 = 1 << 36
%bit37 = 1 << 37
%bit38 = 1 << 38
%mask = %bit36 | %bit37 | %bit38
</pre>

That is obviously going to get very cumbersome if you want to extract 8 or 16 or more bits.  We can use a nice property of binary numbers to simplify this however:  <code>1&nbsp;&lt;&lt;&nbsp;n</code> has a single bit set at position <code>n</code>, so <code>(1&nbsp;&lt;&lt;&nbsp;n)-1</code> has that single bit cleared and all lowest <code>n</code> bits set:
<pre>
%mask = (1<<39)-1
</pre>
will return a mask with the lowest 39 bits enabled.
{{note|type=info|We want to include %bit38 from the prior example, so we need to go one higher before subtracting!}}

But we can do better!  If we want to recreate the 3-bit mask from above, we can construct it by using a second mask to "turn off" some of the lower bits from the first mask:
<pre>
%hi_mask = (1<<39)-1
%lo_mask = (1<<36)-1
%mask = %hi_mask ^ %lo_mask
</pre>
This initially creates <code>%hi_mask</code> with the lowest 39 bits enabled, as before.  It then creates <code>%lo_mask</code> with only the lowest 36 bits enabled.  The XOR operation performs the task of "turning off" the lower 36 bits:
* bits 0..35 are turned off because <code>1^1&nbsp;=&nbsp;0</code>
* bits 36..38 remain on because <code>1^0&nbsp;=&nbsp;1</code>
* bits 39..63 remain off because <code>0^0&nbsp;=&nbsp;0</code>

Finally, we can perform a shift to fully encapsulate the bit slicing behavior.  In fact, we don't even need to "turn off" the lower bits this time, as we'll be shifting them out:
<pre>
%mask = (1<<39)-1
%value = 0x123456789ABCDEF
%extracted = (%value & %mask) >> 36
</pre>

==== Putting it all together ====

While not terribly useful as anything more than a teaching example, we can combine several of the techniques from above create to generic mask that functions the same as the bit slicing operation <code>%value[%top:%bottom]</code>:
<pre>
%zerofix = 0 - ((0 - popcount(%top)) >> 63)
%mask = (1 << %top) | (((1 << ((%top - 1) & %zerofix)) - 1) << 1) | 1
%value = 0x123456789ABCDEF
%extracted = (%value & %mask) >> %bottom
</pre>
{{note|type=error|1=The highest bit (63) currently causes a lot of problems, many of which crash the game.  A bit of a description of what's happening there:
* <code>0 - popcount(%top)</code> will return zero if <code>%top</code> is zero, or a negative value if <code>%top</code> is greater than zero (it's an unsigned operand so we don't have to worry about it being less than zero!).
* <code>(0 - popcount(%top)) >> 63</code> extracts just the sign bit: <code>1</code> if the subtraction is negative (and therefore <code>%top&gt;0</code>) or zero if <code>%top=0</code>.
* <code>0 - ((0 - popcount(%top)) >> 63)</code> will again return <code>0</code> if the previous step was zero, but it will return <code>-1</code> if the previous step is <code>1</code>, giving us a mask with either all 64 bits clear or all 64 bits set.
* <code>(%top - 1) & %zerofix</code> will give us zero if <code>%top</code> is zero, by using the all-zeroes mask from the prior step to erase the <code>-1</code> we'd otherwise expect from the subtraction.  If <code>%top</code> is not zero, we accept whatever <code>%top - 1</code> is, using the all-ones mask from the prior step.  This gives us a shift value between 0 and 62 (importantly, not 63.  The whole point of this mess is to remove 63 from our potential range of values).
* <code>((1 << ((%top - 1) & %zerofix)) - 1) &lt;&lt; 1</code> creates the (up to) 62-bit mask as described in the prior sections, and then shifts it over to compensate for the <code>-&nbsp;1</code> we took out initially.
* <code>{{!}} 1</code> fills in the gap created by the shift, and gives us the 63rd bit of our mask.  We can always assume this is valid as our smallest possible mask is <code>1&nbsp;&lt;&lt;&nbsp;0</code> (only the LSB), and every larger mask necessarily also includes the LSB.
* <code>(1 << %top)</code> is the 64th bit of our mask (maximally).  While bit 63 can have a lot of problems with arithmetic operations such as subtraction, it's generally safe with bitwise operations like <code>&lt;&lt;</code> and <code><nowiki>|</nowiki></code>.
These issues will presumably be fixed (or at least no longer crash) as the alpha branch matures, but in the meantime these types of workarounds are necessary (and even when it's fully mature you still won't be able to do <code>1&lt;&lt;64</code> (or whatever the maximum bit width is by then), so some smaller workarounds will still be needed even if they aren't crashing the game).}}

The various methods can also be combined (using AND, OR, XOR, etc.) to create all sorts of interesting masks.  For the most part though, mask-and-shift of contiguous bits is far more commonly used than "interesting" masks.