1 /*
2  * Copyright 2017 Advanced Micro Devices, Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a
5  * copy of this software and associated documentation files (the "Software"),
6  * to deal in the Software without restriction, including without limitation
7  * on the rights to use, copy, modify, merge, publish, distribute, sub
8  * license, and/or sell copies of the Software, and to permit persons to whom
9  * the Software is furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice (including the next
12  * paragraph) shall be included in all copies or substantial portions of the
13  * Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
18  * THE AUTHOR(S) AND/OR THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM,
19  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
20  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
21  * USE OR OTHER DEALINGS IN THE SOFTWARE.
22  */
23 
24 /**
25  * @file u_log.h
26  * @brief Context logging facilities
27  *
28  * Provides a means of logging context events (draw calls, command streams, ...)
29  * into files.
30  *
31  * Log entries start their life cycle as "chunks". Chunks can be plain text
32  * written by \ref u_log_printf or custom internal representations added by
33  * \ref u_log_chunk that are only converted to text on-demand (e.g. for higher
34  * performance pipelined hang-debugging).
35  *
36  * Chunks are accumulated into "pages". The manager of the log can periodically
37  * take out the current page using \ref u_log_new_page and dump it to a file.
38  *
39  * Furthermore, "auto loggers" can be added to a context, which are callbacks
40  * that are given the opportunity to add their own logging each time a chunk is
41  * added. Drivers can use this to lazily log chunks of their command stream.
42  * Lazy loggers don't need to be re-entrant.
43  */
44 
45 #ifndef U_LOG_H
46 #define U_LOG_H
47 
48 #include <stdio.h>
49 
50 #include "util/u_debug.h"
51 
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
55 
56 struct u_log_page;
57 struct u_log_auto_logger;
58 
59 struct u_log_chunk_type {
60    void (*destroy)(void *data);
61    void (*print)(void *data, FILE *stream);
62 };
63 
64 struct u_log_context {
65    struct u_log_page *cur;
66    struct u_log_auto_logger *auto_loggers;
67    unsigned num_auto_loggers;
68 };
69 
70 typedef void (u_auto_log_fn)(void *data, struct u_log_context *ctx);
71 
72 void
73 u_log_context_init(struct u_log_context *ctx);
74 
75 void
76 u_log_context_destroy(struct u_log_context *ctx);
77 
78 void
79 u_log_add_auto_logger(struct u_log_context *ctx, u_auto_log_fn *callback,
80                       void *data);
81 
82 void
83 u_log_flush(struct u_log_context *ctx);
84 
85 void
86 u_log_printf(struct u_log_context *ctx, const char *fmt, ...) _util_printf_format(2,3);
87 
88 void
89 u_log_chunk(struct u_log_context *ctx, const struct u_log_chunk_type *type,
90             void *data);
91 
92 void
93 u_log_new_page_print(struct u_log_context *ctx, FILE *stream);
94 
95 struct u_log_page *
96 u_log_new_page(struct u_log_context *ctx);
97 
98 void
99 u_log_page_destroy(struct u_log_page *page);
100 
101 void
102 u_log_page_print(struct u_log_page *page, FILE *stream);
103 
104 #ifdef __cplusplus
105 }
106 #endif
107 
108 #endif /* U_LOG_H */
109