Dynamic calls allow you to expose host-side C++ functions to the RISC-V guest script using string names. This method is safer and easier to use than raw system calls.

Workflow

1. Define the call in C++: Use Script::set_dynamic_call to map a signature to a lambda or function. The signature should include the full type information to minimize ABI mistakes.
2. Register in JSON: Add the mapping to programs/dynamic_calls.json to link a short name to the full C++ signature.
3. Call from Script: The build system generates a wrapper, allowing you to call the function directly in your RISC-V code (e.g., sys_lazy();).

Supported Argument Patterns

• Simple types: int, void, etc.
• Results: Use script.machine().set_result(value) to return values to the script.
• Structs: Pass structs by reference/pointer using script.args<T>().
• Buffers: Use riscv::Buffer to handle char* buffer, size_t length pairs, or std::string_view for a view of the memory.

// 1. Define in C++
Script::set_dynamic_call("object_id",
    [] (Script& script) {
        const auto [id] = script.args <int> ();
        script.machine().set_result(1234);
    });

// 2. Register in dynamic_calls.json
// "object_id": "int object_id(int)"

// 3. Call in RISC-V script
int id = object_id(some_arg);

RVScript requires a RISC-V compiler to build script programs. You have two main options:

Option 1: System Package (Simplest)

Install the GNU RISC-V toolchain via your package manager. The build script supports GNU toolchain versions 10 and later.

sudo apt install g++-12-riscv64-linux-gnu

Note: If using glibc from a system toolchain, be cautious when mixing microthreads with C++ exceptions.

Option 2: Newlib RISC-V Toolchain (Recommended for Performance)

For more performant and nimble executables, use the riscvXX-unknown-elf toolchain.

1. Clone and build the toolchain:

   git clone https://github.com/riscv/riscv-gnu-toolchain.git
   cd riscv-gnu-toolchain
   git submodule update --depth 1 --init

Install your system's GCC dependencies here

./configure --prefix=$HOME/riscv --with-arch=rv64g_zba_zbb_zbc_zbs --with-abi=lp64d make -j8

2. Add the toolchain to your `PATH` in `~/.bashrc`:
 ```bash
 export PATH=$PATH:$HOME/riscv/bin

3. Restart your terminal. The build script will automatically prefer this compiler if it is found in your PATH.

# Example: Installing the newlib toolchain
git clone https://github.com/riscv/riscv-gnu-toolchain.git
cd riscv-gnu-toolchain
git submodule update --depth 1 --init
./configure --prefix=$HOME/riscv --with-arch=rv64g_zba_zbb_zbc_zbs --with-abi=lp64d
make -j8

Common issues when working with micro binaries:

• Remote Execution: When executing a function on a remote machine, ensure the function you are calling exists on the target machine, not the machine initiating the call.
• Register Clobbering with vmcall(): If you call vmcall() on a machine that is currently performing an operation, its registers may be clobbered. This causes the machine to resume at the end of the vmcall rather than where it left off. To avoid this, use preempt() when calling into a machine performing long-term operations.
• Blocking the Main Thread: You cannot block the main thread because it is subject to being clobbered by other functions calling into the machine. The design only allows blocking other threads.
• C++ Exceptions: Standard C++ exceptions are not supported because the full C++ standard library is not linked (to maintain efficiency). For high-performance C++ containers, it is recommended to use EASTL (a fork is available that supports RISC-V).

The following patterns demonstrate how to use Script::set_dynamic_call for different data types and requirements.

// Simple void function
Script::set_dynamic_call("void sys_lazy ()", [] (auto&) {
    strf::to(stdout)("I'm not doing much, tbh.\n");
});

// Function with integer argument and return value
Script::set_dynamic_call("object_id",
    [] (Script& script) {
        const auto [id] = script.args <int> ();
        script.machine().set_result(1234);
    });

// Function with struct by reference
Script::set_dynamic_call("struct_by_ref",
    [] (Script& script) {
        struct Something { int a, b, c, d; };
        const auto [s] = script.args <Something> ();
    });

// Function with buffer/string view (consumes two registers: A0=ptr, A1=len)
Script::set_dynamic_call("void sys_big_data (const char*, size_t)",
    [] (Script& script) {
        const auto [buffer] = script.args <riscv::Buffer> ();
        // OR
        const auto [view] = script.args <std::string_view> ();
    });

The Timers class provides an interface for scheduling one-shot and periodic tasks. Timers are identified by an integer ID returned upon creation. You must call handle_events() periodically to process and execute the scheduled callbacks.

Key operations:

• oneshot(when, handler): Schedules a single execution at a specific time.
• periodic(when, period, handler): Schedules a task to run at when, and then repeatedly every period.
• stop(id): Cancels a scheduled timer.
• set_repeats(id, repeats): Updates how many times a periodic timer should repeat.
• active(): Returns the number of currently active timers.
• next(): Returns the time remaining until the next timer event.

// Example usage of the Timers API
Timers timer_manager;

// Schedule a one-shot event in 5.0 units of time
timer_manager.oneshot(5.0, [](int id) {
    // Handle event
});

// Schedule a periodic event starting at 1.0, repeating every 0.5
timer_manager.periodic(1.0, 0.5, [](int id) {
    // Handle periodic event
});

// Main loop to process timer events
while (true) {
    timer_manager.handle_events();
}