IPC4 Asynchronous Notifications & Telemetry Registers

Unsolicited DSP-to-host notifications, resource event reports, keyword detection events, watchdog alerts, and Mailbox Window 0 status registers. More...

Collaboration diagram for IPC4 Asynchronous Notifications & Telemetry Registers:

Files
file	fw_reg.h
	IPC4 firmware registers in mailbox window 0 for host telemetry and status.
file	notification.h
	IPC4 asynchronous notifications, GLITCH reports, and FW ready events.

Data Structures
struct	ipc4_fw_status_reg
	Firmware Status Register (FSR) located at offset 0x0 in Mailbox Window 0. More...
struct	ipc4_fw_pwr_status
	Firmware power and clock status register (offset 0x8 in Mailbox Window 0). More...
struct	ipc4_pipeline_registers
	Pipeline DMA tracking registers in Mailbox Window 0. More...
struct	ipc4_peak_volume_regs
	Peak volume and meter registers for low-latency host inspection. More...
struct	ipc4_llp_reading
	Link Linear Position (LLP) and wallclock snapshot. More...
struct	ipc4_llp_reading_extended
	Extended Link Linear Position reading with total processed data bytes. More...
struct	ipc4_llp_reading_slot
	Mailbox Window 0 reading slot for a single gateway. More...
union	ipc4_rom_info
	ROM build, version, and load capability information. More...
struct	ipc4_fw_registers
	Mailbox Window 0 firmware register layout exposed to host driver. More...
union	ipc4_notification_header
	Standard 32-bit IPC4 notification primary header word. More...
struct	ipc4_watchdog_timeout_notification
	Watchdog timeout notification structure (SOF_IPC4_WATCHDOG_TIMEOUT). More...
struct	ipc4_process_data_error_event_data
	Data payload for process data error event (SOF_IPC4_PROCESS_DATA_ERROR). More...
struct	ipc4_mixer_underrun_event_data
	Data payload for mixer underrun event (SOF_IPC4_MIXER_UNDERRUN_DETECTED). More...
union	ipc4_resource_event_data
	Polymorphic payload for generic resource event notification. More...
struct	ipc4_resource_event_data_notification
	Full resource event notification structure sent in Mailbox Window 0. More...

Typedefs
typedef uint32_t	ipc4_last_error
	Last error code reported by ROM or Base FW.

Enumerations
enum	sof_ipc4_notification_type {   SOF_IPC4_NOTIFY_PHRASE_DETECTED = 4 , SOF_IPC4_NOTIFY_RESOURCE_EVENT = 5 , SOF_IPC4_NOTIFY_LOG_BUFFER_STATUS = 6 , SOF_IPC4_NOTIFY_TIMESTAMP_CAPTURED = 7 ,   SOF_IPC4_NOTIFY_FW_READY = 8 , SOF_IPC4_FW_AUD_CLASS_RESULT = 9 , SOF_IPC4_EXCEPTION_CAUGHT = 10 , SOF_IPC4_MODULE_NOTIFICATION = 12 ,   SOF_IPC4_UAOL_EVENT = 13 , SOF_IPC4_PROBE_DATA_AVAILABLE = 14 , SOF_IPC4_WATCHDOG_TIMEOUT = 15 , SOF_IPC4_MANAGEMENT_SERVICE = 16 }
	Unsolicited DSP-to-host asynchronous notification types. More...
enum	sof_ipc4_resource_event_type {   SOF_IPC4_BUDGET_VIOLATION = 0 , SOF_IPC4_MIXER_UNDERRUN_DETECTED = 1 , SOF_IPC4_STREAM_DATA_SEGMENT = 2 , SOF_IPC4_PROCESS_DATA_ERROR = 3 ,   SOF_IPC4_STACK_OVERFLOW = 4 , SOF_IPC4_BUFFERING_MODE_CHANGED = 5 , SOF_IPC4_GATEWAY_UNDERRUN_DETECTED = 6 , SOF_IPC4_GATEWAY_OVERRUN_DETECTED = 7 ,   SOF_IPC4_EDF_DOMAIN_UNSTABLE = 8 , SOF_IPC4_WATCHDOG_EVENT = 9 , SOF_IPC4_GATEWAY_HIGH_THRES = 10 , SOF_IPC4_GATEWAY_LOW_THRES = 11 ,   SOF_IPC4_I2S_BCE_DETECTED = 12 , SOF_IPC4_I2S_CLK_STATE_CHANGED = 13 , SOF_IPC4_I2S_SINK_MODE_CHANGED = 14 , SOF_IPC4_I2S_SOURCE_MODE_CHANGED = 15 ,   SOF_IPC4_SRE_DRIFT_TOO_HIGH = 16 , SOF_IPC4_TELEMETRY_DATA_STATUS = 17 , SOF_IPC4_SNDW_DEBUG_INFO = 18 , SOF_IPC4_INVALID_RESOURCE_EVENT_TYPE = 19 }
	Specific resource event types reported by identifiable FW entities. More...
