replay: added replay log format description

Audio data is recorded and replay automatically. The command line for recording

and replaying must contain identical specifications of audio hardware, e.g.:

 -soundhw ac97

Replay log format

-----------------

Record/replay log consits of the header and the sequence of execution

events. The header includes 4-byte replay version id and 8-byte reserved

field. Version is updated every time replay log format changes to prevent

using replay log created by another build of qemu.

The sequence of the events describes virtual machine state changes.

It includes all non-deterministic inputs of VM, synchronization marks and

instruction counts used to correctly inject inputs at replay.

Synchronization marks (checkpoints) are used for synchronizing qemu threads

that perform operations with virtual hardware. These operations may change

system's state (e.g., change some register or generate interrupt) and

therefore should execute synchronously with CPU thread.

Every event in the log includes 1-byte event id and optional arguments.

When argument is an array, it is stored as 4-byte array length

and corresponding number of bytes with data.

Here is the list of events that are written into the log:

 - EVENT_INSTRUCTION. Instructions executed since last event.

   Argument: 4-byte number of executed instructions.

 - EVENT_INTERRUPT. Used to synchronize interrupt processing.

 - EVENT_EXCEPTION. Used to synchronize exception handling.

 - EVENT_ASYNC. This is a group of events. They are always processed

   together with checkpoints. When such an event is generated, it is

   stored in the queue and processed only when checkpoint occurs.

   Every such event is followed by 1-byte checkpoint id and 1-byte

   async event id from the following list:

     - REPLAY_ASYNC_EVENT_BH. Bottom-half callback. This event synchronizes

       callbacks that affect virtual machine state, but normally called

       asyncronously.

       Argument: 8-byte operation id.

     - REPLAY_ASYNC_EVENT_INPUT. Input device event. Contains

       parameters of keyboard and mouse input operations

       (key press/release, mouse pointer movement).

       Arguments: 9-16 bytes depending of input event.

     - REPLAY_ASYNC_EVENT_INPUT_SYNC. Internal input synchronization event.

     - REPLAY_ASYNC_EVENT_CHAR_READ. Character (e.g., serial port) device input

       initiated by the sender.

       Arguments: 1-byte character device id.

                  Array with bytes were read.

     - REPLAY_ASYNC_EVENT_BLOCK. Block device operation. Used to synchronize

       operations with disk and flash drives with CPU.

       Argument: 8-byte operation id.

     - REPLAY_ASYNC_EVENT_NET. Incoming network packet.

       Arguments: 1-byte network adapter id.

                  4-byte packet flags.

                  Array with packet bytes.

 - EVENT_SHUTDOWN. Occurs when user sends shutdown event to qemu,

   e.g., by closing the window.

 - EVENT_CHAR_WRITE. Used to synchronize character output operations.

   Arguments: 4-byte output function return value.

              4-byte offset in the output array.

 - EVENT_CHAR_READ_ALL. Used to synchronize character input operations,

   initiated by qemu.

   Argument: Array with bytes that were read.

 - EVENT_CHAR_READ_ALL_ERROR. Unsuccessful character input operation,

   initiated by qemu.

   Argument: 4-byte error code.

 - EVENT_CLOCK + clock_id. Group of events for host clock read operations.

   Argument: 8-byte clock value.

 - EVENT_CHECKPOINT + checkpoint_id. Checkpoint for synchronization of

   CPU, internal threads, and asynchronous input events. May be followed

   by one or more EVENT_ASYNC events.

 - EVENT_END. Last event in the log.