From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from eggs.gnu.org ([2001:4830:134:3::10]:54949)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <eblake@redhat.com>) id 1bVikO-00024s-QC
	for qemu-devel@nongnu.org; Fri, 05 Aug 2016 13:17:25 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <eblake@redhat.com>) id 1bVikJ-0007TR-L1
	for qemu-devel@nongnu.org; Fri, 05 Aug 2016 13:17:23 -0400
Received: from mx1.redhat.com ([209.132.183.28]:58726)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <eblake@redhat.com>) id 1bVikJ-0007TN-CC
	for qemu-devel@nongnu.org; Fri, 05 Aug 2016 13:17:19 -0400
References: <147041636348.2523.2954972609232949598.stgit@fimbulvetr.bsc.es>
	<147041636895.2523.17410454408859217963.stgit@fimbulvetr.bsc.es>
From: Eric Blake <eblake@redhat.com>
Message-ID: <57A4CA1D.9040004@redhat.com>
Date: Fri, 5 Aug 2016 11:17:17 -0600
MIME-Version: 1.0
In-Reply-To: <147041636895.2523.17410454408859217963.stgit@fimbulvetr.bsc.es>
Content-Type: multipart/signed; micalg=pgp-sha256;
	protocol="application/pgp-signature";
	boundary="FpWPiTsXAlcppKH6BWoBj8CXXTHWQ4jsD"
Subject: Re: [Qemu-devel] [PATCH 1/6] hypertrace: Add documentation
List-Id: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel/>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: =?UTF-8?Q?Llu=c3=ads_Vilanova?= <vilanova@ac.upc.edu>, qemu-devel@nongnu.org
Cc: Stefan Hajnoczi <stefanha@redhat.com>

This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--FpWPiTsXAlcppKH6BWoBj8CXXTHWQ4jsD
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

On 08/05/2016 10:59 AM, Llu=C3=ADs Vilanova wrote:
> Signed-off-by: Llu=C3=ADs Vilanova <vilanova@ac.upc.edu>
> ---
>  docs/hypertrace.txt |  141 +++++++++++++++++++++++++++++++++++++++++++=
++++++++
>  docs/tracing.txt    |    3 +
>  2 files changed, 144 insertions(+)
>  create mode 100644 docs/hypertrace.txt
>=20
> diff --git a/docs/hypertrace.txt b/docs/hypertrace.txt
> new file mode 100644
> index 0000000..4a31bcd
> --- /dev/null
> +++ b/docs/hypertrace.txt
> @@ -0,0 +1,141 @@
> +=3D Hypertrace channel =3D

No explicit copyright means that this document inherits the project
default of GPLv2+. If that's not what you intended (or to be clear that
it IS what you intended), you may want to add a copyright and license blu=
rb.

> +
> +The hypertrace channel allows guest code to emit events in QEMU (the h=
ost) using
> +its tracing infrastructure (see "docs/trace.txt"). This works in both =
'system'
> +and 'user' modes. That is, hypertrace is to tracing, what hypercalls a=
re to
> +system calls.
> +
> +You can use this to emit an event on both guest and QEMU (host) traces=
 to easily
> +synchronize or correlate them. You could also modify you guest's traci=
ng system
> +to emit all events through the hypertrace channel, providing a unified=
 and fully
> +synchronized trace log. Another use case is timing the performance of =
guest code
> +when optimizing TCG (QEMU traces have a timestamp).

Do you need to state that this channel should only be opened up to
trusted guests, as otherwise it represents a security hole that a guest
can cause a host denial of service by emitting events as fast as possible=
?


> +3. Create a guest application using "qemu-hypertrace.h":
> +
> +    cat > /tmp/my-hypertrace.c <<EOF

I'd suggest <<\EOF here, to make it obvious that we don't want any $foo
parameter expansion in the heredoc.

> +    #include <stdio.h>
> +    #include <errno.h>
> +    #include <stdlib.h>
> +    #include <string.h>
> +    #include <qemu-hypertrace.h>
> +   =20
> +   =20
> +    int main(int argc, char **argv)
> +    {
> +        char *base =3D NULL;
> +        if (argc > 1) {
> +            base =3D argv[1];
> +        }
> +
> +        /* In 'user' mode this path must be the same we will use to st=
art QEMU. */
> +        if (qemu_hypertrace_init(base) !=3D 0) {
> +            fprintf(stderr, "error: qemu_hypertrace_init: %s\n", strer=
ror(errno));

Worth using perror() in this example code?

Overall looks reasonable.

--=20
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


--FpWPiTsXAlcppKH6BWoBj8CXXTHWQ4jsD
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
Comment: Public key at http://people.redhat.com/eblake/eblake.gpg
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJXpModAAoJEKeha0olJ0NqzYQIAKJqpR1pg71jil62aj7ahktt
a3hsy9lAAo/MBBt/j5yRLeDbhHz62I+HPl4qaMrrAHXqFC9GoICnnhPFUPOCYENk
B5qvWmauwRuUMUJ0dCrbDYcv8sftTCl1FpZtk3WbctzL665Iz0d5wh9utCBI86z5
ghh4nIUiEFQjHpuFRuVcAyrXnFkNIcnVDJdLR5Hit3aOFhtELNCyC4c+06v+bFT3
369kJfR2rgmh3VXMk7OaGI75ZtoP2YQ3gPCHykzXWI5h9hb5kleth88d6CY8X1+l
O0Kw4ULBc5y/9H4pwx96bTj7Z7EPg2yzU4a518qnQZD3xx0L/mfSiJrBU9d0SfQ=
=r2aI
-----END PGP SIGNATURE-----

--FpWPiTsXAlcppKH6BWoBj8CXXTHWQ4jsD--