1##########################
2Log system design document
3##########################
4
5:Author: Shawn Shan
6:Organization: Arm Limited
7:Contact: shawn.shan@arm.com
8
9**********
10Background
11**********
12
13In current TF-M log system, the SPM and Secure partitions share the same log
14APIs and implementations. While TF-M is keep evolving, the requirements for the
15log system has changed:
16
17  - Log level is required for both SPM and SP sides to output message in
18    different scenarios.
19  - SPM only needs simple log format such as hex and string, while SP needs rich
20    formatting.
21  - Distinctions on log output between SPM and SP are required.
22
23A new log system is needed to separate the SPM and Secure partitions and to
24meet their different requirements.
25
26******
27Design
28******
29
30To allow customizable configurations, the log interfaces are defined as macros.
31The macros are easy to be forwarded or even empty. When SPM trying to output
32message and a value, it relies on a wrapper function, and finally output the
33formatted message by the HAL API.
34
35The design principles of TF-M log system:
36
37  - Configurable log levels.
38  - Separated SPM and SP log implementations.
39  - Platforms provide log HAL implementations.
40
41SPM Log System
42==============
43
44Level Control
45-------------
46Three log levels for SPM log system are defined:
47
48  - TFM_SPM_LOG_LEVEL_DEBUG
49  - TFM_SPM_LOG_LEVEL_INFO
50  - TFM_SPM_LOG_LEVEL_ERROR
51  - TFM_SPM_LOG_LEVEL_SILENCE
52
53Then a macro ``TFM_SPM_LOG_LEVEL`` is defined as an indicator, it should
54be equal to one of the four log levels.
55
56API Definition
57--------------
58The following three APIs LOG APIs output the given 'msg' with hexadecimal
59formatted 'val' together. These APIs provide constrained ability to output
60numbers inside SPM. The 'msg' can be skipped with giving an empty string like
61"". And these APIs supports constant 'msg' string only, giving a runtime string
62as parameter 'msg' would potentially cause a runtime error.
63
64  SPMLOG_DBGMSGVAL(msg, val);
65
66  SPMLOG_INFMSGVAL(msg, val);
67
68  SPMLOG_ERRMSGVAL(msg, val);
69
70A C-function needs to work as an underlayer for these APIs as string formatting
71is required. Check 'spm_log_msgval' for details.
72
73.. code-block:: c
74
75  /**
76   * brief Output the given message plus one value as hexadecimal. The message
77   *       can be skipped if the 'msg' is 'NULL' or 'len' equals 0. The
78   *       formatted hexadecimal string for 'value' has a '0x' prefix and
79   *       leading zeros are not stripped. This function rely on HAL API
80   *       'tfm_hal_output_spm_log' to output the formatted string.
81   *
82   * \param[in]  msg    A string message
83   * \param[in]  len    The length of the message
84   * \param[in]  value  A value need to be output
85   *
86   * \retval >=0        Number of chars output.
87   * \retval <0         TFM HAL error code.
88   */
89  int32_t  spm_log_msgval(const char *msg, size_t len, uint32_t value)
90
91The following three APIs output a message in string.
92
93  SPMLOG_DBGMSG(msg);
94
95  SPMLOG_INFMSG(msg);
96
97  SPMLOG_ERRMSG(msg);
98
99Here is a table about the effective APIs with different SPM log level.
100
101+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
102|                  | TFM_SPM_LOG_LEVEL_DEBUG | TFM_SPM_LOG_LEVEL_INFO    | TFM_SPM_LOG_LEVEL_ERROR   | TFM_SPM_LOG_LEVEL_SILENCE   |
103+==================+=========================+===========================+===========================+=============================+
104| SPMLOG_DBGMSGVAL |           Yes           |             No            |             No            |            No               |
105+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
106| SPMLOG_INFMSGVAL |           Yes           |             Yes           |             No            |            No               |
107+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
108| SPMLOG_ERRMSGVAL |           Yes           |             Yes           |             Yes           |            No               |
109+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
110| SPMLOG_DBGMSG    |           Yes           |             No            |             No            |            No               |
111+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
112| SPMLOG_INFMSG    |           Yes           |             Yes           |             No            |            No               |
113+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
114| SPMLOG_ERRMSG    |           Yes           |             Yes           |             Yes           |            No               |
115+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
116
117HAL API
118-------
119Define HAL API for SPM log system:
120
121.. code-block:: c
122
123  /* SPM log HAL API */
124  int32_t tfm_hal_output_spm_log(const char *str, uint32_t len);
125
126Take debug message as an example:
127
128.. code-block:: c
129
130  /* For debug message */
131  #define SPMLOG_DBGMSG(msg) tfm_hal_output_spm_log(msg, sizeof(msg))
132  /* For debug message with a value */
133  #define SPMLOG_DBGMSGVAL(msg, val) spm_log_msgval(msg, sizeof(msg), val)
134
135Partition Log System
136====================
137Partition log outputting required rich formatting in particular cases. There is
138a customized print inside TF-M(``printf``), and it is wrapped as macro.
139
140Level Control
141-------------
142Three log levels for partition log system are defined:
143
144  - TFM_PARTITION_LOG_LEVEL_DEBUG
145  - TFM_PARTITION_LOG_LEVEL_INFO
146  - TFM_PARTITION_LOG_LEVEL_ERROR
147  - TFM_PARTITION_LOG_LEVEL_SILENCE
148
149Then a macro ``TFM_PARTITION_LOG_LEVEL`` is defined as an indicator. It should
150be equal to one of the four log levels and it is an overall setting for all
151partitions.
152
153Log Format
154----------
155Compared to SPM, SP log API supports formatting. Similar to ``printf``, these
156log APIs use a format outputting to output various type of data:
157
158.. code-block:: c
159
160  %d - decimal signed integer
161  %u - decimal unsigned integer
162  %x - hex(hexadecimal)
163  %c - char(character)
164  %s - string
165
166API Definition
167--------------
168Define partition log APIs:
169
170  LOG_DBGFMT(...);
171
172  LOG_INFFMT(...);
173
174  LOG_ERRFMT(...);
175
176Here is a table about the effective APIs with different partition log level.
177
178+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
179|            | TFM_PARTITION_LOG_LEVEL_DEBUG | TFM_PARTITION_LOG_LEVEL_INFO    | TFM_PARTITION_LOG_LEVEL_ERROR   | TFM_PARTITION_LOG_LEVEL_SILENCE |
180+============+===============================+=================================+=================================+=================================+
181| LOG_DBGFMT |              Yes              |                No               |                No               |               No                |
182+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
183| LOG_INFFMT |              Yes              |                Yes              |                No               |               No                |
184+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
185| LOG_ERRFMT |              Yes              |                Yes              |                Yes              |               No                |
186+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
187
188HAL API
189-------
190Please refers to the HAL design document.
191
192***********
193Log Devices
194***********
195In most of the cases, a serial device could be used as a log device. And in
196other particular cases, a memory-based log device could be applied as well.
197These log device interfaces are abstracted into HAL APIs.
198
199.. note::
200
201  It is not recommended to re-use the same HAL for both SPM and SP log
202  outputting especially when SPM and SP run under different privileged level,
203  which makes them have a different information confidential level. Unless:
204
205  - The SPM log outputting would be disabled as silence in the release version.
206
207--------------
208
209*Copyright (c) 2020, Arm Limited. All rights reserved.*
210