@samitouri / QOSamiQemu / commits / 533c98e769

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>

Ziyang Zhang committed Jul 19, 2026 at 15:47 UTC 533c98e769c79bcef56c6e466c4f3cb4c195181e

1 file changed +21 -10

docs/about/emulation.rst

+21 -10

@@ -1072,14 +1072,13 @@ syscall, so the real kernel never sees it.

1072 Trusted guests only. The guest can load arbitrary host libraries and run

1073 arbitrary code in the QEMU host process. The plugin is not a sandbox and

1074 provides no isolation. It also requires ``guest_base == 0`` (qemu-user's

1075 - default), as guest pointers are dereferenced as host addresses with no

1076 - translation.

1075 + default) and a guest whose pointer width and endianness match the host's, as

1076 + guest pointers are dereferenced as host addresses with no translation.

1077

1078 The plugin intentionally keeps the QEMU side lightweight and knows nothing

1079 -about any particular library or its calling convention. Turning a real library

1080 -into working thunks, including argument marshalling, callbacks and variadic

1081 -functions, is done entirely in userspace, and any toolchain can implement the

1082 -interface.

1079 +about any particular library or its calling convention. Producing the thunks

1080 +for a real library is done entirely in userspace, and any toolchain can

1081 +implement the interface.

1082

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

1084

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

1086

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

1088

1089 +If the default number does not suit the guest ABI, pick another one, and build

1090 +the userspace side to issue the same one:

1091 +

1092 +.. code-block:: shell

1093 +

1094 + qemu-x86_64 -plugin contrib/plugins/libdlcall.so,syscall_num=8192 \

1095 + <guest-program> ...

1096 +

1097 `Lorelei <https://github.com/rover2024/lorelei>`_ is one end-to-end userspace

1098 implementation of this: it provides the guest and host runtimes and an

1099 automated toolchain that generates the thunks from a library's headers, so guest

1093 -library calls run on the host's native libraries. It supports an x86_64 guest

1094 -running on an x86_64, aarch64 or riscv64 host.

1100 +library calls run on the host's native libraries. How it handles the parts the

1101 +plugin leaves out, including argument marshalling, callbacks and variadic

1102 +functions, can serve as a reference. It supports an x86_64 guest running on an

1103 +x86_64, aarch64 or riscv64 host.

1104

1105 A minimal end-to-end example uses a one-function library, ``libhello.so``, built

1106 two ways: the guest build tags its output ``(from the guest)`` and the host

@@ -1201,8 +1210,10 @@ which prints::

1210 * - Option

1211 - Description

1212 * - syscall_num=N

1204 - - The magic syscall number the guest issues (default 4096). Must be high

1205 - enough not to clash with a real syscall.

1213 + - The magic syscall number the guest issues (default 4096). It must be a

1214 + number the guest ABI does not use for a real syscall, and does not

1215 + reject before the plugin sees it, which bounds the choice from both

1216 + sides.

1217

1218 Other emulation features

1219 ------------------------