liveBook · Manning

C-style enum

As explained in Embedded Software with Rust

A C type whose values are named enumerators.

A C enum gives names to values, but its size depends on the compiler’s default. That can make its representation disagree with a Rust enum across a C interface. section 8.2.4

For a fixed-width interface, give the Rust enum an explicit representation and replace the C enum with a fixed-width integer typedef and named constants. section 8.2.4

#[repr(u8)]
pub enum DeviceState {
    Idle = 0,
    Active = 1,
    Error = 2,
}

This Rust enum uses a one-byte representation and assigns explicit values to its variants. section 8.2.4

// C side
typedef uint8_t DeviceState;

#define DEVICE_STATE_IDLE   0
#define DEVICE_STATE_ACTIVE 1
#define DEVICE_STATE_ERROR  2

The corresponding C typedef is an alias for uint8_t, not a true enum. The constants provide readable names for the agreed values. section 8.2.4

The typedef can be used in function signatures and struct fields; the state field occupies one byte. The trade-off is that the constants do not prevent an arbitrary byte, such as 4, from being assigned. section 8.2.4

#[repr(transparent)]
pub struct DeviceState(pub u8);

pub const DEVICE_STATE_IDLE: DeviceState = DeviceState(0);
pub const DEVICE_STATE_ACTIVE: DeviceState = DeviceState(1);
pub const DEVICE_STATE_ERROR: DeviceState = DeviceState(2);

enum CheckedDeviceState {
    Idle,
    Active,
    Error,
}

impl DeviceState {
    fn checked(self) -> Option<CheckedDeviceState> {
        match self.0 {
            0 => Some(CheckedDeviceState::Idle),
            1 => Some(CheckedDeviceState::Active),
            2 => Some(CheckedDeviceState::Error),
            _ => None,
        }
    }
}

A transparent Rust wrapper can hold the incoming byte and check it before treating it as a known state. section 8.2.4

#[unsafe(no_mangle)]
pub extern "C" fn advance_state(current: DeviceState) -> DeviceState {
    let next = match current.checked() {
        Some(CheckedDeviceState::Idle) => CheckedDeviceState::Active,
        Some(CheckedDeviceState::Active) => CheckedDeviceState::Error,
        Some(CheckedDeviceState::Error) => CheckedDeviceState::Error,
        None => CheckedDeviceState::Error, // an invalid byte from C is treated as a fault
    };

    match next {
        CheckedDeviceState::Idle => DEVICE_STATE_IDLE,
        CheckedDeviceState::Active => DEVICE_STATE_ACTIVE,
        CheckedDeviceState::Error => DEVICE_STATE_ERROR,
    }
}

This function treats an unrecognized byte from C as a fault state. section 8.2.4

How Embedded Software with Rust covers it

How deep it goes
Works through fixed-width declarations, function and struct usage, and validation of incoming values.
Examples
Traces device states through a state-advancing function and a status struct.
What you can do after
Apply fixed-width representations and validate incoming state values at a Rust-C boundary.
How it connects
Connects enum representation with typedefs, transparent wrappers, and value validation.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Embedded Software with Rust. The section links point to the parts of the book it draws on.