This directory contains the definition of the VM Payload API. This is a native API, exposed as a set of C functions, available to payload code running inside a Microdroid VM.
Note that only native code is supported in Microdroid, so no Java APIs are available in the VM, and only 64 bit code is supported.
To create a VM and run the payload from Android see the AVF Java APIs.
The payload should be packaged as one (or more) .so files inside the app's APK - under the lib/<ABI> directory, like other JNI code.
The primary .so, which is specified as part of the VM configuration via VirtualMachineConfig.Builder#setPayloadBinaryPath, must define the entry point for the payload.
This entry point is a C function called AVmPayload_main(), as declared in vm_main.h. (In C++ this must be defined as extern "C".)
The functions available to the payload once it starts are declared in vm_payload.h.
In the Android build system, the payload binary should be built with libvm_payload#current specified as one of the shared_libs; this links against a stub libvm_payload.so, where the dependencies will be satisfied at runtime from the real libvm_payload.so hosted within the Microdroid VM.
See MicrodroidTestNativeLib in the test APK for an example.
In other build systems a similar stub libvm_payload.so can be built using stub.c and the linker script.
In addition to the VM Payload APIs, a small subset of the Android NDK can be used by the payload.
This subset consists of:
AVmPayload_runVsockRpcServer, defined in vm_payload.h, rather than AServiceManager_addService, and cannot connect to any binder server. Passing file descriptors to and from the VM is not supported.C++ can be used, but you will need to include the C++ runtime in your APK along with your payload, either statically linked (if appropriate) or as a separate .so.
The same is true for other languages such as Rust.
See AIDL backends for information on using AIDL with the NDK Binder from C++.
A Rust wrapper library for the VM Payload API is available (as an rlib) for VM payloads written in Rust.
This wrapper is not guaranteed to be stable; we may change it in future versions. But payload code built using it will depend only on the C VM Payload API and the NDK APIs that are available to the payload, so should run unchanged on future versions.
See wrapper/lib.rs and libvm_payload_rs in Android.bp.