Notification Structures

This page aggregates all notification-related structures shared by the C and C++ APIs.

Note

Notification::i3cHotJoin(), Notification::i3cIbi(), Notification::gpio() and Notification::uartRx() are C++ convenience methods only (available under #ifdef __cplusplus). They are not part of the C API. In C, use CosmicSDK_notificationAsI3cHotJoin, CosmicSDK_notificationAsI3cIbi, CosmicSDK_notificationAsGpio and CosmicSDK_notificationAsUartRx from CosmicSDK_API_c.h.

group Notification-related structures

Enums

enum NotificationType

Enum to represent the different notification types.

Values:

enumerator NOTIF_I3C_HJ

I3C Hot-Join Notification

enumerator NOTIF_I3C_IBI

I3C In-Band Interrupt Notification

enumerator NOTIF_GPIO

GPIO Interrupt Notification

enumerator NOTIF_UART

UART Rx Notification

enumerator NOTIF_I3C_CONNECTOR_EVENT

I3C Connector Event Notification

enumerator NOTIF_UNKNOWN

Unknown Notification. Value 5 in every release, including v1.4.0. New enumerators go AFTER it, never before: this value is what callers compare against, so inserting ahead of it silently reclassifies their traffic.

enumerator NOTIF_I2C_TARGET_BUS_EVENT

I2C Target bus-event Notification

enumerator NOTIF_SPI_TARGET_BUS_EVENT

SPI Target bus-event Notification

enumerator NOTIF_I3C_TARGET_BUS_EVENT

I3C Target Bus Event Notification

enum I3cConnectorPort

I3C port that generated the connector event.

Values:

enumerator I3C_CONNECTOR_PORT_LV

Low-voltage I3C port.

enumerator I3C_CONNECTOR_PORT_HV

High-voltage I3C port.

enum I3cConnectorEvent

Physical event detected on an I3C connector.

Values:

enumerator I3C_CONNECTOR_PLUGGED

Connector inserted.

enumerator I3C_CONNECTOR_UNPLUGGED

Connector removed.

enum I3cConnectorType

Type of connector identified on an I3C port.

Values:

enumerator I3C_CONNECTOR_TYPE_UNIDENTIFIED

Connector identification not supported.

enumerator I3C_CONNECTOR_TYPE_HARNESS

Binho I3C harness cable.

enumerator I3C_CONNECTOR_TYPE_QWIIC_ADAPTER

Qwiic adapter.

enumerator I3C_CONNECTOR_TYPE_SENSEPEEK

SensePeek probes.

enumerator I3C_CONNECTOR_TYPE_NONE

No connector present.

enumerator I3C_CONNECTOR_TYPE_ERROR

Connector identification failed.

enum I3cTargetBusEventKind

Kind of bus event reported by the host adapter while it acts as an I3C target device.

Values:

enumerator I3C_TARGET_WRITE_TRANSFER_EVENT

An I3C controller wrote into the target memory.

enumerator I3C_TARGET_READ_TRANSFER_EVENT

An I3C controller read from the target memory.

enumerator I3C_TARGET_CCC_TRANSFER_EVENT

An I3C controller issued a CCC addressed to this target.

enumerator I3C_TARGET_DYN_ADDR_CHANGE_EVENT

The dynamic address of this target was assigned or changed by the controller.

struct I3cHotJoinNotification
#include <CosmicNotifications.h>

Parsed I3C Hot-Join notification information.

Public Members

uint8_t pid[6]

Provisional ID (48-bit) reported by the device during Hot-Join.

uint8_t bcr

Bus Characteristics Register value of the joining device.

uint8_t dcr

Device Characteristics Register value of the joining device.

uint8_t dynamicAddress

Dynamic address assigned by the controller after Hot-Join.

struct I3cIbiNotification
#include <CosmicNotifications.h>

Parsed I3C In-Band Interrupt (IBI) notification information.

Public Members

uint8_t address

Dynamic address of the device that generated the IBI.

const uint8_t *payload

Pointer to the optional IBI payload data (if present).

size_t payloadLength

Length in bytes of the IBI payload.

struct UartRxNotification
#include <CosmicNotifications.h>

Parsed UART RX notification. This struct holds the data received through the UART.

Public Members

const uint8_t *data

Pointer to the received UART data buffer.

size_t dataLength

Number of bytes received in the buffer.

struct GpioInterruptNotification
#include <CosmicNotifications.h>

Parsed GPIO Interrupt notification information.

Public Members

uint8_t pinNumber

GPIO pin number that triggered the interrupt.

GpioTriggerType triggeredEdge

Which edge fired (rising/falling).

GpioLogicLevel logicLevel

Pin level at interrupt time (HIGH/LOW).

struct I3cConnectorEventNotification
#include <CosmicNotifications.h>

Parsed I3C connector event notification information.

Public Members

I3cConnectorPort port

Which I3C port generated the event.

I3cConnectorEvent event

Plug or unplug event.

I3cConnectorType connectorType

Type of connector identified.

struct I3cTargetBusEvent
#include <CosmicNotifications.h>

Parsed I3C target bus event notification information.

The host adapter emits one of these notifications every time an I3C controller on the bus completes a transfer addressed to it while it acts as an I3C target device.

Only the fields relevant to kind are populated:

  • I3C_TARGET_WRITE_TRANSFER_EVENT and I3C_TARGET_READ_TRANSFER_EVENT populate every field.

  • I3C_TARGET_CCC_TRANSFER_EVENT populates result and targetAddress only.

  • I3C_TARGET_DYN_ADDR_CHANGE_EVENT populates result and targetAddress only, the latter carrying the new dynamic address assigned to this target.

result reports how the transfer ended, and must always be checked before the payload is consumed: a transfer the controller truncated is reported with a partial payload, so a payload shorter than expected is not by itself distinguishable from a complete one. The values the firmware reports in this field are:

Public Members

I3cTargetBusEventKind kind

Kind of bus event reported.

uint16_t result

Outcome of the transfer, as reported by the firmware. See the list of values in the detailed description. Always populated.

uint8_t targetAddress

Dynamic address of the I3C controller that generated the transfer, or, for I3C_TARGET_DYN_ADDR_CHANGE_EVENT, the new dynamic address of this target.

uint16_t memoryAddress

Address of the first register accessed, expressed as a register index of the active memory layout. Valid for write and read transfer events only.

const uint8_t *payload

Pointer to the bytes written into or read from the target memory. Valid for write and read transfer events only, nullptr otherwise.

size_t payloadLength

Number of bytes in payload. Valid for write and read transfer events only, 0 otherwise.

struct I2cTargetBusEventNotification
#include <CosmicNotifications.h>

Parsed I2C target bus-event notification (metadata only).

Emitted when an external controller completes a read or write against the device while it is acting as an I2C target. The bytes themselves are not carried here; read them from the arena with an I2C target read-memory command.

Public Members

uint8_t event

Transfer direction: 0 = write (controller wrote), 1 = read (controller read).

uint8_t address

Target address the transaction addressed.

uint16_t memoryAddress

Arena offset where the transaction started.

uint16_t payloadLength

Number of bytes transferred on the bus.

struct SpiTargetBusEventNotification
#include <CosmicNotifications.h>

Parsed SPI target bus-event notification (metadata only).

Emitted when an external controller completes a chip-select-framed transaction against the device while it is acting as an SPI target. Read the transferred bytes from the arena with an SPI target read-memory command.

Public Members

uint8_t event

Bus event: 0 = transaction completed.

uint8_t address

Chip-select line the transaction used.

uint16_t memoryAddress

Arena offset where the transaction started.

uint16_t payloadLength

Number of bytes clocked in the transaction.

struct Notification
#include <CosmicNotifications.h>

Generic notification wrapper used by both C and C++ APIs.

This structure is delivered by callback-based APIs:

The type field identifies the notification category. The payload bytes are exposed through payload and payloadLength.

Parsing:

Public Functions

inline Notification(NotificationType t, const uint8_t *p, size_t len) noexcept

Constructs a Notification with the given type and payload.

Note

C++ only. Not available in the C API.

Parameters:

  • t – The notification type.

  • p – Pointer to the notification payload data.

  • len – Length of the payload data in bytes.

const I3cHotJoinNotification *i3cHotJoin() const noexcept

Parses this notification as I3C Hot-Join data.

This method validates type and payload length before decoding.

Note

C++ only. Not available in the C API.

Returns:

Pointer to parsed I3cHotJoinNotification when this is a valid NOTIF_I3C_HJ notification; otherwise nullptr.

const I3cIbiNotification *i3cIbi() const noexcept

Parses this notification as I3C In-Band Interrupt (IBI) data.

This method validates type and payload length before decoding.

Note

C++ only. Not available in the C API.

Returns:

Pointer to parsed I3cIbiNotification when this is a valid NOTIF_I3C_IBI notification; otherwise nullptr.

const GpioInterruptNotification *gpio() const noexcept

Parses this notification as GPIO interrupt data.

This method validates type and payload length before decoding.

Note

C++ only. Not available in the C API.

Returns:

Pointer to parsed GpioInterruptNotification when this is a valid NOTIF_GPIO notification; otherwise nullptr.

const UartRxNotification *uartRx() const noexcept

Parses this notification as UART RX data.

This method validates type and payload length before decoding.

Note

C++ only. Not available in the C API.

Returns:

Pointer to parsed UartRxNotification when this is a valid NOTIF_UART notification; otherwise nullptr.

const I3cConnectorEventNotification *i3cConnectorEvent() const noexcept

Parses this notification as I3C connector event data.

This method validates type and payload length before decoding.

Note

C++ only. Not available in the C API.

Returns:

Pointer to parsed I3cConnectorEventNotification when this is a valid NOTIF_I3C_CONNECTOR_EVENT notification; otherwise nullptr.

const I3cTargetBusEvent *i3cTargetBusEvent() const noexcept

Parses this notification as I3C target bus event data.

This method validates type and payload length before decoding.

Note

C++ only. Not available in the C API.

Returns:

Pointer to parsed I3cTargetBusEvent when this is a valid NOTIF_I3C_TARGET_BUS_EVENT notification; otherwise nullptr.

const I2cTargetBusEventNotification *i2cTargetBusEvent() const noexcept

Parses this notification as I2C target bus-event data.

This method validates type and payload length before decoding.

Note

C++ only. Not available in the C API.

Returns:

Pointer to parsed I2cTargetBusEventNotification when this is a valid NOTIF_I2C_TARGET_BUS_EVENT notification; otherwise nullptr.

const SpiTargetBusEventNotification *spiTargetBusEvent() const noexcept

Parses this notification as SPI target bus-event data.

This method validates type and payload length before decoding.

Note

C++ only. Not available in the C API.

Returns:

Pointer to parsed SpiTargetBusEventNotification when this is a valid NOTIF_SPI_TARGET_BUS_EVENT notification; otherwise nullptr.

Public Members

NotificationType type

Notification type. See NotificationType for valid values.

const uint8_t *payload

Pointer to raw notification payload bytes.

The payload format depends on type.

size_t payloadLength

Payload size in bytes.