1// SPDX-License-Identifier: Apache-2.0
2// ----------------------------------------------------------------------------
3// Copyright 2021-2022 Arm Limited
4//
5// Licensed under the Apache License, Version 2.0 (the "License"); you may not
6// use this file except in compliance with the License. You may obtain a copy
7// of the License at:
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing, software
12// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14// License for the specific language governing permissions and limitations
15// under the License.
16// ----------------------------------------------------------------------------
17
18/**
19 * @brief This module provides a set of diagnostic tracing utilities.
20 *
21 * Overview
22 * ========
23 *
24 * The built-in diagnostic trace tool generates a hierarchical JSON tree structure. The tree
25 * hierarchy contains three levels:
26 *
27 * - block
28 * - pass
29 * - candidate
30 *
31 * One block node exists for each compressed block in the image. One pass node exists for each major
32 * pass (N partition, M planes, O components) applied to a block. One candidate node exists for each
33 * encoding candidate trialed for a pass.
34 *
35 * Each node contains both the hierarchy but also a number of attributes which explain the behavior.
36 * For example, the block node contains the block coordinates in the image, the pass explains the
37 * pass configuration, and the candidate will explain the candidate encoding such as weight
38 * decimation, refinement error, etc.
39 *
40 * Trace Nodes are designed as scope-managed C++ objects with stack-like push/pop behavior.
41 * Constructing a trace node on the stack will automatically add it to the current node as a child,
42 * and then make it the current node. Destroying the current node will pop the stack and set the
43 * parent to the current node. This provides a robust mechanism for ensuring reliable nesting in the
44 * tree structure.
45 *
46 * A set of utility macros are provided to add attribute annotations to the current trace node.
47 *
48 * Usage
49 * =====
50 *
51 * Create Trace Nodes on the stack using the @c TRACE_NODE() macro. This will compile-out completely
52 * in builds with diagnostics disabled.
53 *
54 * Add annotations to the current trace node using the @c trace_add_data() macro. This will
55 * similarly compile out completely in builds with diagnostics disabled.
56 *
57 * If you need to add additional code to support diagnostics-only behavior wrap
58 * it in preprocessor guards:
59 *
60 * #if defined(ASTCENC_DIAGNOSTICS)
61 * #endif
62 */
63
64#ifndef ASTCENC_DIAGNOSTIC_TRACE_INCLUDED
65#define ASTCENC_DIAGNOSTIC_TRACE_INCLUDED
66
67#if defined(ASTCENC_DIAGNOSTICS)
68
69#include <iostream>
70#include <fstream>
71#include <vector>
72
73/**
74 * @brief Class representing a single node in the trace hierarchy.
75 */
76class TraceNode
77{
78public:
79 /**
80 * @brief Construct a new node.
81 *
82 * Constructing a node will push to the the top of the stack, automatically making it a child of
83 * the current node, and then setting it to become the current node.
84 *
85 * @param format The format template for the node name.
86 * @param ... The format parameters.
87 */
88 TraceNode(const char* format, ...);
89
90 /**
91 * @brief Add an attribute to this node.
92 *
93 * Note that no quoting is applied to the @c value, so if quoting is needed it must be done by
94 * the caller.
95 *
96 * @param type The type of the attribute.
97 * @param key The key of the attribute.
98 * @param value The value of the attribute.
99 */
100 void add_attrib(std::string type, std::string key, std::string value);
101
102 /**
103 * @brief Destroy this node.
104 *
105 * Destroying a node will pop it from the top of the stack, making its parent the current node.
106 * It is invalid behavior to destroy a node that is not the current node; usage must conform to
107 * stack push-pop semantics.
108 */
109 ~TraceNode();
110
111 /**
112 * @brief The number of attributes and child nodes in this node.
113 */
114 unsigned int m_attrib_count { 0 };
115};
116
117/**
118 * @brief Class representing the trace log file being written.
119 */
120class TraceLog
121{
122public:
123 /**
124 * @brief Create a new trace log.
125 *
126 * The trace log is global; there can be only one at a time.
127 *
128 * @param file_name The name of the file to write.
129 */
130 TraceLog(const char* file_name);
131
132 /**
133 * @brief Detroy the trace log.
134 *
135 * Trace logs MUST be cleanly destroyed to ensure the file gets written.
136 */
137 ~TraceLog();
138
139 /**
140 * @brief Get the current child node.
141 *
142 * @return The current leaf node.
143 */
144 TraceNode* get_current_leaf();
145
146 /**
147 * @brief Get the stack depth of the current child node.
148 *
149 * @return The current leaf node stack depth.
150 */
151 size_t get_depth();
152
153 /**
154 * @brief The file stream to write to.
155 */
156 std::ofstream m_file;
157
158 /**
159 * @brief The stack of nodes (newest at the back).
160 */
161 std::vector<TraceNode*> m_stack;
162
163private:
164 /**
165 * @brief The root node in the JSON file.
166 */
167 TraceNode* m_root;
168};
169
170/**
171 * @brief Utility macro to create a trace node on the stack.
172 *
173 * @param name The variable name to use.
174 * @param ... The name template and format parameters.
175 */
176#define TRACE_NODE(name, ...) TraceNode name(__VA_ARGS__);
177
178/**
179 * @brief Add a string annotation to the current node.
180 *
181 * @param key The name of the attribute.
182 * @param format The format template for the attribute value.
183 * @param ... The format parameters.
184 */
185void trace_add_data(const char* key, const char* format, ...);
186
187/**
188 * @brief Add a float annotation to the current node.
189 *
190 * @param key The name of the attribute.
191 * @param value The value of the attribute.
192 */
193void trace_add_data(const char* key, float value);
194
195/**
196 * @brief Add an integer annotation to the current node.
197 *
198 * @param key The name of the attribute.
199 * @param value The value of the attribute.
200 */
201void trace_add_data(const char* key, int value);
202
203/**
204 * @brief Add an unsigned integer annotation to the current node.
205 *
206 * @param key The name of the attribute.
207 * @param value The value of the attribute.
208 */
209void trace_add_data(const char* key, unsigned int value);
210
211#else
212
213#define TRACE_NODE(name, ...)
214
215#define trace_add_data(...)
216
217#endif
218
219#endif
220