ra8_epaper_devinfo.c File Reference

IT8951 GET_DEV_INFO response decoder. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_epaper.h"
#include "ra8_err.h"

Include dependency graph for ra8_epaper_devinfo.c:

Go to the source code of this file.

Enumerations
enum	ra8_epaper_devinfo_const_t : uint8_t {   k_ra8_epaper_di_byte_mask = 0xFFU ,   k_ra8_epaper_di_byte_shift = 8U ,   k_ra8_epaper_di_word_shift = 16U ,   k_ra8_epaper_di_ver_per_word = 2U ,   k_ra8_epaper_di_ascii_min = 0x20U ,   k_ra8_epaper_di_ascii_max = 0x7FU }
	Word-unpacking constants (no magic numbers). More...
enum	ra8_epaper_devinfo_idx_t : uint8_t {   k_ra8_epaper_di_idx_width = 0U ,   k_ra8_epaper_di_idx_height = 1U ,   k_ra8_epaper_di_idx_buf_lo = 2U ,   k_ra8_epaper_di_idx_buf_hi = 3U ,   k_ra8_epaper_di_idx_fw = 4U ,   k_ra8_epaper_di_idx_lut = 12U ,   k_ra8_epaper_di_idx_end = 20U }
	Word offsets inside the 20-word GET_DEV_INFO response. More...

Functions
static void	internal_ra8_epaper_unpack_ver_word (uint16_t word, char *dst)
	Unpack one 16-bit version word into two ASCII chars.
static void	internal_ra8_epaper_decode_dev_word (uint32_t idx, uint16_t word, ra8_epaper_dev_info_t *out)
	Fold one GET_DEV_INFO word into the decoded info block.
ra8_err_t	ra8_epaper_decode_dev_info (const uint16_t *words, size_t count, ra8_epaper_dev_info_t *out_info)
	Decode a raw GET_DEV_INFO word block into a device-info struct.

Variables
static const char *const	s_tag = "EPAPER"
	Logging tag used by the null-argument guards in this TU.

Detailed Description

IT8951 GET_DEV_INFO response decoder.

Tag

[Ring 3 / HAL] {World: NS}

The controller answers GET_DEV_INFO (0x0302) with a fixed 20-word block: panel geometry, the two halves of its image-buffer base address, and two 16-character version strings packed two ASCII chars per word. Decoding that block is pure – it touches no bus, no GPIO and no driver state – so it lives here rather than in ra8_epaper.c, alongside the same split that produced ra8_epaper_geom.c.

Separating the decode from the read is what makes it testable. The reported LUT version is the input to ra8_epaper_waveform_cfg_for_lut, and therefore decides which waveform mode number A2 refreshes use; a mis-decoded version string silently selects the wrong mode on a panel nobody has attached yet. As a pure function over a word array, every field of the layout can be pinned by a host test with no controller present.

Version bytes outside printable ASCII are dropped to NUL: the strings are logged, and a controller that has not finished loading its waveform answers early reads with garbage that must not reach a log as control characters.

Copyright

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

Definition in file ra8_epaper_devinfo.c.

Enumeration Type Documentation

ra8_epaper_devinfo_const_t

enum ra8_epaper_devinfo_const_t : uint8_t

Word-unpacking constants (no magic numbers).

Enumerator
k_ra8_epaper_di_byte_mask	Low-byte extraction mask.
k_ra8_epaper_di_byte_shift	Bits per byte.
k_ra8_epaper_di_word_shift	Bits per 16-bit word.
k_ra8_epaper_di_ver_per_word	Version chars per word.
k_ra8_epaper_di_ascii_min	Lowest printable ASCII.
k_ra8_epaper_di_ascii_max	One past printable ASCII.

Definition at line 51 of file ra8_epaper_devinfo.c.

ra8_epaper_devinfo_idx_t

enum ra8_epaper_devinfo_idx_t : uint8_t

Word offsets inside the 20-word GET_DEV_INFO response.

The layout is fixed by the controller firmware, so each word is placed by index rather than by a parser state machine.

Enumerator
k_ra8_epaper_di_idx_width	Panel width.
k_ra8_epaper_di_idx_height	Panel height.
k_ra8_epaper_di_idx_buf_lo	Image-buffer base, low half.
k_ra8_epaper_di_idx_buf_hi	Image-buffer base, high half.
k_ra8_epaper_di_idx_fw	First firmware-version word.
k_ra8_epaper_di_idx_lut	First LUT-version word.
k_ra8_epaper_di_idx_end	One past the last decoded word.

Definition at line 68 of file ra8_epaper_devinfo.c.

Function Documentation

internal_ra8_epaper_decode_dev_word()

void internal_ra8_epaper_decode_dev_word ( uint32_t idx, uint16_t word, ra8_epaper_dev_info_t * out )

static

Fold one GET_DEV_INFO word into the decoded info block.

Geometry first, then the two halves of the image-buffer base address, then the firmware and LUT version strings two ASCII chars per word.

