diff options
Diffstat (limited to 'src/corelib/global/qtrace_p.h')
| -rw-r--r-- | src/corelib/global/qtrace_p.h | 173 |
1 files changed, 133 insertions, 40 deletions
diff --git a/src/corelib/global/qtrace_p.h b/src/corelib/global/qtrace_p.h index d9011c6066..f4e39ffe2b 100644 --- a/src/corelib/global/qtrace_p.h +++ b/src/corelib/global/qtrace_p.h @@ -1,41 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Rafael Roquetto <rafael.roquetto@kdab.com> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the QtCore module of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 3 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL3 included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 3 requirements -** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 2.0 or (at your option) the GNU General -** Public license version 3 or any later version approved by the KDE Free -** Qt Foundation. The licenses are as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 -** included in the packaging of this file. Please review the following -** information to ensure the GNU General Public License requirements will -** be met: https://www.gnu.org/licenses/gpl-2.0.html and -** https://www.gnu.org/licenses/gpl-3.0.html. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Rafael Roquetto <rafael.roquetto@kdab.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only #ifndef QTRACE_P_H #define QTRACE_P_H @@ -93,7 +57,7 @@ * qcoreapplication_qrect(const QRect &rect) * * The provider file is then parsed by src/tools/tracegen, which can be - * switched to output either ETW or LTTNG tracepoint definitions. The provider + * switched to output either ETW, CTF or LTTNG tracepoint definitions. The provider * name is deduced to be basename(provider_file). * * To use the above (inside qtcore), you need to include @@ -111,12 +75,56 @@ * - QByteArray * - QUrl * - QRect + * - QRectF + * - QSize + * - QSizeF * * Dynamic arrays are supported using the syntax illustrated by * qcoreapplication_baz above. + * + * One can also add prefix for the generated providername_tracepoints_p.h file + * by specifying it inside brackets '{ }' in the tracepoints file. One can + * for example add forward declaration for a type: + * + * { + * QT_BEGIN_NAMESPACE + * class QEvent; + * QT_END_NAMESPACE + * } + * + * Metadata + * + * Metadata is used to add textual information for different types such + * as enums and flags. How this data is handled depends on the used backend. + * For ETW, the values are converted to text, for CTF and LTTNG they are used to add + * CTF enumerations, which are converted to text after tracing. + * + * Enumererations are specified using ENUM: + * + * ENUM { + * Enum0 = 0, + * Enum1 = 1, + * Enum2, + * RANGE(RangeEnum, 3 ... 10), + * } Name; + * + * Name must match to one of the enumerations used in the tracepoints. Range of values + * can be provided using RANGE(name, first ... last). All values must be unique. + * + * Flags are specified using FLAGS: + * + * FLAGS { + * Default = 0, + * Flag0 = 1, + * Flag1 = 2, + * Flag2 = 4, + * } Name; + * + * Name must match to one of the flags used in the tracepoints. Each value must be + * power of two and unique. */ -#include <QtCore/qglobal.h> +#include <QtCore/private/qglobal_p.h> #include <QtCore/qscopeguard.h> QT_BEGIN_NAMESPACE @@ -140,6 +148,91 @@ QT_BEGIN_NAMESPACE # define Q_TRACE_ENABLED(x) false #endif // defined(Q_TRACEPOINT) && !defined(QT_BOOTSTRAPPED) + +/* + * The Qt tracepoints can also be defined directly in the source files using + * the following macros. If using these macros, the tracepoints file is automatically + * generated using the tracepointgen tool. The tool scans the input files for + * these macros. These macros are ignored during compile time. Both automatic + * generation and manually specifying tracepoints in a file can't be done at the same + * time for the same provider. + * + * - Q_TRACE_INSTRUMENT(provider) + * Generate entry/exit tracepoints for a function. For example, member function + * + * void SomeClass::method(int param1, float param2) + * { + * ... + * } + * + * converted to use tracepoints: + * + * void Q_TRACE_INSTRUMENT(provider) SomeClass::method(int param1, float param2) + * { + * Q_TRACE_SCOPE(SomeClass_method, param1, param2); + * ... + * } + * + * generates following tracepoints in provider.tracepoints file: + * + * SomeClass_method_entry(int param1, float param2) + * SomeClass_method_exit() + * + * - Q_TRACE_PARAM_REPLACE(in, out) + * Can be used with Q_TRACE_INSTRUMENT to replace parameter type in with type out. + * If a parameter type is not supported by the tracegen tool, one can use this to + * change it to another supported type. + * + * void Q_TRACE_INSTRUMENT(provider) SomeClass::method(int param1, UserType param2) + * { + * Q_TRACE_PARAM_REPLACE(UserType, QString); + * Q_TRACE_SCOPE(SomeClass_method, param1, param2.toQString()); + * } + * + * - Q_TRACE_POINT(provider, tracepoint, ...) + * Manually specify tracepoint for the provider. 'tracepoint' is the full name + * of the tracepoint and ... can be zero or more parameters. + * + * Q_TRACE_POINT(provider, SomeClass_function_entry, int param1, int param2); + * + * generates following tracepoint: + * + * SomeClass_function_entry(int param1, int param2) + * + * - Q_TRACE_PREFIX(provider, prefix) + * Provide prefix for the tracepoint. Multiple prefixes can be specified for the same + * provider in different files, they are all concatenated into one in the + * provider.tracepoints file. + * + * Q_TRACE_PREFIX(provider, + * "QT_BEGIN_NAMESPACE" \ + * "class QEvent;" \ + * "QT_END_NAMESPACE") + * + * - Q_TRACE_METADATA(provider, metadata) + * Provides metadata for the tracepoint provider. + * + * Q_TRACE_METADATA(qtgui, + * "ENUM {" \ + * "Format_Invalid," \ + * "Format_Mono," \ + * "Format_MonoLSB," \ + * "Format_Indexed8," \ + * ... + * "} QImage::Format;" \ + * ); + * + * If the content of enum is empty or contains keyword AUTO, then the tracepointgen tool + * tries to find the enumeration from header files. + * + * Q_TRACE_METADATA(qtcore, "ENUM { AUTO, RANGE User ... MaxUser } QEvent::Type;"); + */ +#define Q_TRACE_INSTRUMENT(provider) +#define Q_TRACE_PARAM_REPLACE(in, out) +#define Q_TRACE_POINT(provider, tracepoint, ...) +#define Q_TRACE_PREFIX(provider, prefix) +#define Q_TRACE_METADATA(provider, metadata) + QT_END_NAMESPACE #endif // QTRACE_P_H |