Bitwise operations
Many devices have registers. These are a small number of binary numbers stored in the device and used to control the device or read its sensors.
Often, several values are stored in one register. This means we have to do some programming to manipulate the separate values stored together in one register. For example a display may have an adjustable brightness and and adjustable contrast. These may be stored together in one register.
The problem arises when we have primitives to read or write an entire register, but we only want to read or write one of the values stored in the register.
For this we use a binary "mask". The mask indicates with '1' or '0' which bits we want to process. Mostly people use '1' to indicate the bits that should be processed, but either works. You just have to know which you are using.
Before we can explain the use of a mask we have to explain the bitwise boolean operations.
The "and" operation
The boolean bitwise "and" operation is an operation on two binary numbers that gives a result. It is written:
result = left & right
For each position in the binary number, the result is '1' only if both the inputs have '1' in that position. So:
- 0 & 0 == 0
- 0 & 1 == 0
- 1 & 0 == 0
- 1 & 1 == 1
For a single digit binary number the "&" operation is like multiplication, usually written with "*" on computers.
- 0 * 0 == 0
- 0 * 1 == 0
- 1 * 0 == 0
- 1 * 1 == 1
We can use the bitwise "and" operation with a mask value as follows. Let's say we want to change bits 3 to 7 in a value (bits are counted from the right, starting with 0). We can make a mask that has ones in positions 3 to 7. Binary numbers are written with 0b in Toit, and we can insert underscores anywhere we want to improve readability.
MASK := 0b000000000_1111_000
This mask value has zeros everywhere except in the area we are interested in, positions 3 to 7. For every mask there is the opposite mask, with all the bits reversed:
ANTI_MASK ::= 0b111111111_0000_111
If we have one mask, we can make the other one with the tilde (~) operator:
ANTI_MASK ::= ~MASK // This does the same.
Now if we want to change the bits 3-7 in a value to be 1010 regardless of what they were before we start by zeroing bits 3-7. This can be done with the anti-mask:
value 101010101_0101_010
antimask 111111111_0000_111
------------------ & operation ("and")
new value 101010101_0000_010
^^^^------- the zeroed bits are here.The masking operation has zeroed the bits from 3-7, while the other bits in the value are untouched.
The "or" operation
To set the bits to a desired value, we use the "or" operation which is the pendant to the "and" operation, and is written with the vertical pipe sign "|".
- 0 | 0 == 0
- 0 | 1 == 1
- 1 | 0 == 1
- 1 | 1 == 1
Let's say we want to set bits 3-7 to 1100. We would use an "or" operation on a number with the bits in that place and zeroes in all other places.
new value 101010101_0000_010
number 000000000_1100_000
------------------ | operation ("or")
new2 value 101010101_1100_010
^^^^------ the 1100 has been inserted here.Putting it all together
Perhaps we have a device with an 8-bit register that has two fields. The low 4 bits control brightness, and the high 4 control contrast. There are some constants:
BRIGHTNESS_0 ::= 0b0000 BRIGHTNESS_1 ::= 0b0001 BRIGHTNESS_2 ::= 0b0010 BRIGHTNESS_3 ::= 0b0011 BRIGHTNESS_4 ::= 0b0100 BRIGHTNESS_5 ::= 0b0101 BRIGHTNESS_6 ::= 0b0110 BRIGHTNESS_7 ::= 0b0111 BRIGHTNESS_8 ::= 0b1000 BRIGHTNESS_9 ::= 0b1001 BRIGHTNESS_10 ::= 0b1010 BRIGHTNESS_11 ::= 0b1011 BRIGHTNESS_12 ::= 0b1100 BRIGHTNESS_13 ::= 0b1101 BRIGHTNESS_14 ::= 0b1110 BRIGHTNESS_15 ::= 0b1111 CONTRAST_0 ::= 0b0000_0000 CONTRAST_1 ::= 0b0001_0000 CONTRAST_2 ::= 0b0010_0000 CONTRAST_3 ::= 0b0011_0000 CONTRAST_4 ::= 0b0100_0000 CONTRAST_5 ::= 0b0101_0000 CONTRAST_6 ::= 0b0110_0000 CONTRAST_7 ::= 0b0111_0000 CONTRAST_8 ::= 0b1000_0000 CONTRAST_9 ::= 0b1001_0000 CONTRAST_10 ::= 0b1010_0000 CONTRAST_11 ::= 0b1011_0000 CONTRAST_12 ::= 0b1100_0000 CONTRAST_13 ::= 0b1101_0000 CONTRAST_14 ::= 0b1110_0000 CONTRAST_15 ::= 0b1111_0000
We only have the operations read_register and write_register,
but we want to adjust the two values independently:
class MyDevice extends OneRegisterDevice:
// Constructor...
get_brightness -> int:
reg := read_register
return reg & BRIGHTNESS_MASK_
get_contrast -> int:
reg := read_register
return reg & CONTRAST_MASK_
set_brightness brightness/int -> none:
reg := read_register
// Remove the old brightness with the mask.
reg &= ~BRIGHTNESS_MASK_
// Insert the new brightness with the "or" operation.
reg |= brightness
// Write back the old contrast and the new brightness.
write_register reg
set_contrast contrast/int -> none:
reg := read_register
// Remove the old brightness with the mask.
reg &= ~CONTRAST_MASK_
// Insert the new contrast with the "or" operation.
reg |= contrast
// Write back the new contrast and the old brightness.
write_register reg
BRIGHTNESS_MASK_ ::= 0b0000_1111
CONTRAST_MASK_ ::= 0b1111_0000Using the shift operations
In the example above, the user of the driver could choose between 16 discrete contrast levels, but perhaps the user wants to do a calculation. In that case they have perhaps calculated number between 0 and 15, and would like to use that. We can do that with the help of the shift operators, "<<" and ">>".
The shift operations move the bits of a binary number around. For example, the ">>" operator moves them to the right.
value := 0b00101000000 value = value >> 3 // Now value == 0b00000101000 value <<= 4 // Now value == 0b01010000000
Using this operation we could rewrite our MyDevice to take values from 0 to 15 instead of the constants:
class MyDevice extends OneRegisterDevice:
// Constructors...
/// Get the current brightness from 0-15.
get_brightness -> int:
reg := read_register
return (reg & BRIGHTNESS_MASK_) >> BRIGHTNESS_SHIFT_
/// Get the current contrast from 0-15.
get_contrast -> int:
reg := read_register
return (reg & CONTRAST_MASK_) >> CONTRAST_SHIFT_
/// Set the current brightness from 0-15.
set_brightness brightness/int -> none:
assert: 0 <= brightness <= 15
reg := read_register
// Remove the old brightness with the mask.
reg &= ~BRIGHTNESS_MASK_
// Insert the new brightness with the "or" operation.
reg |= brightness << BRIGHTNESS_SHIFT_
// Write back the old contrast and the new brightness.
write_register reg
/// Set the current contrast from 0-15.
set_contrast contrast/int -> none:
assert: 0 <= contrast <= 15
reg := read_register
// Remove the old contrast with the mask.
reg &= ~CONTRAST_MASK_
// Insert the new contrast with the "or" operation.
reg |= contrast << CONTRAST_SHIFT_
// Write back the new contrast and the old brightness.
write_register reg
// The brightness is stored in the low 4 bits, and the
// contrast is stored in the high 4 bits.
BRIGHTNESS_MASK_ ::= 0b0000_1111
CONTRAST_MASK_ ::= 0b1111_0000
BRIGHTNESS_SHIFT_ ::= 0
CONTRAST_SHIFT_ ::= 4