Enet Trace API

Introduction

Typedefs
typedef uint64_t(*	EnetTrace_TraceTsFunc) (void)
	Callback function used to get trace timestamps. More...
typedef void(*	EnetTrace_ExtTraceFunc) (uint32_t errCode)
	Callback function called to report errors. More...

Enumerations
enum	EnetTrace_TraceLevel {   ENET_TRACE_NONE = 0U, ENET_TRACE_ERROR = 1U, ENET_TRACE_WARN = 2U, ENET_TRACE_INFO = 3U,   ENET_TRACE_DEBUG = 4U, ENET_TRACE_VERBOSE = 5U }
	Enumerates the types of trace level. More...

Build-Time Trace Levels
Enet LLD supports two types of trace levels: build-time and runtime. Build time trace level is specified via ENET_CFG_TRACE_LEVEL and can be any of the levels in this group. The runtime trace level is set through Enet_setTraceLevel(). The runtime trace level should be set equal to or less than the build-time trace level.
#define	ENET_CFG_TRACE_LEVEL_NONE   (0U)
	All traces disabled at build-time. More...
#define	ENET_CFG_TRACE_LEVEL_ERROR   (1U)
	Build-time error level. More...
#define	ENET_CFG_TRACE_LEVEL_WARN   (2U)
	Build-time warning level. More...
#define	ENET_CFG_TRACE_LEVEL_INFO   (3U)
	Build-time information level. More...
#define	ENET_CFG_TRACE_LEVEL_DEBUG   (4U)
	Build-time debug level. More...
#define	ENET_CFG_TRACE_LEVEL_VERBOSE   (5U)
	Build-time verbose level. More...

Trace Formats
The following trace formats are supported: Function prefix: <func>: string File and line number prefix: <func>: <line>: string File, line number and function prefix: <file>: <line>: <func>: string Any of these trace formats can also be prefixed with a timestamp.
#define	ENET_CFG_TRACE_FORMAT_FUNC   (0U)
	Trace prefix: "<func>: string". More...
#define	ENET_CFG_TRACE_FORMAT_FILE   (1U)
	Trace prefix: "<file>: <line>: string". More...
#define	ENET_CFG_TRACE_FORMAT_FULL   (2U)
	Trace prefix: "<file>: <line>: <func>: string". More...
#define	ENET_CFG_TRACE_FORMAT_FUNC_TS   (3U)
	Trace prefix: "<timestamp>: <func>: string". More...
#define	ENET_CFG_TRACE_FORMAT_FILE_TS   (4U)
	Trace prefix: "<timestamp>: <file>: <line>: string". More...
#define	ENET_CFG_TRACE_FORMAT_FULL_TS   (5U)
	Trace prefix: "<timestamp>: <file>: <line>: <func>: string". More...

Enet Trace Configuration Parameters
The default values of the Enet Trace configuration parameters if none is provided via enet_cfg.h.
#define	ENET_CFG_TRACE_LEVEL   (ENET_CFG_TRACE_LEVEL_INFO)
	Default trace level if none is set. More...
#define	ENET_CFG_TRACE_FORMAT   (ENET_CFG_TRACE_FORMAT_FUNC)
	Default trace format if none is specified. More...

