Try   HackMD

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

  1. 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

  2. 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

  1. 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;
  2. 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

  1. 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.
  2. 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

    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 →

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

  1. 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
  2. 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!