Dispatch table of NBL runtime functions. More...

#include <nbl.h>

Data Fields
void (	dlopen )(const char *filename, int mode)
	Open and map an x86_64 shared object into the current process. More...

int(*	dlclose )(void *handle)
	Unmap and close an x86_64 shared object previously opened by dlopen(). More...

int(*	dlinfo )(void handle, int request, void arg)
	Query information about an x86_64 shared object. More...

char (	dlerror )(void)
	Retrieve the most recent error message from the NBL runtime. More...

void (	dlsym )(void handle, const char name)
	Look up the address of a symbol (function or data) in an x86_64 shared object. More...

void (	dlsym_with_signature )(void handle, const char name, const char *nbl_signature)
	Look up an x86_64 function and return the address of a wrapper stub that adapts a LoongArch (la64) call site to the x86_64 callee. More...

bool(*	register_hostfunc )(const void entry, const char name, const char *nbl_signature)
	Register a host (LoongArch) function with NBL so that translated x86_64 code can call back into the host. More...

bool(*	register_hostdata )(const void address, const char name)
	Register a host data symbol for translated ELF relocation. More...

bool(*	register_hostfunc_with_callback )(const void entry, const char name, const char nbl_signature, const void c_entry, const char *c_signature)
	Register a host function together with a callback that derives the effective variadic-argument signature at call time. More...

bool(*	register_hostfunc_with_callback_arg )(const void entry, const char name, const char nbl_signature, const void c_entry, const char *c_signature, int callback_arg_index)
	Register a host variadic / va_list function whose runtime signature is derived from one specifically selected fixed argument, rather than from the fixed arguments immediately preceding the `V` / `A` tail marker. More...

bool(*	register_hostfunc_with_vaargs_policy )(const void entry, const char name, const char *nbl_signature, NblVaargsPolicy policy, char vaargs_type, bool include_terminator)
	Register a host function with an explicit variadic-argument policy. More...

bool(*	unregister_hostfunc )(const void entry, const char name)
	Unregister a host function previously registered with NBL. More...

void (	method_stub )(const char nbl_signature, const void entry)
	Build a wrapper stub for an x86_64 function whose address was obtained through dlsym(). More...

bool(*	is_tr_handle )(void *handle)
	Test whether a handle refers to an x86_64 shared object that is managed by the translator. More...

bool(*	is_tr_symbol )(const void *addr)
	Test whether an address lies inside the `.text` segment of an x86_64 ELF, or was produced by an R_X86_64_GLOB_DAT relocation for such an ELF. More...

bool(*	is_tr_signal )(const void *addr)
	Test whether an address lies inside the translator itself (for example, a translation-cache page or a translator runtime symbol). More...

bool(*	tr_signalhandler )(int sig, siginfo_t info, ucontext_t uc)
	Translator-side signal handler. More...

const void (	get_extension )(uint32_t extension_id)

Detailed Description

Dispatch table of NBL runtime functions.

Each field wraps an entry point provided by the underlying translator and forwards cross-architecture calls to it. Create one with nbl_load() and release it with nbl_unload().

Field Documentation

int(* Nbl::dlclose)(void *handle)

Unmap and close an x86_64 shared object previously opened by dlopen().

Parameters

handle Handle returned by a successful dlopen().

Returns: 0 on success, non-zero on failure.

char*(* Nbl::dlerror)(void)

Retrieve the most recent error message from the NBL runtime.

Returns: NUL-terminated, human-readable string describing the last failure that occurred in the calling thread, or NULL if no error is pending.

Note: Not thread-safe. When tr_mode is 1 the message may be stale or empty for the calling thread; when tr_mode is 2 this entry point is currently a stub.

int(* Nbl::dlinfo)(void *handle, int request, void *arg)

Query information about an x86_64 shared object.

Parameters

handle	Handle returned by dlopen().
request	Information selector; semantics mirror dlinfo() for native handles (e.g. RTLD_DI_LINKMAP).
arg	Output buffer whose meaning depends on `request`.

Returns: 0 on success, non-zero on failure.

Note: When tr_mode is 2 only link_map->l_name is guaranteed to be valid; other fields of the link_map may be uninitialised.

void*(* Nbl::dlopen)(const char *filename, int mode)

Open and map an x86_64 shared object into the current process.

Parameters

