unkernel 0.0.0 → 0.1.0-261115-75add72
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +340 -0
- package/LICENSE-MIT +21 -0
- package/README.md +546 -0
- package/dist/_chunks/core.mjs +9635 -0
- package/dist/_chunks/index.d.mts +3844 -0
- package/dist/_chunks/node.mjs +510 -0
- package/dist/cli.d.mts +1 -0
- package/dist/cli.mjs +524 -0
- package/dist/node.d.mts +103 -0
- package/dist/node.mjs +8 -0
- package/dist/unkernel-alpine.wasm +0 -0
- package/dist/web.d.mts +143 -0
- package/dist/web.mjs +431 -0
- package/package.json +69 -2
|
@@ -0,0 +1,3844 @@
|
|
|
1
|
+
/** DRM fourcc of XRGB8888 ("XR24"): 32-bit pixels, little endian B, G, R, X. */
|
|
2
|
+
export declare const FOURCC_XRGB8888 = 875713112;
|
|
3
|
+
export interface DisplayMode {
|
|
4
|
+
width: number;
|
|
5
|
+
height: number;
|
|
6
|
+
/** Bytes per row. */
|
|
7
|
+
stride: number;
|
|
8
|
+
/** DRM fourcc; only FOURCC_XRGB8888 so far. */
|
|
9
|
+
format: number;
|
|
10
|
+
}
|
|
11
|
+
/** A copy of the frame, RGBA (the layout of canvas ImageData). */
|
|
12
|
+
export interface DisplayFrame {
|
|
13
|
+
width: number;
|
|
14
|
+
height: number;
|
|
15
|
+
data: Uint8ClampedArray;
|
|
16
|
+
}
|
|
17
|
+
/** A display size in pixels. */
|
|
18
|
+
export interface DisplaySize {
|
|
19
|
+
width: number;
|
|
20
|
+
height: number;
|
|
21
|
+
/**
|
|
22
|
+
* Pixels per inch of this size on the host's screen (a browser's CSS
|
|
23
|
+
* pixels: 96). With it the guest learns the physical size of its picture
|
|
24
|
+
* (fb_var_screeninfo width and height, in mm), scaled to fit this area
|
|
25
|
+
* when the mode differs from it. Default: unknown.
|
|
26
|
+
*/
|
|
27
|
+
dpi?: number;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The display option: false (none), true (640x480), a size, or a function
|
|
31
|
+
* that returns the size wanted each time a program first opens /dev/fb0.
|
|
32
|
+
*/
|
|
33
|
+
export type DisplayOption = boolean | DisplaySize | (() => DisplaySize);
|
|
34
|
+
export declare const DEFAULT_DISPLAY_SIZE: DisplaySize;
|
|
35
|
+
export interface DisplayHostOptions {
|
|
36
|
+
/** Offer a display to the kernel, and the size wanted. Default false: no /dev/fb0. */
|
|
37
|
+
enabled?: DisplayOption;
|
|
38
|
+
/** The kernel's memory, read at call time. */
|
|
39
|
+
memory: () => WebAssembly.Memory;
|
|
40
|
+
/** A program opened the display (mode), or the last one closed it (null). */
|
|
41
|
+
onChange?: (mode: DisplayMode | null) => void;
|
|
42
|
+
log?: (msg: string) => void;
|
|
43
|
+
}
|
|
44
|
+
/** What a machine snapshot keeps of the display (DisplayHost.saveState()). */
|
|
45
|
+
interface DisplaySnapshot {
|
|
46
|
+
/** Address of the pixels in kernel memory, 0 while detached. */
|
|
47
|
+
addr: number;
|
|
48
|
+
mode: DisplayMode | null;
|
|
49
|
+
/** The size last offered to the kernel (for the physical size). */
|
|
50
|
+
offered: DisplaySize | null;
|
|
51
|
+
}
|
|
52
|
+
export interface DisplayStats {
|
|
53
|
+
/** wasm_driver_fb_attach() calls with pixels. */
|
|
54
|
+
attaches: number;
|
|
55
|
+
/** ... and without (the last close). */
|
|
56
|
+
detaches: number;
|
|
57
|
+
}
|
|
58
|
+
export declare class DisplayHost {
|
|
59
|
+
#private;
|
|
60
|
+
readonly enabled: boolean;
|
|
61
|
+
/** Address of the pixels in kernel memory; 0 while nothing has /dev/fb0 open. */
|
|
62
|
+
addr: number;
|
|
63
|
+
/** The mode while attached, else null. */
|
|
64
|
+
mode: DisplayMode | null;
|
|
65
|
+
/** Did the kernel ask (wasm_driver_fb_init)? False for a kernel without kwfb. */
|
|
66
|
+
probed: boolean;
|
|
67
|
+
stats: DisplayStats;
|
|
68
|
+
constructor(opts: DisplayHostOptions);
|
|
69
|
+
imports(): Record<string, unknown>;
|
|
70
|
+
/** The state a snapshot keeps (the pixels are in the kernel's memory). */
|
|
71
|
+
saveState(): DisplaySnapshot;
|
|
72
|
+
/**
|
|
73
|
+
* A restored snapshot: the kernel does not ask init or attach again, so
|
|
74
|
+
* take the saved attachment and tell onChange, as an attach would.
|
|
75
|
+
*/
|
|
76
|
+
restoreState(s: DisplaySnapshot): void;
|
|
77
|
+
/**
|
|
78
|
+
* The guest's pixels in place (no copy): `mode.height` rows of
|
|
79
|
+
* `mode.stride` bytes, XRGB8888. Null while detached. Valid only until
|
|
80
|
+
* the kernel runs again (the program may close the device and the
|
|
81
|
+
* kernel reuse the memory), so read it at once and do not keep it.
|
|
82
|
+
*/
|
|
83
|
+
pixels(): Uint8Array | null;
|
|
84
|
+
/**
|
|
85
|
+
* Copy the current frame as RGBA (alpha 255), e.g. for
|
|
86
|
+
* `new ImageData(frame.data, frame.width)`. `out` is reused when it has
|
|
87
|
+
* the right size. Null while detached.
|
|
88
|
+
*/
|
|
89
|
+
readRGBA(out?: Uint8ClampedArray): DisplayFrame | null;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Convert packed XRGB8888 rows (`width * 4` bytes each, as worker mode
|
|
93
|
+
* sends frames) to RGBA with alpha 255. `out` is reused when it has the
|
|
94
|
+
* right size.
|
|
95
|
+
*/
|
|
96
|
+
export declare function xrgbToRgba(src: Uint8Array, width: number, height: number, out?: Uint8ClampedArray): Uint8ClampedArray;
|
|
97
|
+
/** A frame as a binary PPM (P6) image. */
|
|
98
|
+
export declare function frameToPpm(frame: DisplayFrame): Uint8Array;
|
|
99
|
+
export declare const EV_SYN = 0;
|
|
100
|
+
export declare const EV_KEY = 1;
|
|
101
|
+
export declare const EV_REL = 2;
|
|
102
|
+
export declare const EV_ABS = 3;
|
|
103
|
+
export declare const REL_X = 0;
|
|
104
|
+
export declare const REL_Y = 1;
|
|
105
|
+
export declare const REL_WHEEL = 8;
|
|
106
|
+
export declare const ABS_X = 0;
|
|
107
|
+
export declare const ABS_Y = 1;
|
|
108
|
+
/** The tablet's ABS_X/ABS_Y range is 0..ABS_MAX. */
|
|
109
|
+
export declare const ABS_MAX = 32767;
|
|
110
|
+
export declare const BTN_LEFT = 272;
|
|
111
|
+
export declare const BTN_RIGHT = 273;
|
|
112
|
+
export declare const BTN_MIDDLE = 274;
|
|
113
|
+
/** kwinput device numbers (the bits of the open mask). */
|
|
114
|
+
export declare const INPUT_KEYBOARD = 0;
|
|
115
|
+
export declare const INPUT_MOUSE = 1;
|
|
116
|
+
export declare const INPUT_TABLET = 2;
|
|
117
|
+
/** Which kwinput devices some guest program has open. */
|
|
118
|
+
export interface InputState {
|
|
119
|
+
keyboard: boolean;
|
|
120
|
+
/** The relative mouse. */
|
|
121
|
+
mouse: boolean;
|
|
122
|
+
/** The absolute pointer (tablet). A kernel without it never sets this. */
|
|
123
|
+
tablet: boolean;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* The evdev injection surface: InputHost inline, and in worker mode a
|
|
127
|
+
* mirror on the owner's thread that forwards each call to the worker's
|
|
128
|
+
* InputHost (worker-devices.ts). Return values say whether the guest gets
|
|
129
|
+
* the event (in worker mode: as far as this thread knows the open state).
|
|
130
|
+
*/
|
|
131
|
+
export interface Evdev {
|
|
132
|
+
/** Open mask: bit INPUT_KEYBOARD, INPUT_MOUSE, INPUT_TABLET. */
|
|
133
|
+
readonly mask: number;
|
|
134
|
+
readonly keyboardOpen: boolean;
|
|
135
|
+
readonly mouseOpen: boolean;
|
|
136
|
+
readonly tabletOpen: boolean;
|
|
137
|
+
readonly state: InputState;
|
|
138
|
+
key(code: number, down: boolean): boolean;
|
|
139
|
+
button(code: number, down: boolean): boolean;
|
|
140
|
+
move(dx: number, dy: number): boolean;
|
|
141
|
+
wheel(clicks: number): boolean;
|
|
142
|
+
moveTo(x: number, y: number): boolean;
|
|
143
|
+
tabletButton(code: number, down: boolean): boolean;
|
|
144
|
+
tabletWheel(clicks: number): boolean;
|
|
145
|
+
releaseAll(): void;
|
|
146
|
+
}
|
|
147
|
+
export interface InputHostOptions {
|
|
148
|
+
/** Offer the devices (the kernel registers them only then). Default false. */
|
|
149
|
+
enabled?: boolean;
|
|
150
|
+
/** The kernel's memory, read at call time. */
|
|
151
|
+
memory: () => WebAssembly.Memory;
|
|
152
|
+
/** Set IRQ_INPUT and wake the kernel. */
|
|
153
|
+
raise: () => void;
|
|
154
|
+
/** The open state changed. */
|
|
155
|
+
onChange?: (state: InputState) => void;
|
|
156
|
+
}
|
|
157
|
+
/** What a machine snapshot keeps of kwinput (InputHost.saveState()). */
|
|
158
|
+
interface InputSnapshot {
|
|
159
|
+
/** Open mask. */
|
|
160
|
+
mask: number;
|
|
161
|
+
/** Keys and buttons the guest saw pressed. */
|
|
162
|
+
keys: number[];
|
|
163
|
+
buttons: number[];
|
|
164
|
+
tabletButtons: number[];
|
|
165
|
+
/** Events the guest had not read yet, flat: device, type, code, value. */
|
|
166
|
+
queue: number[];
|
|
167
|
+
}
|
|
168
|
+
export interface InputStats {
|
|
169
|
+
/** Events the kernel took. */
|
|
170
|
+
delivered: number;
|
|
171
|
+
/** Presses and motion dropped because no program had the device open, or the queue was full. */
|
|
172
|
+
dropped: number;
|
|
173
|
+
}
|
|
174
|
+
export declare class InputHost implements Evdev {
|
|
175
|
+
#private;
|
|
176
|
+
readonly enabled: boolean;
|
|
177
|
+
/** Did the kernel ask (wasm_driver_input_init)? False for a kernel without kwinput. */
|
|
178
|
+
probed: boolean;
|
|
179
|
+
/** Open mask from the kernel: bit INPUT_KEYBOARD, INPUT_MOUSE, INPUT_TABLET. */
|
|
180
|
+
mask: number;
|
|
181
|
+
stats: InputStats;
|
|
182
|
+
constructor(opts: InputHostOptions);
|
|
183
|
+
/** Some program has the keyboard open. */
|
|
184
|
+
get keyboardOpen(): boolean;
|
|
185
|
+
/** Some program has the mouse open. */
|
|
186
|
+
get mouseOpen(): boolean;
|
|
187
|
+
/** Some program has the absolute pointer (tablet) open. */
|
|
188
|
+
get tabletOpen(): boolean;
|
|
189
|
+
get state(): InputState;
|
|
190
|
+
/**
|
|
191
|
+
* Press (down = true) or release a key, by Linux key code (see
|
|
192
|
+
* domCodeToLinux()). Returns whether the guest gets it: a press only
|
|
193
|
+
* while the keyboard is open, a release only of a key it saw pressed.
|
|
194
|
+
* Repeats of a held key are ignored (the device has no EV_REP).
|
|
195
|
+
*/
|
|
196
|
+
key(code: number, down: boolean): boolean;
|
|
197
|
+
/** Press or release a mouse button (BTN_LEFT, BTN_RIGHT, BTN_MIDDLE); like key(). */
|
|
198
|
+
button(code: number, down: boolean): boolean;
|
|
199
|
+
/** Relative pointer motion in pixels (rounded); dropped while the mouse is closed. */
|
|
200
|
+
move(dx: number, dy: number): boolean;
|
|
201
|
+
/** Wheel clicks: positive = away from the user (up), as REL_WHEEL. */
|
|
202
|
+
wheel(clicks: number): boolean;
|
|
203
|
+
/**
|
|
204
|
+
* Move the absolute pointer to (x, y), normalised: 0..1 from the left
|
|
205
|
+
* and top edges of the picture (clamped). For a pixel px of a mode
|
|
206
|
+
* `width` wide, x = (px + 0.5) / width lands on it. Dropped while the
|
|
207
|
+
* tablet is closed.
|
|
208
|
+
*/
|
|
209
|
+
moveTo(x: number, y: number): boolean;
|
|
210
|
+
/** Press or release a button of the absolute pointer; like button(). */
|
|
211
|
+
tabletButton(code: number, down: boolean): boolean;
|
|
212
|
+
/** Wheel clicks on the absolute pointer; like wheel(). */
|
|
213
|
+
tabletWheel(clicks: number): boolean;
|
|
214
|
+
/** Release every key and button the guest saw pressed (e.g. when the page loses focus). */
|
|
215
|
+
releaseAll(): void;
|
|
216
|
+
/** The state a snapshot keeps. */
|
|
217
|
+
saveState(): InputSnapshot;
|
|
218
|
+
/**
|
|
219
|
+
* A restored snapshot: the kernel does not call init or report the open
|
|
220
|
+
* state again, so take them from the snapshot. The guest still gets the
|
|
221
|
+
* events it had not read, then a release of every key and button it saw
|
|
222
|
+
* pressed (the host's keys are not held in the new session).
|
|
223
|
+
*/
|
|
224
|
+
restoreState(s: InputSnapshot): void;
|
|
225
|
+
imports(): Record<string, unknown>;
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Linux key codes by DOM KeyboardEvent.code (the physical key, independent
|
|
229
|
+
* of the layout), for a US-layout PC keyboard and the usual extra keys.
|
|
230
|
+
*/
|
|
231
|
+
export declare const DOM_CODE_TO_LINUX: Readonly<Record<string, number>>;
|
|
232
|
+
/** The Linux key code of a DOM KeyboardEvent.code, or undefined. */
|
|
233
|
+
export declare function domCodeToLinux(code: string): number | undefined;
|
|
234
|
+
/** The evdev button of a DOM MouseEvent.button (0 left, 1 middle, 2 right), or undefined. */
|
|
235
|
+
export declare function domButtonToLinux(button: number): number | undefined;
|
|
236
|
+
/** JIT counters of one kernel (Kernel.jit.stats). */
|
|
237
|
+
export interface JitStats {
|
|
238
|
+
/** The host offers the JIT (KernelConfig.jit, and the engine can compile synchronously). */
|
|
239
|
+
enabled: boolean;
|
|
240
|
+
/** The kernel's kwemu asked for it (kw_host_jit_caps was called): false for a kernel without the tier. */
|
|
241
|
+
requested: boolean;
|
|
242
|
+
/** Blocks compiled and installed. */
|
|
243
|
+
compiled: number;
|
|
244
|
+
/** Compiled blocks currently installed (compiled - freed). */
|
|
245
|
+
live: number;
|
|
246
|
+
/** Most blocks installed at once (kwemu's pool has 1024 slots). */
|
|
247
|
+
maxLive: number;
|
|
248
|
+
/** Slots kwemu released (block overwritten, evicted or cache reset). */
|
|
249
|
+
freed: number;
|
|
250
|
+
/** Compiles that failed (kwemu interprets those blocks), plus rejected calls. */
|
|
251
|
+
failed: number;
|
|
252
|
+
/** Total time spent compiling and instantiating, in ms. */
|
|
253
|
+
compileMs: number;
|
|
254
|
+
/** Total size of the compiled modules, in bytes. */
|
|
255
|
+
bytes: number;
|
|
256
|
+
/** Compiled modules the engine has garbage-collected (-1: no FinalizationRegistry, unknown). */
|
|
257
|
+
collected: number;
|
|
258
|
+
/** Freed modules not collected yet (freed - collected; -1 when unknown). */
|
|
259
|
+
retained: number;
|
|
260
|
+
/** Most freed modules uncollected at once (-1 when unknown). */
|
|
261
|
+
maxRetained: number;
|
|
262
|
+
/** ArrayBuffers allocated to prompt a collection (retained above RETAINED_NUDGE). */
|
|
263
|
+
gcNudges: number;
|
|
264
|
+
/** Compiles refused because retained reached RETAINED_LIMIT (kwemu interprets those blocks). */
|
|
265
|
+
refused: number;
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* kwemu's own counters, from a kernel built with -Dkwemu-stats
|
|
269
|
+
* (`kernel/build.sh stats`) that has compiled at least one block.
|
|
270
|
+
*/
|
|
271
|
+
export interface KwemuStats {
|
|
272
|
+
/** Guest instructions retired (struct kw_cpu icount). */
|
|
273
|
+
icount: number;
|
|
274
|
+
/**
|
|
275
|
+
* kwemu.Stats as 64-bit words, in the layout of src/emu/kwemu.zig: 11
|
|
276
|
+
* counters, op_hist[192], JIT insns, hand-backs, hb[192], hb_gen[40],
|
|
277
|
+
* jx[64] (indices in src/emu/jit.zig Jx).
|
|
278
|
+
*/
|
|
279
|
+
words: number[];
|
|
280
|
+
}
|
|
281
|
+
export interface JitHostOptions {
|
|
282
|
+
/** Offer the JIT (default true); false: kw_host_jit_caps() returns 0. */
|
|
283
|
+
enabled?: boolean;
|
|
284
|
+
/** The kernel's memory, read at call time (boot may switch memory types). */
|
|
285
|
+
memory: () => WebAssembly.Memory;
|
|
286
|
+
/** Whether that memory is a memory64 one, read at call time. */
|
|
287
|
+
memory64: () => boolean;
|
|
288
|
+
log?: (msg: string) => void;
|
|
289
|
+
/** Uncollected freed modules from which the host prompts a collection (default RETAINED_NUDGE; Infinity: never). */
|
|
290
|
+
retainedNudge?: number;
|
|
291
|
+
/** Uncollected freed modules at which compiles are refused (default RETAINED_LIMIT; Infinity: never). */
|
|
292
|
+
retainedLimit?: number;
|
|
293
|
+
}
|
|
294
|
+
export declare class JitHost {
|
|
295
|
+
#private;
|
|
296
|
+
readonly stats: JitStats;
|
|
297
|
+
constructor(opts: JitHostOptions);
|
|
298
|
+
/** Bind to the kernel instance's function table; call after instantiation, before _start. */
|
|
299
|
+
attach(exports: WebAssembly.Exports): void;
|
|
300
|
+
/**
|
|
301
|
+
* kwemu's counters, if the kernel exports them (-Dkwemu-stats) and has
|
|
302
|
+
* compiled a block (that is how the cpu is found). It writes the emit
|
|
303
|
+
* buffer, which is free outside kw_host_jit_compile, so any call from
|
|
304
|
+
* JavaScript is safe.
|
|
305
|
+
*/
|
|
306
|
+
kwemuStats(): KwemuStats | undefined;
|
|
307
|
+
/** The three `unkernel` imports. */
|
|
308
|
+
imports(): Record<string, unknown>;
|
|
309
|
+
caps(): number;
|
|
310
|
+
compile(ptr: bigint | number, len: bigint | number, slot: number): number;
|
|
311
|
+
free(slot: number): void;
|
|
312
|
+
}
|
|
313
|
+
/** ALSA formats the kernel offers (SNDRV_PCM_FORMAT_*). */
|
|
314
|
+
export declare const SOUND_FORMAT_U8 = 1;
|
|
315
|
+
export declare const SOUND_FORMAT_S16_LE = 2;
|
|
316
|
+
/** The format of a playback stream. */
|
|
317
|
+
export interface SoundFormat {
|
|
318
|
+
/** Frames per second. */
|
|
319
|
+
rate: number;
|
|
320
|
+
/** 1 or 2 (interleaved: left, right). */
|
|
321
|
+
channels: number;
|
|
322
|
+
/** SOUND_FORMAT_U8 (unsigned 8 bit) or SOUND_FORMAT_S16_LE (signed 16 bit). */
|
|
323
|
+
format: number;
|
|
324
|
+
/** Bytes per frame (channels * sample size). */
|
|
325
|
+
frameBytes: number;
|
|
326
|
+
}
|
|
327
|
+
/** What a guest program is doing with the sound device. */
|
|
328
|
+
export interface SoundState {
|
|
329
|
+
/** Some program has the PCM open. */
|
|
330
|
+
open: boolean;
|
|
331
|
+
/** The stream is running: chunks are coming. */
|
|
332
|
+
playing: boolean;
|
|
333
|
+
/** The format once the program set it (prepare), else null. */
|
|
334
|
+
format: SoundFormat | null;
|
|
335
|
+
}
|
|
336
|
+
/** PCM the guest played, in the stream's format. */
|
|
337
|
+
export interface SoundChunk {
|
|
338
|
+
format: SoundFormat;
|
|
339
|
+
/** A copy, owned by the receiver. */
|
|
340
|
+
data: Uint8Array;
|
|
341
|
+
/** data.length / format.frameBytes. */
|
|
342
|
+
frames: number;
|
|
343
|
+
}
|
|
344
|
+
export interface SoundSink {
|
|
345
|
+
/**
|
|
346
|
+
* The host's preferred rate (e.g. an AudioContext's), shown in the card's
|
|
347
|
+
* long name; programs still choose any rate from 8000 to 48000 Hz.
|
|
348
|
+
*/
|
|
349
|
+
rate?: number;
|
|
350
|
+
/**
|
|
351
|
+
* PCM played by the guest, in order. Return the frames (at the chunk's
|
|
352
|
+
* rate) still queued for output after it, if known: programs see it as
|
|
353
|
+
* part of their delay (snd_pcm_delay).
|
|
354
|
+
*/
|
|
355
|
+
onChunk?: (chunk: SoundChunk) => number | void;
|
|
356
|
+
/** The state changed (open, format, start, stop, close). */
|
|
357
|
+
onState?: (state: SoundState, event: SoundEvent) => void;
|
|
358
|
+
}
|
|
359
|
+
/** A state change, as wasm_driver_sound_event() reports it. */
|
|
360
|
+
export type SoundEvent = "open" | "prepare" | "start" | "stop" | "drain" | "close";
|
|
361
|
+
/** The sound option: false (no device), true (a device whose output is dropped), or a sink. */
|
|
362
|
+
export type SoundOption = boolean | SoundSink;
|
|
363
|
+
export interface SoundStats {
|
|
364
|
+
/** Opens of the PCM. */
|
|
365
|
+
opens: number;
|
|
366
|
+
/** Stream starts (one per start after prepare, including restarts after an underrun). */
|
|
367
|
+
starts: number;
|
|
368
|
+
/** Stops that were not the end of a drain: underruns, drops (snd_pcm_drop, close while running). */
|
|
369
|
+
stops: number;
|
|
370
|
+
chunks: number;
|
|
371
|
+
frames: number;
|
|
372
|
+
/**
|
|
373
|
+
* The longest a player that started with the first chunk of a stream
|
|
374
|
+
* would have waited for data, in ms: the largest shortfall of frames
|
|
375
|
+
* received against frames due by the host clock since the stream
|
|
376
|
+
* started. A sink needs at least this much queued to play without gaps.
|
|
377
|
+
*/
|
|
378
|
+
maxLagMs: number;
|
|
379
|
+
}
|
|
380
|
+
/** What a machine snapshot keeps of kwsnd (SoundHost.saveState()). */
|
|
381
|
+
interface SoundSnapshot {
|
|
382
|
+
state: SoundState;
|
|
383
|
+
}
|
|
384
|
+
export interface SoundHostOptions {
|
|
385
|
+
/** Offer a sound device, and where its output goes. Default false: no sound card. */
|
|
386
|
+
enabled?: SoundOption;
|
|
387
|
+
/** The kernel's memory, read at call time. */
|
|
388
|
+
memory: () => WebAssembly.Memory;
|
|
389
|
+
log?: (msg: string) => void;
|
|
390
|
+
}
|
|
391
|
+
export declare class SoundHost {
|
|
392
|
+
#private;
|
|
393
|
+
readonly enabled: boolean;
|
|
394
|
+
/** Did the kernel ask (wasm_driver_sound_init)? False for a kernel without kwsnd. */
|
|
395
|
+
probed: boolean;
|
|
396
|
+
state: SoundState;
|
|
397
|
+
stats: SoundStats;
|
|
398
|
+
constructor(opts: SoundHostOptions);
|
|
399
|
+
/** A program is playing (the stream runs). */
|
|
400
|
+
get playing(): boolean;
|
|
401
|
+
/** The state a snapshot keeps. */
|
|
402
|
+
saveState(): SoundSnapshot;
|
|
403
|
+
/**
|
|
404
|
+
* A restored snapshot: the kernel does not call init again and the
|
|
405
|
+
* stream goes on where it was, so take the saved state and replay it to
|
|
406
|
+
* the sink (open, prepare, start) as the guest's calls did. The kernel's
|
|
407
|
+
* timer keeps handing over frames on the guest's clock, which a restore
|
|
408
|
+
* continues.
|
|
409
|
+
*/
|
|
410
|
+
restoreState(s: SoundSnapshot): void;
|
|
411
|
+
imports(): Record<string, unknown>;
|
|
412
|
+
}
|
|
413
|
+
/** Samples of a chunk as floats in [-1, 1), interleaved like the input. */
|
|
414
|
+
export declare function pcmToFloat32(data: Uint8Array, format: SoundFormat, out?: Float32Array): Float32Array;
|
|
415
|
+
/**
|
|
416
|
+
* A canonical 44-byte WAV (RIFF, PCM) header for `dataBytes` bytes of
|
|
417
|
+
* samples in `format`.
|
|
418
|
+
*/
|
|
419
|
+
export declare function wavHeader(format: SoundFormat, dataBytes: number): Uint8Array;
|
|
420
|
+
/**
|
|
421
|
+
* Convert PCM to another format: channels (mono to stereo duplicates,
|
|
422
|
+
* stereo to mono averages), sample type, and rate (linear interpolation;
|
|
423
|
+
* fine for checking and for occasional format changes, not for music).
|
|
424
|
+
*/
|
|
425
|
+
export declare function convertPcm(data: Uint8Array, from: SoundFormat, to: SoundFormat): Uint8Array;
|
|
426
|
+
/** kwshm's page size. */
|
|
427
|
+
export declare const SHM_PAGE_SIZE = 4096;
|
|
428
|
+
/** Why a shm operation failed: `code` is the errno name (ENOENT, EINVAL, ...). */
|
|
429
|
+
export declare class ShmError extends Error {
|
|
430
|
+
readonly code: string;
|
|
431
|
+
constructor(code: string, message: string);
|
|
432
|
+
}
|
|
433
|
+
/** An export, as the kernel last described it. */
|
|
434
|
+
export interface ShmInfo {
|
|
435
|
+
id: number;
|
|
436
|
+
/** Bytes exported. */
|
|
437
|
+
size: number;
|
|
438
|
+
/** Pages held (size rounded up to whole pages). */
|
|
439
|
+
pages: number;
|
|
440
|
+
/** Whether the host may write (the guest's fd was writable and not sealed against writes, or a file the host opened read-write). */
|
|
441
|
+
writable: boolean;
|
|
442
|
+
/** Made by the guest (KWSHM_IOC_EXPORT) rather than opened or created by the host. */
|
|
443
|
+
guest: boolean;
|
|
444
|
+
/** Counts the page lists the kernel announced for this export (1 at first; refresh() adds one when it changes). */
|
|
445
|
+
generation: number;
|
|
446
|
+
}
|
|
447
|
+
/** What a machine snapshot keeps of kwshm (ShmDevice.saveState()): the exports and their pages. */
|
|
448
|
+
interface ShmSnapshot {
|
|
449
|
+
exports: {
|
|
450
|
+
info: ShmInfo;
|
|
451
|
+
runOff: number[];
|
|
452
|
+
runAddr: number[];
|
|
453
|
+
runLen: number[];
|
|
454
|
+
}[];
|
|
455
|
+
nextTag: number;
|
|
456
|
+
}
|
|
457
|
+
/** One request the API runs: inline on ShmDevice, in worker mode in the worker. */
|
|
458
|
+
export type ShmCall = {
|
|
459
|
+
op: "open";
|
|
460
|
+
name: string;
|
|
461
|
+
timeout?: number;
|
|
462
|
+
} | {
|
|
463
|
+
op: "create";
|
|
464
|
+
name: string;
|
|
465
|
+
size: number;
|
|
466
|
+
mode?: number;
|
|
467
|
+
timeout?: number;
|
|
468
|
+
} | {
|
|
469
|
+
op: "openId";
|
|
470
|
+
id: number;
|
|
471
|
+
} | {
|
|
472
|
+
op: "refresh";
|
|
473
|
+
id: number;
|
|
474
|
+
force?: boolean;
|
|
475
|
+
timeout?: number;
|
|
476
|
+
} | {
|
|
477
|
+
op: "check";
|
|
478
|
+
id: number;
|
|
479
|
+
timeout?: number;
|
|
480
|
+
} | {
|
|
481
|
+
op: "close";
|
|
482
|
+
id: number;
|
|
483
|
+
timeout?: number;
|
|
484
|
+
} | {
|
|
485
|
+
op: "read";
|
|
486
|
+
id: number;
|
|
487
|
+
offset: number;
|
|
488
|
+
length: number;
|
|
489
|
+
} | {
|
|
490
|
+
op: "write";
|
|
491
|
+
id: number;
|
|
492
|
+
offset: number;
|
|
493
|
+
data: Uint8Array;
|
|
494
|
+
};
|
|
495
|
+
/** What a ShmCall gives: an export's info (open, create, openId, refresh), a flag (check), bytes (read) or nothing. */
|
|
496
|
+
export type ShmCallResult = ShmInfo | boolean | Uint8Array | undefined;
|
|
497
|
+
export interface ShmDeviceOptions {
|
|
498
|
+
/** Offer the device (the kernel registers kwshm only then). Default false. */
|
|
499
|
+
enabled?: boolean;
|
|
500
|
+
/** False when the kernel has no kwshm (no wasm_driver_shm_init import): requests fail with ENODEV at once. */
|
|
501
|
+
driver?: boolean;
|
|
502
|
+
/** The kernel's memory, read at call time. */
|
|
503
|
+
memory: () => WebAssembly.Memory;
|
|
504
|
+
/** Set IRQ_SHM and wake the kernel. */
|
|
505
|
+
raise: () => void;
|
|
506
|
+
}
|
|
507
|
+
export interface ShmDeviceStats {
|
|
508
|
+
/** Requests sent to the kernel, and how many it refused. */
|
|
509
|
+
requests: number;
|
|
510
|
+
failed: number;
|
|
511
|
+
/** Page lists announced (exports and refreshes) and exports withdrawn. */
|
|
512
|
+
attaches: number;
|
|
513
|
+
detaches: number;
|
|
514
|
+
/** Exports alive now. */
|
|
515
|
+
exports: number;
|
|
516
|
+
/** Bytes copied out of and into exported pages. */
|
|
517
|
+
bytesRead: number;
|
|
518
|
+
bytesWritten: number;
|
|
519
|
+
}
|
|
520
|
+
/**
|
|
521
|
+
* The kernel's end of kwshm, on the kernel's thread: the imports, the
|
|
522
|
+
* request queue and the page lists of every live export.
|
|
523
|
+
*/
|
|
524
|
+
export declare class ShmDevice {
|
|
525
|
+
#private;
|
|
526
|
+
readonly enabled: boolean;
|
|
527
|
+
readonly driver: boolean;
|
|
528
|
+
/** Did the kernel ask (wasm_driver_shm_init)? */
|
|
529
|
+
probed: boolean;
|
|
530
|
+
/** An export's page list arrived or changed (inside the import: do not call into the kernel). */
|
|
531
|
+
onAttach: ((info: ShmInfo) => void) | undefined;
|
|
532
|
+
/** An export is gone (inside the import). */
|
|
533
|
+
onDetach: ((id: number) => void) | undefined;
|
|
534
|
+
stats: ShmDeviceStats;
|
|
535
|
+
constructor(opts: ShmDeviceOptions);
|
|
536
|
+
imports(): Record<string, unknown>;
|
|
537
|
+
/** Requests queued or waiting for the kernel's answer (a snapshot refuses then). */
|
|
538
|
+
get busy(): number;
|
|
539
|
+
/** The state a snapshot keeps (the pages stay held by the kernel). */
|
|
540
|
+
saveState(): ShmSnapshot;
|
|
541
|
+
/**
|
|
542
|
+
* A restored snapshot: the kernel does not announce its exports again,
|
|
543
|
+
* so take their page lists from the snapshot. Guest exports can be
|
|
544
|
+
* opened by id again (openId()); exports the old host opened stay held
|
|
545
|
+
* in the kernel until closed by id.
|
|
546
|
+
*/
|
|
547
|
+
restoreState(s: ShmSnapshot): void;
|
|
548
|
+
/** The export's current description, or undefined if there is no such export. */
|
|
549
|
+
info(id: number): ShmInfo | undefined;
|
|
550
|
+
/** Send a request to the kernel; resolves with its answer (>= 0) or rejects with a ShmError. */
|
|
551
|
+
request(op: number, what: string, f: {
|
|
552
|
+
id?: number;
|
|
553
|
+
flags?: number;
|
|
554
|
+
size?: number;
|
|
555
|
+
name?: string;
|
|
556
|
+
timeout?: number;
|
|
557
|
+
}): Promise<number>;
|
|
558
|
+
/** Copy bytes out of export `id` (into `out` at 0 if given). Synchronous: call it on the kernel's thread. */
|
|
559
|
+
read(id: number, offset: number, length: number, out?: Uint8Array): Uint8Array;
|
|
560
|
+
/** Copy `data` into export `id` at `offset`. Synchronous: call it on the kernel's thread. */
|
|
561
|
+
write(id: number, offset: number, data: Uint8Array): void;
|
|
562
|
+
/**
|
|
563
|
+
* Views of the kernel's memory covering [offset, offset + length) of
|
|
564
|
+
* export `id`, one per run of consecutive pages, in order. No copy. They
|
|
565
|
+
* are valid only until the kernel runs again (the guest may release or
|
|
566
|
+
* refresh the export then): use them synchronously and ask again later.
|
|
567
|
+
*/
|
|
568
|
+
views(id: number, offset: number, length: number): Uint8Array[];
|
|
569
|
+
/** Run one API call (the inline backend, and the worker's side of worker mode). */
|
|
570
|
+
run(call: ShmCall): Promise<ShmCallResult>;
|
|
571
|
+
/** The kernel exited: fail what is pending and forget every export (the memory stays readable, but nothing in it is held any more). */
|
|
572
|
+
close(): void;
|
|
573
|
+
}
|
|
574
|
+
/** Why a ShmFile handle ended: close() on it, the export went away (the guest released it, or another handle closed it), or the kernel exited. */
|
|
575
|
+
export type ShmCloseReason = "closed" | "released" | "exit";
|
|
576
|
+
export interface ShmStats {
|
|
577
|
+
/** Handles open now. */
|
|
578
|
+
open: number;
|
|
579
|
+
/** read() and write() calls, and their bytes. */
|
|
580
|
+
reads: number;
|
|
581
|
+
bytesRead: number;
|
|
582
|
+
writes: number;
|
|
583
|
+
bytesWritten: number;
|
|
584
|
+
}
|
|
585
|
+
/** One export, seen from the host. Calls on a closed handle reject with ShmError EBADF. */
|
|
586
|
+
export interface ShmFile {
|
|
587
|
+
/** The export's id: the kernel's (for a guest export, the one KWSHM_IOC_EXPORT returned). */
|
|
588
|
+
readonly id: number;
|
|
589
|
+
/** The name in /dev/shm, for files the host opened or created. */
|
|
590
|
+
readonly name: string | undefined;
|
|
591
|
+
/** "host" (open(), create()) or "guest" (openId()). */
|
|
592
|
+
readonly origin: "host" | "guest";
|
|
593
|
+
/** Bytes exported, as of the latest page list (refresh() updates it). */
|
|
594
|
+
readonly size: number;
|
|
595
|
+
readonly pages: number;
|
|
596
|
+
readonly writable: boolean;
|
|
597
|
+
/** Counts the page lists; refresh() bumps it when the kernel took the file's pages again. */
|
|
598
|
+
readonly generation: number;
|
|
599
|
+
/**
|
|
600
|
+
* Copy `length` bytes from `offset` (default: everything from offset).
|
|
601
|
+
* Inline the copy happens at once; in worker mode the worker copies (when
|
|
602
|
+
* the kernel next yields or idles) and transfers the bytes here.
|
|
603
|
+
*/
|
|
604
|
+
read(offset?: number, length?: number): Promise<Uint8Array>;
|
|
605
|
+
/** Copy `data` into the file at `offset` (it must fit within size; the export must be writable). */
|
|
606
|
+
write(offset: number, data: Uint8Array): Promise<void>;
|
|
607
|
+
/**
|
|
608
|
+
* Take the file's current pages if the view is stale (another size, or a
|
|
609
|
+
* held page no longer in the file); `force` takes them anyway. Resolves
|
|
610
|
+
* true when a new page list came (size and generation updated).
|
|
611
|
+
*/
|
|
612
|
+
refresh(opts?: {
|
|
613
|
+
force?: boolean;
|
|
614
|
+
timeout?: number;
|
|
615
|
+
}): Promise<boolean>;
|
|
616
|
+
/** Ask the kernel whether the view is stale: the file changed size, or a held page left the file (truncated or punched). */
|
|
617
|
+
isStale(opts?: {
|
|
618
|
+
timeout?: number;
|
|
619
|
+
}): Promise<boolean>;
|
|
620
|
+
/**
|
|
621
|
+
* End this handle. For a file the host opened or created this releases
|
|
622
|
+
* the export (other handles to it end with "released"); a guest export
|
|
623
|
+
* stays until the guest releases it.
|
|
624
|
+
*/
|
|
625
|
+
close(): Promise<void>;
|
|
626
|
+
/** Settles once the handle has ended. */
|
|
627
|
+
readonly closed: Promise<ShmCloseReason>;
|
|
628
|
+
}
|
|
629
|
+
/** Inline handles add zero-copy access. */
|
|
630
|
+
export interface InlineShmFile extends ShmFile {
|
|
631
|
+
/**
|
|
632
|
+
* Views of the kernel's memory for [offset, offset + length), one per run
|
|
633
|
+
* of consecutive pages (a shmem file's pages are scattered). No copy.
|
|
634
|
+
* Valid only until the kernel runs again: use them synchronously.
|
|
635
|
+
*/
|
|
636
|
+
views(offset?: number, length?: number): Uint8Array[];
|
|
637
|
+
}
|
|
638
|
+
/** The surface both inline and worker mode give as `vm.shm`. */
|
|
639
|
+
export interface Shm<F extends ShmFile = ShmFile> {
|
|
640
|
+
/**
|
|
641
|
+
* Open /dev/shm/`name` in the guest (one path component; resolved in
|
|
642
|
+
* the init mount namespace). The kernel refuses names with "/" or "..",
|
|
643
|
+
* directories (EISDIR), anything that is not a regular file (EINVAL) and
|
|
644
|
+
* files that are not shmem (EOPNOTSUPP), e.g. a bind mount. Holes are
|
|
645
|
+
* allocated. Rejects with a ShmError (ENOENT, ...; ENODEV without kwshm,
|
|
646
|
+
* ETIMEDOUT after `timeout` ms, default 10000).
|
|
647
|
+
*/
|
|
648
|
+
open(name: string, opts?: {
|
|
649
|
+
timeout?: number;
|
|
650
|
+
}): Promise<F>;
|
|
651
|
+
/**
|
|
652
|
+
* Create /dev/shm/`name` with `size` bytes (zeros, all allocated) and
|
|
653
|
+
* open it, for data from the host to the guest. Fails with EEXIST if it
|
|
654
|
+
* exists. `mode` defaults to 0o600 (root's).
|
|
655
|
+
*/
|
|
656
|
+
create(name: string, size: number, opts?: {
|
|
657
|
+
mode?: number;
|
|
658
|
+
timeout?: number;
|
|
659
|
+
}): Promise<F>;
|
|
660
|
+
/** A guest export, by the id KWSHM_IOC_EXPORT gave the guest. Rejects with ENOENT if there is none. */
|
|
661
|
+
openId(id: number): Promise<F>;
|
|
662
|
+
readonly stats: ShmStats;
|
|
663
|
+
}
|
|
664
|
+
/** How a ShmClient runs calls: on ShmDevice (inline) or across to the worker. */
|
|
665
|
+
export interface ShmBackend {
|
|
666
|
+
run(call: ShmCall): Promise<ShmCallResult>;
|
|
667
|
+
/** Inline only. */
|
|
668
|
+
views?: (id: number, offset: number, length: number) => Uint8Array[];
|
|
669
|
+
}
|
|
670
|
+
declare class Handle implements InlineShmFile {
|
|
671
|
+
#private;
|
|
672
|
+
readonly id: number;
|
|
673
|
+
readonly name: string | undefined;
|
|
674
|
+
readonly origin: "host" | "guest";
|
|
675
|
+
readonly closed: Promise<ShmCloseReason>;
|
|
676
|
+
info: ShmInfo;
|
|
677
|
+
done: ShmCloseReason | undefined;
|
|
678
|
+
/** close() asked the kernel to release it: its detach ends this handle as "closed". */
|
|
679
|
+
closing: boolean;
|
|
680
|
+
constructor(client: ShmClient<ShmFile>, info: ShmInfo, name: string | undefined);
|
|
681
|
+
get size(): number;
|
|
682
|
+
get pages(): number;
|
|
683
|
+
get writable(): boolean;
|
|
684
|
+
get generation(): number;
|
|
685
|
+
end(reason: ShmCloseReason): void;
|
|
686
|
+
read(offset?: number, length?: number): Promise<Uint8Array>;
|
|
687
|
+
write(offset: number, data: Uint8Array): Promise<void>;
|
|
688
|
+
refresh(opts?: {
|
|
689
|
+
force?: boolean;
|
|
690
|
+
timeout?: number;
|
|
691
|
+
}): Promise<boolean>;
|
|
692
|
+
isStale(opts?: {
|
|
693
|
+
timeout?: number;
|
|
694
|
+
}): Promise<boolean>;
|
|
695
|
+
close(): Promise<void>;
|
|
696
|
+
views(offset?: number, length?: number): Uint8Array[];
|
|
697
|
+
}
|
|
698
|
+
/**
|
|
699
|
+
* `vm.shm`: handles to exports, on a backend (ShmDevice inline, messages
|
|
700
|
+
* in worker mode). Feed it the kernel's announcements with attached(),
|
|
701
|
+
* detached() and shutdown().
|
|
702
|
+
*/
|
|
703
|
+
export declare class ShmClient<F extends ShmFile = ShmFile> implements Shm<F> {
|
|
704
|
+
#private;
|
|
705
|
+
readonly backend: ShmBackend;
|
|
706
|
+
constructor(backend: ShmBackend);
|
|
707
|
+
get stats(): ShmStats;
|
|
708
|
+
open(name: string, opts?: {
|
|
709
|
+
timeout?: number;
|
|
710
|
+
}): Promise<F>;
|
|
711
|
+
create(name: string, size: number, opts?: {
|
|
712
|
+
mode?: number;
|
|
713
|
+
timeout?: number;
|
|
714
|
+
}): Promise<F>;
|
|
715
|
+
openId(id: number): Promise<F>;
|
|
716
|
+
/** @internal */
|
|
717
|
+
forget(h: Handle): void;
|
|
718
|
+
/** @internal */
|
|
719
|
+
count(read: boolean, bytes: number): void;
|
|
720
|
+
/** An export's page list changed (or arrived): handles to it take the new size and generation. */
|
|
721
|
+
update(info: ShmInfo): void;
|
|
722
|
+
/** The export is gone: its handles end with "released". */
|
|
723
|
+
detached(id: number): void;
|
|
724
|
+
/** The kernel exited: every handle ends with "exit". */
|
|
725
|
+
shutdown(): void;
|
|
726
|
+
}
|
|
727
|
+
/** The inline `vm.shm`: ShmClient straight on the kernel's ShmDevice. */
|
|
728
|
+
export declare function inlineShm(dev: ShmDevice): ShmClient<InlineShmFile>;
|
|
729
|
+
/** Throw one from a handler to answer the guest with that errno: `code` is its name ("ENOENT"). */
|
|
730
|
+
export declare class FsError extends Error {
|
|
731
|
+
readonly code: string;
|
|
732
|
+
readonly errno: number;
|
|
733
|
+
constructor(code: string, message?: string);
|
|
734
|
+
}
|
|
735
|
+
export type FsFileType = "file" | "dir" | "symlink";
|
|
736
|
+
export interface FsAttr {
|
|
737
|
+
type: FsFileType;
|
|
738
|
+
/** Permission bits (default 0o644 files, 0o755 directories, 0o777 links). */
|
|
739
|
+
mode?: number;
|
|
740
|
+
size?: number;
|
|
741
|
+
uid?: number;
|
|
742
|
+
gid?: number;
|
|
743
|
+
nlink?: number;
|
|
744
|
+
atimeMs?: number;
|
|
745
|
+
mtimeMs?: number;
|
|
746
|
+
ctimeMs?: number;
|
|
747
|
+
/** Inode number (with `dev`). Without it one is derived from the path. */
|
|
748
|
+
ino?: number | bigint;
|
|
749
|
+
/** Device number, combined with `ino` (only needed when one tree spans devices). */
|
|
750
|
+
dev?: number | bigint;
|
|
751
|
+
/**
|
|
752
|
+
* A change counter: changes when the data changes. Default: derived
|
|
753
|
+
* from mtimeMs and size. 0 means the guest never caches this file's
|
|
754
|
+
* data, so each of its reads reaches the file (for computed files,
|
|
755
|
+
* whose size may change).
|
|
756
|
+
*/
|
|
757
|
+
version?: number;
|
|
758
|
+
}
|
|
759
|
+
export interface FsDirEntry {
|
|
760
|
+
name: string;
|
|
761
|
+
type: FsFileType;
|
|
762
|
+
/** The inode number and device, as getattr gives them (else one is derived from the path). */
|
|
763
|
+
ino?: number | bigint;
|
|
764
|
+
dev?: number | bigint;
|
|
765
|
+
}
|
|
766
|
+
export interface FsSetAttr {
|
|
767
|
+
mode?: number;
|
|
768
|
+
uid?: number;
|
|
769
|
+
gid?: number;
|
|
770
|
+
size?: number;
|
|
771
|
+
atimeMs?: number;
|
|
772
|
+
mtimeMs?: number;
|
|
773
|
+
}
|
|
774
|
+
export interface FsStatFs {
|
|
775
|
+
/** Block size (default 4096). */
|
|
776
|
+
bsize?: number;
|
|
777
|
+
blocks?: number;
|
|
778
|
+
bfree?: number;
|
|
779
|
+
/** Default: bfree. */
|
|
780
|
+
bavail?: number;
|
|
781
|
+
files?: number;
|
|
782
|
+
ffree?: number;
|
|
783
|
+
/** Longest name (default 255). */
|
|
784
|
+
namelen?: number;
|
|
785
|
+
}
|
|
786
|
+
/** How the guest opens a file. */
|
|
787
|
+
export interface FsOpenFlags {
|
|
788
|
+
read: boolean;
|
|
789
|
+
write: boolean;
|
|
790
|
+
/** O_TRUNC: truncate to 0 first. */
|
|
791
|
+
truncate: boolean;
|
|
792
|
+
append: boolean;
|
|
793
|
+
}
|
|
794
|
+
/**
|
|
795
|
+
* An open file (Fs.open/create), used for the guest's reads, writes,
|
|
796
|
+
* getattr, truncation and fsync until it closes it. It must keep working
|
|
797
|
+
* after the path is renamed or removed. Without `write` the file cannot be
|
|
798
|
+
* opened for writing (EACCES).
|
|
799
|
+
*/
|
|
800
|
+
export interface FsFile {
|
|
801
|
+
read(offset: number, length: number): MaybePromise<Uint8Array>;
|
|
802
|
+
/** Returns the bytes written. */
|
|
803
|
+
write?(offset: number, data: Uint8Array): MaybePromise<number>;
|
|
804
|
+
getattr?(): MaybePromise<FsAttr>;
|
|
805
|
+
setattr?(attr: FsSetAttr): MaybePromise<void>;
|
|
806
|
+
fsync?(): MaybePromise<void>;
|
|
807
|
+
close?(): MaybePromise<void>;
|
|
808
|
+
}
|
|
809
|
+
/**
|
|
810
|
+
* A file system by path: every path absolute and normalised ("/" the
|
|
811
|
+
* root, no "." or ".." parts, names never contain "/"). getattr, readdir
|
|
812
|
+
* and open are required. A missing change method answers EROFS (symlink
|
|
813
|
+
* EOPNOTSUPP); hard links are not supported (EPERM). Handlers may be async
|
|
814
|
+
* and throw an FsError, or any Error with an errno `code` as Node's fs
|
|
815
|
+
* errors have, to answer with that errno; anything else is EIO and logged.
|
|
816
|
+
*/
|
|
817
|
+
export interface Fs {
|
|
818
|
+
getattr(path: string): MaybePromise<FsAttr>;
|
|
819
|
+
readdir(path: string): MaybePromise<FsDirEntry[]>;
|
|
820
|
+
/** Open a regular file. */
|
|
821
|
+
open(path: string, flags: FsOpenFlags): MaybePromise<FsFile>;
|
|
822
|
+
/** Create a regular file (EEXIST if the name exists) and return it open for reading and writing. */
|
|
823
|
+
create?(path: string, mode: number): MaybePromise<FsFile>;
|
|
824
|
+
mkdir?(path: string, mode: number): MaybePromise<void>;
|
|
825
|
+
symlink?(path: string, target: string): MaybePromise<void>;
|
|
826
|
+
readlink?(path: string): MaybePromise<string>;
|
|
827
|
+
/** `dir`: rmdir (ENOTEMPTY unless empty), else unlink. */
|
|
828
|
+
remove?(path: string, dir: boolean): MaybePromise<void>;
|
|
829
|
+
/** Replaces `to` if it exists (an empty directory, or a non-directory over a non-directory). */
|
|
830
|
+
rename?(from: string, to: string): MaybePromise<void>;
|
|
831
|
+
/** Change a path that is not open (chmod, utimes, truncate by name). */
|
|
832
|
+
setattr?(path: string, attr: FsSetAttr): MaybePromise<void>;
|
|
833
|
+
statfs?(): MaybePromise<FsStatFs>;
|
|
834
|
+
/** Called once the last mount of this file system is gone (unmounted, or the VM exited). */
|
|
835
|
+
close?(): MaybePromise<void>;
|
|
836
|
+
}
|
|
837
|
+
/** @internal A fid as a snapshot keeps it (JSON: inode numbers are decimal strings). */
|
|
838
|
+
interface P9FidSnapshot {
|
|
839
|
+
fid: number;
|
|
840
|
+
path: string;
|
|
841
|
+
type: FsFileType;
|
|
842
|
+
/** An open regular file: how it was opened, and its qid.path then. */
|
|
843
|
+
open?: {
|
|
844
|
+
read: boolean;
|
|
845
|
+
write: boolean;
|
|
846
|
+
append: boolean;
|
|
847
|
+
ino: string;
|
|
848
|
+
};
|
|
849
|
+
/** The guest unlinked or replaced it while open: ESTALE after a restore. */
|
|
850
|
+
orphan?: true;
|
|
851
|
+
/** A directory listing being read (readdir past offset 0). */
|
|
852
|
+
dir?: Array<{
|
|
853
|
+
name: string;
|
|
854
|
+
type: FsFileType;
|
|
855
|
+
ino?: string;
|
|
856
|
+
dev?: string;
|
|
857
|
+
}>;
|
|
858
|
+
}
|
|
859
|
+
/** @internal An export's session as a snapshot keeps it (P9Server.saveExport()). */
|
|
860
|
+
interface P9ExportSnapshot {
|
|
861
|
+
name: string;
|
|
862
|
+
/** The guest connection (vsock ports and credit counters). */
|
|
863
|
+
conn: VsockConnSnapshot;
|
|
864
|
+
msize: number;
|
|
865
|
+
fids: P9FidSnapshot[];
|
|
866
|
+
}
|
|
867
|
+
/** A file's content in a tree: text (UTF-8), bytes, or a function evaluated once per open. */
|
|
868
|
+
export type FsTreeFile = string | Uint8Array | (() => string | Uint8Array);
|
|
869
|
+
/** A directory as a plain object: names to files or subdirectories. */
|
|
870
|
+
export interface FsTree {
|
|
871
|
+
[name: string]: FsTreeFile | FsTree;
|
|
872
|
+
}
|
|
873
|
+
/** What the guest changed (MemoryFs.onChange). */
|
|
874
|
+
export interface MemoryFsChange {
|
|
875
|
+
type: "create" | "write" | "truncate" | "setattr" | "mkdir" | "symlink" | "remove" | "rename";
|
|
876
|
+
path: string;
|
|
877
|
+
/** rename: the new path; symlink: the target. */
|
|
878
|
+
to?: string;
|
|
879
|
+
}
|
|
880
|
+
/** An in-memory Fs: a tree the host fills and reads, and the guest reads and writes. */
|
|
881
|
+
export declare class MemoryFs implements Fs {
|
|
882
|
+
#private;
|
|
883
|
+
/** A file system with `tree`'s files (see FsTree), or empty. */
|
|
884
|
+
constructor(tree?: FsTree);
|
|
885
|
+
/** Call `listener` for every change the guest makes. Returns the unsubscribe function. */
|
|
886
|
+
onChange(listener: (change: MemoryFsChange) => void): () => void;
|
|
887
|
+
/** Create or replace a file (parent directories are created). A function is evaluated once per open (and by readFile). */
|
|
888
|
+
writeFile(path: string, content: FsTreeFile, opts?: {
|
|
889
|
+
mode?: number;
|
|
890
|
+
}): void;
|
|
891
|
+
/** A file's bytes (a copy). */
|
|
892
|
+
readFile(path: string): Uint8Array;
|
|
893
|
+
/** A file's text (UTF-8). */
|
|
894
|
+
readText(path: string): string;
|
|
895
|
+
/** Create a directory and its parents (no error if it exists). */
|
|
896
|
+
mkdirp(path: string, opts?: {
|
|
897
|
+
mode?: number;
|
|
898
|
+
}): void;
|
|
899
|
+
/** Create a symbolic link at `path` to `target` (parents are created). */
|
|
900
|
+
writeLink(path: string, target: string): void;
|
|
901
|
+
/** Remove a file, link or directory (a non-empty directory only with `recursive`; a missing path only with `force`). */
|
|
902
|
+
rm(path: string, opts?: {
|
|
903
|
+
recursive?: boolean;
|
|
904
|
+
force?: boolean;
|
|
905
|
+
}): void;
|
|
906
|
+
/** Move (rename) a file or directory, replacing a file at `to`. */
|
|
907
|
+
move(from: string, to: string): void;
|
|
908
|
+
/** The names in a directory. */
|
|
909
|
+
list(path?: string): string[];
|
|
910
|
+
/** Attributes of a path (getattr), or undefined if it does not exist. */
|
|
911
|
+
stat(path: string): FsAttr | undefined;
|
|
912
|
+
exists(path: string): boolean;
|
|
913
|
+
getattr(path: string): FsAttr;
|
|
914
|
+
readdir(path: string): FsDirEntry[];
|
|
915
|
+
readlink(path: string): string;
|
|
916
|
+
open(path: string, flags: FsOpenFlags): FsFile;
|
|
917
|
+
create(path: string, mode: number): FsFile;
|
|
918
|
+
mkdir(path: string, mode: number): void;
|
|
919
|
+
symlink(path: string, target: string): void;
|
|
920
|
+
remove(path: string, dir: boolean): void;
|
|
921
|
+
rename(from: string, to: string): void;
|
|
922
|
+
setattr(path: string, attr: FsSetAttr): void;
|
|
923
|
+
statfs(): FsStatFs;
|
|
924
|
+
}
|
|
925
|
+
/** A file system to mount: an Fs (MemoryFs, nodeFs(), your own) or a plain object tree (made a MemoryFs). */
|
|
926
|
+
export type FsSource = Fs | FsTree;
|
|
927
|
+
export interface MountOptions {
|
|
928
|
+
/** The host answers every change with EROFS, and the guest mounts it read-only. Default false. */
|
|
929
|
+
readOnly?: boolean;
|
|
930
|
+
/** How long mounting (or unmounting) may take, in ms, kwtty's start included. Default 30000; 120000 for createKernel's mounts. */
|
|
931
|
+
timeout?: number;
|
|
932
|
+
/** How long a handler may take before the guest's request fails with ETIMEDOUT (and a log line), in ms; 0 for never. Default 30000. */
|
|
933
|
+
requestTimeout?: number;
|
|
934
|
+
}
|
|
935
|
+
export interface MountSpec extends MountOptions {
|
|
936
|
+
fs: FsSource;
|
|
937
|
+
}
|
|
938
|
+
/** createKernel's `mounts`: guest paths to a file system, or to { fs, ...MountOptions }. */
|
|
939
|
+
export type MountsOption = Record<string, FsSource | MountSpec>;
|
|
940
|
+
export type MountErrorCode =
|
|
941
|
+
/** The instance has no vsock device, or the guest's kernel has no 9p (CONFIG_9P_FS). */
|
|
942
|
+
"ENODEV" |
|
|
943
|
+
/** The guest has no kw9p (an image from before host file systems). */
|
|
944
|
+
"ENOENT" |
|
|
945
|
+
/** The path is already a mount point (in the guest, or by this SDK), or busy at unmount. */
|
|
946
|
+
"EBUSY" |
|
|
947
|
+
/** The guest path exists and is not a directory. */
|
|
948
|
+
"ENOTDIR" |
|
|
949
|
+
/** A bad path or file system. */
|
|
950
|
+
"EINVAL" |
|
|
951
|
+
/** The guest did not finish within the timeout (no kwtty answered, or a handler hung). */
|
|
952
|
+
"ETIMEDOUT" |
|
|
953
|
+
/** The kernel exited. */
|
|
954
|
+
"ECONNABORTED" |
|
|
955
|
+
/** The guest failed otherwise (the message has its words). */
|
|
956
|
+
"EREMOTE";
|
|
957
|
+
export declare class MountError extends Error {
|
|
958
|
+
readonly code: MountErrorCode;
|
|
959
|
+
constructor(code: MountErrorCode, message: string, cause?: unknown);
|
|
960
|
+
}
|
|
961
|
+
/** What the guest asked of a mount (Mount.stats). */
|
|
962
|
+
export interface MountStats {
|
|
963
|
+
requests: number;
|
|
964
|
+
/** Requests answered with an error. */
|
|
965
|
+
errors: number;
|
|
966
|
+
/** Payload bytes the guest read and wrote. */
|
|
967
|
+
bytesRead: number;
|
|
968
|
+
bytesWritten: number;
|
|
969
|
+
}
|
|
970
|
+
/** A host file system mounted in the guest (vm.mount(), createKernel({ mounts })). */
|
|
971
|
+
export interface Mount {
|
|
972
|
+
/** The guest path. */
|
|
973
|
+
readonly path: string;
|
|
974
|
+
/** True while the guest has it mounted (false once unmounted, by unmount() or in the guest, or at exit). */
|
|
975
|
+
readonly mounted: boolean;
|
|
976
|
+
/** Requests, errors, and payload bytes the guest read and wrote. */
|
|
977
|
+
readonly stats: MountStats;
|
|
978
|
+
/** Unmount it in the guest and stop serving it. Rejects with a MountError EBUSY while a guest process uses it. */
|
|
979
|
+
unmount(opts?: {
|
|
980
|
+
timeout?: number;
|
|
981
|
+
}): Promise<void>;
|
|
982
|
+
}
|
|
983
|
+
/** @internal Host file systems as a snapshot keeps them (in VsockSnapshot.mounts). */
|
|
984
|
+
interface MountsSnapshot {
|
|
985
|
+
/** The 9p server's next export number. */
|
|
986
|
+
next: number;
|
|
987
|
+
mounts: Array<{
|
|
988
|
+
path: string;
|
|
989
|
+
readOnly: boolean;
|
|
990
|
+
export: P9ExportSnapshot;
|
|
991
|
+
}>;
|
|
992
|
+
}
|
|
993
|
+
/** @internal */
|
|
994
|
+
type Parsed = {
|
|
995
|
+
path: string;
|
|
996
|
+
fs: FsSource;
|
|
997
|
+
opts: MountOptions;
|
|
998
|
+
};
|
|
999
|
+
/** @internal createKernel's `mounts`, checked before boot. */
|
|
1000
|
+
declare function parseMounts(mounts: MountsOption | undefined, vsock: boolean): Parsed[];
|
|
1001
|
+
/** The host's CID (VMADDR_CID_HOST). */
|
|
1002
|
+
export declare const VSOCK_HOST_CID = 2;
|
|
1003
|
+
/** The guest's CID with kwvsock (KWVSOCK_GUEST_CID). */
|
|
1004
|
+
export declare const VSOCK_GUEST_CID = 3;
|
|
1005
|
+
/** Size of the packet header (struct virtio_vsock_hdr). */
|
|
1006
|
+
export declare const VSOCK_HEADER_SIZE = 44;
|
|
1007
|
+
/** A packet header, decoded. CIDs fit a double (they are 32-bit in practice). */
|
|
1008
|
+
export interface VsockHeader {
|
|
1009
|
+
srcCid: number;
|
|
1010
|
+
dstCid: number;
|
|
1011
|
+
srcPort: number;
|
|
1012
|
+
dstPort: number;
|
|
1013
|
+
len: number;
|
|
1014
|
+
type: number;
|
|
1015
|
+
op: number;
|
|
1016
|
+
flags: number;
|
|
1017
|
+
bufAlloc: number;
|
|
1018
|
+
fwdCnt: number;
|
|
1019
|
+
}
|
|
1020
|
+
/** Decode the header at the start of a packet (at least VSOCK_HEADER_SIZE bytes). */
|
|
1021
|
+
export declare function decodeVsockHeader(pkt: Uint8Array): VsockHeader;
|
|
1022
|
+
/** A packet: the header (its len is the payload's) and the payload. */
|
|
1023
|
+
export declare function encodeVsockPacket(h: Omit<VsockHeader, "len">, payload?: Uint8Array): Uint8Array;
|
|
1024
|
+
export interface VsockDeviceOptions {
|
|
1025
|
+
/** Offer the device (the kernel registers its transport only then). Default false. */
|
|
1026
|
+
enabled?: boolean;
|
|
1027
|
+
/** The kernel's memory, read at call time. */
|
|
1028
|
+
memory: () => WebAssembly.Memory;
|
|
1029
|
+
/** Set IRQ_VSOCK and wake the kernel. */
|
|
1030
|
+
raise: () => void;
|
|
1031
|
+
/** A packet from the guest (a copy; header and payload). */
|
|
1032
|
+
onPacket?: (pkt: Uint8Array) => void;
|
|
1033
|
+
/** The kernel's driver started: the guest's CID and the largest packet it takes (header and payload). */
|
|
1034
|
+
onInit?: (guestCid: number, rxMax: number) => void;
|
|
1035
|
+
}
|
|
1036
|
+
/** What a machine snapshot keeps of kwvsock (VsockDevice.saveState()). */
|
|
1037
|
+
interface VsockSnapshot {
|
|
1038
|
+
guestCid: number;
|
|
1039
|
+
rxMax: number;
|
|
1040
|
+
/**
|
|
1041
|
+
* Host file systems (inline mode): each mount's 9p session and the
|
|
1042
|
+
* vsock connection it runs on, which a restore takes over; the kernel
|
|
1043
|
+
* keeps exactly these connections and resets every other.
|
|
1044
|
+
*/
|
|
1045
|
+
mounts?: MountsSnapshot;
|
|
1046
|
+
}
|
|
1047
|
+
/** @internal A connection a snapshot keeps: its ports and credit counters (Connection.saveState()). */
|
|
1048
|
+
interface VsockConnSnapshot {
|
|
1049
|
+
localPort: number;
|
|
1050
|
+
remotePort: number;
|
|
1051
|
+
rxCnt: number;
|
|
1052
|
+
fwdCnt: number;
|
|
1053
|
+
sentFwd: number;
|
|
1054
|
+
peerBufAlloc: number;
|
|
1055
|
+
peerFwdCnt: number;
|
|
1056
|
+
txCnt: number;
|
|
1057
|
+
}
|
|
1058
|
+
export interface VsockDeviceStats {
|
|
1059
|
+
/** Packets and bytes (headers included) from the guest. */
|
|
1060
|
+
fromGuest: number;
|
|
1061
|
+
fromGuestBytes: number;
|
|
1062
|
+
/** Packets and bytes taken by the guest. */
|
|
1063
|
+
toGuest: number;
|
|
1064
|
+
toGuestBytes: number;
|
|
1065
|
+
/** Guest packets the host refused for now (the kernel sends them again). */
|
|
1066
|
+
refused: number;
|
|
1067
|
+
}
|
|
1068
|
+
/**
|
|
1069
|
+
* The host side of kwvsock's imports. The guest's packets go to
|
|
1070
|
+
* `onPacket`, packets for the guest are queued with deliver(). The queue
|
|
1071
|
+
* for the guest has no limit of its own: VsockHost keeps it to the guest's
|
|
1072
|
+
* credit for data, and control packets are small.
|
|
1073
|
+
*/
|
|
1074
|
+
export declare class VsockDevice {
|
|
1075
|
+
#private;
|
|
1076
|
+
readonly enabled: boolean;
|
|
1077
|
+
/** Did the kernel ask (wasm_driver_vsock_init)? False for a kernel without kwvsock. */
|
|
1078
|
+
probed: boolean;
|
|
1079
|
+
/** The guest's CID and largest packet it takes, from the kernel's init (0 before). */
|
|
1080
|
+
guestCid: number;
|
|
1081
|
+
rxMax: number;
|
|
1082
|
+
onPacket: ((pkt: Uint8Array) => void) | undefined;
|
|
1083
|
+
onInit: ((guestCid: number, rxMax: number) => void) | undefined;
|
|
1084
|
+
/**
|
|
1085
|
+
* Test hook: return true to refuse the guest's packet for now. The
|
|
1086
|
+
* kernel keeps it, with everything after it, and sends it again after
|
|
1087
|
+
* the next IRQ, which is raised from a timer.
|
|
1088
|
+
*/
|
|
1089
|
+
refuse: (() => boolean) | undefined;
|
|
1090
|
+
/**
|
|
1091
|
+
* Connections (`guestPort:hostPort`) the kernel keeps after a restore;
|
|
1092
|
+
* it resets every other connected socket (wasm_driver_vsock_keep, asked
|
|
1093
|
+
* by kwvsock's park restore notifier). Set by the host's restore of
|
|
1094
|
+
* its mounts before the kernel runs; undefined resets them all.
|
|
1095
|
+
*/
|
|
1096
|
+
keep: Set<string> | undefined;
|
|
1097
|
+
/** Saved with the device at the snapshot point: the host file systems (inline mode). */
|
|
1098
|
+
onSave: (() => MountsSnapshot | undefined) | undefined;
|
|
1099
|
+
/** Why the host's end cannot be saved at the snapshot point (a 9p request in flight), or "". */
|
|
1100
|
+
hostBusy: (() => string) | undefined;
|
|
1101
|
+
stats: VsockDeviceStats;
|
|
1102
|
+
constructor(opts: VsockDeviceOptions);
|
|
1103
|
+
/** Packets queued for the guest. */
|
|
1104
|
+
get queued(): number;
|
|
1105
|
+
/** At the snapshot point: what keeps it from being saved now ("vsock packets", a mount's request), or "". */
|
|
1106
|
+
blocker(): string;
|
|
1107
|
+
/** Queue a packet (header and payload, at most rxMax bytes once known) for the guest and raise the IRQ. */
|
|
1108
|
+
deliver(pkt: Uint8Array): void;
|
|
1109
|
+
imports(): Record<string, unknown>;
|
|
1110
|
+
/**
|
|
1111
|
+
* The state a snapshot keeps. Connections do not survive, except those
|
|
1112
|
+
* of host file systems (`mounts`, inline mode): after a restore the
|
|
1113
|
+
* kernel resets every connected socket that `keep` does not name.
|
|
1114
|
+
*/
|
|
1115
|
+
saveState(): VsockSnapshot;
|
|
1116
|
+
/**
|
|
1117
|
+
* A restored snapshot: the kernel does not call init again, so take the
|
|
1118
|
+
* saved values and tell onInit, as init would. The kernel resets every
|
|
1119
|
+
* connected socket after the restore that `keep` does not name
|
|
1120
|
+
* (kwvsock's restore notifier), and any packet for an old connection
|
|
1121
|
+
* gets an RST from VsockHost.
|
|
1122
|
+
*/
|
|
1123
|
+
restoreState(s: VsockSnapshot): void;
|
|
1124
|
+
/** Drop what is queued (the kernel exited). */
|
|
1125
|
+
close(): void;
|
|
1126
|
+
}
|
|
1127
|
+
/** Why a vsock operation failed: `code` is the errno name. */
|
|
1128
|
+
export declare class VsockError extends Error {
|
|
1129
|
+
readonly code: string;
|
|
1130
|
+
constructor(code: string, message: string);
|
|
1131
|
+
}
|
|
1132
|
+
export interface VsockStats {
|
|
1133
|
+
/** Connections open now (connecting, established or closing). */
|
|
1134
|
+
open: number;
|
|
1135
|
+
/** Connections established, in either direction. */
|
|
1136
|
+
accepted: number;
|
|
1137
|
+
connected: number;
|
|
1138
|
+
/** Connection requests refused (by the guest: connect(); by the host: no listener, or a full backlog). */
|
|
1139
|
+
refused: number;
|
|
1140
|
+
/** Connections reset (RST sent or received while established). */
|
|
1141
|
+
resets: number;
|
|
1142
|
+
/** Payload bytes received from and sent to the guest. */
|
|
1143
|
+
bytesIn: number;
|
|
1144
|
+
bytesOut: number;
|
|
1145
|
+
/** Packets the guest sent that broke the protocol (beyond the credit, unknown types). */
|
|
1146
|
+
violations: number;
|
|
1147
|
+
}
|
|
1148
|
+
/** The surface both inline and worker mode give as `vm.vsock`. */
|
|
1149
|
+
export interface Vsock {
|
|
1150
|
+
/** The guest's CID (3). Connections from the host's side go to this CID. */
|
|
1151
|
+
readonly guestCid: number;
|
|
1152
|
+
/**
|
|
1153
|
+
* Accept guest connections to host port `port` (a guest program
|
|
1154
|
+
* connects to CID 2, `port`). Connections go to `onConnection` if given,
|
|
1155
|
+
* else they wait for accept() (or the listener's async iterator).
|
|
1156
|
+
* Throws a VsockError EADDRINUSE if the port is taken.
|
|
1157
|
+
*/
|
|
1158
|
+
listen(port: number, onConnection?: (conn: VsockConnection) => void): VsockListener;
|
|
1159
|
+
/**
|
|
1160
|
+
* Connect to a guest program listening on `port` (bound to any CID or
|
|
1161
|
+
* to 3). Rejects with a VsockError: ECONNREFUSED (nothing listens),
|
|
1162
|
+
* ETIMEDOUT (no answer within `timeout` ms, default 10000) or
|
|
1163
|
+
* ECONNABORTED (the kernel exited).
|
|
1164
|
+
*/
|
|
1165
|
+
connect(port: number, opts?: {
|
|
1166
|
+
timeout?: number;
|
|
1167
|
+
}): Promise<VsockConnection>;
|
|
1168
|
+
readonly stats: VsockStats;
|
|
1169
|
+
}
|
|
1170
|
+
export interface VsockListener extends AsyncIterable<VsockConnection> {
|
|
1171
|
+
readonly port: number;
|
|
1172
|
+
/** The next connection, or null once the listener is closed (or the kernel exited). */
|
|
1173
|
+
accept(): Promise<VsockConnection | null>;
|
|
1174
|
+
/** Stop listening: connections not accepted yet are reset, and new requests are refused. */
|
|
1175
|
+
close(): void;
|
|
1176
|
+
}
|
|
1177
|
+
/**
|
|
1178
|
+
* One stream connection. `readable` gives what the guest sends and ends
|
|
1179
|
+
* when the guest shuts down its sending side (or closes); `writable`
|
|
1180
|
+
* sends, and closing it shuts down the host's sending side (a half-close:
|
|
1181
|
+
* the guest reads EOF and may still send). Data is acknowledged to the
|
|
1182
|
+
* guest (credit) only as `readable` is read.
|
|
1183
|
+
*/
|
|
1184
|
+
export interface VsockConnection {
|
|
1185
|
+
/** The host side's port (the listener's, or the one connect() picked). */
|
|
1186
|
+
readonly localPort: number;
|
|
1187
|
+
/** The guest side's port. */
|
|
1188
|
+
readonly remotePort: number;
|
|
1189
|
+
readonly readable: ReadableStream<Uint8Array>;
|
|
1190
|
+
/** Strings are sent as UTF-8. A write resolves once its bytes are sent (the guest gave credit for them). */
|
|
1191
|
+
readonly writable: WritableStream<Uint8Array | string>;
|
|
1192
|
+
/**
|
|
1193
|
+
* Close both directions: what was written is still sent, then the
|
|
1194
|
+
* guest is told that the host neither sends nor receives (its reads
|
|
1195
|
+
* get EOF, its writes EPIPE). Data not read yet is dropped.
|
|
1196
|
+
*/
|
|
1197
|
+
close(): void;
|
|
1198
|
+
/** Reset now (RST): pending data is dropped, the guest's writes fail with EPIPE and its reads end. */
|
|
1199
|
+
reset(): void;
|
|
1200
|
+
/** Settles once the connection is gone: "closed" (both sides shut down) or "reset" (by either side, or the kernel exited). */
|
|
1201
|
+
readonly closed: Promise<"closed" | "reset">;
|
|
1202
|
+
}
|
|
1203
|
+
export interface VsockHostOptions {
|
|
1204
|
+
/** Send a packet to the guest (VsockDevice.deliver, or across to the worker). */
|
|
1205
|
+
send: (pkt: Uint8Array) => void;
|
|
1206
|
+
/** The host's receive buffer per connection, the credit the guest gets (default 256 KiB). */
|
|
1207
|
+
bufferSize?: number;
|
|
1208
|
+
log?: (msg: string) => void;
|
|
1209
|
+
}
|
|
1210
|
+
type ConnState = "connecting" | "established" | "closing" | "closed";
|
|
1211
|
+
declare class Connection implements VsockConnection {
|
|
1212
|
+
#private;
|
|
1213
|
+
readonly localPort: number;
|
|
1214
|
+
readonly remotePort: number;
|
|
1215
|
+
readonly readable: ReadableStream<Uint8Array>;
|
|
1216
|
+
readonly writable: WritableStream<Uint8Array | string>;
|
|
1217
|
+
readonly closed: Promise<"closed" | "reset">;
|
|
1218
|
+
state: ConnState;
|
|
1219
|
+
/** connect(): settled by RESPONSE or RST. */
|
|
1220
|
+
onEstablished: ((err?: VsockError) => void) | undefined;
|
|
1221
|
+
constructor(host: VsockHost, localPort: number, remotePort: number, state: ConnState);
|
|
1222
|
+
get key(): string;
|
|
1223
|
+
/**
|
|
1224
|
+
* A snapshot keeps this connection: its credit counters, or why it
|
|
1225
|
+
* cannot be kept now (data or a shutdown on the way, which the guest's
|
|
1226
|
+
* memory and these counters would not agree on).
|
|
1227
|
+
*/
|
|
1228
|
+
saveState(): VsockConnSnapshot | string;
|
|
1229
|
+
/** A restore: take the saved counters (the connection is established, nothing on the way). */
|
|
1230
|
+
loadState(s: VsockConnSnapshot): void;
|
|
1231
|
+
/** The fields every packet on this connection carries. */
|
|
1232
|
+
header(op: number, flags?: number): Omit<VsockHeader, "len">;
|
|
1233
|
+
/** A packet from the guest on this connection. */
|
|
1234
|
+
receive(h: VsockHeader, pkt: Uint8Array): void;
|
|
1235
|
+
close(): void;
|
|
1236
|
+
reset(): void;
|
|
1237
|
+
/** The kernel exited. */
|
|
1238
|
+
abort(): void;
|
|
1239
|
+
}
|
|
1240
|
+
declare class Listener implements VsockListener {
|
|
1241
|
+
#private;
|
|
1242
|
+
readonly port: number;
|
|
1243
|
+
closed: boolean;
|
|
1244
|
+
constructor(host: VsockHost, port: number, handler?: (conn: VsockConnection) => void);
|
|
1245
|
+
/** Room for one more connection? */
|
|
1246
|
+
get full(): boolean;
|
|
1247
|
+
offer(conn: Connection): void;
|
|
1248
|
+
accept(): Promise<VsockConnection | null>;
|
|
1249
|
+
[Symbol.asyncIterator](): AsyncIterator<VsockConnection>;
|
|
1250
|
+
close(): void;
|
|
1251
|
+
}
|
|
1252
|
+
/**
|
|
1253
|
+
* The host's end of the vsock protocol (CID 2): see the top of this file.
|
|
1254
|
+
* Give it the guest's packets with receive(); it sends through `send`.
|
|
1255
|
+
*/
|
|
1256
|
+
export declare class VsockHost implements Vsock {
|
|
1257
|
+
#private;
|
|
1258
|
+
/** The guest's CID (from the kernel's init; 3 until then). */
|
|
1259
|
+
guestCid: number;
|
|
1260
|
+
/** The credit each connection gives the guest. */
|
|
1261
|
+
readonly bufferSize: number;
|
|
1262
|
+
/** Payload per packet to the guest (the kernel's limit, once known, less the header). */
|
|
1263
|
+
maxPayload: number;
|
|
1264
|
+
stats: VsockStats;
|
|
1265
|
+
readonly log: (msg: string) => void;
|
|
1266
|
+
constructor(opts: VsockHostOptions);
|
|
1267
|
+
/** The kernel's driver started (VsockDevice onInit). */
|
|
1268
|
+
deviceReady(guestCid: number, rxMax: number): void;
|
|
1269
|
+
/** @internal */
|
|
1270
|
+
sendPacket(pkt: Uint8Array): void;
|
|
1271
|
+
/** @internal */
|
|
1272
|
+
forget(conn: Connection): void;
|
|
1273
|
+
/** @internal */
|
|
1274
|
+
unlisten(l: Listener): void;
|
|
1275
|
+
listen(port: number, onConnection?: (conn: VsockConnection) => void): VsockListener;
|
|
1276
|
+
connect(port: number, opts?: {
|
|
1277
|
+
timeout?: number;
|
|
1278
|
+
}): Promise<VsockConnection>;
|
|
1279
|
+
/**
|
|
1280
|
+
* @internal A restore (before the kernel runs): take over a connection
|
|
1281
|
+
* the snapshot kept, with its counters. The restored kernel keeps it
|
|
1282
|
+
* (VsockDevice.keep) and resets every other.
|
|
1283
|
+
*/
|
|
1284
|
+
adopt(s: VsockConnSnapshot): VsockConnection;
|
|
1285
|
+
/** A packet from the guest. */
|
|
1286
|
+
receive(pkt: Uint8Array): void;
|
|
1287
|
+
/** The kernel exited: every connection ends (ECONNABORTED), listeners return null. */
|
|
1288
|
+
shutdown(reason?: string): void;
|
|
1289
|
+
}
|
|
1290
|
+
/**
|
|
1291
|
+
* The host side of each device the machine had. A key is present when the
|
|
1292
|
+
* device was configured; its value is null if the kernel had not started
|
|
1293
|
+
* its driver yet (it then starts it after the restore, as at boot).
|
|
1294
|
+
*/
|
|
1295
|
+
export interface DeviceSnapshots {
|
|
1296
|
+
display?: DisplaySnapshot | null;
|
|
1297
|
+
input?: InputSnapshot | null;
|
|
1298
|
+
sound?: SoundSnapshot | null;
|
|
1299
|
+
vsock?: VsockSnapshot | null;
|
|
1300
|
+
shm?: ShmSnapshot | null;
|
|
1301
|
+
/** The MAC the guest's kwnet got. */
|
|
1302
|
+
network?: {
|
|
1303
|
+
mac: number[];
|
|
1304
|
+
} | null;
|
|
1305
|
+
}
|
|
1306
|
+
/** The devices of DeviceSnapshots that a restore must find configured, or not, as saved. */
|
|
1307
|
+
export type DeviceKind = "display" | "sound" | "vsock" | "shm" | "network";
|
|
1308
|
+
/** A saved machine (Kernel.snapshot()). */
|
|
1309
|
+
export interface KernelSnapshot {
|
|
1310
|
+
version: 1;
|
|
1311
|
+
/** The kernel build it came from (Kernel.fingerprint); restore refuses another. */
|
|
1312
|
+
fingerprint: string;
|
|
1313
|
+
memory64: boolean;
|
|
1314
|
+
/** All of the kernel's memory; the pages it reported free are zero. */
|
|
1315
|
+
memory: Uint8Array;
|
|
1316
|
+
/** Bytes of free pages left out of `memory` (0 if the kernel reported none). */
|
|
1317
|
+
freeBytes?: number;
|
|
1318
|
+
/** The guest's monotonic clock at the snapshot, in ms; a restore continues from it. */
|
|
1319
|
+
monotonicMs: number;
|
|
1320
|
+
/** rows << 16 | cols, 0 = unknown. */
|
|
1321
|
+
consoleSize: number;
|
|
1322
|
+
/** Console input the guest had not read yet. */
|
|
1323
|
+
input: Uint8Array;
|
|
1324
|
+
/** The disks, in order (/dev/wda, wdb, ...); a restore needs the same ones, unchanged. */
|
|
1325
|
+
disks: DiskSnapshotState[];
|
|
1326
|
+
/** The other devices (empty in snapshots from before devices were saved). */
|
|
1327
|
+
devices: DeviceSnapshots;
|
|
1328
|
+
}
|
|
1329
|
+
/**
|
|
1330
|
+
* Why a machine with the devices `present` (and the network MAC `mac`, if
|
|
1331
|
+
* set) cannot resume `saved`, or null if it can: the restored kernel has
|
|
1332
|
+
* exactly the drivers it had, so each device must be configured, or not,
|
|
1333
|
+
* as it was.
|
|
1334
|
+
*/
|
|
1335
|
+
export declare function snapshotDeviceMismatch(saved: DeviceSnapshots, present: Record<DeviceKind, boolean>, mac?: Uint8Array): string | null;
|
|
1336
|
+
/**
|
|
1337
|
+
* Why `disks` cannot resume `saved` (a snapshot's disks), or null if they
|
|
1338
|
+
* can: the same number of disks, each with the same identity, write
|
|
1339
|
+
* generation and stamp. A disk that changed after the snapshot would not match the
|
|
1340
|
+
* restored kernel's caches (its file systems would be corrupted).
|
|
1341
|
+
*/
|
|
1342
|
+
export declare function snapshotDiskMismatch(saved: DiskSnapshotState[], disks: BlockDevice[]): string | null;
|
|
1343
|
+
/**
|
|
1344
|
+
* Encode a snapshot: MAGIC, a u32 header length, the JSON header (everything
|
|
1345
|
+
* but the memory and the input), the input, then each non-zero 64 KiB chunk
|
|
1346
|
+
* of the memory as a u32 chunk index and its bytes. Little-endian.
|
|
1347
|
+
*/
|
|
1348
|
+
export declare function encodeSnapshot(s: KernelSnapshot): Uint8Array;
|
|
1349
|
+
export declare function decodeSnapshot(bytes: Uint8Array): KernelSnapshot;
|
|
1350
|
+
type Fd = {
|
|
1351
|
+
type: "stdin" | "stdout" | "stderr";
|
|
1352
|
+
} | {
|
|
1353
|
+
type: "dir";
|
|
1354
|
+
name: Uint8Array;
|
|
1355
|
+
files: Map<string, Uint8Array>;
|
|
1356
|
+
} | {
|
|
1357
|
+
type: "file";
|
|
1358
|
+
data: Uint8Array;
|
|
1359
|
+
pos: number;
|
|
1360
|
+
};
|
|
1361
|
+
interface Subscription {
|
|
1362
|
+
userdata: bigint;
|
|
1363
|
+
tag: number;
|
|
1364
|
+
clock?: number;
|
|
1365
|
+
deadline?: bigint;
|
|
1366
|
+
fd?: number;
|
|
1367
|
+
}
|
|
1368
|
+
interface PollEvent {
|
|
1369
|
+
userdata: bigint;
|
|
1370
|
+
type: number;
|
|
1371
|
+
error: number;
|
|
1372
|
+
nbytes: bigint;
|
|
1373
|
+
}
|
|
1374
|
+
interface WasiHostOptions {
|
|
1375
|
+
/** Program arguments (argv[0] first). */
|
|
1376
|
+
args: string[];
|
|
1377
|
+
/** Read-only files of the preopened "/". */
|
|
1378
|
+
files?: Record<string, Uint8Array>;
|
|
1379
|
+
}
|
|
1380
|
+
declare class WasiHost {
|
|
1381
|
+
k: Kernel;
|
|
1382
|
+
args: Uint8Array[];
|
|
1383
|
+
/** The last 4 KiB written to stderr (the panic message). */
|
|
1384
|
+
stderr: string;
|
|
1385
|
+
fds: Map<number, Fd>;
|
|
1386
|
+
buf: ArrayBuffer | null;
|
|
1387
|
+
dvCache: DataView | null;
|
|
1388
|
+
u8Cache: Uint8Array<ArrayBuffer> | null;
|
|
1389
|
+
/**
|
|
1390
|
+
* Added to performance.now() for the guest's monotonic clock (ms): a
|
|
1391
|
+
* restored snapshot continues from the value it was saved at.
|
|
1392
|
+
*/
|
|
1393
|
+
monoOffset: number;
|
|
1394
|
+
/**
|
|
1395
|
+
* @param k console input/output, idle wake-ups, exit
|
|
1396
|
+
*/
|
|
1397
|
+
constructor(k: Kernel, { args, files }: WasiHostOptions);
|
|
1398
|
+
/** The guest's monotonic clock (ms). */
|
|
1399
|
+
monotonicMs(): number;
|
|
1400
|
+
clockNs(id: number): bigint;
|
|
1401
|
+
/** Views of the kernel's memory, rebuilt only if it grew (the old buffer is then detached). */
|
|
1402
|
+
views(): void;
|
|
1403
|
+
dv(): DataView;
|
|
1404
|
+
u8(): Uint8Array<ArrayBuffer>;
|
|
1405
|
+
/** [ptr, len] pairs of an iovec array. */
|
|
1406
|
+
iovecs(iovs: number, n: number): Array<[number, number]>;
|
|
1407
|
+
/** Bytes of console input queued in the kernel object. */
|
|
1408
|
+
stdinQueued(): number;
|
|
1409
|
+
readStdin(dst: number, want: number): number;
|
|
1410
|
+
/** The poll_oneoff subscriptions at `inp`. */
|
|
1411
|
+
subscriptions(inp: number, n: number): Subscription[];
|
|
1412
|
+
/** Events for the subscriptions that are ready now. */
|
|
1413
|
+
ready(subs: Subscription[]): PollEvent[];
|
|
1414
|
+
writeEvents(out: number, nevents: number, events: PollEvent[]): void;
|
|
1415
|
+
exit(code: number): void;
|
|
1416
|
+
imports(): Record<string, unknown>;
|
|
1417
|
+
}
|
|
1418
|
+
/**
|
|
1419
|
+
* The host asks the kernel to sync (ksys_sync(): write back and flush every
|
|
1420
|
+
* file system; WASM_IRQ_SYNC). The kernel clears the bit when it takes the
|
|
1421
|
+
* request.
|
|
1422
|
+
*/
|
|
1423
|
+
export declare const IRQ_SYNC = 4;
|
|
1424
|
+
/**
|
|
1425
|
+
* How a kernel run ended: "halt" (orderly power-off/reboot: code 0 power
|
|
1426
|
+
* off, 1 halt, 2 restart), "panic" (code 253), "trap" (a wasm trap or JS
|
|
1427
|
+
* exception inside the kernel, code 254, `error` holds it), "fatal" (a host
|
|
1428
|
+
* runtime invariant broke, code 255) or "stopped" (Kernel.stop()).
|
|
1429
|
+
*/
|
|
1430
|
+
export type ExitKind = "halt" | "panic" | "trap" | "fatal" | "stopped";
|
|
1431
|
+
export interface ExitResult {
|
|
1432
|
+
code: number;
|
|
1433
|
+
reason: string;
|
|
1434
|
+
kind: ExitKind;
|
|
1435
|
+
error?: unknown;
|
|
1436
|
+
}
|
|
1437
|
+
/**
|
|
1438
|
+
* The host side of the kwnet device, e.g. a NetStack (net.ts). Frames for
|
|
1439
|
+
* the guest go through Kernel.receiveFrame().
|
|
1440
|
+
*/
|
|
1441
|
+
export interface NetDevice {
|
|
1442
|
+
/** The guest's MAC address (6 bytes). */
|
|
1443
|
+
mac?: Uint8Array;
|
|
1444
|
+
/** Called once when the guest's driver initialises. */
|
|
1445
|
+
attach?(kernel: Kernel): void;
|
|
1446
|
+
/** An Ethernet frame from the guest. */
|
|
1447
|
+
send(frame: Uint8Array): void;
|
|
1448
|
+
/** Release host resources (connections, sockets). */
|
|
1449
|
+
close?(): void;
|
|
1450
|
+
}
|
|
1451
|
+
/** Detail of the "memory" boot stage. */
|
|
1452
|
+
export interface MemoryStage {
|
|
1453
|
+
mib: number;
|
|
1454
|
+
requestedMiB: number;
|
|
1455
|
+
failures: string[];
|
|
1456
|
+
memory64: boolean;
|
|
1457
|
+
}
|
|
1458
|
+
export type BootStage = "memory" | "instantiate" | "start" | "exit";
|
|
1459
|
+
export interface KernelStats {
|
|
1460
|
+
switches: number;
|
|
1461
|
+
idles: number;
|
|
1462
|
+
yields: number;
|
|
1463
|
+
}
|
|
1464
|
+
export interface KernelConfig {
|
|
1465
|
+
/** Compiled vmlinux (wasm64) or vmlinux32.wasm (lowered), or a bundle of either. */
|
|
1466
|
+
module: WebAssembly.Module;
|
|
1467
|
+
/** Memory type to import; default: moduleIsMemory64(module). */
|
|
1468
|
+
memory64?: boolean;
|
|
1469
|
+
/** Default 512. */
|
|
1470
|
+
memoryMiB?: number;
|
|
1471
|
+
/** Default: the module's bundled one (bundledBoot), else "". */
|
|
1472
|
+
cmdline?: string;
|
|
1473
|
+
/** Default (undefined): the module's bundled initramfs, if any; null boots without one. */
|
|
1474
|
+
initrd?: Uint8Array | null;
|
|
1475
|
+
/** Smaller sizes to try, in order, if allocating memoryMiB fails (e.g. a phone without the address space). */
|
|
1476
|
+
memoryFallbackMiB?: number[];
|
|
1477
|
+
/** Console output. */
|
|
1478
|
+
write: (bytes: Uint8Array) => void;
|
|
1479
|
+
/** Host diagnostics; default console.error. */
|
|
1480
|
+
log?: (msg: string) => void;
|
|
1481
|
+
/**
|
|
1482
|
+
* Boot progress: "memory" (MemoryStage), "instantiate", "start" (kernel
|
|
1483
|
+
* entry), "exit" (ExitResult).
|
|
1484
|
+
*/
|
|
1485
|
+
onStage?: (stage: BootStage, detail?: MemoryStage | ExitResult) => void;
|
|
1486
|
+
/** kwblk disks: /dev/wda, wdb, ... */
|
|
1487
|
+
disks?: BlockDevice[];
|
|
1488
|
+
/** kwnet device; without one the guest has no network interface. */
|
|
1489
|
+
net?: NetDevice;
|
|
1490
|
+
/**
|
|
1491
|
+
* Offer a display (kwfb, /dev/fb0; display.ts): true (640x480), a size,
|
|
1492
|
+
* or a function returning the size wanted when a program first opens
|
|
1493
|
+
* it. Default false: the guest has no framebuffer device.
|
|
1494
|
+
*/
|
|
1495
|
+
display?: DisplayOption;
|
|
1496
|
+
/** A guest program opened the display (its mode), or the last one closed it (null). */
|
|
1497
|
+
onDisplay?: (mode: DisplayMode | null) => void;
|
|
1498
|
+
/**
|
|
1499
|
+
* With a display, the guest also gets a keyboard and a mouse (kwinput,
|
|
1500
|
+
* evdev). Called when some program opens or the last one closes them.
|
|
1501
|
+
*/
|
|
1502
|
+
onInput?: (state: InputState) => void;
|
|
1503
|
+
/** Offer a sound card (kwsnd: ALSA playback, sound.ts) and where its PCM goes. Default false: none. */
|
|
1504
|
+
sound?: SoundOption;
|
|
1505
|
+
/**
|
|
1506
|
+
* Offer a vsock device (kwvsock: AF_VSOCK, guest CID 3, host CID 2;
|
|
1507
|
+
* vsock.ts). Default false: the kernel registers no transport. The
|
|
1508
|
+
* guest's packets go to onVsockPacket; Kernel.vsock.deliver() sends.
|
|
1509
|
+
*/
|
|
1510
|
+
vsock?: boolean;
|
|
1511
|
+
/** A packet from the guest's kwvsock (header and payload; a copy). */
|
|
1512
|
+
onVsockPacket?: (pkt: Uint8Array) => void;
|
|
1513
|
+
/** kwvsock started: the guest's CID and the largest packet it takes (header and payload). */
|
|
1514
|
+
onVsockInit?: (guestCid: number, rxMax: number) => void;
|
|
1515
|
+
/**
|
|
1516
|
+
* Offer kwshm (shm.ts): the host reads and writes guest shmem files in
|
|
1517
|
+
* place. Default false: the kernel registers nothing.
|
|
1518
|
+
*/
|
|
1519
|
+
shm?: boolean;
|
|
1520
|
+
/**
|
|
1521
|
+
* Offer kwemu's JIT tier (hot guest code compiled to WebAssembly; see
|
|
1522
|
+
* jit.ts). Default true; false makes kwemu interpret everything. A
|
|
1523
|
+
* kernel built without the tier ignores it.
|
|
1524
|
+
*/
|
|
1525
|
+
jit?: boolean;
|
|
1526
|
+
/**
|
|
1527
|
+
* Resume this snapshot (snapshot()) instead of booting: same kernel
|
|
1528
|
+
* build, memory size and type. initrd and cmdline are ignored. `disks`
|
|
1529
|
+
* must be the snapshot's, unchanged (snapshotDiskMismatch); boot()
|
|
1530
|
+
* rejects otherwise.
|
|
1531
|
+
*/
|
|
1532
|
+
restore?: KernelSnapshot;
|
|
1533
|
+
}
|
|
1534
|
+
/**
|
|
1535
|
+
* Does this kernel module import a 64-bit (memory64) memory?
|
|
1536
|
+
*
|
|
1537
|
+
* The kernel comes in two builds of the same code: vmlinux (wasm64:
|
|
1538
|
+
* memory64 + table64) and vmlinux32.wasm, the same module after Binaryen's
|
|
1539
|
+
* --memory64-lowering. The lowered one keeps i64 pointers in code and at the
|
|
1540
|
+
* JS boundary but has a 32-bit memory and table, so it runs on engines
|
|
1541
|
+
* without memory64 (WebKit). The JS API does not reflect an import's memory
|
|
1542
|
+
* type, so this reads the linker's "target_features" section (Binaryen drops
|
|
1543
|
+
* "memory64" from it when lowering). Without that section it guesses wasm64;
|
|
1544
|
+
* boot() retries with the other memory type if instantiation fails.
|
|
1545
|
+
*/
|
|
1546
|
+
export declare function moduleIsMemory64(module: WebAssembly.Module): boolean;
|
|
1547
|
+
/**
|
|
1548
|
+
* The root file system, command line and data disk template bundled into
|
|
1549
|
+
* the module by kernel/tools/bundle.mjs (custom sections "unkernel.initrd",
|
|
1550
|
+
* "unkernel.cmdline" and "unkernel.datadisk"), or undefined for each that
|
|
1551
|
+
* is absent. datadisk is a gzipped kwsparse image (kwsparse.ts).
|
|
1552
|
+
*/
|
|
1553
|
+
export declare function bundledBoot(module: WebAssembly.Module): {
|
|
1554
|
+
initrd?: Uint8Array;
|
|
1555
|
+
cmdline?: string;
|
|
1556
|
+
datadisk?: Uint8Array;
|
|
1557
|
+
};
|
|
1558
|
+
type Resolver = (task: bigint) => void;
|
|
1559
|
+
/**
|
|
1560
|
+
* A host side that cannot get the event loop while the kernel runs (worker
|
|
1561
|
+
* mode's shared transport, worker-shared.ts) and looks for its events in
|
|
1562
|
+
* the WASI clock instead, which the kernel reads at the end of every slice
|
|
1563
|
+
* and before it reads wasm_host_irqs. None of these may suspend.
|
|
1564
|
+
*/
|
|
1565
|
+
interface KernelPoller {
|
|
1566
|
+
/** Every monotonic clock_time_get: cheap when nothing is new. */
|
|
1567
|
+
poll(): void;
|
|
1568
|
+
/** poll_oneoff is about to wait: true if events arrived (handled; do not wait). */
|
|
1569
|
+
idle(): boolean;
|
|
1570
|
+
/** That wait ended. */
|
|
1571
|
+
awake(): void;
|
|
1572
|
+
}
|
|
1573
|
+
/**
|
|
1574
|
+
* One kernel instance. boot() resolves with an ExitResult when the kernel
|
|
1575
|
+
* halts, panics, traps, hits a host invariant or is stopped.
|
|
1576
|
+
*/
|
|
1577
|
+
export declare class Kernel {
|
|
1578
|
+
opts: KernelConfig;
|
|
1579
|
+
log: (msg: string) => void;
|
|
1580
|
+
/** Pending console input chunks. */
|
|
1581
|
+
input: Uint8Array[];
|
|
1582
|
+
inputOffset: number;
|
|
1583
|
+
/** rows << 16 | cols, 0 = unknown (setConsoleSize). */
|
|
1584
|
+
consoleSize: number;
|
|
1585
|
+
/** resolve() of the current wasm_idle promise. */
|
|
1586
|
+
idleWake: (() => void) | null;
|
|
1587
|
+
/** task -> resolve(lastTask) */
|
|
1588
|
+
resumers: Map<bigint, Resolver>;
|
|
1589
|
+
onStage: (stage: BootStage, detail?: MemoryStage | ExitResult) => void;
|
|
1590
|
+
/** Settles with the first exit (halt, panic, trap, fatal, stop). */
|
|
1591
|
+
exited: Promise<ExitResult>;
|
|
1592
|
+
/** Record the exit (the first one wins). */
|
|
1593
|
+
exit: (res: ExitResult) => void;
|
|
1594
|
+
/** The exit, once there is one. */
|
|
1595
|
+
result: ExitResult | undefined;
|
|
1596
|
+
stats: KernelStats;
|
|
1597
|
+
block: BlockHost;
|
|
1598
|
+
/** kwemu's JIT host (kw_host_jit_* imports); counters in jit.stats. */
|
|
1599
|
+
jit: JitHost;
|
|
1600
|
+
netRx: Uint8Array[];
|
|
1601
|
+
/** kwfb's host side: where the guest's pixels are, if anywhere. */
|
|
1602
|
+
display: DisplayHost;
|
|
1603
|
+
/** kwinput's host side (evdev keyboard and mouse): the event queue and whether a program reads it. */
|
|
1604
|
+
evdev: InputHost;
|
|
1605
|
+
/** kwsnd's host side (sound.ts): the playback state and the sink. */
|
|
1606
|
+
sound: SoundHost;
|
|
1607
|
+
/** kwvsock's host side (vsock.ts): the packet queues; the protocol is VsockHost's. */
|
|
1608
|
+
vsock: VsockDevice;
|
|
1609
|
+
/** kwshm's host side (shm.ts): requests, page lists and copies; the API is ShmClient's. */
|
|
1610
|
+
shm: ShmDevice;
|
|
1611
|
+
memory: WebAssembly.Memory;
|
|
1612
|
+
memory64: boolean;
|
|
1613
|
+
wasi: WasiHost;
|
|
1614
|
+
exports: WebAssembly.Exports | undefined;
|
|
1615
|
+
/** Address of wasm_host_irqs, once instantiated. */
|
|
1616
|
+
irqAddr: number | undefined;
|
|
1617
|
+
retFromFork: (prev: bigint, next: bigint) => Promise<unknown>;
|
|
1618
|
+
/** performance.now() at kernel entry. */
|
|
1619
|
+
bootTime: number;
|
|
1620
|
+
/** Polled from the clock import, if set (KernelPoller). */
|
|
1621
|
+
poller: KernelPoller | null;
|
|
1622
|
+
/** The kernel build: its linux_banner (compile time and build number), once instantiated. */
|
|
1623
|
+
fingerprint: string;
|
|
1624
|
+
/** The MAC kwnet got (wasm_driver_net_init), once the guest's driver started; null before or without a network. */
|
|
1625
|
+
netMac: Uint8Array | null;
|
|
1626
|
+
/** The snapshot() in progress. */
|
|
1627
|
+
snapshotWaiter: {
|
|
1628
|
+
resolve: (s: KernelSnapshot) => void;
|
|
1629
|
+
reject: (e: Error) => void;
|
|
1630
|
+
stop: boolean;
|
|
1631
|
+
} | null;
|
|
1632
|
+
constructor(opts: KernelConfig);
|
|
1633
|
+
/** Queue an Ethernet frame for the guest's kwnet device. */
|
|
1634
|
+
receiveFrame(frame: Uint8Array): void;
|
|
1635
|
+
/** Set a host IRQ bit in wasm_host_irqs (once instantiated) and wake the kernel. */
|
|
1636
|
+
raiseIrq(bit: number): void;
|
|
1637
|
+
netImports(): Record<string, unknown>;
|
|
1638
|
+
u8(): Uint8Array;
|
|
1639
|
+
dv(): DataView;
|
|
1640
|
+
cstr(ptr: number | bigint, max?: number): string;
|
|
1641
|
+
fatal(msg: string): void;
|
|
1642
|
+
/**
|
|
1643
|
+
* Stop the kernel for good. The exit is recorded at once (exited
|
|
1644
|
+
* settles with it); the kernel itself parks at its next suspension
|
|
1645
|
+
* point (an idle wait, a periodic yield or a task switch, at most about
|
|
1646
|
+
* 20 ms of guest work away) and never runs again. There is no clean
|
|
1647
|
+
* shutdown: the guest is not told, so unflushed disk writes are lost.
|
|
1648
|
+
*/
|
|
1649
|
+
stop(res?: Partial<ExitResult>): void;
|
|
1650
|
+
/** Feed console input (bytes or string). */
|
|
1651
|
+
sendInput(data: Uint8Array | string): void;
|
|
1652
|
+
/**
|
|
1653
|
+
* Set the console window size (the guest tty's rows and columns). hvc_wasm
|
|
1654
|
+
* picks it up on its next input poll, which the console IRQ triggers;
|
|
1655
|
+
* the foreground process gets SIGWINCH.
|
|
1656
|
+
*/
|
|
1657
|
+
setConsoleSize(cols: number, rows: number): void;
|
|
1658
|
+
/**
|
|
1659
|
+
* Ask the kernel to sync (IRQ_SYNC) and wait until every persistent disk
|
|
1660
|
+
* (BlockDevice.persistent, with flushSeq and whenFlushed) has completed a
|
|
1661
|
+
* flush issued after this call, i.e. one whose save started after it.
|
|
1662
|
+
* Resolves true then, or false after `timeout` ms; on a timeout the bit
|
|
1663
|
+
* is cleared here, since a kernel without IRQ_SYNC support never clears
|
|
1664
|
+
* it. Resolves true at once when no disk is persistent.
|
|
1665
|
+
*/
|
|
1666
|
+
requestSync({ timeout }?: {
|
|
1667
|
+
timeout?: number;
|
|
1668
|
+
}): Promise<boolean>;
|
|
1669
|
+
/**
|
|
1670
|
+
* Save the machine: the kernel parks every task (arch/wasm/kernel/
|
|
1671
|
+
* park.c) and, at the point where all its state is in memory, the host
|
|
1672
|
+
* copies the memory and seals the disks (BlockDevice.snapshotSeal: their
|
|
1673
|
+
* content becomes durable and the snapshot records their identity and
|
|
1674
|
+
* write generation; disks are not copied). Resolves once the disks are
|
|
1675
|
+
* durable. Without `stop` the guest keeps running, and its next write
|
|
1676
|
+
* to a disk makes the snapshot unrestorable with that disk (a restore
|
|
1677
|
+
* refuses it); with `stop: true` the kernel never runs again after the
|
|
1678
|
+
* copy (exit kind "stopped"), so the disks stay as saved. Rejects if a
|
|
1679
|
+
* task does not park within 2 s (the error names it), if I/O is in
|
|
1680
|
+
* flight, if a disk cannot be part of a snapshot (one without
|
|
1681
|
+
* snapshotSeal, or an overlay kept only in memory that was written), or
|
|
1682
|
+
* if shm requests are waiting for the kernel. The other devices keep
|
|
1683
|
+
* their host side's state (DeviceSnapshots); vsock connections and the
|
|
1684
|
+
* network's TCP connections do not survive a restore (the guest's get
|
|
1685
|
+
* reset), except the 9p sessions of host file systems, which the vsock
|
|
1686
|
+
* device saves (VsockDevice.onSave; a request in flight on one makes
|
|
1687
|
+
* the snapshot point busy, VsockDevice.blocker()).
|
|
1688
|
+
*/
|
|
1689
|
+
snapshot({ stop }?: {
|
|
1690
|
+
stop?: boolean;
|
|
1691
|
+
}): Promise<KernelSnapshot>;
|
|
1692
|
+
/** Put a snapshot into the fresh instance's memory (boot(), KernelConfig.restore). */
|
|
1693
|
+
loadSnapshot(s: KernelSnapshot): void;
|
|
1694
|
+
/** Which devices this machine has, as a snapshot records them (DeviceSnapshots keys). */
|
|
1695
|
+
devicesPresent(): Record<"display" | "sound" | "vsock" | "shm" | "network", boolean>;
|
|
1696
|
+
/** The host side of each configured device, at the snapshot point (null: its driver had not started). */
|
|
1697
|
+
saveDevices(): DeviceSnapshots;
|
|
1698
|
+
/**
|
|
1699
|
+
* Give each device's host side the state the kernel told the old one
|
|
1700
|
+
* (loadSnapshot, after the memory is in and the IRQ bits are cleared);
|
|
1701
|
+
* the restored kernel does not tell it again.
|
|
1702
|
+
*/
|
|
1703
|
+
restoreDevices(d: DeviceSnapshots): void;
|
|
1704
|
+
/** wasm_snapshot_point: the end of a snapshot cycle (see snapshot()). */
|
|
1705
|
+
snapshotPoint(result: number, blocker: bigint, freeMap?: bigint, freeBits?: bigint): number;
|
|
1706
|
+
wake(): void;
|
|
1707
|
+
imports(): WebAssembly.Imports;
|
|
1708
|
+
onTrap(e: unknown): void;
|
|
1709
|
+
/** A fixed-size memory of `pages` 64 KiB pages, 64-bit (BigInt sizes) or 32-bit. */
|
|
1710
|
+
static newMemory(pages: number, memory64: boolean): WebAssembly.Memory;
|
|
1711
|
+
/**
|
|
1712
|
+
* Allocate the kernel's memory (fixed size: the kernel sizes RAM from it
|
|
1713
|
+
* once at boot). Tries memoryMiB, then each of opts.memoryFallbackMiB.
|
|
1714
|
+
* The maximum equals the initial size so engines reserve no more address
|
|
1715
|
+
* space than needed.
|
|
1716
|
+
*/
|
|
1717
|
+
allocateMemory(memoryMiB: number, initrdBytes: number): WebAssembly.Memory;
|
|
1718
|
+
/**
|
|
1719
|
+
* Instantiate and boot. Resolves with the ExitResult when the kernel
|
|
1720
|
+
* halts; rejects if it cannot start (memory, instantiation, initrd size).
|
|
1721
|
+
*/
|
|
1722
|
+
boot(): Promise<ExitResult>;
|
|
1723
|
+
}
|
|
1724
|
+
export declare const KWSPARSE_MAGIC = "KWSPARS1";
|
|
1725
|
+
/** A decoded kwsparse image: indices[i] is the disk block whose content is block(i). */
|
|
1726
|
+
export interface KwsparseImage {
|
|
1727
|
+
size: number;
|
|
1728
|
+
blockSize: number;
|
|
1729
|
+
indices: number[];
|
|
1730
|
+
/** The block data, all blocks back to back. */
|
|
1731
|
+
data: Uint8Array;
|
|
1732
|
+
block(i: number): Uint8Array;
|
|
1733
|
+
/** Block index -> data (views into `data`). */
|
|
1734
|
+
map(): Map<number, Uint8Array>;
|
|
1735
|
+
}
|
|
1736
|
+
/** All bytes zero? */
|
|
1737
|
+
export declare function isZeroBlock(b: Uint8Array): boolean;
|
|
1738
|
+
/** The header of a kwsparse image holding the given block indices (ascending). */
|
|
1739
|
+
export declare function kwsparseHeader(size: number, blockSize: number, indices: readonly number[]): Uint8Array;
|
|
1740
|
+
/**
|
|
1741
|
+
* Encode blocks into one (uncompressed) kwsparse image. `blocks` are
|
|
1742
|
+
* [index, data] pairs in any order; all-zero blocks are dropped.
|
|
1743
|
+
*/
|
|
1744
|
+
export declare function encodeKwsparse({ size, blockSize, blocks }: {
|
|
1745
|
+
size: number;
|
|
1746
|
+
blockSize?: number;
|
|
1747
|
+
blocks: Iterable<[number, Uint8Array]>;
|
|
1748
|
+
}): Uint8Array;
|
|
1749
|
+
/** Parse an uncompressed kwsparse image (see gunzipIfNeeded). The result views `bytes`. */
|
|
1750
|
+
export declare function decodeKwsparse(bytes: Uint8Array | ArrayBuffer): KwsparseImage;
|
|
1751
|
+
/** Gunzip (DecompressionStream: browsers and Node) if the bytes are gzip. */
|
|
1752
|
+
export declare function gunzipIfNeeded(bytes: Uint8Array | ArrayBuffer): Promise<Uint8Array>;
|
|
1753
|
+
/** Decode a kwsparse image, gzipped or not. */
|
|
1754
|
+
export declare function readKwsparse(bytes: Uint8Array | ArrayBuffer): Promise<KwsparseImage>;
|
|
1755
|
+
/**
|
|
1756
|
+
* gzip parts (e.g. CowDisk.exportParts()) with CompressionStream into a
|
|
1757
|
+
* Blob. The output is not byte-for-byte reproducible across engines; the
|
|
1758
|
+
* build tool uses zlib for that.
|
|
1759
|
+
*/
|
|
1760
|
+
export declare function gzipBlob(parts: BlobPart[]): Promise<Blob>;
|
|
1761
|
+
export declare const F_RO = 1, F_FLUSH = 2, F_DISCARD = 4, F_WRITE_ZEROES = 8;
|
|
1762
|
+
/** A result that is either ready now or arrives later. */
|
|
1763
|
+
export type MaybePromise<T> = T | Promise<T>;
|
|
1764
|
+
/**
|
|
1765
|
+
* A kwblk disk (/dev/wda, wdb, ... in the order given). Byte offsets and
|
|
1766
|
+
* sizes; `views` are subarrays of the kernel's memory to fill (read) or
|
|
1767
|
+
* take the data from (write). A method either completes synchronously or
|
|
1768
|
+
* returns a promise. It must not touch the views after that promise
|
|
1769
|
+
* settles.
|
|
1770
|
+
*/
|
|
1771
|
+
export interface BlockDevice {
|
|
1772
|
+
/** Size in bytes (a multiple of 512). */
|
|
1773
|
+
size: number;
|
|
1774
|
+
/** F_FLUSH | F_DISCARD | F_WRITE_ZEROES | F_RO. */
|
|
1775
|
+
flags?: number;
|
|
1776
|
+
readOnly?: boolean;
|
|
1777
|
+
/** Logical block size, default 512. */
|
|
1778
|
+
blockSize?: number;
|
|
1779
|
+
read(off: number, views: Uint8Array[]): MaybePromise<void>;
|
|
1780
|
+
write(off: number, views: Uint8Array[]): MaybePromise<unknown>;
|
|
1781
|
+
flush?(): MaybePromise<unknown>;
|
|
1782
|
+
discard?(off: number, len: number): MaybePromise<unknown>;
|
|
1783
|
+
writeZeroes?(off: number, len: number): MaybePromise<unknown>;
|
|
1784
|
+
/**
|
|
1785
|
+
* Flushes reach storage that outlives the host process or page (a file,
|
|
1786
|
+
* IndexedDB). Kernel.requestSync() waits only for such disks, which must
|
|
1787
|
+
* also provide flushSeq and whenFlushed.
|
|
1788
|
+
*/
|
|
1789
|
+
readonly persistent?: boolean;
|
|
1790
|
+
/** Number of flushes issued so far (see FlushTracker). */
|
|
1791
|
+
readonly flushSeq?: number;
|
|
1792
|
+
/** Resolves once a flush issued after the `after`-th one has completed successfully. */
|
|
1793
|
+
whenFlushed?(after: number): Promise<void>;
|
|
1794
|
+
/** A save in flight, if any (CowDisk): requestSync() waits for it when the kernel is not running. */
|
|
1795
|
+
readonly saving?: Promise<void> | null;
|
|
1796
|
+
/**
|
|
1797
|
+
* Snapshot support: which disk this is and its write generation now.
|
|
1798
|
+
* Throws if the disk cannot be part of a snapshot (its writes live only
|
|
1799
|
+
* in this process's memory). A disk without it cannot be in a snapshot.
|
|
1800
|
+
*/
|
|
1801
|
+
snapshotState?(): DiskSnapshotState;
|
|
1802
|
+
/**
|
|
1803
|
+
* At a snapshot's consistent point (the kernel parked, no request in
|
|
1804
|
+
* flight; synchronous): make the current content durable and return
|
|
1805
|
+
* its state. `done` settles when it is durable (a failure fails the
|
|
1806
|
+
* snapshot). The next write starts a new generation.
|
|
1807
|
+
*/
|
|
1808
|
+
snapshotSeal?(): {
|
|
1809
|
+
state: DiskSnapshotState;
|
|
1810
|
+
done: Promise<void>;
|
|
1811
|
+
};
|
|
1812
|
+
}
|
|
1813
|
+
/** What a snapshot records about a disk (BlockDevice.snapshotState). */
|
|
1814
|
+
export interface DiskSnapshotState {
|
|
1815
|
+
/** For messages: a path or a store name. */
|
|
1816
|
+
name: string;
|
|
1817
|
+
/** Which disk: stays the same across processes for the same content source. */
|
|
1818
|
+
identity: string;
|
|
1819
|
+
/** Write generation: differs whenever the content may differ. */
|
|
1820
|
+
gen: number;
|
|
1821
|
+
/** What changes when another program writes the disk (a file's size and mtime), if known. */
|
|
1822
|
+
stamp?: string;
|
|
1823
|
+
}
|
|
1824
|
+
/** Block I/O counters of one kernel (Kernel.block.stats). */
|
|
1825
|
+
export interface BlockStats {
|
|
1826
|
+
reads: number;
|
|
1827
|
+
writes: number;
|
|
1828
|
+
flushes: number;
|
|
1829
|
+
discards: number;
|
|
1830
|
+
async: number;
|
|
1831
|
+
bytesRead: number;
|
|
1832
|
+
bytesWritten: number;
|
|
1833
|
+
}
|
|
1834
|
+
declare class BlockHost {
|
|
1835
|
+
k: Kernel;
|
|
1836
|
+
disks: BlockDevice[];
|
|
1837
|
+
/** Completed async requests (BigInt pointers). */
|
|
1838
|
+
done: bigint[];
|
|
1839
|
+
inflight: number;
|
|
1840
|
+
stats: BlockStats;
|
|
1841
|
+
/**
|
|
1842
|
+
* @param kernel the Kernel (needs dv(), u8(), irqAddr, wake(), log)
|
|
1843
|
+
* @param disks backends; index i becomes /dev/wd('a'+i)
|
|
1844
|
+
*/
|
|
1845
|
+
constructor(kernel: Kernel, disks?: BlockDevice[]);
|
|
1846
|
+
imports(): Record<string, unknown>;
|
|
1847
|
+
submit(reqPtr: bigint): number;
|
|
1848
|
+
raise(): void;
|
|
1849
|
+
}
|
|
1850
|
+
/**
|
|
1851
|
+
* Counts flushes: flushSeq is the number of flushes issued, and
|
|
1852
|
+
* whenFlushed(n) resolves once a flush issued after the n-th one has
|
|
1853
|
+
* completed successfully. Flushes of one disk complete in order.
|
|
1854
|
+
*/
|
|
1855
|
+
export declare class FlushTracker {
|
|
1856
|
+
flushSeq: number;
|
|
1857
|
+
flushedSeq: number;
|
|
1858
|
+
waiters: Array<{
|
|
1859
|
+
after: number;
|
|
1860
|
+
resolve: () => void;
|
|
1861
|
+
}>;
|
|
1862
|
+
/** A flush starts: its sequence number. */
|
|
1863
|
+
begin(): number;
|
|
1864
|
+
/** Flush `seq` completed successfully. */
|
|
1865
|
+
done(seq: number): void;
|
|
1866
|
+
whenFlushed(after: number): Promise<void>;
|
|
1867
|
+
}
|
|
1868
|
+
/** Overlay value of a block that reads as zeros (stored as an empty record). */
|
|
1869
|
+
export declare const ZERO_BLOCK: Uint8Array;
|
|
1870
|
+
/** A read-only disk image: the base of a CowDisk. */
|
|
1871
|
+
export interface DiskBase {
|
|
1872
|
+
size: number;
|
|
1873
|
+
/** Identifies the image's content (e.g. URL + size + ETag); a store refuses or drops an overlay saved for another one. */
|
|
1874
|
+
identity?: string;
|
|
1875
|
+
/** The base reads as all zeros (ZeroBase): discarding a block deletes its record instead of storing zeros. */
|
|
1876
|
+
zero?: boolean;
|
|
1877
|
+
/** Block indices with content, ascending (SparseBase; used by exportParts). */
|
|
1878
|
+
keys?(): number[];
|
|
1879
|
+
read(off: number, len: number): MaybePromise<Uint8Array>;
|
|
1880
|
+
}
|
|
1881
|
+
/** What OverlayStore.open() found. */
|
|
1882
|
+
export interface StoreIndex {
|
|
1883
|
+
/** Block numbers that have a record. */
|
|
1884
|
+
keys: Set<number>;
|
|
1885
|
+
/** The store was seeded (a data disk, see web/disk.ts). */
|
|
1886
|
+
initialized: boolean;
|
|
1887
|
+
/** The store belongs to this other identity and was left alone ("refuse", or a read-only open). */
|
|
1888
|
+
mismatch?: string;
|
|
1889
|
+
/** The store belonged to this other identity and was cleared ("clear"). */
|
|
1890
|
+
cleared?: string;
|
|
1891
|
+
/** The write generation saved with the blocks (save()'s `meta`), if the store keeps one. */
|
|
1892
|
+
gen?: number;
|
|
1893
|
+
/** A random id the store chose when it was created, seeded or cleared, if it keeps one. */
|
|
1894
|
+
uid?: string;
|
|
1895
|
+
}
|
|
1896
|
+
/**
|
|
1897
|
+
* Persistence for a CowDisk overlay: records of 4 KiB blocks by index, an
|
|
1898
|
+
* empty record for a block that reads as zeros. IdbStore (web/disk.ts) is
|
|
1899
|
+
* the IndexedDB one. Every save must be atomic (one transaction), so the
|
|
1900
|
+
* stored state is always the state after some complete flush.
|
|
1901
|
+
*/
|
|
1902
|
+
export interface OverlayStore {
|
|
1903
|
+
/** e.g. "kwdisk:alpine", for messages. */
|
|
1904
|
+
readonly name?: string;
|
|
1905
|
+
/** Read the index (block numbers, not data). onMismatch: what to do with a store of another identity (default "refuse"). */
|
|
1906
|
+
open(identity: string, opts?: {
|
|
1907
|
+
onMismatch?: "clear" | "refuse";
|
|
1908
|
+
write?: boolean;
|
|
1909
|
+
}): Promise<StoreIndex>;
|
|
1910
|
+
/** The records of these blocks (absent ones are missing from the map). */
|
|
1911
|
+
getBlocks(blocks: number[]): Promise<Map<number, Uint8Array>>;
|
|
1912
|
+
/** One atomic transaction: put these records, delete those, and record `meta.gen` (the disk's write generation) if given. */
|
|
1913
|
+
save(puts: Array<[number, Uint8Array]>, dels: number[], meta?: {
|
|
1914
|
+
gen: number;
|
|
1915
|
+
}): Promise<void>;
|
|
1916
|
+
/** Delete everything. */
|
|
1917
|
+
clear(): Promise<void>;
|
|
1918
|
+
close?(): Promise<void>;
|
|
1919
|
+
}
|
|
1920
|
+
/** A base that reads as zeros (the data disk: its content is all in the store). */
|
|
1921
|
+
export declare class ZeroBase implements DiskBase {
|
|
1922
|
+
size: number;
|
|
1923
|
+
readonly zero = true;
|
|
1924
|
+
identity: string;
|
|
1925
|
+
constructor(size: number);
|
|
1926
|
+
read(_off: number, len: number): Uint8Array;
|
|
1927
|
+
}
|
|
1928
|
+
/** A base made of a few non-zero 4 KiB blocks (a decoded kwsparse image, or a Map). */
|
|
1929
|
+
export declare class SparseBase implements DiskBase {
|
|
1930
|
+
size: number;
|
|
1931
|
+
blocks: Map<number, Uint8Array>;
|
|
1932
|
+
identity: string;
|
|
1933
|
+
constructor(size: number, blocks: Map<number, Uint8Array>);
|
|
1934
|
+
static fromKwsparse(img: KwsparseImage): SparseBase;
|
|
1935
|
+
read(off: number, len: number): Uint8Array;
|
|
1936
|
+
keys(): number[];
|
|
1937
|
+
}
|
|
1938
|
+
export interface CowDiskOptions {
|
|
1939
|
+
/** Persistence for the overlay (loaded lazily after open()). */
|
|
1940
|
+
store?: OverlayStore | null;
|
|
1941
|
+
/** Host diagnostics; default console.warn. */
|
|
1942
|
+
log?: (msg: string) => void;
|
|
1943
|
+
/** A save failed (e.g. QuotaExceededError); the flush fails with EIO too. */
|
|
1944
|
+
onError?: (err: unknown) => void;
|
|
1945
|
+
}
|
|
1946
|
+
export interface CowDiskStats {
|
|
1947
|
+
/** Store read requests and the blocks they asked for (readahead included). */
|
|
1948
|
+
storeReads: number;
|
|
1949
|
+
storeBlocksRead: number;
|
|
1950
|
+
/** Blocks fetched ahead of a read, and reads served from them. */
|
|
1951
|
+
aheadBlocks: number;
|
|
1952
|
+
aheadHits: number;
|
|
1953
|
+
/** Committed saves, blocks put and records deleted by them. */
|
|
1954
|
+
saves: number;
|
|
1955
|
+
blocksSaved: number;
|
|
1956
|
+
blocksDeleted: number;
|
|
1957
|
+
/** Partial writes of blocks not in memory (read-modify-write). */
|
|
1958
|
+
rmw: number;
|
|
1959
|
+
saveErrors: number;
|
|
1960
|
+
}
|
|
1961
|
+
/**
|
|
1962
|
+
* Copy-on-write overlay over a read-only base, optionally persisted.
|
|
1963
|
+
*
|
|
1964
|
+
* Invariants, per block b:
|
|
1965
|
+
* mem.has(b) the newest content is in memory (always so without a
|
|
1966
|
+
* store; with one: written since the last committed save of b)
|
|
1967
|
+
* stored.has(b) the store has a record for b (used when !mem.has(b))
|
|
1968
|
+
* otherwise the base has the content.
|
|
1969
|
+
* A buffer handed to an in-flight save is frozen: a write copies it first,
|
|
1970
|
+
* so the save sees exactly what it was given. A block leaves memory only
|
|
1971
|
+
* when the save transaction that contains it has committed and it was not
|
|
1972
|
+
* written again meanwhile.
|
|
1973
|
+
*/
|
|
1974
|
+
export declare class CowDisk implements BlockDevice {
|
|
1975
|
+
#private;
|
|
1976
|
+
base: DiskBase;
|
|
1977
|
+
size: number;
|
|
1978
|
+
flags: number;
|
|
1979
|
+
store: OverlayStore | null;
|
|
1980
|
+
log: (msg: string) => void;
|
|
1981
|
+
onError: ((err: unknown) => void) | null;
|
|
1982
|
+
/** Block -> Uint8Array(4096) | ZERO_BLOCK. */
|
|
1983
|
+
mem: Map<number, Uint8Array>;
|
|
1984
|
+
/** Blocks with a record in the store. */
|
|
1985
|
+
stored: Set<number>;
|
|
1986
|
+
/** Blocks in mem not yet handed to a save. */
|
|
1987
|
+
dirty: Set<number>;
|
|
1988
|
+
/** Buffers an in-flight save holds. */
|
|
1989
|
+
frozen: WeakSet<Uint8Array>;
|
|
1990
|
+
/** Block -> store read in flight. */
|
|
1991
|
+
loading: Map<number, Promise<Uint8Array>>;
|
|
1992
|
+
/**
|
|
1993
|
+
* Readahead: store records fetched with a read that missed, for the
|
|
1994
|
+
* blocks after it. A read of one consumes it, a write drops it (so it
|
|
1995
|
+
* always equals the store's record). Each store read is one transaction,
|
|
1996
|
+
* and the guest often reads metadata one block at a time (ext4 reads its
|
|
1997
|
+
* orphan file, 256 blocks, that way at every mount); in WebKit every
|
|
1998
|
+
* IndexedDB transaction is a round trip to another process.
|
|
1999
|
+
*/
|
|
2000
|
+
ahead: Map<number, Uint8Array>;
|
|
2001
|
+
/** Blocks being fetched ahead; a write removes them, so a stale fetch is not kept. */
|
|
2002
|
+
aheadPending: Set<number>;
|
|
2003
|
+
/** Block -> tail of the asynchronous writes on it. */
|
|
2004
|
+
busy: Map<number, Promise<void>>;
|
|
2005
|
+
/** The last flush in flight (flushes are chained). */
|
|
2006
|
+
saving: Promise<void> | null;
|
|
2007
|
+
/** detach(): flushes no longer reach the store. */
|
|
2008
|
+
saveDisabled: boolean;
|
|
2009
|
+
flushes: FlushTracker;
|
|
2010
|
+
stats: CowDiskStats;
|
|
2011
|
+
/** Set by openDataDisk: why this disk is not the persistent one (another tab, a format mismatch). */
|
|
2012
|
+
notice?: string;
|
|
2013
|
+
/** Set by openDataDisk: the store was created from the template in this session. */
|
|
2014
|
+
seeded: boolean;
|
|
2015
|
+
/** Set by openDataDisk: the store's identity. */
|
|
2016
|
+
identity?: string;
|
|
2017
|
+
/** Write generation (snapshotState): bumped by the first write after open() and after each snapshotSeal(). */
|
|
2018
|
+
gen: number;
|
|
2019
|
+
/** The generation the store has (StoreIndex.gen, then each committed save). */
|
|
2020
|
+
storedGen: number;
|
|
2021
|
+
/** From the store: its id (StoreIndex.uid) and identity. */
|
|
2022
|
+
storeUid?: string;
|
|
2023
|
+
storeIdentity?: string;
|
|
2024
|
+
constructor(base: DiskBase, { store, log, onError }?: CowDiskOptions);
|
|
2025
|
+
/**
|
|
2026
|
+
* Load the store's index (block numbers only, not the data). A store
|
|
2027
|
+
* saved for another base identity is cleared with onMismatch "clear"
|
|
2028
|
+
* (the store logs it), or makes this throw a StoreMismatchError.
|
|
2029
|
+
*/
|
|
2030
|
+
open({ onMismatch }?: {
|
|
2031
|
+
onMismatch?: "clear" | "refuse";
|
|
2032
|
+
}): Promise<this>;
|
|
2033
|
+
/** Take what the store's open() found (openDataDisk opens the store itself). */
|
|
2034
|
+
adoptStore(st: StoreIndex, identity: string): void;
|
|
2035
|
+
/** Is every flush saved somewhere that outlives the page (a store that is attached)? */
|
|
2036
|
+
get persistent(): boolean;
|
|
2037
|
+
get flushSeq(): number;
|
|
2038
|
+
whenFlushed(after: number): Promise<void>;
|
|
2039
|
+
/** Number of blocks that differ from the base (stored or in memory). */
|
|
2040
|
+
get overlayBlocks(): number;
|
|
2041
|
+
/** Bytes of block data held in memory. */
|
|
2042
|
+
get memBytes(): number;
|
|
2043
|
+
read(off: number, views: Uint8Array[]): MaybePromise<void>;
|
|
2044
|
+
static readonly RA_MIN = 8;
|
|
2045
|
+
static readonly RA_MAX = 128;
|
|
2046
|
+
/** Most blocks kept ahead (4 MiB); the oldest go first. */
|
|
2047
|
+
static readonly AHEAD_MAX = 1024;
|
|
2048
|
+
write(off: number, views: Uint8Array[]): MaybePromise<unknown>;
|
|
2049
|
+
discard(off: number, len: number): MaybePromise<unknown>;
|
|
2050
|
+
writeZeroes(off: number, len: number): MaybePromise<unknown>;
|
|
2051
|
+
/**
|
|
2052
|
+
* Save every block written so far in one store transaction; the flush
|
|
2053
|
+
* completes when it has committed. Flushes are chained: one issued while
|
|
2054
|
+
* a save is in flight waits for it (even with nothing new to save). On a
|
|
2055
|
+
* failed save the blocks are dirty again (the next flush retries them)
|
|
2056
|
+
* and the flush fails (EIO in the guest).
|
|
2057
|
+
*/
|
|
2058
|
+
flush(): MaybePromise<unknown>;
|
|
2059
|
+
snapshotState(): DiskSnapshotState;
|
|
2060
|
+
/**
|
|
2061
|
+
* Take the dirty blocks now (no request is in flight, so no flush is
|
|
2062
|
+
* queued) and save them with the current generation; later writes go
|
|
2063
|
+
* to the next generation and later saves.
|
|
2064
|
+
*/
|
|
2065
|
+
snapshotSeal(): {
|
|
2066
|
+
state: DiskSnapshotState;
|
|
2067
|
+
done: Promise<void>;
|
|
2068
|
+
};
|
|
2069
|
+
/** Stop saving to the store (before replacing or clearing it); the running kernel's further writes stay in memory. */
|
|
2070
|
+
detach(): void;
|
|
2071
|
+
/** Drop all local changes (memory and persisted). Only while the kernel is not running. */
|
|
2072
|
+
reset(): Promise<void>;
|
|
2073
|
+
/**
|
|
2074
|
+
* The disk's current content as a kwsparse image (uncompressed), in
|
|
2075
|
+
* parts (Blobs, so a browser can keep large exports out of the JS heap;
|
|
2076
|
+
* gzipBlob() compresses them). Reads the store in batches. The base must
|
|
2077
|
+
* be a ZeroBase or a SparseBase.
|
|
2078
|
+
*/
|
|
2079
|
+
exportParts({ batch }?: {
|
|
2080
|
+
batch?: number;
|
|
2081
|
+
}): Promise<{
|
|
2082
|
+
size: number;
|
|
2083
|
+
blocks: number;
|
|
2084
|
+
parts: BlobPart[];
|
|
2085
|
+
}>;
|
|
2086
|
+
}
|
|
2087
|
+
export interface HttpBaseOptions {
|
|
2088
|
+
/** Fetch granularity (power of two), default 256 KiB. */
|
|
2089
|
+
chunkSize?: number;
|
|
2090
|
+
/** Largest single Range request, default 4 MiB. */
|
|
2091
|
+
maxRequest?: number;
|
|
2092
|
+
}
|
|
2093
|
+
export declare class HttpBase implements DiskBase {
|
|
2094
|
+
#private;
|
|
2095
|
+
url: string;
|
|
2096
|
+
size: number;
|
|
2097
|
+
identity: string;
|
|
2098
|
+
chunkSize: number;
|
|
2099
|
+
maxChunks: number;
|
|
2100
|
+
/** Chunk index -> data. */
|
|
2101
|
+
chunks: Map<number, Uint8Array>;
|
|
2102
|
+
/** Chunk index -> fetch in flight. */
|
|
2103
|
+
pending: Map<number, Promise<void>>;
|
|
2104
|
+
stats: {
|
|
2105
|
+
requests: number;
|
|
2106
|
+
bytes: number;
|
|
2107
|
+
};
|
|
2108
|
+
static open(url: string, { chunkSize, maxRequest }?: HttpBaseOptions): Promise<HttpBase>;
|
|
2109
|
+
read(off: number, len: number): MaybePromise<Uint8Array>;
|
|
2110
|
+
}
|
|
2111
|
+
/** The guest server's vsock port (kernel/guest/kwtty.c KWTTY_PORT). Privileged, so no unprivileged guest program can take it. */
|
|
2112
|
+
export declare const TTY_PORT = 1022;
|
|
2113
|
+
/** The protocol version this client speaks (OPEN's max_version). */
|
|
2114
|
+
export declare const TTY_VERSION = 1;
|
|
2115
|
+
/** OPENED feature bit: the guest has PIPES, EOF and STDERR. */
|
|
2116
|
+
export declare const TTY_FEATURE_PIPES = 1;
|
|
2117
|
+
/** OPENED feature bit: the guest has CONNECT (connectGuest()). */
|
|
2118
|
+
export declare const TTY_FEATURE_CONNECT = 2;
|
|
2119
|
+
/** The signals kill() can send (kwtty.c has the same list). */
|
|
2120
|
+
export declare const TTY_SIGNALS: readonly ["HUP", "INT", "QUIT", "ILL", "TRAP", "ABRT", "BUS", "FPE", "KILL", "USR1", "SEGV", "USR2", "PIPE", "ALRM", "TERM", "CHLD", "CONT", "STOP", "TSTP", "TTIN", "TTOU", "URG", "XCPU", "XFSZ", "VTALRM", "PROF", "WINCH", "IO", "PWR", "SYS"];
|
|
2121
|
+
export type PtyErrorCode =
|
|
2122
|
+
/** No guest server answered within the timeout (or no OPENED came). */
|
|
2123
|
+
"ETIMEDOUT" |
|
|
2124
|
+
/** A malformed frame, an unknown critical frame, or a version the client does not speak. */
|
|
2125
|
+
"EPROTO" |
|
|
2126
|
+
/** The guest sent ERROR; the message is the guest's (a failed exec or chdir; a guest without PIPES refuses `pty: false`, one without CONNECT refuses connectGuest()). */
|
|
2127
|
+
"EREMOTE" |
|
|
2128
|
+
/** connectGuest(): nothing listens on that TCP port on the guest's 127.0.0.1. */
|
|
2129
|
+
"ECONNREFUSED" |
|
|
2130
|
+
/** The signal was aborted while opening (or, for exec(), while the program ran: it is killed). */
|
|
2131
|
+
"ABORTED" |
|
|
2132
|
+
/** The connection ended before OPENED (or, for exec(), before EXIT). */
|
|
2133
|
+
"ECONNRESET" |
|
|
2134
|
+
/** The kernel exited. */
|
|
2135
|
+
"ECONNABORTED" |
|
|
2136
|
+
/** write() after the session ended, or the connection failed under it. */
|
|
2137
|
+
"EPIPE" |
|
|
2138
|
+
/** spawn(), exec() or connect() on an instance created with `vsock: false`. */
|
|
2139
|
+
"ENODEV" |
|
|
2140
|
+
/** exec(): stdout or stderr went over `maxBuffer` (the program is killed). */
|
|
2141
|
+
"ENOBUFS";
|
|
2142
|
+
/** Why a pty could not be spawned, or failed. */
|
|
2143
|
+
export declare class PtyError extends Error {
|
|
2144
|
+
readonly code: PtyErrorCode;
|
|
2145
|
+
constructor(code: PtyErrorCode, message: string, cause?: unknown);
|
|
2146
|
+
}
|
|
2147
|
+
/** A window size; pixels are 0 when unknown. */
|
|
2148
|
+
export interface PtySize {
|
|
2149
|
+
cols: number;
|
|
2150
|
+
rows: number;
|
|
2151
|
+
xpixel?: number;
|
|
2152
|
+
ypixel?: number;
|
|
2153
|
+
}
|
|
2154
|
+
/** What spawn() on a pty, spawn() on pipes and exec() take. */
|
|
2155
|
+
export interface SpawnOptions {
|
|
2156
|
+
/** The program's working directory. Default root's home. */
|
|
2157
|
+
cwd?: string;
|
|
2158
|
+
/** Extra environment, applied after the defaults (HOME, USER, LOGNAME, SHELL, PATH, and TERM on a pty), so it may override them. */
|
|
2159
|
+
env?: Record<string, string>;
|
|
2160
|
+
/** The guest server's port. Default TTY_PORT (1022). */
|
|
2161
|
+
port?: number;
|
|
2162
|
+
/** How long to wait for the guest server, in ms: connect retries (it may not be up yet) and the handshake together. Default 30000. */
|
|
2163
|
+
timeout?: number;
|
|
2164
|
+
/** Aborts spawning (PtyError ABORTED). It has no effect once the program runs, except in exec(). */
|
|
2165
|
+
signal?: AbortSignal;
|
|
2166
|
+
}
|
|
2167
|
+
export interface PtyOptions extends SpawnOptions, Partial<PtySize> {
|
|
2168
|
+
/** On a pty (the default). */
|
|
2169
|
+
pty?: true;
|
|
2170
|
+
/** Default 80 columns by 24 rows. */
|
|
2171
|
+
cols?: number;
|
|
2172
|
+
rows?: number;
|
|
2173
|
+
/** TERM for the program (printable ASCII, at most 64 bytes). Default "xterm-256color". */
|
|
2174
|
+
term?: string;
|
|
2175
|
+
}
|
|
2176
|
+
/** spawn() on pipes: stdin, stdout and stderr are pipes, with no pty (and no TERM unless `env` sets it). */
|
|
2177
|
+
export interface PipeOptions extends SpawnOptions {
|
|
2178
|
+
pty: false;
|
|
2179
|
+
}
|
|
2180
|
+
export interface ExecOptions extends SpawnOptions {
|
|
2181
|
+
/** Bytes for stdin (strings are UTF-8), then EOF. Default: EOF at once. */
|
|
2182
|
+
input?: Uint8Array | string;
|
|
2183
|
+
/** "utf8" (the default): stdout and stderr as strings; "buffer": as bytes. */
|
|
2184
|
+
encoding?: "utf8" | "buffer";
|
|
2185
|
+
/** The most bytes stdout and stderr may hold, each; beyond it the program gets SIGKILL and exec() rejects with ENOBUFS. Default 64 MiB. */
|
|
2186
|
+
maxBuffer?: number;
|
|
2187
|
+
/** Also aborts the run: the program gets SIGKILL and exec() rejects with ABORTED. */
|
|
2188
|
+
signal?: AbortSignal;
|
|
2189
|
+
}
|
|
2190
|
+
/** How exec()'s program ended, and what it printed. */
|
|
2191
|
+
export interface ExecResult<T extends string | Uint8Array = string> {
|
|
2192
|
+
stdout: T;
|
|
2193
|
+
stderr: T;
|
|
2194
|
+
/** The exit status, or null when a signal ended the program. */
|
|
2195
|
+
exitCode: number | null;
|
|
2196
|
+
/** The signal's number in the guest, or null when the program exited. */
|
|
2197
|
+
signal: number | null;
|
|
2198
|
+
}
|
|
2199
|
+
export type PtyEnd =
|
|
2200
|
+
/** The program exited with `code`. */
|
|
2201
|
+
{
|
|
2202
|
+
type: "exit";
|
|
2203
|
+
code: number;
|
|
2204
|
+
} |
|
|
2205
|
+
/** The program was killed by `signal` (its number in the guest). */
|
|
2206
|
+
{
|
|
2207
|
+
type: "signal";
|
|
2208
|
+
signal: number;
|
|
2209
|
+
coreDumped: boolean;
|
|
2210
|
+
} |
|
|
2211
|
+
/** The host called close(). */
|
|
2212
|
+
{
|
|
2213
|
+
type: "closed";
|
|
2214
|
+
} |
|
|
2215
|
+
/** EOF or a reset without EXIT, or the kernel exited. */
|
|
2216
|
+
{
|
|
2217
|
+
type: "lost";
|
|
2218
|
+
};
|
|
2219
|
+
export interface Pty extends AsyncDisposable {
|
|
2220
|
+
/** The program's pid in the guest. */
|
|
2221
|
+
readonly pid: number;
|
|
2222
|
+
/** The pty's number: the program's terminal is /dev/pts/<pts>. */
|
|
2223
|
+
readonly pts: number;
|
|
2224
|
+
/** The size last set (spawn options, then resize()). */
|
|
2225
|
+
readonly cols: number;
|
|
2226
|
+
readonly rows: number;
|
|
2227
|
+
/** The exit status once `ended` settled with an exit, else null. */
|
|
2228
|
+
readonly exitCode: number | null;
|
|
2229
|
+
/** The protocol version both sides agreed on. */
|
|
2230
|
+
readonly version: number;
|
|
2231
|
+
/** The guest's feature bits (TTY_FEATURE_PIPES). */
|
|
2232
|
+
readonly features: number;
|
|
2233
|
+
/**
|
|
2234
|
+
* What the pty prints. A pull stream: vsock credit follows what is read,
|
|
2235
|
+
* so keep reading, or the guest program blocks once the window is full.
|
|
2236
|
+
* It ends after EXIT, close() or a lost connection, and errors with the
|
|
2237
|
+
* PtyError that `ended` rejects with. Cancelling it discards the
|
|
2238
|
+
* rest, so `ended` still settles.
|
|
2239
|
+
*/
|
|
2240
|
+
readonly output: ReadableStream<Uint8Array>;
|
|
2241
|
+
/** Type into the pty. Strings are UTF-8. Split into DATA frames of at most 4096 bytes; resolves once they are sent. */
|
|
2242
|
+
write(data: Uint8Array | string): Promise<void>;
|
|
2243
|
+
/** Set the window size (the foreground process gets SIGWINCH). Ordered with write(). */
|
|
2244
|
+
resize(cols: number, rows: number, xpixel?: number, ypixel?: number): void;
|
|
2245
|
+
/**
|
|
2246
|
+
* Send a signal to the program ("SIGTERM" or "TERM"; default SIGHUP).
|
|
2247
|
+
* `ended` then reports how it ended. Ordered with write(); a no-op once
|
|
2248
|
+
* the pty has ended. Throws a RangeError for an unknown name.
|
|
2249
|
+
*/
|
|
2250
|
+
kill(signal?: string): void;
|
|
2251
|
+
/** Hang up (the session gets SIGHUP): closes the connection both ways. Resolves once the connection is gone. */
|
|
2252
|
+
close(): Promise<void>;
|
|
2253
|
+
/**
|
|
2254
|
+
* How the session ended. Settles once `output` has been read up to the
|
|
2255
|
+
* end (EXIT comes behind the shell's last output), or at close().
|
|
2256
|
+
* Rejects with a PtyError (EREMOTE, EPROTO) if the session failed.
|
|
2257
|
+
*/
|
|
2258
|
+
readonly ended: Promise<PtyEnd>;
|
|
2259
|
+
/** `await using`: close(). */
|
|
2260
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
2261
|
+
}
|
|
2262
|
+
/** A program on pipes: spawn(file, args, { pty: false }). */
|
|
2263
|
+
export interface Subprocess extends AsyncDisposable {
|
|
2264
|
+
/** The program's pid in the guest, the leader of its own session. */
|
|
2265
|
+
readonly pid: number;
|
|
2266
|
+
/** The exit status once `ended` settled with an exit, else null. */
|
|
2267
|
+
readonly exitCode: number | null;
|
|
2268
|
+
/** The protocol version both sides agreed on. */
|
|
2269
|
+
readonly version: number;
|
|
2270
|
+
/** The guest's feature bits (TTY_FEATURE_PIPES). */
|
|
2271
|
+
readonly features: number;
|
|
2272
|
+
/**
|
|
2273
|
+
* The program's stdin. Strings are UTF-8, sent in DATA frames of at most
|
|
2274
|
+
* 4096 bytes. close() sends EOF (the program reads end of file); a write
|
|
2275
|
+
* after the session ended rejects with EPIPE.
|
|
2276
|
+
*/
|
|
2277
|
+
readonly stdin: WritableStream<Uint8Array | string>;
|
|
2278
|
+
/**
|
|
2279
|
+
* What the program writes to stdout and stderr, byte for byte. Pull
|
|
2280
|
+
* streams on one connection: the connection is read while either is
|
|
2281
|
+
* read, and output for the other is held until it is read, so read both,
|
|
2282
|
+
* or cancel the one you do not want (that discards it). They end after
|
|
2283
|
+
* EXIT, close() or a lost connection.
|
|
2284
|
+
*/
|
|
2285
|
+
readonly stdout: ReadableStream<Uint8Array>;
|
|
2286
|
+
readonly stderr: ReadableStream<Uint8Array>;
|
|
2287
|
+
/** Send a signal to the program ("SIGINT" or "INT"; default SIGTERM). As Pty.kill(). */
|
|
2288
|
+
kill(signal?: string): void;
|
|
2289
|
+
/** Hang up: the program's process group gets SIGHUP, and the connection closes both ways. */
|
|
2290
|
+
close(): Promise<void>;
|
|
2291
|
+
/** How the session ended. Settles once stdout and stderr have been read (or cancelled) up to EXIT, or at close(). */
|
|
2292
|
+
readonly ended: Promise<PtyEnd>;
|
|
2293
|
+
/** `await using`: close(). */
|
|
2294
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
2295
|
+
}
|
|
2296
|
+
/** One frame as received. */
|
|
2297
|
+
export interface TtyFrame {
|
|
2298
|
+
type: number;
|
|
2299
|
+
flags: number;
|
|
2300
|
+
payload: Uint8Array;
|
|
2301
|
+
}
|
|
2302
|
+
/** A frame: header and payload (copied). */
|
|
2303
|
+
export declare function encodeTtyFrame(type: number, payload?: Uint8Array, flags?: number): Uint8Array;
|
|
2304
|
+
/** RESIZE's payload (on the wire rows come first, as in struct winsize). */
|
|
2305
|
+
export declare function encodeTtyResize(s: PtySize): Uint8Array;
|
|
2306
|
+
/**
|
|
2307
|
+
* OPEN's payload: max_version, the size, then TERM, one ENV option per
|
|
2308
|
+
* entry, ARG options (`file`, then `args`), CWD, PIPES and CONNECT. With
|
|
2309
|
+
* `pipes` or `connect`, TERM goes only when `term` is given. Throws a RangeError for values the
|
|
2310
|
+
* guest would refuse.
|
|
2311
|
+
*/
|
|
2312
|
+
export declare function encodeTtyOpen(opts: PtySize & {
|
|
2313
|
+
term?: string;
|
|
2314
|
+
env?: Record<string, string>;
|
|
2315
|
+
cwd?: string;
|
|
2316
|
+
file?: string;
|
|
2317
|
+
args?: readonly string[];
|
|
2318
|
+
pipes?: boolean;
|
|
2319
|
+
connect?: number;
|
|
2320
|
+
}): Uint8Array;
|
|
2321
|
+
/**
|
|
2322
|
+
* Splits a byte stream into frames, however it is chunked. push() what
|
|
2323
|
+
* arrives, then take whole frames with next(). A payload within one chunk
|
|
2324
|
+
* is a view of it, else a copy.
|
|
2325
|
+
*/
|
|
2326
|
+
export declare class TtyFrameParser {
|
|
2327
|
+
#private;
|
|
2328
|
+
/** Bytes held that do not make a whole frame yet. */
|
|
2329
|
+
get buffered(): number;
|
|
2330
|
+
push(chunk: Uint8Array): void;
|
|
2331
|
+
/** The next whole frame, without taking it. */
|
|
2332
|
+
peek(): TtyFrame | undefined;
|
|
2333
|
+
/** Take the next whole frame. */
|
|
2334
|
+
next(): TtyFrame | undefined;
|
|
2335
|
+
/** Take every byte held, frames not taken yet included, as they arrived (for a switch to raw bytes). */
|
|
2336
|
+
rest(): Uint8Array;
|
|
2337
|
+
}
|
|
2338
|
+
/**
|
|
2339
|
+
* Run `file` with `args` on a new pty in the guest (no file: root's login
|
|
2340
|
+
* shell; a file without "/" is looked up in PATH): connect to the guest's
|
|
2341
|
+
* kwtty server (retrying while it is not up yet), send OPEN, and wait for
|
|
2342
|
+
* OPENED. Rejects with a PtyError (ETIMEDOUT, EREMOTE with the guest's
|
|
2343
|
+
* message, e.g. a failed exec or chdir, EPROTO, ABORTED, ECONNRESET,
|
|
2344
|
+
* ECONNABORTED), or a RangeError for bad options.
|
|
2345
|
+
*/
|
|
2346
|
+
export declare function spawnPty(vsock: Vsock, file?: string, args?: readonly string[], opts?: PtyOptions): Promise<Pty>;
|
|
2347
|
+
/**
|
|
2348
|
+
* Run `file` with `args` in the guest on pipes (stdin, stdout and stderr;
|
|
2349
|
+
* no file: root's login shell, reading stdin), as spawnPty() otherwise. A
|
|
2350
|
+
* guest without PIPES (a kernel from before them) refuses it: EREMOTE.
|
|
2351
|
+
*/
|
|
2352
|
+
export declare function spawnSubprocess(vsock: Vsock, file?: string, args?: readonly string[], opts?: SpawnOptions): Promise<Subprocess>;
|
|
2353
|
+
/**
|
|
2354
|
+
* Run `file` with `args` on pipes, feed it `input`, and resolve with what
|
|
2355
|
+
* it printed on stdout and stderr and how it ended, once it ended. A
|
|
2356
|
+
* non-zero exit or a signal resolves too. Rejects with a PtyError as
|
|
2357
|
+
* spawnSubprocess(), or ENOBUFS (output over `maxBuffer`), ABORTED (the
|
|
2358
|
+
* signal; the program gets SIGKILL), ECONNRESET (the session was lost:
|
|
2359
|
+
* the kernel exited).
|
|
2360
|
+
*/
|
|
2361
|
+
export declare function execSubprocess(vsock: Vsock, file: string, args?: readonly string[], opts?: ExecOptions & {
|
|
2362
|
+
encoding?: "utf8";
|
|
2363
|
+
}): Promise<ExecResult<string>>;
|
|
2364
|
+
export declare function execSubprocess(vsock: Vsock, file: string, args: readonly string[] | undefined, opts: ExecOptions & {
|
|
2365
|
+
encoding: "buffer";
|
|
2366
|
+
}): Promise<ExecResult<Uint8Array>>;
|
|
2367
|
+
export declare function execSubprocess(vsock: Vsock, file: string, args?: readonly string[], opts?: ExecOptions): Promise<ExecResult<string | Uint8Array>>;
|
|
2368
|
+
/** What connectGuest() takes. */
|
|
2369
|
+
export interface ConnectOptions {
|
|
2370
|
+
/** How long to wait, in ms: for the guest server (connect retries), its TCP connect and the handshake together. Default 30000. */
|
|
2371
|
+
timeout?: number;
|
|
2372
|
+
/** Aborts connecting (PtyError ABORTED). It has no effect once connected: cancel `readable` or call close(). */
|
|
2373
|
+
signal?: AbortSignal;
|
|
2374
|
+
/** The guest server's (kwtty's) vsock port. Default TTY_PORT (1022). */
|
|
2375
|
+
ttyPort?: number;
|
|
2376
|
+
}
|
|
2377
|
+
/**
|
|
2378
|
+
* A raw byte stream to a TCP server in the guest (connectGuest()). It has
|
|
2379
|
+
* the shape of a ByteDuplex (http.ts), so fetchOver() can use it.
|
|
2380
|
+
*/
|
|
2381
|
+
export interface GuestSocket extends AsyncDisposable {
|
|
2382
|
+
/** The guest's TCP port. */
|
|
2383
|
+
readonly port: number;
|
|
2384
|
+
/**
|
|
2385
|
+
* What the server sends. A pull stream: vsock credit follows what is
|
|
2386
|
+
* read. It ends when the server shuts down its sending side (or
|
|
2387
|
+
* closes), and errors with a VsockError on a reset. Cancelling it tells
|
|
2388
|
+
* the guest the host no longer reads, which ends the connection.
|
|
2389
|
+
*/
|
|
2390
|
+
readonly readable: ReadableStream<Uint8Array>;
|
|
2391
|
+
/**
|
|
2392
|
+
* Bytes for the server; a write resolves once its bytes are sent.
|
|
2393
|
+
* close() is a half-close: the server reads EOF and may still send.
|
|
2394
|
+
* abort() resets the connection.
|
|
2395
|
+
*/
|
|
2396
|
+
readonly writable: WritableStream<Uint8Array>;
|
|
2397
|
+
/** Close both ways (what was written is still sent; what was not read is dropped). Resolves once the connection is gone. */
|
|
2398
|
+
close(): Promise<void>;
|
|
2399
|
+
/** Settles once the connection is gone: "closed" (both sides shut down) or "reset". */
|
|
2400
|
+
readonly closed: Promise<"closed" | "reset">;
|
|
2401
|
+
/** `await using`: close(). */
|
|
2402
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
2403
|
+
}
|
|
2404
|
+
/**
|
|
2405
|
+
* Connect to TCP `port` on the guest's 127.0.0.1 through the guest's kwtty
|
|
2406
|
+
* server (CONNECT; retrying while kwtty is not up yet). The guest connects
|
|
2407
|
+
* before it answers, so the promise resolves with a connected GuestSocket,
|
|
2408
|
+
* or rejects with a PtyError: ECONNREFUSED (nothing listens on the port),
|
|
2409
|
+
* EREMOTE (another connect error, with the guest's message, or a guest
|
|
2410
|
+
* without CONNECT), ETIMEDOUT, ABORTED, ECONNRESET, ECONNABORTED, EPROTO;
|
|
2411
|
+
* a RangeError for a port outside 1 to 65535.
|
|
2412
|
+
*/
|
|
2413
|
+
export declare function connectGuest(vsock: Vsock, port: number, opts?: ConnectOptions): Promise<GuestSocket>;
|
|
2414
|
+
/** A kernel: a compiled module, its bytes, a Response, or a URL to fetch (a file path or file: URL on Node). */
|
|
2415
|
+
export type KernelSource = WebAssembly.Module | BytesSource;
|
|
2416
|
+
/** Bytes, a Response, or a URL to fetch (a file path or file: URL on Node). */
|
|
2417
|
+
export type BytesSource = Uint8Array | ArrayBuffer | ArrayBufferView | Response | URL | string;
|
|
2418
|
+
/** Download progress of the kernel or the initramfs. */
|
|
2419
|
+
export interface DownloadProgress {
|
|
2420
|
+
stage: "download";
|
|
2421
|
+
what: "kernel" | "initrd";
|
|
2422
|
+
url: string;
|
|
2423
|
+
/** Bytes so far. */
|
|
2424
|
+
loaded: number;
|
|
2425
|
+
/** Expected bytes, 0 if unknown. */
|
|
2426
|
+
total: number;
|
|
2427
|
+
done: boolean;
|
|
2428
|
+
}
|
|
2429
|
+
export interface LoadOptions {
|
|
2430
|
+
what?: "kernel" | "initrd";
|
|
2431
|
+
onProgress?: (p: DownloadProgress) => void;
|
|
2432
|
+
signal?: AbortSignal;
|
|
2433
|
+
/**
|
|
2434
|
+
* Read a URL or path without fetch, or return undefined to fetch it (the
|
|
2435
|
+
* Node entry reads file: URLs and plain paths from disk).
|
|
2436
|
+
*/
|
|
2437
|
+
readFile?: (src: URL | string) => Promise<Uint8Array> | undefined;
|
|
2438
|
+
}
|
|
2439
|
+
/** Why loading or booting failed: the step that failed. */
|
|
2440
|
+
export type BootFailStage = "support" | "download" | "compile" | "memory" | "boot";
|
|
2441
|
+
/** An error from createKernel() or the loaders, tagged with the step that failed. */
|
|
2442
|
+
export declare class BootError extends Error {
|
|
2443
|
+
stage: BootFailStage;
|
|
2444
|
+
constructor(stage: BootFailStage, message: string, options?: {
|
|
2445
|
+
cause?: unknown;
|
|
2446
|
+
});
|
|
2447
|
+
}
|
|
2448
|
+
/**
|
|
2449
|
+
* Download into memory, reporting progress (`onProgress`). With
|
|
2450
|
+
* content-encoding, content-length counts compressed bytes but the reader
|
|
2451
|
+
* yields decoded ones: x-decoded-length (if the server sends it) is used, else the total
|
|
2452
|
+
* is unknown (0).
|
|
2453
|
+
*/
|
|
2454
|
+
export declare function download(url: URL | string, opts?: LoadOptions): Promise<Uint8Array>;
|
|
2455
|
+
/** Bytes of an initramfs (or any file) from any BytesSource. */
|
|
2456
|
+
export declare function loadBytes(src: BytesSource, opts?: LoadOptions): Promise<Uint8Array>;
|
|
2457
|
+
/**
|
|
2458
|
+
* Compile a kernel from any KernelSource. URLs and Responses are compiled
|
|
2459
|
+
* while they download (WebAssembly.compileStreaming) when the engine has it.
|
|
2460
|
+
*/
|
|
2461
|
+
export declare function loadKernelModule(src: KernelSource, opts?: LoadOptions): Promise<WebAssembly.Module>;
|
|
2462
|
+
/** Events a backend reports for one TCP connection. */
|
|
2463
|
+
export interface NetConnectionEvents {
|
|
2464
|
+
onConnect(): void;
|
|
2465
|
+
onData(data: Uint8Array): void;
|
|
2466
|
+
/** The remote side half-closed (no more data). */
|
|
2467
|
+
onEnd(): void;
|
|
2468
|
+
/** Data written earlier has been sent; `buffered` went down. */
|
|
2469
|
+
onDrain(): void;
|
|
2470
|
+
/** Called once, last; null for a clean close. */
|
|
2471
|
+
onClose(error: Error | null): void;
|
|
2472
|
+
}
|
|
2473
|
+
/** The host side of one TCP connection. */
|
|
2474
|
+
export interface NetConnection {
|
|
2475
|
+
write(data: Uint8Array): void;
|
|
2476
|
+
/** Half-close (the guest sent FIN). */
|
|
2477
|
+
end(): void;
|
|
2478
|
+
/** Abort; no events follow. */
|
|
2479
|
+
destroy(): void;
|
|
2480
|
+
/** Stop delivering onData until resume(). */
|
|
2481
|
+
pause(): void;
|
|
2482
|
+
resume(): void;
|
|
2483
|
+
/** Bytes written but not yet sent. */
|
|
2484
|
+
readonly buffered: number;
|
|
2485
|
+
}
|
|
2486
|
+
/**
|
|
2487
|
+
* Transport for the guest's TCP connections and DNS lookups.
|
|
2488
|
+
*
|
|
2489
|
+
* connect({ host, port }, events) -> NetConnection
|
|
2490
|
+
* lookup(name) -> IPv4 dotted quads; reject with { code: "ENOTFOUND" }
|
|
2491
|
+
* for NXDOMAIN, anything else becomes SERVFAIL
|
|
2492
|
+
* close() (optional) drops every connection and the transport
|
|
2493
|
+
*/
|
|
2494
|
+
export interface NetBackend {
|
|
2495
|
+
connect(addr: {
|
|
2496
|
+
host: string;
|
|
2497
|
+
port: number;
|
|
2498
|
+
}, ev: NetConnectionEvents): NetConnection;
|
|
2499
|
+
lookup(name: string): Promise<string[]>;
|
|
2500
|
+
close?(): void;
|
|
2501
|
+
}
|
|
2502
|
+
export interface NetStackOptions {
|
|
2503
|
+
backend: NetBackend;
|
|
2504
|
+
log?: (msg: string) => void;
|
|
2505
|
+
/** TCP to the gateway (10.0.2.2) goes to 127.0.0.1. Default false. */
|
|
2506
|
+
hostLoopback?: boolean;
|
|
2507
|
+
/** MTU advertised by DHCP (option 26). */
|
|
2508
|
+
mtu?: number;
|
|
2509
|
+
/** The guest's MAC address, default 52:54:00:12:34:56. */
|
|
2510
|
+
mac?: string;
|
|
2511
|
+
}
|
|
2512
|
+
export interface NetStats {
|
|
2513
|
+
rx: number;
|
|
2514
|
+
tx: number;
|
|
2515
|
+
tcpOpened: number;
|
|
2516
|
+
dns: number;
|
|
2517
|
+
}
|
|
2518
|
+
export declare const ip4: (s: string) => number;
|
|
2519
|
+
export declare const ip4str: (n: number) => string;
|
|
2520
|
+
/** FIFO of bytes with random-access reads from the front. */
|
|
2521
|
+
declare class ByteQueue {
|
|
2522
|
+
chunks: Uint8Array[];
|
|
2523
|
+
/** Offset into chunks[0]. */
|
|
2524
|
+
head: number;
|
|
2525
|
+
length: number;
|
|
2526
|
+
push(u8: Uint8Array): void;
|
|
2527
|
+
drop(n: number): void;
|
|
2528
|
+
copyTo(dst: Uint8Array, dstOff: number, offset: number, len: number): void;
|
|
2529
|
+
}
|
|
2530
|
+
interface Segment {
|
|
2531
|
+
sport: number;
|
|
2532
|
+
dport: number;
|
|
2533
|
+
seq: number;
|
|
2534
|
+
ack: number;
|
|
2535
|
+
flags: number;
|
|
2536
|
+
win: number;
|
|
2537
|
+
mss?: number;
|
|
2538
|
+
wscale?: number;
|
|
2539
|
+
}
|
|
2540
|
+
/** What sendTcp needs of a connection (a TcpConn, or a stand-in for a reset). */
|
|
2541
|
+
interface TcpEndpoint {
|
|
2542
|
+
ip: number;
|
|
2543
|
+
port: number;
|
|
2544
|
+
gport: number;
|
|
2545
|
+
rcvNxt: number;
|
|
2546
|
+
sndUna: number;
|
|
2547
|
+
sendq: ByteQueue | null;
|
|
2548
|
+
}
|
|
2549
|
+
declare class TcpConn implements TcpEndpoint {
|
|
2550
|
+
stack: NetStack;
|
|
2551
|
+
key: string;
|
|
2552
|
+
gport: number;
|
|
2553
|
+
ip: number;
|
|
2554
|
+
port: number;
|
|
2555
|
+
irs: number;
|
|
2556
|
+
rcvNxt: number;
|
|
2557
|
+
iss: number;
|
|
2558
|
+
sndUna: number;
|
|
2559
|
+
sndNxt: number;
|
|
2560
|
+
mss: number;
|
|
2561
|
+
sndWscale: number;
|
|
2562
|
+
rcvWscale: number;
|
|
2563
|
+
sndWl: number;
|
|
2564
|
+
sendq: ByteQueue;
|
|
2565
|
+
state: "connecting" | "synrcvd" | "established" | "closed";
|
|
2566
|
+
remoteEof: boolean;
|
|
2567
|
+
finSent: boolean;
|
|
2568
|
+
guestFin: boolean;
|
|
2569
|
+
paused: boolean;
|
|
2570
|
+
rto: number;
|
|
2571
|
+
retries: number;
|
|
2572
|
+
timer: ReturnType<typeof setTimeout> | null;
|
|
2573
|
+
lastWnd: number;
|
|
2574
|
+
handle: NetConnection | undefined;
|
|
2575
|
+
constructor(stack: NetStack, key: string, gport: number, ip: number, port: number, seg: Segment);
|
|
2576
|
+
inFlight(): number;
|
|
2577
|
+
rcvWnd(): number;
|
|
2578
|
+
send(flags: number, seq: number, payloadLen?: number, opts?: Uint8Array | null): void;
|
|
2579
|
+
ack(): void;
|
|
2580
|
+
synAck(): void;
|
|
2581
|
+
/** Send whatever the guest's window allows, then FIN if due. */
|
|
2582
|
+
flush(): void;
|
|
2583
|
+
armTimer(): void;
|
|
2584
|
+
clearTimer(): void;
|
|
2585
|
+
onTimer(): void;
|
|
2586
|
+
connect(): void;
|
|
2587
|
+
refuse(err?: Error | null): void;
|
|
2588
|
+
close(): void;
|
|
2589
|
+
maybeDone(): void;
|
|
2590
|
+
/** A segment from the guest for this connection. */
|
|
2591
|
+
input(seg: Segment, payload: Uint8Array): void;
|
|
2592
|
+
}
|
|
2593
|
+
/**
|
|
2594
|
+
* The host end of the guest's network: pass it as the kernel's `net`
|
|
2595
|
+
* (kwnet) device. Terminates the guest's frames and bridges TCP and DNS to
|
|
2596
|
+
* `opts.backend`.
|
|
2597
|
+
*/
|
|
2598
|
+
export declare class NetStack implements NetDevice {
|
|
2599
|
+
backend: NetBackend;
|
|
2600
|
+
log: ((msg: string) => void) | undefined;
|
|
2601
|
+
hostLoopback: boolean;
|
|
2602
|
+
mtu: number | undefined;
|
|
2603
|
+
/** The guest's MAC. */
|
|
2604
|
+
mac: Uint8Array;
|
|
2605
|
+
gwMac: Uint8Array;
|
|
2606
|
+
guestMac: Uint8Array;
|
|
2607
|
+
net: number;
|
|
2608
|
+
mask: number;
|
|
2609
|
+
gw: number;
|
|
2610
|
+
dns: number;
|
|
2611
|
+
guest: number;
|
|
2612
|
+
tcp: Map<string, TcpConn>;
|
|
2613
|
+
ipId: number;
|
|
2614
|
+
/** Where frames for the guest go (set by attach()). */
|
|
2615
|
+
output: (frame: Uint8Array) => void;
|
|
2616
|
+
stats: NetStats;
|
|
2617
|
+
constructor(opts: NetStackOptions);
|
|
2618
|
+
/** Hook up to a Kernel (core/kernel.ts); called when the guest's driver initialises. */
|
|
2619
|
+
attach(kernel: Kernel): void;
|
|
2620
|
+
/** Frame from the guest. */
|
|
2621
|
+
send(frame: Uint8Array): void;
|
|
2622
|
+
/** Reset every TCP connection (the backend stays usable). */
|
|
2623
|
+
close(): void;
|
|
2624
|
+
emit(frame: Uint8Array): void;
|
|
2625
|
+
backendHost(ip: number): string | null;
|
|
2626
|
+
input(f: Uint8Array): void;
|
|
2627
|
+
arp(f: Uint8Array): void;
|
|
2628
|
+
ipv4(f: Uint8Array): void;
|
|
2629
|
+
/** Ethernet + IPv4 header for a reply to the guest; returns [frame, view]. */
|
|
2630
|
+
ipFrame(src: number, dst: number, proto: number, l4len: number, dstMac?: Uint8Array): [Uint8Array, DataView];
|
|
2631
|
+
l4csum(f: Uint8Array, src: number, dst: number, proto: number, off: number, len: number): number;
|
|
2632
|
+
sendUdp(src: number, sport: number, dst: number, dport: number, payload: Uint8Array, dstMac?: Uint8Array): void;
|
|
2633
|
+
sendTcp(c: TcpEndpoint, flags: number, seq: number, payloadLen: number, opts: Uint8Array | null, wnd: number): void;
|
|
2634
|
+
icmpInput(f: Uint8Array, _dv: DataView, src: number, dst: number, l4: number, end: number): void;
|
|
2635
|
+
icmpUnreachable(f: Uint8Array, l4: number, src: number, dst: number, code: number): void;
|
|
2636
|
+
udpInput(f: Uint8Array, dv: DataView, src: number, dst: number, l4: number, end: number): void;
|
|
2637
|
+
dhcp(p: Uint8Array): void;
|
|
2638
|
+
bytes4(n: number): number[];
|
|
2639
|
+
dnsQuery(q: Uint8Array, src: number, sport: number, dst: number): Promise<void>;
|
|
2640
|
+
tcpInput(f: Uint8Array, dv: DataView, _src: number, dst: number, l4: number, end: number): void;
|
|
2641
|
+
}
|
|
2642
|
+
/** The spec format. A spec may carry `v`; a factory refuses other versions. */
|
|
2643
|
+
export declare const DEVICE_SPEC_VERSION = 1;
|
|
2644
|
+
interface SpecCommon {
|
|
2645
|
+
/** Format version, default DEVICE_SPEC_VERSION. */
|
|
2646
|
+
v?: number;
|
|
2647
|
+
/** If it cannot be built, leave it out (and say why) instead of failing the boot. Later disks move up a letter. */
|
|
2648
|
+
optional?: boolean;
|
|
2649
|
+
}
|
|
2650
|
+
/** A disk image file on the host (Node). */
|
|
2651
|
+
export interface FileDiskSpec extends SpecCommon {
|
|
2652
|
+
kind: "file";
|
|
2653
|
+
/** A path (relative paths are relative to the process's working directory). */
|
|
2654
|
+
path: string;
|
|
2655
|
+
/** Refuse writes. */
|
|
2656
|
+
readOnly?: boolean;
|
|
2657
|
+
/** Writes go to an in-memory overlay and are lost at exit (the CLI's --snapshot). */
|
|
2658
|
+
snapshot?: boolean;
|
|
2659
|
+
}
|
|
2660
|
+
/** An image served over HTTP with Range support, read lazily, under a copy-on-write overlay. */
|
|
2661
|
+
export interface HttpDiskSpec extends SpecCommon {
|
|
2662
|
+
kind: "http";
|
|
2663
|
+
/** An absolute URL (a relative one is resolved against the page before it crosses to a worker). */
|
|
2664
|
+
url: string;
|
|
2665
|
+
chunkSize?: number;
|
|
2666
|
+
/** Browsers: keep the overlay in IndexedDB under this name (openHttpDisk's `name`); else it is in memory. */
|
|
2667
|
+
persist?: string;
|
|
2668
|
+
}
|
|
2669
|
+
/** The persistent data disk (browsers: IndexedDB; see js/web/disk.ts openDataDisk()). */
|
|
2670
|
+
export interface DataDiskSpec extends SpecCommon {
|
|
2671
|
+
kind: "data";
|
|
2672
|
+
/** A kwsparse image (gzipped or not), or "bundled": the kernel module's unkernel.datadisk section. */
|
|
2673
|
+
template: Uint8Array | "bundled";
|
|
2674
|
+
/** "persistent" (default; the caller holds the one-tab lock) or "snapshot" (memory only, e.g. another tab owns it). */
|
|
2675
|
+
mode?: "persistent" | "snapshot";
|
|
2676
|
+
/** Store name and format version (default "kwdata", "v1"). */
|
|
2677
|
+
name?: string;
|
|
2678
|
+
version?: string;
|
|
2679
|
+
snapshotLimit?: number;
|
|
2680
|
+
}
|
|
2681
|
+
export type DiskSpec = FileDiskSpec | HttpDiskSpec | DataDiskSpec;
|
|
2682
|
+
/** The network device: a NetStack over a backend. */
|
|
2683
|
+
export interface NetSpec extends SpecCommon {
|
|
2684
|
+
kind: "net";
|
|
2685
|
+
backend: {
|
|
2686
|
+
kind: "direct";
|
|
2687
|
+
} | {
|
|
2688
|
+
kind: "wisp";
|
|
2689
|
+
servers: string | string[];
|
|
2690
|
+
headers?: Record<string, string>;
|
|
2691
|
+
};
|
|
2692
|
+
/** TCP to the gateway (10.0.2.2) goes to the host's 127.0.0.1 (direct only). */
|
|
2693
|
+
hostLoopback?: boolean;
|
|
2694
|
+
mtu?: number;
|
|
2695
|
+
mac?: string;
|
|
2696
|
+
}
|
|
2697
|
+
export type NetBackendSpec = NetSpec["backend"];
|
|
2698
|
+
/** A disk spec (plain data), not a BlockDevice object. */
|
|
2699
|
+
export declare function isDiskSpec(x: unknown): x is DiskSpec;
|
|
2700
|
+
/** A network spec, not a NetDevice or NetBackend object. */
|
|
2701
|
+
export declare function isNetSpec(x: unknown): x is NetSpec;
|
|
2702
|
+
/** A disk that a spec marked optional could not be built: why. */
|
|
2703
|
+
export interface SkippedDisk {
|
|
2704
|
+
index: number;
|
|
2705
|
+
kind: string;
|
|
2706
|
+
reason: string;
|
|
2707
|
+
}
|
|
2708
|
+
/**
|
|
2709
|
+
* What can be read off a disk from another thread (a WorkerKernel's
|
|
2710
|
+
* disks): the BlockDevice's flags and flush count, and for a CowDisk its
|
|
2711
|
+
* overlay, store and counters.
|
|
2712
|
+
*/
|
|
2713
|
+
export interface DiskState {
|
|
2714
|
+
/** Its index in the `disks` option (/dev/wda is the first disk that was built; skipped ones take no letter). */
|
|
2715
|
+
index: number;
|
|
2716
|
+
kind: string;
|
|
2717
|
+
size: number;
|
|
2718
|
+
readOnly: boolean;
|
|
2719
|
+
/** Flushes reach storage that outlives the host (a file, IndexedDB). */
|
|
2720
|
+
persistent: boolean;
|
|
2721
|
+
flushSeq: number;
|
|
2722
|
+
/** A save is in flight. */
|
|
2723
|
+
saving: boolean;
|
|
2724
|
+
/** CowDisk: blocks that differ from the base (stored or in memory). */
|
|
2725
|
+
overlayBlocks?: number;
|
|
2726
|
+
/** CowDisk: bytes of block data held in memory. */
|
|
2727
|
+
memBytes?: number;
|
|
2728
|
+
/** CowDisk with a store: blocks the store holds, its name, whether it was seeded now, and its identity. */
|
|
2729
|
+
storedBlocks?: number;
|
|
2730
|
+
store?: string;
|
|
2731
|
+
seeded?: boolean;
|
|
2732
|
+
identity?: string;
|
|
2733
|
+
/** CowDisk: why it is not the persistent disk (e.g. "in memory only, started from the template"). */
|
|
2734
|
+
notice?: string;
|
|
2735
|
+
/** CowDisk: saves no longer reach the store (detached before an import or reset). */
|
|
2736
|
+
detached?: boolean;
|
|
2737
|
+
cow?: CowDiskStats;
|
|
2738
|
+
}
|
|
2739
|
+
/**
|
|
2740
|
+
* A kernel or initrd source that crosses a thread: an absolute URL (the
|
|
2741
|
+
* worker fetches it, or reads it from disk on Node: file: URLs), bytes
|
|
2742
|
+
* (transferred), or, for the kernel, a WebAssembly.Module (it survives
|
|
2743
|
+
* postMessage within one process).
|
|
2744
|
+
*/
|
|
2745
|
+
type WorkerSource = string | Uint8Array;
|
|
2746
|
+
/** Everything the worker needs to boot. It loads and compiles the kernel itself. */
|
|
2747
|
+
interface WorkerBootSpec {
|
|
2748
|
+
kernel: WorkerSource | WebAssembly.Module;
|
|
2749
|
+
/** undefined = the module's bundled initramfs (if any), null = none. */
|
|
2750
|
+
initrd: WorkerSource | null | undefined;
|
|
2751
|
+
cmdline?: string;
|
|
2752
|
+
memoryMiB: number;
|
|
2753
|
+
memoryFallbackMiB?: number[];
|
|
2754
|
+
memory64?: boolean;
|
|
2755
|
+
jit?: boolean;
|
|
2756
|
+
consoleSize?: {
|
|
2757
|
+
cols: number;
|
|
2758
|
+
rows: number;
|
|
2759
|
+
};
|
|
2760
|
+
/** Disk and network specs (devices.ts), built by the worker's registry. */
|
|
2761
|
+
disks?: DiskSpec[];
|
|
2762
|
+
net?: NetSpec;
|
|
2763
|
+
/** Milliseconds between stats snapshots while running. */
|
|
2764
|
+
statsIntervalMs: number;
|
|
2765
|
+
/** Milliseconds the owner took to load and compile the kernel, when it did (the worker's stats report it). */
|
|
2766
|
+
compileMs?: number;
|
|
2767
|
+
/**
|
|
2768
|
+
* The display: true (640x480) or the size wanted. For a `display`
|
|
2769
|
+
* function the owner calls it and sends the result here and in
|
|
2770
|
+
* "display-size" messages; the worker answers the kernel from the latest.
|
|
2771
|
+
*/
|
|
2772
|
+
display?: boolean | DisplaySize;
|
|
2773
|
+
/** A sound card: the sink's preferred rate, and whether the owner wants the PCM ("sound-chunk"). */
|
|
2774
|
+
sound?: false | {
|
|
2775
|
+
rate?: number;
|
|
2776
|
+
chunks: boolean;
|
|
2777
|
+
};
|
|
2778
|
+
/** A vsock device: the worker's kernel passes packets ("vsock" both ways); the protocol runs on the owner. */
|
|
2779
|
+
vsock?: boolean;
|
|
2780
|
+
/** kwshm: the worker's kernel offers it and runs the owner's "shm" calls (the copies happen there). */
|
|
2781
|
+
shm?: boolean;
|
|
2782
|
+
/**
|
|
2783
|
+
* The shared transport's control block (worker-shared.ts): console and
|
|
2784
|
+
* evdev input and frame requests go through it instead of "input",
|
|
2785
|
+
* "evdev" and "frame-want" messages. Absent: messages only.
|
|
2786
|
+
*/
|
|
2787
|
+
shared?: SharedArrayBuffer;
|
|
2788
|
+
/**
|
|
2789
|
+
* Resume this snapshot instead of booting (CreateKernelOptions.restore);
|
|
2790
|
+
* its memory is transferred. The worker builds the disks and devices from
|
|
2791
|
+
* the spec and checks them against it, as inline.
|
|
2792
|
+
*/
|
|
2793
|
+
restore?: KernelSnapshot;
|
|
2794
|
+
}
|
|
2795
|
+
/** An ExitResult with `error` reduced to something structured clone accepts. */
|
|
2796
|
+
interface WorkerExit {
|
|
2797
|
+
code: number;
|
|
2798
|
+
reason: string;
|
|
2799
|
+
kind: ExitKind;
|
|
2800
|
+
error?: unknown;
|
|
2801
|
+
}
|
|
2802
|
+
/** Owner -> worker. */
|
|
2803
|
+
type ToWorker = {
|
|
2804
|
+
t: "boot";
|
|
2805
|
+
spec: WorkerBootSpec;
|
|
2806
|
+
} | {
|
|
2807
|
+
t: "input";
|
|
2808
|
+
data: Uint8Array | string;
|
|
2809
|
+
} | {
|
|
2810
|
+
t: "resize";
|
|
2811
|
+
cols: number;
|
|
2812
|
+
rows: number;
|
|
2813
|
+
} | {
|
|
2814
|
+
t: "sync";
|
|
2815
|
+
id: number;
|
|
2816
|
+
timeout?: number;
|
|
2817
|
+
} | {
|
|
2818
|
+
t: "stop";
|
|
2819
|
+
code?: number;
|
|
2820
|
+
reason?: string;
|
|
2821
|
+
} |
|
|
2822
|
+
/** The owner's AbortSignal fired: abort the downloads, or stop the kernel once booted. */
|
|
2823
|
+
{
|
|
2824
|
+
t: "abort";
|
|
2825
|
+
} |
|
|
2826
|
+
/**
|
|
2827
|
+
* An operation on disk `index` (built order), answered by "disk-result":
|
|
2828
|
+
* "detach" stops its saves, waits for the one in flight and closes its
|
|
2829
|
+
* store (before the owner replaces the store); "export" returns its
|
|
2830
|
+
* content as kwsparse parts (CowDisk.exportParts(): Blobs).
|
|
2831
|
+
*/
|
|
2832
|
+
{
|
|
2833
|
+
t: "disk";
|
|
2834
|
+
id: number;
|
|
2835
|
+
index: number;
|
|
2836
|
+
op: "detach" | "export";
|
|
2837
|
+
} |
|
|
2838
|
+
/** Evdev calls, in order (EVDEV_OP triples). */
|
|
2839
|
+
{
|
|
2840
|
+
t: "evdev";
|
|
2841
|
+
ops: number[];
|
|
2842
|
+
} |
|
|
2843
|
+
/** The display size the owner's `display` function returns now (asked at the next first open). */
|
|
2844
|
+
{
|
|
2845
|
+
t: "display-size";
|
|
2846
|
+
size: DisplaySize;
|
|
2847
|
+
} |
|
|
2848
|
+
/**
|
|
2849
|
+
* A frame credit: send one "frame" (id = this id) once the picture may
|
|
2850
|
+
* have changed (at once with `now`, even if unchanged). `buf` is a
|
|
2851
|
+
* returned frame buffer for the worker to reuse.
|
|
2852
|
+
*/
|
|
2853
|
+
{
|
|
2854
|
+
t: "frame-want";
|
|
2855
|
+
id: number;
|
|
2856
|
+
buf?: ArrayBuffer;
|
|
2857
|
+
now?: boolean;
|
|
2858
|
+
} |
|
|
2859
|
+
/**
|
|
2860
|
+
* The sink's answer to "sound-chunk" `seq`: frames queued after it, at
|
|
2861
|
+
* `at` (performance.timeOrigin + performance.now() on the owner).
|
|
2862
|
+
*/
|
|
2863
|
+
{
|
|
2864
|
+
t: "sound-queued";
|
|
2865
|
+
seq: number;
|
|
2866
|
+
frames: number;
|
|
2867
|
+
at: number;
|
|
2868
|
+
} |
|
|
2869
|
+
/** Shared transport: the owner wrote into the control block while the kernel waited idle. */
|
|
2870
|
+
{
|
|
2871
|
+
t: "kick";
|
|
2872
|
+
} |
|
|
2873
|
+
/** vsock packets for the guest (header and payload each; transferred), in order. */
|
|
2874
|
+
{
|
|
2875
|
+
t: "vsock";
|
|
2876
|
+
packets: Uint8Array[];
|
|
2877
|
+
} |
|
|
2878
|
+
/** A kwshm call (shm.ts) for the worker's ShmDevice; answered by "shm-result" with the same rid. */
|
|
2879
|
+
{
|
|
2880
|
+
t: "shm";
|
|
2881
|
+
rid: number;
|
|
2882
|
+
call: ShmCall;
|
|
2883
|
+
} |
|
|
2884
|
+
/** Save the machine (KernelInstance.snapshot()); answered by "snapshot-result" with the same id. */
|
|
2885
|
+
{
|
|
2886
|
+
t: "snapshot";
|
|
2887
|
+
id: number;
|
|
2888
|
+
stop?: boolean;
|
|
2889
|
+
};
|
|
2890
|
+
/** Worker -> owner. Output, log and progress keep their order relative to "started" and "exit". */
|
|
2891
|
+
type FromWorker =
|
|
2892
|
+
/** First message: the worker runs (a web binding revokes its Blob URL then), and whether it has JSPI. */
|
|
2893
|
+
{
|
|
2894
|
+
t: "ready";
|
|
2895
|
+
jspi: boolean;
|
|
2896
|
+
} | {
|
|
2897
|
+
t: "output";
|
|
2898
|
+
bytes: Uint8Array;
|
|
2899
|
+
} | {
|
|
2900
|
+
t: "log";
|
|
2901
|
+
msg: string;
|
|
2902
|
+
} | {
|
|
2903
|
+
t: "progress";
|
|
2904
|
+
p: BootProgress;
|
|
2905
|
+
} | {
|
|
2906
|
+
t: "started";
|
|
2907
|
+
cmdline: string;
|
|
2908
|
+
memoryMiB: number;
|
|
2909
|
+
memory64: boolean;
|
|
2910
|
+
stats: InstanceStats;
|
|
2911
|
+
disks: DiskState[];
|
|
2912
|
+
skipped: SkippedDisk[];
|
|
2913
|
+
} | {
|
|
2914
|
+
t: "boot-error";
|
|
2915
|
+
stage: string;
|
|
2916
|
+
message: string;
|
|
2917
|
+
} | {
|
|
2918
|
+
t: "stats";
|
|
2919
|
+
stats: InstanceStats;
|
|
2920
|
+
disks: DiskState[];
|
|
2921
|
+
} | {
|
|
2922
|
+
t: "synced";
|
|
2923
|
+
id: number;
|
|
2924
|
+
ok: boolean;
|
|
2925
|
+
} |
|
|
2926
|
+
/** A disk failed to save a flush (CowDisk onError). */
|
|
2927
|
+
{
|
|
2928
|
+
t: "disk-error";
|
|
2929
|
+
index: number;
|
|
2930
|
+
error: {
|
|
2931
|
+
name: string;
|
|
2932
|
+
message: string;
|
|
2933
|
+
stack?: string;
|
|
2934
|
+
};
|
|
2935
|
+
} | {
|
|
2936
|
+
t: "disk-result";
|
|
2937
|
+
id: number;
|
|
2938
|
+
ok: true;
|
|
2939
|
+
value?: unknown;
|
|
2940
|
+
} | {
|
|
2941
|
+
t: "disk-result";
|
|
2942
|
+
id: number;
|
|
2943
|
+
ok: false;
|
|
2944
|
+
error: string;
|
|
2945
|
+
} |
|
|
2946
|
+
/** A program opened the display or changed its mode, or the last one closed it (null). */
|
|
2947
|
+
{
|
|
2948
|
+
t: "display";
|
|
2949
|
+
mode: DisplayMode | null;
|
|
2950
|
+
} |
|
|
2951
|
+
/** The evdev open mask changed (InputHost.mask). */
|
|
2952
|
+
{
|
|
2953
|
+
t: "input-state";
|
|
2954
|
+
mask: number;
|
|
2955
|
+
} |
|
|
2956
|
+
/**
|
|
2957
|
+
* The answer to "frame-want" `id`: the mode, and the pixels as packed
|
|
2958
|
+
* XRGB8888 rows (width * 4 bytes; transferred), or null when the picture
|
|
2959
|
+
* did not change since the last frame sent or no program has the display.
|
|
2960
|
+
*/
|
|
2961
|
+
{
|
|
2962
|
+
t: "frame";
|
|
2963
|
+
id: number;
|
|
2964
|
+
mode: DisplayMode | null;
|
|
2965
|
+
data: Uint8Array | null;
|
|
2966
|
+
} |
|
|
2967
|
+
/**
|
|
2968
|
+
* Shared transport: the frame triple buffer for the mode in the next
|
|
2969
|
+
* "display" message (`cap` bytes per slot), or null when none could be
|
|
2970
|
+
* made (frames then go by "frame-want" and "frame").
|
|
2971
|
+
*/
|
|
2972
|
+
{
|
|
2973
|
+
t: "frame-buffer";
|
|
2974
|
+
buffer: SharedArrayBuffer | null;
|
|
2975
|
+
cap: number;
|
|
2976
|
+
} |
|
|
2977
|
+
/** Shared transport: the answer to FRAME_NOW `id` (and earlier ones); the frame is in the buffer. */
|
|
2978
|
+
{
|
|
2979
|
+
t: "frame-ready";
|
|
2980
|
+
id: number;
|
|
2981
|
+
mode: DisplayMode | null;
|
|
2982
|
+
} | {
|
|
2983
|
+
t: "sound-state";
|
|
2984
|
+
state: SoundState;
|
|
2985
|
+
event: SoundEvent;
|
|
2986
|
+
} |
|
|
2987
|
+
/** PCM the guest played (transferred); answered by "sound-queued" (throttled). */
|
|
2988
|
+
{
|
|
2989
|
+
t: "sound-chunk";
|
|
2990
|
+
seq: number;
|
|
2991
|
+
format: SoundFormat;
|
|
2992
|
+
data: Uint8Array;
|
|
2993
|
+
} |
|
|
2994
|
+
/** vsock packets from the guest (transferred), in order; posted from inside the import once 64 KiB or 64 packets are waiting, else per microtask. */
|
|
2995
|
+
{
|
|
2996
|
+
t: "vsock";
|
|
2997
|
+
packets: Uint8Array[];
|
|
2998
|
+
} |
|
|
2999
|
+
/** The kernel's kwvsock started (VsockDevice onInit). */
|
|
3000
|
+
{
|
|
3001
|
+
t: "vsock-ready";
|
|
3002
|
+
guestCid: number;
|
|
3003
|
+
rxMax: number;
|
|
3004
|
+
} |
|
|
3005
|
+
/** The answer to "shm": the result (read's bytes transferred), or the ShmError's code and message. */
|
|
3006
|
+
{
|
|
3007
|
+
t: "shm-result";
|
|
3008
|
+
rid: number;
|
|
3009
|
+
ok: true;
|
|
3010
|
+
value: ShmCallResult;
|
|
3011
|
+
} | {
|
|
3012
|
+
t: "shm-result";
|
|
3013
|
+
rid: number;
|
|
3014
|
+
ok: false;
|
|
3015
|
+
code: string;
|
|
3016
|
+
message: string;
|
|
3017
|
+
} |
|
|
3018
|
+
/** kwshm announced an export's page list (new, or refreshed). */
|
|
3019
|
+
{
|
|
3020
|
+
t: "shm-attach";
|
|
3021
|
+
info: ShmInfo;
|
|
3022
|
+
} |
|
|
3023
|
+
/** kwshm withdrew an export. */
|
|
3024
|
+
{
|
|
3025
|
+
t: "shm-detach";
|
|
3026
|
+
id: number;
|
|
3027
|
+
} |
|
|
3028
|
+
/**
|
|
3029
|
+
* The answer to "snapshot": the snapshot (its memory transferred), or why
|
|
3030
|
+
* it failed. Always posted before "exit" (a snapshot with stop ends the kernel).
|
|
3031
|
+
*/
|
|
3032
|
+
{
|
|
3033
|
+
t: "snapshot-result";
|
|
3034
|
+
id: number;
|
|
3035
|
+
ok: true;
|
|
3036
|
+
snapshot: KernelSnapshot;
|
|
3037
|
+
} | {
|
|
3038
|
+
t: "snapshot-result";
|
|
3039
|
+
id: number;
|
|
3040
|
+
ok: false;
|
|
3041
|
+
error: string;
|
|
3042
|
+
} |
|
|
3043
|
+
/** Sent after every save in flight has settled, so the worker can be ended at once. */
|
|
3044
|
+
{
|
|
3045
|
+
t: "exit";
|
|
3046
|
+
result: WorkerExit;
|
|
3047
|
+
stats: InstanceStats;
|
|
3048
|
+
disks: DiskState[];
|
|
3049
|
+
};
|
|
3050
|
+
/** The owner's end: a started worker running serveKernel(). */
|
|
3051
|
+
interface WorkerEndpoint {
|
|
3052
|
+
post(msg: ToWorker, transfer?: ArrayBuffer[]): void;
|
|
3053
|
+
listen(handlers: {
|
|
3054
|
+
message(msg: FromWorker): void;
|
|
3055
|
+
/** An uncaught error in the worker. */
|
|
3056
|
+
error(err: unknown): void;
|
|
3057
|
+
/** The worker thread ended (also after terminate()). */
|
|
3058
|
+
exit(): void;
|
|
3059
|
+
}): void;
|
|
3060
|
+
terminate(): void;
|
|
3061
|
+
}
|
|
3062
|
+
/** Which way the owner and the kernel talk: on one thread, or worker mode by messages or with shared memory. */
|
|
3063
|
+
export type KernelTransport = "inline" | "messages" | "shared";
|
|
3064
|
+
/**
|
|
3065
|
+
* Can this thread use the shared transport: SharedArrayBuffer exists, the
|
|
3066
|
+
* context is not a non-isolated browser page, and one survives a post.
|
|
3067
|
+
*/
|
|
3068
|
+
export declare function sharedMemoryAvailable(): boolean;
|
|
3069
|
+
/** The options WorkerKernel takes over from createKernel(). */
|
|
3070
|
+
export interface WorkerKernelOptions {
|
|
3071
|
+
onOutput?: (bytes: Uint8Array) => void;
|
|
3072
|
+
onProgress: (p: BootProgress) => void;
|
|
3073
|
+
log: (msg: string) => void;
|
|
3074
|
+
onDiskError?: (index: number, error: unknown) => void;
|
|
3075
|
+
display?: DisplayOption;
|
|
3076
|
+
onDisplay?: (mode: DisplayMode | null) => void;
|
|
3077
|
+
onInput?: (state: InputState) => void;
|
|
3078
|
+
sound?: SoundOption;
|
|
3079
|
+
/** The vsock protocol runs here (VsockHost); the worker's kernel only passes packets. */
|
|
3080
|
+
vsock?: boolean | VsockOption;
|
|
3081
|
+
/** kwshm: the API (ShmClient) runs here, the calls run in the worker. */
|
|
3082
|
+
shm?: boolean;
|
|
3083
|
+
/** The shared transport's control block (worker-shared.ts), also sent in the boot spec; absent: messages. */
|
|
3084
|
+
shared?: SharedArrayBuffer;
|
|
3085
|
+
}
|
|
3086
|
+
/**
|
|
3087
|
+
* A kernel running in a worker: the surface of KernelInstance, proxied over
|
|
3088
|
+
* messages. There is no low-level `kernel` object (it lives in the worker).
|
|
3089
|
+
* stats() returns the latest snapshot the worker sent (every 500 ms while
|
|
3090
|
+
* running, and a final one at exit) with uptimeMs brought up to date. The
|
|
3091
|
+
* display, evdev and sound work as inline, with the differences that a
|
|
3092
|
+
* thread boundary makes (worker-devices.ts): frame() returns the latest
|
|
3093
|
+
* frame the worker sent (readFrame() waits for a fresh one), evdev's open
|
|
3094
|
+
* state and return values are this thread's mirror, and a `display`
|
|
3095
|
+
* function is asked here, at boot, on resize() and on updateDisplaySize().
|
|
3096
|
+
*/
|
|
3097
|
+
export declare class WorkerKernel implements KernelHandle {
|
|
3098
|
+
#private;
|
|
3099
|
+
/** The command line it booted with. */
|
|
3100
|
+
cmdline: string;
|
|
3101
|
+
/** Memory actually allocated, in MiB. */
|
|
3102
|
+
memoryMiB: number;
|
|
3103
|
+
memory64: boolean;
|
|
3104
|
+
/** Settles when the kernel exits (see KernelInstance.exited), or 255 "fatal" if the worker dies. */
|
|
3105
|
+
readonly exited: Promise<ExitResult>;
|
|
3106
|
+
/** @internal Resolves once the kernel has started; rejects with a BootError. */
|
|
3107
|
+
readonly started: Promise<void>;
|
|
3108
|
+
/** @internal Use createKernel({ worker: true }). */
|
|
3109
|
+
constructor(endpoint: WorkerEndpoint, opts: WorkerKernelOptions);
|
|
3110
|
+
/** @internal Loading the kernel failed before the boot message was sent: end the worker. */
|
|
3111
|
+
abandon(reason: string): void;
|
|
3112
|
+
/** Console output as a stream (see KernelInstance.output). */
|
|
3113
|
+
get output(): ReadableStream<Uint8Array>;
|
|
3114
|
+
/** Call `listener` with console output from now on. Returns the unsubscribe function. */
|
|
3115
|
+
onOutput(listener: (bytes: Uint8Array) => void): () => void;
|
|
3116
|
+
/** Type into the console (bytes, or text encoded as UTF-8); "\n" or "\r" is Enter. */
|
|
3117
|
+
write(data: Uint8Array | string): void;
|
|
3118
|
+
/**
|
|
3119
|
+
* How console and evdev input and frames reach the worker: "shared"
|
|
3120
|
+
* (SharedArrayBuffers, read by the worker while the kernel runs, within
|
|
3121
|
+
* about a millisecond) or "messages" (handled when the kernel yields, up
|
|
3122
|
+
* to 20 ms while the guest is busy). Everything else is messages either way.
|
|
3123
|
+
*/
|
|
3124
|
+
get transport(): KernelTransport;
|
|
3125
|
+
/** Console input as a stream. */
|
|
3126
|
+
get input(): WritableStream<Uint8Array | string>;
|
|
3127
|
+
/** Set the console window size; the guest's foreground process gets SIGWINCH. */
|
|
3128
|
+
resize(cols: number, rows: number): void;
|
|
3129
|
+
/**
|
|
3130
|
+
* Ask a `display` function for the size again and send it to the worker
|
|
3131
|
+
* if it changed, so that the next program to open /dev/fb0 gets it
|
|
3132
|
+
* (inline, the kernel calls the function itself at that moment; the
|
|
3133
|
+
* worker cannot). resize() does this too. A no-op for other options.
|
|
3134
|
+
*/
|
|
3135
|
+
updateDisplaySize(): void;
|
|
3136
|
+
/** @internal The display option as it goes in the boot message. */
|
|
3137
|
+
get bootDisplay(): boolean | DisplaySize;
|
|
3138
|
+
/**
|
|
3139
|
+
* The keyboard, mouse and tablet (with the display option): InputHost's
|
|
3140
|
+
* methods, forwarded to the worker in order. The open state is a mirror
|
|
3141
|
+
* of the worker's (reported with onInput), so it may lag by a yield.
|
|
3142
|
+
*/
|
|
3143
|
+
get evdev(): Evdev | undefined;
|
|
3144
|
+
/** With the display option: the mode while a program has /dev/fb0 open (as last reported), else null. */
|
|
3145
|
+
get display(): {
|
|
3146
|
+
readonly mode: DisplayMode | null;
|
|
3147
|
+
} | undefined;
|
|
3148
|
+
/**
|
|
3149
|
+
* The latest frame the worker sent, as RGBA (see KernelInstance.frame()),
|
|
3150
|
+
* or null with no display, while no program has it open, or before the
|
|
3151
|
+
* first frame arrived. Each call also asks for a newer one (at most two
|
|
3152
|
+
* requests are outstanding; the worker answers once the picture may have
|
|
3153
|
+
* changed). Compare frameSeq to skip repainting an unchanged frame.
|
|
3154
|
+
*/
|
|
3155
|
+
frame(out?: Uint8ClampedArray): DisplayFrame | null;
|
|
3156
|
+
/** Ask for a newer frame without converting the current one (see frame()). */
|
|
3157
|
+
requestFrame(): void;
|
|
3158
|
+
/** Counts frames received with new pixels: frame() has something new when it changed. */
|
|
3159
|
+
get frameSeq(): number;
|
|
3160
|
+
/** A fresh frame: a round trip to the worker (with messages at most about 20 ms while the guest is busy; shared, about a millisecond). */
|
|
3161
|
+
readFrame(out?: Uint8ClampedArray): Promise<DisplayFrame | null>;
|
|
3162
|
+
/**
|
|
3163
|
+
* With the vsock option: listen() and connect() as inline (VsockHost).
|
|
3164
|
+
* The protocol runs on this thread; the packets cross to the worker as
|
|
3165
|
+
* messages, which it takes while the kernel is suspended (up to 20 ms
|
|
3166
|
+
* while the guest is busy, with either transport).
|
|
3167
|
+
*/
|
|
3168
|
+
get vsock(): VsockHost | undefined;
|
|
3169
|
+
/** A program on its own pty or on pipes, and exec(), as inline (tty.ts; the protocol runs on this thread). */
|
|
3170
|
+
spawn(file: string | undefined, args: readonly string[] | undefined, opts: PipeOptions): Promise<Subprocess>;
|
|
3171
|
+
spawn(file?: string, args?: readonly string[], opts?: PtyOptions): Promise<Pty>;
|
|
3172
|
+
exec(file: string, args?: readonly string[], opts?: ExecOptions & {
|
|
3173
|
+
encoding?: "utf8";
|
|
3174
|
+
}): Promise<ExecResult<string>>;
|
|
3175
|
+
exec(file: string, args: readonly string[] | undefined, opts: ExecOptions & {
|
|
3176
|
+
encoding: "buffer";
|
|
3177
|
+
}): Promise<ExecResult<Uint8Array>>;
|
|
3178
|
+
/** A raw byte stream to a TCP server on the guest's loopback, as inline (kwtty's CONNECT; the protocol runs on this thread). */
|
|
3179
|
+
connect(port: number, opts?: ConnectOptions): Promise<GuestSocket>;
|
|
3180
|
+
/** HTTP/1.1 to a server on the guest's loopback, as inline (http.ts over connect()). */
|
|
3181
|
+
fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
|
|
3182
|
+
/** Host file systems in the guest, as inline (mounts.ts): the 9p server and the handlers run on this thread. */
|
|
3183
|
+
mount(path: string, fs: FsSource, opts?: MountOptions): Promise<Mount>;
|
|
3184
|
+
get mounts(): ReadonlyMap<string, Mount>;
|
|
3185
|
+
/** @internal createKernel's `mounts`, once the kernel runs. */
|
|
3186
|
+
startMounts(list: ReturnType<typeof parseMounts>): void;
|
|
3187
|
+
/**
|
|
3188
|
+
* With the shm option: open(), create() and openId() as inline. Each call
|
|
3189
|
+
* is a round trip to the worker, which runs it when the kernel next
|
|
3190
|
+
* suspends (up to 20 ms while the guest is busy); read() copies there and
|
|
3191
|
+
* transfers the bytes. No views(): the kernel's memory is the worker's.
|
|
3192
|
+
*/
|
|
3193
|
+
get shm(): ShmClient | undefined;
|
|
3194
|
+
/** With the sound option: the playback state, as the worker last reported it. */
|
|
3195
|
+
get sound(): {
|
|
3196
|
+
readonly state: SoundState;
|
|
3197
|
+
readonly playing: boolean;
|
|
3198
|
+
} | undefined;
|
|
3199
|
+
/**
|
|
3200
|
+
* See KernelInstance.sync(): a round trip to the worker, which raises
|
|
3201
|
+
* the sync IRQ and waits for every persistent disk to complete a flush
|
|
3202
|
+
* issued after it (true), or `timeout` ms (false). A request still
|
|
3203
|
+
* open when the kernel exits or the worker dies resolves false if a
|
|
3204
|
+
* persistent disk was attached (nothing confirmed it), else true. After
|
|
3205
|
+
* the exit it resolves true at once: the worker reported the exit only
|
|
3206
|
+
* after the saves in flight had settled.
|
|
3207
|
+
*/
|
|
3208
|
+
sync(opts?: {
|
|
3209
|
+
timeout?: number;
|
|
3210
|
+
}): Promise<boolean>;
|
|
3211
|
+
/**
|
|
3212
|
+
* Save the machine, as KernelInstance.snapshot(): the worker takes the
|
|
3213
|
+
* snapshot and transfers it here (its memory is not copied again).
|
|
3214
|
+
* Resume it with createKernel({ restore }), in worker mode or inline.
|
|
3215
|
+
* Rejects while host file systems are mounted, as inline.
|
|
3216
|
+
*/
|
|
3217
|
+
snapshot(opts?: {
|
|
3218
|
+
stop?: boolean;
|
|
3219
|
+
}): Promise<KernelSnapshot>;
|
|
3220
|
+
/**
|
|
3221
|
+
* Stop the kernel now (see KernelInstance.stop()). The worker confirms
|
|
3222
|
+
* and is then ended; if it does not answer within 2 s it is ended anyway.
|
|
3223
|
+
*/
|
|
3224
|
+
stop(res?: {
|
|
3225
|
+
code?: number;
|
|
3226
|
+
reason?: string;
|
|
3227
|
+
}): Promise<ExitResult>;
|
|
3228
|
+
/**
|
|
3229
|
+
* The disks' state as of the latest snapshot (every 500 ms, and final at
|
|
3230
|
+
* exit): flags, flush count, and for a CowDisk its overlay, store and
|
|
3231
|
+
* counters. Indexed as the `disks` option; see skippedDisks for the
|
|
3232
|
+
* optional ones left out.
|
|
3233
|
+
*/
|
|
3234
|
+
get disks(): readonly DiskState[];
|
|
3235
|
+
/** Disks whose spec was optional and could not be built, and why. */
|
|
3236
|
+
get skippedDisks(): readonly SkippedDisk[];
|
|
3237
|
+
/**
|
|
3238
|
+
* Stop disk `index` (a CowDisk with a store) saving: the worker detaches
|
|
3239
|
+
* it, waits for the save in flight and closes its store, so this thread
|
|
3240
|
+
* may then replace or clear the store (the guest's later writes stay in
|
|
3241
|
+
* the worker's memory). Rejects if the kernel has exited.
|
|
3242
|
+
*/
|
|
3243
|
+
detachDisk(index: number): Promise<void>;
|
|
3244
|
+
/** Disk `index`'s current content as a kwsparse image in parts (CowDisk.exportParts(); gzipBlob() compresses them). */
|
|
3245
|
+
exportDisk(index: number): Promise<{
|
|
3246
|
+
size: number;
|
|
3247
|
+
blocks: number;
|
|
3248
|
+
parts: BlobPart[];
|
|
3249
|
+
}>;
|
|
3250
|
+
/** The latest snapshot from the worker, with uptimeMs brought up to date while it runs. */
|
|
3251
|
+
stats(): InstanceStats;
|
|
3252
|
+
}
|
|
3253
|
+
/**
|
|
3254
|
+
* Boot progress, in order: downloads (with compile overlapping them when
|
|
3255
|
+
* streaming), memory, instantiate, start. Worker mode adds "worker" (the
|
|
3256
|
+
* worker runs, and whether it has JSPI) before "memory": it may come
|
|
3257
|
+
* before, during or after the download and compile, which run on the
|
|
3258
|
+
* owner's thread while the worker starts (unless compileInWorker).
|
|
3259
|
+
*/
|
|
3260
|
+
export type BootProgress = {
|
|
3261
|
+
stage: "worker";
|
|
3262
|
+
jspi: boolean;
|
|
3263
|
+
} | DownloadProgress | {
|
|
3264
|
+
stage: "compile";
|
|
3265
|
+
} | {
|
|
3266
|
+
stage: "compiled";
|
|
3267
|
+
ms: number;
|
|
3268
|
+
memory64: boolean;
|
|
3269
|
+
} | ({
|
|
3270
|
+
stage: "memory";
|
|
3271
|
+
} & MemoryStage) | {
|
|
3272
|
+
stage: "instantiate";
|
|
3273
|
+
} | {
|
|
3274
|
+
stage: "start";
|
|
3275
|
+
cmdline: string;
|
|
3276
|
+
};
|
|
3277
|
+
export interface CreateKernelOptions {
|
|
3278
|
+
/**
|
|
3279
|
+
* Resume a snapshot (KernelInstance.snapshot()) instead of booting: the
|
|
3280
|
+
* same kernel build; initrd, cmdline and memoryMiB are ignored. In
|
|
3281
|
+
* worker mode the memory is copied to the worker (see
|
|
3282
|
+
* WorkerOption.transferRestore). `disks` must be the snapshot's disks,
|
|
3283
|
+
* unchanged since it was taken (same identity and write generation); otherwise createKernel
|
|
3284
|
+
* rejects, naming the disk, and the caller can boot normally instead.
|
|
3285
|
+
* The devices must be the snapshot's too: display, sound, vsock, shm
|
|
3286
|
+
* and network each given, or not, as when it was taken (a network with
|
|
3287
|
+
* the same MAC), or createKernel rejects. vsock sessions (spawn(),
|
|
3288
|
+
* exec(), connect(), fetch(), listeners' connections) and the guest's
|
|
3289
|
+
* TCP connections do not survive: the guest's ends are reset. Host file
|
|
3290
|
+
* systems do (inline only): `mounts` must give one for each mount path
|
|
3291
|
+
* in the snapshot, read-only as it was, and the guest's open files on
|
|
3292
|
+
* it are opened again by path (a file gone meanwhile answers ESTALE);
|
|
3293
|
+
* nothing of their files is in the snapshot. Other `mounts` are
|
|
3294
|
+
* mounted as at boot.
|
|
3295
|
+
*/
|
|
3296
|
+
restore?: KernelSnapshot;
|
|
3297
|
+
/**
|
|
3298
|
+
* The kernel: a URL (a path or file: URL on Node), bytes, a Response or
|
|
3299
|
+
* a compiled WebAssembly.Module. Default: the bundled Alpine kernel
|
|
3300
|
+
* (unkernel-alpine.wasm next to the entry).
|
|
3301
|
+
*/
|
|
3302
|
+
kernel?: KernelSource;
|
|
3303
|
+
/**
|
|
3304
|
+
* The initramfs (a cpio, optionally gzipped). Default (undefined): the
|
|
3305
|
+
* one bundled into the kernel, if any; null boots without one.
|
|
3306
|
+
*/
|
|
3307
|
+
initrd?: BytesSource | null;
|
|
3308
|
+
/**
|
|
3309
|
+
* Kernel command line. Default: the kernel's bundled one if its bundled
|
|
3310
|
+
* initramfs is used; else "console=hvc0 root=/dev/wda rw" with disks and
|
|
3311
|
+
* no initramfs; else "console=hvc0 rdinit=/init".
|
|
3312
|
+
*/
|
|
3313
|
+
cmdline?: string;
|
|
3314
|
+
/** Kernel memory (fixed for the run). Default 512 on Node; on the web, autoMemoryMiB(). */
|
|
3315
|
+
memoryMiB?: number;
|
|
3316
|
+
/** Smaller sizes to try in order if memoryMiB cannot be allocated. Default none on Node; DEFAULT_MEMORY_FALLBACK_MIB on the web. */
|
|
3317
|
+
memoryFallbackMiB?: number[];
|
|
3318
|
+
/** Memory type; default: detected from the module. */
|
|
3319
|
+
memory64?: boolean;
|
|
3320
|
+
/**
|
|
3321
|
+
* kwblk disks: /dev/wda, wdb, ... (CowDisk, HttpBase-backed disks,
|
|
3322
|
+
* FileDisk on Node, or your own BlockDevice), or specs (devices.ts:
|
|
3323
|
+
* plain data such as { kind: "file", path } on Node or { kind: "data",
|
|
3324
|
+
* template: "bundled" } in browsers), which the instance builds, owns
|
|
3325
|
+
* and closes at exit. Worker mode takes specs only.
|
|
3326
|
+
*/
|
|
3327
|
+
disks?: Array<BlockDevice | DiskSpec>;
|
|
3328
|
+
/**
|
|
3329
|
+
* Network: a NetBackend (wrapped in a NetStack), a NetStack, any
|
|
3330
|
+
* NetDevice, or a spec ({ kind: "net", backend: { kind: "direct" } } on
|
|
3331
|
+
* Node, or { kind: "wisp", servers }). Default: none (the guest has no
|
|
3332
|
+
* eth0). The instance closes it (and its backend) when the kernel exits.
|
|
3333
|
+
* Worker mode takes a spec only.
|
|
3334
|
+
*/
|
|
3335
|
+
net?: NetDevice | NetBackend | NetSpec;
|
|
3336
|
+
/** A disk built from a spec failed to save a flush (e.g. QuotaExceededError; the guest gets EIO for it). */
|
|
3337
|
+
onDiskError?: (index: number, error: unknown) => void;
|
|
3338
|
+
/**
|
|
3339
|
+
* kwemu's JIT tier: hot guest code is compiled to WebAssembly modules at
|
|
3340
|
+
* run time (synchronously, a few KiB each). Default true; false runs the
|
|
3341
|
+
* interpreter only.
|
|
3342
|
+
*/
|
|
3343
|
+
jit?: boolean;
|
|
3344
|
+
/**
|
|
3345
|
+
* A display: the guest gets /dev/fb0 (kwfb, XRGB8888), and frame() /
|
|
3346
|
+
* display read what it draws. true = 640x480; or a size; or a function
|
|
3347
|
+
* returning the size wanted each time a program first opens the device
|
|
3348
|
+
* (e.g. the window's size; the kernel caps it at 1M pixels by dividing
|
|
3349
|
+
* by an integer; in worker mode it is asked ahead of time instead, see
|
|
3350
|
+
* WorkerOption). A program may set its own size; onDisplay reports
|
|
3351
|
+
* every change. Default false (no device).
|
|
3352
|
+
*/
|
|
3353
|
+
display?: DisplayOption;
|
|
3354
|
+
/** A guest program opened the display or changed its mode (the mode), or the last one closed it (null). */
|
|
3355
|
+
onDisplay?: (mode: DisplayMode | null) => void;
|
|
3356
|
+
/**
|
|
3357
|
+
* With a display the guest also gets a keyboard and a mouse (evdev,
|
|
3358
|
+
* /dev/input/event0 and event1). Called when a program opens or the
|
|
3359
|
+
* last one closes them; send keys and motion through `evdev` only
|
|
3360
|
+
* while they are open, and to the console otherwise.
|
|
3361
|
+
*/
|
|
3362
|
+
onInput?: (state: InputState) => void;
|
|
3363
|
+
/**
|
|
3364
|
+
* A sound card (kwsnd: ALSA hw:0,0 and OSS /dev/dsp, playback only):
|
|
3365
|
+
* true (output dropped) or a sink that receives the PCM chunks with
|
|
3366
|
+
* their format and the playback state (sound.ts). Default false (no card).
|
|
3367
|
+
*/
|
|
3368
|
+
sound?: SoundOption;
|
|
3369
|
+
/**
|
|
3370
|
+
* A vsock device (kwvsock: AF_VSOCK, guest CID 3, host CID 2): `vsock`
|
|
3371
|
+
* on the instance listens for guest connections and connects to guest
|
|
3372
|
+
* listeners, each a byte stream (vsock.ts), and spawn() and exec() run
|
|
3373
|
+
* programs through it (tty.ts). true, or options. Default true; false:
|
|
3374
|
+
* the guest has no vsock transport.
|
|
3375
|
+
*/
|
|
3376
|
+
vsock?: boolean | VsockOption;
|
|
3377
|
+
/**
|
|
3378
|
+
* kwshm: `shm` on the instance opens guest shmem files (by name in
|
|
3379
|
+
* /dev/shm, or by the id a guest program got from /dev/kwshm) and reads
|
|
3380
|
+
* and writes their pages in place (shm.ts). Default false: no device.
|
|
3381
|
+
*/
|
|
3382
|
+
shm?: boolean;
|
|
3383
|
+
/**
|
|
3384
|
+
* Host file systems to mount in the guest (mounts.ts): guest paths to a
|
|
3385
|
+
* file system (an Fs such as MemoryFs or nodeFs(), or a plain object
|
|
3386
|
+
* tree of files: strings, bytes, functions, subdirectory objects), or to
|
|
3387
|
+
* { fs, readOnly, timeout, requestTimeout }. Each is served over 9p on
|
|
3388
|
+
* vsock and mounted by the guest's kw9p, through kwtty, once it answers.
|
|
3389
|
+
* spawn() and exec() wait for them; if one failed, the calls that waited
|
|
3390
|
+
* reject with its MountError (it is logged too). Needs vsock (the default).
|
|
3391
|
+
*/
|
|
3392
|
+
mounts?: MountsOption;
|
|
3393
|
+
/** Initial console size (cols x rows); resize() changes it later. */
|
|
3394
|
+
consoleSize?: {
|
|
3395
|
+
cols: number;
|
|
3396
|
+
rows: number;
|
|
3397
|
+
};
|
|
3398
|
+
/** Console output, from the first byte. */
|
|
3399
|
+
onOutput?: (bytes: Uint8Array) => void;
|
|
3400
|
+
/** Host diagnostics ("[host] ...", "[net] ..."). Default console.error. */
|
|
3401
|
+
log?: (msg: string) => void;
|
|
3402
|
+
/** Download, compile and boot progress. */
|
|
3403
|
+
onProgress?: (p: BootProgress) => void;
|
|
3404
|
+
/** Aborts the downloads; once booted, stops the kernel (stop()). */
|
|
3405
|
+
signal?: AbortSignal;
|
|
3406
|
+
}
|
|
3407
|
+
export interface VsockOption {
|
|
3408
|
+
/** The host's receive buffer per connection: the credit the guest gets. Default 256 KiB. */
|
|
3409
|
+
bufferSize?: number;
|
|
3410
|
+
/**
|
|
3411
|
+
* Low level, inline only: the guest's packets (virtio-vsock header and
|
|
3412
|
+
* payload) go to `onPacket` instead of the SDK's protocol, and `vsock`
|
|
3413
|
+
* on the instance is undefined; send with kernel.vsock.deliver().
|
|
3414
|
+
*/
|
|
3415
|
+
raw?: {
|
|
3416
|
+
onPacket: (pkt: Uint8Array) => void;
|
|
3417
|
+
onInit?: (guestCid: number, rxMax: number) => void;
|
|
3418
|
+
};
|
|
3419
|
+
}
|
|
3420
|
+
/**
|
|
3421
|
+
* The worker option, kept out of CreateKernelOptions so that plain
|
|
3422
|
+
* options still type createKernel() as a KernelInstance.
|
|
3423
|
+
*/
|
|
3424
|
+
export interface WorkerOption {
|
|
3425
|
+
/**
|
|
3426
|
+
* Run the kernel in a worker (a worker_threads Worker on Node, a module
|
|
3427
|
+
* Web Worker in browsers), so it never blocks this thread. The
|
|
3428
|
+
* result is a WorkerKernel: the console, sync(), stop(), stats(),
|
|
3429
|
+
* exited, the disks' state, the display (frame() is the latest frame
|
|
3430
|
+
* the worker sent; readFrame() waits for a fresh one), evdev and sound,
|
|
3431
|
+
* without the low-level `kernel`. Disks and the network must be specs
|
|
3432
|
+
* (devices.ts), which the worker builds. A `display` function is asked
|
|
3433
|
+
* on this thread at boot, on resize() and on
|
|
3434
|
+
* WorkerKernel.updateDisplaySize(). The worker starts at once, and while
|
|
3435
|
+
* it starts this thread downloads (or reads) and compiles the kernel
|
|
3436
|
+
* (the engine compiles off-thread) and then posts the compiled
|
|
3437
|
+
* WebAssembly.Module to it. Default false.
|
|
3438
|
+
*/
|
|
3439
|
+
worker?: boolean;
|
|
3440
|
+
/**
|
|
3441
|
+
* Worker mode: load and compile the kernel in the worker instead of on
|
|
3442
|
+
* this thread (it then starts only once the worker runs, which is
|
|
3443
|
+
* slower). A kernel given as a WebAssembly.Module is posted as it is
|
|
3444
|
+
* either way. Default false.
|
|
3445
|
+
*/
|
|
3446
|
+
compileInWorker?: boolean;
|
|
3447
|
+
/**
|
|
3448
|
+
* Worker mode: console and evdev input and frames through
|
|
3449
|
+
* SharedArrayBuffers (worker-shared.ts), which the worker reads while the
|
|
3450
|
+
* kernel runs, instead of messages it handles only when the kernel
|
|
3451
|
+
* yields (up to 20 ms while the guest is busy). Default (undefined):
|
|
3452
|
+
* shared where a SharedArrayBuffer can be posted (Node; a browser page
|
|
3453
|
+
* only when cross-origin isolated), else messages. false: messages
|
|
3454
|
+
* always. true: shared, or a BootError ("support") where it cannot be.
|
|
3455
|
+
* WorkerKernel.transport says which is used.
|
|
3456
|
+
*/
|
|
3457
|
+
shared?: boolean;
|
|
3458
|
+
/**
|
|
3459
|
+
* Worker mode with `restore`: hand the snapshot's memory buffer to the
|
|
3460
|
+
* worker instead of copying it (about 150 ms per 512 MiB), for a
|
|
3461
|
+
* snapshot that is used once; its `memory` is detached then. Default false.
|
|
3462
|
+
*/
|
|
3463
|
+
transferRestore?: boolean;
|
|
3464
|
+
}
|
|
3465
|
+
export interface InstanceStats extends KernelStats {
|
|
3466
|
+
/** Milliseconds since kernel entry. */
|
|
3467
|
+
uptimeMs: number;
|
|
3468
|
+
/** Milliseconds to download and compile the kernel (0 if a Module was given). */
|
|
3469
|
+
compileMs: number;
|
|
3470
|
+
block: BlockStats;
|
|
3471
|
+
net?: NetStats;
|
|
3472
|
+
jit: JitStats;
|
|
3473
|
+
/** kwemu's counters, only from a -Dkwemu-stats kernel (`kernel/build.sh stats`). */
|
|
3474
|
+
kwemu?: KwemuStats;
|
|
3475
|
+
display?: DisplayStats;
|
|
3476
|
+
evdev?: InputStats;
|
|
3477
|
+
sound?: SoundStats;
|
|
3478
|
+
vsock?: VsockStats;
|
|
3479
|
+
shm?: ShmStats;
|
|
3480
|
+
}
|
|
3481
|
+
/**
|
|
3482
|
+
* A running kernel, wherever it runs: KernelInstance (on this thread) and
|
|
3483
|
+
* WorkerKernel (in a worker) both have this surface.
|
|
3484
|
+
*/
|
|
3485
|
+
export interface KernelHandle {
|
|
3486
|
+
/** The command line it booted with. */
|
|
3487
|
+
readonly cmdline: string;
|
|
3488
|
+
/** Settles when the kernel exits: halt (power off 0, halt 1, restart 2), panic 253, trap 254, fatal 255, or stop(). */
|
|
3489
|
+
readonly exited: Promise<ExitResult>;
|
|
3490
|
+
/** Console output as a stream: the first access gets everything since boot (the last 1 MiB); closes at exit. */
|
|
3491
|
+
readonly output: ReadableStream<Uint8Array>;
|
|
3492
|
+
/** Call `listener` with console output from now on. Returns the unsubscribe function. */
|
|
3493
|
+
onOutput(listener: (bytes: Uint8Array) => void): () => void;
|
|
3494
|
+
/** Type into the console (bytes, or text encoded as UTF-8); "\n" or "\r" is Enter. */
|
|
3495
|
+
write(data: Uint8Array | string): void;
|
|
3496
|
+
/** Console input as a stream. */
|
|
3497
|
+
readonly input: WritableStream<Uint8Array | string>;
|
|
3498
|
+
/** Set the console window size; the guest's foreground process gets SIGWINCH. */
|
|
3499
|
+
resize(cols: number, rows: number): void;
|
|
3500
|
+
/** Ask the guest to sync its file systems and disks; true once persistent disks have flushed. */
|
|
3501
|
+
sync(opts?: {
|
|
3502
|
+
timeout?: number;
|
|
3503
|
+
}): Promise<boolean>;
|
|
3504
|
+
/** Stop the kernel now (no clean shutdown). Resolves with the exit. */
|
|
3505
|
+
stop(res?: {
|
|
3506
|
+
code?: number;
|
|
3507
|
+
reason?: string;
|
|
3508
|
+
}): Promise<ExitResult>;
|
|
3509
|
+
/** Save the machine; resume it with createKernel({ restore }) (see KernelInstance.snapshot()). */
|
|
3510
|
+
snapshot(opts?: {
|
|
3511
|
+
stop?: boolean;
|
|
3512
|
+
}): Promise<KernelSnapshot>;
|
|
3513
|
+
/** Counters (in a worker: the latest snapshot, at most about 500 ms old while running). */
|
|
3514
|
+
stats(): InstanceStats;
|
|
3515
|
+
/** Memory actually allocated, in MiB. */
|
|
3516
|
+
readonly memoryMiB: number;
|
|
3517
|
+
readonly memory64: boolean;
|
|
3518
|
+
/** With the display option: the mode while a program has /dev/fb0 open, else null. */
|
|
3519
|
+
readonly display: {
|
|
3520
|
+
readonly mode: DisplayMode | null;
|
|
3521
|
+
} | undefined;
|
|
3522
|
+
/** With the display option: the keyboard, mouse and tablet (InputHost's methods). */
|
|
3523
|
+
readonly evdev: Evdev | undefined;
|
|
3524
|
+
/** The current frame as RGBA (in a worker: the latest one it sent), or null. */
|
|
3525
|
+
frame(out?: Uint8ClampedArray): DisplayFrame | null;
|
|
3526
|
+
/** A fresh frame as RGBA (in a worker: a round trip), or null. */
|
|
3527
|
+
readFrame(out?: Uint8ClampedArray): Promise<DisplayFrame | null>;
|
|
3528
|
+
/** With the sound option: the playback state. */
|
|
3529
|
+
readonly sound: {
|
|
3530
|
+
readonly state: SoundState;
|
|
3531
|
+
readonly playing: boolean;
|
|
3532
|
+
} | undefined;
|
|
3533
|
+
/**
|
|
3534
|
+
* With the vsock option: listen() for guest connections to the host
|
|
3535
|
+
* (CID 2) and connect() to guest listeners (CID 3). In worker mode the
|
|
3536
|
+
* protocol runs on this thread and the packets cross as messages.
|
|
3537
|
+
*/
|
|
3538
|
+
readonly vsock: Vsock | undefined;
|
|
3539
|
+
/**
|
|
3540
|
+
* Run `file` with `args` in the guest (no file: root's login shell),
|
|
3541
|
+
* served by the guest's kwtty over vsock (tty.ts): on its own pty, a Pty
|
|
3542
|
+
* (the zigpty / node-pty shape), or with `pty: false` on stdin, stdout
|
|
3543
|
+
* and stderr pipes, a Subprocess. Rejects with a PtyError ENODEV when
|
|
3544
|
+
* the instance was created with `vsock: false`. Waits until
|
|
3545
|
+
* createKernel's `mounts` are mounted, as exec() does, and rejects with
|
|
3546
|
+
* the MountError if one of them failed.
|
|
3547
|
+
*/
|
|
3548
|
+
spawn(file: string | undefined, args: readonly string[] | undefined, opts: PipeOptions): Promise<Subprocess>;
|
|
3549
|
+
spawn(file?: string, args?: readonly string[], opts?: PtyOptions): Promise<Pty>;
|
|
3550
|
+
/**
|
|
3551
|
+
* Run `file` with `args` on pipes, feed it `input`, and resolve with
|
|
3552
|
+
* its stdout and stderr (strings, or bytes with `encoding: "buffer"`)
|
|
3553
|
+
* and how it ended (a non-zero exit resolves too). tty.ts.
|
|
3554
|
+
*/
|
|
3555
|
+
exec(file: string, args?: readonly string[], opts?: ExecOptions & {
|
|
3556
|
+
encoding?: "utf8";
|
|
3557
|
+
}): Promise<ExecResult<string>>;
|
|
3558
|
+
exec(file: string, args: readonly string[] | undefined, opts: ExecOptions & {
|
|
3559
|
+
encoding: "buffer";
|
|
3560
|
+
}): Promise<ExecResult<Uint8Array>>;
|
|
3561
|
+
/**
|
|
3562
|
+
* A raw byte stream to TCP `port` on the guest's 127.0.0.1, through the
|
|
3563
|
+
* guest's kwtty (tty.ts, CONNECT): resolves once the guest connected,
|
|
3564
|
+
* rejects with a PtyError ECONNREFUSED when nothing listens there, or
|
|
3565
|
+
* ENODEV without vsock. Waits for createKernel's `mounts`, as spawn().
|
|
3566
|
+
*/
|
|
3567
|
+
connect(port: number, opts?: ConnectOptions): Promise<GuestSocket>;
|
|
3568
|
+
/**
|
|
3569
|
+
* An HTTP/1.1 request to a server on the guest's loopback (http.ts
|
|
3570
|
+
* fetchOver() over connect()): the URL's port picks the guest port
|
|
3571
|
+
* (default 80), its host only goes into the Host header.
|
|
3572
|
+
*/
|
|
3573
|
+
fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
|
|
3574
|
+
/**
|
|
3575
|
+
* Mount a host file system at guest `path` (mounts.ts): serve `fs` over
|
|
3576
|
+
* 9p and run kw9p in the guest. Resolves with the Mount (unmount(),
|
|
3577
|
+
* stats) once the guest has it mounted; rejects with a MountError
|
|
3578
|
+
* (ENODEV without vsock or without 9p in the kernel, ENOENT without kw9p
|
|
3579
|
+
* in the image, EBUSY, ETIMEDOUT, ...).
|
|
3580
|
+
*/
|
|
3581
|
+
mount(path: string, fs: FsSource, opts?: MountOptions): Promise<Mount>;
|
|
3582
|
+
/** The mounts the guest has now, by guest path. */
|
|
3583
|
+
readonly mounts: ReadonlyMap<string, Mount>;
|
|
3584
|
+
/**
|
|
3585
|
+
* With the shm option: guest shmem files read and written in place
|
|
3586
|
+
* (open(), create(), openId(); ShmFile.read()/write()). In worker mode the
|
|
3587
|
+
* copies run in the worker, where the kernel's memory is.
|
|
3588
|
+
*/
|
|
3589
|
+
readonly shm: Shm | undefined;
|
|
3590
|
+
/**
|
|
3591
|
+
* How input and frames reach the kernel: "inline" (this thread),
|
|
3592
|
+
* "messages" or "shared" (worker mode; see WorkerOption.shared).
|
|
3593
|
+
*/
|
|
3594
|
+
readonly transport: KernelTransport;
|
|
3595
|
+
}
|
|
3596
|
+
/** A booted kernel: its console, its exit, and the low-level Kernel. */
|
|
3597
|
+
export declare class KernelInstance implements KernelHandle {
|
|
3598
|
+
#private;
|
|
3599
|
+
/** The low-level runtime object (imports, memory, IRQ bits). */
|
|
3600
|
+
readonly kernel: Kernel;
|
|
3601
|
+
readonly module: WebAssembly.Module;
|
|
3602
|
+
/** The command line it booted with. */
|
|
3603
|
+
readonly cmdline: string;
|
|
3604
|
+
/** The network device, if any. */
|
|
3605
|
+
readonly net: NetDevice | undefined;
|
|
3606
|
+
/** Disks whose spec was optional and could not be built, and why. */
|
|
3607
|
+
skippedDisks: SkippedDisk[];
|
|
3608
|
+
/** Settles when the kernel exits: halt (power off 0, halt 1, restart 2), panic 253, trap 254, fatal 255, or stop(). */
|
|
3609
|
+
readonly exited: Promise<ExitResult>;
|
|
3610
|
+
/** @internal Use createKernel(). */
|
|
3611
|
+
constructor(kernel: Kernel, module: WebAssembly.Module, cmdline: string, net: NetDevice | undefined, compileMs: number);
|
|
3612
|
+
/** @internal The vsock protocol's host end, when the vsock option is set (and not raw). */
|
|
3613
|
+
attachVsock(host: VsockHost): void;
|
|
3614
|
+
/**
|
|
3615
|
+
* @internal createKernel({ restore, mounts }), before the kernel runs:
|
|
3616
|
+
* serve the snapshot's mounts again and tell the kernel to keep their
|
|
3617
|
+
* connections. Returns the mounts to mount once it runs.
|
|
3618
|
+
*/
|
|
3619
|
+
restoreMounts(snap: KernelSnapshot, list: ReturnType<typeof parseMounts>): Promise<ReturnType<typeof parseMounts>>;
|
|
3620
|
+
/** @internal createKernel's `mounts`, once the kernel runs. */
|
|
3621
|
+
startMounts(list: ReturnType<typeof parseMounts>): void;
|
|
3622
|
+
/**
|
|
3623
|
+
* With the vsock option: listen() for guest connections to the host
|
|
3624
|
+
* (CID 2, any port) and connect() to guest listeners (CID 3), each a
|
|
3625
|
+
* byte stream with half-close and reset (VsockHost, vsock.ts).
|
|
3626
|
+
*/
|
|
3627
|
+
get vsock(): VsockHost | undefined;
|
|
3628
|
+
/**
|
|
3629
|
+
* A program on its own pty, or on pipes (`pty: false`), served by the
|
|
3630
|
+
* guest's kwtty on vsock port 1022 (tty.ts).
|
|
3631
|
+
*/
|
|
3632
|
+
spawn(file: string | undefined, args: readonly string[] | undefined, opts: PipeOptions): Promise<Subprocess>;
|
|
3633
|
+
spawn(file?: string, args?: readonly string[], opts?: PtyOptions): Promise<Pty>;
|
|
3634
|
+
exec(file: string, args?: readonly string[], opts?: ExecOptions & {
|
|
3635
|
+
encoding?: "utf8";
|
|
3636
|
+
}): Promise<ExecResult<string>>;
|
|
3637
|
+
exec(file: string, args: readonly string[] | undefined, opts: ExecOptions & {
|
|
3638
|
+
encoding: "buffer";
|
|
3639
|
+
}): Promise<ExecResult<Uint8Array>>;
|
|
3640
|
+
/** A raw byte stream to a TCP server on the guest's loopback (see KernelHandle.connect()). */
|
|
3641
|
+
connect(port: number, opts?: ConnectOptions): Promise<GuestSocket>;
|
|
3642
|
+
/** HTTP/1.1 to a server on the guest's loopback (see KernelHandle.fetch()). */
|
|
3643
|
+
fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
|
|
3644
|
+
/** Mount a host file system in the guest (mounts.ts; see KernelHandle.mount()). */
|
|
3645
|
+
mount(path: string, fs: FsSource, opts?: MountOptions): Promise<Mount>;
|
|
3646
|
+
get mounts(): ReadonlyMap<string, Mount>;
|
|
3647
|
+
/**
|
|
3648
|
+
* With the shm option: open guest shmem files by name or by a guest
|
|
3649
|
+
* export's id and read and write their pages in place (shm.ts). Handles
|
|
3650
|
+
* have views() too: zero-copy views of the kernel's memory, valid until
|
|
3651
|
+
* the kernel runs again.
|
|
3652
|
+
*/
|
|
3653
|
+
get shm(): ShmClient<InlineShmFile> | undefined;
|
|
3654
|
+
/** @internal Disks built from specs, closed (after their last save) when the kernel exits. */
|
|
3655
|
+
own(disks: BlockDevice[]): void;
|
|
3656
|
+
/** Resolves once every save in flight on the disks has settled (a no-op for disks without saves). */
|
|
3657
|
+
settled(): Promise<void>;
|
|
3658
|
+
/** @internal Console output from the kernel. */
|
|
3659
|
+
emit(bytes: Uint8Array): void;
|
|
3660
|
+
/**
|
|
3661
|
+
* Console output as a stream. The first access gets everything since
|
|
3662
|
+
* boot (the last 1 MiB); later chunks are queued without limit, so keep
|
|
3663
|
+
* reading it (or use onOutput()). Closes when the kernel exits. There is
|
|
3664
|
+
* one such stream; tee() it for more readers.
|
|
3665
|
+
*/
|
|
3666
|
+
get output(): ReadableStream<Uint8Array>;
|
|
3667
|
+
/** Call `listener` with console output from now on. Returns the unsubscribe function. */
|
|
3668
|
+
onOutput(listener: (bytes: Uint8Array) => void): () => void;
|
|
3669
|
+
/** Type into the console (bytes, or text encoded as UTF-8); "\n" or "\r" is Enter. */
|
|
3670
|
+
write(data: Uint8Array | string): void;
|
|
3671
|
+
/** Console input as a stream (e.g. pipe a terminal into it). */
|
|
3672
|
+
get input(): WritableStream<Uint8Array | string>;
|
|
3673
|
+
/** Set the console window size; the guest's foreground process gets SIGWINCH. */
|
|
3674
|
+
resize(cols: number, rows: number): void;
|
|
3675
|
+
/**
|
|
3676
|
+
* Ask the guest to write back all file systems and flush its disks (the
|
|
3677
|
+
* sync IRQ), e.g. before a page goes away. Resolves true once every
|
|
3678
|
+
* persistent disk (FileDisk, a CowDisk saved in IndexedDB) has completed
|
|
3679
|
+
* a flush issued after the call, false after `timeout` ms (default 3000).
|
|
3680
|
+
* True at once without persistent disks.
|
|
3681
|
+
*/
|
|
3682
|
+
sync(opts?: {
|
|
3683
|
+
timeout?: number;
|
|
3684
|
+
}): Promise<boolean>;
|
|
3685
|
+
/**
|
|
3686
|
+
* Save the machine (Kernel.snapshot()); resume it with createKernel({
|
|
3687
|
+
* restore }). Disks are not copied: the snapshot stays restorable only
|
|
3688
|
+
* while they are unchanged. Without `stop` the guest keeps running, and
|
|
3689
|
+
* its next disk write ends that; `stop: true` stops the kernel right
|
|
3690
|
+
* after the copy (no clean shutdown), the usual way to suspend a machine
|
|
3691
|
+
* with disks. The devices' host state is saved (display, input, sound,
|
|
3692
|
+
* shm exports, the network's MAC); vsock sessions and TCP connections
|
|
3693
|
+
* are not (a restored guest's ends are reset). Host file systems are:
|
|
3694
|
+
* each mount's 9p session and the guest's open files on it (not the
|
|
3695
|
+
* files themselves; restore with the same `mounts`). Rejects while a
|
|
3696
|
+
* mount or unmount runs, or when a 9p request is in flight at the
|
|
3697
|
+
* snapshot point.
|
|
3698
|
+
*/
|
|
3699
|
+
snapshot(opts?: {
|
|
3700
|
+
stop?: boolean;
|
|
3701
|
+
}): Promise<KernelSnapshot>;
|
|
3702
|
+
/**
|
|
3703
|
+
* Stop the kernel now (no clean shutdown: the guest is not told and
|
|
3704
|
+
* unflushed disk writes are lost; prefer typing `poweroff` or call
|
|
3705
|
+
* sync() first). Resolves
|
|
3706
|
+
* with the exit, which is the stop unless the kernel had already exited.
|
|
3707
|
+
*/
|
|
3708
|
+
stop(res?: {
|
|
3709
|
+
code?: number;
|
|
3710
|
+
reason?: string;
|
|
3711
|
+
}): Promise<ExitResult>;
|
|
3712
|
+
stats(): InstanceStats;
|
|
3713
|
+
/** The kernel runs on this thread. */
|
|
3714
|
+
get transport(): KernelTransport;
|
|
3715
|
+
/** The sound card's host side, if the sound option was set: `playing`, `state`, `stats`. */
|
|
3716
|
+
get sound(): SoundHost | undefined;
|
|
3717
|
+
/** Memory actually allocated, in MiB. */
|
|
3718
|
+
get memoryMiB(): number;
|
|
3719
|
+
get memory64(): boolean;
|
|
3720
|
+
/**
|
|
3721
|
+
* The display's host side, if the display option was set: its mode and
|
|
3722
|
+
* the address of the pixels while a guest program has /dev/fb0 open.
|
|
3723
|
+
*/
|
|
3724
|
+
get display(): DisplayHost | undefined;
|
|
3725
|
+
/**
|
|
3726
|
+
* The current frame as RGBA (canvas ImageData layout), or null when there
|
|
3727
|
+
* is no display or no program has it open. The guest is suspended
|
|
3728
|
+
* whenever this can run, but a program may be in the middle of drawing;
|
|
3729
|
+
* call it once per animation frame at most. `out` is reused when it has
|
|
3730
|
+
* the right size.
|
|
3731
|
+
*/
|
|
3732
|
+
/**
|
|
3733
|
+
* The keyboard and mouse (with the display option): key(), button(),
|
|
3734
|
+
* move(), wheel(), and their open state (keyboardOpen, mouseOpen).
|
|
3735
|
+
*/
|
|
3736
|
+
get evdev(): InputHost | undefined;
|
|
3737
|
+
frame(out?: Uint8ClampedArray): DisplayFrame | null;
|
|
3738
|
+
/** frame(), as a promise (the same call as WorkerKernel.readFrame(), which needs a round trip). */
|
|
3739
|
+
readFrame(out?: Uint8ClampedArray): Promise<DisplayFrame | null>;
|
|
3740
|
+
}
|
|
3741
|
+
/**
|
|
3742
|
+
* The default Wisp server: the project's own. Public alternatives (run by
|
|
3743
|
+
* third parties, who see the host names and ports the guest connects to and
|
|
3744
|
+
* plain-HTTP content; the guest's TLS is end to end): wss://anura.pro/,
|
|
3745
|
+
* wss://wisp.mercurywork.shop/. A ws:// server is blocked as mixed content
|
|
3746
|
+
* on an https page.
|
|
3747
|
+
*/
|
|
3748
|
+
export declare const DEFAULT_WISP_SERVERS: readonly string[];
|
|
3749
|
+
export interface WispBackendOptions {
|
|
3750
|
+
log?: (msg: string) => void;
|
|
3751
|
+
/**
|
|
3752
|
+
* Extra handshake headers, e.g. `{ Origin: "http://localhost" }`. Only
|
|
3753
|
+
* runtimes whose WebSocket takes `{ headers }` (Node, Deno, Bun) send
|
|
3754
|
+
* them; in browsers, which set Origin themselves, the option is ignored.
|
|
3755
|
+
* The Node entry's wispBackend() defaults to NODE_WISP_HEADERS.
|
|
3756
|
+
*/
|
|
3757
|
+
headers?: Record<string, string>;
|
|
3758
|
+
}
|
|
3759
|
+
/** A Wisp backend; close() drops the WebSocket (and with it every stream). */
|
|
3760
|
+
export interface WispBackend extends NetBackend {
|
|
3761
|
+
close(): void;
|
|
3762
|
+
}
|
|
3763
|
+
/**
|
|
3764
|
+
* @param url Wisp endpoint(s), e.g. "wss://wisp.example/" (trailing slash
|
|
3765
|
+
* per the spec). Several are raced; the fastest handshake wins.
|
|
3766
|
+
*/
|
|
3767
|
+
export declare function wispBackend(url: string | readonly string[], opts?: WispBackendOptions): WispBackend;
|
|
3768
|
+
/** A kernel log line: "[ 1.234567] ...". */
|
|
3769
|
+
export declare const KSTAMP: RegExp;
|
|
3770
|
+
/** Kernel messages worth showing even when kernel lines are hidden. */
|
|
3771
|
+
export declare const IMPORTANT: RegExp;
|
|
3772
|
+
/** ANSI escape sequences (CSI, charset selection, keypad modes, save/restore). */
|
|
3773
|
+
export declare const ANSI: RegExp;
|
|
3774
|
+
export interface KernelLineInfo {
|
|
3775
|
+
/** The time stamp, seconds since boot. */
|
|
3776
|
+
time: number;
|
|
3777
|
+
/** Matches IMPORTANT (panic, oops, OOM kill, segfault, ...). */
|
|
3778
|
+
important: boolean;
|
|
3779
|
+
/** The line as received, with its line end. */
|
|
3780
|
+
raw: string;
|
|
3781
|
+
}
|
|
3782
|
+
export interface ConsoleRouterOptions {
|
|
3783
|
+
/** A kernel message, without "\r" and the line end. */
|
|
3784
|
+
onKernelLine?: (line: string, info: KernelLineInfo) => void;
|
|
3785
|
+
/** User-space output (including `dmesg` output), as it arrives. */
|
|
3786
|
+
onUserOutput?: (text: string) => void;
|
|
3787
|
+
/**
|
|
3788
|
+
* Once: user space printed its first non-empty line, or a shell prompt.
|
|
3789
|
+
* `why` is "first output: <line>" or "shell prompt".
|
|
3790
|
+
*/
|
|
3791
|
+
onUserspace?: (why: string) => void;
|
|
3792
|
+
/** How long an undecidable line start is held back, default 250 ms. */
|
|
3793
|
+
holdMs?: number;
|
|
3794
|
+
}
|
|
3795
|
+
export declare class ConsoleRouter {
|
|
3796
|
+
#private;
|
|
3797
|
+
/** Whether user space has started printing (onUserspace fired). */
|
|
3798
|
+
userspace: boolean;
|
|
3799
|
+
constructor(opts?: ConsoleRouterOptions);
|
|
3800
|
+
/** Console output: bytes (decoded as a UTF-8 stream) or text. */
|
|
3801
|
+
write(data: Uint8Array | string): void;
|
|
3802
|
+
/** Release a held-back line start as user output now. */
|
|
3803
|
+
flush(): void;
|
|
3804
|
+
}
|
|
3805
|
+
export interface SupportReport {
|
|
3806
|
+
/** Everything the default (lowered, 32-bit memory) kernel needs: WebAssembly, BigInt and working JSPI. */
|
|
3807
|
+
ok: boolean;
|
|
3808
|
+
wasm: boolean;
|
|
3809
|
+
bigint: boolean;
|
|
3810
|
+
/** WebAssembly.Suspending and WebAssembly.promising exist and a suspend/resume round trip works. */
|
|
3811
|
+
jspi: boolean;
|
|
3812
|
+
/** memory64: only the wasm64 reference kernel (vmlinux) needs it. */
|
|
3813
|
+
memory64: boolean;
|
|
3814
|
+
/** Why `ok` is false (empty when it is true). */
|
|
3815
|
+
problems: string[];
|
|
3816
|
+
}
|
|
3817
|
+
/** Check JSPI by suspending a tiny module on a timer and resuming it. */
|
|
3818
|
+
export declare function checkJspi(timeoutMs?: number): Promise<{
|
|
3819
|
+
ok: boolean;
|
|
3820
|
+
why?: string;
|
|
3821
|
+
}>;
|
|
3822
|
+
/** What this engine supports, and whether that is enough to boot the default kernel. */
|
|
3823
|
+
export declare function checkSupport(): Promise<SupportReport>;
|
|
3824
|
+
/** A byte stream to a server in the guest. */
|
|
3825
|
+
export interface ByteDuplex {
|
|
3826
|
+
readable: ReadableStream<Uint8Array>;
|
|
3827
|
+
writable: WritableStream<Uint8Array>;
|
|
3828
|
+
}
|
|
3829
|
+
/** Open a byte stream to the guest's 127.0.0.1:<port>. */
|
|
3830
|
+
export type GuestConnect = (port: number, opts: {
|
|
3831
|
+
signal?: AbortSignal;
|
|
3832
|
+
}) => Promise<ByteDuplex>;
|
|
3833
|
+
/** The largest status line plus header block accepted, interim responses included. */
|
|
3834
|
+
export declare const HTTP_MAX_HEADER_BYTES: number;
|
|
3835
|
+
/**
|
|
3836
|
+
* Fetch from a server in the guest: always connects to the guest's
|
|
3837
|
+
* 127.0.0.1:<port>, the URL's port (default 80). Only http: URLs. The
|
|
3838
|
+
* hostname goes only into the Host header. Takes what fetch() takes; a
|
|
3839
|
+
* Request's own body is read in full first and sent with Content-Length,
|
|
3840
|
+
* a ReadableStream (or other streaming) `init.body` is sent chunked.
|
|
3841
|
+
* Redirects are returned, not followed. Rejects 101 Switching Protocols.
|
|
3842
|
+
*/
|
|
3843
|
+
export declare function fetchOver(connect: GuestConnect, input: string | URL | Request, init?: RequestInit): Promise<Response>;
|
|
3844
|
+
export {};
|