/* Host platform layer for the hosted system call ABI. * * Every operation that touches the host operating system on behalf of a * guest goes through this interface. The emulator decodes guest memory and * calls these functions; it never calls host file or process functions for * guest requests itself. A port to another host implements this header. * * Fallible functions return a value >= 0 on success, or a negative `HOST_E_*` * code, which equals the error code of the guest ABI. Paths are NUL-terminated * host strings. Files are identified by small host descriptors; the emulator * maps guest descriptors onto them. */ #ifndef HOST_H #define HOST_H #include "types.h" /* Longest path accepted from a guest, including the terminating zero. */ #define HOST_PATH_MAX 4096 /* Error codes, shared with the guest ABI. */ #define HOST_E_NOT_FOUND -1 /* No such file, directory or child. */ #define HOST_E_EXISTS -2 /* The path already exists. */ #define HOST_E_DENIED -3 /* The host refused access. */ #define HOST_E_NOT_EMPTY -4 /* The directory is not empty. */ #define HOST_E_INVALID -5 /* Bad argument, mode, path or call. */ #define HOST_E_TOO_LARGE -6 /* The output buffer is too small. */ #define HOST_E_LIMIT -7 /* Too many open files or running children. */ #define HOST_E_IO -8 /* Any other host failure. */ /* Kind of a file system object, as reported by `host_stat`. */ enum host_kind { HOST_KIND_FILE = 1, HOST_KIND_DIR = 2, HOST_KIND_OTHER = 3, }; /* File metadata. */ struct host_stat { u64 size; /* Size in bytes, zero for directories. */ u32 kind; /* One of `enum host_kind`. */ }; /* Where a child's standard output or error goes. */ enum host_output { HOST_OUT_INHERIT = 0, /* Share the emulator's stream. */ HOST_OUT_DISCARD = 1, /* Write to the null device. */ HOST_OUT_FILE = 2, /* Create or truncate a file. */ HOST_OUT_MERGE = 3, /* Standard error only: share standard output. */ }; /* How a child ended, as reported by the child emulator itself. */ enum host_outcome_kind { HOST_OUTCOME_EXITED = 0, /* The guest exited; `code` is its status. */ HOST_OUTCOME_STEPS = 1, /* The step budget ran out. */ HOST_OUTCOME_FAULT = 2, /* A runtime fault, or the child crashed. */ }; /* Final state of a child. */ struct host_outcome { u32 kind; /* One of `enum host_outcome_kind`. */ i32 code; /* Exit status when exited, otherwise zero. */ }; /* Request to start a child emulator process. */ struct host_spawn { char *const *argv; /* Emulator options and guest arguments after the * program name, NULL terminated. The program * name argv[0] is filled in by the host layer. */ u32 out_kind; /* `host_output` for standard output. */ const char *out_path; /* File for `HOST_OUT_FILE`. */ u32 err_kind; /* `host_output` for standard error. */ const char *err_path; /* File for `HOST_OUT_FILE`. */ }; /* Descriptor number on which a child receives its outcome pipe. The parent * passes it to the child as `-outcome-fd=N`. */ #define HOST_OUTCOME_FD 3 /* Maximum number of children that can be running at once. */ #define HOST_MAX_CHILDREN 64 /* Open an existing file for reading. The descriptor is not inherited by * children. Returns the descriptor. */ i64 host_open_read(const char *path); /* Create or truncate a file for writing with permissions 0644, subject to * the host umask. Returns the descriptor. */ i64 host_open_write(const char *path); /* Read up to `len` bytes. Returns the count, zero at end of file. */ i64 host_read(int fd, void *buf, u32 len); /* Write up to `len` bytes. Returns the count written. */ i64 host_write(int fd, const void *buf, u32 len); /* Close a descriptor returned by one of the open functions. */ i64 host_close(int fd); /* Describe the object at `path`. */ i64 host_stat(const char *path, struct host_stat *out); /* Create one directory level. */ i64 host_make_dir(const char *path); /* Remove a file or an empty directory. */ i64 host_remove(const char *path); /* Rename a file or directory, replacing an existing file. */ i64 host_rename(const char *from, const char *to); /* Atomically exchange two existing directory entries on the same filesystem. */ i64 host_exchange(const char *left, const char *right); /* List a directory into `buf`: each entry name followed by a zero byte, * excluding "." and "..", in host order. Returns the byte count, or * `HOST_E_TOO_LARGE` if `cap` bytes are not enough. */ i64 host_list_dir(const char *path, u8 *buf, u32 cap); /* Start a child emulator, running this emulator's own executable with the * given request. The child reports its outcome through a private pipe, and * its standard input is the null device. Returns a child handle. */ i64 host_spawn(const struct host_spawn *spec); /* Wait for one child to end and store its outcome. The handle is released. * `HOST_E_NOT_FOUND` for an unknown handle. */ i64 host_wait(i64 child, struct host_outcome *out); /* Wait for any running child. Returns its handle, and releases it. * `HOST_E_NOT_FOUND` when no child is running. */ i64 host_wait_any(struct host_outcome *out); /* Arrange for every child that has not been waited for to be terminated * and reaped when this process exits or is asked to terminate. */ void host_init(void); /* Write the outcome record for this process to `fd`, as the child side of * `host_spawn`. The record is 8 bytes: kind and code, little-endian. */ void host_report_outcome(int fd, const struct host_outcome *outcome); #endif /* HOST_H */