src/gallium/auxiliary/util/u_log.h

   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 struct u_log_page;
  53 struct u_log_auto_logger;
  54
  55 struct u_log_chunk_type {
  56    void (*destroy)(void *data);
  57    void (*print)(void *data, FILE *stream);
  58 };
  59
  60 struct u_log_context {
  61    struct u_log_page *cur;
  62    struct u_log_auto_logger *auto_loggers;
  63    unsigned num_auto_loggers;
  64 };
  65
  66 typedef void (u_auto_log_fn)(void *data, struct u_log_context *ctx);
  67
  68 void
  69 u_log_context_init(struct u_log_context *ctx);
  70
  71 void
  72 u_log_context_destroy(struct u_log_context *ctx);
  73
  74 void
  75 u_log_add_auto_logger(struct u_log_context *ctx, u_auto_log_fn *callback,
  76                       void *data);
  77
  78 void
  79 u_log_flush(struct u_log_context *ctx);
  80
  81 void
  82 u_log_printf(struct u_log_context *ctx, const char *fmt, ...) _util_printf_format(2,3);
  83
  84 void
  85 u_log_chunk(struct u_log_context *ctx, const struct u_log_chunk_type *type,
  86             void *data);
  87
  88 void
  89 u_log_new_page_print(struct u_log_context *ctx, FILE *stream);
  90
  91 struct u_log_page *
  92 u_log_new_page(struct u_log_context *ctx);
  93
  94 void
  95 u_log_page_destroy(struct u_log_page *page);
  96
  97 void
  98 u_log_page_print(struct u_log_page *page, FILE *stream);
  99
 100 #endif /* U_LOG_H */