trace: update docs to reflect new code generation approach

== Trace events ==

Each directory in the source tree can declare a set of static trace events

in a "trace-events" file. Each trace event declaration names the event, its

arguments, and the format string which can be used for pretty-printing:

=== Sub-directory setup ===

    qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"

    qemu_vfree(void *ptr) "ptr %p"

All "trace-events" files must be listed in the "trace-event-y" make variable

in the top level Makefile.objs. During build the individual files are combined

to create a "trace-events-all" file, which is processed by the "tracetool"

script during build to generate code for the trace events. The

"trace-events-all" file is also installed into "/usr/share/qemu".

Each directory in the source tree can declare a set of static trace events

in a local "trace-events" file. All directories which contain "trace-events"

files must be listed in the "trace-events-subdirs" make variable in the top

level Makefile.objs. During build, the "trace-events" file in each listed

subdirectory will be processed by the "tracetool" script to generate code for

the trace events.

The individual "trace-events" files are merged into a "trace-events-all" file,

which is also installed into "/usr/share/qemu" with the name "trace-events".

This merged file is to be used by the "simpletrace.py" script to later analyse

traces in the simpletrace data format.

In the sub-directory the following files will be automatically generated

 - trace.c - the trace event state declarations

 - trace.h - the trace event enums and probe functions

 - trace-dtrace.h - DTrace event probe specification

 - trace-dtrace.dtrace - DTrace event probe helper declaration

 - trace-dtrace.o - binary DTrace provider (generated by dtrace)

 - trace-ust.h - UST event probe helper declarations

Source files in the sub-directory should #include the local 'trace.h' file,

without any sub-directory path prefix. eg io/channel-buffer.c would do

  #include "trace.h"

To access the 'io/trace.h' file. While it is possible to include a trace.h

file from outside a source files' own sub-directory, this is discouraged in

general. It is strongly preferred that all events be declared directly in

the sub-directory that uses them. The only exception is where there are some

shared trace events defined in the top level directory trace-events file.

The top level directory generates trace files with a filename prefix of

"trace-root" instead of just "trace". This is to avoid ambiguity between

a trace.h in the current directory, vs the top level directory.

=== Using trace events ===

Trace events are invoked directly from source code like this:

special care to use PRId64 and PRIu64 for int64_t and uint64_t types,

respectively.  This ensures portability between 32- and 64-bit platforms.

Each event declaration will start with the event name, then its arguments,

finally a format string for pretty-printing. For example:

    qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"

    qemu_vfree(void *ptr) "ptr %p"

=== Hints for adding new trace events ===

1. Trace state changes in the code.  Interesting points in the code usually