Signed-off-by: Lluís Vilanova<address@hidden>
---
docs/backdoor.txt | 167 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 167 insertions(+), 0 deletions(-)
create mode 100644 docs/backdoor.txt
diff --git a/docs/backdoor.txt b/docs/backdoor.txt
new file mode 100644
index 0000000..1c6502a
--- /dev/null
+++ b/docs/backdoor.txt
@@ -0,0 +1,167 @@
+= Backdoor communication channel =
+
+== Introduction ==
+
+This document describes how the guest can use the backdoor communication
channel
+to interact with user-provided code inside QEMU.
+
+The backdoor provides a lightweight and guest-initiated communication channel
+between code running inside the guest system and code in QEMU, including both
+QEMU in 'softmmu' and 'user' modes.
+
+The semantics of the backdoor channel are up to the user, who must provide the
+implementation of the QEMU-side callbacks used when the backdoor channel is
+invoked.
+
+On the guest side, code can be linked against a simple library provided in QEMU
+to interface with the backdoor channel.
+
+The features of this mechanism are:
+
+* Minimal setup for the guest.
+* Independent of guest architecture.
+* Works with 'softmmu' and 'user' mode.
+* Negligible guest overhead; guest invocations of the backdoor channel does not
+ go through any OS abstraction, except during the setup of the communication
+ channel.
+* Negligible host overhead; invocations of the backdoor channel are interpreted
+ by QEMU, while a side-channel can be used as regular memory to communicate
+ bulk data without any extra overhead.
+* The user-provided backdoor callbacks can perform arbitrary actions on the
+ guest system (e.g., read or write memory, change register values, etc.).
+
+
+== QEMU-side code ==
+
+1. Create the "Makefile" to build the user-provided backdoor channel library:
+
+ mkdir /tmp/my-backdoor-qemu
+ cat> /tmp/my-backdoor-qemu/Makefile<<EOF
+ include $(BUILD_DIR)/config-host.mak
+ include $(BUILD_DIR)/$(TARGET_DIR)../config-target.mak
+ include $(SRC_PATH)/rules.mak
+
+ vpath %.c /tmp/my-backdoor-qemu
+
+
+ libbackdoor.a: backdoor.o
+
+
+ # Include automatically generated dependency files
+ -include $(wildcard *.d)
+ EOF
+
+2. Implement the callbacks declared in "backdoor/qemu/qemu-backdoor.h":
+
+ cat> /tmp/my-backdoor-qemu/backdoor.c<<EOF