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 <paul.dale@oracle.com>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8463)

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<OSSL_trace_set_callback(3)/Trace types>.
 The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
 with the functions described here.
 
+Tracing for a specific category is enabled if a so called
+I<trace channel> 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<simple trace channel> and a I<callback trace channel>,
+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</Macros> section below.
+
+
 =head2 Functions
 
 OSSL_trace_enabled() can be used to check if tracing for the given
@@ -46,7 +83,7 @@ is I<mandatory>.
 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<BIO> C<trc_out> 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<OSSL_TRACE1()>, ... C<OSSL_TRACE9()> 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</Convenience Macros> above:
+For example, take this example from L</Macros> section above:
 
  OSSL_TRACE_BEGIN(TLS) {
 

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<trace channel> 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<simple trace channel> and a I<callback trace channel>,
+respectively.
 
 =head2 Functions
 
 OSSL_trace_set_channel() is used to enable the given trace C<category>
-by giving it the B<BIO> C<bio>.
+by attaching the B<BIO> C<bio> 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<category> by giving it the tracer callback C<cb> with the associated
 data C<data>, which will simply be passed through to C<cb> whenever
-it's called.
+it's called. The callback function is internally wrapped by a
+dedicated BIO object, the so called I<callback trace channel>.
 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<OSSL_TRACE_CTRL_DURING>
+=item C<OSSL_TRACE_CTRL_WRITE>
 
-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<OSSL_TRACE_CTRL_WRITE> callbacks can occur
+inside a group marked by a pair of C<OSSL_TRACE_CTRL_BEGIN> and
+C<OSSL_TRACE_CTRL_END> calls, but never outside such a group.
 
 =item C<OSSL_TRACE_CTRL_END>
 
@@ -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,

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