[PATCH v1 5/7] docs: mark intention to deprecate TCG tracing functionality

[Daniel P. Berrangé]

On Wed, May 05, 2021 at 10:22:57AM +0100, Alex Bennée wrote:
> Currently attempts to add a new TCG trace events results in failures
> to build. Previous discussions have suggested maybe it's time to mark
> the feature as deprecated and push people towards using plugins.
> 
> Signed-off-by: Alex Bennée <alex.bennee at linaro.org>
> Cc: Luis Vilanova <vilanova at imperial.ac.uk>
> Cc: Stefan Hajnoczi <stefanha at redhat.com>
> ---
>  docs/devel/tcg-plugins.rst |  2 ++
>  docs/devel/tracing.rst     |  7 +++++++
>  docs/system/deprecated.rst | 13 +++++++++++++
>  3 files changed, 22 insertions(+)
> 
> diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst
> index 18c6581d85..edf04e3091 100644
> --- a/docs/devel/tcg-plugins.rst
> +++ b/docs/devel/tcg-plugins.rst
> @@ -3,6 +3,8 @@
>     Copyright (c) 2019, Linaro Limited
>     Written by Emilio Cota and Alex Bennée
>  
> +.. _tcgplugin-ref:
> +
>  ================
>  QEMU TCG Plugins
>  ================
> diff --git a/docs/devel/tracing.rst b/docs/devel/tracing.rst
> index ba83954899..6b0f46cd54 100644
> --- a/docs/devel/tracing.rst
> +++ b/docs/devel/tracing.rst
> @@ -414,6 +414,13 @@ disabled, this check will have no performance impact.
>  "tcg"
>  -----
>  
> +.. warning::
> +   The ability to add new TCG trace points relies on a having a good
> +   understanding of the TCG internals. In the meantime TCG plugins
> +   have been introduced which solve many of the same problems with
> +   more of a focus on analysing guest code. See :ref:`tcgplugin-ref`
> +   for more details.
> +
>  Guest code generated by TCG can be traced by defining an event with the "tcg"
>  event property. Internally, this property generates two events:
>  "<eventname>_trans" to trace the event at translation time, and
> diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
> index 80cae86252..0c9d3c1e1e 100644
> --- a/docs/system/deprecated.rst
> +++ b/docs/system/deprecated.rst
> @@ -312,6 +312,19 @@ The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
>  (the ISA has never been upstreamed to a compiler toolchain). Therefore
>  this CPU is also deprecated.
>  
> +TCG introspection features
> +--------------------------
> +
> +TCG trace-events (since 6.1)
> +''''''''''''''''''''''''''''
> +
> +The ability to add new TCG trace points has bit rotted and as the

When you say this "has bit rotted", just how bad is the situation ?

Is the TCG tracing still usable at all, or is is fully broken
already ?


> +feature can be replicated with TCG plugins it will be deprecated. If
> +any user is currently using this feature and needs help with
> +converting to using TCG plugins they should contact the qemu-devel
> +mailing list.
> +

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|