Logging - Thread Stack

This module includes OpenThread logging related definitions.

Summary

Functions
`otDumpCritPlat(const char aText, const void aData, uint16_t aDataLength)`	`void` Generates a memory dump at critical log level.
`otDumpDebgPlat(const char aText, const void aData, uint16_t aDataLength)`	`void` Generates a memory dump at debug log level.
`otDumpInfoPlat(const char aText, const void aData, uint16_t aDataLength)`	`void` Generates a memory dump at info log level.
`otDumpNotePlat(const char aText, const void aData, uint16_t aDataLength)`	`void` Generates a memory dump at note log level.
`otDumpWarnPlat(const char aText, const void aData, uint16_t aDataLength)`	`void` Generates a memory dump at warning log level.
`otGetLogLevel(otInstance *aInstance)`	`otLogLevel` Returns the current log level for a given OpenThread instance.
`otLogCli(otLogLevel aLogLevel, const char *aFormat, ...)`	`void` Emits a log message at a given log level.
`otLogCritPlat(const char *aFormat, ...)`	`void` Emits a log message at critical log level.
`otLogDebgPlat(const char *aFormat, ...)`	`void` Emits a log message at debug log level.
`otLogGenerateNextHexDumpLine(otLogHexDumpInfo *aInfo)`	`otError` Generates the next hex dump line.
`otLogInfoPlat(const char *aFormat, ...)`	`void` Emits a log message at info log level.
`otLogNotePlat(const char *aFormat, ...)`	`void` Emits a log message at note log level.
`otLogPlat(otLogLevel aLogLevel, const char aPlatModuleName, const char aFormat, ...)`	`void` Emits a log message at given log level using a platform module name.
`otLogPlatArgs(otLogLevel aLogLevel, const char aPlatModuleName, const char aFormat, va_list aArgs)`	`void` Emits a log message at given log level using a platform module name.
`otLogWarnPlat(const char *aFormat, ...)`	`void` Emits a log message at warning log level.
`otLoggingGetLevel(void)`	`otLogLevel` Returns the current global log level.
`otLoggingSetLevel(otLogLevel aLogLevel)`	`otError` Sets the global log level.
`otSetLogLevel(otInstance *aInstance, otLogLevel aLogLevel)`	`otError` Sets the log level for a given OpenThread instance.

Macros
`OT_LOG_HEX_DUMP_LINE_SIZE 73`	Hex dump line string size.

Structs
otLogHexDumpInfo	Represents information used for generating hex dump output.

Functions

otDumpCritPlat

void otDumpCritPlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)

Generates a memory dump at critical log level.

If OPENTHREAD_CONFIG_LOG_PLATFORM or OPENTHREAD_CONFIG_LOG_PKT_DUMP is not set or the current log level is below critical this function does not emit any log message.

Details

Parameters

`[in] aText`	A string that is printed before the bytes.
`[in] aData`	A pointer to the data buffer.
`[in] aDataLength`	Number of bytes in `aData`.

otDumpDebgPlat

void otDumpDebgPlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)

Generates a memory dump at debug log level.

If OPENTHREAD_CONFIG_LOG_PLATFORM or OPENTHREAD_CONFIG_LOG_PKT_DUMP is not set or the current log level is below debug this function does not emit any log message.

Details

Parameters

`[in] aText`	A string that is printed before the bytes.
`[in] aData`	A pointer to the data buffer.
`[in] aDataLength`	Number of bytes in `aData`.

otDumpInfoPlat

void otDumpInfoPlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)

Generates a memory dump at info log level.

If OPENTHREAD_CONFIG_LOG_PLATFORM or OPENTHREAD_CONFIG_LOG_PKT_DUMP is not set or the current log level is below info this function does not emit any log message.

Details

Parameters

`[in] aText`	A string that is printed before the bytes.
`[in] aData`	A pointer to the data buffer.
`[in] aDataLength`	Number of bytes in `aData`.

otDumpNotePlat

void otDumpNotePlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)

Generates a memory dump at note log level.

If OPENTHREAD_CONFIG_LOG_PLATFORM or OPENTHREAD_CONFIG_LOG_PKT_DUMP is not set or the current log level is below note this function does not emit any log message.

Details

Parameters

`[in] aText`	A string that is printed before the bytes.
`[in] aData`	A pointer to the data buffer.
`[in] aDataLength`	Number of bytes in `aData`.

otDumpWarnPlat

void otDumpWarnPlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)

Generates a memory dump at warning log level.

