126 lines
5.9 KiB
Markdown
126 lines
5.9 KiB
Markdown
Integer as Bit-Fields
|
||
=====================
|
||
|
||
{{#include ../links.md}}
|
||
|
||
```admonish note.side
|
||
|
||
Nothing here cannot be done via standard bit-manipulation (i.e. shifting and masking).
|
||
|
||
Built-in support is more elegant and performant since it usually replaces a sequence of multiple steps.
|
||
|
||
```
|
||
|
||
Since bit-wise operators are defined on integer numbers, individual bits can also be accessed and
|
||
manipulated via an indexing syntax.
|
||
|
||
If a bit is set (i.e. `1`), the index access returns `true`.
|
||
|
||
If a bit is not set (i.e. `0`), the index access returns `false`.
|
||
|
||
When a [range] is used, the bits within the [range] are shifted and extracted as an integer value.
|
||
|
||
Bit-fields are very commonly used in embedded systems which must squeeze data into limited memory.
|
||
Built-in support makes handling them efficient.
|
||
|
||
Indexing an integer as a bit-field is disabled for the [`no_index`] feature.
|
||
|
||
|
||
Syntax
|
||
------
|
||
|
||
### From Least-Significant Bit (LSB)
|
||
|
||
Bits in a bit-field are accessed with zero-based, non-negative integer indices:
|
||
|
||
> _integer_ `[` _index from 0 to 63 or 31_ `]`
|
||
>
|
||
> _integer_ `[` _index from 0 to 63 or 31_ `] =` `true` or `false` ;
|
||
|
||
[Ranges] can also be used:
|
||
|
||
> _integer_ `[` _start_ `..` _end_ `]`
|
||
> _integer_ `[` _start_ `..=` _end_ `]`
|
||
>
|
||
> _integer_ `[` _start_ `..` _end_ `] =` _new integer value_ ;
|
||
> _integer_ `[` _start_ `..=` _end_ `] =` _new integer value_ ;
|
||
|
||
```admonish warning.small "Number of bits"
|
||
|
||
The maximum bit number that can be accessed is 63 (or 31 under [`only_i32`]).
|
||
|
||
Bits outside of the range are ignored.
|
||
```
|
||
|
||
|
||
### From Most-Significant Bit (MSB)
|
||
|
||
A _negative_ index accesses a bit in the bit-field counting from the _end_, or from the
|
||
_most-significant bit_, with −1 being the _highest_ bit.
|
||
|
||
> _integer_ `[` _index from −1 to −64 or −32_ `]`
|
||
>
|
||
> _integer_ `[` _index from −1 to −64 or −32_ `] =` `true` or `false` ;
|
||
|
||
[Ranges] always count from the least-significant bit (LSB) and has no support for negative positions.
|
||
|
||
```admonish warning.small "Number of bits"
|
||
|
||
The maximum bit number that can be accessed is −64 (or −32 under [`only_i32`]).
|
||
```
|
||
|
||
|
||
Bit-Field Functions
|
||
-------------------
|
||
|
||
The following standard functions (defined in the [`BitFieldPackage`][built-in packages] but excluded
|
||
when using a [raw `Engine`]) operate on `INT` bit-fields.
|
||
|
||
These functions are available even under the [`no_index`] feature.
|
||
|
||
| Function | Parameter(s) | Description |
|
||
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
||
| `get_bit` | bit number, counting from MSB if < 0 | returns the state of a bit: `true` if `1`, `false` if `0` |
|
||
| `set_bit` | <ol><li>bit number, counting from MSB if < 0</li><li>new state: `true` if `1`, `false` if `0`</li></ol> | sets the state of a bit |
|
||
| `get_bits` | <ol><li>starting bit number, counting from MSB if < 0</li><li>number of bits to extract, none if < 1, to MSB if ≥ _length_</li></ol> | extracts a number of bits, shifted towards LSB |
|
||
| `get_bits` | [range] of bits | extracts a number of bits, shifted towards LSB |
|
||
| `set_bits` | <ol><li>starting bit number, counting from MSB if < 0</li><li>number of bits to set, none if < 1, to MSB if ≥ _length_<br/>3) new value</li></ol> | sets a number of bits from the new value |
|
||
| `set_bits` | <ol><li>[range] of bits</li><li>new value</li></ol> | sets a number of bits from the new value |
|
||
| `bits` method and property | <ol><li>_(optional)_ starting bit number, counting from MSB if < 0</li><li>_(optional)_ number of bits to extract, none if < 1, to MSB if ≥ _length_</li></ol> | allows iteration over the bits of a bit-field |
|
||
| `bits` | [range] of bits | allows iteration over the bits of a bit-field |
|
||
|
||
|
||
Example
|
||
-------
|
||
|
||
```js , no_run
|
||
// Assume the following bits fields in a single 16-bit word:
|
||
// ┌─────────┬────────────┬──────┬─────────┐
|
||
// │ 15-12 │ 11-4 │ 3 │ 2-0 │
|
||
// ├─────────┼────────────┼──────┼─────────┤
|
||
// │ 0 │ 0-255 data │ flag │ command │
|
||
// └─────────┴────────────┴──────┴─────────┘
|
||
|
||
let value = read_start_hw_register(42);
|
||
|
||
let command = value.get_bits(0, 3); // Command = bits 0-2
|
||
|
||
let flag = value[3]; // Flag = bit 3
|
||
|
||
let data = value[4..=11]; // Data = bits 4-11
|
||
let data = value.get_bits(4..=11); // <- above is the same as this
|
||
|
||
let reserved = value.get_bits(-4); // Reserved = last 4 bits
|
||
|
||
if reserved != 0 {
|
||
throw reserved;
|
||
}
|
||
|
||
switch command {
|
||
0 => print(`Data = ${data}`),
|
||
1 => value[4..=11] = data / 2,
|
||
2 => value[3] = !flag,
|
||
_ => print(`Unknown: ${command}`)
|
||
}
|
||
```
|