[RFC v6 9/9] docs/user: Add doc for native library calls

[Yeqi Fu]

Signed-off-by: Yeqi Fu <fufuyqqqqqq@gmail.com>
---
 docs/user/index.rst        |  1 +
 docs/user/native_calls.rst | 91 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 docs/user/native_calls.rst

diff --git a/docs/user/index.rst b/docs/user/index.rst
index 782d27cda2..d3fc9b7af1 100644
--- a/docs/user/index.rst
+++ b/docs/user/index.rst
@@ -12,3 +12,4 @@ processes compiled for one CPU on another CPU.
    :maxdepth: 2
 
    main
+   native_calls
diff --git a/docs/user/native_calls.rst b/docs/user/native_calls.rst
new file mode 100644
index 0000000000..0f8c2273a3
--- /dev/null
+++ b/docs/user/native_calls.rst
@@ -0,0 +1,91 @@
+Native Library Calls Optimization
+=================================
+
+Description
+-----------
+
+Executing a program under QEMU's user mode subjects the entire
+program, including all library calls, to translation. It's important
+to understand that many of these library functions are optimized
+specifically for the guest architecture. Therefore, their
+translation might not yield the most efficient execution.
+
+When the semantics of a library function are well defined, we can
+capitalize on this by substituting the translated version with a call
+to the native equivalent function.
+
+To achieve tangible results, focus should be given to functions such
+as memory-related ('mem*') and string-related ('str*') functions.
+These subsets of functions often have the most significant effect
+on overall performance, making them optimal candidates for
+optimization.
+
+Implementation
+--------------
+
+By writing the name of a specific library into the /etc/ld.so.preload
+file, the dynamic linker will prioritize loading this library before
+any others. If this library contains functions that share names with
+functions in other libraries, the ones in the specified library will
+take precedence.
+
+In order to bypass certain native libraries, we have developed a
+shared library and re-implemented the native functions within it
+as a special instruction sequence. By making dynamic modifications
+to the /etc/ld.so.preload file, the shared library is loaded into
+the user program. Consequently, when the user program calls a native
+function, it executes the corresponding special instruction sequence.
+During execution, the QEMU translator identifies these special
+instructions and executes the corresponding native functions
+accordingly.
+
+These special instructions are implemented using
+architecture-specific unused or invalid opcodes, ensuring that they
+do not conflict with existing instructions.
+
+
+i386 and x86_64
+---------------
+An unused instruction is utilized to mark a native call.
+
+arm and aarch64
+---------------
+HLT is an invalid instruction for userspace programs, and is used to
+mark a native call.
+
+mips and mips64
+---------------
+The syscall instruction contains 20 unused bits, which are typically
+set to 0. These bits can be used to store non-zero data,
+distinguishing them from a regular syscall instruction.
+
+Usage
+-----
+
+1. Install cross-compilation tools
+
+Cross-compilation tools are required to build the shared libraries
+that can hook the necessary library functions. For example, a viable
+command on Ubuntu is:
+
+::
+
+    apt install gcc-arm-linux-gnueabihf gcc-aarch64-linux-gnu \
+    gcc-mips-linux-gnu gcc-mips64-linux-gnuabi64
+
+
+2. Locate the compiled libnative.so
+
+After compilation, the libnative.so file can be found in the
+``./build/common-user/native/<target>-linux-user`` directory.
+
+3. Run the program with the ``--native-bypass`` option
+
+To run your program with native library bypass, use the
+``--native-bypass`` option to import libnative.so:
+
+::
+
+    qemu-<target> --native-bypass \
+    ./build/common-user/native/<target>-linux-user/libnative.so ./program
+
-- 
2.34.1