From c37e635065a5bcb744dfb282f59e978e41490ce4 Mon Sep 17 00:00:00 2001 From: "Dr. Matthias St. Pierre" Date: Tue, 12 Mar 2019 23:35:45 +0100 Subject: [PATCH] trace: update the documentation This commit adds some missing symbols and other minor enhancements. In particular, it establishes the term 'channel' as a synonym for a BIO object attached to a trace category, and introduces the concept of a 'simple' channel versus a 'callback' channel. Reviewed-by: Paul Dale Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/8463) --- doc/man3/OSSL_trace_enabled.pod | 55 ++++++++++++++++++++++++++--- doc/man3/OSSL_trace_set_channel.pod | 30 +++++++++++----- util/private.num | 6 ++++ 3 files changed, 78 insertions(+), 13 deletions(-) diff --git a/doc/man3/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod index db3f99c89b..98e3bd6356 100644 --- a/doc/man3/OSSL_trace_enabled.pod +++ b/doc/man3/OSSL_trace_enabled.pod @@ -2,7 +2,8 @@ =head1 NAME -OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end +OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end, +OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9 - OpenSSL Tracing API =head1 SYNOPSIS @@ -14,6 +15,18 @@ OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end BIO *OSSL_trace_begin(int category); void OSSL_trace_end(int category, BIO *channel); + /* trace group macros */ + OSSL_TRACE_BEGIN(category) { + ... + } OSSL_TRACE_END(category); + + /* one-shot trace macros */ + OSSL_TRACE1(category, format, arg1) + OSSL_TRACE2(category, format, arg1, arg2) + ... + OSSL_TRACE9(category, format, arg1, ..., arg9) + + =head1 DESCRIPTION The functions described here are mainly interesting for those who provide @@ -30,6 +43,30 @@ L. The fallback type C should I be used with the functions described here. +Tracing for a specific category is enabled if a so called +I is attached to it. A trace channel is simply a +BIO object to which the application can write its trace output. + +The application has two different ways of registering a trace channel, +either by directly providing a BIO object using OSSL_trace_set_channel(), +or by providing a callback routine using OSSL_trace_set_callback(). +The latter is wrapped internally by a dedicated BIO object, so for the +tracing code both channel types are effectively indistinguishable. +We call them a I and a I, +respectively. + +To produce trace output, it is necessary to obtain a pointer to the +trace channel (i.e., the BIO object) using OSSL_trace_begin(), write +to it using arbitrary BIO output routines, and finally releases the +channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end() +calls surrounding the trace output create a group, which acts as a +critical section (guarded by a mutex) to ensure that the trace output +of different threads does not get mixed up. + +The tracing code normally does not call OSSL_trace_{begin,end}() directly, +but rather uses a set of convenience macros, see the L section below. + + =head2 Functions OSSL_trace_enabled() can be used to check if tracing for the given @@ -46,7 +83,7 @@ is I. The result of trying to produce tracing output outside of such sections is undefined. -=head2 Convenience Macros +=head2 Macros There are a number of convenience macros defined, to make tracing easy and consistent. @@ -60,7 +97,7 @@ the B C and are used as follows to wrap a trace section: } OSSL_TRACE_END(TLS); -This will normally expands to: +This will normally expand to: do { BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); @@ -98,6 +135,16 @@ This will normally expand to: OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); } while (0); + +C, ... C are one-shot macros which essentially wrap +a single BIO_printf() into a tracing group. + +The call OSSL_TRACEn(category, format, arg1, ..., argN) expands to: + + OSSL_TRACE_BEGIN(category) { + BIO_printf(trc_out, format, arg1, ..., argN) + } OSSL_TRACE_END(category) + =head1 NOTES It is advisable to always check that a trace type is enabled with @@ -133,7 +180,7 @@ nothing. =item * the convenience macros are defined to produce dead code. -For example, take this example from L above: +For example, take this example from L section above: OSSL_TRACE_BEGIN(TLS) { diff --git a/doc/man3/OSSL_trace_set_channel.pod b/doc/man3/OSSL_trace_set_channel.pod index fb680a52a7..773a6b1064 100644 --- a/doc/man3/OSSL_trace_set_channel.pod +++ b/doc/man3/OSSL_trace_set_channel.pod @@ -25,14 +25,21 @@ This output comes in form of free text for humans to read. The trace output is divided into categories which can be enabled individually. -They are enabled by giving them a channel in form of a BIO, or a -tracer callback, which is responsible for performing the actual -output. +Every category can be enabled individually by attaching a so called +I to it, which in the simplest case is just a BIO object +to which the application can write the tracing output for this category. +Alternatively, the application can provide a tracer callback in order to +get more finegrained trace information. This callback will be wrapped +internally by a dedicated BIO object. + +For the tracing code, both trace channel types are indistinguishable. +These are called a I and a I, +respectively. =head2 Functions OSSL_trace_set_channel() is used to enable the given trace C -by giving it the B C. +by attaching the B C object as (simple) trace channel. OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add an extra line for each channel, to be output before and after group of @@ -46,7 +53,8 @@ OSSL_trace_set_callback() instead. OSSL_trace_set_callback() is used to enable the given trace C by giving it the tracer callback C with the associated data C, which will simply be passed through to C whenever -it's called. +it's called. The callback function is internally wrapped by a +dedicated BIO object, the so called I. This should be used when it's desirable to do form the trace output to something suitable for application needs where a prefix and suffix line aren't enough. @@ -78,9 +86,13 @@ callback the possibility to output a dynamic starting line, or set a prefix that should be output at the beginning of each line, or something other. -=item C +=item C -The callback is called from any regular BIO output routine. +This callback is called whenever data is written to the BIO by some +regular BIO output routine. +An arbitrary number of C callbacks can occur +inside a group marked by a pair of C and +C calls, but never outside such a group. =item C @@ -177,8 +189,8 @@ success, or 0 on failure. =head1 EXAMPLES -In all examples below, we assume that the trace producing code is -this: +In all examples below, the trace producing code is assumed to be +the following: int foo = 42; const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7, diff --git a/util/private.num b/util/private.num index 1fbc160cf5..6c37fc0553 100644 --- a/util/private.num +++ b/util/private.num @@ -503,3 +503,9 @@ ASYNC_STATUS_EAGAIN define ASYNC_STATUS_OK define ASYNC_STATUS_ERR define ASYNC_STATUS_UNSUPPORTED define +OSSL_TRACE_BEGIN define +OSSL_TRACE_END define +OSSL_TRACE_CANCEL define +OSSL_TRACE1 define +OSSL_TRACE2 define +OSSL_TRACE9 define -- 2.34.1