{"id":13836059,"url":"https://github.com/Wren6991/RISCBoy","last_synced_at":"2025-07-10T13:31:36.799Z","repository":{"id":41394790,"uuid":"125576403","full_name":"Wren6991/RISCBoy","owner":"Wren6991","description":"Portable games console, designed from scratch: CPU, graphics, PCB, and the kitchen sink","archived":false,"fork":false,"pushed_at":"2023-07-04T20:15:11.000Z","size":51362,"stargazers_count":283,"open_issues_count":3,"forks_count":14,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-07-01T18:12:42.367Z","etag":null,"topics":["cpu","fpga","gameboy","pcb","risc","risc-v"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wren6991.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-03-16T22:31:53.000Z","updated_at":"2025-06-30T07:18:40.000Z","dependencies_parsed_at":"2024-01-13T16:44:51.962Z","dependency_job_id":"ada46cd8-8e77-4c17-81d5-1b2dad553e32","html_url":"https://github.com/Wren6991/RISCBoy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Wren6991/RISCBoy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wren6991%2FRISCBoy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wren6991%2FRISCBoy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wren6991%2FRISCBoy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wren6991%2FRISCBoy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wren6991","download_url":"https://codeload.github.com/Wren6991/RISCBoy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wren6991%2FRISCBoy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264585372,"owners_count":23632646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpu","fpga","gameboy","pcb","risc","risc-v"],"created_at":"2024-08-04T15:00:34.441Z","updated_at":"2025-07-10T13:31:31.790Z","avatar_url":"https://github.com/Wren6991.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"RISCBoy\n=======\n\nRISCBoy is an open-source portable games console, designed from scratch. This includes:\n\n- A RISC-V compatible CPU\n- A raster graphics pipeline and display controller\n- Other chip infrastructure: busfabric, memory controllers, UART, GPIO etc.\n- A PCB layout in KiCad\n\n![](doc/diagrams/system_arch.png)\n\nIt is a Gameboy Advance from a parallel universe where RISC-V existed in 2001. A love letter to the handheld consoles from my childhood, and a 3AM drunk text to the technology that powered them.\n\nThe design is written in synthesisable Verilog 2005, and is intended to fit onto an iCE40-HX8k FPGA. This is a LUT4-based FPGA with 7680 logic elements, so fitting a 32 bit games console requires a crowbar and some vaseline, or perhaps just careful design. The HX8k was once the largest FPGA targeted by the open-source [Icestorm](http://www.clifford.at/icestorm/) FPGA toolchain, but that toolchain has since [moved on](https://github.com/SymbiFlow/prjtrellis) to [greater things](https://github.com/SymbiFlow/prjxray).\n\nMore detailed information can be found in the [documentation](doc/riscboy_doc.pdf).\n\nThe processor supports the RV32IMC instruction set, and passes the RISC-V compliance suite for these instructions, as well as the [riscv-formal](https://github.com/SymbioticEDA/riscv-formal) verification suite, and some of my own formal property checks for instruction frontend consistency and basic bus compliance. It also supports M-mode CSRs, exceptions, and a simple compliant extension for vectored external interrupts.\n\nCloning\n-------\n\n**This repository uses submodules for HDL as well as tests**\n\n```bash\ngit clone --recursive https://github.com/Wren6991/RISCBoy.git riscboy\n```\n\nAlternatively\n\n```bash\ngit clone https://github.com/Wren6991/RISCBoy.git riscboy\ncd riscboy\ngit submodule update --init --recursive\n```\n\nNote a recursive submodule update is required to run the processor's standalone tests. This is not necessary for building RISCBoy gateware.\n\nBuilding RV32IMC Toolchain\n-------------------------\n\nThe RV32IMC toolchain is required for compilation of software-based tests. Follow the instructions on the [RISC-V GNU Toolchain GitHub](https://github.com/riscv/riscv-gnu-toolchain), except for the configure line:\n\n```bash\n# Prerequisites for Ubuntu 20.04\nsudo apt install -y 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\ncd /tmp\ngit clone --recursive https://github.com/riscv/riscv-gnu-toolchain\ncd riscv-gnu-toolchain\n# The ./configure arguments are the most important difference\n./configure --prefix=/opt/riscv --with-arch=rv32imc --with-abi=ilp32 --with-multilib-generator=\"rv32i-ilp32--;rv32ic-ilp32--;rv32im-ilp32--;rv32imc-ilp32--\"\nsudo mkdir /opt/riscv\nsudo chown $(whoami) /opt/riscv\nmake -j $(nproc)\n```\n\nOn smaller FPGAs, like the iCE40 UP5k, RISCBoy may be configured to use a smaller RV32I variant of the processor, rather than the higher-performance RV32IMC version. The compiler will support any of the ISA variants available on RISCBoy, but we must also instruct the toolchain build scripts to produce standard libraries for these variants, via the `--with-multilib` arguments. Running a RV32I executable linked against an RV32IMC standard library on an RV32I-only processor will ruin your day!\n\nSimulation\n----------\n\nThe simulation flow is driven by Xilinx ISIM 14.x; makefiles are found in the scripts/ folder. This has only been tested with the Linux version of ISIM.\n\nYou will also need to checkout the RISC-V compliance suite in order to run these tests (note the `-- test` is required to stop git from looking in the KiCad directories and complaining about the library structure there).\n\n```\n$ git submodule update --init --recursive\n```\n\nOnce this is ready, you should be able to run the following:\n\n```bash\n. sourceme\ncd test\n./runtests\n```\n\nwhich will run all of the HDL-level tests. Software tests will require the RV32IC toolchain. You may need to adjust some of the paths in `sourceme` if ISIM is installed in a non-default location. To graphically debug a test, run its makefile directly:\n\n```bash\ncd system\nmake TEST=helloworld gui\n```\n\nPCB\n---\n\nThe image shows the Rev A PCB. It is compatible with iTead's 4-layer 5x5 cm prototyping service, which currently costs $65 for 10 boards.\n\n![](board/riscboy_reva0/board_render01.jpg)\n\nThe schematic can be viewed [here (pdf)](board/fpgaboy.pdf)\n\nRev B will look quite different; I am waiting for the gateware and bootloader to mature before proceeding. My current dev hardware looks a lot like my [Snowflake FPGA board](https://github.com/Wren6991/Snowflake-FPGA).\n\nSynthesis\n---------\n\nFPGA synthesis for iCE40 uses an open-source toolchain. If you would like to build this project using the existing makefiles, you will first need to build the toolchain I used:\n\n- [Yosys](https://github.com/yosyshq/yosys) for synthesis\n- [nextpnr](https://github.com/YosysHQ/nextpnr) for place and route\n- [Project Icestorm](http://www.clifford.at/icestorm/) for bitstream generation\n\nNote that I have only built these on Linux. I've heard it is possible to build these on Windows, but haven't tried it. However, they can be built on a Raspberry Pi, which is neat.\n\nOnce the toolchain is in place, run\n\n```bash\n. sourceme\ncd synth\nmake -f HX8k-EVN.mk bit\n```\n\nto generate an FPGA image suitable for Lattice HX8k evaluation board.\n\nThere is also highly experimental support (i.e. not my main dev platform) for ECP5, with board files for the Lattice LEF5UM5G-85F-EVN evaluation board:\n\n```bash\nmake -f ECP5-EVN.mk BUILD=full bit\n```\n\nThis build replaces the external, 512 kiB, 16 bit wide SRAM of RISCBoy development hardware with an internal, 256 kiB, 32 bit wide synchronous memory, which Trellis builds out of ECP5 sysmem blocks.\n\nDirectory Structure\n-------------------\n\n- `board`: KiCad files for main RISCBoy PCB and other small boards used during development\n- `doc`: LaTeX source and diagrams for documentation, and the most recently built PDF\n- `hdl`: The Verilog source for RISCBoy gateware.\n\t- `busfabric`: AHB-lite crossbar and APB peripheral fabric\n\t- `graphics`: Source for the pixel processing unit\n\t- `hazard5`: Source for the RISC-V processor. This is completely self-contained.\n\t- `mem`: Memory controllers, and inference/injection wrappers and models for the memories themselves\n\t- `peris`: Small peripherals such as UART, SPI, PWM\n\t- `riscboy_core`: Structural module to instantiate and connect the components that comprise RISCBoy\n\t- `riscboy_fpga`: Top-level wrappers for a few different FPGAs and boards: connect up IOs, provide clock and reset\n- `reference`: a few PDFs for standards used in RISCBoy, e.g. the RISC-V instruction set\n- `scripts`: Junk that I can't put anywhere else\n- `software`: Loose collection of C files that are used for system-level tests. Not really a useful software tree yet.\n- `synth`: Working directory for running whole-system synthesis. Top-level makefiles, pin constraint files.\n- `test`: Regression tests. Some are Verilog testbenches, others are software testcases that run on simulations of the processor or the full system.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWren6991%2FRISCBoy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWren6991%2FRISCBoy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWren6991%2FRISCBoy/lists"}