Tips Regarding 64-bit WASM Porting Pitfalls for JS

[sgbeal]

What follows are random tips for folks who are interested in using Emscripten's -sMEMORY64=1 flag, based on recent work to get SQLite's JS pieces working with that. This post is primarily about friction encountered when porting JS code to work in both 32- and 64-bit builds. None of what follows is a criticism of how Emscripten handles 64-bit builds - it's doing completely the right things. Unfortunately, though, some of those right things (baked into the corresponding language standards) are easy to trip over.

Part One: BigInt !== Number

First off, 64-bit builds necessarily change the data type of pointers from Number to BigInt. While that may sound pretty innocuous, it leads to discrepancies like:

Number(0); // ===0
BigInt(0); // !==0 (it's ===0n). This pains me as someone who habitually prefers === and !== over == and !=.
Number(null); // ===0
BigInt(null); // throws

Sigh. More surprising to me was:

const ptr = myCFunction();
const otherPtr = ptr + 8; // is not legal when ptr is-a BigInt!

That's relevant here because JS code using C libraries via WASM commonly has to do pointer arithmetic. Much of the above-linked work was ironing out that one difference by converting all pointer arithmetic into function calls:

// this is refactored from real code to remove API-specific pieces, so it may not compile as-is:
const __ptrSize = 4; // see notes below
const asPtrType = (4===__ptrSize) ? (v)=>Number(v || 0) : (v)=>BigInt(v || 0);
// ^^ The ||0 part is explained at:
// https://sqlite.org/wasm/doc/trunk/api-wasm.md#wasm-ptr
const NullPtr = asPtrType(0);
const ptrAdd(...args){
  let rc = NullPtr;
  for(const v of args) rc += asPtrType(v);
  return rc;
};

...

const ptr = myCFunction();
const otherPtr = ptrAdd(ptr, 8);

Regarding __ptrSize: that value is most readily available by calling any WASM function which returns a pointer. In my case that looked like:

  /** Figure out if this is a 32- or 64-bit WASM build. */
  switch( typeof SABC.exports.sqlite3_libversion() ){
    case 'number':
      SABC.wasmPtrIR = 'i32';
      SABC.wasmPtrSizeof = 4;
      break;
    case 'bigint':
      SABC.wasmPtrIR = 'i64';
      SABC.wasmPtrSizeof = 8;
      break;
    default:
      throw new Error("Cannot determine whether this is a 32- or 64-bit build");
  }

Part Two: BigInt != Number

Most of the effort in aforementioned port to 64-bit builds was caused by the previous point. A secondary problem is that some functions do not like BigInt arguments. The WASM heap is a byte array, and we copy memory out of it by taking slices of that array:

const chunk = theHeap.slice( ptrStart, ptrAdd(ptrStart, 12)/*see above*/ );

That won't work if ptrStart is a BigInt. We instead need:

const chunk = theHeap.slice( Number(ptrStart), Number(ptrStart) + 12) );

(Which is ironic, given that BigInt is there to provide access to a full 64 bits and the byte array APIs will never let us make use of more than Number's 53 integer bits, so Number would, in practice, suffice as a pointer type in 64-bit builds.)

That's easy to account for but is tedious and it's easy to forget to do, leading to code which "just works" in 32-bit builds but fails miserably in 64-bit.

More insidious and surprising, however, is that some APIs change which type they expect in 64-bit builds. For example, WebAssembly.Table.get() wants a Number in 32-bit builds (and when -sMEMORY64=2) but a BigInt when using -sMEMORY64=1, and will throw if given the other type. One workaround for that is:

const f = theTable.get(asPtrType(n)).

Noting that the purely-JS APIs, e.g. the TypedArrays used for the WASM heap, do not change their signatures. The WebAssembly namespace is a special case.

Pics or it didn't happen:

// 64-bit via the dev console:
> S.wasm.exports.__indirect_function_table.get(1)
VM1381:1 Uncaught TypeError: Cannot convert 1 to a BigInt
    at <anonymous>:1:42

> S.wasm.exports.__indirect_function_table.get(1n)
ƒ $func211() { [native code] }

// 32-bit:
> S.wasm.exports.__indirect_function_table.get(1)
ƒ $func211() { [native code] }

> S.wasm.exports.__indirect_function_table.get(1n)
VM1411:1 Uncaught TypeError: Cannot convert a BigInt value to a number
    at <anonymous>:1:42

Part 3: That might be all

There may be other porting holes which my feet have randomly avoided so far, but this post covers the biggest (IMO) pitfalls.

Hopefully this post has been of some use.

[sgbeal]

For completeness's sake, the following docs describe the JS APIs which were added to the SQLite project to help support 64-bit mode: https://sqlite.org/wasm/doc/trunk/api-wasm.md#wasm-ptr

[sbc100]

Thanks @sgbeal.

I sounds like you (sqlite) went with an approach the doesn't try to hide the "pointers can be BigInt" from the end user code. As you probably know emscripten instead tried to keep the "pointers are numbers" fiction even on 64-bit, although (as you probably also know) there are places where this abstraction is leaky (e.g. EM_JS function that take to return pointer value) and users may still need to modify their code.

I have long considered a second mode that does try to hide the bigint values and instead lets bigints flow through all the JS APIs. There could be some efficiency advantages, but also more useability pitfalls.

[sgbeal]

Also:

I sounds like you (sqlite) went with an approach the doesn't try to hide the "pointers can be BigInt" from the end user code.

i did consider adding a NativePointer type which would proxy Number of BigInt, but that seemed (A) like overkill, (B) an unnecessary performance hit, and (C) too easy to bypass (e.g. by calling exports.someMethod directly instead of via wrappers). Also, we want to interop with arbitrary other libs in any given app, and trickery like that feels doomed to backfire. My current take is that "transparency" is better achieved by proving explicit ways to gloss over the differences rather than trying to somehow hide that difference (and likely failing to do so, resulting in yet another leaky abstraction).

[sbc100]

i'm not sure what Emscripten could do to hide that distinction from me, as Emscripten has no influence over the TypedArray and DataView APIs (which don't like BigInt arguments). (Please don't customize the core JS types to hide that discrepancy! That way lies madness!)

In emscripten all pointers are converted to i53 number values when the go into JS and then automatically converted to bigint when they flow into wasm.

As long as emscripten known which arguments and return values correspond to pointers (or intptr_t) then the JS can simply assume everything that points are numbers. At least that is the theory.

If this all works as indented then all or your pointer-indexing into TypedArray and DataView will just work with any modification to handle bigint.

[sbc100]

What this means is that user JS code should never be exposed to bigint (except for real int64_t values of course, but those require the same handle on wasm32 and wasm64 since they are always bigint regardless)

[sgbeal]

What this means is that user JS code should never be exposed to bigint (except for real int64_t values of course, but those require the same handle on wasm32 and wasm64 since they are always bigint regardless)

That would be the ideal (from my end-user standpoint, anyway), but that's presumably the WASM group's decision to make, rather than Emscripten's?

JS can't possibly make use of the full range of 53-bit pointers, making BigInt way overkill for it. Certainly the designers had a good reason for opting for BigInt, though. i freely admin that it's technically correct, but the discrepancy is annoying for the end developers.

[sbc100]

What this means is that user JS code should never be exposed to bigint (except for real int64_t values of course, but those require the same handle on wasm32 and wasm64 since they are always bigint regardless)

That would be the ideal (from my end-user standpoint, anyway), but that's presumably the WASM group's decision to make, rather than Emscripten's?

JS can't possibly make use of the full range of 53-bit pointers, making BigInt way overkill for it. Certainly the designers had a good reason for opting for BigInt, though. i freely admin that it's technically correct, but the discrepancy is annoying for the end developers.

I've not been thinking about this as something that would need to be pushed upstream in Wasm.

Today we can do this strictly as a layer on top of Wasm. We use various hacks to detect when function signatures contains pointers and we generated thunks for calling in/out of Wasm when we detect a pointer is part of the signature.

See this automatically generated list of JS functions, for example: https://github.com/emscripten-core/emscripten/blob/main/src/lib/libsigs.js.

One of the purposes of this file is that it allows it to generated thunks for any JS function that has a pointer p in its signature.

For the other direction its not so elegant. See

emscripten/tools/emscripten.py

Lines 1039 to 1139 in 1294dd5

	def create_pointer_conversion_wrappers(metadata):
	# TODO(sbc): Move this into somewhere less static. Maybe it can become
	# part of library.js file, even though this metadata relates specifically
	# to native (non-JS) functions.
	#
	# The signature format here is similar to the one used for JS libraries
	# but with the following as the only valid char:
	# '_' - non-pointer argument (pass through unchanged)
	# 'p' - pointer/int53 argument (convert to/from BigInt)
	# 'P' - same as above but allow `undefined` too (requires extra check)
	mapping = {
	'sbrk': 'pP',
	'_emscripten_stack_alloc': 'pp',
	'emscripten_builtin_malloc': 'pp',
	'emscripten_builtin_calloc': 'ppp',
	'wasmfs_create_node_backend': 'pp',
	'malloc': 'pp',
	'realloc': 'ppp',
	'calloc': 'ppp',
	'webidl_malloc': 'pp',
	'memalign': 'ppp',
	'memcmp': '_ppp',
	'memcpy': 'pppp',
	'__getTypeName': 'pp',
	'setThrew': '_p',
	'free': '_p',
	'webidl_free': '_p',
	'_emscripten_stack_restore': '_p',
	'fflush': '_p',
	'emscripten_stack_get_end': 'p',
	'emscripten_stack_get_base': 'p',
	'pthread_self': 'p',
	'emscripten_stack_get_current': 'p',
	'__errno_location': 'p',
	'emscripten_builtin_memalign': 'ppp',
	'emscripten_builtin_free': 'vp',
	'main': '__PP',
	'__main_argc_argv': '__PP',
	'emscripten_stack_set_limits': '_pp',
	'__set_stack_limits': '_pp',
	'__set_thread_state': '_p___',
	'__cxa_can_catch': '_ppp',
	'__cxa_increment_exception_refcount': '_p',
	'__cxa_decrement_exception_refcount': '_p',
	'__cxa_get_exception_ptr': 'pp',
	'_wasmfs_write_file': '_ppp',
	'_wasmfs_mknod': '_p__',
	'_wasmfs_symlink': '_pp',
	'_wasmfs_chmod': '_p_',
	'_wasmfs_lchmod': '_p_',
	'_wasmfs_get_cwd': 'p_',
	'_wasmfs_identify': '_p',
	'_wasmfs_read_file': '_ppp',
	'_wasmfs_node_record_dirent': '_pp_',
	'__dl_seterr': '_pp',
	'_emscripten_run_js_on_main_thread': '__p_p_',
	'_emscripten_thread_exit': '_p',
	'_emscripten_thread_init': '_p_____',
	'_emscripten_thread_free_data': '_p',
	'_emscripten_dlsync_self_async': '_p',
	'_emscripten_proxy_dlsync_async': '_pp',
	'_emscripten_wasm_worker_initialize': '_p_',
	'_wasmfs_rename': '_pp',
	'_wasmfs_readlink': '_pp',
	'_wasmfs_truncate': '_p_',
	'_wasmfs_mmap': 'pp____',
	'_wasmfs_munmap': '_pp',
	'_wasmfs_msync': '_pp_',
	'_wasmfs_read': '__pp',
	'_wasmfs_pread': '__pp_',
	'_wasmfs_utime': '_p__',
	'_wasmfs_rmdir': '_p',
	'_wasmfs_unlink': '_p',
	'_wasmfs_mkdir': '_p_',
	'_wasmfs_open': '_p__',
	'_wasmfs_mount': '_pp',
	'_wasmfs_chdir': '_p',
	'asyncify_start_rewind': '_p',
	'asyncify_start_unwind': '_p',
	'__get_exception_message': '_ppp',
	'stbi_image_free': 'vp',
	'stbi_load': 'ppppp_',
	'stbi_load_from_memory': 'pp_ppp_',
	'strerror': 'p_',
	'emscripten_proxy_finish': '_p',
	'emscripten_proxy_execute_queue': '_p',
	'_emval_coro_resume': '_pp',
	'_emval_coro_reject': '_pp',
	'emscripten_main_runtime_thread_id': 'p',
	'_emscripten_set_offscreencanvas_size_on_thread': '_pp__',
	'fileno': '_p',
	'_emscripten_run_callback_on_thread': '_pp_pp',
	'_emscripten_find_dylib': 'ppppp',
	}
	for function in settings.SIGNATURE_CONVERSIONS:
	sym, sig = function.split(':')
	mapping[sym] = sig
	for f in ASAN_C_HELPERS:
	mapping[f] = '_pp'