From c495c920c0f0c763c783300e434b1b7ed1972d2d Mon Sep 17 00:00:00 2001 From: Anselme Gazard Date: Fri, 13 Dec 2024 13:31:14 +0100 Subject: [PATCH] Update documentation with new annotations ej.wasm.Wasm* --- .../managedc/communication.rst | 56 +++++++++---------- .../managedc/compilation.rst | 2 +- .../managedc/getting_started.rst | 30 +++++----- .../managedc/troubleshooting.rst | 8 +-- 4 files changed, 48 insertions(+), 48 deletions(-) diff --git a/ApplicationDeveloperGuide/managedc/communication.rst b/ApplicationDeveloperGuide/managedc/communication.rst index df9fff8ff..bd334b1bd 100644 --- a/ApplicationDeveloperGuide/managedc/communication.rst +++ b/ApplicationDeveloperGuide/managedc/communication.rst @@ -28,7 +28,7 @@ Link between Managed C function declaration and Java static methods can be done * ``class``: * Java `fully qualified name `__ of the class containing the Java static method (e.g: ``com.mycompany.MyApp``). - * An empty string (``""``) or ``"env"``. In that case, Java static method is searched in the current annotated ``@ManagedCModule`` Java class. + * An empty string (``""``) or ``"env"``. In that case, Java static method is searched in the current annotated ``@WasmModule`` Java class. * ``method``: Java static method name. @@ -90,7 +90,7 @@ Here is an example showing how to write Java and C source code when C macro para .. note:: - Java annotation ``@ManagedCModule("my_app.wasm")`` should be put some where, in this class or in another class. + Java annotation ``@WasmModule("my_app.wasm")`` should be put some where, in this class or in another class. Here is an example showing how to write Java and C source code when the C macro parameter ``class`` is an empty string: @@ -100,7 +100,7 @@ Here is an example showing how to write Java and C source code when the C macro package com.mycompany; - @ManagedCModule("my_app.wasm") + @WasmModule("my_app.wasm") public class MyApp { public static void delay(int ms) { @@ -137,14 +137,14 @@ Calling Managed C from Java The Core Engine allows to expose C functions to Java. C functions has to be declared as global function (intern C function using ``static`` C keyword will not be exposed). -On Java side, use ``@ManagedCModule`` annotation with Managed C compiled file path passed as parameter on the Java class. This +On Java side, use ``@WasmModule`` annotation with Managed C compiled file path passed as parameter on the Java class. This declaration will link a Java class to Managed C module. File path put as annotation parameter has to follow `Java resources naming convention `__ . .. note:: Managed C compiled files are seen as resources and has to be available in the Java classpath. -Use ``@ManagedCFunction`` annotation to link a Java method to a Managed C module function. The Java method has to be declared as `static native` and only use +Use ``@WasmFunction`` annotation to link a Java method to a Managed C module function. The Java method has to be declared as `static native` and only use ``int``, ``long``, ``float`` or ``double`` Java base type as method parameters or return types. The annotated Java native method signature must match the Managed C function signature. @@ -164,10 +164,10 @@ Here is an example: package com.mycompany; - import com.microej.managedc.ManagedCFunction; - import com.microej.managedc.ManagedCModule; + import ej.wasm.WasmFunction; + import ej.wasm.WasmModule; - @ManagedCModule("my_app.wasm") + @WasmModule("my_app.wasm") public class MyApp { public static void main(String[] args) { @@ -177,7 +177,7 @@ Here is an example: System.out.println(a + " + " + b + " = "+ add(a, b)); } - @ManagedCFunction + @WasmFunction public static native int add(int a, int b); } @@ -195,13 +195,13 @@ You should see the following output when launching the Java application: .. note:: You can give the Java method a different name than the C function. - In that case, you must provide the name of the corresponding C function as a parameter in the ``@ManagedCFunction`` annotation. + In that case, you must provide the name of the corresponding C function as a parameter in the ``@WasmFunction`` annotation. This is especially useful if you want to write a Java method in camel case while mapping it to a C function written in snake case. .. code-block:: java :emphasize-lines: 11,12 - @ManagedCModule("my_app.wasm") + @WasmModule("my_app.wasm") public class Main { public static void main(String[] args) { @@ -211,7 +211,7 @@ You should see the following output when launching the Java application: System.out.println(a + " + " + b + " = "+ myManagedCAdd(a, b)); } - @ManagedCFunction("add") + @WasmFunction("add") public static native int myManagedCAdd(int a, int b); } @@ -230,29 +230,29 @@ Manipulate Managed C Memory from Java The Core Engine allows to expose Managed C memory to Java. A Managed C module contains at most one memory. This Managed C module memory is automatically generated by the C compiler according to C source code and C compiler options. On Java side, Managed C module memory can be seen by -using ``@ManagedCMemory`` annotation on a Java static byte array field declaration (mapping automatically +using ``@WasmMemory`` annotation on a Java static byte array field declaration (mapping automatically done by the :ref:`soar`). -Managed C module memory is zero-initialiazed (once) when the :ref:`soar_clinit` of the Java class annotated with ``@ManagedCMemory`` is executed. +Managed C module memory is zero-initialiazed (once) when the :ref:`soar_clinit` of the Java class annotated with ``@WasmMemory`` is executed. .. note:: - A SOAR error will occurred if ``@ManagedCMemory`` is not strictly followed by a Java static byte array declaration (see :ref:`managedc.troubleshooting`). + A SOAR error will occurred if ``@WasmMemory`` is not strictly followed by a Java static byte array declaration (see :ref:`managedc.troubleshooting`). Here is a Java example: .. code:: java - package com.microej.managedc; - - import com.microej.managedc.ManagedCFunction; - import com.microej.managedc.ManagedCMemory; + package com.mycompany; + + import ej.wasm.WasmFunction; + import ej.wasm.WasmMemory; - @ManagedCModule("my_app.wasm") - public class ManagedCUtil { + @WasmModule("my_app.wasm") + public class MyApp { ... - @ManagedCMemory + @WasmMemory private static byte[] Memory; ... @@ -282,11 +282,11 @@ Here is a full C/Java example manipulating Managed C module memory in Java: package com.mycompany; - import com.microej.managedc.ManagedCFunction; - import com.microej.managedc.ManagedCMemory; - import com.microej.managedc.ManagedCModule; + import ej.wasm.WasmFunction; + import ej.wasm.WasmMemory; + import ej.wasm.WasmModule; - @ManagedCModule("my_app.wasm") + @WasmModule("my_app.wasm") public class MyApp { public static void main(String[] args) { @@ -294,13 +294,13 @@ Here is a full C/Java example manipulating Managed C module memory in Java: app_main(); } - @ManagedCMemory + @WasmMemory private static byte[] Memory; /** * Managed C entry point */ - @ManagedCFunction + @WasmFunction public static native void app_main(); /** diff --git a/ApplicationDeveloperGuide/managedc/compilation.rst b/ApplicationDeveloperGuide/managedc/compilation.rst index e62c602dc..c1d2e4ef6 100644 --- a/ApplicationDeveloperGuide/managedc/compilation.rst +++ b/ApplicationDeveloperGuide/managedc/compilation.rst @@ -41,7 +41,7 @@ In the terminal, navigate to the ``src/main/c`` directory and execute the follow If your module is composed of multiple C files, append all object files to the command line. The generated file ``my_app.wasm`` is the result of the link of all the content of the object file(s) (functions, globals, constants) in a single WebAssembly module. -This linked WebAssembly module can now be mapped to a :ref:`@ManagedCModule `. +This linked WebAssembly module can now be mapped to a :ref:`@WasmModule `. .. _managedc.link.command_line_options: diff --git a/ApplicationDeveloperGuide/managedc/getting_started.rst b/ApplicationDeveloperGuide/managedc/getting_started.rst index b9ce8ced6..8838c2dfe 100644 --- a/ApplicationDeveloperGuide/managedc/getting_started.rst +++ b/ApplicationDeveloperGuide/managedc/getting_started.rst @@ -34,11 +34,11 @@ To use Managed C in your Application, follow these steps: #. **Add the Annotations for Accessing Managed C in Java:** - Create a file named ``ManagedCModule.java`` in the directory ``src/main/java/com/microej/managedc`` with the following content: + Create a file named ``WasmModule.java`` in the directory ``src/main/java/ej/wasm`` with the following content: .. code-block:: java - package com.microej.managedc; + package ej.wasm; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; @@ -47,52 +47,52 @@ To use Managed C in your Application, follow these steps: @Retention(RetentionPolicy.CLASS) @Target(ElementType.TYPE) - public @interface ManagedCModule { + public @interface WasmModule { String value(); } - Create a file named ``ManagedCFunction.java`` in the directory ``src/main/java/com/microej/managedc`` with the following content: + Create a file named ``WasmFunction.java`` in the directory ``src/main/java/ej/wasm`` with the following content: .. code-block:: java - package com.microej.managedc; + package ej.wasm; import java.lang.annotation.ElementType; import java.lang.annotation.Target; @Target(ElementType.METHOD) - public @interface ManagedCFunction { + public @interface WasmFunction { String value() default ""; } #. **Configure your Java class to call a Managed C Function:** - Add the ``ManagedCModule`` annotation to the ``Main`` class with the Wasm module name: + Add the ``WasmModule`` annotation to the ``Main`` class with the Wasm module name: .. code-block:: java :emphasize-lines: 1,3 - import com.microej.managedc.* + import ej.wasm.*; - @ManagedCModule("factorial.wasm") + @WasmModule("factorial.wasm") public class Main { ... } - Define a native Java method with the ``ManagedCFunction`` annotation in your main application class: + Define a native Java method with the ``WasmFunction`` annotation in your main application class: .. code-block:: java :emphasize-lines: 8,9 - import com.microej.managedc.* + import ej.wasm.*; - @ManagedCModule("factorial.wasm") + @WasmModule("factorial.wasm") public class Main { ... - @ManagedCFunction + @WasmFunction public static native int factorial(int n); } @@ -101,14 +101,14 @@ To use Managed C in your Application, follow these steps: .. code-block:: java :emphasize-lines: 5 - @ManagedCModule("factorial.wasm") + @WasmModule("factorial.wasm") public class Main { public static void main(String[] args) { System.out.println("factorial(10) = " + factorial(10)); } - @ManagedCFunction + @WasmFunction public static native int factorial(int n); } diff --git a/ApplicationDeveloperGuide/managedc/troubleshooting.rst b/ApplicationDeveloperGuide/managedc/troubleshooting.rst index f2b5b1a26..d69300406 100644 --- a/ApplicationDeveloperGuide/managedc/troubleshooting.rst +++ b/ApplicationDeveloperGuide/managedc/troubleshooting.rst @@ -7,7 +7,7 @@ Troubleshooting SOAR-L ERROR "Unknown module ..." ----------------------------------------------------------------- -When using the ``@ManagedCModule`` annotation on a Java class, ensure there's a corresponding WebAssembly file in the classpath. +When using the ``@WasmModule`` annotation on a Java class, ensure there's a corresponding WebAssembly file in the classpath. An error in SOAR-L might occur if the WebAssembly file is missing. @@ -17,7 +17,7 @@ Failure to do so may result in the following error: soar2-r/do: [soar2-r] 1 : SOAR-L ERROR : - [soar2-r] [M403] - Unknown module 'my_module.wasm' (module is referenced by the annotation '@ManagedCModule' on the type 'com.mycompany.MyWebAssemblyModule'). + [soar2-r] [M403] - Unknown module 'my_module.wasm' (module is referenced by the annotation '@WasmModule' on the type 'com.mycompany.MyWebAssemblyModule'). [soar2-r] ----------------------------------------------------------------- @@ -53,7 +53,7 @@ Failure to do so may result in the following error: SOAR-L ERROR "Cannot find an exported function '...'" ----------------------------------------------------------------- -When using the ``@ManagedCFunction`` annotation on a Java method, ensure there's a corresponding WebAssembly function with the right signature in the associated WebAssembly module. +When using the ``@WasmFunction`` annotation on a Java method, ensure there's a corresponding WebAssembly function with the right signature in the associated WebAssembly module. An error in SOAR-L might occur if no function matching the annotated Java method signature is found. Failure to do so may result in the following error: @@ -68,7 +68,7 @@ Failure to do so may result in the following error: SOAR-L ERROR "'...' is not a byte array" ----------------------------------------------------------------- -When using the ``@ManagedCMemory`` annotation on a Java static field, ensure that corresponding type is a Java byte array (`byte[]`). +When using the ``@WasmMemory`` annotation on a Java static field, ensure that corresponding type is a Java byte array (`byte[]`). Failure to do so may result in the following error: