diff options
Diffstat (limited to 'ccdjit.h')
| -rw-r--r-- | ccdjit.h | 601 |
1 files changed, 601 insertions, 0 deletions
diff --git a/ccdjit.h b/ccdjit.h new file mode 100644 index 0000000..bf1e239 --- /dev/null +++ b/ccdjit.h @@ -0,0 +1,601 @@ +#ifndef CCDJIT_PUBLIC_H +#define CCDJIT_PUBLIC_H + +/* + * CCDJIT public embedding API + * + * This header is the stable boundary for hosts that want to compile and run C + * code at runtime. The implementation lives in ccdjit.c, but the intended use + * should be clear from this file alone. + * + * Basic use: + * + * ccdjit_context *ctx = ccdjit_context_new(NULL); + * ccdjit_module *module = NULL; + * + * if (ccdjit_compile_string(ctx, source, "plugin.c", &module) == 0) { + * int result = 0; + * ccdjit_module_call_main(module, 0, NULL, &result); + * ccdjit_module_free(module); + * } + * ccdjit_context_free(ctx); + * + * Return convention: + * Functions returning int use 0 for success and -1 for failure unless + * documented otherwise. On failure, call ccdjit_context_last_error(). + * + * Lifetime: + * A context owns options, include paths, registered symbols, and the last + * diagnostic. A module owns generated code or a loaded CCDJIT binary. + * Modules keep their context state alive, so ccdjit_context_free() may be + * called before ccdjit_module_free(); the context is released when the + * last module using it is freed. + * Function pointers returned by ccdjit_module_symbol() are invalid after + * ccdjit_module_free(). + * + * Runtime policy: + * Module calls, symbol lookup, and emission intentionally consult the + * current context options, sandbox settings, resource limits, registered + * symbols, resolver callback, and loaded libraries. Machine code that + * has already been compiled may contain resolved external addresses; use + * a new module or function-handle replacement when changing symbol + * bindings must affect already compiled call sites. + * + * Threads: + * Public API entry points are internally serialized, and module calls, + * symbol lookup, emission, and lazy compilation take a module lock. Raw + * function pointers returned by ccdjit_module_symbol() are still host + * pointers: do not free or replace their module while those pointers may + * run, and prefer typed handle/call helpers for dynamic bindings. + * + * Safety: + * Normal calls run in the host process. Set sandbox_execution to + * CCDJIT_SANDBOX_PROCESS to run ccdjit_module_call_main() in a child + * process with optional resource, syscall, and filesystem limits. Child + * crashes are reported through ccdjit_diagnostic. + */ + +#include <stddef.h> +#include <stdint.h> +#include <stdio.h> + +#ifdef __cplusplus +extern "C" { +#endif + +#define CCDJIT_VERSION_MAJOR 1 +#define CCDJIT_VERSION_MINOR 3 +#define CCDJIT_VERSION_PATCH 1 +#define CCDJIT_VERSION_STRING "1.3.1" +#define CCDJIT_API_ABI_VERSION 1 +#define CCDJITB2_FORMAT_VERSION 2 +#define CCDJITB2_FLAG_DEBUG_INFO 1u +/* + * CCDJITB2 fixed header layout, in bytes: + * magic "CCDJITB2" (8) + version (4) + flags (4) + text_size (8) + + * data_size (8) + rodata_size (8) + bss_size (8) + symbol_count (4) + + * reloc_count (4) + * Section payloads follow immediately. Every reader must check the file is + * at least this large before parsing the header fields, and the writer must + * emit exactly this many bytes before any payload. + */ +#define CCDJITB2_HEADER_SIZE 56 +#define CCDJITB2_MAGIC_SIZE 8 +#define CCDJITB2_SYMBOL_RECORD_SIZE 32 +#define CCDJITB2_RELOC_RECORD_SIZE 32 + +typedef struct ccdjit_context ccdjit_context; +typedef struct ccdjit_module ccdjit_module; +typedef struct ccdjit_function_handle ccdjit_function_handle; +typedef struct ccdjit_execution_result ccdjit_execution_result; + +typedef struct { + /* Host compiler or linker driver. NULL uses $CC, then cc. */ + const char *driver; + + /* Extra linker arguments such as -L, -l, or -Wl options. */ + const char *const *link_args; + size_t link_arg_count; + + /* Print the host linker command to stderr when nonzero. */ + int verbose; + + /* Wall-clock driver timeout. Zero uses the default. */ + unsigned int timeout_ms; + + /* Captured driver stdout/stderr cap. Zero uses the default. */ + size_t output_limit_bytes; +} ccdjit_link_options; + +/* + * Host symbol callback. Return NULL when the name is unknown. + * + * The returned pointer is used as an external function or object address by + * generated code. Keep any pointed-to object alive while modules using it may + * run. + */ +typedef void *(*ccdjit_symbol_resolver)(const char *name, void *userdata); + +typedef enum { + /* Run generated code directly in the host process. */ + CCDJIT_SANDBOX_OFF = 0, + + /* Run ccdjit_module_call_main() in a forked child process. */ + CCDJIT_SANDBOX_PROCESS = 1, +} ccdjit_sandbox_mode; + +typedef enum { + /* + * Minimal child profile: enough to write the result pipe, write + * captured output, and exit. Unexpected syscalls are trapped. + */ + CCDJIT_SANDBOX_SYSCALL_STRICT = 0, + + /* STRICT plus read/close for simple stdio-style code. */ + CCDJIT_SANDBOX_SYSCALL_STDIO = 1, + + /* STDIO plus mmap/munmap/mprotect/brk/clock_gettime. */ + CCDJIT_SANDBOX_SYSCALL_RUNTIME = 2, + + /* Disable the seccomp filter. Resource limits still apply. */ + CCDJIT_SANDBOX_SYSCALL_PERMISSIVE = 3, +} ccdjit_sandbox_syscall_policy; + +typedef enum { + /* Runtime file syscalls are denied by the syscall policy. */ + CCDJIT_SANDBOX_FS_NONE = 0, + + /* Permit read-only access under explicitly added roots. */ + CCDJIT_SANDBOX_FS_READ_ONLY_ROOTS = 1, + + /* Permit writes only for roots added with writable != 0. */ + CCDJIT_SANDBOX_FS_WRITABLE_ROOTS = 2, +} ccdjit_sandbox_filesystem_policy; + +typedef struct { + /* Allow #include to read files from include paths. */ + int allow_filesystem_includes; + + /* Allow the preprocessor to discover and read host system includes. */ + int allow_system_includes; + + /* Allow executable mappings for JIT code and loaded CCDJIT binaries. */ + int allow_executable_memory; + + /* ccdjit_sandbox_mode. Default is CCDJIT_SANDBOX_OFF. */ + int sandbox_execution; + + /* ccdjit_sandbox_syscall_policy. Default is STRICT. */ + int sandbox_syscalls; + + /* ccdjit_sandbox_filesystem_policy. Default is FS_NONE. */ + int sandbox_filesystem; + + /* + * In sandbox mode, default dlsym lookup is disabled unless this is set. + * Prefer explicit ccdjit_context_register_symbol() capabilities. + */ + int sandbox_allow_implicit_symbols; + + /* Wall-clock timeout for one sandboxed main call. Zero means no limit. + */ + unsigned int sandbox_timeout_ms; + + /* RLIMIT_CPU for sandboxed calls, rounded up to seconds by the OS. */ + unsigned int sandbox_cpu_time_ms; + + /* RLIMIT_AS for sandboxed calls. Zero means keep the host default. */ + size_t sandbox_address_space_bytes; + + /* RLIMIT_STACK for sandboxed calls. Zero means keep the host default. + */ + size_t sandbox_stack_bytes; + + /* RLIMIT_FSIZE for sandboxed calls. Zero means keep the host default. + */ + size_t sandbox_file_size_bytes; + + /* Captured stdout/stderr cap for sandboxed calls. Zero means 64 KiB. + */ + size_t sandbox_output_limit_bytes; + + /* Emit and retain optional debug/source mapping metadata. */ + int debug_info; + + /* + * Preprocessor output byte cap. Zero uses the default currently 128 + * MiB. + */ + size_t preprocessor_output_limit_bytes; + + /* Macro expansion recursion cap. Zero uses the default. */ + unsigned int preprocessor_macro_depth_limit; + + /* Nested include cap. Zero uses the default. */ + unsigned int preprocessor_include_depth_limit; + + /* + * Optional compiler driver used for host system include and builtin + * macro probes. NULL auto-detects from $CC, then common cc drivers. + */ + const char *preprocessor_compiler; + + /* Wall-clock timeout for one compiler probe. Zero uses the default. */ + unsigned int preprocessor_probe_timeout_ms; + + /* Captured compiler-probe output cap. Zero uses the default. */ + size_t preprocessor_probe_output_limit_bytes; +} ccdjit_options; + +typedef struct { + /* Compiler phase such as LEXER, PARSER, JIT, API, or SANDBOX. */ + const char *phase; + + /* Source file, binary path, symbol name, or "<input>". */ + const char *filename; + + /* Human-readable error text owned by the context. */ + const char *message; + + /* Optional source excerpt for lexer/parser/type diagnostics. */ + const char *source_line; + const char *caret_line; + + /* One-based line and column when available, otherwise zero. */ + int line; + int column; + + /* ccdjit_diagnostic_code plus optional code-specific detail. */ + int code; + int subcode; + + /* Raw child wait status or errno-style value for sandbox/API failures. + */ + int status; + + /* Signal that terminated the sandbox child, or zero. */ + int signal_number; + + /* Faulting address for sandboxed crash diagnostics, when available. */ + int has_fault_address; + uintptr_t fault_address; +} ccdjit_diagnostic; + +typedef enum { + CCDJIT_DIAG_NONE = 0, + CCDJIT_DIAG_LEXER = 1, + CCDJIT_DIAG_PARSER = 2, + CCDJIT_DIAG_PREPROCESSOR = 3, + CCDJIT_DIAG_TYPE = 4, + CCDJIT_DIAG_JIT = 5, + CCDJIT_DIAG_UNRESOLVED_SYMBOL = 6, + CCDJIT_DIAG_SANDBOX = 7, + CCDJIT_DIAG_SANDBOX_TIMEOUT = 8, + CCDJIT_DIAG_SANDBOX_FORBIDDEN_SYSCALL = 9, + CCDJIT_DIAG_SANDBOX_CRASH = 10, + CCDJIT_DIAG_INVALID_OPTIONS = 11, + CCDJIT_DIAG_INVALID_ARGUMENT = 12, + CCDJIT_DIAG_UNSUPPORTED_ABI = 13, + CCDJIT_DIAG_MALFORMED_BINARY = 14, + CCDJIT_DIAG_HOST_LINKER = 15, + CCDJIT_DIAG_OUT_OF_MEMORY = 16, +} ccdjit_diagnostic_code; + +typedef enum { + CCDJIT_SYMBOL_UNKNOWN = 0, + CCDJIT_SYMBOL_FUNCTION = 1, + CCDJIT_SYMBOL_OBJECT = 2, +} ccdjit_symbol_kind; + +typedef enum { + CCDJIT_TYPE_INT = 0, + CCDJIT_TYPE_CHAR = 1, + CCDJIT_TYPE_BOOL = 2, + CCDJIT_TYPE_VOID = 3, + CCDJIT_TYPE_FLOAT = 4, + CCDJIT_TYPE_DOUBLE = 5, + CCDJIT_TYPE_LONG = 6, + CCDJIT_TYPE_SHORT = 7, + CCDJIT_TYPE_STRUCT = 8, + CCDJIT_TYPE_ENUM = 9, + CCDJIT_TYPE_UNION = 10, + CCDJIT_TYPE_FLOAT128 = 11, +} ccdjit_type_base; + +typedef struct { + int has_type; + int base; + int pointer_level; + int array_size; + int is_unsigned; + int is_complex; + int is_atomic; +} ccdjit_type_info; + +typedef struct { + int kind; + int has_signature; + ccdjit_type_info type; + ccdjit_type_info return_type; + size_t parameter_count; + int is_variadic; + size_t size; +} ccdjit_symbol_info; + +typedef struct { + int process; + int seccomp; + int landlock; +} ccdjit_sandbox_capabilities; + +typedef struct { + const char *filename; + const char *function; + int line; + int column; + uintptr_t address; + size_t size; +} ccdjit_debug_location; + +/* + * Create a compiler context. Passing NULL uses permissive CLI-like defaults. + * Invalid options return NULL; call ccdjit_context_last_error(NULL) for the + * thread-local creation diagnostic. + */ +ccdjit_context *ccdjit_context_new(const ccdjit_options *options); + +int ccdjit_version_major(void); +int ccdjit_version_minor(void); +int ccdjit_version_patch(void); +const char *ccdjit_version_string(void); +int ccdjit_api_abi_version(void); +int ccdjit_binary_format_version(void); +const char *ccdjit_git_commit(void); +int ccdjit_sandbox_capabilities_query(ccdjit_sandbox_capabilities *out); + +/* Free the context and all context-owned diagnostics/options/lists. */ +void ccdjit_context_free(ccdjit_context *ctx); + +/* Add a preprocessor include search path, like -I. */ +int ccdjit_context_add_include_path(ccdjit_context *ctx, const char *path); + +/* Restrict filesystem includes to this root when include roots are used. */ +int ccdjit_context_add_include_root(ccdjit_context *ctx, const char *path); + +/* Add a preprocessor definition, like -DNAME or -DNAME=value. */ +int ccdjit_context_add_define(ccdjit_context *ctx, const char *define); + +/* Grant generated code an explicit external symbol capability. */ +int ccdjit_context_register_symbol(ccdjit_context *ctx, const char *name, + void *addr); + +/* Add an explicit shared library path for external symbol lookup. */ +int ccdjit_context_add_library(ccdjit_context *ctx, const char *path); + +/* Install a fallback external symbol resolver. */ +void ccdjit_context_set_symbol_resolver(ccdjit_context *ctx, + ccdjit_symbol_resolver resolver, void *userdata); + +/* Update sandbox mode, syscall policy, filesystem policy, and symbol policy. */ +int ccdjit_context_set_sandbox_options(ccdjit_context *ctx, int mode, + int syscall_policy, int filesystem_policy, int allow_implicit_symbols); + +/* Update all sandbox resource limits in one call. */ +int ccdjit_context_set_sandbox_limits(ccdjit_context *ctx, + unsigned int timeout_ms, unsigned int cpu_time_ms, + size_t address_space_bytes, size_t stack_bytes, size_t file_size_bytes, + size_t output_limit_bytes); + +/* Update preprocessor resource limits. Passing zero keeps the default. */ +int ccdjit_context_set_preprocessor_limits(ccdjit_context *ctx, + size_t output_limit_bytes, unsigned int macro_depth, + unsigned int include_depth); + +/* Select the compiler driver used by system include and builtin macro probes. + */ +int ccdjit_context_set_preprocessor_compiler(ccdjit_context *ctx, + const char *compiler); + +/* Update compiler-probe timeout/output limits. Passing zero keeps defaults. */ +int ccdjit_context_set_preprocessor_probe_limits(ccdjit_context *ctx, + unsigned int timeout_ms, size_t output_limit_bytes); + +/* Free this thread's cached compiler probe results and system include paths. */ +void ccdjit_preprocessor_free_probe_cache(void); + +/* Enable or disable executable memory for future compile/load/call paths. */ +int ccdjit_context_set_executable_memory(ccdjit_context *ctx, int allow); + +/* Enable or disable optional debug/source mapping metadata. */ +int ccdjit_context_set_debug_info(ccdjit_context *ctx, int enable); + +/* + * Add a Landlock filesystem root for sandboxed execution. + * + * writable is only honored when sandbox_filesystem is + * CCDJIT_SANDBOX_FS_WRITABLE_ROOTS. On systems without Landlock, requesting a + * root-based filesystem policy fails while entering the sandbox. + */ +int ccdjit_context_add_sandbox_filesystem_root(ccdjit_context *ctx, + const char *path, int writable); + +/* + * Return the last error for this context. Passing NULL returns the + * thread-local diagnostic for context creation or NULL-context API failures. + * + * The result is a per-thread snapshot taken under the internal API lock, so it + * may be read safely while another thread compiles on the same context. The + * snapshot stays valid until the same accessor is called again on this thread + * (or the thread exits); copy the fields if they must outlive that window. + */ +const ccdjit_diagnostic *ccdjit_context_last_error(ccdjit_context *ctx); + +/* + * Return captured sandbox stdout/stderr from the last sandboxed main call. + * Like ccdjit_context_last_error(), the result is a per-thread snapshot that + * stays valid until the same accessor is called again on this thread. + */ +const char *ccdjit_context_last_stdout(ccdjit_context *ctx); +const char *ccdjit_context_last_stderr(ccdjit_context *ctx); + +/* + * Owned execution result snapshot for bindings and concurrent hosts. + * + * Result objects keep copies of the call status, integer result, diagnostic, + * captured stdout, and captured stderr. They are not invalidated by later + * calls on the same context. + */ +void ccdjit_execution_result_free(ccdjit_execution_result *result); +int ccdjit_execution_result_status(const ccdjit_execution_result *result); +int ccdjit_execution_result_has_value(const ccdjit_execution_result *result); +int ccdjit_execution_result_value(const ccdjit_execution_result *result); +const ccdjit_diagnostic *ccdjit_execution_result_diagnostic( + const ccdjit_execution_result *result); +const char *ccdjit_execution_result_stdout( + const ccdjit_execution_result *result); +const char *ccdjit_execution_result_stderr( + const ccdjit_execution_result *result); +int ccdjit_execution_result_signal(const ccdjit_execution_result *result); +int ccdjit_execution_result_has_fault_address( + const ccdjit_execution_result *result); +uintptr_t ccdjit_execution_result_fault_address( + const ccdjit_execution_result *result); + +/* Compile a source file into a live JIT module. */ +int ccdjit_compile_file(ccdjit_context *ctx, const char *path, + ccdjit_module **out); + +/* Compile a source string into a live JIT module. */ +int ccdjit_compile_string(ccdjit_context *ctx, const char *source, + const char *filename, ccdjit_module **out); + +/* + * Compile a source file into a live JIT module without requiring main(). + * Use ccdjit_module_symbol() to find and call exported config/plugin symbols. + */ +int ccdjit_compile_file_module(ccdjit_context *ctx, const char *path, + ccdjit_module **out); + +/* + * Compile a source string into a live JIT module without requiring main(). + * Use ccdjit_module_symbol() to find and call exported config/plugin symbols. + */ +int ccdjit_compile_string_module(ccdjit_context *ctx, const char *source, + const char *filename, ccdjit_module **out); + +/* Convenience wrapper: compile a source string, call main, free the module. */ +int ccdjit_eval_string(ccdjit_context *ctx, const char *source, + const char *filename, int argc, char **argv, int *result_out); + +/* + * Find a function or object symbol in a module. + * + * Calling the returned function pointer runs in the host process even when the + * context has sandbox_execution enabled. Use ccdjit_module_call_main() for + * sandboxed execution. + */ +void *ccdjit_module_symbol(ccdjit_module *module, const char *name); + +/* + * Inspect a module symbol without forcing the caller to cast blindly. + * + * JIT functions expose return type, parameter count, variadic flag, and + * per-parameter metadata through ccdjit_module_function_parameter_type(). + * Object symbols expose their object type and size. Loaded CCDJITB2 binaries + * expose function/object kind and size but not full C signatures. + */ +int ccdjit_module_symbol_info(ccdjit_module *module, const char *name, + ccdjit_symbol_info *out); + +int ccdjit_module_function_parameter_type(ccdjit_module *module, + const char *name, size_t index, ccdjit_type_info *out); + +/* + * Return a callable function pointer only when the JIT signature exactly + * matches the expected return and parameter types. + */ +void *ccdjit_module_function_symbol_checked(ccdjit_module *module, + const char *name, const ccdjit_type_info *return_type, + const ccdjit_type_info *parameter_types, size_t parameter_count, + int allow_variadic); + +/* Map a live JIT instruction address to lightweight module-owned debug info. */ +int ccdjit_module_debug_location(ccdjit_module *module, const void *address, + ccdjit_debug_location *out); + +/* Call module main(argc, argv). Honors CCDJIT_SANDBOX_PROCESS. */ +int ccdjit_module_call_main(ccdjit_module *module, int argc, char **argv, + int *result_out); +int ccdjit_module_call_main_result(ccdjit_module *module, int argc, char **argv, + ccdjit_execution_result **out); + +/* + * Call an exported JIT function with signature int name(int). + * + * Honors CCDJIT_SANDBOX_PROCESS like ccdjit_module_call_main(). Other + * signatures and binary modules are rejected with a diagnostic. + */ +int ccdjit_module_call_i32(ccdjit_module *module, const char *symbol, int arg, + int *result_out); +int ccdjit_module_call_i32_result(ccdjit_module *module, const char *symbol, + int arg, ccdjit_execution_result **out); + +/* + * Compile and publish a named function behind a stable handle. + * + * The initial source and every replacement must define the same function + * signature. Calls through the handle do not expose raw function pointers, so + * replacements can wait for active callers and then free old generated code. + */ +int ccdjit_function_handle_new(ccdjit_context *ctx, const char *source, + const char *filename, const char *symbol, ccdjit_function_handle **out); + +/* + * Compile replacement source and atomically publish it on success. + * + * On compile failure or signature mismatch the old implementation remains + * active and the context diagnostic describes the failure. + */ +int ccdjit_function_handle_replace(ccdjit_function_handle *handle, + const char *source, const char *filename); + +/* Call a handle whose published function has signature int name(int). */ +int ccdjit_function_handle_call_i32(ccdjit_function_handle *handle, int arg, + int *result_out); + +/* Free a function handle and the currently published implementation. */ +void ccdjit_function_handle_free(ccdjit_function_handle *handle); + +/* Emit textual assembly-like bytes for inspection. */ +int ccdjit_module_emit_assembly(ccdjit_module *module, FILE *out); + +/* Emit a CCDJITB2 binary image. */ +int ccdjit_module_emit_binary(ccdjit_module *module, FILE *out); + +/* Emit an ELF64 relocatable object. */ +int ccdjit_module_emit_object(ccdjit_module *module, FILE *out); + +/* + * Emit a linked host executable. + * + * This depends on the host compiler driver. It is intended for trusted build + * paths, not sandboxed execution. + */ +int ccdjit_module_emit_executable_file(ccdjit_module *module, const char *path, + const ccdjit_link_options *options); + +/* Emit a CCDJITB2 binary image directly to a path. */ +int ccdjit_module_emit_binary_file(ccdjit_module *module, const char *path); + +/* Load a CCDJITB2 binary image into executable memory. */ +int ccdjit_module_load_binary(ccdjit_context *ctx, const char *path, + ccdjit_module **out); + +/* Free generated code, loaded binary storage, AST, and module-owned source. */ +void ccdjit_module_free(ccdjit_module *module); + +#ifdef __cplusplus +} +#endif + +#endif |
