Home /Modules/os-level-support/native_loader.h

native_loader.h

os-level-support/loader/native_loader.h · 146 line(s) · c

#ifndef SLEELA_NATIVE_LOADER_H
#define SLEELA_NATIVE_LOADER_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define SL_NATIVE_ABI_VERSION 1u
#define SL_NATIVE_TYPED_ABI_VERSION 1u
#define SL_NATIVE_MAX_UNITS 9u

#if defined(_WIN32) && defined(SL_NATIVE_PLUGIN_BUILD)
#  define SL_NATIVE_EXPORT __declspec(dllexport)
#elif defined(__GNUC__) || defined(__clang__)
#  define SL_NATIVE_EXPORT __attribute__((visibility("default")))
#else
#  define SL_NATIVE_EXPORT
#endif

typedef int (*SLNativeEntry)(int argc, const char *const argv[]);
typedef uint32_t (*SLNativeAbiVersion)(void);
typedef uint32_t (*SLNativeTypedAbiVersion)(void);

/* Stable tagged scalar/string value contract. Scalar fields use fixed-width
 * integer types; F64 uses the platform's 8-byte C double. String pointers are
 * borrowed UTF-8 byte spans, never NUL-terminated by contract, and may contain
 * embedded NUL bytes. Composite VM objects and raw VM handles are deliberately
 * not representable in this first ABI version. */
typedef enum SLNativeValueTag {
    SL_NATIVE_VALUE_NULL = 0,
    SL_NATIVE_VALUE_BOOL = 1,
    SL_NATIVE_VALUE_I64 = 2,
    SL_NATIVE_VALUE_F64 = 3,
    SL_NATIVE_VALUE_UTF8 = 4
} SLNativeValueTag;

typedef struct SLNativeValue {
    uint32_t tag;
    uint32_t reserved;
    union {
        int32_t boolean;
        int64_t i64;
        double f64;
        struct {
            const uint8_t *data;
            uint32_t length;
        } utf8;
    } as;
} SLNativeValue;

/* Optional typed method export. Return 0 for success and nonzero for a
 * plugin-defined failure. The result is initialized to NULL by the loader.
 * Any returned UTF-8 bytes must remain valid until the next call to this
 * module or module close; the host copies them before making another call. */
typedef enum SLNativeCallStatus {
    SL_NATIVE_CALL_OK = 0,
    /* The module does not implement this method; the VM may use bytecode fallback. */
    SL_NATIVE_CALL_NOT_HANDLED = 1,
    /* A handled method failed; this must never trigger interpreter fallback. */
    SL_NATIVE_CALL_ERROR = 2,
    /* Appended typed failures preserve the Java String boundary's error class. */
    SL_NATIVE_CALL_INDEX_OUT_OF_BOUNDS = 3,
    SL_NATIVE_CALL_MALFORMED_TEXT = 4,
    SL_NATIVE_CALL_INVALID_ARGUMENT = 5
} SLNativeCallStatus;

typedef int (*SLNativeTypedCall)(const char *method,
                                 uint32_t argc,
                                 const SLNativeValue *argv,
                                 SLNativeValue *out_result);

/* Optional native-to-host callback bridge. A plugin copies this immutable
 * table during sl_native_bind_host(); it must not retain any SLValue or VM
 * pointer. invoke() accepts only the scalar/UTF-8 ABI values above. */
#define SL_NATIVE_HOST_CALLBACK_ABI_VERSION 1u
typedef int (*SLNativeHostInvoke)(void *context, const char *function,
                                  uint32_t argc, const SLNativeValue *argv,
                                  SLNativeValue *out_result);
typedef struct SLNativeHostAPI {
    uint32_t abi_version;
    uint32_t struct_size;
    void *context;
    SLNativeHostInvoke invoke;
} SLNativeHostAPI;
typedef int (*SLNativeBindHost)(const SLNativeHostAPI *host_api);

/* Keep the public module layout stable: the optional typed symbol is resolved
 * from handle at call time rather than stored in this struct. */
typedef struct SLNativeModule {
    void *handle;
    SLNativeEntry run;
} SLNativeModule;

typedef enum SLNativeStatus {
    SL_NATIVE_OK = 0,
    SL_NATIVE_INVALID_ARGUMENT = 1,
    SL_NATIVE_LOAD_ERROR = 2,
    SL_NATIVE_ABI_MISMATCH = 3,
    SL_NATIVE_ENTRY_NOT_FOUND = 4,
    SL_NATIVE_AUTHORIZATION_DENIED = 5,
    SL_NATIVE_TABLE_FULL = 6,
    SL_NATIVE_STALE_HANDLE = 7,
    SL_NATIVE_TYPED_ENTRY_NOT_FOUND = 8,
    SL_NATIVE_PLUGIN_ERROR = 9,
    SL_NATIVE_METHOD_NOT_HANDLED = 10,
    SL_NATIVE_HOST_CALLBACK_NOT_FOUND = 11,
    SL_NATIVE_REENTRANT_CALL = 12,
    /* Appended statuses; existing native-loader status numbers remain stable. */
    SL_NATIVE_JAVA_INDEX_OUT_OF_BOUNDS = 13,
    SL_NATIVE_JAVA_MALFORMED_TEXT = 14,
    SL_NATIVE_JAVA_INVALID_ARGUMENT = 15
} SLNativeStatus;

/* Plugins export these C-linkage functions; initialize module as {0}. */
SL_NATIVE_EXPORT uint32_t sl_native_abi_version(void);
/* Required when the optional sl_native_call typed entry is exported. */
SL_NATIVE_EXPORT uint32_t sl_native_typed_abi_version(void);
SL_NATIVE_EXPORT int sl_native_run(int argc, const char *const argv[]);
/* Optional typed entry: int sl_native_call(const char*, uint32_t,
 * const SLNativeValue*, SLNativeValue*). */
SL_NATIVE_EXPORT int sl_native_call(const char *method, uint32_t argc,
                                    const SLNativeValue *argv,
                                    SLNativeValue *out_result);
/* Optional: int sl_native_bind_host(const SLNativeHostAPI *host_api). */
SL_NATIVE_EXPORT int sl_native_bind_host(const SLNativeHostAPI *host_api);

/* Opens a trusted shared library (DLL, .dylib, or .so); loading executes native code. */
SLNativeStatus sl_native_open(SLNativeModule *module, const char *path);
SLNativeStatus sl_native_run_module(SLNativeModule *module, int argc,
                                    const char *const argv[], int *out_result);
SLNativeStatus sl_native_call_module(SLNativeModule *module, const char *method,
                                     uint32_t argc, const SLNativeValue *argv,
                                     SLNativeValue *out_result);
SLNativeStatus sl_native_bind_host_api(SLNativeModule *module,
                                       const SLNativeHostAPI *host_api);
SLNativeStatus sl_native_close(SLNativeModule *module);
const char *sl_native_status_string(SLNativeStatus status);
const char *sl_native_loader_error(void);

#ifdef __cplusplus
}
#endif
#endif