tt_grendel_i3c.h File Reference

Inter-die command protocol over I3C. More...

#include <stdint.h>
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <zephyr/toolchain.h>

Include dependency graph for tt_grendel_i3c.h:

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

Go to the source code of this file.

Data Structures
struct	tt_grendel_i3c_d2d_req
	Payload for TT_GRENDEL_I3C_CMD_D2D_INIT and TT_GRENDEL_I3C_CMD_D2D_START. More...
struct	tt_grendel_i3c_cmd_frame
	Command frame, written by the controller. More...
struct	tt_grendel_i3c_response
	Response frame, written by the target once a command has run. More...

Macros
#define	TT_GRENDEL_I3C_CMD_PING   0x01U
	Ping the target to check it is up. Carries no payload.
#define	TT_GRENDEL_I3C_CMD_D2D_INIT   0x02U
	Reset-release one of the target's D2D tiles and load its firmware.
#define	TT_GRENDEL_I3C_CMD_D2D_START   0x03U
	Release the D2D Rocket selected by tt_grendel_i3c_d2d_req::instance so its loaded firmware runs.
#define	TT_GRENDEL_I3C_CMD_PAYLOAD_MAX_LEN   sizeof(struct tt_grendel_i3c_d2d_req)
	Largest payload carried by any TT_GRENDEL_I3C_CMD_* opcode.

Enumerations
enum	tt_grendel_i3c_result {   TT_GRENDEL_I3C_OK = 0 ,   TT_GRENDEL_I3C_NOT_OK = 1 }
	Result reported in tt_grendel_i3c_response. More...

Functions
	BUILD_ASSERT (sizeof(struct tt_grendel_i3c_response)==4, "response frame must stay 4 bytes")
int	tt_grendel_i3c_wait_ready (const struct device *dev, k_timeout_t timeout)
	Wait until the remote die is on the bus and answering.
int	tt_grendel_i3c_d2d_init (const struct device *dev, uint8_t instance, k_timeout_t timeout)
	Reset-release D2D tile instance on the remote die and load its firmware.
int	tt_grendel_i3c_d2d_start (const struct device *dev, uint8_t instance, k_timeout_t timeout)
	Release D2D tile instance's Rocket on the remote die so its loaded firmware runs.

Variables
struct tt_grendel_i3c_d2d_req	__packed

Detailed Description

Inter-die command protocol over I3C.

Lets the die that owns a bring-up sequence (the I3C controller, Keraunos) run work on another die (the I3C target, Mimir). The first user is D2D link bring-up, where both ends have to be loaded before either is started or the link does not train, and with sideband synchronisation disabled nothing in hardware arranges that.

Commands are plain I3C private writes of an opcode byte followed by an opcode-specific payload struct (below), sized to fit within TT_GRENDEL_I3C_CMD_PAYLOAD_MAX_LEN. The target runs the command on a workqueue and then writes a tt_grendel_i3c_response back, which the controller collects with a private read. There is no IBI, so the controller retries that read until the response echoes the opcode it sent.

Adding a command needs a new opcode, a payload struct if it carries one, a handler on the target, and a wrapper function on the controller side.

Macro Definition Documentation

TT_GRENDEL_I3C_CMD_D2D_INIT

#define TT_GRENDEL_I3C_CMD_D2D_INIT   0x02U

Reset-release one of the target's D2D tiles and load its firmware.

Leaves the tile's Rocket in reset, so the link does not begin training until TT_GRENDEL_I3C_CMD_D2D_START. The firmware image is the one already staged in the target's local memory; it is not carried over I3C. The tile is selected by tt_grendel_i3c_d2d_req::instance.

TT_GRENDEL_I3C_CMD_D2D_START

#define TT_GRENDEL_I3C_CMD_D2D_START   0x03U

Release the D2D Rocket selected by tt_grendel_i3c_d2d_req::instance so its loaded firmware runs.

TT_GRENDEL_I3C_CMD_PAYLOAD_MAX_LEN

#define TT_GRENDEL_I3C_CMD_PAYLOAD_MAX_LEN   sizeof(struct tt_grendel_i3c_d2d_req)

Largest payload carried by any TT_GRENDEL_I3C_CMD_* opcode.

TT_GRENDEL_I3C_CMD_PING

#define TT_GRENDEL_I3C_CMD_PING   0x01U

Ping the target to check it is up. Carries no payload.

Enumeration Type Documentation

tt_grendel_i3c_result

enum tt_grendel_i3c_result

Result reported in tt_grendel_i3c_response.

Enumerator
TT_GRENDEL_I3C_OK	0	The command completed successfully.
TT_GRENDEL_I3C_NOT_OK	1	The command failed on the target.

Function Documentation

BUILD_ASSERT()

BUILD_ASSERT	(	sizeof(struct tt_grendel_i3c_response)	= =4,
		"response frame must stay 4 bytes"	)

tt_grendel_i3c_d2d_init()

int tt_grendel_i3c_d2d_init	(	const struct device *	dev,
		uint8_t	instance,
		k_timeout_t	timeout )

Reset-release D2D tile instance on the remote die and load its firmware.

Blocks until the target answers, or timeout elapses. See TT_GRENDEL_I3C_CMD_D2D_INIT for details.

Parameters

dev	Grendel I3C controller device
instance	D2D tile index on the remote die
timeout	How long to wait for the response

Return values

0	if the target reported TT_GRENDEL_I3C_OK
-EIO	if an I3C transfer failed or the target reported TT_GRENDEL_I3C_NOT_OK
-ETIMEDOUT	if no matching response arrived in time

tt_grendel_i3c_d2d_start()

int tt_grendel_i3c_d2d_start	(	const struct device *	dev,
		uint8_t	instance,
		k_timeout_t	timeout )

Release D2D tile instance's Rocket on the remote die so its loaded firmware runs.

Blocks until the target answers, or timeout elapses.

Parameters

dev	Grendel I3C controller device
instance	D2D tile index on the remote die
timeout	How long to wait for the response

Return values

0	if the target reported TT_GRENDEL_I3C_OK
-EIO	if an I3C transfer failed or the target reported TT_GRENDEL_I3C_NOT_OK
-ETIMEDOUT	if no matching response arrived in time

tt_grendel_i3c_wait_ready()

int tt_grendel_i3c_wait_ready	(	const struct device *	dev,
		k_timeout_t	timeout )

Wait until the remote die is on the bus and answering.

The target only registers once the remote die has booted far enough to run its driver, so pings are expected to fail for a while. Retry until one is answered.

Parameters

dev	Grendel I3C controller device
timeout	How long to wait for the target to appear

Return values

0	once the target answers
-ETIMEDOUT	if it never did

Variable Documentation

__packed

struct tt_grendel_i3c_response __packed