Merge memory checking from sandbox

Change-id: Ibce845d0

2 files changed, 80 insertions, 0 deletions

diff --git a/docs/ANDROID-ELFF.TXT b/docs/ANDROID-ELFF.TXT
new file mode 100644
index 0000000..afb3015
--- /dev/null
+++ b/docs/ANDROID-ELFF.TXT
@@ -0,0 +1,23 @@
+ANDROID ELFF LIBRARY
+
+The docs/ANDROID-ELFF.TXT document contains notes about the ELFF library used
+by the emulator to extract debugging information from symbol files of the
+emulated system.
+
+The ELFF library has been introduced to provide the emulator's memory checker
+subsystem with information about routine name, source file name and location
+when a memory access violation detected at runtime. This requires parsing symbol
+files corresponding to the libraries of the emulated system, in order to extract
+relevant information from them.
+
+Due to lack of windows support on available open source projects, this is a
+full new implementation of an ELF/DWARF parser.
+
+The library exposes a simple API that at this point allows:
+- Extract information about routine, containing given PC address in the emulated
+  system. Routine information, collected by the library includes:
+  * Routine name
+  * Source file name and line corresponded to the given emulated PC.
+  * If routine happens to be inlined, library traces inclusion up to the first
+    routine that is not inlined, providing names and source file location
+    information for all inlined routines in that chain.
diff --git a/docs/ANDROID-MEMCHECK.TXT b/docs/ANDROID-MEMCHECK.TXT
new file mode 100644
index 0000000..0c5e716
--- /dev/null
+++ b/docs/ANDROID-MEMCHECK.TXT
@@ -0,0 +1,57 @@
+ANDROID MEMORY CHECKER COMPONENT
+
+The docs/ANDROID-MEMCHECK.TXT document contains description of a memory checker
+implemented in the emulator
+
+The memory checker is intended to catch simple memory access violations in the
+emulated system, including:
+- Memory leaks
+- Attempts to free / reallocate invalid pointers (including pointers that have
+  already been freed, or reallocated).
+- Attempts to read from / write to areas outside of allocated blocks.
+
+To provide this functionality, the memory checker works in conjunction with
+an instrumented version of libc.so library used by the emulated system. Both,
+emulator's memory checking, and libc's instrumentation are turned on by the
+-memcheck command-line option. If this argument is omitted, libc.so will run in
+the regular, not instrumented mode, and the emulator will not perform any
+actions related to the memory checking.
+
+The way emulator and instrumented libc.so work together is as such:
+libc.so hooks up every memory allocation call (malloc, free, calloc, realloc,
+and memalign). For each such call, libc sends a notification message to the
+emulator, providing an allocation descriptor that contains information about
+allocation block and operation that is being performed on this block. Emulator
+and libc use a "magic page" that is set up in such a way that every write to
+that page on the emulated system produces some sort of event in the emulator,
+allowing emulator to receive data that emulated system has written to the "magic
+page". For more info on that, see hw/goldfish-trace.c
+
+In response to events, received from libc.so, emulator keep tracks of all blocks
+that have been allocated from the heap on emulated system. Block descriptors are
+kept in a per-process basis, so when a process exits, emulator can list all the
+leaked blocks the process left behind.
+
+When a free, or realloc operation is performed on the emulated system, emulator
+can verify that the pointer passed to free/realloc matches the address of a
+block recorded in the current process' descriptors table. This way emulator can
+detect and report attempts to free/reallocate invalid pointers.
+
+To detect read/write violations, emulator uses prefix and suffix guarding areas
+that were added to the allocated blocks by the instrumented libc. To watch for
+access violations, emulator instruments ld_/st_mmu routines to verify that
+accessed memory doesn't belong to a guarding area of a block allocated in
+context of the current process.
+
+There are some tricky things like:
+- invalidating every page containing allocated blocks every time anything has
+  been read, or written to that page, so we can be sure that we don't miss AV
+  on condition that page has been cached and ld_/st_mmu is omitted when
+  accessing memory in that page.
+- Keeping track of each thread calling stack, so when access violation is
+  reported, we can pinpoint violation to precise location in the source code.
+- etc.
+
+All the code related to memory checking is guarded in emulator's code by
+CONFIG_MEMCHECK macro, making it easy to spot changes related to it in the
+sources.