If OPENTHREAD_CONFIG_LOG_PLATFORM or OPENTHREAD_CONFIG_LOG_PKT_DUMP is not set or the current log level is below warning this function does not emit any log message.

Details

Parameters

`[in] aText`	A string that is printed before the bytes.
`[in] aData`	A pointer to the data buffer.
`[in] aDataLength`	Number of bytes in `aData`.

otGetLogLevel

otLogLevel otGetLogLevel(
  otInstance *aInstance
)

Returns the current log level for a given OpenThread instance.

If dynamic log level feature OPENTHREAD_CONFIG_LOG_LEVEL_DYNAMIC_ENABLE is enabled, this function returns the currently set dynamic log level:

In a single-instance configuration, it returns the instance's log level.
In a multi-instance configuration, it returns the instance-specific log level if it has been explicitly set (see otSetLogLevel()). Otherwise, it returns the global log level (see otLoggingGetLevel()).

If the dynamic log level feature is not enabled, this function returns the build-time configured log level.

Details

Parameters

[in] aInstance

The OpenThread instance.

Returns

The log level.

otLogCli

void otLogCli(
  otLogLevel aLogLevel,
  const char *aFormat,
  ...
)

Emits a log message at a given log level.

Is intended for use by CLI only. If OPENTHREAD_CONFIG_LOG_CLI is not set or the current log level is below the given log level, this function does not emit any log message.

Details

Parameters

`[in] aLogLevel`	The log level.
`[in] aFormat`	The format string.
`[in] ...`	Arguments for the format specification.

otLogCritPlat

void otLogCritPlat(
  const char *aFormat,
  ...
)

Emits a log message at critical log level.

Is intended for use by platform. If OPENTHREAD_CONFIG_LOG_PLATFORM is not set or the current log level is below critical, this function does not emit any log message.

Details

Parameters

`[in] aFormat`	The format string.
`[in] ...`	Arguments for the format specification.

otLogDebgPlat

void otLogDebgPlat(
  const char *aFormat,
  ...
)

Emits a log message at debug log level.

Is intended for use by platform. If OPENTHREAD_CONFIG_LOG_PLATFORM is not set or the current log level is below debug, this function does not emit any log message.

Details

Parameters

`[in] aFormat`	The format string.
`[in] ...`	Arguments for the format specification.

otLogGenerateNextHexDumpLine

otError otLogGenerateNextHexDumpLine(
  otLogHexDumpInfo *aInfo
)

Generates the next hex dump line.

Can call this method back-to-back to generate the hex dump output line by line. On the first call the mIterator field in aInfo MUST be set to zero.

Here is an example of the generated hex dump output:

"==========================[{mTitle} len=070]============================" "| 41 D8 87 34 12 FF FF 25 | 4C 57 DA F2 FB 2F 62 7F | A..4...%LW.../b. |" "| 3B 01 F0 4D 4C 4D 4C 54 | 4F 00 15 15 00 00 00 00 | ;..MLMLTO....... |" "| 00 00 00 01 80 DB 60 82 | 7E 33 72 3B CC B3 A1 84 | ......`.~3r;.... |" "| 3B E6 AD B2 0B 45 E7 45 | C5 B9 00 1A CB 2D 6D 1C | ;....E.E.....-m. |" "| 10 3E 3C F5 D3 70 | | .><..p |" "------------------------------------------------------------------------"

Details

Parameters

[in,out] aInfo

A pointer to otLogHexDumpInfo to use to generate hex dump.

Return Values

`OT_ERROR_NONE`	Successfully generated the next line, `mLine` field in `aInfo` is updated.
`OT_ERROR_NOT_FOUND`	Reached the end and no more line to generate.

otLogInfoPlat

void otLogInfoPlat(
  const char *aFormat,
  ...
)

Emits a log message at info log level.

Is intended for use by platform. If OPENTHREAD_CONFIG_LOG_PLATFORM is not set or the current log level is below info, this function does not emit any log message.

Details

Parameters

`[in] aFormat`	The format string.
`[in] ...`	Arguments for the format specification.

otLogNotePlat

void otLogNotePlat(
  const char *aFormat,
  ...
)

Emits a log message at note log level.

Is intended for use by platform. If OPENTHREAD_CONFIG_LOG_PLATFORM is not set or the current log level is below note, this function does not emit any log message.

Details

Parameters

`[in] aFormat`	The format string.
`[in] ...`	Arguments for the format specification.

otLogPlat

void otLogPlat(
  otLogLevel aLogLevel,
  const char *aPlatModuleName,
  const char *aFormat,
  ...
)

Emits a log message at given log level using a platform module name.

