gba-types

Structs for GBA MMIO

lib.rs:

gba-types contains data types for interacting with the GBA's MMIO registers.

The most important types here are generated by the bitstruct_newtype! macro:

• It's an opaque struct that wraps a primitive unsigned integer value
• Each "field" in the struct is bit-packed inside of the integer data.
• A field is often less than 8 bits, but could be more than 8 bits, and even could be exactly 8 bits.
  • Single-bit fields are bools.
  • Some multi-bit fields are integers within a reduced range. For example, a Color value has RGB channels, but only 5 bits per channel, so only the range 0 through 31 is allowed.
  • Some multi-bit fields are basically enums, but for increased FFI safety, we use a "const_enum" macro (see below) instead of actual Rust enum types.
• Each field has both a getter and a setter. Many MMIO locations aren't both readable and writable in all fields, but even so every struct has getters and setters for all fields just to make the in-memory manipulation of a value as easy as possible.

This crate also contains some helper types that are considered to be a const_enum! type:

• This is an opaque value that should only be one of a specific list of associated consts.
• Like with a normal enum, the bit pattern of the value isn't important, what's important is some semantic meaning other than the literal number value.
• Unlike with a normal enum, because this is a wrapped integer it's more FFI friendly. If an illegal bit pattern does somehow get read in from a register then it won't instantly cause UB.

Nightly Only

• This crate utilizes the const_mut_refs nightly feature to allow both the setter functions to be const. This will probably become stable "sooner rather than later", particularly compared to some of the other nightly features that GBA programming is likely to use.