ffi: add experimental fast FFI call API

Add fast API trampolines for AArch64 and x86_64.

IsJitMemorySupported() maps an RW page, writes a ret instruction
(0xD65F03C0 AArch64 / 0xC3 x86_64), and mprotects it to RX. A
successful RX transition is treated as the support signal. The page is
deliberately not executed: this check may run during normal operation
(when an FFI function is first created), and executing freshly written
code from a capability probe could SIGSEGV/SIGKILL the process on
systems that block executable memory. The real trampoline emitter
performs the same mprotect at creation time and falls back to libffi
when it is rejected.

The result is computed once via std::call_once and cached for the
lifetime of the process, so concurrent callers never observe a
provisional value.

Wired into CreateFastFFIMetadata() for early nullptr bail-out when
JIT memory is unavailable.

Windows stub returns false (no trampolines yet on this branch).

IsFastCallEligible() validates at parse time whether a signature can
use the fast-call path, covering:

- Return and argument type eligibility (numeric, pointer; no structs)
- Argument count cap (8, matching V8 fast-call limit)
- Per-ABI register pressure limits that mirror the trampoline emitters
  (AArch64 and x86_64 SysV). Platforms without an emitter, including
  Win64, are reported ineligible.
- Buffer and float args cannot coexist, and buffer args additionally
  consume an extra GP register slot on both supported ABIs.

The arg/arg-name lengths are checked before the per-arg loop so a
malformed signature cannot index out of bounds.

Returns nullptr from CreateFastFFIMetadata() for ineligible signatures,
falling back to libffi.

Co-authored-by: Bryan English <bryan@bryanenglish.com>
Signed-off-by: Paolo Insogna <paolo@cowtech.it>
Signed-off-by: Bryan English <bryan@bryanenglish.com>
Assisted-By: OpenAI:GPT-5.5 <openai/gpt-5.5>

Author: ShogunPanda

benchmark/ffi/add-f64.js benchmark/ffi/add-64.jsbenchmark/ffi/add-f64.js renamed to benchmark/ffi/add-64.js

@@ -21,7 +21,7 @@ const add = functions.add_f64;
 function main({ n }) {
   bench.start();
   for (let i = 0; i < n; ++i)
-    add(1.5, 2.5);
+    add(20.5, 21.5);
   bench.end(n);
 
   lib.close();

benchmark/ffi/add-f32.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_f32: { result: 'f32', parameters: ['f32', 'f32'] },
+});
+
+const add = functions.add_f32;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(20.5, 21.5);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/add-i16.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_i16: { result: 'i16', parameters: ['i16', 'i16'] },
+});
+
+const add = functions.add_i16;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(20, 22);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/add-i64.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_i64: { result: 'i64', parameters: ['i64', 'i64'] },
+});
+
+const add = functions.add_i64;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(20n, 22n);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/add-i8.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_i8: { result: 'i8', parameters: ['i8', 'i8'] },
+});
+
+const add = functions.add_i8;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(20, 22);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/add-u16.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_u16: { result: 'u16', parameters: ['u16', 'u16'] },
+});
+
+const add = functions.add_u16;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(20, 22);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/add-u64.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_u64: { result: 'u64', parameters: ['u64', 'u64'] },
+});
+
+const add = functions.add_u64;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(20n, 22n);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/add-u8.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_u8: { result: 'u8', parameters: ['u8', 'u8'] },
+});
+
+const add = functions.add_u8;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(20, 22);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/buffer-first-byte-direct.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  first_byte: { result: 'u8', parameters: ['pointer'] },
+});
+
+const fn = functions.first_byte;
+const bytes = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
+const pointer = ffi.getRawPointer(bytes);
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    fn(pointer);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/buffer-first-byte.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  first_byte: { result: 'u8', parameters: ['buffer'] },
+});
+
+const fn = functions.first_byte;
+const bytes = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    fn(bytes);
+  bench.end(n);
+
+  lib.close();
+}