History

Alan Stokes a0e4296f04 Require unsafe blocks in unsafe functions Some hopefully harmless refactoring. Only minor behavioral changes are introduced. Turn on the unsafe_op_in_unsafe_fn lint, treated as an error, for all our low-level code, to ensure that unsafe code is properly highlighted & commented even inside unsafe functions. I've moved the setting from the code to the blueprint in order to make it the default for new code, and reduce clutter. Add unsafe blocks as required to fix all the errors that this surfaced, with appropriate safety comments. I've tried to keep them as small as possible. Slightly to my surprise I removed the unsafe marker from malloc_ (and renamed it in passing); I believe it has no preconditions and is always safe - although doing anything with the returned memory wouldn't be. Bug: 275693559 Test: flash pvmfw, atest MicrodroidTests Change-Id: Ia6f39102caea05c6517bc7500914b7fe7025286c		2023-04-21 12:00:55 +01: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	Require unsafe blocks in unsafe functions	2023-04-21 12:00:55 +01:00
stub	Check in stub.c	2022-12-07 11:49:59 +00:00
Android.bp	Require unsafe blocks in unsafe functions	2023-04-21 12:00:55 +01: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++.