# pspdev/psplinkusb architecture

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

- Interactive diagram: https://gitdiagram.com/pspdev/psplinkusb
- Repository: https://github.com/pspdev/psplinkusb

## Overview

##### Main components
- Core Functionality: At the heart is the PSPLINK application (the “psplink” directory) which contains the main code, configuration files, and interfaces (C and assembly modules) for managing connections, debugging, and other low-level operations.
- Libraries and Drivers: There are several libraries (for example, libpsplink, libusbhostfs, and their corresponding driver directories) that encapsulate lower-level functionality such as USB communication, kernel mode services (see psplink/kmode.S and others), and routines dealing with API hooks.
- Bootstrapping: The “bootstrap” directory contains startup code (like main.c) and resources (including configuration files like psplink.ini) that set up the environment before launching the core functionality.
- User Interfaces and Shells: The “psplink_user” and “pspsh” directories include code for user-side tools. “pspsh” in particular provides a command line interface that lets you interact with the PSP once a connection is established.
- Auxiliary Tools: The “tools” directory (with subdirectories such as debugmenu, echo, reboothook, remotejoy, and others) comprises various utility programs that either extend the functionality of PSPLINK or serve as additional debugging/experimental tools.
- Additional utilities like “sersh”, “ttylink”, “usbgdb”, “usbhostfs”, and “usbshell” indicate there’s a suite of applications around the core PSPLINK functionality, each handling aspects such as serial shell interactions, USB-based GDB stubs, and host filesystem access.

##### Relationships and interactions
- At runtime, the bootstrap code that resides in the “bootstrap” directory initiates the environment which then loads the main PSPLINK application.
- The core PSPLINK (in “psplink”) leverages the libraries (libpsplink, libusbhostfs, etc.) to interface with the PSP hardware via USB and to provide low-level debugging and communication capabilities.
- The user-facing tools (psplink_user, pspsh, etc.) build on the core functionalities to provide a debugging shell or to expose commands for troubleshooting.
- The suite of auxiliary tools (found under “tools”) appears to be built on top of the core libraries and possibly given different builds (often with their own Makefiles) that expose specific functionalities. Their placement and naming conventions (for instance, reboothook, remotejoy) indicate distinct functions that interact with or extend PSPLINK’s core capabilities.
- The GitHub workflows and Makefiles hint at a robust build and integration process, likely ensuring that all components (kernel modules, user space applications, and drivers) are compiled and linked properly.

##### Architectural patterns & design principles
- Modularity: The separation into distinct directories for libraries, drivers, main applications, and tools suggests a modular design where each module is built, tested, and maintained separately.
- Layered structure: There is a clear separation between low-level modules (assembly routines, drivers) and higher-level tools (command-line shells and debugging utilities).
- Extensibility: With a variety of auxiliary tools and utilities, the design is set out to easily include additional functionalities or custom utilities.

##### Relevant technologies
- C & Assembly languages: Many files in the project (e.g., .c, .S) indicate the mix of C code and low-level assembly, necessary for tight hardware integration and performance.
- Build Automation: Use of Makefiles spread throughout the project and GitHub Actions workflows (in .github/workflows) speaks to an automated build/deployment process.
- PSPSDK Dependency: The README notes that PSPSDK is required, implying that several components depend on this SDK, which may provide pre-built libraries or headers supporting PSP-specific features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Build & Integration Tools"]:::build
    B["PSPSDK"]:::build
    C["Bootstrap (Startup Code & Configuration)"]:::bootstrap
    D["Core PSPLINK Application"]:::core

    subgraph "Libraries & Drivers"
        L1["libpsplink & Assembly Drivers"]:::libs
        L2["USB Host Filesystem Drivers"]:::libs
    end

    subgraph "User Interfaces & Shells"
        UI1["PSPSH Debug Shell"]:::ui
        UI2["PSPLINK User Tools"]:::ui
    end

    subgraph "Auxiliary Tools"
        T1["Utility Programs (Tools)"]:::tools
        T2["Serial Shell"]:::tools
        T3["USB-based GDB Stub"]:::tools
        T4["USB Host Filesystem Application (Target & PC)"]:::tools
        T5["USB Shell"]:::tools
    end

    A -->|"initializes"| C
    B -->|"provides"| C
    C -->|"launches"| D
    D <-->|"uses"| L1
    D <-->|"uses"| L2
    D -->|"supplies"| UI1
    D -->|"supplies"| UI2
    D -->|"integrates"| T1
    UI1 -->|"interfaces"| T2
    UI1 -->|"interfaces"| T3
    UI2 -->|"interfaces"| T1
    T1 -->|"extends"| T4
    T1 -->|"extends"| T5

    click D "https://github.com/pspdev/psplinkusb/tree/master/psplink/"
    click L1 "https://github.com/pspdev/psplinkusb/tree/master/libpsplink/"
    click L2 "https://github.com/pspdev/psplinkusb/tree/master/libusbhostfs/"
    click C "https://github.com/pspdev/psplinkusb/tree/master/bootstrap/"
    click UI1 "https://github.com/pspdev/psplinkusb/tree/master/pspsh/"
    click UI2 "https://github.com/pspdev/psplinkusb/tree/master/psplink_user/"
    click T1 "https://github.com/pspdev/psplinkusb/tree/master/tools/"
    click T2 "https://github.com/pspdev/psplinkusb/tree/master/sersh/"
    click T3 "https://github.com/pspdev/psplinkusb/tree/master/usbgdb/"
    click T4 "https://github.com/pspdev/psplinkusb/tree/master/usbhostfs/"
    click T5 "https://github.com/pspdev/psplinkusb/tree/master/usbshell/"
    click A "https://github.com/pspdev/psplinkusb/tree/master/.github/workflows/"

    classDef bootstrap fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef libs fill:#f08080,stroke:#333,stroke-width:2px;
    classDef ui fill:#ffebcd,stroke:#333,stroke-width:2px;
    classDef tools fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef build fill:#dda0dd,stroke:#333,stroke-width:2px;
```
