[docs] Added info about 'j' and 'p' types and function signatures (#2…

…2562)

This information needs to be reviewed by someone with deeper knowledge
about function signatures, __i53abi, and WASM_BIGINT.

site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst

@@ -613,30 +613,63 @@ Calling JavaScript functions as function pointers from C
 ========================================================
 
 You can use ``addFunction`` to return an integer value that represents a
-function pointer. Passing that integer to C code then lets it call that value as
-a function pointer, and the JavaScript function you sent to ``addFunction`` will
-be called.
+function pointer. Passing that integer to C code then lets it call that value
+as a function pointer, and the JavaScript function you sent to ``addFunction``
+will be called.
 
 See `test_add_function in test/test_core.py`_ for an example.
 
 You should build with ``-sALLOW_TABLE_GROWTH`` to allow new functions to be
 added to the table. Otherwise by default the table has a fixed size.
 
-.. note:: When using ``addFunction`` on LLVM Wasm backend, you need to provide
-   an additional second argument, a Wasm function signature string. Each
-   character within a signature string represents a type. The first character
-   represents the return type of a function, and remaining characters are for
-   parameter types.
+When using ``addFunction`` with a JavaScript function, you need to provide
+an additional second argument, a Wasm function signature string, explained
+below. See `test/interop/test_add_function_post.js <https://github.com/emscripten-core/emscripten/blob/main/test/interop/test_add_function_post.js>`_ for an example.
+
+
+.. _interacting-with-code-function-signatures:
+
+Function Signatures
+===================
+
+The LLVM Wasm backend requires a Wasm function signature string when using
+``addFunction`` and in JavaScript libraries. Each character within a signature
+string represents a type. The first character represents the return type of a
+function, and remaining characters are for parameter types.
 
    - ``'v'``: void type
    - ``'i'``: 32-bit integer type
-   - ``'j'``: 64-bit integer type (currently does not exist in JavaScript)
+   - ``'j'``: 64-bit integer type (see note below)
    - ``'f'``: 32-bit float type
    - ``'d'``: 64-bit float type
+   - ``'p'``: 32-bit or 64-bit pointer (MEMORY64)
+
+For example, if you add a function that takes an integer and does not return
+anything, the signature is ``'vi'``.
+
+When ``'j'`` is used there are several ways in which the parameter value will
+be passed to JavaScript. By default, the value will either be passed as a
+single BigInt or a pair of JavaScript numbers (double) depending on whether
+the ``WASM_BIGINT`` settings is enabled. In addition, if you only require 53
+bits of precision you can add the ``__i53abi`` decorator, which will ignore
+the upper bits and the value will be received as a single JavaScript number
+(double).  It cannot be used with ``addFunction``.  Here is an example of a
+library function that sets the size of a file using a 64-bit value passed as
+a 53 bit (double) and returns an integer error code:
+
+.. code-block:: c
+
+  extern "C" int _set_file_size(int handle, uint64_t size);
+
+.. code-block:: javascript
 
-   For example, if you add a function that takes an integer and does not return
-   anything, you can do ``addFunction(your_function, 'vi');``. See
-   `test/interop/test_add_function_post.js <https://github.com/emscripten-core/emscripten/blob/main/test/interop/test_add_function_post.js>`_ for an example.
+  _set_file_size__i53abi: true,  // Handle 64-bit 
+  _set_file_size__sig: 'iij',    // Function signature
+  _set_file_size: function(handle, size) { ... return error; }
+    
+Using ``-sWASM_BIGINT`` when linking is an alternative method of handling
+64-bit types in libraries.  ```Number()``` may be needed on the JavaScript
+side to convert it to a useable value.  See `settings reference <https://emscripten.org/docs/tools_reference/settings_reference.html?highlight=environment#wasm-bigint>`_.
 
 
 .. _interacting-with-code-access-memory: