Integrating custom SystemC peripheral with QEMU instance using qbox.

[TunaHalpert]

Summary

I'm new to using Qbox and SystemC together and would like to get started by integrating a very simple custom SystemC module (like a memory block) into a QEMU-based virtual platform.

My goal is to eventually:

• Create a small virtual platform where QEMU simulates a CPU running Linux.
• Add a custom SystemC component (e.g., a memory model or peripheral).
• Observe and control interactions between QEMU and SystemC.

Right now, I'm looking for step-by-step guidance or a minimal working example.

---

What I'm Trying to Do

I want to:

• Understand how QEMU (inside Qbox) can interact with a SystemC TLM model.
• Learn how to set up a SystemC module (e.g., a memory block) that can be accessed from QEMU as a memory-mapped device.

But I’m not sure:

• How to begin writing the SystemC platform code that integrates with Qbox.
• How memory maps and device access work between QEMU and SystemC in Qbox.
• Whether I need to register anything explicitly with QEMU for access to happen.

---

What I Need Help With

1. A simple example or tutorial that shows how to connect a custom SystemC module into a Qbox simulation.
2. A brief explanation of how memory transactions flow from QEMU to SystemC — what makes QEMU access a SystemC model?
3. A minimal project structure to start from — which files I need to create and how to link them into the Qbox build system.

---

Thanks so much for your time!

[tmarcero]

Hi !

A simple example or tutorial that shows how to connect a custom SystemC module into a Qbox simulation.

You can find a quick tutorial on how to implement a simple memory here: https://www.doulos.com/knowhow/systemc/tlm-20/tutorial-1-sockets-generic-payload-blocking-transport/

You will learn all the things about "TLM sockets", this is thanks to these "sockets" that the SystemC models and QEMU models communicates.

(You should have a look into the tutorials here: https://www.doulos.com/knowhow/systemc/tlm-20/)

A minimal project structure to start from — which files I need to create and how to link them into the Qbox build system.

So you can start to create a simple main.cc like this one:
https://github.com/quic/qbox/blob/main/platforms/src/main.cc

You will need to have a configuration Lua file like this one:
https://github.com/quic/qbox/blob/main/platforms/ubuntu/conf_aarch64.lua

You can just keep to make it simple, the RAM, the Qemu Instances, the Router, the GIC and the CPU, you can add also your SystemC model.
You can find some models in Qbox/systemc-components for SystemC models or in Qbox/qemu-components for QEMU models.

And then to link your files with the Qbox build system you can do something like that:

cmake_minimum_required(VERSION 3.0)

project(FirstSystemCProject)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")

include(FetchContent)
include(CTest)

# download CPM.cmake
file(
  DOWNLOAD
  https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.40.2/CPM.cmake
  ${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake
)
include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)

CPMAddPackage(
    NAME qbox
    GIT_REPOSITORY https://github.com/quic/qbox.git
    GIT_TAG main
    GIT_SHALLOW on
)

# Add the executable
add_executable(${PROJECT_NAME} /path/to/your/main.cpp)

target_link_libraries(${PROJECT_NAME} PUBLIC
    ${TARGET_LIBS}
)

And to start your little executable: ./your_executable -l /path/to/your/lua_file.lua

[Aabhash23]

Hi @tmarcero

Summary

I'm working on integrating a custom SystemC peripheral into a QEMU-based virtual platform using QBox. My goal is to simulate a multi-core AArch64 (Cortex-A76) platform where Linux runs on QEMU and interacts with a SystemC peripheral. This setup will eventually help me understand QEMU–SystemC communication, including memory-mapped access and device transactions via TLM.

What I’ve Done So Far

Cloned and built the QBox repository.

Created a new custom SystemC peripheral (myperipheral1) and compiled it into a shared library.

Prepared a new Lua configuration file (conf_mp1.lua) with:

8-core ARM Cortex-A76 QEMU CPU.

SystemC router and memory (initiator/target sockets).

GICv3, UART, VirtIO devices.

Linux kernel, DTB, initrd loaded through the QEMU instance.

Added a SystemC peripheral via libname = myperipheral1.so, using global_quantum, amba_socket, and binding to the router.

Removed the global_peripheral_initiator from this setup to simplify the SystemC side.

Attempted to launch the platform with /path/to/platforms-vp --conf conf_mp1.lua.

The Problem / Error

On launching, the simulation crashes with the following error:

ibname =arm_gicv3.so
[E] [ 0 s ]cciutils.find_sc_obj : Unable to find platform.platform.charbackend_stdio_0 [FILE:/home/qbox/systemc-components/common/src/cciutils.cc:43]
terminate called after throwing an instance of 'sc_core::sc_report'
what(): Error: cciutils.find_sc_obj: Unable to find platform.platform.charbackend_stdio_0
In file: /home/qbox/systemc-components/common/src/cciutils.cc:43
Aborted

What I Suspect

From what I understand:

This error suggests the simulation is looking for a charbackend_stdio_0 object at platform.platform.charbackend_stdio_0.

However, in my current conf_mp1.lua, I’ve either omitted this component or defined it at a different hierarchy level.

Previously working versions of my config included a block like:

charbackend_stdio_0 = {
moduletype = "char_backend_stdio";
read_write = true;
};

And this was used by pl011_uart_0:

pl011_uart_0 = {
...
backend_socket = {bind = "&charbackend_stdio_0.biflow_socket"},
};

Now that I’ve removed or restructured this, it seems the QEMU or SystemC peripheral still attempts to reference this component.

What I Need Help With

1. Clarification: Where and how exactly should charbackend_stdio_0 be defined to avoid this error? Is there a fixed hierarchy that must be followed?

2. Alternatives: If I want to avoid standard character backends (e.g., redirect UART elsewhere), how can I cleanly disable/remove this requirement?

3. Best Practices: For new SystemC peripherals, should they also look for console/logging backends in the same way, or can this be optional?

System Information

Host: Ubuntu 22.04

QBox branch: master (latest as of May 2025)

QBox build: Successfully built using standard instructions

Lua config: Custom conf_mp1.lua (can attach if needed)

SystemC peripheral: Custom, simple module for learning purposes

[tmarcero]

Hi @Aabhash23 !

Can you attach your conf_mp1.lua please ?

But yes you should follow a hierarchy like this one platform.charbackend_stdio_0, and not platform.platform.charbackend_stdio_0.

it should be in this form:

platform = {
    ....
   charbackend_stdio_0 = {
      moduletype = "char_backend_stdio";
      read_write = true;
   };
    ....
};

If you want to use UART model you can write your own backend, or even your own UART, but if you want to use the one in Qbox, at the end, you will need a backend model connected to the backend socket of UART.

but the problem here I think is your implementation of the backend model in the lua file.

[Aabhash23]

Hi @tmarcero !

Thankyou for your response PFA modified (conf_mp1.lua) file below take a look at the modifications i have made and please guide me through the correct path to integrate the systemc peripheral with qbox.

conf_mp1.lua

-- Virtual platform configuration
function top()
local str = debug.getinfo(2, "S").source:sub(2)
if str:match("(./)")
then
return str:match("(./)")
else
return "./"
end
end

dofile(top().."../fw/utils.lua");
print ("Lua config running...")

INITIAL_DDR_SPACE = 0x80000000
_KERNEL64_LOAD_ADDR = INITIAL_DDR_SPACE + 0x01200000
_DTB_LOAD_ADDR = INITIAL_DDR_SPACE + 0x07600000
_INITRD_LOAD_ADDR = INITIAL_DDR_SPACE + 0x0A800000

dofile(top().."fw/arm64_bootloader.lua")

local ARM_NUM_CPUS = 8
local IS_SHARED_MEM = false
if ACCEL == nil then ACCEL = "tcg" end

print("Virtual acceleration: " .. ACCEL)

local MY_PERIPHERAL_ADDR = 0x100000000
local UART_ADDR = 0x09000000
local UART_IRQ = 33

platform = {
moduletype = "Container";
quantum_ns = 10000000;

router = {
    moduletype = "router";
    log_level = 4;
};

ram_0 = {
    moduletype = "gs_memory";
    target_socket = { address = INITIAL_DDR_SPACE; size = 0x100000000; bind = "&router.initiator_socket" };
    log_level = 0;
    shared_memory = IS_SHARED_MEM;
};

qemu_inst_mgr = {
    moduletype = "QemuInstanceManager";
};

qemu_inst = {
    moduletype = "QemuInstance";
    args = {"&platform.qemu_inst_mgr", "AARCH64"};
    accel = ACCEL;
    tcg_mode = "MULTI";
    sync_policy = "multithread-unconstrained";
    log_level = 4;
};

gic_0 = {
    moduletype = "arm_gicv3";
    args = {"&platform.qemu_inst"};
    dist_iface = { address = 0x17A00000; size = 0x60000; bind = "&router.initiator_socket" };
    redist_iface_0 = { address = 0x17A60000; size = 0x1C0000; bind = "&router.initiator_socket" };
    num_cpus = ARM_NUM_CPUS;
    redist_region = { ARM_NUM_CPUS };
    num_spi = 960;
};

charbackend_stdio_0 = {
    moduletype = "char_backend_stdio";
    read_write = true;
};

uart_0 = {
    moduletype = "Pl011";
    dylib_path = "/home/qbox/build/uart-pl011";
    irq = { bind = "&gic_0.spi_in_32" };
    target_socket = { address = 0x09000000; size = 0x1000; bind = "&router.initiator_socket" };
    char_backend = { bind = "&platform.charbackend_stdio_0" };
};

myperipheral1 = {
    moduletype = "myperipheral1";
    dylib_path = "/home/qbox/build/myperipheral1";
    target_socket = { address = MY_PERIPHERAL_ADDR; size = 0x1000; bind = "&router.initiator_socket" };
    log_level = 4;
};

fallback_0 = {
    moduletype = "gs_memory";
    target_socket = { address = 0x0; size = 0x800000000; bind = "&router.initiator_socket"; priority = 1 };
    dmi_allow = false;
    log_level = 0;
    shared_memory = IS_SHARED_MEM;
};

load = {
    moduletype = "loader";
    initiator_socket = { bind = "&router.target_socket" };
    { bin_file = top().."fw/Artifacts/Image.bin", address = _KERNEL64_LOAD_ADDR };
    { bin_file = top().."fw/Artifacts/ubuntu.dtb", address = _DTB_LOAD_ADDR };
    { bin_file = top().."fw/Artifacts/image_ext4_initrd.img", address = _INITRD_LOAD_ADDR };
    { data = _bootloader_aarch64, address = INITIAL_DDR_SPACE };
};

};

-- Print memory map summary
print("Kernel is loaded at: 0x" .. string.format("%x", _KERNEL64_LOAD_ADDR))
print("DTB is loaded at: 0x" .. string.format("%x", _DTB_LOAD_ADDR))
print("Initrd is loaded at: 0x" .. string.format("%x", _INITRD_LOAD_ADDR))
print("MyPeripheral1 mapped at: 0x" .. string.format("%x", MY_PERIPHERAL_ADDR))
print("PL011 UART mapped at: 0x" .. string.format("%x", UART_ADDR))

-- Add CPUs
for i = 0, (ARM_NUM_CPUS - 1) do
platform["cpu_" .. i] = {
moduletype = "cpu_arm_cortexA76";
args = {"&platform.qemu_inst"};
mem = { bind = "&router.target_socket" };
has_el3 = false;
has_el2 = false;
irq_timer_phys_out = { bind = "&gic_0.ppi_in_cpu_" .. i .. "26" };
irq_timer_virt_out = { bind = "&gic_0.ppi_in_cpu" .. i .. "27" };
irq_timer_hyp_out = { bind = "&gic_0.ppi_in_cpu" .. i .. "_24" };
}
end

[tmarcero]

Ok thanks, so char_backend is not the right name of the socket, the socket is called backend_socket, and you should link it with a socket of the charbackend_stdio_0 model like this:

backend_socket = {bind = "&charbackend_stdio_0.biflow_socket"}

[Aabhash23]

Hi @tmarcero !

Thanks a lot for the help now im successfully able to initiate the qemu instance but after a certain point the terminal got stuck with the below output could so you please help me with some insights here.

Output

    SystemC 3.0.2-Accellera --- May 20 2025 19:02:27
    Copyright (c) 1996-2025 by all Contributors,
    ALL RIGHTS RESERVED

Lua config running...
Virtual acceleration: tcg
Kernel is loaded at: 0x81200000
DTB is loaded at: 0x87600000
Initrd is loaded at: 0x8a800000
MyPeripheral1 mapped at: 0x100000000
PL011 UART mapped at: 0x9000000
libname =char_backend_stdio.so
libname =gs_memory.so
libname =loader.so
myperipheral1: Constructor complete.
libname =router.so
libname =/home/qbox/build/uart-pl011.so
libname =cpu_arm_cortexA76.so
libname =arm_gicv3.so
[I] [ 0 s ]SystemC : SC_START
[I] [ 0 s ]pla...fallback_0.target_socket: Address map platform.fallback_0.target_socket at address 0x0 size 0x800000000 (with relative address)
[I] [ 0 s ]pla...eripheral1.target_socket: Address map platform.myperipheral1.target_socket at address 0x100000000 size 0x1000 (with relative address)
[I] [ 0 s ]platform.ram_0.target_socket : Address map platform.ram_0.target_socket at address 0x80000000 size 0x100000000 (with relative address)
[I] [ 0 s ]platform.uart_0.target_socket : Address map platform.uart_0.target_socket at address 0x9000000 size 0x1000 (with relative address)
[I] [ 0 s ]platform.gic_0.dist_iface : Address map platform.gic_0.dist_iface at address 0x17a00000 size 0x60000 (with relative address)
[I] [ 0 s ]platform.gic_0.redist_iface_0 : Address map platform.gic_0.redist_iface_0 at address 0x17a60000 size 0x1c0000 (with relative address)
[I] [ 0 s ]platform.qemu_inst : Initializing QEMU instance with args:
[I] [ 0 s ]platform.qemu_inst : libqbox
[I] [ 0 s ]platform.qemu_inst : -M
[I] [ 0 s ]platform.qemu_inst : none
[I] [ 0 s ]platform.qemu_inst : -m
[I] [ 0 s ]platform.qemu_inst : 2048
[I] [ 0 s ]platform.qemu_inst : -monitor
[I] [ 0 s ]platform.qemu_inst : null
[I] [ 0 s ]platform.qemu_inst : -serial
[I] [ 0 s ]platform.qemu_inst : null
[I] [ 0 s ]platform.qemu_inst : -accel
[I] [ 0 s ]platform.qemu_inst : tcg,thread=multi
[I] [ 0 s ]platform.qemu_inst : -display
[I] [ 0 s ]platform.qemu_inst : none
Loading libqemu-system-aarch64.so

[tmarcero]

Hi @Aabhash23 !

Do you have the images Image.bin, ubuntu.dtb and image_ext4_initrd.img ?

Otherwise can you use GDB and Debug build and hit CTRL + C, when the VP is "waiting" ?