1# VM Payload API
2
3This directory contains the definition of the VM Payload API. This is a native
4API, exposed as a set of C functions, available to payload code running inside a
5[Microdroid](https://android.googlesource.com/platform/packages/modules/Virtualization/+/refs/heads/main/build/microdroid/README.md)
6VM.
7
8Note that only native code is supported in Microdroid, so no Java APIs are
9available in the VM, and only 64 bit code is supported.
10
11To create a VM and run the payload from Android see the [AVF Java
12APIs](../framework-virtualization/README.md).
13
14## Entry point
15
16The payload should be packaged as one (or more) .so files inside the app's APK -
17under the `lib/<ABI>` directory, like other JNI code.
18
19The primary .so, which is specified as part of the VM configuration via
20[VirtualMachineConfig.Builder#setPayloadBinaryPath](https://android.googlesource.com/platform/packages/modules/Virtualization/+/refs/heads/main/libs/framework-virtualization/src/android/system/virtualmachine/VirtualMachineConfig.java),
21must define the entry point for the payload.
22
23This entry point is a C function called `AVmPayload_main()`, as declared in
24[vm_main.h](include/vm_main.h). (In C++ this must be defined as `extern "C"`.)
25
26## API header
27
28The functions available to the payload once it starts are declared in
29[vm_payload.h](include/vm_payload.h).
30
31### Linking
32
33In the Android build system, the payload binary should be built with
34`libvm_payload#current` specified as one of the `shared_libs`; this links
35against a stub `libvm_payload.so`, where the dependencies will be satisfied at
36runtime from the real `libvm_payload.so` hosted within the Microdroid VM.
37
38See `MicrodroidTestNativeLib` in the [test
39APK](https://android.googlesource.com/platform/packages/modules/Virtualization/+/refs/heads/main/tests/testapk/Android.bp)
40for an example.
41
42In other build systems a similar stub `libvm_payload.so` can be built using
43[stub.c](stub/stub.c) and the [linker script](libvm_payload.map.txt).
44
45## Available NDK APIs
46
47In addition to the VM Payload APIs, a small subset of the [Android
48NDK](https://developer.android.com/ndk) can be used by the payload.
49
50This subset consists of:
51- The [standard C library](https://developer.android.com/ndk/guides/stable_apis#c_library).
52- The [Logging APIs](https://developer.android.com/ndk/guides/stable_apis#logging).
53- The [NdkBinder
54  API](https://developer.android.com/ndk/reference/group/ndk-binder). However
55  note that the payload can only host a binder server via
56  `AVmPayload_runVsockRpcServer`, defined in
57  [vm_payload.h](include/vm_payload.h), rather than
58  `AServiceManager_addService`, and cannot connect to any binder server. Passing
59  file descriptors to and from the VM is not supported.
60
61## C++
62
63C++ can be used, but you will need to include the C++ runtime in your APK along
64with your payload, either statically linked (if
65[appropriate](https://developer.android.com/ndk/guides/cpp-support#sr)) or as a
66separate .so.
67
68The same is true for other languages such as Rust.
69
70See [AIDL
71backends](https://source.android.com/docs/core/architecture/aidl/aidl-backends)
72for information on using AIDL with the NDK Binder from C++.
73
74## Rust
75
76A Rust wrapper library for the VM Payload API is available (as an rlib) for VM
77payloads written in Rust.
78
79This wrapper is not guaranteed to be stable; we may change it in future
80versions. But payload code built using it will depend only on the C VM Payload
81API and the NDK APIs that are available to the payload, so should run unchanged
82on future versions.
83
84See [wrapper/lib.rs](wrapper/lib.rs) and `libvm_payload_rs` in
85[Android.bp](Android.bp).
86