Multi-touch input driver – GoodIX GT911 backend. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_i2c_bus_ops.h"

Include dependency graph for ra8_touch.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_touch_point_t
	One decoded touch contact. More...
struct	ra8_touch_cfg_t
	Configuration descriptor for ra8_touch_open. More...

Typedefs
typedef void(*	ra8_touch_event_fn_t) (void *ctx)
	Touch-event callback signature.

Enumerations
enum	ra8_touch_limits_t : uint8_t { k_ra8_touch_max_points = 5U , k_ra8_touch_irq_pin_unset = 32U }
	Static-allocation caps for the touch driver. More...

Functions
ra8_err_t	ra8_touch_open (const ra8_touch_cfg_t *cfg)
	Bring up the touch IC over the injected I2C bus seam.
ra8_err_t	ra8_touch_close (void)
	Tear the driver down and detach any registered handler.
ra8_err_t	ra8_touch_attach_handler (ra8_touch_event_fn_t fn, void *ctx)
	Register a touch event callback.
void	ra8_touch_dispatch_irq (void)
	Test-callable IRQ dispatch shim.
ra8_err_t	ra8_touch_read (ra8_touch_point_t out_points, uint8_t max_count, uint8_t got_count)
	Drain the current touch frame.
ra8_err_t	ra8_touch_calibrate (void)
	Run any backend-specific calibration routine.

Detailed Description

Multi-touch input driver – GoodIX GT911 backend.

Tag: [Ring 3 / HAL] {World: NS}

The RA8D2 has no on-die capacitive touch sensing unit (no CTSU); touch on the EK-RA8D2 ereader carrier is provided by an off-chip GoodIX GT911 IC sitting on the I2C0 bus. ra8_touch exposes a narrow, vendor-agnostic surface so a future FT5x06 / Atmel maXTouch backend can be slotted in without changing application code.

Lifecycle:

ra8_touch_open(cfg) latches the injected I2C bus seam (cfg->bus, app-bound – see ra8_i2c_bus_ops.h), wakes the GT911 by reading its product id string, programmes the GT911 status register to "clear", and – if cfg->irq_pin is in range – programmes the matching ICU IRQ pin for falling-edge detection. The bus peripheral itself (IIC_B today, RIIC on a future board revision) is initialised by the app, not here.
ra8_touch_attach_handler(fn, ctx) installs an event callback fired by ra8_touch_dispatch_irq() (the test-callable shim) when the GT911 INT pin asserts. The callback is expected to call ra8_touch_read() to drain the touch frame.
ra8_touch_read(out, max_count, *got_count) reads the GT911 status byte, copies up to max_count decoded points into out, and writes the GT911 command register with k_ra8_touch_gt911_cmd_clear_status so the IC can latch the next frame.
ra8_touch_calibrate() is a no-op for GT911 (factory-calibrated) and returns k_ra8_ok – it exists in the API so future resistive backends can plug in.
ra8_touch_close() clears the registered handler and releases the driver slot; the app keeps owning the bus peripheral.

Static-allocation footprint:

One ra8_touch_state_t slot (driver-private, file-scope).
No runtime allocation; out_points is caller-provided.

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

Definition in file ra8_touch.h.

Typedef Documentation

◆ ra8_touch_event_fn_t

typedef void(* ra8_touch_event_fn_t) (void *ctx)

Touch-event callback signature.

Fired by ra8_touch_dispatch_irq() when the GT911 INT pin asserts. The callback is expected to call ra8_touch_read() to drain the frame; ra8_touch does not pre-decode points before dispatch because the driver does not know how many of them the application actually wants.

Parameters

[in] ctx Caller-supplied context.

Definition at line 130 of file ra8_touch.h.

Enumeration Type Documentation

◆ ra8_touch_limits_t

enum ra8_touch_limits_t : uint8_t

Static-allocation caps for the touch driver.

Enumerator
k_ra8_touch_max_points	Hard cap (matches GT911 capacity).
k_ra8_touch_irq_pin_unset	Sentinel for "no IRQ pin attached".

Definition at line 70 of file ra8_touch.h.

Function Documentation

◆ ra8_touch_attach_handler()

ra8_err_t ra8_touch_attach_handler	(	ra8_touch_event_fn_t	fn,
		void *	ctx )

nodiscard

Register a touch event callback.

Parameters

[in]	fn	Callback fired on GT911 INT assertion. NULL detaches.
[in]	ctx	Forwarded to the callback as its only argument.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handler stored.
k_ra8_err_not_initialized	Driver is not open.

Precondition: Driver is open.

Since: 0.1.0

Definition at line 424 of file ra8_touch.c.

References k_ra8_err_not_initialized, k_ra8_ok, and s_state.

◆ ra8_touch_calibrate()

ra8_err_t ra8_touch_calibrate ( void )

nodiscard

Run any backend-specific calibration routine.

