# xrip/sg1000-multicart architecture

> Architecture diagram of the GitHub repository xrip/sg1000-multicart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xrip/sg1000-multicart
- Repository: https://github.com/xrip/sg1000-multicart

## Overview

##### Project Type & Purpose
- This is an embedded firmware project aimed at implementing a multicart for Sega SG-1000, Mark III, and Master System consoles.
- The system uses an RP2040 microcontroller to interface directly with the console’s address and data buses. A built‐in menu system allows the user to select ROMs for play, and bank switching is used for handling game data larger than 16KB.
- There are distinct modules for menu handling, ROM banking/console interface routines, and supporting libraries like FATFS (presumably for file system routines or legacy support).

##### Analyzing the File Structure
- Top-level files like CMakeLists.txt, memmap_sd1000.ld, and sega_cart.c define the core firmware.
- The “fatfs” directory holds files such as diskio.c/h, ff.c/h, ffconf.h, ffsystem.c, and ffunicode.c. This indicates that the FATFS module is incorporated – either for a file system component on storage (for instance, SD card access) or for handling ROM image data conversion.
- The “menu” directory contains files like menu.c, a Makefile, bin2c.py, font.h, menu.sg, and sega_logo.h. This suggests that there is a dedicated module for the game selection menu, perhaps even compiled as a separate ROM that is integrated into the project using devkitSMS.
- The “roms” directory includes a Python script (make.py) which processes ROM files (from sources like .sg or .sms files), converting binary data into C arrays and generating a header (roms.h) used by the application.

##### Reviewing the README for Architectural Insights
- The README explains that the RP2040 connects directly to the console’s address bus (A0-A15), data bus (D0-D7), and control lines (MEMR, MEMW, etc.) through designated GPIO pins.
- It details the ROM bank switching mechanism to support multiple game cartridges.
- There is an explanation of the menu system which relies on the processing of ROM files and the generation of a header file.
- The hardware requirements and pin connections are clearly illustrated in the README, signifying a tight coupling between the hardware interface and the firmware logic.

##### Main Components
a. Hardware Interface:
- RP2040 Microcontroller (central component)
- GPIO Ports mapped:
– GPIO 0-15 → Address Lines (A0-A15)
– GPIO 16-23 → Data Lines (D0-D7)
– GPIO 24-29 → Control Signals (MEMR, MEMW, MREQ, etc.)
- Sega Console Bus where the memory requests originate.
- External passive components and any associated wiring/peripherals (such as buttons for game selection).

b. Software/Firmware Modules:
- Console Interface Module (sega_cart.c and related routines) that monitors bus requests and handles ROM data transfer.
- ROM Banking Module that implements bank switching via addresses 0xFFFD, 0xFFFE, and 0xFFFF.
- Menu Module (menu/menu.c, menu.sg, font.h, sega_logo.h) that provides game selection through the on-screen menu.
- ROM Data Preparation & Integration:
- Python Script in “roms” (make.py) that converts ROM files into a C header file (roms.h) with the required metadata and binary arrays.
- FATFS Library (all files in the “fatfs” folder) – if used at runtime, it will handle file system operations; if only for preprocessing, note this as a supporting library.
- Build & Deployment Components:
- CMakeLists.txt (for Pico SDK build process)
- Makefile in menu/ for devkitSMS-based build of the menu ROM.

##### Relationships and Data Flow
- The RP2040 is the hub, handling console memory requests and interfacing with the ROM banks.
- When the console initiates a memory access, the firmware (in sega_cart.c) identifies the correct ROM bank based on the current selection.
- The menu system (menu module) allows the user to choose a game, which then instructs the firmware to reconfigure bank switching.
- The Python script in the “roms” folder ensures that the ROM binary data is formatted as C arrays for compilation into the firmware.
- Both build systems (CMake and Makefiles) are used during the development to compile different firmware segments and generate the final UF2 file for flashing onto the RP2040.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Interface
    subgraph "Hardware Interface"
        B2["Sega Console Bus"]:::hardware
        B1["RP2040 Microcontroller\n(GPIO: A0-A15, D0-D7, Control)"]:::hardware
        B3["External Peripherals\n(Buttons, etc.)"]:::hardware
    end

    %% Firmware Modules
    subgraph "Firmware Modules"
        F1["Console Interface & ROM Banking\n(sega_cart.c)"]:::firmware
        F2["Menu System\n(menu/menu.c)"]:::firmware
        F3["ROM Data Preparation\n(roms/make.py)"]:::utility
        F4["FATFS Library\n(fatfs/)"]:::utility
    end

    %% Build & Deployment Components
    subgraph "Build & Deployment"
        D1["Build System\n(CMakeLists.txt)"]:::build
        D2["Menu Build\n(Makefile)"]:::build
    end

    %% Hardware Connections
    B2 -->|"BusRequest"| B1
    B3 -->|"UserInput"| B1

    %% Firmware Data Flow
    B1 -->|"HandlesConsoleRequest"| F1
    F2 -->|"GameSelect-BankSwitch"| F1
    F3 -->|"GeneratesROMData"| F1
    F4 -->|"FSOperations"| F1

    %% Build System Compilation Flow
    D1 --> F1
    D1 --> F2
    D1 --> F3
    D1 --> F4
    D2 --> F2

    %% Click Events
    click F1 "https://github.com/xrip/sg1000-multicart/blob/master/sega_cart.c"
    click B1 "https://github.com/xrip/sg1000-multicart/blob/master/memmap_sd1000.ld"
    click F2 "https://github.com/xrip/sg1000-multicart/blob/master/menu/menu.c"
    click F3 "https://github.com/xrip/sg1000-multicart/blob/master/roms/make.py"
    click F4 "https://github.com/xrip/sg1000-multicart/tree/master/fatfs/"
    click D1 "https://github.com/xrip/sg1000-multicart/blob/master/CMakeLists.txt"

    %% Style Definitions
    classDef hardware fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef firmware fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef utility fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef build fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
