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/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](../java/framework/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/java/framework/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