VirtualBox

source: vbox/trunk/include/iprt/formats/tracelog.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 22 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.0 KB
Line 
1/* $Id: tracelog.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * IPRT, Binary trace log format.
4 */
5
6/*
7 * Copyright (C) 2018-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * The contents of this file may alternatively be used under the terms
26 * of the Common Development and Distribution License Version 1.0
27 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28 * in the VirtualBox distribution, in which case the provisions of the
29 * CDDL are applicable instead of those of the GPL.
30 *
31 * You may elect to license modified versions of this file under the
32 * terms and conditions of either the GPL or the CDDL or both.
33 *
34 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35 */
36
37#ifndef IPRT_INCLUDED_formats_tracelog_h
38#define IPRT_INCLUDED_formats_tracelog_h
39#ifndef RT_WITHOUT_PRAGMA_ONCE
40# pragma once
41#endif
42
43#include <iprt/assert.h>
44#include <iprt/cdefs.h>
45#include <iprt/types.h>
46
47
48/** @defgroup grp_rt_formats_tracelog Binary trace log structures and definitions
49 * @ingroup grp_rt_formats
50 * @{
51 */
52
53/** Size of the record magic in bytes. */
54#define TRACELOG_MAGIC_SZ 8
55
56/**
57 * Trace log identification and options header.
58 */
59typedef struct TRACELOGHDR
60{
61 /** Identifiaction magic. */
62 uint8_t szMagic[8];
63 /** Endianess indicator. */
64 uint32_t u32Endianess;
65 /** File version indicator. */
66 uint32_t u32Version;
67 /** File flags (MBZ for now). */
68 uint32_t fFlags;
69 /** Size of the trace log description in bytes following this header. */
70 uint32_t cbStrDesc;
71 /** Size of a pointer item in bytes. */
72 uint8_t cbTypePtr;
73 /** size of the size_t item in bytes. */
74 uint8_t cbTypeSize;
75 /** Padding to an 4 byte boundary. */
76 uint16_t u16Reserved0;
77 /** Padding to an 8 byte boundary. */
78 uint32_t u32Reserved0;
79 /** Starting timestamp when the log was initialised. */
80 uint64_t u64TsStart;
81 /** Padding to 64byte boundary, reserved for future use. */
82 uint64_t au64Reserved[3];
83} TRACELOGHDR;
84AssertCompileSize(TRACELOGHDR, 64);
85/** Pointer to a trace log header. */
86typedef TRACELOGHDR *PTRACELOGHDR;
87/** Pointer to a const trace log header. */
88typedef const TRACELOGHDR *PCTRACELOGHDR;
89
90/** Magic value for a trace log file (TRACELOG backwards). */
91#define TRACELOG_HDR_MAGIC "GOLECART"
92/** Endianess indicator. */
93#define TRACELOG_HDR_ENDIANESS 0xdeadc0de
94/** The default version (Higher 16bits major, low 16bits minor version). */
95#define TRACELOG_VERSION RT_MAKE_U32(1, 0)
96
97
98/**
99 * Trace log event structure descriptor.
100 */
101typedef struct TRACELOGEVTDESC
102{
103 /** Event descriptor magic. */
104 uint8_t szMagic[8];
105 /** Event structure descriptor ID for identification in events later. */
106 uint32_t u32Id;
107 /** Severity class of the event .*/
108 uint32_t u32Severity;
109 /** Size of the identifier string in bytes without terminator. */
110 uint32_t cbStrId;
111 /** Size of the description string in bytes without terminator. */
112 uint32_t cbStrDesc;
113 /** Number of event items following. */
114 uint32_t cEvtItems;
115 /** Padding to end the descriptor on a 32 byte boundary. */
116 uint32_t au32Padding0;
117} TRACELOGEVTDESC;
118AssertCompileSize(TRACELOGEVTDESC, 32);
119/** Pointer to a trace log event structure descriptor. */
120typedef TRACELOGEVTDESC *PTRACELOGEVTDESC;
121/** Pointer to a const trace log event structure descriptor. */
122typedef const TRACELOGEVTDESC *PCTRACELOGEVTDESC;
123
124/** Event descriptor magic. */
125#define TRACELOG_EVTDESC_MAGIC "\0CSEDTVE"
126
127/** Severity: Informational event*/
128#define TRACELOG_EVTDESC_SEVERITY_INFO UINT32_C(0)
129/** Severity: Warning event*/
130#define TRACELOG_EVTDESC_SEVERITY_WARNING UINT32_C(1)
131/** Severity: Error event*/
132#define TRACELOG_EVTDESC_SEVERITY_ERROR UINT32_C(2)
133/** Severity: Fatal event*/
134#define TRACELOG_EVTDESC_SEVERITY_FATAL UINT32_C(3)
135/** Severity: Debug event*/
136#define TRACELOG_EVTDESC_SEVERITY_DEBUG UINT32_C(4)
137
138
139/**
140 * Trace log event item descriptor.
141 */
142typedef struct TRACELOGEVTITEMDESC
143{
144 /** Event item descriptor magic. */
145 uint8_t szMagic[8];
146 /** Size of the item name string in bytes without terminator. */
147 uint32_t cbStrName;
148 /** Size of the optional description string in bytes without terminator. */
149 uint32_t cbStrDesc;
150 /** Item type */
151 uint32_t u32Type;
152 /** Size of the raw data type if static throughout. */
153 uint32_t cbRawData;
154 /** Padding to end the descriptor on a 32 byte boundary. */
155 uint32_t au32Padding0[2];
156} TRACELOGEVTITEMDESC;
157AssertCompileSize(TRACELOGEVTITEMDESC, 32);
158/** Pointer to a trace log event item descriptor. */
159typedef TRACELOGEVTITEMDESC *PTRACELOGEVTITEMDESC;
160/** Pointer to a const trace log event item descriptor. */
161typedef const TRACELOGEVTITEMDESC *PCTRACELOGEVTITEMDESC;
162
163/** Event item descriptor magic. */
164#define TRACELOG_EVTITEMDESC_MAGIC "CSEDMETI"
165/** Boolean type. */
166#define TRACELOG_EVTITEMDESC_TYPE_BOOL UINT32_C(1)
167/** Unsigned 8bit integer type. */
168#define TRACELOG_EVTITEMDESC_TYPE_UINT8 UINT32_C(2)
169/** Signed 8bit integer type. */
170#define TRACELOG_EVTITEMDESC_TYPE_INT8 UINT32_C(3)
171/** Unsigned 16bit integer type. */
172#define TRACELOG_EVTITEMDESC_TYPE_UINT16 UINT32_C(4)
173/** Signed 16bit integer type. */
174#define TRACELOG_EVTITEMDESC_TYPE_INT16 UINT32_C(5)
175/** Unsigned 32bit integer type. */
176#define TRACELOG_EVTITEMDESC_TYPE_UINT32 UINT32_C(6)
177/** Signed 32bit integer type. */
178#define TRACELOG_EVTITEMDESC_TYPE_INT32 UINT32_C(7)
179/** Unsigned 64bit integer type. */
180#define TRACELOG_EVTITEMDESC_TYPE_UINT64 UINT32_C(8)
181/** Signed 64bit integer type. */
182#define TRACELOG_EVTITEMDESC_TYPE_INT64 UINT32_C(9)
183/** 32bit floating point type. */
184#define TRACELOG_EVTITEMDESC_TYPE_FLOAT32 UINT32_C(10)
185/** 64bit floating point type. */
186#define TRACELOG_EVTITEMDESC_TYPE_FLOAT64 UINT32_C(11)
187/** Raw binary data type. */
188#define TRACELOG_EVTITEMDESC_TYPE_RAWDATA UINT32_C(12)
189/** Pointer data type. */
190#define TRACELOG_EVTITEMDESC_TYPE_POINTER UINT32_C(13)
191/** size_t data type. */
192#define TRACELOG_EVTITEMDESC_TYPE_SIZE UINT32_C(14)
193
194/**
195 * Trace log event marker.
196 */
197typedef struct TRACELOGEVT
198{
199 /** Event marker magic. */
200 uint8_t szMagic[8];
201 /** Trace log sequence number to identify the event uniquely. */
202 uint64_t u64SeqNo;
203 /** Timestamp for the marker (resolution is infered from the header). */
204 uint64_t u64Ts;
205 /** Event group ID for grouping different events together - for no grouped event. */
206 uint64_t u64EvtGrpId;
207 /** Parent group ID this event originated from. */
208 uint64_t u64EvtParentGrpId;
209 /** Overall number of bytes for the event data following including static and possibly variable data. */
210 uint32_t cbEvtData;
211 /** Number of size_t sized raw data size indicators before the raw event data follows. */
212 uint32_t cRawEvtDataSz;
213 /** Event flags. */
214 uint32_t fFlags;
215 /** Event structure descriptor ID to use for structuring the event data. */
216 uint32_t u32EvtDescId;
217 /** Reserved for future use. */
218 uint64_t u64Reserved0;
219} TRACELOGEVT;
220AssertCompileSize(TRACELOGEVT, 64);
221/** Pointer to a trace log event marker. */
222typedef TRACELOGEVT *PTRACELOGEVT;
223/** Pointer to a const trace log event marker. */
224typedef const TRACELOGEVT *PCTRACELOGEVT;
225
226/** Event marker descriptor magic. */
227#define TRACELOG_EVT_MAGIC "\0RKRMTVE"
228/** Flag indicating this is the start of an event group and all subsequent events
229 * with the same group ID belong to the same group. */
230#define TRACELOG_EVT_F_GRP_START RT_BIT_32(0)
231/** Flag indicating this is the end of an event group which was started earlier. */
232#define TRACELOG_EVT_F_GRP_END RT_BIT_32(1)
233/** Combination of valid flags. */
234#define TRACELOG_EVT_F_VALID (TRACELOG_EVT_F_GRP_START | TRACELOG_EVT_F_GRP_END)
235
236/** @} */
237
238#endif /* !IPRT_INCLUDED_formats_tracelog_h */
239
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette