Add option to invoke callout prior to each instruction

custom_tests/data/ubpf_test_debug_function.input

@@ -0,0 +1 @@
+85 00 00 00 01 00 00 00 95 00 00 00 00 00 00 00

custom_tests/descrs/ubpf_test_debug_function.md

@@ -0,0 +1,3 @@
+## Test Description
+
+This test verifies that a debug call-out can be registered to inspect the state of the vm prior to each instruction.

custom_tests/srcs/ubpf_test_debug_function.cc

@@ -0,0 +1,107 @@
+// Copyright (c) Will Hawkins
+// SPDX-License-Identifier: Apache-2.0
+
+#include <cstdint>
+#include <iostream>
+#include <memory>
+#include <stdint.h>
+#include <vector>
+#include <string>
+
+extern "C"
+{
+#include "ubpf.h"
+}
+
+#include "ubpf_custom_test_support.h"
+
+typedef struct _vm_state {
+ int pc;
+ std::vector<uint64_t> registers;
+ std::vector<uint8_t> stack;
+} vm_state_t;
+
+void
+debug_callout(void* context, int program_counter, const uint64_t registers[16], const uint8_t* stack_start, size_t stack_length)
+{
+ std::vector<vm_state_t>* vm_states = static_cast<std::vector<vm_state_t>*>(context);
+ vm_state_t vm_state{};
+
+ vm_state.pc = program_counter;
+ for (int i = 0; i < 16; i++) {
+ vm_state.registers.push_back(registers[i]);
+ }
+ for (size_t i = 0; i < stack_length; i++) {
+ vm_state.stack.push_back(stack_start[i]);
+ }
+
+ vm_states->push_back(vm_state);
+}
+
+uint64_t test_function_1(uint64_t r1, uint64_t r2, uint64_t r3, uint64_t r4, uint64_t r5)
+{
+ return r1 + r2 + r3 + r4 + r5;
+}
+
+int
+main(int argc, char** argv)
+{
+ std::string program_string{};
+ std::string error{};
+ ubpf_jit_fn jit_fn;
+
+ std::vector<vm_state_t> vm_states;
+
+ if (!get_program_string(argc, argv, program_string, error)) {
+ std::cerr << error << std::endl;
+ return 1;
+ }
+
+ uint64_t memory{0x123456789};
+
+ std::unique_ptr<ubpf_vm, decltype(&ubpf_destroy)> vm(ubpf_create(), ubpf_destroy);
+ if (!ubpf_setup_custom_test(
+ vm,
+ program_string,
+ [](ubpf_vm_up& vm, std::string& error) {
+ int retval = ubpf_register(vm.get(), 1, "test_function_1", test_function_1);
+ if (retval < 0) {
+ error = "Problem registering test function retval=" + std::to_string(retval);
+ return false;
+ }
+ return true;
+ },
+ jit_fn,
+ error)) {
+ std::cerr << "Problem setting up custom test: " << error << std::endl;
+ return 1;
+ }
+
+ if (ubpf_register_debug_fn(vm.get(), &vm_states, debug_callout) < 0) {
+ std::cerr << "Problem registering debug function" << std::endl;
+ return 1;
+ }
+
+ uint64_t bpf_return_value;
+ if (ubpf_exec(vm.get(), &memory, sizeof(memory), &bpf_return_value)) {
+ std::cerr << "Problem executing program" << std::endl;
+ return 1;
+ }
+
+ if (vm_states.empty()) {
+ std::cerr << "No debug callouts were made" << std::endl;
+ return 1;
+ }
+
+ for (auto& vm_state : vm_states) {
+ std::cout << "Program Counter: " << vm_state.pc << std::endl;
+ for (int i = 0; i < 16; i++) {
+ std::cout << "Register " << i << ": " << vm_state.registers[i] << std::endl;
+ }
+ std::cout << "Stack: ";
+ for (auto& stack_byte : vm_state.stack) {
+ std::cout << std::hex << static_cast<int>(stack_byte) << " ";
+ }
+ std::cout << std::endl;
+ }
+}

vm/inc/ubpf.h

@@ -562,6 +562,34 @@ extern "C"
  */
  bool
  ubpf_toggle_undefined_behavior_check(struct ubpf_vm* vm, bool enable);
+
+ /**
+ * @brief A function to invoke before each instruction.
+ *
+ * @param[in, out] context Context passed in to ubpf_register_debug_fn.
+ * @param[in] program_counter Current instruction pointer.
+ * @param[in] registers Array of 11 registers representing the VM state.
+ * @param[in] stack_start Pointer to the beginning of the stack.
+ * @param[in] stack_length Size of the stack in bytes.
+ */
+ typedef void (*ubpf_debug_fn)(
+ void* context,
+ int program_counter,
+ const uint64_t registers[16],
+ const uint8_t* stack_start,
+ size_t stack_length);
+
+ /**
+ * @brief Add option to invoke a debug function before each instruction.
+ * Note: This only applies to the interpreter and not the JIT.
+ *
+ * @param[in] vm VM to add the option to.
+ * @param[in] debug_fn Function to invoke before each instruction. Pass NULL to remove the function.
+ * @return 0 on success.
+ * @return -1 on failure.
+ */
+ int
+ ubpf_register_debug_fn(struct ubpf_vm* vm, void* context, ubpf_debug_fn debug_function);
 #ifdef __cplusplus
 }
 #endif

vm/ubpf_int.h

@@ -99,6 +99,8 @@ struct ubpf_vm
  ubpf_bounds_check bounds_check_function;
  void* bounds_check_user_data;
  int instruction_limit;
+ void* debug_function_context; ///< Context pointer that is passed to the debug function.
+ ubpf_debug_fn debug_function; ///< Debug function that is called before each instruction.
 #ifdef DEBUG
  uint64_t* regs;
 #endif

vm/ubpf_vm.c

@@ -677,6 +677,11 @@ ubpf_exec_ex(
 
  struct ebpf_inst inst = ubpf_fetch_instruction(vm, pc++);
 
+ // Invoke the debug function to allow the user to inspect the state of the VM if it is enabled.
+ if (vm->debug_function) {
+ vm->debug_function(vm->debug_function_context, cur_pc, reg, stack_start, stack_length);
+ }
+
  if (!ubpf_validate_shadow_register(vm, &shadow_registers, inst)) {
  return_value = -1;
  goto cleanup;
@@ -1893,3 +1898,15 @@ ubpf_register_stack_usage_calculator(struct ubpf_vm* vm, stack_usage_calculator_
  vm->stack_usage_calculator = calculator;
  return 0;
 }
+int
+ubpf_register_debug_fn(struct ubpf_vm* vm, void* context, ubpf_debug_fn debug_function)
+{
+ if ((vm->debug_function != NULL && debug_function != NULL) ||
+ (vm->debug_function == NULL && debug_function == NULL)) {
+ return -1;
+ }
+
+ vm->debug_function = debug_function;
+ vm->debug_function_context = context;
+ return 0;
+}