retro-go 딥다이브
— ESP32 한 칩에 NES·게임보이·SNES·DOOM을 욱여넣고, '앱마다 펌웨어 하나 + OTA 파티션 점프'로 굴리는 레트로 에뮬레이터 펌웨어

RockBase-iot/retro-go. 손바닥만 한 ESP32 보드에서 런처 1개 + 에뮬레이터 여러 개를 각각 독립 펌웨어로 굽고, 게임을 고를 때마다 부팅 파티션을 바꿔 재부팅하는 방식으로 NES·Game Boy·SNES·Master System·PC Engine·Game & Watch·Lynx·Genesis·MSX·DOOM을 돌리는 임베디드 펌웨어다. 사실 이 레포는 유명한 ducalex/retro-go의 포크이고, RockBase가 새로 더한 건 딱 하나 — NM-CYD-C5라는 신형 ESP32-C5(RISC-V) + Cheap Yellow Display + 저항막 터치 하드웨어 타겟이다. 그래서 이 문서는 두 겹으로 읽는다 — ① retro-go 본체가 메모리 부족한 MCU에서 어떻게 거대한 에뮬레이터들을 굴리는가(멀티-앱 OTA·SPI 디스플레이 부분갱신·크래시 트레이스), ② RockBase의 기여가 어떻게 물리 버튼 없는 $10 보드를 게임기로 만드는가(SPI 버스 공유·터치 가상패드). (저장소: RockBase-iot/retro-go · 언어 C(대부분)·C++·Python · 약 874파일 · ESP-IDF 4.4~5.5 · 라이선스 GPLv2 · upstream = ducalex/retro-go · 신생 포크 — TrendShift 라이브 멘션)

1프로젝트 한줄 요약

"에뮬레이터 하나하나를 '독립된 작은 펌웨어'로 만들어 두고, 게임을 고르면 그 펌웨어로 갈아 끼워 재부팅한다."

좀 더 구체적으로, retro-go는 ESP-IDF(Espressif 공식 SDK, FreeRTOS 기반)로 짠 C 프로젝트입니다. 핵심은 두 부분 — 공통 라이브러리(components/retro-go/, 약 7,800줄)가 디스플레이·오디오·입력·저장·설정·네트워크를 모든 앱이 공유하는 "작은 OS"처럼 추상화하고, 그 위에 런처(파일 브라우저·즐겨찾기·Wi-Fi 파일 매니저)와 에뮬레이터 앱들(7개를 한 펌웨어에 묶은 retro-core + 덩치 큰 prboom-go/gwenesis/fmsx)이 얹힙니다.

그리고 이 레포가 트렌딩에 오른 직접적 이유는 RockBase-iot가 더한 NM-CYD-C5 타겟입니다 — 메이커 씬에서 유명한 CYD(Cheap Yellow Display)의 신형 ESP32-C5 버전 보드에 retro-go를 올리고, 물리 버튼이 하나도 없는 보드에서 저항막 터치스크린을 9개 가상 버튼으로 매핑해 게임기를 만든 "기술 검증(PoC)"입니다. 이 문서는 사용법을 넘어 그 안의 임베디드 시스템 설계를 파고듭니다 — 멀티-앱 OTA, SPI 버스 하나에 화면·터치·SD카드를 다는 법, 매 프레임 전체가 아닌 바뀐 줄만 보내는 부분 갱신, 재부팅해도 살아남는 RTC 메모리로 크래시를 SD카드에 남기는 법.

2왜 주목받는가

"$10 만능 보드(CYD) + 신형 RISC-V 칩(ESP32-C5) + 버튼 없이 터치로 게임 — 따라 하기 쉬운 화제성의 3박자."

먼저, retro-go 본체가 푸는 문제 — '메모리가 손바닥만 한 칩에서 큰 에뮬레이터 돌리기'

ESP32에서 에뮬레이터를 돌리려는 사람은 항상 같은 벽에 부딪힙니다 — 코드도 RAM도 부족하다는 것. SNES 에뮬레이터 하나만 해도 코드가 1MB에 육박하고, 에뮬레이션엔 프레임버퍼·작업 RAM이 또 필요합니다. 에뮬레이터를 여러 개 담으면 플래시·RAM이 모두 터집니다.

그리고 RockBase가 더한 화제성 — '버튼 없는 $10 보드를 게임기로'

이 포크가 트렌딩에 오른 건 접근성 때문입니다. 세 가지가 겹쳤습니다.