enum	sof_ipc4_resource_type {   SOF_IPC4_MODULE_INSTANCE = 0 , SOF_IPC4_PIPELINE = 1 , SOF_IPC4_GATEWAY = 2 , SOF_IPC4_EDF_TASK = 3 ,   SOF_IPC4_INVALID_RESOURCE_TYPE = 4 }
	Originator resource category firing a resource event. More...

Functions
static void	ipc4_notification_watchdog_init (struct ipc4_watchdog_timeout_notification *notif, uint32_t core_id, bool first_timeout)
	Helper to initialize watchdog timeout notification structure.
void	send_process_data_error_notif_msg (uint32_t resource_id, uint32_t error_code)
	Send process data error notification message to host.
bool	send_copier_gateway_xrun_notif_msg (uint32_t pipeline_id, enum sof_ipc_stream_direction dir)
	Send Copier gateway xrun (underrun/overrun) notification to host.
bool	send_gateway_xrun_notif_msg (uint32_t resource_id, enum sof_ipc_stream_direction dir)
	Send DMA gateway xrun notification to host.
void	send_mixer_underrun_notif_msg (uint32_t resource_id, uint32_t eos_flag, uint32_t data_mixed, uint32_t expected_data_mixed)
	Send mixer underrun notification message to host.
void	ipc4_update_notification_mask (uint32_t ntfy_mask, uint32_t enabled_mask)
	Update host notification enable/disable bitmasks.
bool	send_resource_notif (uint32_t resource_id, uint32_t event_type, uint32_t resource_type, void *data, uint32_t data_size)
	Send generic resource event notification.

Detailed Description

Unsolicited DSP-to-host notifications, resource event reports, keyword detection events, watchdog alerts, and Mailbox Window 0 status registers.

Typedef Documentation

ipc4_last_error

typedef uint32_t ipc4_last_error

Last error code reported by ROM or Base FW.

Enumeration Type Documentation

sof_ipc4_notification_type

enum sof_ipc4_notification_type

Unsolicited DSP-to-host asynchronous notification types.

Enumerator
SOF_IPC4_NOTIFY_PHRASE_DETECTED	Key phrase detected by wake-on-voice engine.
SOF_IPC4_NOTIFY_RESOURCE_EVENT	Resource event (underrun, overrun, budget violation).
SOF_IPC4_NOTIFY_LOG_BUFFER_STATUS	Trace log buffer half-full or aging timer expired.
SOF_IPC4_NOTIFY_TIMESTAMP_CAPTURED	Audio wallclock timestamp captured.
SOF_IPC4_NOTIFY_FW_READY	Firmware initialization complete and ready for IPC.
SOF_IPC4_FW_AUD_CLASS_RESULT	Audio classifier / acoustic event result.
SOF_IPC4_EXCEPTION_CAUGHT	Critical DSP exception or panic caught.
SOF_IPC4_MODULE_NOTIFICATION	Generic module-specific event notification.
SOF_IPC4_UAOL_EVENT	USB Audio Offload event notification.
SOF_IPC4_PROBE_DATA_AVAILABLE	Probe extraction buffer contains recorded audio.
SOF_IPC4_WATCHDOG_TIMEOUT	Watchdog timer timeout interrupt on DSP core.
SOF_IPC4_MANAGEMENT_SERVICE	System management service event notification.

sof_ipc4_resource_event_type

enum sof_ipc4_resource_event_type

Specific resource event types reported by identifiable FW entities.

Enumerator
SOF_IPC4_BUDGET_VIOLATION	MCPS budget for module or core exceeded.
SOF_IPC4_MIXER_UNDERRUN_DETECTED	Underrun detected by mixer/mixin component.
SOF_IPC4_STREAM_DATA_SEGMENT	Stream data segment completed by gateway.
SOF_IPC4_PROCESS_DATA_ERROR	Error caught during audio processing.
SOF_IPC4_STACK_OVERFLOW	Stack overflow detected in module or thread.
SOF_IPC4_BUFFERING_MODE_CHANGED	Key Phrase Buffer (KPB) buffering mode changed.
SOF_IPC4_GATEWAY_UNDERRUN_DETECTED	Underrun detected at peripheral DMA gateway.
SOF_IPC4_GATEWAY_OVERRUN_DETECTED	Overrun detected at peripheral DMA gateway.
SOF_IPC4_EDF_DOMAIN_UNSTABLE	Data-processing EDF task missed its deadline.
SOF_IPC4_WATCHDOG_EVENT	Watchdog expiration event.
SOF_IPC4_GATEWAY_HIGH_THRES	IPC gateway reached high watermark threshold.
SOF_IPC4_GATEWAY_LOW_THRES	IPC gateway reached low watermark threshold.
SOF_IPC4_I2S_BCE_DETECTED	Bit Count Error detected on I2S/SSP port.
SOF_IPC4_I2S_CLK_STATE_CHANGED	Clock state change (detected/lost) on I2S port.
SOF_IPC4_I2S_SINK_MODE_CHANGED	I2S sink mode change (started/stopped dropping).
SOF_IPC4_I2S_SOURCE_MODE_CHANGED	I2S source mode change (started/stopped zero-fill).
SOF_IPC4_SRE_DRIFT_TOO_HIGH	Sample Rate Estimator frequency drift exceeded limit.
SOF_IPC4_TELEMETRY_DATA_STATUS	Telemetry buffer exceeded threshold or aged.
SOF_IPC4_SNDW_DEBUG_INFO	SoundWire debug notification (e.g. external VAD).
SOF_IPC4_INVALID_RESOURCE_EVENT_TYPE	Invalid resource event sentinel.

sof_ipc4_resource_type

enum sof_ipc4_resource_type

Originator resource category firing a resource event.

Enumerator
SOF_IPC4_MODULE_INSTANCE	Event originated from a module instance.
SOF_IPC4_PIPELINE	Event originated from a pipeline.
SOF_IPC4_GATEWAY	Event originated from a DMA gateway.
SOF_IPC4_EDF_TASK	Event originated from an EDF DP task.
SOF_IPC4_INVALID_RESOURCE_TYPE	Invalid resource type sentinel.

Function Documentation

ipc4_notification_watchdog_init()

static void ipc4_notification_watchdog_init ( struct ipc4_watchdog_timeout_notification *  notif, uint32_t  core_id, bool  first_timeout  )

inlinestatic

Helper to initialize watchdog timeout notification structure.

Parameters

notif	Pointer to watchdog timeout notification structure to initialize.
core_id	DSP core ID that timed out.
first_timeout	True if this is the first timeout event.

ipc4_update_notification_mask()

void ipc4_update_notification_mask	(	uint32_t	ntfy_mask,
		uint32_t	enabled_mask
	)

Update host notification enable/disable bitmasks.

Parameters

ntfy_mask	Bitmask of notifications to update.
enabled_mask	Target state (1 = enable, 0 = disable) for selected bits.

send_copier_gateway_xrun_notif_msg()

bool send_copier_gateway_xrun_notif_msg	(	uint32_t	pipeline_id,
		enum sof_ipc_stream_direction	dir
	)

Send Copier gateway xrun (underrun/overrun) notification to host.

Parameters

pipeline_id	Target pipeline identifier.
dir	Stream direction (playback underrun or capture overrun).

Returns

True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry.

send_gateway_xrun_notif_msg()

bool send_gateway_xrun_notif_msg	(	uint32_t	resource_id,
		enum sof_ipc_stream_direction	dir
	)

Send DMA gateway xrun notification to host.

Parameters

resource_id	Gateway connector node ID.
dir	Stream direction.

Returns

True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry.

send_mixer_underrun_notif_msg()

void send_mixer_underrun_notif_msg	(	uint32_t	resource_id,
		uint32_t	eos_flag,
		uint32_t	data_mixed,
		uint32_t	expected_data_mixed
	)

Send mixer underrun notification message to host.

Parameters

resource_id	Target mixer pipeline identifier.
eos_flag	End of stream flag.
data_mixed	Actual bytes mixed.
expected_data_mixed	Expected bytes mixed.

send_process_data_error_notif_msg()

void send_process_data_error_notif_msg	(	uint32_t	resource_id,
		uint32_t	error_code
	)

Send process data error notification message to host.

Parameters

resource_id	ID of module instance encountering error.
error_code	Module-specific error code.

send_resource_notif()

bool send_resource_notif	(	uint32_t	resource_id,
		uint32_t	event_type,
		uint32_t	resource_type,
		void *	data,
		uint32_t	data_size
	)

Send generic resource event notification.

Parameters

resource_id	ID of originator resource.
event_type	Event type (enum sof_ipc4_resource_event_type).
resource_type	Resource category (enum sof_ipc4_resource_type).
data	Pointer to event payload.
data_size	Size of event payload in bytes.

Returns

True if dispatched or suppressed by notification mask; false if notification pool was exhausted and caller should retry.