Fault Injection Framework
                           =========================

Introduction
------------

The fault injection framework allows users to write python scripts to inject
faults through the QMP (QEMU Machine Protocol) during execution.

Basically it's composed of a Python API which makes some QMP commands easy to
send to the machine:
  * read/write a memory location from a CPU view.
  * set a GPIO line.
  * get/set a QOM property.

In addition it allows the Python script to be notified back by QEMU so it can
do any of the previous commands at a given time.

Today the available function in the API are the following:
  * notify(time_ns, cb)
  * inject_write(address, value, size, cpu)
  * read(address, size, cpu)
  * get_qom_property(path, property)
  * set_qom_property(path, property, value)
  * set_gpio(path, gpio, num, value)

Empty Example
-------------

This is an empty example to begin:

import fault_injection
import sys

framework = None

def main():
    # The injection framework will parse the command line automatically
    # (eg: the qmp socket/port.. etc)
    sys.stdout.write('Fault Injection Example\n')
    global framework
    framework = fault_injection.FaultInjectionFramework(sys.argv[1])

    framework.run()
    sys.exit(1)

if __name__ == '__main__':
    main()

To run the example just save the example in `script/qmp/example_scenario`
Run qemu with the additional arguments: `-S -qmp unix:/path/to/qmp-sock,server`
in order to wait for a qmp connection and stop the QEMU machine.
Run the example with: `./example_scenario /path/to/qmp-sock`

It will start the simulation inside QEMU and do nothing else.

Adding a callback at a given time
---------------------------------

As described above a callback can be added in the python scenario.
For example we can create the following callback which write 0xDEADBEEF @0 with
a size of 4 from cpu 0 and then reads it back:

def write_mem_callback():
    print 'write_mem_callback()'
    framework.write(0x0, 0xDEADBEEF, 4, 0)
    val = framework.read(0x0, 4, 0)
    print('value read: 0x' + str(val['value']))

Then we can notify it in the main function before framework.run():
`framework.notify(1000000000, write_mem_callback)`

The script works as expected:

write_mem_callback()
value read: 0xDEADBEEF

Using the python interpreter
----------------------------

The Python interpreter can be used to send the command above:
For example to set the vinithi bit to 1 for the /rpu_cpu@0 the following
commands can be done in the script/qmp directory:

$ python
>>> import fault_injection
>>> inj=fault_injection.FaultInjectionFramework("../../qmp-sock", 0)
Connected to QEMU 2.2.50

>>> inj.help()

Fault Injection Framework Commands
==================================

cont()
 * Resume the simulation when the Virtual Machine is stopped.

run()
 * Start the simulation when the notify are set.

notify(time_ns, cb)
 * Notify the callback cb in guest time time_ns.

write(address, value, size, cpu)
 * Write @value of size @size at @address from @cpu.
 * @cpu can be either a qom path or the cpu id.

read(address, size, cpu)
 * Read a value of size @size at @address from @cpu.
 * @cpu can be either a qom path or the cpu id.
 * Returns the value.

get_qom_property(path, property)
 * Get a qom property.
 * Returns the qom property named @property in @path.

set_qom_property(path, property, value)
 * Set the property named @property in @path with @value.

set_gpio(path, gpio, num, value)
 * Set the gpio named @gpio number @num in @path with the @val.
 * @val is a boolean.

>>> inj.set_gpio('/rpu_cpu@0', 'vinithi', 0, 1)

Notes
-----

The user can turn debug information on by passing a level to the framework
constructor eg:
"framework = fault_injection.FaultInjectionFramework(1)" will print timed traces
such as write or read.
"framework = fault_injection.FaultInjectionFramework(2)" will print the QMP
commands as well.