One-call bring-up of the EK-RA8D2 panel's GoodIX GT911 touch controller. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_board_ek_ra8d2_touch.h:

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

Data Structures
struct	ra8_board_touch_cfg_t
	The two touch settings that are an APPLICATION choice, not a board fact. More...

Functions
ra8_err_t	ra8_board_touch_open (const ra8_board_touch_cfg_t *cfg)
	Bring the on-board GT911 up and open the touch driver against it.

Detailed Description

One-call bring-up of the EK-RA8D2 panel's GoodIX GT911 touch controller.

Tag: [Ring 5 / BSP] {World: S}

The board has one touch controller, on one bus, at one address – and getting at it nonetheless cost every application four checked calls (ra8_i3c_init -> ra8_io_i2c_bus_bind_i3c_compat -> ra8_io_i2c_bus_as_ops -> ra8_touch_open) plus four constants it had to know: the channel, the 7-bit address, the bus rate and the clock feeding the bit-rate divider. Eight applications wrote that block, and all eight hardcoded the same 60 MHz source clock rather than asking ra8_cgc_get_clock_hz – so on this project's 125 MHz PCLKA tree the touch bus was not running at the 400 kHz any of them asked for. ra8_board_touch_open is the board's answer to all four questions at once, and it solves the divider against the LIVE clock.

The seam underneath is untouched: ra8_touch_open still takes an injected ra8_i2c_bus_ops_t, ra8_i3c_init and the ra8_io_i2c_bus_* binders are still public, and a custom carrier board that puts the GT911 somewhere else still wires it up by hand. This is a shortcut to the ON-BOARD wiring, not a replacement for the injection point. Same shape as ra8_board_pdm_mic_route for the microphone and ra8_board_camera_select_parallel for the camera; touch was the one on-board sensor that never got it.

OPT-IN, DELIBERATELY. This header is NOT pulled in by the ra8_board_ek_ra8d2.h umbrella, and the translation unit behind it is compiled into an application only when that application declares ra8_io or ra8_io_bus in its LIBS: the bus binding it performs lives in libs/ra8_io, which is not on every app's include path.

const ra8_board_touch_cfg_t cfg = {};  // board defaults, polled
if (ra8_board_touch_open(&cfg) != k_ra8_ok) {
  // UI still renders; taps just do not arrive.
}

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

Since: 0.1.0

Definition in file ra8_board_ek_ra8d2_touch.h.

Function Documentation

◆ ra8_board_touch_open()

ra8_err_t ra8_board_touch_open ( const ra8_board_touch_cfg_t * cfg )

nodiscard

Bring the on-board GT911 up and open the touch driver against it.

Reads PCLKA from ra8_cgc_get_clock_hz and initialises the board's I3C channel in I2C-compatibility mode at k_ra8_board_touch_bus_hz against that live rate, binds the channel through the ra8_io_i2c_bus facade, projects it as an ra8_i2c_bus_ops_t, and opens ra8_touch at k_ra8_board_touch_target_7b.

Parameters

[in] cfg Application-side settings; see ra8_board_touch_cfg_t. Must not be null. max_points must be 0 or at most k_ra8_touch_max_points.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The GT911 answered and the driver is open.
k_ra8_err_null_ptr	`cfg` was null.
k_ra8_err_invalid_arg	max_points exceeds the GT911's capacity.
k_ra8_err_invalid_state	ra8_touch_open was already called.
k_ra8_err_hw_timeout	The I3C block did not come out of module stop, or the GT911 did not answer.
k_ra8_err_*	Any other code propagated unchanged from ra8_i3c_init or ra8_touch_open.

Precondition: ra8_cgc_init() has run, so PCLKA reflects the application's clock tree rather than the reset default.; SW4-5 selects the I3C routing for P400 / P401 (UM Table 20 p 28), and the Parallel Graphics Expansion Board is fitted.

Postcondition: On success the touch driver is open and ra8_touch_read may be called; the board's I3C channel is initialised in I2C-compat mode.; On any non-ok return the touch driver is left closed. The I3C channel may already have been initialised, which is harmless and idempotent.

Note: Not thread-safe; call once from the single-threaded bring-up path.

Warning: The bus rate is only as accurate as PCLKA at the moment of the call. An application that retunes CGC afterwards must re-open, or call ra8_i3c_set_clock with the new rate.

See also: ra8_board_touch_wiring_t The board facts this call spends.; ra8_touch_read Reading contacts once this has succeeded.

Since: 0.1.0

Definition at line 60 of file ra8_board_ek_ra8d2_touch.c.

References ra8_board_touch_cfg_t::irq_pin, k_ra8_board_touch_bus_hz, k_ra8_board_touch_i3c_channel, k_ra8_board_touch_target_7b, k_ra8_clock_id_pclka, k_ra8_err_invalid_arg, k_ra8_i3c_mode_i2c, k_ra8_ok, k_ra8_touch_max_points, ra8_board_touch_cfg_t::max_points, ra8_cgc_get_clock_hz(), RA8_CHECK_NULL_PTR, ra8_i3c_init(), ra8_io_i2c_bus_as_ops(), ra8_io_i2c_bus_bind_i3c_compat(), ra8_touch_open(), s_tag, and s_touch_bus.

Referenced by app_bringup_touch(), cm_bringup_touch(), ez_bringup_touch(), internal_tc_touch_bringup(), main(), mg_bringup_touch(), and sh_input_init().

Data Structures

Functions

Detailed Description

Function Documentation

◆ ra8_board_touch_open()