Skip to content

Commit

Permalink
Update documentation with new annotations ej.wasm.Wasm*
Browse files Browse the repository at this point in the history
  • Loading branch information
@agazardMicroeJ @frivieremicroej
agazardMicroeJ authored and frivieremicroej committed Dec 13, 2024
1 parent 8f75715 commit c495c92
Show file tree
Hide file tree
Showing 4 changed files with 48 additions and 48 deletions.
56 changes: 28 additions & 28 deletions ApplicationDeveloperGuide/managedc/communication.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Link between Managed C function declaration and Java static methods can be done
* ``class``:

* Java `fully qualified name <https://docs.oracle.com/javase/specs/jls/se11/html/jls-6.html#jls-6.7>`__ 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.

Expand Down Expand Up @@ -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:

Expand All @@ -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) {
Expand Down Expand Up @@ -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 <https://docs.oracle.com/javase/7/docs/technotes/guides/lang/resources.html#res_name_context>`__ .

.. 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.

Expand All @@ -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) {
Expand All @@ -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);
}
Expand All @@ -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) {
Expand All @@ -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);
}
Expand All @@ -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;
...
Expand Down Expand Up @@ -282,25 +282,25 @@ 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) {
// Call Managed C entry point
app_main();
}
@ManagedCMemory
@WasmMemory
private static byte[] Memory;
/**
* Managed C entry point
*/
@ManagedCFunction
@WasmFunction
public static native void app_main();
/**
Expand Down
2 changes: 1 addition & 1 deletion ApplicationDeveloperGuide/managedc/compilation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <managedc.communication.managedc_to_java>`.
This linked WebAssembly module can now be mapped to a :ref:`@WasmModule <managedc.communication.managedc_to_java>`.

.. _managedc.link.command_line_options:

Expand Down
30 changes: 15 additions & 15 deletions ApplicationDeveloperGuide/managedc/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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);
}
Expand All @@ -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);
}
Expand Down
8 changes: 4 additions & 4 deletions ApplicationDeveloperGuide/managedc/troubleshooting.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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]
-----------------------------------------------------------------
Expand Down Expand Up @@ -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:
Expand All @@ -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:

Expand Down

0 comments on commit c495c92

Please sign in to comment.