Commit 533c98e769 for qemu.org

commit 533c98e769c79bcef56c6e466c4f3cb4c195181e
Author: Ziyang Zhang <functioner@sjtu.edu.cn>
Date:   Sun Jul 19 15:47:30 2026 +0800

    docs/about/emulation: sharpen the dlcall boundary and its guest requirements

    Record the same data model requirement as the plugin: guest_base == 0 is
    necessary but not sufficient.

    Describe the magic syscall number the way the plugin now does. It has to be a
    number the guest ABI does not use and does not reject before the plugin sees
    it, rather than merely a high one, so show syscall_num= being used as well.

    A library is not turned into thunks, it is left alone and the thunks are
    produced for it, so say that instead. Argument marshalling, callbacks and
    variadic functions are also what the plugin does not do, and listing them in
    its description blurs the boundary it draws. Move them to Lorelei, where they
    are pointed at as a reference.

    Co-authored-by: Kailiang Xu <xukl2019@sjtu.edu.cn>
    Co-authored-by: Mingyuan Xia <xiamy@ultrarisc.com>
    Signed-off-by: Ziyang Zhang <functioner@sjtu.edu.cn>
    Reviewed-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
    Link: https://lore.kernel.org/qemu-devel/20260719074730.1520517-4-functioner@sjtu.edu.cn
    Signed-off-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>

diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst
index b861501e85..c58149086c 100644
--- a/docs/about/emulation.rst
+++ b/docs/about/emulation.rst
@@ -1072,14 +1072,13 @@ syscall, so the real kernel never sees it.
    Trusted guests only. The guest can load arbitrary host libraries and run
    arbitrary code in the QEMU host process. The plugin is not a sandbox and
    provides no isolation. It also requires ``guest_base == 0`` (qemu-user's
-   default), as guest pointers are dereferenced as host addresses with no
-   translation.
+   default) and a guest whose pointer width and endianness match the host's, as
+   guest pointers are dereferenced as host addresses with no translation.

 The plugin intentionally keeps the QEMU side lightweight and knows nothing
-about any particular library or its calling convention. Turning a real library
-into working thunks, including argument marshalling, callbacks and variadic
-functions, is done entirely in userspace, and any toolchain can implement the
-interface.
+about any particular library or its calling convention. Producing the thunks
+for a real library is done entirely in userspace, and any toolchain can
+implement the interface.

 Loading the plugin is all that is required from QEMU's side:

@@ -1087,11 +1086,21 @@ Loading the plugin is all that is required from QEMU's side:

    qemu-x86_64 -plugin contrib/plugins/libdlcall.so <guest-program> ...

+If the default number does not suit the guest ABI, pick another one, and build
+the userspace side to issue the same one:
+
+.. code-block:: shell
+
+   qemu-x86_64 -plugin contrib/plugins/libdlcall.so,syscall_num=8192 \
+       <guest-program> ...
+
 `Lorelei <https://github.com/rover2024/lorelei>`_ is one end-to-end userspace
 implementation of this: it provides the guest and host runtimes and an
 automated toolchain that generates the thunks from a library's headers, so guest
-library calls run on the host's native libraries. It supports an x86_64 guest
-running on an x86_64, aarch64 or riscv64 host.
+library calls run on the host's native libraries. How it handles the parts the
+plugin leaves out, including argument marshalling, callbacks and variadic
+functions, can serve as a reference. It supports an x86_64 guest running on an
+x86_64, aarch64 or riscv64 host.

 A minimal end-to-end example uses a one-function library, ``libhello.so``, built
 two ways: the guest build tags its output ``(from the guest)`` and the host
@@ -1201,8 +1210,10 @@ which prints::
   * - Option
     - Description
   * - syscall_num=N
-    - The magic syscall number the guest issues (default 4096). Must be high
-      enough not to clash with a real syscall.
+    - The magic syscall number the guest issues (default 4096). It must be a
+      number the guest ABI does not use for a real syscall, and does not
+      reject before the plugin sees it, which bounds the choice from both
+      sides.

 Other emulation features
 ------------------------