No-op for GT911 (factory-calibrated). Returns k_ra8_ok so callers can wire it unconditionally; resistive backends added later will actually drive the calibration sequence here.

Returns: k_ra8_ok unconditionally for the GT911 backend.

Since: 0.1.0

Definition at line 566 of file ra8_touch.c.

References k_ra8_ok.

◆ ra8_touch_close()

ra8_err_t ra8_touch_close ( void )

nodiscard

Tear the driver down and detach any registered handler.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Driver closed.
k_ra8_err_not_initialized	ra8_touch_open was not called.

Precondition: Driver is currently open.

Postcondition: No handler is registered and the driver slot is free; the app keeps owning the bus peripheral behind the injected seam.

Since: 0.1.0

Definition at line 408 of file ra8_touch.c.

References k_ra8_err_not_initialized, k_ra8_ok, and s_state.

◆ ra8_touch_dispatch_irq()

void ra8_touch_dispatch_irq ( void )

Test-callable IRQ dispatch shim.

Mirrors the ERI dispatch helper from ra8_i3c_i2c: this is the function the application's IRQ vector should call when the GT911 INT pin fires. The shim simply forwards to the registered handler.

Since: 0.1.0

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Definition at line 434 of file ra8_touch.c.

References s_state.

◆ ra8_touch_open()

ra8_err_t ra8_touch_open ( const ra8_touch_cfg_t * cfg )

nodiscard

Bring up the touch IC over the injected I2C bus seam.

Steps:

Validate cfg (non-NULL bus.write / bus.transfer, known GT911 address) and clamp max_points to k_ra8_touch_max_points.
Read the GT911 PRODUCT_ID register (4 ASCII bytes) to confirm the IC is alive. If the read fails or the id does not start with '9', return k_ra8_err_hw_init_failed.
Clear the GT911 status byte so the next interrupt corresponds to a fresh frame.
If cfg->irq_pin is in range, configure that ICU IRQ pin for falling-edge detection.

The bus peripheral behind cfg->bus (IIC_B in I2C-compat mode at fast-mode speed today) is initialised by the app before this call, typically bound through ra8_io_i2c_bus_as_ops().

Parameters

[in] cfg Configuration descriptor (non-NULL).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	IC alive, driver ready.
k_ra8_err_null_ptr	cfg is NULL.
k_ra8_err_invalid_arg	cfg->bus seam incomplete or cfg->target_7b not 0x5D/0x14.
k_ra8_err_invalid_state	ra8_touch_open was already called.
k_ra8_err_hw_init_failed	Product-id check failed.

Precondition: IRQs masked or single-threaded init context.; The bus peripheral behind cfg->bus is initialised.

Postcondition: On success the driver is in the open state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 387 of file ra8_touch.c.

References internal_open_finalise(), internal_stash_state(), internal_validate_cfg(), k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_info, RA8_RETURN_ON_ERROR, s_state, and s_tag.

Referenced by ra8_board_touch_open().

◆ ra8_touch_read()

ra8_err_t ra8_touch_read	(	ra8_touch_point_t *	out_points,
		uint8_t	max_count,
		uint8_t *	got_count )

nodiscard

Drain the current touch frame.

Sequence:

bus.transfer with the 16-bit register pointer to k_ra8_touch_gt911_reg_status, reads 1 status byte.
If bit7 is clear (no frame ready), set *got_count = 0 and return k_ra8_ok.
Otherwise read up to min(status & 0x0F, max_count) 8-byte point records starting at k_ra8_touch_gt911_reg_point0 and decode them into out_points.
Write k_ra8_touch_gt911_cmd_clear_status (0x00) into the status register so the IC can latch the next frame.

Parameters

[out]	out_points	Destination buffer (non-NULL, must hold max_count entries).
[in]	max_count	Capacity of out_points, in entries.
[out]	got_count	Number of valid entries written.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Frame drained (possibly empty).
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_invalid_arg	max_count == 0.
k_ra8_err_not_initialized	Driver is not open.
k_ra8_err_hw_error	I2C transport failed.

Precondition: Driver is open.

Postcondition: On success *got_count <= max_count.

Since: 0.1.0

Definition at line 551 of file ra8_touch.c.

References internal_read_inner(), k_ra8_err_invalid_arg, k_ra8_err_not_initialized, RA8_CHECK_NULL_PTR, s_state, and s_tag.

Referenced by cm_poll_touch(), er_poll_touch(), ez_poll_touch(), internal_tc_read_raw(), internal_td_poll_points(), ls_poll_touch(), mg_poll_touch(), and sh_pump_input().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_touch_event_fn_t

Enumeration Type Documentation

◆ ra8_touch_limits_t

Function Documentation

◆ ra8_touch_attach_handler()

◆ ra8_touch_calibrate()

◆ ra8_touch_close()

◆ ra8_touch_dispatch_irq()

◆ ra8_touch_open()

◆ ra8_touch_read()