# Run Quake on rv32emu
## Goal
- Check how to use [SDL](https://www.libsdl.org/) systemcall in [rv32emu](https://github.com/sysprog21/rv32emu)
- Learn the transplant process of [quake](https://github.com/id-Software/Quake) by [quakembd](https://github.com/FantomJAC/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)](https://github.com/riscv-collab/riscv-gnu-toolchain)
> 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

### 2. Use SDL systemcall in rv32emu
1. #### Check How rv32emu implement SDL systemcall via [syscall_sdl.c](https://github.com/sysprog21/rv32emu/blob/master/syscall_sdl.c) and [syscall.c](https://github.com/sysprog21/rv32emu/blob/master/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
### 3. Learning from [quakembd](https://github.com/FantomJAC/quakembd)
1. Follow the github [readme](https://github.com/FantomJAC/quakembd#readme), we can use CMake and ninja with [GNU Arm Embedded Toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads) and [STM32Cube package](https://github.com/STMicroelectronics/STM32CubeH7) to build quake for embedded devices like [STM32H747I-DISCO](https://www.st.com/ja/evaluation-tools/stm32h747i-disco.html) ARM Cortex-M devices,since I don't have above device so I can't run it.
3. Check the repo, I also find there is a emulator directory that use [minifb](https://github.com/emoon/minifb/tree/2b1d7633aecee7b2d9b92e5da739de20af3fc68c) 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。
:::spoiler How to build {state="open"}
#### 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](https://www.libsdl.org/projects/quake/) 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
{%youtube fXdEKz2QBFM %}

:::
### 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](https://www.libsdl.org/projects/quake/) 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
{%youtube w8ksbzBr0pQ %}
### 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](https://github.com/Korin777/rv32emu)
[quakembd](https://github.com/Korin777/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](https://github.com/sysprog21/rv32emu)!