struct trace_buffer_header

This header provides framing information about the buffer, for use in

implementing circular buffering and double(streaming) buffering.

Writing to the buffer has conceptually three modes:

oneshot, circular, streaming.

Buffers are passed from Trace Manager to Trace Provider in vmos.

How the buffer is treated depends on the writing mode.

For "oneshot" mode the vmo is one big simple buffer.

Using one big buffer means durable and non-durable records all share the

same buffer.

For simplicity in the code, oneshot mode uses rolling buffer 0.

For "circular" and "streaming" buffering modes, the vmo is treated as a

"virtual buffer" and is split into three logical parts:

- one buffer for "durable" records

- two buffers, labeled 0 and 1, for "non-durable" records, called

"rolling buffers"

Writing switches back and forth between the two rolling buffers as each

fills. Streaming buffering differs from circular buffering in that the Trace

Manager is involved in saving each rolling buffer as it fills.

Besides consistency, a nice property of using two separate buffers for

circular mode is that, because records are variable sized, there are no

issues trying to find the "first" non-durable record in the complete virtual

buffer after a wrap: It's always the first record of the other rolling

buffer.

To help preserve data integrity tracing stops when the durable buffer fills,

even in circular mode.

TODO(dje): Relax this restriction, and accept potentially more lost data.

Durable records:

- initialization record

- string table

- thread table

TODO(dje): Move initialization record to header?

Non-durable records:

- everything else

The total physical buffer is laid out as follows (without gaps):

- header

- durable buffer (empty in oneshot mode)

- non-durable buffer 0

- non-durable buffer 1 (empty in oneshot mode)

It is an invariant that:

oneshot:

total_size == header + rolling_buffer_size

circular/streaming:

total_size == header + durable_buffer_size + 2 * rolling_buffer_size

All buffer sizes must be a multiple of 8 as all records are a multiple of 8.