Add C API VM function call example

Author: fwsGonzo

docs/emulator/vmcalls.md

@@ -271,3 +271,61 @@ inline std::optional<Script::sgaddr_t> Script::call(gaddr_t address, Args&&... a
 }
 ```
 From `script.call(...)` as implemented in the [gamedev example](https://github.com/libriscv/libriscv/blob/master/examples/gamedev/script.hpp). `ScriptDepthMeter` measures the current call depth in order to avoid too many recursive calls back into the script, while also using the faster `vmcall()` on the first call.
+
+## VM Calls with the C API
+
+In the C API each argument register has to be populated manually, and the return value(s) have to be read as well.
+
+A general rule for passing data to a function is that:
+1. Each integer goes into the next free integer register
+2. Each pointer goes into the next free integer register
+3. Each float goes into the next free float register of that type
+
+### Example
+
+Function:
+```c
+long my_function(const char* arg1, const bool arg2, const struct my_struct* arg3, size_t arg4, float arg5);
+```
+
+Input values:
+```c
+const char* mystring = "";
+const bool  mybool = true;
+const struct mystruct s;
+const size_t mysize = 4;
+const float  myfloat = 5.0f;
+```
+
+C++ API:
+```cpp
+long result =
+  machine.vmcall(mystring, mybool, mystruct, mysize, myfloat);
+```
+
+C API:
+```c
+/* We start by setting up the call, providing the address of the function */
+libriscv_setup_vmcall(machine, guest_function_address);
+
+/**
+ * We push structs on the stack, and get a guest pointer in return.
+ * Guest pointers go into integer registers along with other integers
+**/
+LIBRISCV_ARG_REGISTER(regs, 0) = libriscv_stack_push(machine, regs, ...);
+LIBRISCV_ARG_REGISTER(regs, 1) = true;
+LIBRISCV_ARG_REGISTER(regs, 2) = libriscv_stack_push(machine, regs, ...);
+LIBRISCV_ARG_REGISTER(regs, 3) = 4;
+/* Floating point values go into their own registers */
+LIBRISCV_FP32_ARG_REG(regs, 0) = 5.0f;
+
+/* Running the VM will now execute the function with the above arguments as input */
+if (libriscv_run(machine, ~0)) {
+	fprintf(stderr, "Ooops! Function call failed!\n");
+	exit(1);
+}
+
+/* Integer return values are in A0. */
+long result = LIBRISCV_ARG_REGISTER(regs, 0);
+printf("The function returned: %ld\n", result);
+```