Skip to content

Latest commit

 

History

History
121 lines (74 loc) · 6.14 KB

BUILDING.md

File metadata and controls

121 lines (74 loc) · 6.14 KB

Table of contents

Building Retro-Go

Prerequisites

You will need a working installation of esp-idf. Versions 4.3 to 5.2 are supported.

Note: As of retro-go 1.35, I use 4.3. Version 4.1 was used for 1.20 to 1.34 versions.

ESP-IDF Patches

Patching esp-idf may be required for full functionality. Patches are located in tools/patches and can be applied to your global esp-idf installation, they will not break your other projects/devices.

  • sdcard-fix: This patch is mandatory for the ODROID-GO (and clones).
  • panic-hook: This is to help users report bugs, see Capturing crash logs below for more details. The patch is optional but recommended.

Obtaining the code

Using git is the preferred method but you can also download a zip from the project's front page and extract it if you want, Retro-Go has no external dependencies.

There are generally two active git branches on retro-go:

  • master contains the code form the most recent release and is usually tested and known to be working
  • dev contains code in development that will be merged to master upon the next release and is often untested

git clone -b <branch> https://github.com/ducalex/retro-go/

rg_tool.py

ESP-IDF's idf.py isn't capable of managing multiple applications in one project by itself (building a multi-app image, flashing to the correct partition, single build command, etc). rg_tool.py must be used instead, which passes correct arguments to idf.py and other tools.

For brevity, all the commands listed in this document omit additional flags that you will likely need, such as --target and --port. Those two flags can also be specified in the environment as RG_TOOL_TARGET and RG_TOOL_PORT, respectively.

Run python rg_tool.py --help to see all available flags and commands.

Build everything and generate a firmware image:

  • Generate a .fw file to be installed with odroid-go-firmware or odroid-go-multi-firmware from SD Card:
    python rg_tool.py build-fw or python rg_tool.py release (clean build)
  • Generate a .img to be flashed with esptool.py (Serial):
    python rg_tool.py build-img or python rg_tool.py release (clean build)

For a smaller build you can also specify which apps you want, for example the launcher + DOOM only:

  1. python rg_tool.py build-fw launcher prboom-go

Note that the app named retro-core contains the following emulators: NES, PCE, G&W, Lynx, and SMS/GG/COL. As such, these emulators cannot be selected individually. The reason for the bundling is simply size, together they account for a mere 700KB instead of almost 3MB when they were built separately.

Flashing an image for the first time

Once we have successfully built an image file (.img or .fw), it must be flashed to the device.

To flash a .img file with rg_tool.py, run:

python rg_tool.py --target (target) --port (usbport) install (apps)

To flash a .img file with esptool.py, run:

esptool.py write_flash --flash_size detect 0x0 retro-go_*.img

To flash a .fw file:

Instructions depend on your device, refer to README.md.

Build, flash, and monitor individual apps for faster development:

A full Retro-Go image must be flashed at least once (refer to previous section), but, after that, it is possible to flash and monitor individual apps for faster development time.

  1. Flash: python rg_tool.py --port=COM3 flash prboom-go
  2. Monitor: python rg_tool.py --port=COM3 monitor prboom-go
  3. Flash then monitor: python rg_tool.py --port=COM3 run prboom-go

Windows

Running ./rg_tool.py ... on Windows might invoke the wrong Python interpreter (causing the build to fail) or even do nothing at all. In such cases you should use python rg_tool.py ... instead.

Changing the launcher's images

All images used by the launcher (headers, logos) are located in launcher/main/images. If you edit them you must run the launcher/main/gen_images.py script to regenerate images.c. Magenta (rgb(255, 0, 255) / 0xF81F) is used as the transparency color.

Capturing crash logs

When a panic occurs, Retro-Go has the ability to save debugging information to /sd/crash.log. This provides users with a simple way of recovering a backtrace (and often more) without having to install drivers and serial console software. A weak hook is installed into esp-idf panic's putchar, allowing us to save each chars in RTC RAM. Then, after the system resets, we can move that data to the sd card. You will find a small esp-idf patch to enable this feature in tools/patches.

To resolve the backtrace you will need the application's elf file. If lost, you can recreate it by building the app again using the same esp-idf and retro-go versions. Then you can run xtensa-esp32-elf-addr2line -ifCe app-name/build/app-name.elf.

Porting Retro-Go

ESP32

Instructions to port to new ESP32 devices can be found in PORTING.md.

Other architectures

I don't want to maintain non-ESP32 ports in this repository, but let me know if I can make small changes to make your own port easier! The absolute minimum requirements for Retro-Go are roughly:

  • Processor: 200Mhz 32bit little-endian
  • Memory: 2MB
  • Compiler: C99 (and C++03 for handy-go)

Whilst all applications were heavily modified or even redesigned for our constrained needs, special care is taken to keep Retro-Go and ESP32-specific code exclusively in their port file (main.c). This makes reusing them in your own codebase very easy!

IDE Support

VS Code

Retro-Go comes with a VS Code workspace file that contains configuration for the C/C++ extension.

To get intellisense working properly you have to define some paths in your global configuration file:

    "retro-go.sdk-path": "C:/espressif/frameworks/esp-idf-v5.0.4",
    "retro-go.tools-path": "C:/espressif/tools/xtensa-esp32-elf/esp-2021r2-patch3-8.4.0/xtensa-esp32-elf",

Clangd is not supported at this time because I have not found a way to make it work well in our multi-folder workspace.