runtime/README.md

# Reborn Runtime
This is a simple program allowing ARM32 code to easily call "native" code.

By running an ARM32 program inside this runtime, it gains the ability to call `raw_trampoline`. This function copies its arguments and passes them to the `trampoline` function inside `libmedia-layer-trampoline.so`.

The runtime also automatically uses QEMU on x86_64 systems.

## Terminology
- "Guest" code is the main ARM32 program.
- "Host" code is the native code located in `libmedia-layer-trampoline.so`.

## Example
There is a simple C example [here](./example). It sends a given string to the host, which returns the string's length multiplied by two.

## Early Returning
`raw_trampoline` supports returning before the host code has finished executing. This can be enabled by passing `true` to `allow_early_return`. However, this is only supported in certain circumstances, can cause race-conditions, and prevents the guest code from receiving the host's return value.

## Syscall Versus Pipe Trampolines
The runtime supports two methods of passing data between the guest and host.
- System Call
  - Data is passed through a custom system-call added to QEMU.
  - Only supported on x86_64.
- Pipes
  - Data is passed through standard UNIX pipes.
  - Supports early-returning.
  - Can be forced using an environmental variable.

## Licensing
The runtime itself is licensed with [GPLv2](./LICENSE) to comply with QEMU's license. However, the `raw_trampoline` function and associated headers are licensed with the [Unlicense](lib/LICENSE) as they do not directly link to the runtime.