Merge pull request #1155 from MicroEJ/feature/M0081MEJA-2367_managedc…

…-friviere-review Feature/m0081 meja 2367 managedc friviere review
MicroEJ · Dec 24, 2024 · 85bad87 · 85bad87
2 parents dd3e7d2 + 24b4f5d
commit 85bad87
Show file tree

Hide file tree

Showing 17 changed files with 81 additions and 57 deletions.
diff --git a/ApplicationDeveloperGuide/images/binary_code_verifier.png b/ApplicationDeveloperGuide/images/binary_code_verifier.png
diff --git a/ApplicationDeveloperGuide/images/build-flow.png b/ApplicationDeveloperGuide/images/build-flow.png
diff --git a/ApplicationDeveloperGuide/images/build-flow.pptx b/ApplicationDeveloperGuide/images/build-flow.pptx
diff --git a/ApplicationDeveloperGuide/images/runtime.png b/ApplicationDeveloperGuide/images/runtime.png
diff --git a/...erGuide/managedc/images/managed-code.pptx → ...icationDeveloperGuide/images/runtime.pptx b/...erGuide/managedc/images/managed-code.pptx → ...icationDeveloperGuide/images/runtime.pptx
diff --git a/ApplicationDeveloperGuide/images/soar.png b/ApplicationDeveloperGuide/images/soar.png
diff --git a/ApplicationDeveloperGuide/index.rst b/ApplicationDeveloperGuide/index.rst
@@ -19,6 +19,7 @@ Application Developer Guide
    limitations
    github
    modulesRepositories
+   managedc/index
    libraries
    tools
 

diff --git a/ApplicationDeveloperGuide/libraries.rst b/ApplicationDeveloperGuide/libraries.rst
@@ -46,7 +46,6 @@ To consult its libraries APIs documentation, please visit `<https://developer.mi
    javaTime
    eventQueue
    js/index
-   managedc/index
 
 ..
    | Copyright 2008-2024, MicroEJ Corp. Content in this space is free 

diff --git a/ApplicationDeveloperGuide/managedc/images/managed-code.png b/ApplicationDeveloperGuide/managedc/images/managed-code.png
diff --git a/ApplicationDeveloperGuide/managedc/index.rst b/ApplicationDeveloperGuide/managedc/index.rst
@@ -1,24 +1,21 @@
-.. _managedc:
+.. _c_language:
 
 ============
  Managed C
 ============
 
-MicroEJ provides the capability to develop parts of an application in C, known as Managed C. Essentially, a MicroEJ Application boots in Java and then run a mix of Java and Managed C code, etc.
+MicroEJ provides the capability to develop parts of an application in C, known as Managed C. Essentially, a MicroEJ Application boots in Java and then run a mix of Java and Managed C code.
 
-.. figure:: images/managed-code.png
-   :alt: MicroEJ Managed C Overview
+.. figure:: ../images/runtime.png
    :scale: 75%
    :align: center
 
-   MicroEJ Managed C Overview
-
-|
+   MicroEJ Runtime Overview
 
 .. note::
-   This feature requires Architecture version ``8.2.0`` or higher, and is currently not supported in simulation.
+   This feature requires Architecture version ``8.3.0`` or higher, and is currently not supported in simulation.
 
-Managed C code is enabled through `WebAssembly 1.0 <https://www.w3.org/TR/wasm-core-1/>`_, with :ref:`certain limitations <managedc.limitations>`. 
+Managed C code is enabled through the support of `WebAssembly 1.0 <https://www.w3.org/TR/wasm-core-1/>`_, with :ref:`certain limitations <managedc.limitations>`. 
 
 You can start exploring this functionality by following the instructions provided in the :ref:`Getting Started <managedc.getting_started>` page.
 

diff --git a/ApplicationDeveloperGuide/pptx/binary_code_verifier.pptx b/ApplicationDeveloperGuide/pptx/binary_code_verifier.pptx
diff --git a/ApplicationDeveloperGuide/pptx/soar.pptx b/ApplicationDeveloperGuide/pptx/soar.pptx
diff --git a/ApplicationDeveloperGuide/runtime.rst b/ApplicationDeveloperGuide/runtime.rst
@@ -1,12 +1,11 @@
+.. _microej_runtime:
+
 MicroEJ Runtime
 ===============
 
-.. _mjvm_javalanguage:
-
-Language
---------
+MicroEJ allows to run code written in :ref:`Java <java_language>` as primary language and in :ref:`C <c_language>`. It also supports code extensions written in :ref:`JavaScript <javascript>`.
 
