Trace Layer

Trace Layer Overview

The ability to output human readable trace messages is necessary to be able to properly debug firmware operation. However, due to the potential for huge amounts of messages due to fast transitions in firewalls, clocks, etc, a compact trace format that can be easily machine parsed is required as well. A global ‘trace’ layer is provided so that any sub-system present in the firmware has the ability to output information in a common way over a user configured interface.

Trace Configuration

All built-in trace options can be selectively enabled during runtime as described in Design details for System Firmware Debug Console. The trace destinations are configurable as build options but by default are built in and usage of them is left up to the aforementioned board configuration.

All trace debug and trace print messages will be routed as strings over the UART or memory buffer as there is only a single resource for each of these. ITM has multiple channels available that will be partitioned as described below:

ITM Channel Number	Usage
0	Trace print strings.
1	Baseport Trace debug.
2	Security Trace debug.
3	Resource Management Trace debug.
4	Power Management Trace debug.

Trace Memory Buffer Location

The trace memory buffer is located within the firmware memory. Information about the location and size can be found below.

SoC	Base Address	Size
AM65x	0x44083000	0x1000

Trace Debug Data Format

The Trace Debug API supports the sending of arbitrary u32’s to the various Trace destination. By definining a common convention for these u32’s to represent data they can be used to describe events within the system. The below format describes the meaning of each bit inside the u32.

Type	Bit Index	Use
Domain ID	31 - 29	Identifies which domain this debug code belongs to.
Action ID	28 - 22	Identifies the action this code represents, domain specific.
Message Specific Data	21 - 0	Additional data specific to the domain and action ID.

Domain ID

Domain Name	Value	Use
Baseport	0	Debug trace is from Baseport Domain.
Security	1	Debug trace is from Security Domain
RM	2	Debug trace is from Resource Management Domain
PM	3	Debug trace is from Power Management Domain.
Reserved	4	Reserved for future use.
Reserved	5	Reserved for future use.
Reserved	6	Reserved for future use.
Reserved	7	Reserved for future use.

Messages sent using any reserved Domain IDs will be ignored.

Action ID

Below is a listing of the Action IDs for each domain along with how the Message Specific Data (MSD) is to be interpreted.

Baseport Action IDs

Action ID	Value	Use	MSD Use
BP_INIT_COMPLETE	0	OSAL/Baseport init complete	Unused
SEC_MSG_RECEIVED	1	Message from secure host received	(21-15) Host ID of request (14-0) TISCI ID
USER_MSG_RECEIVED	2	Message from secure host received	(21-15) Host ID of request (14-0) TISCI ID
GENERIC_DEBUG	127	Generic Debug Message	Any use.

Security Action IDs

Action ID	Value	Use	MSD Use
FIREWALL_ACTIVE	0	Device has been turned on.	Firewall ID
GENERIC_DEBUG	127	Generic Debug Message	Any use.

Resource Management Action IDs

