1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2021 Intel Corporation. All rights reserved. 3 */ 4 5 /** 6 * \file 7 * Trace parser library 8 */ 9 10 #ifndef SPDK_TRACE_PARSER_H 11 #define SPDK_TRACE_PARSER_H 12 13 #include "spdk/stdinc.h" 14 #include "spdk/trace.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 /** Trace parser object used as a context for the parsing functions */ 21 struct spdk_trace_parser; 22 23 enum spdk_trace_parser_mode { 24 /** Regular file */ 25 SPDK_TRACE_PARSER_MODE_FILE, 26 /** Shared memory */ 27 SPDK_TRACE_PARSER_MODE_SHM, 28 }; 29 30 /** Describes trace file and options to use when parsing it */ 31 struct spdk_trace_parser_opts { 32 /** Either file name or shared memory name depending on mode */ 33 const char *filename; 34 /** Trace file type, either regular file or shared memory */ 35 int mode; 36 /** Logical core number to parse the traces from (or SPDK_TRACE_MAX_LCORE) for all cores */ 37 uint16_t lcore; 38 }; 39 40 /** 41 * Initialize the parser using a specified trace file. This results in parsing the traces, merging 42 * entries from multiple cores together and sorting them by their tsc, so it can take a significant 43 * amount of time to complete. 44 * 45 * \param opts Describes the trace file to parse. 46 * 47 * \return Parser object or NULL in case of any failures. 48 */ 49 struct spdk_trace_parser *spdk_trace_parser_init(const struct spdk_trace_parser_opts *opts); 50 51 /** 52 * Free any resources tied to a parser object. 53 * 54 * \param parser Parser to clean up. 55 */ 56 void spdk_trace_parser_cleanup(struct spdk_trace_parser *parser); 57 58 /** 59 * Return trace file describing the traces. 60 * 61 * \param parser Parser object to be used. 62 * 63 * \return Pointer to the trace file. 64 */ 65 const struct spdk_trace_file *spdk_trace_parser_get_file(const struct spdk_trace_parser *parser); 66 67 /** 68 * Return the highest tsc out of first entries across all specified cores. This value can be used 69 * to select entries from the subset of time we have the data from all reactors. 70 * 71 * \param parser Parser object to be used. 72 * 73 * \return Offset in tsc. 74 */ 75 uint64_t spdk_trace_parser_get_tsc_offset(const struct spdk_trace_parser *parser); 76 77 /** Describes a parsed trace entry */ 78 struct spdk_trace_parser_entry { 79 /** Pointer to trace entry */ 80 struct spdk_trace_entry *entry; 81 /** 82 * Index of an object this entry is a part of. It's only available for tracepoints with 83 * object_type != OBJECT_NONE. If unavailable, it'll be assigned to UINT64_MAX. 84 */ 85 uint64_t object_index; 86 /** The tsc of when the object tied to this entry was created */ 87 uint64_t object_start; 88 /** Logical core number */ 89 uint16_t lcore; 90 /** Related object index */ 91 uint64_t related_index; 92 /** Related object type */ 93 uint8_t related_type; 94 /** Tracepoint arguments */ 95 struct { 96 bool is_related; 97 union { 98 uint64_t integer; 99 void *pointer; 100 char string[UINT8_MAX + 1]; 101 } u; 102 } args[SPDK_TRACE_MAX_ARGS_COUNT]; 103 }; 104 105 /** 106 * Return next parsed trace entry. Once no more traces are available, this will return false and 107 * entry won't be touched. 108 * 109 * \param parser Parser object to be used. 110 * \param entry Tracepoint entry. 111 * 112 * \return True if a trace entry was available, false otherwise. 113 */ 114 bool spdk_trace_parser_next_entry(struct spdk_trace_parser *parser, 115 struct spdk_trace_parser_entry *entry); 116 117 /** 118 * Return the number of entries recorded on a given core. 119 * 120 * \param parser Parser object to be used. 121 * \param lcore Logical core number. 122 * 123 * \return Number of entries. 124 */ 125 uint64_t spdk_trace_parser_get_entry_count(const struct spdk_trace_parser *parser, uint16_t lcore); 126 127 #ifdef __cplusplus 128 } 129 #endif 130 131 #endif /* SPDK_TRACE_PARSER_H */ 132