host.h 5.5 KiB raw
1
/* Host platform layer for the hosted system call ABI.
2
 *
3
 * Every operation that touches the host operating system on behalf of a
4
 * guest goes through this interface. The emulator decodes guest memory and
5
 * calls these functions; it never calls host file or process functions for
6
 * guest requests itself. A port to another host implements this header.
7
 *
8
 * Fallible functions return a value >= 0 on success, or a negative `HOST_E_*`
9
 * code, which equals the error code of the guest ABI. Paths are NUL-terminated
10
 * host strings. Files are identified by small host descriptors; the emulator
11
 * maps guest descriptors onto them. */
12
#ifndef HOST_H
13
#define HOST_H
14
15
#include "types.h"
16
17
/* Longest path accepted from a guest, including the terminating zero. */
18
#define HOST_PATH_MAX 4096
19
20
/* Error codes, shared with the guest ABI. */
21
#define HOST_E_NOT_FOUND -1 /* No such file, directory or child. */
22
#define HOST_E_EXISTS    -2 /* The path already exists. */
23
#define HOST_E_DENIED    -3 /* The host refused access. */
24
#define HOST_E_NOT_EMPTY -4 /* The directory is not empty. */
25
#define HOST_E_INVALID   -5 /* Bad argument, mode, path or call. */
26
#define HOST_E_TOO_LARGE -6 /* The output buffer is too small. */
27
#define HOST_E_LIMIT     -7 /* Too many open files or running children. */
28
#define HOST_E_IO        -8 /* Any other host failure. */
29
30
/* Kind of a file system object, as reported by `host_stat`. */
31
enum host_kind {
32
    HOST_KIND_FILE  = 1,
33
    HOST_KIND_DIR   = 2,
34
    HOST_KIND_OTHER = 3,
35
};
36
37
/* File metadata. */
38
struct host_stat {
39
    u64 size; /* Size in bytes, zero for directories. */
40
    u32 kind; /* One of `enum host_kind`. */
41
};
42
43
/* Where a child's standard output or error goes. */
44
enum host_output {
45
    HOST_OUT_INHERIT = 0, /* Share the emulator's stream. */
46
    HOST_OUT_DISCARD = 1, /* Write to the null device. */
47
    HOST_OUT_FILE    = 2, /* Create or truncate a file. */
48
    HOST_OUT_MERGE   = 3, /* Standard error only: share standard output. */
49
};
50
51
/* How a child ended, as reported by the child emulator itself. */
52
enum host_outcome_kind {
53
    HOST_OUTCOME_EXITED = 0, /* The guest exited; `code` is its status. */
54
    HOST_OUTCOME_STEPS  = 1, /* The step budget ran out. */
55
    HOST_OUTCOME_FAULT  = 2, /* A runtime fault, or the child crashed. */
56
};
57
58
/* Final state of a child. */
59
struct host_outcome {
60
    u32 kind; /* One of `enum host_outcome_kind`. */
61
    i32 code; /* Exit status when exited, otherwise zero. */
62
};
63
64
/* Request to start a child emulator process. */
65
struct host_spawn {
66
    char *const *argv;    /* Emulator options and guest arguments after the
67
                           * program name, NULL terminated. The program
68
                           * name argv[0] is filled in by the host layer. */
69
    u32         out_kind; /* `host_output` for standard output. */
70
    const char *out_path; /* File for `HOST_OUT_FILE`. */
71
    u32         err_kind; /* `host_output` for standard error. */
72
    const char *err_path; /* File for `HOST_OUT_FILE`. */
73
};
74
75
/* Descriptor number on which a child receives its outcome pipe. The parent
76
 * passes it to the child as `-outcome-fd=N`. */
77
#define HOST_OUTCOME_FD 3
78
79
/* Maximum number of children that can be running at once. */
80
#define HOST_MAX_CHILDREN 64
81
82
/* Open an existing file for reading. The descriptor is not inherited by
83
 * children. Returns the descriptor. */
84
i64 host_open_read(const char *path);
85
86
/* Create or truncate a file for writing with permissions 0644, subject to
87
 * the host umask. Returns the descriptor. */
88
i64 host_open_write(const char *path);
89
90
/* Read up to `len` bytes. Returns the count, zero at end of file. */
91
i64 host_read(int fd, void *buf, u32 len);
92
93
/* Write up to `len` bytes. Returns the count written. */
94
i64 host_write(int fd, const void *buf, u32 len);
95
96
/* Close a descriptor returned by one of the open functions. */
97
i64 host_close(int fd);
98
99
/* Describe the object at `path`. */
100
i64 host_stat(const char *path, struct host_stat *out);
101
102
/* Create one directory level. */
103
i64 host_make_dir(const char *path);
104
105
/* Remove a file or an empty directory. */
106
i64 host_remove(const char *path);
107
108
/* Rename a file or directory, replacing an existing file. */
109
i64 host_rename(const char *from, const char *to);
110
/* Atomically exchange two existing directory entries on the same filesystem. */
111
i64 host_exchange(const char *left, const char *right);
112
113
/* List a directory into `buf`: each entry name followed by a zero byte,
114
 * excluding "." and "..", in host order. Returns the byte count, or
115
 * `HOST_E_TOO_LARGE` if `cap` bytes are not enough. */
116
i64 host_list_dir(const char *path, u8 *buf, u32 cap);
117
118
/* Start a child emulator, running this emulator's own executable with the
119
 * given request. The child reports its outcome through a private pipe, and
120
 * its standard input is the null device. Returns a child handle. */
121
i64 host_spawn(const struct host_spawn *spec);
122
123
/* Wait for one child to end and store its outcome. The handle is released.
124
 * `HOST_E_NOT_FOUND` for an unknown handle. */
125
i64 host_wait(i64 child, struct host_outcome *out);
126
127
/* Wait for any running child. Returns its handle, and releases it.
128
 * `HOST_E_NOT_FOUND` when no child is running. */
129
i64 host_wait_any(struct host_outcome *out);
130
131
/* Arrange for every child that has not been waited for to be terminated
132
 * and reaped when this process exits or is asked to terminate. */
133
void host_init(void);
134
135
/* Write the outcome record for this process to `fd`, as the child side of
136
 * `host_spawn`. The record is 8 bytes: kind and code, little-endian. */
137
void host_report_outcome(int fd, const struct host_outcome *outcome);
138
139
#endif /* HOST_H */