OXYGENHUB
# d69f9ef6bbac retro-remote-debug-controller / core / retro_control.h
5.3 KiB · Objective-C · last changed Contract 0.3.0: memory write (POST /mem) + audio drain (GET /audio) 3 months ago source blame history raw
1 
/* retro_control.h — portable emulator control server (see ../SPEC.md).
2 
 *
3 
 * A retro-platform emulator implements the small read-only backend below and
4 
 * calls retro_control_start(). The shared server (retro_control.c) owns the
5 
 * socket loop, HTTP parsing, PPM/JSON encoding, and control flow
6 
 * (pause / step / free-run). It always binds 127.0.0.1. Contract 0.1.0.
7 
 *
8 
 * Integration is three calls in the emulator's main loop:
9 
 *   retro_control_service();                 // once per iteration (cheap)
10 
 *   if (!retro_control_running()) { idle; }  // gate advancing the machine
11 
 *   ... run one instruction / frame ...
12 
 *   if (frame_completed) retro_control_on_frame();
13 
 *
14 
 * Threading: the server runs on its own thread but never touches machine state
15 
 * there. State-reading endpoints (/mem, /regs, /screenshot) are executed inside
16 
 * retro_control_service() ON THE EMULATOR THREAD, so every read is consistent.
17 
 * The backend callbacks are therefore called from the emulator thread (except
18 
 * get_frame_count, which the server may also read for /status — make it a plain
19 
 * atomic-ish counter read).
20 
 */
21 
#ifndef RETRO_CONTROL_H
22 
#define RETRO_CONTROL_H
23
24 
#include <stdint.h>
25 
#include <stddef.h>
26
27 
/* Highest contract the core implements. The server advertises the highest level
28 
 * whose backend callbacks are all present: 0.3.0 needs inject_key + write_mem +
29 
 * capture_audio; 0.2.0 needs inject_key; else 0.1.0. Keeps a partial backend
30 
 * honest. */
31 
#define RETRO_CONTROL_CONTRACT "0.3.0"
32
33 
/* Native framebuffer pixel layout; the server swizzles to PPM RGB. */
34 
typedef enum {
35 
    RETRO_PIX_RGB888 = 0,   /* 3 bytes/px: R,G,B                       */
36 
    RETRO_PIX_RGBA8888,     /* 4 bytes/px: R,G,B,A                     */
37 
    RETRO_PIX_BGRA8888      /* 4 bytes/px: B,G,R,A (x16 framebuffer)   */
38 
} retro_pix_fmt_t;
39
40 
typedef struct {
41 
    const uint8_t *pixels;  /* start of the current complete frame     */
42 
    int width;
43 
    int height;
44 
    retro_pix_fmt_t fmt;
45 
} retro_framebuffer_t;
46
47 
/* Key action for inject_key (0.2). */
48 
typedef enum {
49 
    RETRO_KEY_TAP  = 0,   /* press then release */
50 
    RETRO_KEY_DOWN = 1,   /* press / hold       */
51 
    RETRO_KEY_UP   = 2    /* release            */
52 
} retro_key_action_t;
53
54 
/* The emulator implements these. Any may be NULL: the matching endpoint then
55 
 * returns 501 Not Implemented. */
56 
typedef struct retro_control_backend {
57 
    const char *platform;   /* "x16" | "neo6502" | "agon" | ...        */
58 
    const char *emulator;   /* human name, e.g. "x16emu"               */
59
60 
    /* Debug-read up to min(len, out_cap) bytes at addr into out, side-effect
61 
     * free. bank is the optional bank selector (<0 = current bank). Returns the
62 
     * number of bytes written. */
63 
    uint32_t (*read_mem)(uint32_t addr, int32_t bank, uint32_t len,
64 
                         uint8_t *out, uint32_t out_cap);
65
66 
    /* Write a JSON object of registers into buf (NUL-terminated). */
67 
    void (*get_regs_json)(char *buf, size_t cap);
68
69 
    /* Report the current complete-frame framebuffer. */
70 
    void (*get_framebuffer)(retro_framebuffer_t *out);
71
72 
    /* Monotonic completed-frame counter. */
73 
    uint64_t (*get_frame_count)(void);
74
75 
    /* 0.2: inject a key. is_text=1 => `value` is a character code point;
76 
     * is_text=0 => `value` is a raw platform key code. `action` is a
77 
     * retro_key_action_t. Return 1 on success, 0 if unmappable (server -> 400).
78 
     * NULL => /key returns 501 and the server advertises contract 0.1.0. */
79 
    int (*inject_key)(int is_text, uint32_t value, int action);
80
81 
    /* 0.2: soft/cold reset the machine. NULL => /reset returns 501. */
82 
    void (*reset)(void);
83
84 
    /* 0.3: write len bytes from `in` at addr (debug/state poke; bank<0 =
85 
     * current). Intended for RAM/state — I/O-register writes may trigger device
86 
     * side effects. Return bytes written. NULL => POST /mem returns 501. */
87 
    uint32_t (*write_mem)(uint32_t addr, int32_t bank, uint32_t len,
88 
                          const uint8_t *in);
89
90 
    /* 0.3: drain up to `cap` interleaved signed-16-bit audio samples the
91 
     * emulator has synthesised since the last call into `out`; set *rate and
92 
     * *channels; set *dropped to samples lost to overflow since the last drain.
93 
     * Return the number of int16 samples written. NULL => /audio returns 501. */
94 
    uint32_t (*capture_audio)(int16_t *out, uint32_t cap,
95 
                              int *rate, int *channels, uint32_t *dropped);
96 
} retro_control_backend_t;
97
98 
/* Start the server thread bound to 127.0.0.1:port. Non-blocking; 0 on success,
99 
 * negative on error. backend must outlive the server. */
100 
int  retro_control_start(int port, const retro_control_backend_t *backend);
101
102 
/* Drain a pending control request. Call once per main-loop iteration, at an
103 
 * instruction/frame boundary. Cheap no-op when idle and when control is off. */
104 
void retro_control_service(void);
105
106 
/* Nonzero => the machine should advance this iteration. Returns 1 always when
107 
 * control is off or the machine is free-running; 0 when paused with no steps
108 
 * left. */
109 
int  retro_control_running(void);
110
111 
/* Call when a video frame completes. Drives /step (decrements the step budget,
112 
 * halts and answers when it reaches zero). No-op when control is off. */
113 
void retro_control_on_frame(void);
114
115 
/* Stop the server (optional; process exit is fine too). */
116 
void retro_control_stop(void);
117
118 
#endif /* RETRO_CONTROL_H */