Qubot/retro-go
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
retro-go/BUILDING.md
Rohan Gupta 45bdfaf6f8
Instructions for porting retro-go to custom hardware (#156) 
* PATCHING.md and some instructions for building imgs

* Add Custom Hardware to the table of contents

* Github Markdown formatting changes

* Update BUILDING.md

I'm not too keen on your changes in BUILDING.md. Once a .img/.fw has been flashed, flash/run/monitor will work regardless of the initial format but your addition implies that those don't apply to .img but they do.

I think what should be done instead is move your new "Flashing" section to be right after the "Build everything" section. Maybe rename it "Initial Flashing" or "First Installation" or something along those lines. Then describe how to flash a .img or a .fw for the first time on a new device.


I'm doing a commit just to quickly show you what I have in mind, feel free to revert or entirely rewrite and continue with your vision :)

* Remove redundant changes in README.md
While previous changes in the README.md introduced unnececary info, I do want to keep some links.

One thing is that a link to building/installing should definetly be higher up, as I wasn't sure where to get started with retro-go until I scrolled down the whole README

Another thing is that I added a link to PATCHING in the "Generic ESP32" install instructions as their was already a mention about porting in it

* Rename PATCHING and replace all occurances/refs

Yup, this name makes much more sense

* Fill in blank info and reorganize rg_tool info

This fills in instructions for the esp_tool info.
Also, it made more sense to describe rg_tool in BUILDING.md as it isn't only used for porting

* Consitency with Links and commands

This adds links (to the relevent section) to unlinked text. Also makes the difference between `./rg_tool.py` and `python rg_tool.py` a little more consistant

* Remove Unused Title in README

* Remove redundant spaces and lines

---------

Co-authored-by: ducalex <ducalex007@gmail.com>
2024-10-11 13:53:05 -04:00

5.1 KiB
Raw Blame History

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

ESP-IDF doesn't support managing multiple apps in one environment (launcher, prboom-go, etc). rg_tool.py is used instead, which passes correct arguments to idf.py and other tools.

To get started, run

./rg_tool.py

or

python rg_tool.py

Build everything and generate a firmware image:

  • Generate a .fw file to be installed with odroid-go-firmware (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

Environment variables

rg_tool.py supports a few environment variables if you want to avoid passing flags all the time:

  • RG_TOOL_TARGET represents --target
  • RG_TOOL_BAUD represents --baud
  • RG_TOOL_PORT represents --port

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

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

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!