board_periph_eink.h File Reference

IT8951 e-paper SPI-device model for ra8_emulator (attached to SPI_B). More...

#include <stdint.h>

Include dependency graph for board_periph_eink.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
bool	board_eink_attach (void)
	Attach (arm) the modelled IT8951 e-paper controller.
bool	board_eink_attached (void)
	Report whether the IT8951 controller is currently attached.
uint8_t	board_eink_exchange (uint8_t tx)
	Exchange one full-duplex SPI byte with the modelled controller.
void	board_eink_reset (void)
	Reset the controller's command / read framing to power-on.
void	board_eink_apply_gpio_defaults (void)
	Re-arm the panel HRDY "ready" GPIO input high (if attached).
void	board_eink_report (void)
	Print the controller's end-of-run summary line (if attached).

Detailed Description

IT8951 e-paper SPI-device model for ra8_emulator (attached to SPI_B).

Models a Waveshare / IT8951 e-paper timing controller sitting on the SPI_B bus, so the epaper_refresh example drives the genuine firmware path – ra8_epaper (Ring 3 HAL) through the ra8_display_pal_eink backend (Ring 4 PAL) over ra8_io_spi_bus – against a responding controller with no physical panel.

The controller is attached with --eink. Two seams tie it into the rest of the emulator, mirroring the way board_periph_sd.c attaches an SD card:

• The SPI_B block model (board_periph_spi.c) routes each SPDR byte exchange into board_eink_exchange when a controller is attached and the channel is NOT in internal loopback, so the firmware's real preamble / command / register / image-load / display path runs byte for byte.
• The GPIO/PORT block model (board_periph_gpio.c) calls board_eink_apply_gpio_defaults from its power-on reset so the panel's HRDY "ready" line reads high – the firmware polls HRDY before every preamble, so without it ra8_epaper_init would time out.

The IT8951 SPI protocol modelled here follows the IT8951 datasheet rev 0.2 chapter 3.4 "SPI Interface" + chapter 4 "Application Note": every transaction opens with a 16-bit preamble (0x6000 command / 0x0000 data write / 0x1000 data read), then the host clocks 16-bit words MSB-first. The model assembles those words from the byte stream and answers reads (GET_DEV_INFO device block, register reads such as LUTAFSR "LUT idle") so the driver completes exactly as it would on silicon.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file board_periph_eink.h.

Function Documentation

board_eink_apply_gpio_defaults()

void board_eink_apply_gpio_defaults

(

void

)

Re-arm the panel HRDY "ready" GPIO input high (if attached).

Drives the modelled HRDY pin high through board_periph_gpio_set_input so the firmware's ra8_gpio_read of the busy line returns "ready". Called from the GPIO/PORT block's power-on reset AFTER it clears every port, so the level survives the reset that would otherwise clear it. A no-op when no controller is attached.

Returns

None.

Precondition

The GPIO/PORT block model is registered.

Called after the GPIO block cleared its ports.

Postcondition

When attached, the HRDY pin reads high.

When not attached, no GPIO state is modified.

Note

Not thread-safe.

Since

0.1.0

Definition at line 452 of file board_periph_eink.c.

References board_periph_gpio_set_input(), k_eink_hrdy_pin, k_eink_hrdy_port, and s_eink.

Referenced by internal_port_reset().

board_eink_attach()

bool board_eink_attach

(

void

)

Attach (arm) the modelled IT8951 e-paper controller.

Sets the module's armed flag so board_eink_attached returns true and the SPI_B block routes byte exchanges into board_eink_exchange. Idempotent: a second call is a no-op. Panel geometry is the fixed demo size the model reports through GET_DEV_INFO.

Returns

true once the controller is armed and serving.

Return values

true	Controller armed (always, on this in-memory model).

Precondition

Called once during ra8_emulator start-up (single-threaded arg parse).

No physical hardware is required.

Postcondition

board_eink_attached returns true.

The command / read framing is reset to power-on.

Note

Not thread-safe.

Since

0.1.0

Definition at line 397 of file board_periph_eink.c.

References board_eink_reset(), and s_eink.

Referenced by internal_args_try_mode().

board_eink_attached()

bool board_eink_attached

(

void

)

Report whether the IT8951 controller is currently attached.

Returns

true if --eink armed the controller.

Return values

false	No --eink was passed.
true	--eink armed the controller.

Precondition

None.

None.

Postcondition

No state is modified.

No state is modified.

Note

Not thread-safe.

Since

0.1.0

Report whether the it8951 controller is currently attached; this step is contained within the board periph eink model and uses bounded caller or module-owned storage.

Definition at line 404 of file board_periph_eink.c.

References s_eink.

Referenced by internal_spi_spdr_write().

board_eink_exchange()

uint8_t board_eink_exchange

(

uint8_t

tx

)

Exchange one full-duplex SPI byte with the modelled controller.

Advances the IT8951 byte state machine: assembles 16-bit words from the host TX stream, latches preambles / commands / register + image data, and returns the controller's response byte during a read burst (0xFF idle otherwise).

Parameters

[in]

tx

Byte clocked out by the host (host-out).

Returns

The byte the controller drives back (controller-out).

Return values

0	Bus idle / no read byte pending.

Precondition

A controller is attached (board_eink_attached is true).

None.

Postcondition

The model's command / read framing may advance by one byte.

The captured pixel / refresh counters may advance.

Note

Not thread-safe.

Since

0.1.0

Definition at line 409 of file board_periph_eink.c.

References internal_eink_consume_word(), k_eink_byte_shift, k_eink_idle_byte, and s_eink.

Referenced by internal_spi_spdr_write().

board_eink_report()

void board_eink_report

(

void

)

Print the controller's end-of-run summary line (if attached).

One injected error sink line reporting the pixels loaded and refreshes issued, so a run visibly exercised the image-load + display path. A no-op when no controller is attached.

Returns

None.

Precondition

None.

None.

Postcondition

No model state is modified.

At most one line is written to injected error sink.

Note

Not thread-safe.

Since

0.1.0

Definition at line 460 of file board_periph_eink.c.

References priv_emu_io_errf(), and s_eink.

Referenced by internal_spi_report().

board_eink_reset()

void board_eink_reset

(

void

)

Reset the controller's command / read framing to power-on.

Clears the in-flight word assembly, current command, register-read target and read cursor; the armed / attached flag is preserved. Called from the SPI_B block's power-on reset (board_periph_spi.c).

Returns

None.

Precondition

None.

None.

Postcondition

The byte state machine is back at "expect preamble".

The attached flag is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 435 of file board_periph_eink.c.

References internal_eink_px_per_word(), k_eink_st_preamble, k_eink_vcom_power_on_mv, k_eink_wire_pf_8bpp, and s_eink.

Referenced by board_eink_attach(), and internal_spi_reset().