-MicroEJ allows to develop Applications in the `Java® Language Specification version 7 <https://docs.oracle.com/javase/specs/jls/se7/jls7.pdf>`_ with :ref:`some limitations <java_limitations>`, and supports code extensions written in :ref:`JavaScript <javascript>`, and in :ref:`C <managedc>`.
+Such code is oftenly called `Managed Code`_ as it is executed by a runtime, the :ref:`Core Engine <core_engine>` (also called `MEJ32`).
 
 .. figure:: images/runtime.png
    :alt: MicroEJ Runtime Overview
@@ -15,18 +14,73 @@ MicroEJ allows to develop Applications in the `Java® Language Specification ver
 
    MicroEJ Runtime Overview 
 
-Basically, Java source code is compiled by the Java compiler [1]_ into the binary format specified in the JVM specification [2]_. 
-This binary code is linked by a tool named :ref:`SOAR <soar>` before execution: ``.class`` files and some other application-related files (see :ref:`Classpath <chapter.microej.classpath>` chapter) are linked to produce the final binary file that the :ref:`Core Engine <core_engine>` will execute.
+Build Flow
+----------
+
+Basically, the source code is first compiled by a compiler to produce an architecture independent `binary-code <https://en.wikipedia.org/wiki/Binary_code>`_.
+
+- The Java source code is compiled by a Java compiler [1]_ into Java bytecode, the binary format specified in the `Java Virtual Machine specification <https://docs.oracle.com/javase/specs/jvms/se7/html/>`_. 
+- The C source code is compiled by a C compiler [2]_ into `WebAssembly <https://webassembly.org/>`_, also called `Wasm`.
+
+Finally, the binary code is loaded and linked by a tool named the :ref:`SOAR <soar>`. 
+The SOAR loads both Java bytecode (``.class`` files), WebAssembly (``.wasm`` files), and other application-related :ref:`files and resources <chapter.microej.classpath>`.
+It links these components to produce the final binary file executed by the :ref:`Core Engine <core_engine>`.
+
+
+.. figure:: images/build-flow.png
+   :alt: MicroEJ Build Flow
+   :scale: 75%
+   :align: center
 
-.. note:: When opened in the SDK 5, make sure that the Compiler Compliance Level of your project is set to 1.7 to ensure the bytecode produced by the Java compiler is compatible with MicroEJ. The Compliance Level can be changed from the menu: :guilabel:`Window` > :guilabel:`Preferences` > :guilabel:`Java` > :guilabel:`Compiler`.
+   MicroEJ Build Flow
 
 .. [1]
-   The JDT compiler from the Eclipse IDE.
+   MICROEJ SDK internally embeds the `Eclipse JDT compiler <https://eclipse.dev/jdt/core/>`_.
 
 .. [2]
-   Tim Lindholm & Frank Yellin, The Java™ Virtual Machine Specification, Second Edition, 1999
+   MICROEJ SDK is configured by default to connect the C compiler packaged with the `WASI SDK <https://github.com/WebAssembly/wasi-sdk/>`_.
+
+.. _Managed Code: https://developer.microej.com/managed-code/
+
+.. _java_language:
+
+Java Language
+-------------
+
+MicroEJ's primary language is the `Java language <https://en.wikipedia.org/wiki/Java_(programming_language)>`_.
+
+MicroEJ supports the `Java® Language Specification version 7 <https://docs.oracle.com/javase/specs/jls/se7/jls7.pdf>`_ with :ref:`some limitations <java_limitations>`.
+
+.. _java_limitations:
+
+Limitations
+~~~~~~~~~~~
 
+**Primitive Types**
 
+Getting a Class instance of a primitive type is not supported:
+
+- ``boolean.class``,
+- ``byte.class``,
+- ``char.class``,
+- ``short.class``,
+- ``int.class``,
+- ``long.class``,
+- ``float.class``,
+- ``double.class``.
+
+On Architecture ``8.x``, you will get the following dedicated error message:
+
+.. code-block::
+
+    SOAR-L ERROR :
+    [M79] - Unsupported access to the Class instance of a primitive type (found 'boolean.class' in method 'com.mycompany.MyClass.myMethod()void')
+
+On Architecture ``7.x`` you will get the following default error message:
+
+.. code-block::
+
+    No such field TYPE at com/mycompany/MyClass.myMethod()V.
 
 .. _runtime_core_libraries:
 
@@ -182,39 +236,6 @@ second one blocks while the queue is empty.
 
 The Application is responsible of the execution of such hook.
 