경쟁/유사 프로젝트와 비교

3기술 스택 전체 지도

"ESP-IDF + FreeRTOS 위에, C로 짠 '작은 OS'(공통 라이브러리)와 에뮬레이터 코어들, 그리고 Python 빌드 오케스트레이터."

retro-go는 외부 서비스·클라우드가 전혀 없는 순수 펌웨어입니다. 스택은 네 층으로 읽으면 깔끔합니다 — ① 토대(ESP-IDF/FreeRTOS), ② 공통 라이브러리(모든 앱이 공유하는 추상화), ③ 에뮬레이터 코어들, ④ 빌드·패킹 도구.

① 토대 — ESP-IDF + FreeRTOS

② 공통 라이브러리(components/retro-go/) — 모든 앱의 '작은 OS'

이 폴더가 retro-go의 심장입니다. 런처든 에뮬레이터든 모두 이 라이브러리를 링크해, 하드웨어를 직접 만지지 않고 추상화된 API만 부릅니다.

③ 에뮬레이터 코어 — 한 레포에 8/16비트 CPU가 줄줄이

retro-go는 코어를 두 형태로 배치합니다 — 가벼운 7개는 retro-core 하나로 번들(크기 절약), 덩치 큰 3개는 독립 앱.

④ 빌드·패킹 도구(Python) — '여러 펌웨어를 한 이미지로'

rg_tool.py가 핵심입니다. idf.py가 멀티-앱을 못 하므로, 이 도구가 ① 타겟 환경(targets/{target}/env.py)을 읽어 IDF_TARGET·기본 앱 목록을 정하고, ② 각 앱을 idf.py app으로 빌드하며 타겟 매크로를 주입하고, ③ mkfw.py로 부트로더+파티션테이블+앱들을 단일 이미지(.img/.fw)로 묶습니다.

# rg_tool.py — 앱마다 OTA 파티션을 부여하는 정의
PROJECT_APPS = {
  # 이름          Type SubType  Size(bytes)
  'launcher':     [0, 16, 1048576],   # 1MB
  'retro-core':   [0, 16, 1048576],   # 1MB (NES+GB+SNES+PCE+SMS+G&W+Lynx 번들)
  'prboom-go':    [0, 16, 786432],    # 768KB (DOOM)
  'gwenesis':     [0, 16, 1048576],   # 1MB (Genesis)
  'fmsx':         [0, 16, 589824],    # 576KB (MSX)
}
# SubType 16 = APP_OTA_0. 빌드 시 16,17,18… 순으로 OTA 인덱스를 재기록

타겟별 환경은 env.py 한 장이 exec()로 주입됩니다. NM-CYD-C5의 예 — PoC라 가벼운 앱만 기본 포함합니다:

# targets/nm-cyd-c5/env.py
IDF_TARGET = "esp32c5"
FW_FORMAT  = "none"
DEFAULT_APPS = "launcher retro-core"          # PoC: 가벼운 것만
PROJECT_APPS["retro-core"][2] = 0x110000      # C5용 파티션 크기 오버라이드

4아키텍처 심화 분석 (게임 하나가 부팅되기까지)

"핵심은 단 하나 — 앱 전환 = '부팅 파티션을 바꾸고 재부팅'. 그 위에 디스플레이 부분 갱신, 크래시 트레이스, SPI 버스 공유가 얹힌다."

설계 ① — 멀티-앱 OTA: 앱 전환이 곧 '재부팅 점프'

retro-go에서 가장 중요한 아이디어입니다. 각 에뮬레이터는 플래시의 서로 다른 OTA 파티션에 들어간 독립 펌웨어입니다. 런처에서 게임을 고르면 — ① "다음 부팅은 이 게임, 이 롬 경로"를 NVS에 적고, ② 부팅 파티션을 그 에뮬레이터로 지정한 뒤, ③ 재부팅합니다. 켜지면 통째로 다른 프로그램이 됩니다.

// components/retro-go/rg_system.c — 앱 전환은 noreturn(돌아오지 않음)
void rg_system_switch_app(const char *partition, const char *name,
                          const char *args, uint32_t flags)
{
    if (update_boot_config(partition, name, args, flags))  // 1) 부트 설정 기록
        rg_system_restart();                                // 2) esp_restart()
    RG_PANIC("Failed to switch app!");
}
// update_boot_config 내부:
rg_settings_set_string(NS_BOOT, SETTING_BOOT_NAME, name);   // 어떤 게임
rg_settings_set_string(NS_BOOT, SETTING_BOOT_ARGS, args);   // 롬 경로
esp_ota_set_boot_partition(...);                            // 다음 부팅 파티션

설계 ② — 한 펌웨어 안의 7개 코어: 부트 시 네임스페이스로 분기

retro-core는 7개 에뮬레이터를 한 펌웨어에 묶었습니다. 부팅하면 런처가 NVS에 적어 둔 configNs(네임스페이스 문자열, 예 "nes")를 읽어 해당 코어의 진입점으로 분기합니다.

// retro-core/main/main.c — 부트 시 한 코어로 분기
void app_main(void) {
    rg_app_t *app = rg_system_init(AUDIO_SAMPLE_RATE, NULL, NULL);
    if      (!strcmp(app->configNs, "gb")  || !strcmp(app->configNs,"gbc")) gbc_main();
    else if (!strcmp(app->configNs, "nes"))  nes_main();
    else if (!strcmp(app->configNs, "pce"))  pce_main();
    else if (!strcmp(app->configNs, "sms"))  sms_main();   // gg, col도 sms_main
    else if (!strcmp(app->configNs, "gw"))   gw_main();
    else if (!strcmp(app->configNs, "snes")) snes_main();
    else if (!strcmp(app->configNs, "lnx"))  lynx_main();
    else launcher_main();
    RG_PANIC("Never reached");
}

각 코어의 ESP32 종속 코드는 main_nes.c·main_gbc.c·main_snes.c 같은 main 파일에만 격리됩니다. 덕분에 에뮬레이터 본체(CPU 에뮬레이션)는 거의 그대로 두고, 디스플레이·오디오·입력만 retro-go API에 연결하면 이식이 끝납니다.

설계 ③ — 디스플레이 파이프라인: SPI + DMA + '바뀐 줄만' 전송

SPI로 240×320 화면을 매 프레임 통째로 보내면 대역폭이 모자랍니다. retro-go는 스캔라인마다 체크섬을 떠서, 직전 프레임과 같은 줄은 건너뛰고 바뀐 줄만 전송합니다(부분 갱신).

// rg_display.c — 줄 단위 체크섬으로 바뀐 줄만 그림
if (partial_update)
    checksum = rg_hash(line_buffer_ptr - draw_width, draw_width * 2);
if (screen_line_checksum[draw_top + y] != checksum) {
    screen_line_checksum[draw_top + y] = checksum;
    need_update = true;   // 이 줄만 다시 전송
}

설계 ④ — 크래시 복구: 재부팅해도 살아남는 RTC 메모리

임베디드의 명장면입니다. 패닉(크래시)이 나면 보통 화면도 시리얼도 못 쓰는데, retro-go는 재부팅해도 지워지지 않는 RTC RAM에 백트레이스를 쌓아 두었다가, 다음 부팅 때 SD카드에 crash.log로 저장합니다. 사용자가 케이블 없이 버그를 신고할 수 있죠.

// rg_system.c — 패닉 시 putchar를 가로채 RTC RAM에 누적
static RTC_NOINIT_ATTR panic_trace_t panicTrace;   // 재부팅해도 보존
IRAM_ATTR void esp_panic_putchar_hook(char c) {
    if (panicTrace.magicWord != RG_STRUCT_MAGIC)
        begin_panic_trace("esp_panic", NULL);
    logbuf_putc(&panicTrace, c);
}
// 부팅 시 매직워드가 살아 있으면 = 직전이 크래시 → SD에 저장 + 런처 복귀

설계 ⑤ — SPI 버스 공유: 화면·터치·SD카드가 한 줄을 나눠 쓴다 (NM-CYD-C5)

CYD 보드는 핀이 적어 디스플레이·터치·SD카드가 같은 SPI 버스를 쓰고 CS(칩 선택) 핀만 다릅니다. 문제는, 부팅 초기에 어떤 장치의 CS가 떠 있으면(floating) SD카드 초기화가 깨진다는 것. 해법은 부팅하자마자 모든 CS를 HIGH로 올려 버스 충돌을 막는 것입니다.

// targets/nm-cyd-c5/config.h — SPI 공유 버스 핀맵 (발췌)
#define RG_GPIO_LCD_MISO   GPIO_NUM_2
#define RG_GPIO_LCD_MOSI   GPIO_NUM_7
#define RG_GPIO_LCD_CLK    GPIO_NUM_6
#define RG_GPIO_LCD_CS     GPIO_NUM_23
#define RG_GPIO_SDSPI_CS   GPIO_NUM_10   // SD는 같은 MISO/MOSI/CLK, CS만 다름
#define NM_CYD_C5_TOUCH_CS GPIO_NUM_1

// 부팅 시 모든 CS를 HIGH로 (버스 충돌 방지)
#define RG_CUSTOM_PLATFORM_INIT()                             \
    gpio_set_direction(NM_CYD_C5_TOUCH_CS, GPIO_MODE_OUTPUT); \
    gpio_set_level(NM_CYD_C5_TOUCH_CS, 1);                    \
    gpio_set_pull_mode(RG_GPIO_SDSPI_MISO, GPIO_PULLUP_ONLY);

그리고 버튼이 없으니 터치 좌표를 9개 가상 버튼으로 매핑합니다 — 화면을 십자키·A·B·START 영역으로 나눈 표 하나로:

// targets/nm-cyd-c5/config.h — 저항막 터치 → 가상 게임패드
#define RG_GAMEPAD_TOUCH_MAP {\
  {RG_KEY_UP,     0,   0, 120,  70}, {RG_KEY_LEFT,   0,  50,  70, 170},\
  {RG_KEY_RIGHT, 70,  50, 140, 170}, {RG_KEY_DOWN,   0, 170, 120, 239},\
  {RG_KEY_B,    170,  90, 239, 179}, {RG_KEY_A,    240,  90, 319, 179},\
  {RG_KEY_MENU, 170,   0, 319,  59}, {RG_KEY_SELECT,140,180,229, 239},\
  {RG_KEY_START,230, 180, 319, 239},\
}

5디렉토리 구조 해부

"공통 라이브러리 1개 + 앱 여러 개 + 빌드 도구. 폴더 이름만 봐도 '추상화(components) / 화면(launcher) / 게임기(retro-core)'가 보인다."

가장 큰 파일이 말해 주는 것

rg_system.c(47KB)·rg_gui.c(84KB)가 가장 큰 건 "이 프로젝트의 진짜 핵심은 에뮬레이터가 아니라, 모든 앱이 공유하는 시스템 계층"이라는 뜻입니다. 부팅 조율·앱 전환·크래시 복구(rg_system)와 메뉴/위젯(rg_gui)이 무게중심이고, 에뮬레이터 코어들은 대부분 외부 프로젝트를 가져와 main 파일만 얹은 형태입니다. 즉 retro-go의 기여는 "에뮬레이터를 새로 짠 것"이 아니라 "여러 에뮬레이터를 작은 칩에서 굴리는 운영 계층을 만든 것"입니다.

6학습 포인트 (기술별 — 배울 것 + 실습 아이디어)

"한 레포 안에 임베디드 펌웨어·OTA·SPI 디스플레이·DMA·메모리 관리·에뮬레이터 내부가 전부 실물로 들어 있다."

① 멀티-앱 OTA 아키텍처

배울 것: 메모리가 부족한 MCU에서 큰 프로그램 여러 개를 운영하는 패턴 — 각 앱을 독립 펌웨어로 굽고 OTA 파티션 + 재부팅 점프로 전환, NVS로 상태(다음 게임)를 인계. ESP-IDF의 OTA가 원래는 무선 업데이트용 A/B 슬롯인데, 이를 앱 슬롯으로 전용하는 발상.

실습: ESP-IDF 예제로 "버튼을 누르면 otadata를 바꿔 다른 펌웨어로 재부팅"하는 최소 2-앱 프로젝트를 만들어, retro-go의 rg_system_switch_app을 축소 재현해 보기.

② 파티션 테이블 + 부트로더 + mkfw 패킹

배울 것: 플래시를 nvs/otadata/phy_init/app으로 나누는 파티션 테이블, 칩별 부트로더/테이블 오프셋(C5는 0x2000/0x8000), 그리고 esptool로 굽는 이미지 포맷. mkfw.py가 gen_esp32part.py 대신 직접 파티션을 배치하는 이유.

실습: 같은 펌웨어를 partitions.csv만 바꿔(앱 1개 vs 2개) 빌드해, otadata가 어떻게 부팅 대상을 고르는지 esptool.py read_flash로 들여다보기.

③ SPI 디스플레이 + DMA + 부분 갱신