Action ID	Value	Use	MSD Use
RING_ALLOCATE	0	NavSS ring has been allocated	[21:14] - NavSS Device ID, [13:0] - Ring index
RING_CONFIGURE	4	NavSS ring has been configured	[21:14] - NavSS Device ID, [13:0] - Ring index
RING_FREE	1	NavSS ring has been freed	[21:14] - NavSS Device ID, [13:0] - Ring index
RING_RECONFIG	2	NavSS ring has been reconfigured	[21:14] - NavSS Device ID, [13:0] - Ring index
RING_GET_CFG	5	NavSS ring get configuration	[21:14] - NavSS Device ID, [13:0] - Ring index
RING_RESET	3	NavSS ring has been reset	[21:14] - NavSS Device ID, [13:0] - Ring index
RING_OES_INDEX	8	NavSS ring OES event has been programmed	[21:14] - NavSS Device ID, [13:0] - OES register index
RING_OES_EVENT	9	NavSS ring OES event has been programmed	[15:0] - Global event programmed into OES register
UDMAP_TX_CH_ALLOC	10	NavSS UDMAP TX channel has been allocated	[21:14] - NavSS Device ID, [13:0] - TX channel index
UDMAP_TX_CH_CFG	14	NavSS UDMAP TX channel has been configured	[21:14] - NavSS Device ID, [13:0] - TX channel index
UDMAP_TX_CH_GET_CFG	15	NavSS UDMAP TX channel get configuration	[21:14] - NavSS Device ID, [13:0] - TX channel index
UDMAP_TX_CH_FREE	11	NavSS UDMAP TX channel has been freed	[21:14] - NavSS Device ID, [13:0] - TX channel index
UDMAP_TX_CH_INDEX	12	NavSS UDMAP TX channel has been modified	[21:14] - NavSS Device ID, [13:0] - TX channel index
UDMAP_TX_CH_THRD_ID	13	NavSS UDMAP TX channel thread ID modified	[21:0] - PSI-L thread ID programmed into the TX channel THRD_ID register
UDMAP_RX_CH_ALLOC	17	NavSS UDMAP RX channel has been allocated	[21:14] - NavSS Device ID, [13:0] - RX channel index
UDMAP_RX_CH_CFG	21	NavSS UDMAP RX channel has been configured	[21:14] - NavSS Device ID, [13:0] - RX channel index
UDMAP_RX_CH_GET_CFG	22	NavSS UDMAP RX channel get configuration	[21:14] - NavSS Device ID, [13:0] - RX channel index
UDMAP_RX_CH_FREE	18	NavSS UDMAP RX channel has been freed	[21:14] - NavSS Device ID, [13:0] - RX channel index
UDMAP_RX_CH_INDEX	19	NavSS UDMAP RX channel has been modified	[21:14] - NavSS Device ID, [13:0] - RX channel index
UDMAP_RX_CH_THRD_ID	20	NavSS UDMAP RX channel thread ID modified	[21:0] - PSI-L thread ID programmed into the RX channel THRD_ID register
UDMAP_RX_FLOW_ALLOC	24	NavSS UDMAP RX flow has been allocated	[21:14] - NavSS Device ID, [13:0] - RX flow index
UDMAP_RX_FLOW_FREE	25	NavSS UDMAP RX flow has been freed	[21:14] - NavSS Device ID, [13:0] - RX flow index
UDMAP_RX_FLOW_CFG	26	NavSS UDMAP RX flow non-optional configure	[21:14] - NavSS Device ID, [13:0] - RX flow index
UDMAP_FLOW_CFG	29	NavSS UDMAP RX flow standard configure	[21:14] - NavSS Device ID, [13:0] - RX flow index
UDMAP_FLOW_GET_CFG	33	NavSS UDMAP RX flow get standard config	[21:14] - NavSS Device ID, [13:0] - RX flow index
UDMAP_RX_FLOW_OPT_CFG	27	NavSS UDMAP RX flow optional configure	[21:14] - NavSS Device ID, [13:0] - RX flow index
UDMAP_FLOW_SZ_CFG	30	NavSS UDMAP RX flow size threshold cfg	[21:14] - NavSS Device ID, [13:0] - RX flow index
UDMAP_FLOW_SZ_GET_CFG	34	NavSS UDMAP RX flow get size threshold cfg	[21:14] - NavSS Device ID, [13:0] - RX flow index
UDMAP_RX_FLOW_CH_OWNER	28	NavSS UDMAP RX flow RX channel owner	[13:0] - RX channel index owning the rx flow being configured
UDMAP_OES_INDEX	31	NavSS UDMAP OES event has been programmed	[21:14] - NavSS Device ID, [13:0] - OES register index
UDMAP_OES_EVENT	32	NavSS UDMAP OES event has been programmed	[15:0] - Global event programmed into OES register
PSIL_PAIR	36	NavSS PSI-L threads have been paired	[21:14] - NavSS Device ID
PSIL_PAIR_SRC_THRD_ID	37	NavSS PSI-L paired source thread ID	[21:0] - PSI-L source thread ID
PSIL_PAIR_DST_THRD_ID	38	NavSS PSI-L paired destination thread ID	[21:0] - PSI-L destination thread ID
PSIL_UNPAIR	40	NavSS PSI-L threads have been unpaired	[21:14] - NavSS Device ID
PSIL_UNPAIR_SRC_THRD_ID	41	NavSS PSI-L unpaired source thread ID	[21:0] - PSI-L source thread ID
PSIL_UNPAIR_DST_THRD_ID	42	NavSS PSI-L unpaired destination thread ID	[21:0] - PSI-L destination thread ID
IRQ_SET_SRC	44	Programmed interrupt route source	[21:14] - Interrupt Source Device ID [13:0] - Device’s interrupt source index
IRQ_SET_DST	45	Programmed interrupt route destination	[21:14] - Interrupt Destination Device ID [13:0] - Interrupt destination input IRQ index
IRQ_REL_SRC	46	Released interrupt route source	[21:14] - Interrupt Source Device ID [13:0] - Device’s interrupt source index
IRQ_REL_DST	47	Released interrupt route destination	[21:14] - Interrupt Destination Device ID [13:0] - Interrupt destination input IRQ index
IRQ_IA_CFG_VINT	48	IA virtual interrupt programmed	[21:14] - Interrupt Aggregator Device ID [13:0] - Virtual interrupt
IRQ_IA_CFG_VINT_EVT	49	IA VINT event and status bit programmed	[21:16] - IA virtual interrupt status bit programmed [15:0] - IA input event mapped to status bit
IRQ_IA_CLR_VINT	50	IA virtual interrupt cleared	[21:14] - Interrupt Aggregator Device ID [13:0] - Virtual interrupt
IRQ_IA_CLR_VINT_EVT	51	IA VINT event and status bit cleared	[21:16] - IA virtual interrupt status bit cleared [15:0] - IA input event unmapped from status bit
IRQ_IR_CFG	52	IR input to output route programmed	[21:14] - Interrupt Router Device ID
IRQ_IR_CFG_IO	53	Programmed IR input and output	[21:10] - IR input index [9:0] - IR output index
IRQ_IR_CLR	54	IR input to output route cleared	[21:14] - Interrupt Router Device ID
IRQ_IR_CLR_IO	55	Cleared IR input and output	[21:10] - IR input index [9:0] - IR output index
RESOURCE_GET	61	Retrieved a resource range for a host	[21:16] - Host requesting range [15:6] - Resource type [5:0] - Resource subtype
RESOURCE_GET_START	62	Retrieved resource range start index	[15:0] - Resource start index
RESOURCE_GET_NUM	63	Retrieved resource range number	[15:0] - Number of resources
FAIL (modifier)	0x40	Action failed when action bit set	N/A
GENERIC_DEBUG	127	Generic Debug Message	Any use.