-.. _java_limitations:
-
-Limitations
------------
-
-Primitive Types
-~~~~~~~~~~~~~~~
-
-Getting a Class instance of a primitive type is not supported:
-
-- ``boolean.class``,
-- ``byte.class``,
-- ``char.class``,
-- ``short.class``,
-- ``int.class``,
-- ``long.class``,
-- ``float.class``,
-- ``double.class``.
-
-On Architecture ``8.x``, you will get the following dedicated error message:
-
-.. code-block::
-
-    SOAR-L ERROR :
-    [M79] - Unsupported access to the Class instance of a primitive type (found 'boolean.class' in method 'com.mycompany.MyClass.myMethod()void')
-
-On Architecture ``7.x`` you will get the following default error message:
-
-.. code-block::
-
-    No such field TYPE at com/mycompany/MyClass.myMethod()V.
-
-
 .. _architecture_characteristics:
 
 Architecture Characteristics

diff --git a/ApplicationDeveloperGuide/soar.rst b/ApplicationDeveloperGuide/soar.rst
@@ -6,6 +6,12 @@ SOAR
 This chapter describes SOAR capabilities and optimizations from the Application developer's point of view.
 To get more details on its internal structure, please refer to :ref:`soar_build_phases` section.
 
+.. figure:: images/soar.png
+   :alt: SOAR Build Flow
+   :align: center
+   :scale: 80%
+
+   SOAR Build Flow
 
 Java Symbols Encoding
 ---------------------

diff --git a/Trainings/tutorialCreateFirmwareFromScratch.rst b/Trainings/tutorialCreateFirmwareFromScratch.rst
@@ -365,7 +365,7 @@ This section describes how to create and configure a MicroEJ Platform
 compatible with the FreeRTOS BSP and GCC toolchain.
 
 * A MicroEJ Architecture is a software package that includes the
-  :ref:`MicroEJ Runtime<mjvm_javalanguage>` port to a specific target
+  :ref:`MicroEJ Runtime <microej_runtime>` port to a specific target
   Instruction Set Architecture (ISA) and C compiler. It contains a set
   of libraries, tools and C header files. The MicroEJ Architectures
   are provided by MicroEJ SDK.

diff --git a/glossary.rst b/glossary.rst
@@ -6,7 +6,7 @@ MicroEJ Glossary
 .. glossary::
 
    Add-On Library
-      An Add-On Library is a pure `Managed Code`_ (Java, Javascript, managed-C, etc.) library. It runs over one or more Foundation Libraries.
+      An Add-On Library is a pure `Managed Code`_ (Java, C, Javascript) library. It runs over one or more Foundation Libraries.
 
    Abstraction Layer
       An Abstraction Layer is the code (C, asm, etc.) that implements a Foundation Library's low-level APIs over a board support package (BSP) or a C library.
@@ -39,7 +39,7 @@ MicroEJ Glossary
             A Multi-Sandbox Executable is an Executable that implements the ability to be extended, by exposing a set of APIs and a memory space to link Sandboxed Applications. (formerly called a Multi-app Firmware) 
 
    Foundation Library
-      A Foundation Library is a library that provides core or hardware-dependent functionalities. A Foundation Library combines `Managed Code`_ (Java, Javascript, managed-C, etc. ) and low-level APIs (C, asm, etc.) implemented by one or more Abstraction Layers through a native interface (:ref:`SNI <sni_specification>`).
+      A Foundation Library is a library that provides core or hardware-dependent functionalities. A Foundation Library combines `Managed Code`_ (Java, C, Javascript) and low-level APIs (C, asm, etc.) implemented by one or more Abstraction Layers through a native interface (:ref:`SNI <sni_specification>`).
 
    MICROEJ SDK
       MICROEJ SDK is a comprehensive tools suite for developers to build VEE Ports for their devices, create Applications, build Executable, and run Virtual Devices.

diff --git a/overview/index.rst b/overview/index.rst
@@ -12,7 +12,7 @@ MicroEJ (pronounced “micro-EDGE”) is a software vendor of cost-driven soluti
 The MicroEJ solution is made up of two products:
 
 - MICROEJ VEE (Virtual Execution Environment) is an application container for resource-constrained embedded devices running on microcontrollers or microprocessors. 
-  It allows devices to run multiple and mixed managed code (Java, JavaScript, C).
+  It allows devices to run multiple and mixed managed code (Java, C, JavaScript).
 - MICROEJ SDK allows developers to develop applications in Managed Code and deploy them to resource-constrained devices, such as microcontrollers.
 
 .. _vee: