Run Quake on rv32emu

Goal

Check how to use SDL systemcall in rv32emu
Learn the transplant process of quake by quakembd which run quake in ARM ISA
run quake on rv32emu whitch is an instruction set architecture (ISA) emulator implementing the 32 bit RISC-V processor model

Step of this project

1. Compile C code to riscv 32bits elf file which can run on rv32emu

Get riscv64-unknown-elf(Newlib multilib)

sudo apt-get install autoconf automake autotools-dev curl python3 libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev
git clone https://github.com/riscv/riscv-gnu-toolchain
cd riscv-gnu-toolchain/
sudo ./configure –prefix=/opt/riscv –enable-multilib
sudo make
export PATH=$PATH:/opt/riscv/bin
Compile and run
- C code
```
#include<stdio.h>
int main() {
        int i;
        i = 1;
        printf("hello risc-v\n");
}
```
- Compile
  
  riscv64-unknown-elf-gcc -march=rv32i -mabi=ilp32 test.c -o test
- Run on rv32emu
  Image Not Showing Possible Reasons
  The image file may be corrupted
  The server hosting the image is unavailable
  The image path is incorrect
  The image format is not supported
  Learn More →

2. Use SDL systemcall in rv32emu

Check How rv32emu implement SDL systemcall via syscall_sdl.c and syscall.c

In syscall_sdl.c we can see that it use three register, a0 is the address of pixel array which SDL will use it to render the scrren, a1 is the width of the screen, and a2 is the height of the scrren。
























void syscall_draw_frame(struct riscv_t *rv)
{
    state_t *s = rv_userdata(rv); /* access userdata */

    /* draw(screen, width, height) */
    const uint32_t screen = rv_get_reg(rv, rv_reg_a0);
    const uint32_t width = rv_get_reg(rv, rv_reg_a1);
    const uint32_t height = rv_get_reg(rv, rv_reg_a2);

    if (!check_sdl(rv, width, height))
        return;

    /* read directly into video memory */
    int pitch = 0;
    void *pixels_ptr;
    if (SDL_LockTexture(texture, NULL, &pixels_ptr, &pitch)) {
        exit(-1);
    }
    memory_read(s->mem, pixels_ptr, screen, width * height * 4);
    SDL_UnlockTexture(texture);

    SDL_RenderCopy(renderer, texture, NULL, &(SDL_Rect){0, 0, width, height});
    SDL_RenderPresent(renderer);
}

In syscall.c, we can see that it use fake systemcall number 0xbeef and 0xbabe to call SDL, so we have to set the corresponding number to a7 register in order to call it。







#ifdef ENABLE_SDL
    case 0xbeef:
        syscall_draw_frame(rv);
        break;
    case 0xbabe:
        syscall_draw_frame_pal(rv);
        break;

Write C code to use SDL in rv32emu

C code
- we can use C to generate riscv assembly, register int a asm("a0") = width just like li a0,800, and asm volatile("scall") is ecall。
- In my observation, if we write register int a asm("a0") = width in a function, it may be discard by compiler due to optimizetion, to avoid that, we can write register int a asm("a0") = width; asm volatile (""::"r"(a0)); instead, the volatile keyword will prevent optimiztion。


















int main() {
        int syscall_num,width,height;
        syscall_num = 0xbeef; // syscall_draw_frame
        width = 800;
        height = 480;
        static int buffer[800 * 480];
        int i = 0;
        for(i = 0; i < 400* 320; i++) {
                buffer[i] = 255;
        }
        register int a0 asm("a0") = &buffer;
        register int a1 asm("a1") = width;
        register int a2 asm("a2") = height;
        while(1) {
                register int a7 asm("a7") = syscall_num;
                asm volatile ("scall");
        }
}

run in rv32emu
Image Not Showing Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →

3. Learning from quakembd

Follow the github readme, we can use CMake and ninja with GNU Arm Embedded Toolchain and STM32Cube package to build quake for embedded devices like STM32H747I-DISCO ARM Cortex-M devices,since I don't have above device so I can't run it.

Check the repo, I also find there is a emulator directory that use minifb to run quake for different ISA, as long as we modify the Cmake file, here I want to build it in x86 ISA first, because I think it's much easy compared to riscv since many include library may not be support by riscv-toolchain and if we can success build it in x86, it will much easy for me to rewrite it to riscv。

How to build

Change CMake.txt

In winquke

Here I remove some .c and all .s file, becuse it will cause some error in riscv and in fact we don't need them absolutely








































































set(WQ_SRCS
    chase.c
    cmd.c
    common.c
    console.c
    crc.c
    cvar.c
    draw.c
    host.c
    host_cmd.c
    keys.c
    mathlib.c
    menu.c
    model.c
    nonintel.c
    screen.c
    sbar.c
    zone.c
    view.c
    wad.c
    world.c
    cl_demo.c
    cl_input.c
    cl_main.c
    cl_parse.c
    cl_tent.c
    d_edge.c
    d_fill.c
    d_init.c
    d_modech.c
    d_part.c
    d_polyse.c
    d_scan.c
    d_sky.c
    d_sprite.c
    d_surf.c
    d_vars.c
    d_zpoint.c
    net_loop.c
    net_main.c
    net_vcr.c
    pr_cmds.c
    pr_edict.c
    pr_exec.c
    r_aclip.c
    r_alias.c
    r_bsp.c
    r_light.c
    r_draw.c
    r_efrag.c
    r_edge.c
    r_misc.c
    r_main.c
    r_sky.c
    r_sprite.c
    r_surf.c
    r_part.c
    r_vars.c
    sv_main.c
    sv_phys.c
    sv_move.c
    sv_user.c
)

list(APPEND WQ_SRCS net_none.c)


add_library(winquake OBJECT ${WQ_SRCS}})

target_include_directories(winquake PUBLIC
    ${PROJECT_SOURCE_DIR}/winquake
)

In port

change add_subdirectory to boards/emulator, then we can build quake in another way














add_library(port OBJECT
    in_port.c
    cd_null.c
    snd_null.c
    sys_port.c
    vid_port.c
)

target_include_directories(port PUBLIC
    ${PROJECT_SOURCE_DIR}/include
    ${PROJECT_SOURCE_DIR}/winquake
)

add_subdirectory(boards/emulator)

In port/boards/emulator

here we must add m in target_link_libraries, otherwise it will not link math.h library and cause undefied reference if we use function in math.h。

















set(USE_METAL_API ON)
add_subdirectory(${PROJECT_SOURCE_DIR}/lib/minifb ${CMAKE_BINARY_DIR}/minifb)

add_executable(quakembd
    main.c
    display.c
    ../../fio/fio_posix.c
)



target_link_libraries(quakembd
    winquake
    port
    minifb
    m
)

Change toolchain.cmake

We can find it in /port/boards/stm32h747i_disco/gcc/ and replace it to project root directory
Change the toolchain from arm to x86, then add some neccessary C_FLAGS and remove all unecessary C_FLAGS




























set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR x86_64)


set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
set(CMAKE_C_COMPILER gcc)
set(CMAKE_CXX_COMPILER g++)
set(CMAKE_ASM_COMPILER gcc)
set(CMAKE_OBJCOPY objcopy)
set(CMAKE_SIZE size)


set(CMAKE_C_FLAGS "-std=gnu11 -Wall -ffunction-sections -fdata-sections")
set(CMAKE_ASM_FLAGS "-x assembler-with-cpp")
set(CMAKE_EXE_LINKER_FLAGS "-Wl,-Map=${CMAKE_CURRENT_BINARY_DIR}/output.map -Wl,--gc-sections -u _printf_float -u _scanf_float -lm")

set(CMAKE_C_FLAGS_DEBUG "-Og -g")
set(CMAKE_ASM_FLAGS_DEBUG "-g")

set(CMAKE_C_FLAGS_RELEASE "-Os")
set(CMAKE_ASM_FLAGS_RELEASE "")


function(add_embedded_binary TARGET)
    add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_OBJCOPY} -O binary ${TARGET} ${TARGET}.bin)
    add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_OBJCOPY} -O ihex ${TARGET} ${TARGET}.hex)
    add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_SIZE} ${TARGET})
endfunction()

Get quake Shareware Data

Dowload shareware data and place it in project root directory

Fixed some error and change some code in original project source code

There is a little error that we have to fixed, and some code we have to change in winquake source code, in order to run quake correctly。

Build quake for x86 ISA

Here, I write the build step to a shell script for convenience









#!/bin/bash
rm -r build
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake -DUSE_WAYLAND_API=OFF -DUSE_OPENGL_API=OFF  -DCMAKE_BUILD_TYPE=RELEASE  -GNinja ..
ninja
cd port/boards/emulator
mkdir quake
mv quakembd quake/
cp ../../../../id1 -r quake/id1

Run quake on x86 ISA

4.Run Quake on rv32emu

Since we successfully run the emulator code in x86 ISA, we can now modify it to other ISA easyly by making some essential change。

Change toolchain.cmake

We can specify the toolchain and the flag in this file, and when we use cmake, use -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake flag to Cross Compiling































set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR riscv)

set(TOOLCHAIN_PREFIX "/opt/riscv/bin/riscv64-unknown-elf-")

set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
set(CMAKE_C_COMPILER ${TOOLCHAIN_PREFIX}gcc)
set(CMAKE_CXX_COMPILER ${TOOLCHAIN_PREFIX}g++)
set(CMAKE_ASM_COMPILER ${TOOLCHAIN_PREFIX}gcc)
set(CMAKE_OBJCOPY ${TOOLCHAIN_PREFIX}objcopy)
set(CMAKE_SIZE ${TOOLCHAIN_PREFIX}size)

set(ARCH_FLAGS "-march=rv32i -mabi=ilp32")

set(CMAKE_C_FLAGS "${ARCH_FLAGS} -std=gnu11 -Wall -ffunction-sections -fdata-sections")
set(CMAKE_ASM_FLAGS "${ARCH_FLAGS} -x assembler-with-cpp")
set(CMAKE_EXE_LINKER_FLAGS "-Wl,-Map=${CMAKE_CURRENT_BINARY_DIR}/output.map -Wl,--gc-sections -u _printf_float -u _scanf_float -lm")

set(CMAKE_C_FLAGS_DEBUG "-Og -g")
set(CMAKE_ASM_FLAGS_DEBUG "-g")

set(CMAKE_C_FLAGS_RELEASE "-Os")
set(CMAKE_ASM_FLAGS_RELEASE "")


function(add_embedded_binary TARGET)
	add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_OBJCOPY} -O binary ${TARGET} ${TARGET}.bin)
	add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_OBJCOPY} -O ihex ${TARGET} ${TARGET}.hex)
	add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_SIZE} ${TARGET})
endfunction()

Change CMake.txt in port/boards/emulator

Remove minifb in target_link_libraries, since we will use rv32emu SDL systemcall to rendering game screen

Replace MiniFB API to rv32emu SDL systemcall to rendering gmae screen

In port/boards/emulator/display.c, rewrite the function related to game screen init and refresh
Original











void qembd_vidinit()
{
	window = mfb_open_ex("Quake", DISPLAY_WIDTH, DISPLAY_HEIGHT, WF_RESIZABLE);
	if (!window)
		qembd_error("Can't create Window");
}
void qembd_refresh()
{
	if (window)
		mfb_update(window, buffer);
}

Chage to




















void qembd_vidinit()
{
	register int a0 asm("a0") = &buffer;
	register int a1 asm("a1") = DISPLAY_WIDTH;
	register int a2 asm("a2") = DISPLAY_HEIGHT;
	register int a7 asm("a7") = syscall_num;

	asm volatile ("scall"
		: "r+"(a0) : "r"(a1), "r"(a2), "r"(a7));
}
void qembd_refresh()
{
	register int a0 asm("a0") = &buffer;
	register int a1 asm("a1") = DISPLAY_WIDTH;
	register int a2 asm("a2") = DISPLAY_HEIGHT;
	register int a7 asm("a7") = syscall_num;

	asm volatile ("scall"
		: "r+"(a0) : "r"(a1), "r"(a2), "r"(a7));
}

Get quake Shareware Data

Dowload shareware data and place it in project root directory

Fixed some error and change some code in original project source code

We have to avoid include Linux's library like <sys/socket.h>、<sys/time.h> etc…, since riscv toolchain newlib mode don't support them, if we really need it change it to C standard library, for example open->fopen
Although we can use the library, some function in it may not be implemented for example usleep in <unistd.h>, so we have to replace it in another way。

Here I write new systemcall in rv32emu, because we can use the above library in rv32emu, so we use it and pass to our game through register

In syscall_sdl.c









void syscall_get_ticks(struct riscv_t *rv)
{
    rv_set_reg(rv,rv_reg_a0,(uint32_t)SDL_GetTicks());
}
void syscall_delay(struct riscv_t *rv)
{
    uint32_t ms = rv_get_reg(rv, rv_reg_a0);
    SDL_Delay(ms);
}

In syscall.c







extern void syscall_get_ticks(struct riscv_t *rv);
extern void syscall_delay(struct riscv_t *rv);
    case 0xcafe:
        syscall_get_ticks(rv);
        break;
    case 0xcaff:
        syscall_delay(rv);

Also add two case in syscall_handler function






case 0xcafe:
    syscall_get_ticks(rv);
    break;
case 0xcaff:
    syscall_delay(rv);
    break;

Then we can use these systemcall in winquake
In port/boards/emulator/main.c




















uint64_t qembd_get_us_time()
{
	register int a0 asm("a0");
	register int a7 asm("a7") = syscall_get_tick;

	asm volatile ("scall"
		: "r+"(a0) : "r"(a7));

	uint32_t time = a0;

	return time;
}
void qembd_udelay(uint32_t us)
{
	register int a0 asm("a0") = 1;
	register int a7 asm("a7") = sys_delay;
	asm volatile ("scall"
		: "r+"(a0) : "r"(a7));
}

Build quake for rv32emu









#!/bin/bash
rm -r build
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake -DCMAKE_BUILD_TYPE=RELEASE  -GNinja ..
ninja
cd port/boards/emulator
mkdir quake
mv quakembd quake/
cp ../../../../id1 -r quake/id1

Run Quake on rv32emu

We have to run it in the directory where quake elf file is, otherwise it can't read the shareware data

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

Observation

Each frame of the game in rv32emu is 15 seconds, because the program will stuck in Host_Frame() for to long, so the game display refresh so slow。
Compared to the game run in x86 ISA, each frame will take only 0.3 second, which make the game display looks more smooth

Fork Repo In Github

Use the following repo to reproduce quake on rv32emu
rv32emu
quakembd

Future Work

Add Audio
Add input event

Use original systemcall in rv32emu for gettime and sleep

Gettime

in syscall.c, we can use syscall_gettimeofday to get time, moreover we can use clock function in time.h to trigger this system call, so we can remove the new systemcall






















static void syscall_gettimeofday(struct riscv_t *rv)
{
    state_t *s = rv_userdata(rv); /* access userdata */

    /* get the parameters */
    riscv_word_t tv = rv_get_reg(rv, rv_reg_a0);
    riscv_word_t tz = rv_get_reg(rv, rv_reg_a1);

    /* return the clock time */
    if (tv) {
        clock_t t = clock();
        int32_t tv_sec = t / CLOCKS_PER_SEC;
        int32_t tv_usec = (t % CLOCKS_PER_SEC) * (1000000 / CLOCKS_PER_SEC);
        memory_write(s->mem, tv + 0, (const uint8_t *) &tv_sec, 4);
        memory_write(s->mem, tv + 8, (const uint8_t *) &tv_usec, 4);
    }
    if (tz) {
        // FIXME: This parameter is ignored by the syscall handler in newlib.
    }
    // success
    rv_set_reg(rv, rv_reg_a0, 0);
}

change in main.c












uint64_t qembd_get_us_time()
{
	uint64_t cur_time = (uint64_t)clock();
	static int secbase;

	if (!secbase) {
		secbase = cur_time / 1000000;
		return (uint64_t) secbase;
	}

	return cur_time;
}

Sleep

For sleep, I let the program stuck in a loop and record the time it get into the loop, then continue to get the latest time until the time minus the start time greater than 1
change in main.c








void qembd_udelay(uint32_t us)
{
	uint64_t start = qembd_get_us_time(), end;
	end = start;
	while(end - start < 1)
		end = qembd_get_us_time();
}

So we don't need the new systemcall and can run quake on original rv32emu!

Jim Huang

2022/01/15 12:57:07

#### Build quake for rv32emu

You can create the fork from GitHub. So that, others can reproduce your work. (Edited)

Korin777

2022/01/16 09:41:43

OK! Thanks for professor's comment~

2022/01/17 23:51:00

se [minifb](https://github.com/emoon/minifb/tree/2b1d7633aecee7b2d9b92e5da739de20af3fc68c) to run quak

Did you have to maintain your own minifb fork? (Edited)

2022/01/18 02:08:25

For quake on x86 ISA，I didn't change the code in minifb repo，and for quake on rv32emu-next，I replace minifb to SDL for rendering game display，so I think no。

2022/01/22 09:22:41

the new s

Thanks for clarifying this! Please send pull request(s) to rv32emu-next for adding Quake binary and usage information. (Edited)

2022/01/22 10:25:09

Thanks for professor's comment and check，I have sent a pull request to rv32emu-next，if there is any problem，please inform me!

Run Quake on rv32emu

Goal

Step of this project

1. Compile C code to riscv 32bits elf file which can run on rv32emu

Get riscv64-unknown-elf(Newlib multilib)

Compile and run

2. Use SDL systemcall in rv32emu

Check How rv32emu implement SDL systemcall via syscall_sdl.c and syscall.c

Write C code to use SDL in rv32emu

3. Learning from quakembd

Change CMake.txt

In winquke

In port

In port/boards/emulator

Change toolchain.cmake

Get quake Shareware Data

Fixed some error and change some code in original project source code

Build quake for x86 ISA

Run quake on x86 ISA

4.Run Quake on rv32emu

Change toolchain.cmake

Change CMake.txt in port/boards/emulator

Replace MiniFB API to rv32emu SDL systemcall to rendering gmae screen

Get quake Shareware Data

Fixed some error and change some code in original project source code

Build quake for rv32emu

Run Quake on rv32emu

Observation

Fork Repo In Github

Future Work

Use original systemcall in rv32emu for gettime and sleep

Gettime

Sleep

Read more

2023q1 Homework7 (ktcp)

2023q1 Homework5 (quiz5)

2023q1 Homework4 (quiz4)

2023q1 Homework3 (quiz3)