Power Management Action IDs

Action ID	Value	Use	MSD Use
DEVICE_ON	0	Device has been turned on .	Device ID
DEVICE_OFF	1	Device has been turned off.	Device ID
CLOCK_ENABLE	2	Clock has been enabled.	Clock ID
CLOCK_DISABLE	3	Clock has been disabled.	Clock ID
CLOCK_SET_RATE	4	Clock frequency has been changed.	[9:0] - Clock ID [16:10] - Clock frequency, significand [21:17] - Clock frequency, exponent
CLOCK_SET_PARENT	5	Clock parent has been changed.	[9:0] - Clock ID [21:10] - New parent ID
MSG_RECEIVED	6	TI-SCI message received	Message ID
MSG_PARAM_DEV_CLK_ID	7	TI-SCI message content: dev/clk-ids	[9:0] - Device ID [10:21] - Clock ID
MSG_PARAM_VAL	8	TI-SCI message content: value	Target value
WAKE_ARM	9	ARM wakeup event received	Host ID
WAKE_HANDLER	10	Wakeup handler executed	Interrupt ID
PD_GET	11	Powerdomain get	[19:14] - Powerdomain ID [21:20] - PSC ID [13:0] - PD Use count
PD_PUT	12	Powerdomain put	[19:14] - Powerdomain ID [21:20] - PSC ID [13:0] - PD Use count
SET_LOCAL_RESET	13	Set local reset	[19:14] - Powerdomain ID [21:20] - PSC ID [0] - Enable (1) / Disable (0)
MODULE_GET	14	Module get	[19:14] - LPSC ID [21:20] - PSC ID [13:0] - Module Use count
MODULE_PUT	15	Module put	[19:14] - LPSC ID [21:20] - PSC ID [13:0] - Module Use count
RETENTION_GET	16	Retention put	[19:14] - Powerdomain ID [21:20] - LPSC ID [13:0] - Module Retention count
RETENTION_PUT	17	Retention put	[19:14] - Powerdomain ID [21:20] - LPSC ID [13:0] - Module Retention count
PD_INIT	18	Powerdomain init	[19:14] - Powerdomain ID [21:20] - PSC ID
FAIL (modifier)	0x40	Action failed when action bit set	N/A
INVALID_STATE	125	API attempted to set invalid state	Target state
BAD_DEVICE	126	API received bad device ID	Device ID
GENERIC_DEBUG	127	Generic Debug Message	Any use.