aboutsummaryrefslogtreecommitdiff
path: root/ccdjit.h
diff options
context:
space:
mode:
authorDavid Moc <personal@cdatgoose.org>2026-11-19 02:15:38 +0100
committerDavid Moc <personal@cdatgoose.org>2026-11-19 02:15:38 +0100
commitb80f9cfb17d1a26dc39b0c9e14c7d7c3e5e15484 (patch)
treedc3205fdeb6f666d7d1fbe492115f3007afd27dc /ccdjit.h
parent74111495622a13104b4f6500f6dc8e9db6aec9bd (diff)
Used the new ccdjit.hHEADmain
Diffstat (limited to 'ccdjit.h')
-rw-r--r--ccdjit.h136
1 files changed, 125 insertions, 11 deletions
diff --git a/ccdjit.h b/ccdjit.h
index bf1e239..724511b 100644
--- a/ccdjit.h
+++ b/ccdjit.h
@@ -33,6 +33,26 @@
* Function pointers returned by ccdjit_module_symbol() are invalid after
* ccdjit_module_free().
*
+ * Function pointers:
+ * ccdjit_module_symbol() returns the raw JIT entry point. JIT code uses
+ * an internal convention for non-scalar signatures, so a host may only
+ * call that pointer directly when the function has an ABI-agnostic
+ * signature: a non-variadic integer/pointer signature with at most six
+ * parameters. Use ccdjit_module_symbol_info() and
+ * ccdjit_module_function_parameter_type() to inspect the signature,
+ * ccdjit_module_function_symbol_checked() to obtain a pointer that has
+ * been verified as host-callable, or expose a wrapper with an
+ * ABI-agnostic signature. Data symbols are plain host addresses and may
+ * be used directly.
+ *
+ * Calls made from JIT code through a function pointer are classified at
+ * runtime: a JIT target receives the internal convention and a host
+ * target receives SysV. This makes function-pointer parameters, globals,
+ * struct fields, and dlsym results callable without extra annotations.
+ * Passing a JIT-compiled callback to host code is only supported when its
+ * signature is ABI-agnostic; other callbacks are rejected rather than
+ * entered with the wrong convention.
+ *
* Runtime policy:
* Module calls, symbol lookup, and emission intentionally consult the
* current context options, sandbox settings, resource limits, registered
@@ -67,7 +87,7 @@ extern "C" {
#define CCDJIT_VERSION_MINOR 3
#define CCDJIT_VERSION_PATCH 1
#define CCDJIT_VERSION_STRING "1.3.1"
-#define CCDJIT_API_ABI_VERSION 1
+#define CCDJIT_API_ABI_VERSION 2
#define CCDJITB2_FORMAT_VERSION 2
#define CCDJITB2_FLAG_DEBUG_INFO 1u
/*
@@ -287,52 +307,99 @@ typedef enum {
CCDJIT_SYMBOL_OBJECT = 2,
} ccdjit_symbol_kind;
+/* Diagnostic codes returned in ccdjit_diagnostic.code. */
+
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_FLOAT = 4, /* float or _Float16 (see is_float16) */
+ CCDJIT_TYPE_DOUBLE = 5, /* double or long double (see is_long_double) */
+ CCDJIT_TYPE_LONG = 6, /* long or __int128 (see is_int128) */
CCDJIT_TYPE_SHORT = 7,
CCDJIT_TYPE_STRUCT = 8,
CCDJIT_TYPE_ENUM = 9,
CCDJIT_TYPE_UNION = 10,
- CCDJIT_TYPE_FLOAT128 = 11,
+ CCDJIT_TYPE_FLOAT128 = 11, /* __float128 */
} ccdjit_type_base;
typedef struct {
int has_type;
- int base;
- int pointer_level;
- int array_size;
+ int base; /* ccdjit_type_base */
+ int pointer_level; /* 0 for objects, 1 for T*, 2 for T**, ... */
+ int array_size; /* -1 for non-array, 0 for [], >0 for fixed size */
int is_unsigned;
int is_complex;
int is_atomic;
+
+ /*
+ * Extended identity flags. The base field names the storage class, so
+ * _Float16 shares TY_FLOAT, long double shares TY_DOUBLE, and
+ * __int128 shares TY_LONG. These flags distinguish them.
+ */
+ int is_long_double;
+ int is_float16;
+ int is_int128;
+
+ /* GNU vector_size type and its total size in bytes. */
+ int is_vector;
+ int vector_size;
+
+ /*
+ * Struct or union tag for aggregate types. Borrowed from the module
+ * and valid only while the module is alive. NULL for other types.
+ */
+ const char *struct_name;
} ccdjit_type_info;
typedef struct {
+ /* ccdjit_symbol_kind */
int kind;
+
+ /*
+ * Nonzero for live JIT functions. Loaded CCDJITB2 files carry kind
+ * and size but not full C signatures, so this is zero for them.
+ */
int has_signature;
+
+ /* Object type when kind is CCDJIT_SYMBOL_OBJECT. */
ccdjit_type_info type;
+
+ /* Function return type when has_signature is nonzero. */
ccdjit_type_info return_type;
+
+ /* Fixed parameter count and variadic flag for JIT functions. */
size_t parameter_count;
int is_variadic;
+
+ /* Object size in bytes, or function code size when available. */
size_t size;
} ccdjit_symbol_info;
typedef struct {
+ /* Process sandboxing is available on this platform. */
int process;
+
+ /* seccomp syscall filtering is available. */
int seccomp;
+
+ /* Landlock filesystem policies are available. */
int landlock;
} ccdjit_sandbox_capabilities;
typedef struct {
+ /* Source file name, or NULL when unavailable. Module-owned. */
const char *filename;
+
+ /* Enclosing function name, or NULL when unavailable. Module-owned. */
const char *function;
+
+ /* One-based source location, or zero when unavailable. */
int line;
int column;
+
+ /* Address range covered by the generated code. */
uintptr_t address;
size_t size;
} ccdjit_debug_location;
@@ -344,13 +411,22 @@ typedef struct {
*/
ccdjit_context *ccdjit_context_new(const ccdjit_options *options);
+/* Compiler version components and human-readable string. */
int ccdjit_version_major(void);
int ccdjit_version_minor(void);
int ccdjit_version_patch(void);
const char *ccdjit_version_string(void);
+
+/* Public API ABI version; must match the header the host compiled against. */
int ccdjit_api_abi_version(void);
+
+/* CCDJITB2 binary format version accepted by the loader. */
int ccdjit_binary_format_version(void);
+
+/* Build revision string, or an empty string when unknown. */
const char *ccdjit_git_commit(void);
+
+/* Report process, seccomp, and Landlock sandbox availability. */
int ccdjit_sandbox_capabilities_query(ccdjit_sandbox_capabilities *out);
/* Free the context and all context-owned diagnostics/options/lists. */
@@ -493,6 +569,13 @@ int ccdjit_eval_string(ccdjit_context *ctx, const char *source,
* 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.
+ *
+ * A function pointer follows the internal JIT ABI. The host may call it
+ * directly only for ABI-agnostic integer/pointer signatures (at most six
+ * parameters, non-variadic). Use ccdjit_module_function_symbol_checked() to
+ * enforce that contract, or expose an ABI-agnostic wrapper. Object addresses
+ * are ordinary host addresses. For a thread-local object, the returned
+ * address belongs to the calling thread.
*/
void *ccdjit_module_symbol(ccdjit_module *module, const char *name);
@@ -504,15 +587,33 @@ void *ccdjit_module_symbol(ccdjit_module *module, const char *name);
* Object symbols expose their object type and size. Loaded CCDJITB2 binaries
* expose function/object kind and size but not full C signatures.
*/
+/*
+ * Inspect a symbol without casting blindly.
+ *
+ * Live JIT functions report kind, full return type, fixed parameter count,
+ * and the variadic flag. Loaded CCDJITB2 files report kind and size only.
+ * Objects report their declared type and byte size. The struct_name pointer
+ * in a reported type is borrowed from the module.
+ */
int ccdjit_module_symbol_info(ccdjit_module *module, const char *name,
ccdjit_symbol_info *out);
+/*
+ * Return the type of parameter index (zero based) for a live JIT function.
+ * Loaded binaries carry no parameter metadata and fail with a diagnostic.
+ */
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.
+ * matches the expected return and parameter types and the signature is
+ * host-callable.
+ *
+ * Host-callable means ABI-agnostic: integer and pointer values only,
+ * non-variadic, and at most six fixed parameters. Functions with float,
+ * _Float16, long double, complex, __float128, aggregate, vector, or __int128
+ * values in their signature must be reached through a wrapper instead.
*/
void *ccdjit_module_function_symbol_checked(ccdjit_module *module,
const char *name, const ccdjit_type_info *return_type,
@@ -566,7 +667,13 @@ int ccdjit_function_handle_call_i32(ccdjit_function_handle *handle, int arg,
/* 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. */
+/*
+ * Emit textual assembly-like bytes for inspection.
+ *
+ * Standalone assembly/object/binary emission is rejected when generated code
+ * calls a compiler-internal runtime helper, because the artifact would not
+ * contain that helper. Live JIT modules have no such restriction.
+ */
int ccdjit_module_emit_assembly(ccdjit_module *module, FILE *out);
/* Emit a CCDJITB2 binary image. */
@@ -587,7 +694,14 @@ int ccdjit_module_emit_executable_file(ccdjit_module *module, const char *path,
/* 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. */
+/*
+ * Load a CCDJITB2 binary image into executable memory.
+ *
+ * The image is a CCDJIT runtime format, not ELF and not a standalone
+ * executable. Loaded symbols retain kind and size but not full C signatures
+ * or source locations. External symbols are resolved through the context as
+ * they are for live modules.
+ */
int ccdjit_module_load_binary(ccdjit_context *ctx, const char *path,
ccdjit_module **out);