filename	Path of the x86_64 shared object to load. When NULL or empty, a handle to the main program is returned.
mode	Same flags as POSIX `dlopen` (e.g. RTLD_LAZY, RTLD_NOW, RTLD_GLOBAL, RTLD_LOCAL).

Returns: Opaque handle on success, or NULL on failure. Use dlerror() to retrieve diagnostic information on failure.

void*(* Nbl::dlsym)(void *handle, const char *name)

Look up the address of a symbol (function or data) in an x86_64 shared object.

The returned address lives inside the x86_64 address space managed by the translator. Do not call it directly from LoongArch code; obtain a callable wrapper via dlsym_with_signature() or method_stub() instead.

Parameters

handle	Handle returned by dlopen(), or one of the standard pseudo-handles RTLD_DEFAULT / RTLD_NEXT.
name	NUL-terminated symbol name.

Returns: Symbol address on success, or NULL if the symbol cannot be found.

void*(* Nbl::dlsym_with_signature)(void *handle, const char *name, const char *nbl_signature)

Look up an x86_64 function and return the address of a wrapper stub that adapts a LoongArch (la64) call site to the x86_64 callee.

The wrapper handles argument marshalling (la64 register/stack layout -> x86_64 register/stack layout) and return-value marshalling in the opposite direction.

Parameters

handle	Handle returned by dlopen().
name	NUL-terminated function name.
nbl_signature	NUL-terminated string describing the function's parameter list and return type. See NBL signature grammar.

Returns: Method-entry address of the wrapper stub, or NULL on failure.

Warning: nbl_signature must not be NULL.

const void*(* Nbl::get_extension)(uint32_t extension_id)

Query an optional NBL extension by its private identifier and ABI version.

Extension-specific declarations are intentionally kept out of this public header. Integrations must query extensions during initialization and cache the returned operation table before entering a signal handler.

bool(* Nbl::is_tr_handle)(void *handle)

Test whether a handle refers to an x86_64 shared object that is managed by the translator.

Parameters

handle Handle previously returned by dlopen() (or any of the other translator entry points that yield a handle).

Returns: true if handle is a translator-managed x86_64 handle, false otherwise (including for native la64 handles).

bool(* Nbl::is_tr_signal)(const void *addr)

Test whether an address lies inside the translator itself (for example, a translation-cache page or a translator runtime symbol).

Parameters

addr	Address to test.

Returns: true if addr is owned by the translator, false otherwise.

bool(* Nbl::is_tr_symbol)(const void *addr)

Test whether an address lies inside the .text segment of an x86_64 ELF, or was produced by an R_X86_64_GLOB_DAT relocation for such an ELF.

Parameters

addr	Address to test.

Returns: true if addr is an x86_64 translated-symbol address, false otherwise.

void*(* Nbl::method_stub)(const char *nbl_signature, const void *entry)

Build a wrapper stub for an x86_64 function whose address was obtained through dlsym().

Parameters

nbl_signature	NUL-terminated nbl signature of the function. See NBL signature grammar.
entry	Raw x86_64 function entry address, as returned by dlsym().

Returns: Method-entry address of the wrapper stub, or NULL on failure.

bool(* Nbl::register_hostdata)(const void *address, const char *name)

Register a host data symbol for translated ELF relocation.

The symbol is visible to the translator's host-symbol fallback but is not callable and does not carry an NBL ABI signature.

Parameters

address	Address of the host data object or variable storage.
name	NUL-terminated symbol name used by the translated ELF.

Returns: true on success, false on invalid arguments or registration failure.

bool(* Nbl::register_hostfunc)(const void *entry, const char *name, const char *nbl_signature)

Register a host (LoongArch) function with NBL so that translated x86_64 code can call back into the host.

Parameters

entry	Entry address of the host function to publish.
name	NUL-terminated host function name. Used as the lookup key from translated x86_64 code.
nbl_signature	NUL-terminated nbl signature of the host function. See NBL signature grammar.

Returns: true on success, false on failure.

bool(* Nbl::register_hostfunc_with_callback)(const void *entry, const char *name, const char *nbl_signature, const void *c_entry, const char *c_signature)

Register a host function together with a callback that derives the effective variadic-argument signature at call time.

The translator invokes c_entry to ask the host for the runtime nbl_signature of the variadic part, then uses the returned signature to marshal the variable arguments. This is the standard mechanism for exporting variadic host functions such as printf-style helpers.

Parameters