배울 것: ST7789/ILI9341 같은 SPI TFT를 초기화·구동하는 법, DMA로 CPU를 안 거치고 픽셀을 보내는 법, 그리고 매 프레임 전체가 아닌 바뀐 줄만 보내는 체크섬 부분 갱신으로 대역폭을 아끼는 기법.

실습: ESP32+CYD로 ST7789에 컬러바를 띄운 뒤, "한 줄만 색을 바꾸고 그 줄만 다시 전송"하도록 만들어, 전체 전송 대비 프레임레이트가 얼마나 오르는지 측정.

④ SPI 버스 공유 (디스플레이·터치·SD)

배울 것: 핀이 부족할 때 여러 장치를 한 SPI 버스에 CS로 다중화하는 법, 그리고 floating CS가 SD 초기화를 깨뜨리는 실전 버그와 해법(부팅 시 모든 CS를 HIGH로). CYD류 보드를 다루면 반드시 만나는 함정.

실습: CYD에서 SD카드 마운트가 실패할 때, 터치 CS를 일부러 떠 있게 두면 재현되는지 확인하고, RG_CUSTOM_PLATFORM_INIT처럼 CS를 올려 고쳐 보기.

⑤ 메모리 관리 — PSRAM·버킷 할당자·CRC 캐시

배울 것: 내부 RAM과 PSRAM을 용도별로 나눠 쓰는 법(MEM_FAST 등), 수천 개 파일명을 strdup할 때 내부 RAM을 채우지 않으려는 버킷 할당자, 커버아트 매칭을 빠르게 하는 CRC 캐시 같은 임베디드 메모리 절약 패턴.

실습: 큰 SD카드의 롬 목록을 스캔하며 "각 파일명을 그냥 strdup vs 풀에 모아 할당"했을 때 내부 RAM 사용량 차이를 heap_caps_get_free_size로 비교.

⑥ 에뮬레이터 내부 — 여러 8/16비트 CPU

배울 것: 한 레포에서 6502(NES)·Z80(SMS)·65c816+SPC700(SNES)·H6280(PCE)·SM510(G&W) 구현체를 비교하며, CPU 에뮬레이션의 기본(명령 디코드·사이클 카운팅)과 카트리지 매퍼(뱅크 스위칭)를 플러그인 구조로 짜는 법(map000.c~map231.c).

실습: nofrendo의 매퍼 한 개(예 MMC1)를 읽고, "롬의 어느 부분을 어느 주소에 매핑하는가"를 그림으로 정리. 가장 단순한 NROM(map000)부터.

⑦ FreeRTOS 태스크 분리 + 더블버퍼

배울 것: 렌더·오디오·입력을 별도 태스크로 돌리고 큐로 잇는 법, 화면 깜빡임을 막는 더블버퍼(updates[2] + REDRAW 이벤트), 그리고 코어가 적은 칩(C5 싱글코어)에서 스케줄링 여유를 확보하는 고민.

실습: FreeRTOS로 "생산자(난수 생성) 태스크 + 소비자(화면 출력) 태스크"를 큐로 연결하고, 큐가 가득/비었을 때의 블로킹 동작을 관찰.

7하드웨어 / 시스템 요구사항

"클라우드·DB·GPU 전부 불필요. 대신 'PSRAM 달린 ESP32 보드'와 'microSD', 그리고 빌드용 ESP-IDF가 필수다."

8직접 해볼 수 있는 실습 과제

"보드에 구워 보기 → SPI 화면 띄우기 → 2-앱 OTA 점프 → 터치 가상패드 → 새 타겟 포팅."

9관련 기술 심화 학습 로드맵 (6주 플랜)

"ESP-IDF 기초에서 출발해 파티션·OTA·SPI 디스플레이·메모리·에뮬레이터까지, retro-go를 길잡이 삼아."

10핵심 키워드 사전

"이 문서와 저장소에서 반복되는 임베디드·ESP32·에뮬레이터 용어를 한곳에 모았다."

11참고 링크

• 이 포크(GitHub) — github.com/RockBase-iot/retro-go · 하드웨어 레포 RockBase-iot/NM-CYD-C5
• upstream 원본 — ducalex/retro-go · 커버아트 팩 ducalex/retro-go-covers
• TrendShift 라이브 멘션 — trendshift.io/repositories/62142
• ESP-IDF 문서 — docs.espressif.com/projects/esp-idf · SPI 공유(SD+LCD) sdspi_share
• 에뮬레이터 원본 — Snes9x · gwenesis · libretro-handy · HuExpress