History

Alan Stokes 1702ac6ca0 Documentation fixes Replace relative paths with full AOSP https paths, so they work in contexts without the full Virtualization repo. Mention the linker script, which may be needed to generate the stub library. Bug: 259237660 Test: n/a Change-Id: Ifce9b91955c97a19c0227d8535d5313eb34c5714		2023-01-16 12:17:19 +00:00
..
include	Rewrite the getVmInstanceSecret comment	2023-01-04 15:42:43 +00:00
include-restricted	Native API fixes	2022-12-16 16:53:45 +00:00
src	rpc_binder: Update users of RpcSession	2022-12-19 09:30:02 +00:00
stub	Check in stub.c	2022-12-07 11:49:59 +00:00
Android.bp	libvm_payload as a cc_library	2022-11-28 11:15:29 +00:00
README.md	Documentation fixes	2023-01-16 12:17:19 +00:00
libvm_payload.map.txt	libvm_payload as a cc_library	2022-11-28 11:15:29 +00:00

README.md

VM Payload API

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 android.system.virtualmachine.VirtualMachineManager.

Entry point

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".)

API header

The functions available to the payload once it starts are declared in vm_payload.h.

Linking

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.

Available NDK APIs

In addition to the VM Payload APIs, a small subset of the Android NDK can be used by the payload.

This subset consists of:

The standard C library.
The Logging APIs.
The NdkBinder API. However note that the payload can only host a binder server via 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++

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++.