entry	Entry address of the host function.
name	NUL-terminated host function name.
nbl_signature	Static nbl signature covering the fixed parameter list; the variable-argument portion is supplied by `c_entry` at call time. See NBL signature grammar.
c_entry	Entry address of the host callback that returns the runtime signature of the variadic part.
c_signature	NUL-terminated nbl signature of `c_entry`.

Returns: true on success, false on failure.

Example:
  // int test(int fixed1, int fixed2, ...);
  // void get_test_args(void* ctx, char* out_sig);  // out_sig: runtime sig
  register_hostfunc_with_callback(
      test, "test", "iFiiV", get_test_args, "vFpp");

bool(* Nbl::register_hostfunc_with_callback_arg)(const void *entry, const char *name, const char *nbl_signature, const void *c_entry, const char *c_signature, int callback_arg_index)

Register a host variadic / va_list function whose runtime signature is derived from one specifically selected fixed argument, rather than from the fixed arguments immediately preceding the V / A tail marker.

The default register_hostfunc_with_callback() derives the variable-argument signature from the fixed arguments that sit right before the tail marker V (or A). Some host APIs – notably CPython's PyArg_ParseTupleAndKeywords and friends – keep the format string describing the variadic part earlier in the fixed argument list; this variant lets the caller point at that argument explicitly.

Parameters

entry	Entry address of the host function.
name	NUL-terminated host function name.
nbl_signature	Nbl signature whose tail is `V` (variadic) or `A` (va_list). See NBL signature grammar.
c_entry	Host callback that fills the output buffer with the runtime signature of the variable arguments.
c_signature	Nbl signature of `c_entry`.
callback_arg_index	Zero-based index into the fixed arguments that follow `F` and precede the tail marker, selecting which fixed argument is passed to `c_entry`. For "iFppppA", index 2 selects the third fixed argument.

Returns: true on success, false on failure.

Note: The callback signature is currently restricted to "vFpp": the selected fixed pointer argument followed by the output signature buffer.

Example: int PyArg_ParseTupleAndKeywords(PyObject*, PyObject*, const char*, char**, ...); register_hostfunc_with_callback_arg( PyArg_ParseTupleAndKeywords, "PyArg_ParseTupleAndKeywords", "iFppppV", get_format_sig, "vFpp", 2);

int PyArg_VaParseTupleAndKeywords(PyObject*, PyObject*, const char*, char**, va_list); register_hostfunc_with_callback_arg( PyArg_VaParseTupleAndKeywords, "PyArg_VaParseTupleAndKeywords", "iFppppA", get_format_sig, "vFpp", 2);

bool(* Nbl::register_hostfunc_with_vaargs_policy)(const void *entry, const char *name, const char *nbl_signature, NblVaargsPolicy policy, char vaargs_type, bool include_terminator)

Register a host function with an explicit variadic-argument policy.

Note: Unstable API. Currently used to model CPython's variadic call conventions.

Parameters

entry	Entry address of the host function.
name	NUL-terminated host function name.
nbl_signature	Nbl signature of the host function. See NBL signature grammar.
policy	How the variadic arguments are terminated (NBL_VAARGS_NONE or NBL_VAARGS_NULL_TERMINATED).
vaargs_type	Single-letter nbl type code describing the variable arguments (e.g. 'p' for pointer).
include_terminator	Whether the trailing terminator (e.g. the NULL sentinel for NBL_VAARGS_NULL_TERMINATED) is counted as a regular argument by the translator.

Returns: true on success, false on failure.

bool(* Nbl::tr_signalhandler)(int sig, siginfo_t *info, ucontext_t *uc)

Translator-side signal handler.

Invoked by the host when a signal is suspected to originate from translated x86_64 code. Returning true tells the host that the translator has fully handled the signal and no further action is required; returning false asks the host to fall back to its own signal handling.

Parameters

sig	Signal number (as in a POSIX sa_sigaction handler).
info	`siginfo_t` provided by the kernel.
uc	`ucontext_t` provided by the kernel.

Returns: true if the translator handled the signal, false otherwise.

bool(* Nbl::unregister_hostfunc)(const void *entry, const char *name)

Unregister a host function previously registered with NBL.

Parameters

entry	Entry address of the host function to unregister. Must match the value passed to the corresponding register_hostfunc*() call.
name	NUL-terminated host function name. Used only for diagnostics / debug output.

Returns: true on success, false on failure.

The documentation for this struct was generated from the following file:

nbl.h

Data Fields

Detailed Description

Field Documentation