This is is intended for use by platform. If OPENTHREAD_CONFIG_LOG_PLATFORM is not set or the current log level is below aLogLevel , this function does not emit any log message.

The aPlatModuleName name is used to determine the log module name in the emitted log message, following the P-{PlatModuleName}--- format. This means that the prefix string "P-" is added to indicate that this is a platform sub-module, followed by the next 12 characters of the PlatModuleName string, with padded hyphens - at the end to ensure that the region name is 14 characters long.

Details

Parameters

`[in] aLogLevel`	The log level.
`[in] aPlatModuleName`	The platform sub-module name.
`[in] aFormat`	The format string.
`[in] ...`	Arguments for the format specification.

otLogPlatArgs

void otLogPlatArgs(
  otLogLevel aLogLevel,
  const char *aPlatModuleName,
  const char *aFormat,
  va_list aArgs
)

Emits a log message at given log level using a platform module name.

This is is intended for use by platform. If OPENTHREAD_CONFIG_LOG_PLATFORM is not set or the current log level is below aLogLevel , this function does not emit any log message.

Details

Parameters

`[in] aLogLevel`	The log level.
`[in] aPlatModuleName`	The platform sub-module name.
`[in] aFormat`	The format string.
`[in] aArgs`	Arguments for the format specification.

otLogWarnPlat

void otLogWarnPlat(
  const char *aFormat,
  ...
)

Emits a log message at warning log level.

Is intended for use by platform. If OPENTHREAD_CONFIG_LOG_PLATFORM is not set or the current log level is below warning, this function does not emit any log message.

Details

Parameters

`[in] aFormat`	The format string.
`[in] ...`	Arguments for the format specification.

otLoggingGetLevel

otLogLevel otLoggingGetLevel(
  void
)

Returns the current global log level.

In a single-instance configuration, this function behaves the same as otGetLogLevel(). In a multi-instance configuration, it returns the global log level which is used for all instances.

Details
Returns	The global log level.

otLoggingSetLevel

otError otLoggingSetLevel(
  otLogLevel aLogLevel
)

Sets the global log level.

Note: This function requires OPENTHREAD_CONFIG_LOG_LEVEL_DYNAMIC_ENABLE=1.

In a single-instance configuration, this function behaves the same as otSetLogLevel() (which is the recommended function to use).

In a multi-instance configuration, it sets the global log level which is used by all instances. The log level can be explicitly set on a specific instance using otSetLogLevel(), which will then be used instead of the global value.

Details

Parameters

[in] aLogLevel

The log level.

Return Values

`OT_ERROR_NONE`	Successfully updated the log level.
`OT_ERROR_INVALID_ARGS`	Log level value is invalid.

otSetLogLevel

otError otSetLogLevel(
  otInstance *aInstance,
  otLogLevel aLogLevel
)

Sets the log level for a given OpenThread instance.

Note: This function requires OPENTHREAD_CONFIG_LOG_LEVEL_DYNAMIC_ENABLE=1.

In a single-instance configuration, this function sets the log level for the instance.

In a multi-instance configuration (OPENTHREAD_CONFIG_MULTIPLE_INSTANCE_ENABLE), if OPENTHREAD_CONFIG_LOG_INSTANCE_AWARE_API_ENABLE is not enabled, this function returns OT_ERROR_NOT_CAPABLE. When the log level is explicitly set on an instance, it overrides the global log level set using otLoggingSetLevel().

Details

Parameters

`[in] aInstance`	The OpenThread instance.
`[in] aLogLevel`	The log level.

Return Values

`OT_ERROR_NONE`	Successfully updated the log level.
`OT_ERROR_INVALID_ARGS`	Log level value is invalid.
`OT_ERROR_NOT_CAPABLE`	Instance-aware logging is not enabled in a multi-instance configuration.

Macros

OT_LOG_HEX_DUMP_LINE_SIZE

 OT_LOG_HEX_DUMP_LINE_SIZE 73

Hex dump line string size.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.

Logging - Thread Stack

Summary

Functions

Macros

Structs

Functions

otDumpCritPlat

otDumpDebgPlat

otDumpInfoPlat

otDumpNotePlat

otDumpWarnPlat

otGetLogLevel

otLogCli

otLogCritPlat

otLogDebgPlat

otLogGenerateNextHexDumpLine

otLogInfoPlat

otLogNotePlat

otLogPlat

otLogPlatArgs

otLogWarnPlat

otLoggingGetLevel

otLoggingSetLevel

otSetLogLevel

Macros

OT_LOG_HEX_DUMP_LINE_SIZE

Resources