.githooks/
riscv/
test/
.clang-format
570 B
.gitignore
5 B
.gitsigners
112 B
AGENTS.md
227 B
LICENSE
1.1 KiB
Makefile
3.5 KiB
README
12.5 KiB
STYLE
781 B
abi_host.c
12.2 KiB
abi_linux.c
3.7 KiB
bitmanip.h
5.8 KiB
color.h
567 B
debug_map.c
5.1 KiB
debug_map.h
1.3 KiB
emulator.c
87.3 KiB
host.h
5.5 KiB
host_posix.c
11.2 KiB
hosted.h
5.7 KiB
image_native.c
4.6 KiB
image_rad0.c
2.7 KiB
image_raw.c
2.6 KiB
io.c
1.1 KiB
io.h
444 B
jit.c
99.2 KiB
jit.h
7.8 KiB
machine.c
4.4 KiB
machine.h
2.1 KiB
machine_cpu.c
13.6 KiB
machine_csr.c
4.6 KiB
machine_devices.c
10.8 KiB
machine_fdt.c
8.7 KiB
machine_internal.h
7.4 KiB
muldiv.h
1.0 KiB
profile.c
17.5 KiB
profile.h
1.4 KiB
riscv.c
755 B
riscv.h
4.3 KiB
types.h
1019 B
vector.c
54.0 KiB
vector.h
1.3 KiB
host.h
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 */ |