[Qemu-devel] [RFC PATCH 5/5] docs: add fault injection framework documentation

[Damien Hedde <damien.hedde@greensocs.com>]

This adds some hints about how to use the fault injection framework.

This is based on Frederic Konrad's work.

Signed-off-by: Damien Hedde <damien.hedde@greensocs.com>
---
 docs/fault_injection.txt | 149 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 docs/fault_injection.txt

diff --git a/docs/fault_injection.txt b/docs/fault_injection.txt
new file mode 100644
index 0000000000..3cb1c1fd1a
--- /dev/null
+++ b/docs/fault_injection.txt
@@ -0,0 +1,149 @@
+                           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 virtual/memory memory location.
+  * 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 virtual clock time.
+
+Today the available function in the API are the following:
+  * notify(time_ns, cb, do_halt)
+  * write_mem(address, value, size, cpu)
+  * read_mem(address, size, cpu)
+  * write_pmem(address, value, size)
+  * read_pmem(address, size)
+  * 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_mem(0x0, 0xDEADBEEF, 4, 0)
+    val = framework.read_mem(0x0, 4, 0)
+    print 'value read: 0x%8.8X' %val
+
+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.
+
+notify(time_ns, cb, do_pause)
+ * Notify the callback cb in guest time time_ns. Simulation is stopped only if
+   do_pause is set to True.
+
+run_once()
+ * Start the simulation and handle a callback set by notify. Return after
+   first callback is handled
+
+run()
+ * Start the simulation and handle the callbacks set by notify. Do not return
+   until the end of the simulation.
+
+write_mem(address, value, size, cpu)
+ * Write @value of size @size at virtual @address from @cpu.
+ * @cpu is the cpu id.
+
+write_pmem(address, value, size)
+ * Like write_mem, but on a physical @address.
+
+read_mem(address, size, cpu)
+ * Read a value of size @size at virtual @address from @cpu.
+ * @cpu is the cpu id.
+ * Returns the value.
+
+read_pmem(address, size)
+ * Like read_mem, but on a physical @address.
+
+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.
+
-- 
2.22.0