From 762338d067a7bd3e52085a950b9a7f6df2b6818a Mon Sep 17 00:00:00 2001 From: goldwaving <77494627+goldwaving@users.noreply.github.com> Date: Wed, 11 Sep 2024 09:11:18 -0230 Subject: [PATCH 1/7] Add some information about 'j' and 'p' types --- .../Interacting-with-code.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index a3f8287047e88..1d542a36e8179 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -630,14 +630,17 @@ added to the table. Otherwise by default the table has a fixed size. - ``'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, you can do ``addFunction(your_function, 'vi');``. See `test/interop/test_add_function_post.js `_ for an example. - + ``'j'`` is used with the __i53abi decorator to simplify handling 64-bit numbers in a 32-bit wasm build. + See library_wasmfs_opfs.js `_ + for an example. .. _interacting-with-code-access-memory: From b8e33d1cf11032e3e99677d5a358cc637cdcf87b Mon Sep 17 00:00:00 2001 From: goldwaving <77494627+goldwaving@users.noreply.github.com> Date: Wed, 11 Sep 2024 09:31:19 -0230 Subject: [PATCH 2/7] Added 'j' and 'p' information --- .../Interacting-with-code.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index 1d542a36e8179..52b6121e3e57d 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -638,9 +638,10 @@ added to the table. Otherwise by default the table has a fixed size. 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 `_ for an example. - ``'j'`` is used with the __i53abi decorator to simplify handling 64-bit numbers in a 32-bit wasm build. - See library_wasmfs_opfs.js `_ - for an example. + ``'j'`` is used with the __i53abi decorator to simplify passing 64-bit numbers in Javascript libraries. + See `library_wasmfs_opfs.js `_ + for an example. Using ``-sWASM_BIGINT`` when linking is an alternative method of handling 64-bit types. + See `settings reference `_. .. _interacting-with-code-access-memory: From 54781c10f4cfa85d21837c6d1b125e395ba52bf3 Mon Sep 17 00:00:00 2001 From: goldwaving <77494627+goldwaving@users.noreply.github.com> Date: Wed, 11 Sep 2024 09:40:56 -0230 Subject: [PATCH 3/7] Added some information about 'j' and 'p' types --- .../Interacting-with-code.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index 52b6121e3e57d..e59087565e23a 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -635,13 +635,15 @@ added to the table. Otherwise by default the table has a fixed size. - ``'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, you can do ``addFunction(your_function, 'vi');``. See - `test/interop/test_add_function_post.js `_ for an example. - ``'j'`` is used with the __i53abi decorator to simplify passing 64-bit numbers in Javascript libraries. - See `library_wasmfs_opfs.js `_ - for an example. Using ``-sWASM_BIGINT`` when linking is an alternative method of handling 64-bit types. - See `settings reference `_. +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 `_ for an example. + +``'j'`` must be used with the __i53abi decorator. It simplifies passing 64-bit numbers in Javascript libraries. It cannot be used with ``addFunction``. See `library_wasmfs_opfs.js `_ +for an example. + +Using ``-sWASM_BIGINT`` when linking is an alternative method of handling 64-bit types in libraries. +See `settings reference `_. .. _interacting-with-code-access-memory: From 0344b7d37115c89d76eb43d0aa5f1e98b7371364 Mon Sep 17 00:00:00 2001 From: goldwaving <77494627+goldwaving@users.noreply.github.com> Date: Wed, 11 Sep 2024 10:12:36 -0230 Subject: [PATCH 4/7] Added some information about 'j' and 'p' types and function signatures --- .../Interacting-with-code.rst | 39 ++++++++++++++----- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index e59087565e23a..d6585c88a157e 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -622,11 +622,20 @@ 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`` on the LLVM Wasm backend, you need to provide +an additional second argument, a Wasm function signature string, explained below. +See `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 @@ -636,15 +645,25 @@ added to the table. Otherwise by default the table has a fixed size. - ``'p'``: 32-bit or 64-bit pointer (MEMORY64) 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 `_ for an example. +anything, the signature is ``'vi'``. + +``'j'`` must be used with the ``__i53abi`` decorator. It simplifies passing 64-bit numbers in JavaScript libraries. 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 and returns +an integer error code: -``'j'`` must be used with the __i53abi decorator. It simplifies passing 64-bit numbers in Javascript libraries. It cannot be used with ``addFunction``. See `library_wasmfs_opfs.js `_ -for an example. +.. code-block:: c + + extern "C" int _set_file_size(int handle, uint64_t size); -Using ``-sWASM_BIGINT`` when linking is an alternative method of handling 64-bit types in libraries. +.. code-block:: javascript + + _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 `_. + .. _interacting-with-code-access-memory: Access memory from JavaScript From ce4c3058b87f2cd4d70c03d2de311f5351565592 Mon Sep 17 00:00:00 2001 From: goldwaving <77494627+goldwaving@users.noreply.github.com> Date: Wed, 11 Sep 2024 17:51:11 -0230 Subject: [PATCH 5/7] Expanded and corrected 'j' type information --- .../connecting_cpp_and_javascript/Interacting-with-code.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index d6585c88a157e..96b036ffefad2 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -622,7 +622,7 @@ 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. -When using ``addFunction`` on the LLVM Wasm backend, you need to provide +When using ``addFunction`` with 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 `_ for an example. @@ -647,8 +647,7 @@ parameter types. For example, if you add a function that takes an integer and does not return anything, the signature is ``'vi'``. -``'j'`` must be used with the ``__i53abi`` decorator. It simplifies passing 64-bit numbers in JavaScript libraries. 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 and returns -an integer error code: +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 From ac5f7aef939346ca8fdef532c3b2961703349f92 Mon Sep 17 00:00:00 2001 From: goldwaving <77494627+goldwaving@users.noreply.github.com> Date: Wed, 11 Sep 2024 21:40:49 -0230 Subject: [PATCH 6/7] Formatting changes and typo fix --- .../Interacting-with-code.rst | 35 ++++++++++++------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index 96b036ffefad2..d603bb962d588 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -613,18 +613,18 @@ 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. -When using ``addFunction`` with 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 `_ for an example. +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 `_ for an example. .. _interacting-with-code-function-signatures: @@ -632,10 +632,10 @@ See `test/interop/test_add_function_post.js `_. +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 `_. .. _interacting-with-code-access-memory: From 1a5be9dcea024775d69e827f47570ed93df24b71 Mon Sep 17 00:00:00 2001 From: goldwaving <77494627+goldwaving@users.noreply.github.com> Date: Tue, 8 Oct 2024 08:53:03 -0230 Subject: [PATCH 7/7] Minor punctuation fix --- .../connecting_cpp_and_javascript/Interacting-with-code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index d603bb962d588..a94b04918f4a9 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -648,7 +648,7 @@ 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 +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