Enet Trace Error Code
Enet Trace is capable of generating unique error codes from module id (Enet core, soc, per, mod, phy, etc), line number (where error code was reported) and status (error value reported by the module). The error code is a 32-bit value which is generated as follows: Bits 31:28 - Module's major number (see ENET_TRACE_MOD_ID) Bits 27:20 - Module's minor number (see ENET_TRACE_MOD_ID) Bits 19:8 - Line number where error was reported by the driver Bits 7:0 - Status value (positive value) Major Number Module File location 0 Enet core src/core/*.c, src/common/*.c 1 Peripherals src/per/*.c 2 Modules src/mod/*.c 3 DMA src/dma/*.c 4 Enet SoC soc/*.c 5 PHY src/phy/*.c Each individual source file in the locations shown in previous table is considered a module and is tagged with a unique ENET_TRACE_MOD_ID, denoting the module's major (4-bit) and minor (16-bit) numbers.
#define	ENET_TRACE_ERRCODE_MOD_OFFSET   (20U)
	Module id offset in the error code value. More...
#define	ENET_TRACE_ERRCODE_MOD_MAJ_OFFSET   (28U)
	Module id (major number) offset in the error code value. More...
#define	ENET_TRACE_ERRCODE_MOD_MIN_OFFSET   (20U)
	Module id (minor number) offset in the error code value. More...
#define	ENET_TRACE_ERRCODE_LINE_OFFSET   (8U)
	Line number offset in the error code value. More...
#define	ENET_TRACE_ERRCODE_STATUS_OFFSET   (0U)
	Status offset in the error code value. More...
#define	ENET_TRACE_ERRCODE_MOD_MASK   (0xFFF00000U)
	Module id mask in the error code value. More...
#define	ENET_TRACE_ERRCODE_MOD_MAJ_MASK   (0xF0000000U)
	Module id (major number) mask in the error code value. More...
#define	ENET_TRACE_ERRCODE_MOD_MIN_MASK   (0x0FF00000U)
	Module id (minor number) mask in the error code value. More...
#define	ENET_TRACE_ERRCODE_LINE_MASK   (0x000FFF00U)
	Line number mask in the error code value. More...
#define	ENET_TRACE_ERRCODE_STATUS_MASK   (0x000000FFU)
	Status mask in the error code value. More...
#define	ENET_TRACE_ERRCODE_MOD(x)
	Helper macro to extract the module id from the error code value. More...
#define	ENET_TRACE_ERRCODE_MOD_MAJ(x)
	Helper macro to extract the module id (major number) from the error code value. More...
#define	ENET_TRACE_ERRCODE_MOD_MIN(x)
	Helper macro to extract the module id (minor number) from the error code value. More...
#define	ENET_TRACE_ERRCODE_LINE(x)
	Helper macro to extract the line number from the error code value. More...
#define	ENET_TRACE_ERRCODE_STATUS(x)
	Helper macro to extract the status value from the error code value. More...

Macro Definition Documentation

ENET_CFG_TRACE_LEVEL_NONE

#define ENET_CFG_TRACE_LEVEL_NONE   (0U)

All traces disabled at build-time.

ENET_CFG_TRACE_LEVEL_ERROR

#define ENET_CFG_TRACE_LEVEL_ERROR   (1U)

Build-time error level.

ENET_CFG_TRACE_LEVEL_WARN

#define ENET_CFG_TRACE_LEVEL_WARN   (2U)

Build-time warning level.

ENET_CFG_TRACE_LEVEL_INFO

#define ENET_CFG_TRACE_LEVEL_INFO   (3U)

Build-time information level.

ENET_CFG_TRACE_LEVEL_DEBUG

#define ENET_CFG_TRACE_LEVEL_DEBUG   (4U)

Build-time debug level.

ENET_CFG_TRACE_LEVEL_VERBOSE

#define ENET_CFG_TRACE_LEVEL_VERBOSE   (5U)

Build-time verbose level.

ENET_CFG_TRACE_FORMAT_FUNC

#define ENET_CFG_TRACE_FORMAT_FUNC   (0U)

Trace prefix: "<func>: string".

ENET_CFG_TRACE_FORMAT_FILE

#define ENET_CFG_TRACE_FORMAT_FILE   (1U)

Trace prefix: "<file>: <line>: string".

ENET_CFG_TRACE_FORMAT_FULL

#define ENET_CFG_TRACE_FORMAT_FULL   (2U)

Trace prefix: "<file>: <line>: <func>: string".

ENET_CFG_TRACE_FORMAT_FUNC_TS

#define ENET_CFG_TRACE_FORMAT_FUNC_TS   (3U)

Trace prefix: "<timestamp>: <func>: string".

ENET_CFG_TRACE_FORMAT_FILE_TS

#define ENET_CFG_TRACE_FORMAT_FILE_TS   (4U)

Trace prefix: "<timestamp>: <file>: <line>: string".

ENET_CFG_TRACE_FORMAT_FULL_TS

#define ENET_CFG_TRACE_FORMAT_FULL_TS   (5U)

Trace prefix: "<timestamp>: <file>: <line>: <func>: string".

ENET_CFG_TRACE_LEVEL

#define ENET_CFG_TRACE_LEVEL   (ENET_CFG_TRACE_LEVEL_INFO)

Default trace level if none is set.

ENET_CFG_TRACE_FORMAT

#define ENET_CFG_TRACE_FORMAT   (ENET_CFG_TRACE_FORMAT_FUNC)

Default trace format if none is specified.

ENET_TRACE_ERRCODE_MOD_OFFSET

#define ENET_TRACE_ERRCODE_MOD_OFFSET   (20U)

Module id offset in the error code value.

ENET_TRACE_ERRCODE_MOD_MAJ_OFFSET

#define ENET_TRACE_ERRCODE_MOD_MAJ_OFFSET   (28U)

Module id (major number) offset in the error code value.

ENET_TRACE_ERRCODE_MOD_MIN_OFFSET

#define ENET_TRACE_ERRCODE_MOD_MIN_OFFSET   (20U)

Module id (minor number) offset in the error code value.

ENET_TRACE_ERRCODE_LINE_OFFSET

#define ENET_TRACE_ERRCODE_LINE_OFFSET   (8U)

Line number offset in the error code value.

ENET_TRACE_ERRCODE_STATUS_OFFSET

#define ENET_TRACE_ERRCODE_STATUS_OFFSET   (0U)

Status offset in the error code value.

ENET_TRACE_ERRCODE_MOD_MASK

#define ENET_TRACE_ERRCODE_MOD_MASK   (0xFFF00000U)

Module id mask in the error code value.

ENET_TRACE_ERRCODE_MOD_MAJ_MASK

#define ENET_TRACE_ERRCODE_MOD_MAJ_MASK   (0xF0000000U)

Module id (major number) mask in the error code value.

ENET_TRACE_ERRCODE_MOD_MIN_MASK

#define ENET_TRACE_ERRCODE_MOD_MIN_MASK   (0x0FF00000U)

Module id (minor number) mask in the error code value.

ENET_TRACE_ERRCODE_LINE_MASK

#define ENET_TRACE_ERRCODE_LINE_MASK   (0x000FFF00U)

Line number mask in the error code value.

ENET_TRACE_ERRCODE_STATUS_MASK

#define ENET_TRACE_ERRCODE_STATUS_MASK   (0x000000FFU)

Status mask in the error code value.

ENET_TRACE_ERRCODE_MOD

#define ENET_TRACE_ERRCODE_MOD

(

x

)

Value:

(((x) & ENET_TRACE_ERRCODE_MOD_MASK) \
                                               >> ENET_TRACE_ERRCODE_MOD_OFFSET)

Helper macro to extract the module id from the error code value.

ENET_TRACE_ERRCODE_MOD_MAJ

#define ENET_TRACE_ERRCODE_MOD_MAJ

(

x

)

Value:

(((x) & ENET_TRACE_ERRCODE_MOD_MAJ_MASK) \
                                               >> ENET_TRACE_ERRCODE_MOD_MAJ_OFFSET)

Helper macro to extract the module id (major number) from the error code value.

ENET_TRACE_ERRCODE_MOD_MIN

#define ENET_TRACE_ERRCODE_MOD_MIN

(

x

)

Value:

(((x) & ENET_TRACE_ERRCODE_MOD_MIN_MASK) \
                                               >> ENET_TRACE_ERRCODE_MOD_MIN_OFFSET)

Helper macro to extract the module id (minor number) from the error code value.

ENET_TRACE_ERRCODE_LINE

#define ENET_TRACE_ERRCODE_LINE

(

x

)

Value:

(((x) & ENET_TRACE_ERRCODE_LINE_MASK) \
                                               >> ENET_TRACE_ERRCODE_LINE_OFFSET)

Helper macro to extract the line number from the error code value.

ENET_TRACE_ERRCODE_STATUS

#define ENET_TRACE_ERRCODE_STATUS

(

x

)

Value:

(((x) & ENET_TRACE_ERRCODE_STATUS_MASK) \
                                               >> ENET_TRACE_ERRCODE_STATUS_OFFSET)

Helper macro to extract the status value from the error code value.

Typedef Documentation

EnetTrace_TraceTsFunc

typedef uint64_t(* EnetTrace_TraceTsFunc) (void)

Callback function used to get trace timestamps.

Callback function called when ENET_CFG_TRACE_FORMAT is set to ENET_CFG_TRACE_FORMAT_FUNC_TS, ENET_CFG_TRACE_FORMAT_FILE_TS or ENET_CFG_TRACE_FORMAT_FULL_TS.

The timestamp value must be in microseconds.

EnetTrace_ExtTraceFunc

typedef void(* EnetTrace_ExtTraceFunc) (uint32_t errCode)

Callback function called to report errors.

Callback function called by EnetTrace when Enet driver has reported an error. A unique 32-bit error code is passed to the callback, which encodes information about the module where error occurred, line of code and the status value.

Application can use the helper macros ENET_TRACE_ERRCODE_MOD, ENET_TRACE_ERRCODE_MOD_MAJ, ENET_TRACE_ERRCODE_MOD_MIN, ENET_TRACE_ERRCODE_LINE and ENET_TRACE_ERRCODE_STATUS to decode the error code.

Enumeration Type Documentation

EnetTrace_TraceLevel

enum EnetTrace_TraceLevel

Enumerates the types of trace level.

Enumerator
ENET_TRACE_NONE	All traces are disabled at runtime
ENET_TRACE_ERROR	Error trace level
ENET_TRACE_WARN	Warning trace level
ENET_TRACE_INFO	Info trace level: enables only important informational messages for the user (i.e. PHY link is up or down, NIMU layer is ready, etc). The amount of info logs is not invasive in nature so this trace level may be enabled by applications at init time.
ENET_TRACE_DEBUG	Debug trace level: enables further information messages about operations taking place in the driver (i.e. a module is being opened, PHY auto-negotiation is started, etc). The debug level should be enabled by the user on a need basis (i.e. for debugging or tracing execution flow, etc) as the number of messages will increase considerably with respect to ENET_TRACE_INFO level. This trace level can be enabled at runtime only in 'debug' builds.
ENET_TRACE_VERBOSE	Verbose trace level: enables even further messages about operations taking place in the driver (i.e. PHY state transitions, DMA transfer completion, etc) that are periodic in nature or simply happen very often during normal execution. The amount of messages will increase drastically when the verbose level is enabled, so it's recommended to set it only if really needed. This trace level can be enabled at runtime only in 'debug' builds.