Parameters

[in]	idx	Word index within the 20-word response.
[in]	word	The word to fold in.
[in,out]	out	Info block being assembled; non-NULL.

Precondition

out points at a block zeroed before the first word.

idx is less than k_ra8_epaper_di_idx_end.

Postcondition

Exactly the one field selected by idx is updated.

No bus transaction is issued.

Note

Not thread-safe; called only from the decode loop below.

Since

0.1.0

Definition at line 139 of file ra8_epaper_devinfo.c.

References ra8_epaper_dev_info_t::fw_version, ra8_epaper_dev_info_t::image_buf_base, internal_ra8_epaper_unpack_ver_word(), k_ra8_epaper_di_idx_buf_hi, k_ra8_epaper_di_idx_buf_lo, k_ra8_epaper_di_idx_fw, k_ra8_epaper_di_idx_height, k_ra8_epaper_di_idx_lut, k_ra8_epaper_di_idx_width, k_ra8_epaper_di_ver_per_word, k_ra8_epaper_di_word_shift, ra8_epaper_dev_info_t::lut_version, ra8_epaper_dev_info_t::panel_height, and ra8_epaper_dev_info_t::panel_width.

Referenced by ra8_epaper_decode_dev_info().

internal_ra8_epaper_unpack_ver_word()

void internal_ra8_epaper_unpack_ver_word ( uint16_t word, char * dst )

static

Unpack one 16-bit version word into two ASCII chars.

Version strings arrive packed two characters per word, high byte first. Any byte outside printable ASCII is dropped to NUL so a garbled read cannot inject control characters into a string the app may log.

Parameters

[in]	word	Source word.
[out]	dst	Destination for two chars; non-NULL.

Precondition

dst has room for two chars.

word is one version word of a GET_DEV_INFO response.

Postcondition

dst[0] and dst[1] are printable ASCII or NUL.

No driver state is mutated.

Note

Not thread-safe; called only from the decode loop below.

Since

0.1.0

Definition at line 99 of file ra8_epaper_devinfo.c.

References k_ra8_epaper_di_ascii_max, k_ra8_epaper_di_ascii_min, k_ra8_epaper_di_byte_mask, and k_ra8_epaper_di_byte_shift.

Referenced by internal_ra8_epaper_decode_dev_word().

ra8_epaper_decode_dev_info()

ra8_err_t ra8_epaper_decode_dev_info ( const uint16_t * words, size_t count, ra8_epaper_dev_info_t * out_info )

nodiscard

Decode a raw GET_DEV_INFO word block into a device-info struct.

The controller answers GET_DEV_INFO with 20 big-endian-assembled words: panel width, panel height, the low and high halves of the image-buffer base address, then two 16-character version strings packed two ASCII chars per word. This is the pure decode half of that read – ra8_epaper_init buffers the words off the bus and calls this.

Version bytes outside printable ASCII are dropped to NUL, because the strings are logged and a controller that has not finished loading its waveform answers early reads with garbage.

Split out so the layout can be pinned by host tests with no controller attached: the decoded lut_version is what ra8_epaper_waveform_cfg_for_lut maps to a waveform mode number, so a mis-decode silently selects the wrong A2 mode on the panel.

Parameters

[in]	words	Response words, most significant byte first as assembled by the bus layer; non-NULL.
[in]	count	Number of words available in words; must be at least 20.
[out]	out_info	Receives the decoded block; non-NULL. Fully overwritten, so it need not be pre-zeroed.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Block decoded.
k_ra8_err_null_ptr	words or out_info is NULL.
k_ra8_err_invalid_arg	count is below the 20-word layout.

Precondition

words holds at least count readable words.

out_info is writable.

Postcondition

On success fw_version and lut_version are NUL-terminated.

No bus traffic and no driver state mutated.

Note

Thread-safe: pure function over its arguments.

Example:

ra8_epaper_dev_info_t info = {};
if (ra8_epaper_decode_dev_info(words, 20U, &info) == k_ra8_ok) {
  ra8_epaper_waveform_cfg_t wf = {};
  (void)ra8_epaper_waveform_cfg_for_lut(info.lut_version, &wf);
}

See also

ra8_epaper_dev_info

ra8_epaper_waveform_cfg_for_lut

Since

0.1.0

Definition at line 161 of file ra8_epaper_devinfo.c.

References ra8_epaper_dev_info_t::fw_version, internal_ra8_epaper_decode_dev_word(), k_ra8_epaper_di_idx_end, k_ra8_epaper_ver_chars, k_ra8_err_invalid_arg, k_ra8_ok, ra8_epaper_dev_info_t::lut_version, RA8_CHECK_NULL_PTR, ra8_log_error, and s_tag.

Referenced by internal_ra8_epaper_read_dev_info().

Variable Documentation

s_tag

const char* const s_tag = "EPAPER"

static

Logging tag used by the null-argument guards in this TU.

Definition at line 45 of file ra8_epaper_devinfo.c.