Architecture
Architecture
Section titled “Architecture”This document describes the technical architecture of ryu_ldn_nx.
Overview
Section titled “Overview”┌──────────────────────────────────────────────────────────────────┐│ Nintendo Switch │├──────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────┐ ┌──────────────────────┐ ││ │ Game │◀──── IPC ───────▶│ ryu_ldn_nx │ ││ │ (ldn:u API) │ │ sysmodule │ ││ └─────────────┘ │ │ ││ │ ┌────────────────┐ │ ││ │ │ LdnMitMService │ │ ││ │ │ (MITM ldn:u) │ │ ││ │ └───────┬────────┘ │ ││ │ │ │ ││ │ ┌───────▼────────┐ │ ││ │ │ NetworkClient │ │ ││ │ │ (TCP + RyuLdn) │ │ ││ │ └───────┬────────┘ │ ││ └──────────┼───────────┘ ││ │ ││ ┌─────────────────┐ │ ││ │ Tesla Overlay │◀──── IPC ────────────────┤ ││ │ (status/config) │ │ ││ └─────────────────┘ │ ││ │ │└────────────────────────────────────────────────┼─────────────────┘ │ ▼ TCP/IP ┌───────────────────┐ │ Ryujinx LDN │ │ Server │ └───────────────────┘Components
Section titled “Components”Sysmodule
Section titled “Sysmodule”The main component that runs in the background on the Switch.
LdnMitMService
Section titled “LdnMitMService”Atmosphere MITM service that intercepts ldn:u IPC calls:
- Registers with Service Manager
- Creates
LdnICommunicationsessions - Forwards non-LDN calls to original service
class LdnMitMService { Result CreateUserLocalCommunicationService(...); static bool ShouldMitm(...);};LdnICommunication
Section titled “LdnICommunication”Handles individual game sessions:
- Manages LDN state machine
- Converts LDN API to network operations
- Routes game data through server
class LdnICommunication { // Lifecycle Result Initialize(); Result Finalize();
// Host (Access Point) Result OpenAccessPoint(); Result CreateNetwork();
// Client (Station) Result OpenStation(); Result Scan(); Result Connect();};NetworkClient
Section titled “NetworkClient”Manages TCP connection to the server:
- Connection establishment
- RyuLdn protocol encoding/decoding
- Automatic reconnection
class NetworkClient { Result Connect(); Result SendPacket(RyuLdnPacket&); void ProcessIncoming();};Protocol
Section titled “Protocol”RyuLdn protocol implementation:
- Binary packet format
- Game data proxy messages
- Session management messages
namespace ryu_ldn::protocol { void encode_create_access_point(...); void encode_scan(...); void encode_proxy_data(...);}Tesla Overlay
Section titled “Tesla Overlay”User interface component:
- Displays connection status
- Shows session information
- Allows configuration changes
class RyuLdnOverlay : public tsl::Overlay { void initServices(); void exitServices();};Overlay IPC
Section titled “Overlay IPC”Custom IPC service for overlay communication:
- Commands 65001-65010 on ldn:u MITM
- Read-only status queries
- Configuration changes
class LdnConfigService { Result GetVersion(...); Result GetConnectionStatus(...); Result GetSessionInfo(...); Result ForceReconnect();};Data Flow
Section titled “Data Flow”Creating a Network (Host)
Section titled “Creating a Network (Host)”Game LdnICommunication NetworkClient Server │ │ │ │ │── Initialize() ──────────▶│ │ │ │ │ │ │ │── OpenAccessPoint() ─────▶│── Connect() ────────────▶│── TCP Connect ────▶│ │ │ │◀── Connected ──────│ │ │ │ │ │── CreateNetwork(cfg) ────▶│── SendCreateAP() ───────▶│── CreateAP msg ───▶│ │ │ │◀── CreateAP OK ────│ │◀── Success ───────────────│ │ │ │ │ │ │Joining a Network (Client)
Section titled “Joining a Network (Client)”Game LdnICommunication NetworkClient Server │ │ │ │ │── OpenStation() ─────────▶│── Connect() ────────────▶│── TCP Connect ────▶│ │ │ │◀── Connected ──────│ │ │ │ │ │── Scan(filter) ──────────▶│── SendScan() ───────────▶│── Scan msg ───────▶│ │ │ │◀── ScanResult ─────│ │◀── Networks[] ────────────│ │ │ │ │ │ │ │── Connect(network) ──────▶│── SendConnect() ────────▶│── Connect msg ────▶│ │ │ │◀── Connected ──────│ │◀── Success ───────────────│ │ │Game Data Proxy
Section titled “Game Data Proxy”Game A ryu_ldn_nx Server Game B │ │ │ │ │── SendData(B, data) ────▶│── ProxyData(B) ─────▶│── ProxyData(B) ──────▶│ │ │ │ │ │ │◀── ProxyData(A) ─────│◀── ProxyData(A) ──────│ │◀── RecvData(A, data) ────│ │ │Threading Model
Section titled “Threading Model”Main Thread (ServerManager)├── IPC request handling├── LdnMitMService└── LdnICommunication
Network Thread (per session)├── TCP socket I/O├── Packet processing└── Callback invocation
State events signaled cross-thread via os::SystemEventMemory Management
Section titled “Memory Management”- Fixed-size packet buffers (MTU-based)
- Ring buffers for proxy data
- No dynamic allocation in hot paths
- RAII for resource cleanup
Error Handling
Section titled “Error Handling”- Atmosphere Result codes for IPC
- Automatic reconnection on network errors
- State machine prevents invalid operations
- Graceful degradation on server issues