Add claude docs

2026-06-16 10:15:59 -05:00
parent 8131bcd4d4
commit ed5c60ac30
32 changed files with 3781 additions and 13 deletions
@@ -0,0 +1,132 @@
+# Network System
+
+Source: `src/dusk/network/`, platform layers in
+`src/dusk<platform>/network/`
+
+## Overview
+
+The network system provides a platform-agnostic API for detecting and
+managing a network connection. Higher-level functionality (HTTP, sockets)
+is not yet implemented in any platform. The system handles the
+connection lifecycle -- connect, detect disconnect, disconnect -- and
+reports the current IP address.
+
+## Implementation status by platform
+
+| Platform | Connection | IP info | HTTP/Requests | Notes |
+|----------|-----------|---------|--------------|-------|
+| **Linux** | Auto (OS) | IPv4 + IPv6 | Not implemented | `getifaddrs()` |
+| **Knulli** | Auto (OS) | IPv4 + IPv6 | Not implemented | same as Linux |
+| **PSP** | Manual dialog | IPv4 only | Not implemented | `sceUtilityNetconf`; SSL/HTTP modules commented out |
+| **GameCube** | Manual DHCP | IPv4 only | Not implemented | `if_config()` stubbed; `net_init()` commented out |
+| **Wii** | Manual DHCP | IPv4 only | Not implemented | blocking `if_config()` via System Menu Wi-Fi settings |
+
+## Connection states
+
+```c
+typedef enum {
+  NETWORK_STATE_DISCONNECTED,
+  NETWORK_STATE_CONNECTING,
+  NETWORK_STATE_CONNECTED,
+  NETWORK_STATE_DISCONNECTING,
+} networkstate_t;
+```
+
+## Global state
+
+```c
+extern network_t NETWORK;
+// NETWORK.state         -- current connection state
+// NETWORK.platform      -- platform-specific data
+// NETWORK.onDisconnect  -- callback fired on unexpected disconnect
+```
+
+## Core API (`network.h`)
+
+```c
+errorret_t networkInit();
+errorret_t networkUpdate();   // call each frame; detects dropped connections
+errorret_t networkDispose();
+
+bool_t networkIsConnected();
+
+void networkRequestConnection(
+  void (*onConnected)(void *user),
+  void (*onFailed)(errorret_t error, void *user),
+  void (*onDisconnect)(errorret_t error, void *user),
+  void *user
+);
+
+void networkRequestDisconnection(
+  void (*onComplete)(void *user),
+  void *user
+);
+```
+
+On platforms that manage their own connection (Linux, macOS, Windows),
+`networkRequestConnection` immediately calls `onConnected` if a network
+interface is up, or `onFailed` if not. No `networkPlatformRequestConnection`
+macro is needed.
+
+On platforms that require explicit connection (PSP, Wii), the platform
+implements `networkPlatformRequestConnection` and
+`networkPlatformRequestDisconnection`.
+
+## Network info
+
+```c
+networkinfo_t networkGetInfo();
+// Only valid when NETWORK.state == NETWORK_STATE_CONNECTED.
+```
+
+```c
+typedef struct {
+  networktype_t type;   // NETWORK_TYPE_IPV4 or (ifdef) NETWORK_TYPE_IPV6
+  union {
+    networkinfoipv4_t ipv4;  // uint8_t ip[4]
+    networkinfoipv6_t ipv6;  // uint8_t ip[16] (requires DUSK_NETWORK_IPV6)
+  };
+} networkinfo_t;
+```
+
+IPv6 support requires the `DUSK_NETWORK_IPV6` compile-time define.
+
+## Platform-specific notes
+
+### Linux / Knulli
+
+Fully functional for connection detection and IP querying. No explicit
+connect/disconnect step needed -- the OS manages the interface. Uses
+`getifaddrs()` to find the first non-loopback running interface.
+
+### PSP
+
+Connection is asynchronous and driven by a state machine in
+`networkPSPUpdate()`. The PSP shows the built-in network configuration
+dialog (`sceUtilityNetconfInitStart`) to let the user pick a Wi-Fi
+access point.
+
+HTTP/SSL modules (`psphttp`, `pspssl`) are loaded in commented-out code
+-- the infrastructure for HTTP exists but is disabled.
+
+### GameCube
+
+`net_init()` is commented out. Networking on GameCube is non-functional
+in the current build.
+
+### Wii
+
+Uses `if_config()` (DHCP via libogc) to connect using the Wi-Fi settings
+stored in Wii System Menu. This call **blocks** the main thread. The
+connection only works when `DUSK_WII` is defined; the GameCube path
+always fails.
+
+## Adding a new platform implementation
+
+1. Create `src/dusk<platform>/network/network<platform>.h/.c`.
+2. Implement the five required functions:
+   `Init`, `Update`, `Dispose`, `IsConnected`, `GetInfo`.
+3. Optionally implement `RequestConnection` and `RequestDisconnection`
+   if the platform requires an explicit connection step.
+4. Create `networkplatform.h` mapping each `networkPlatform*` macro to
+   your functions, and defining `networkplatform_t`.