Log system design document

Author

Shawn Shan

Organization

Arm Limited

Contact

shawn.shan@arm.com

Background

In current TF-M log system, the SPM and Secure partitions share the same log APIs and implementations. While TF-M is keep evolving, the requirements for the log system has changed:

• Log level is required for both SPM and SP sides to output message in different scenarios.

• SPM only needs simple log format such as hex and string, while SP needs rich formatting.

• Distinctions on log output between SPM and SP are required.

A new log system is needed to separate the SPM and Secure partitions and to meet their different requirements.

Design

To allow customizable configurations, the log interfaces are defined as macros. The macros are easy to be forwarded or even empty. When SPM trying to output message and a value, it relies on a wrapper function, and finally output the formatted message by the HAL API.

The design principles of TF-M log system:

• Configurable log levels.

• Separated SPM and SP log implementations.

• Platforms provide log HAL implementations.

SPM Log System

Level Control

Three log levels for SPM log system are defined:

• LOG_LEVEL_NONE

• LOG_LEVEL_ERROR

• LOG_LEVEL_NOTICE

• LOG_LEVEL_WARNING

• LOG_LEVEL_INFO

• LOG_LEVEL_VERBOSE

Then a macro TFM_SPM_LOG_LEVEL is defined as an indicator, it should be equal to one of the six log levels.

API Definition

The following APIs output the string with optional format specifiers. The _RAW forms of the macros, output the string directly, without adding a prefix identifying the log level of the print:

VERBOSE_RAW(…); VERBOSE(…);

INFO_RAW(…); INFO(…);

WARN(…); WARN_RAW(…);

NOTICE(…); NOTICE_RAW(…);

ERROR(…); ERROR_RAW(…);

Here is a table about the effective APIs with different SPM log level.

	DEBUG	INFO	ERROR	NONE
VERBOSE_RAW VERBOSE	Yes	No	No	No
INFO_RAW INFO	Yes	Yes	No	No
NOTICE_RAW NOTICE	Yes	Yes	No	No
WARN_RAW WARN	Yes	Yes	No	No
ERROR_RAW ERROR	Yes	Yes	Yes	No

Partition Log System

Partition log outputting required rich formatting in particular cases. There is a customized print inside TF-M(tfm_log_unpriv), and it is wrapped as macro.

Level Control

Three log levels for partition log system are defined:

• LOG_LEVEL_NONE

• LOG_LEVEL_ERROR

• LOG_LEVEL_NOTICE

• LOG_LEVEL_WARNING

• LOG_LEVEL_INFO

• LOG_LEVEL_VERBOSE

Then a macro TFM_PARTITION_LOG_LEVEL is defined as an indicator. It should be equal to one of the six log levels and it is an overall setting for all partitions.

Log Format

Compared to SPM, SP log API supports formatting. Similar to printf, these log APIs use a format outputting to output various type of data:

%d - decimal signed integer
%u - decimal unsigned integer
%x - hex(hexadecimal)
%s - string

API Definition

Define partition log APIs:

VERBOSE_UNPRIV_RAW(…); VERBOSE_UNPRIV(…);

INFO_UNPRIV_RAW(…); INFO_UNPRIV(…);

WARN_UNPRIV(…); WARN_UNPRIV_RAW(…);

NOTICE_UNPRIV(…); NOTICE_UNPRIV_RAW(…);

ERROR_UNPRIV(…); ERROR_UNPRIV_RAW(…);

Here is a table about the effective APIs with different partition log level.

	DEBUG	INFO	ERROR	NONE
VERBOSE_UNPRIV_RAW VERBOSE_UNPRIV	Yes	No	No	No
INFO_UNPRIV_RAW INFO_UNPRIV	Yes	Yes	No	No
NOTICE_UNPRIV_RAW NOTICE_UNPRIV	Yes	Yes	No	No
WARN_UNPRIV_RAW WARN_UNPRIV	Yes	Yes	No	No
ERROR_UNPRIV_RAW ERROR_UNPRIV	Yes	Yes	Yes	No

HAL API

Please refers to the HAL design document.

Log Devices

In most of the cases, a serial device could be used as a log device. And in other particular cases, a memory-based log device could be applied as well. These log device interfaces are abstracted into HAL APIs.

Note

It is not recommended to reuse the same HAL for both SPM and SP log outputting especially when SPM and SP run under different privileged level, which makes them have a different information confidential level. Unless:

• The SPM log outputting would be disabled as silence in the release version.

---

SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors