lib/std/process.rad 6.2 KiB raw
1
//! Starting RV64 guest images through the host.
2
//!
3
//! A child is an image run by the same emulator as the parent. Guests never
4
//! name host executables.
5
6
use std::mem;
7
use std::sys;
8
use std::sys::host;
9
10
/// Destination of a child's standard output or standard error.
11
export union Output: Copy {
12
    /// Share the parent's stream.
13
    Inherit,
14
    /// Drop everything the child writes.
15
    Discard,
16
    /// Create or truncate the file at the path. Equal paths merge both streams.
17
    File(*[u8]),
18
}
19
20
/// Sizes of a hosted child, in KB. Zero selects the host default.
21
export record Memory: Copy {
22
    /// Guest memory size.
23
    memory: u32,
24
    /// Data segment size.
25
    data: u32,
26
    /// Stack size.
27
    stack: u32,
28
}
29
30
/// A machine interrupt source that fires once.
31
export record Irq: Copy {
32
    /// Interrupt source number. Zero is reserved for none.
33
    source: u32,
34
    /// Machine tick of the interrupt edge.
35
    tick: u64,
36
}
37
38
/// Machine configuration of a child that runs without the hosted runtime.
39
export record Machine: Copy {
40
    /// Hart count. Zero selects the host default.
41
    harts: u32,
42
    /// Memory size in KB. Zero selects the host default.
43
    memory: u32,
44
    /// One-shot interrupt, if any.
45
    irq: ?Irq,
46
}
47
48
/// How the host runs the image.
49
export union Target: Copy {
50
    /// Hosted program with the given sizes.
51
    Hosted(Memory),
52
    /// Hosted program with the parent's memory, data and stack sizes.
53
    Inherit,
54
    /// Bare machine.
55
    Machine(Machine),
56
}
57
58
/// Description of a child to start.
59
export record Command: Copy {
60
    /// Path of the RV64 image.
61
    image: *[u8],
62
    /// Arguments the child receives. Element zero is the first argument.
63
    args: *[*[u8]],
64
    /// Standard output destination.
65
    stdout: Output,
66
    /// Standard error destination.
67
    stderr: Output,
68
    /// Execution mode and sizes.
69
    target: Target,
70
    /// Instruction budget, or `nil` for the host default.
71
    maxSteps: ?u64,
72
}
73
74
/// Handle of a running child. It is valid until the child is waited for.
75
export record Child: Copy {
76
    /// Host identifier of the child.
77
    handle: u32,
78
}
79
80
/// How a child ended.
81
export union Outcome: Copy {
82
    /// The child exited with a status.
83
    Exited(i32),
84
    /// The child used up its step budget.
85
    StepLimit,
86
    /// The child faulted.
87
    Fault,
88
}
89
90
/// A finished child and how it ended.
91
export record Exit: Copy {
92
    /// The child that finished.
93
    child: Child,
94
    /// How it ended.
95
    outcome: Outcome,
96
}
97
98
/// Return the stream kind code of an output.
99
fn kind(output: Output) -> u64 {
100
    match output {
101
        case Output::Inherit => return 0,
102
        case Output::Discard => return 1,
103
        case Output::File(_) => return 2,
104
    }
105
}
106
107
/// Decode an `Outcome` record: a 32-bit kind (exited, step limit or fault)
108
/// and a 32-bit exit status.
109
fn decode(raw: &[u8]) -> Outcome {
110
    match mem::readLe(raw, 0, 4) {
111
        case 0 => return Outcome::Exited(mem::readLe(raw, 4, 4) as u32 as i32),
112
        case 1 => return Outcome::StepLimit,
113
        else   => return Outcome::Fault,
114
    }
115
}
116
117
/// Sequential writer of the little-endian fields of the host `Spawn` record.
118
/// The buffer starts zeroed, so padding and unset fields read as zero.
119
record Spawn {
120
    /// The 128-byte record.
121
    raw: [u8; 128],
122
    /// Offset of the next field.
123
    pos: u32,
124
}
125
126
/// Append an integer field of `size` bytes.
127
fn (s: &mut Spawn) put(value: u64, size: u32) {
128
    mem::writeLe(&mut s.raw[..], s.pos, value, size);
129
    set s.pos += size;
130
}
131
132
/// Append a slice field: 64-bit pointer, 32-bit length and padding.
133
fn (s: &mut Spawn) slice(pointer: i64, len: u32) {
134
    s.put(pointer as u64, 8);
135
    s.put(len as u64, 8);
136
}
137
138
/// Append the mode, harts, memory, data, stack, interrupt source and
139
/// interrupt tick fields. Without an interrupt the last two are zero.
140
fn (s: &mut Spawn) row(mode: u32, harts: u32, memory: u32, data: u32, stack: u32, irq: ?Irq) {
141
    for field in &[mode, harts, memory, data, stack] {
142
        s.put(field as u64, 4);
143
    }
144
    let mut edge = Irq { source: 0, tick: 0 };
145
    if let given = irq {
146
        set edge = given;
147
    }
148
    s.put(edge.source as u64, 4);
149
    s.put(edge.tick, 8);
150
}
151
152
/// Start a child. The child runs concurrently until it is waited for.
153
/// Throws `Limit` when too many children run, and `NotFound` or `Invalid`
154
/// when the image cannot be started.
155
export fn spawn(command: &Command) -> Child throws (sys::Error) {
156
    // The fields follow the Spawn record of the host ABI, in order.
157
    let mut s = Spawn { raw: [0; 128], pos: 0 };
158
    s.slice(host::addr(command.image), command.image.len);
159
    // The argument array is passed as the slice array it already is.
160
    unsafe {
161
        s.slice(command.args.ptr as i64, command.args.len);
162
    }
163
    s.put(kind(command.stdout), 4);
164
    s.put(kind(command.stderr), 4);
165
    for output in &[command.stdout, command.stderr] {
166
        if let case Output::File(file) = output {
167
            s.slice(host::addr(file), file.len);
168
        } else {
169
            s.put(0, 16);
170
        }
171
    }
172
    let mut flags: u64 = 0;
173
    match command.target {
174
        case Target::Hosted(m)  => s.row(0, 0, m.memory, m.data, m.stack, nil),
175
        case Target::Machine(m) => s.row(1, m.harts, m.memory, 0, 0, m.irq),
176
        case Target::Inherit => {
177
            s.row(0, 0, 0, 0, 0, nil);
178
            set flags = 1;
179
        }
180
    }
181
    let mut steps: u64 = 0;
182
    if let limit = command.maxSteps {
183
        set steps = limit;
184
    }
185
    s.put(steps, 8);
186
    s.put(flags, 4);
187
    let handle = try host::call(host::SPAWN, host::addr(&s.raw[..]), 0, 0, 0);
188
    return Child { handle: handle as u32 };
189
}
190
191
/// Wait for a child to finish and return how it ended.
192
export fn wait(child: Child) -> Outcome throws (sys::Error) {
193
    let mut raw: [u8; 8] = [0; 8];
194
    try host::call(host::WAIT, child.handle as i64, host::addr(&raw[..]), 0, 0);
195
    return decode(&raw[..]);
196
}
197
198
/// Wait for any child to finish. Throws `NotFound` when none is running.
199
export fn waitAny() -> Exit throws (sys::Error) {
200
    let mut raw: [u8; 8] = [0; 8];
201
    let handle = try host::call(host::WAIT_ANY, host::addr(&raw[..]), 0, 0, 0);
202
    return Exit { child: Child { handle: handle as u32 }, outcome: decode(&raw[..]) };
203
}
204
205
/// Start a child and wait for it.
206
export fn run(command: &Command) -> Outcome throws (sys::Error) {
207
    let child = try spawn(command);
208
    return try wait(child);
209
}