[PULL 29/32] target/avr: Add section into QEMU documentation

[Philippe Mathieu-Daudé]

From: Thomas Huth <huth@tuxfamily.org>

The new section explains basic ways of using AVR target in QEMU.

Signed-off-by: Michael Rolnik <mrolnik@gmail.com>
[thuth: Converted doc from texi to Sphinx syntax]
Signed-off-by: Thomas Huth <huth@tuxfamily.org>
Message-Id: <20200705140315.260514-31-huth@tuxfamily.org>
Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
---
 docs/system/target-avr.rst | 37 +++++++++++++++++++++++++++++++++++++
 docs/system/targets.rst    |  1 +
 2 files changed, 38 insertions(+)
 create mode 100644 docs/system/target-avr.rst

diff --git a/docs/system/target-avr.rst b/docs/system/target-avr.rst
new file mode 100644
index 0000000000..dc99afc895
--- /dev/null
+++ b/docs/system/target-avr.rst
@@ -0,0 +1,37 @@
+.. _AVR-System-emulator:
+
+AVR System emulator
+-------------------
+
+Use the executable ``qemu-system-avr`` to emulate a AVR 8 bit based machine.
+These can have one of the following cores: avr1, avr2, avr25, avr3, avr31,
+avr35, avr4, avr5, avr51, avr6, avrtiny, xmega2, xmega3, xmega4, xmega5,
+xmega6 and xmega7.
+
+As for now it supports few Arduino boards for educational and testing purposes.
+These boards use a ATmega controller, which model is limited to USART & 16-bit
+timer devices, enought to run FreeRTOS based applications (like
+https://github.com/seharris/qemu-avr-tests/blob/master/free-rtos/Demo/AVR_ATMega2560_GCC/demo.elf
+).
+
+Following are examples of possible usages, assuming demo.elf is compiled for
+AVR cpu
+
+ - Continuous non interrupted execution:
+   ``qemu-system-avr -machine mega2560 -bios demo.elf``
+
+ - Continuous non interrupted execution with serial output into telnet window:
+   ``qemu-system-avr -machine mega2560 -bios demo.elf -serial
+   tcp::5678,server,nowait -nographic``
+   and then in another shell
+   ``telnet localhost 5678``
+
+ - Debugging wit GDB debugger:
+   ``qemu-system-avr -machine mega2560 -bios demo.elf -s -S``
+   and then in another shell
+   ``avr-gdb demo.elf``
+   and then within GDB shell
+   ``target remote :1234``
+
+ - Print out executed instructions:
+   ``qemu-system-avr -machine mega2560 -bios demo.elf -d in_asm``
diff --git a/docs/system/targets.rst b/docs/system/targets.rst
index 99435a3eba..560783644d 100644
--- a/docs/system/targets.rst
+++ b/docs/system/targets.rst
@@ -19,3 +19,4 @@ Contents:
    target-xtensa
    target-s390x
    target-rx
+   target-avr
-- 
2.21.3